Documentation

Installation

Installing Vibe-Guard globally makes it available across all your projects without per-project setup. The tool requires no Docker containers, complex dependencies, or configuration files to start scanning. Global installation enables seamless CI/CD integration and consistent command availability.

# Install Vibe-Guard globally

$ npm install -g vibe-guard

✓ Installation complete

Prerequisites

Node.js 16.0 or higher
npm, yarn, or pnpm package manager
Access to the target codebase

Alternative Installation Methods

YARN

yarn global add vibe-guard

PNPM

pnpm add -g vibe-guard

Verify Installation

# Check version

$ vibe-guard --version

vX.Y.Z

Update

npm update -g vibe-guard

Uninstall

npm uninstall -g vibe-guard

Common Issues

Command not found: ensure global npm bin is on PATH (npm bin -g)
Permission denied: use a Node version manager instead of sudo
Proxy/firewall: configure npm registry or use a different network

Basic Usage

Learn the fundamentals of security scanning with Vibe-Guard's command interface. This section covers how to interpret scan results, understand exit codes, and establish workflows for different development scenarios.

# Scan current directory

$ vibe-guard scan

✓ Scanning 47 files...

✓ Analysis complete (0.8s)

✓ Found 2 vulnerabilities

Common Commands

$ vibe-guard scan ./src

Scan specific directory

$ vibe-guard scan --severity high

Only show high and critical issues

$ vibe-guard scan --format json --output-file results.json

Generate JSON report and save to file

$ vibe-guard scan --parallel --max-files 10

Enable parallel processing with file limit

$ vibe-guard scan --exclude node_modules --include "*.ts"

Exclude node_modules, only scan TypeScript files

Understanding the Output

SQL_INJECTION (critical)

File: src/db/user.ts:42

Snippet: db.query("SELECT ...")

Fix: Use parameterized queries

Rule: Identifier and severity
Location: File path and line number
Snippet: Context around the finding
Remediation: Concrete fix guidance

Exit Codes

0

No issues or all below threshold

1

Issues at/above threshold found

>1

Reserved for internal errors

Typical Workflows

Local dev: vibe-guard scan --severity high before commit
CI check: vibe-guard scan --format json --output-file results.json gate merges
Audit: vibe-guard scan --format html --output-file report.html for sharing

CLI Options

Command-line flags customize scan behavior, output formats, and performance. Learn when and how to combine flags effectively to improve scan relevance, reduce noise, and optimize execution time.

Option	Description	Default
--format, -f	Output format (table, json, sarif, html)	table
--output-file, -o	Write output to file	stdout
--verbose, -v	Verbose output	false
--severity, -s	Minimum severity level (critical, high, medium, low)	all levels
--config, -c	Path to configuration file	auto-detected
--parallel	Enable parallel processing	false
--max-files	Maximum files to process concurrently	unlimited
--exclude	Directories or files to exclude	node_modules, .git
--include	Specific files or patterns to include	all files

When To Use Which Flag

--severity

Reduce noise locally; gate only high/critical in CI

--parallel --max-files

Large repos; tune to avoid I/O contention

--include/--exclude

Monorepos; focus scans or skip vendor dirs

Practical Combos

--format json --output-file results.json for CI artifacts
--severity high --parallel for fast red/green feedback
--exclude node_modules dist --include "src/**/*.ts" targeted scans

Security Rules

Security rules target specific vulnerability patterns found in real-world applications. Rules are categorized by severity to help teams prioritize fixes. Understanding why patterns are dangerous and how to fix them reduces security debt and prevents future vulnerabilities.

Critical Severity

• SQL Injection
• Exposed Secrets
• Hardcoded Credentials
• AI Data Leakage

High Severity

• XSS Detection
• Directory Traversal
• CSRF Protection
• Broken Access Control

View All 28 Rules →

Why it matters

Severity helps prioritize fixes that reduce real risk first.

Fix it

Prefer parameterized queries, output encoding, CSRF tokens, least privilege, validated inputs, and secret management.

Scanning Engine

The scanning engine uses pattern matching and AST analysis to balance speed with accuracy. This approach minimizes false positives while maintaining fast scan times on large codebases. Understanding the engine's methods helps you interpret results and tune scans effectively.

// How Vibe-Guard works internally

1. File discovery and filtering

2. Content parsing and AST generation

3. Rule application and pattern matching

4. Result aggregation and reporting

Supported File Types

JavaScript

.js, .jsx

TypeScript

.ts, .tsx

Python

.py

Go

.go

Java

.java

Ruby

.rb

Rust

.rs

Config Files

.json, .yaml, .env

Plus C++, C#, PHP, Swift, Dart, Scala, and more...

Detection Methods

Pattern matching for fast, broad coverage
AST hints to reduce common false positives
Context-aware exclusions (tests, mocks, fixtures)

Philosophy

Bias toward signal with actionable remediation
Keep scans fast; fail quickly on high risk
Make tuning easy per project via config

Output Formats

Choose the right output format for your workflow. Tables work well for local development, JSON for automation and CI/CD, SARIF for security platforms, and HTML for detailed reports. Each format serves different integration needs.

CLI Output

Human-readable output with color coding and severity indicators.

✓ No critical issues found
⚠️ 2 medium issues found
Security Score: 85/100

JSON Output

Machine-readable format for CI/CD integration and automation.

{
"issues": [...],
"summary": {...}
}

HTML Report

Detailed visual report with code snippets and remediation guidance.

<html>
  <body>
    Security Report
  </body>
</html>

How to Consume

jq

vibe-guard scan --format json | jq '.summary'

GitHub Summary

echo "## Security" >> $GITHUB_STEP_SUMMARY

HTML

Open report.html locally or publish to artifacts

Configuration

Configuration files ensure consistent scan behavior across team members and environments. They reduce command-line complexity and adapt to project needs like monorepos, legacy code exclusions, and team risk tolerance. Environment variables provide flexibility for CI/CD deployments.

vibe-guard.json

{

"outputFormat": "table",

"severity": "medium",

"exclude": ["node_modules", ".git"],

"include": [],

"verbose": false,

"rules": {

"sql-injection": { "enabled": true, "severity": "high" }

}

Also supported: .vibe-guard.json, vibe-guard.config.json. CLI flags override config.

Practical Configurations

Speed (local dev)

{
  "severity": "high",
  "exclude": ["node_modules", "dist"],
  "verbose": false
}

Strict CI

{
  "severity": "medium",
  "outputFormat": "json",
  "rules": { "xss-detection": { "enabled": true } }
}

Monorepo

{
"include": ["packages/*/src/**/*.ts"],
"exclude": ["**/fixtures/**", "**/mocks/**"]
}

Environment Variables

VIBE_GUARD_CONFIG_PATH

Path to configuration file

VIBE_GUARD_LOG_LEVEL

Logging level (debug, info, warn, error)

VIBE_GUARD_TIMEOUT

Scan timeout in milliseconds

Performance & Benchmarks

Performance optimization maintains developer productivity and enables practical CI/CD integration. Vibe-Guard prioritizes speed through parallel processing, intelligent file filtering, and optimized pattern matching. Understanding tuning options helps achieve optimal scan times while maintaining accuracy.

< 1s

Average Scan Time

1000+

Files Per Second

0 MB

Additional Memory

100%

CPU Utilization

💡 Performance Tip

Use the --parallel flag to utilize all CPU cores for faster scanning on large codebases.

Tuning Recipes

I/O bound: --parallel --max-files 8 to cap concurrency
CPU bound: --parallel --max-files 2x cores for throughput
Noise reduction: exclude generated/vendor dirs; include only source globs

Troubleshooting

Most problems stem from file system permissions, memory constraints, or overly broad scan patterns. This section provides systematic approaches to diagnosing issues, interpreting error messages, and optimizing scan parameters for reliable operation.

Scan is taking too long

Large codebases can take time to scan. Try these solutions:

Use --exclude to skip unnecessary directories
Enable parallel processing with --parallel
Scan specific directories instead of entire codebase

Too many false positives

Adjust sensitivity and create custom rules:

Increase minimum severity with --severity high
Create custom rule exclusions in configuration
Use --ignore-patterns for specific cases

Memory issues on large projects

Optimize memory usage:

Use --max-files to limit concurrent file processing
Enable streaming mode with --stream
Scan in smaller batches

False negatives

Lower threshold and re-run; broaden include patterns

Unstable timings

Pin --max-files to avoid I/O spikes

Too much output

Use --severity high and save full JSON to file

CI/CD Integration

CI/CD integration transforms security scanning from occasional audits into continuous protection. Successful integration requires balancing thoroughness with build performance and implementing appropriate gating strategies. This section covers platform-specific configurations and proven patterns.

# GitHub Actions Example

name: Security Scan

on: [push, pull_request]

jobs:

security:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- run: npm install -g vibe-guard

- run: vibe-guard scan ./src --severity high

Pipeline Integration Patterns

PR Gate Pattern

Fail fast on high/critical issues

vibe-guard scan --severity high
exit_code=$?
if [ $exit_code -eq 1 ]; then
echo "Security gate failed"
exit 1
fi

Audit Pattern

Collect all findings, never fail build

vibe-guard scan --format json \
--output-file security.json \
|| true
# Always upload artifacts

Automation Tips

--severity high

Use in CI to only fail on high/critical issues

--format json

Generate machine-readable output for parsing

--output-file results.json

Save results for later analysis or reporting

GitLab CI ✓ Tested

# .gitlab-ci.yml

scan:

image: node:20

script:

- npm i -g vibe-guard

- vibe-guard scan --format json --output-file results.json --severity high

artifacts:

paths: [results.json]

CircleCI (Untested)

# .circleci/config.yml