Documentation

Complete guide to Vibe-Guard's security scanning capabilities and features.

Motivation

Vibe-Guard was created to solve the problem of security scanning that actually catches real vulnerabilities without the noise. Traditional security tools often produce overwhelming false positives, making them impractical for daily development workflows.

Key Insight: Security tools should enhance developer productivity, not hinder it. Vibe-Guard focuses on actionable results that developers can immediately address.

Security Rules

Vibe-Guard implements 25 carefully crafted security rules that target real-world vulnerabilities commonly found in production applications.

Rule Categories

Injection Attacks: SQL Injection, XSS, Command Injection
Authentication & Authorization: Broken Access Control, Missing Authentication
Data Exposure: Exposed Secrets, Hardcoded Credentials
Configuration: Insecure Dependencies, Insecure Configuration
Input Validation: Unvalidated Input, Directory Traversal
AI Security: AI-generated code validation, Prompt injection detection

Scanning Engine

Vibe-Guard uses optimized regex patterns to efficiently detect vulnerabilities across multiple file types.

How It Works

// 1. File discovery
const files = discoverFiles(targetPath);

// 2. Apply security rules
for (const rule of rules) {
  const issues = rule.check(fileContent);
  results.push(...issues);
}

// 3. Generate report
return formatResults(results);
                            

Performance & Benchmarks

Vibe-Guard is engineered for maximum speed and efficiency, designed to scan large codebases in seconds, not minutes.

⚡

Startup Time

~41ms

Near-instant startup with zero dependency resolution delays

🚀

Small Files (1KB)

~51ms

Ultra-fast scanning for individual files

⚡

Medium Files (5KB)

~51ms

Very fast processing for typical source files

🏃

Large Files (50KB)

~117ms

Efficient handling of large code files

💾

Memory Usage

~56KB

Ultra-low memory footprint for large projects

📁

Directory Scan

~123ms

Fast scanning of entire project directories

Performance Features

Zero Dependencies: No external runtime dependencies
Optimized Patterns: Pre-compiled regex patterns for maximum speed
Smart Filtering: Skip irrelevant files and directories
Memory Efficient: Stream-based processing for large files
Fast Startup: No dependency resolution delays
Parallel Processing: Efficient multi-threading for large codebases

Run Your Own Benchmarks

Test Vibe-Guard's performance on your own system:

Run Performance Benchmarks

npm run benchmark

Or run directly

node scripts/benchmark.js

Performance Comparison

Tool	Startup Time	Small File	Large File	Memory Usage	Dependencies
Vibe-Guard	~41ms	~51ms	~117ms	~56KB	0
Other Security Tools	2-5s	500ms-2s	5-15s	50-200MB	50-200

Real-World Performance

Vibe-Guard has been tested on various project sizes:

Small Projects (1-10 files): Scans complete in under 200ms
Medium Projects (100-1000 files): Scans complete in 2-5 seconds
Large Projects (1000+ files): Scans complete in 8-20 seconds
Enterprise Codebases: Efficiently handles projects with 10,000+ files

Zero Dependencies

Vibe-Guard is built with zero runtime dependencies, making it lightweight, fast, and secure.

Benefits

Lightweight: Under 1MB total size
Fast Startup: No dependency resolution delays
Security: No external dependencies to audit
Reliability: No dependency conflicts or version issues
Portability: Works anywhere Node.js runs

Installation

Vibe-Guard can be installed via multiple methods depending on your platform and preferences.

npm

npm install -g vibe-guard

Homebrew

brew install Devjosef/tap/vibe-guard

Direct Download

curl -fsSL https://raw.githubusercontent.com/Devjosef/vibe-guard/main/install.sh | sh

Basic Usage

Get started with Vibe-Guard in under 30 seconds.

Scan Current Directory

vibe-guard

Scan Specific Path

vibe-guard /path/to/your/project

Output to JSON

vibe-guard --output json --output-file results.json

CLI Options

Vibe-Guard provides essential command-line options for customization.

Option	Description	Default
`--format`	Output format (table, json, sarif, html)	table
`--output-file`	Save results to file	stdout
`--verbose`	Show detailed output	false
`--exclude`	Exclude file patterns	config
`--include`	Include file patterns	config

CLI Commands

Command	Description
`vibe-guard scan <target>`	Scan files or directories
`vibe-guard rules`	List all available security rules
`vibe-guard init`	Create a default vibe-guard.json configuration file
`vibe-guard config`	Show sample configuration
`vibe-guard version`	Show version information

File Scanning

Vibe-Guard automatically discovers and scans files across your project.

Supported File Types

JavaScript/TypeScript: .js, .jsx, .ts, .tsx
Web Frameworks: .vue, .svelte
Backend Languages: .py, .php, .rb, .go, .java, .cs
Systems Languages: .cpp, .c, .h, .rs, .kt
Configuration: .json, .yaml, .yml, .xml, .env

Configuration Support

Vibe-Guard automatically loads configuration from vibe-guard.json files in your project hierarchy.

vibe-guard.json

{
  "exclude": ["node_modules/**", "dist/**"],
  "outputFormat": "json",
  "verbose": true,
  "rules": {
    "sql-injection": { "enabled": true }
  }
}
                            

Automatic Filtering

Skips binary files and large files (>5MB)
Excludes common directories (node_modules, dist, .git)
Ignores minified and bundled files

Rule System

Vibe-Guard uses a pattern-based rule system to detect security vulnerabilities.

Rule Structure

abstract class BaseRule {
  name: string;
  description: string;
  severity: SeverityLevel;
  
  abstract check(fileContent: FileContent): SecurityIssue[];
}
                            

Severity Levels

Critical: Immediate security risk
High: Significant security vulnerability
Medium: Moderate security concern
Low: Minor security issue

Output Formats

Vibe-Guard provides two output formats for different use cases.

Text Format (Default)

Human-readable console output with color-coded severity levels and detailed issue descriptions.

Text Output Example

🛡️  Vibe-Guard Security Scan Results

📁 Files scanned: 45
🚨 Issues found: 3

🔴 CRITICAL: SQL Injection detected
   File: src/database.js:15
   Line: 15: const query = `SELECT * FROM users WHERE id = ${userId}`;
   Suggestion: Use parameterized queries or prepared statements

🟡 MEDIUM: Hardcoded credentials found
   File: config/database.json:8
   Line: 8: "password": "admin123"
   Suggestion: Use environment variables for sensitive data
                            

JSON Format

Machine-readable structured data for integration with other tools and CI/CD pipelines.

JSON Output Example

{
  "issues": [
    {
      "rule": "sql-injection",
      "severity": "critical",
      "file": "src/database.js",
      "line": 15,
      "message": "SQL Injection detected"
    }
  ],
  "summary": {
    "critical": 1,
    "high": 0,
    "medium": 1,
    "low": 1
  }
}
                            

SARIF Format

Static Analysis Results Interchange Format for integration with GitHub, Azure DevOps, and other tools.

SARIF Output Example

{
  "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Vibe-Guard",
          "version": "1.1.3"
        }
      },
      "results": [
        {
          "ruleId": "sql-injection",
          "level": "error",
          "message": { "text": "SQL Injection detected" },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "src/database.js" },
                "region": {
                  "startLine": 15,
                  "startColumn": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}
                            

HTML Format

Beautiful, interactive HTML reports for sharing with teams and stakeholders.

HTML Report Features

• Responsive design for all devices
• Color-coded severity levels
• Interactive issue details
• Code snippets with syntax highlighting
• Professional styling and branding
• Easy to share and archive
                            

TypeScript Types

Vibe-Guard provides comprehensive TypeScript types for type-safe development.

Core Types

interface SecurityIssue {
  rule: string;
  severity: SeverityLevel;
  file: string;
  line: number;
  message: string;
  suggestion: string;
}

interface ScanResult {
  issues: SecurityIssue[];
  filesScanned: number;
  summary: {
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
}
                            

False Positives

Learn how to handle and reduce false positives in your security scans.

Common False Positive Sources

Test Files: Mock data and test scenarios
Documentation: Code examples in comments
Generated Code: Auto-generated boilerplate
Legacy Code: Deprecated but safe patterns

Note: Vibe-Guard focuses on reducing false positives through careful pattern design, but some may still occur. Always review findings in context.

Best Practices

Follow these best practices to get the most out of Vibe-Guard.

Scanning Strategy

Run scans early in development, not just before deployment
Review findings in context - not all matches are vulnerabilities
Use Vibe-Guard alongside other security tools
Regularly update to get the latest security patterns

Integration Tips

Add Vibe-Guard to your development workflow
Use JSON output for CI/CD integration
Set up regular automated scans
Document security findings and fixes

Pro Tip: Use Vibe-Guard in combination with other security tools for comprehensive coverage. Vibe-Guard excels at catching common vulnerabilities quickly, while other tools can provide deeper analysis.

Roadmap

Future features we're planning to add to Vibe-Guard.

Planned Features

Custom Rules: User-defined security rules
CI/CD Integration: GitHub Actions and other CI/CD examples
Performance Improvements: Parallel processing, caching
IDE Integration: VS Code extension, editor plugins

Contributing: We welcome contributions! Check out our GitHub repository to see how you can help improve Vibe-Guard.