vibe-guard 1.1.4 → 1.1.5

package/README.md

@@ -1,343 +1,185 @@
-# Vibe-Guard Security Scanner
+# ██ Vibe-Guard Security Scanner
 
-**The security scanner that actually catches real vulnerabilities without the noise**
+**Security Scanner** - Zero dependencies, instant setup, works everywhere. Optimized performance for security scanning. Current ruleset: 25 essential security rules.
 
-Zero dependencies • Instant setup • Works everywhere • 25 essential security rules
+[![npm version](https://img.shields.io/npm/v/vibe-guard.svg)](https://www.npmjs.com/package/vibe-guard)
+[![Downloads (total)](https://img.shields.io/npm/dt/vibe-guard.svg)](https://www.npmjs.com/package/vibe-guard)
+[![License](https://img.shields.io/npm/l/vibe-guard.svg)](https://github.com/Devjosef/vibe-guard/blob/main/LICENSE)
 
-## What Is This Thing?
+## 🚀 Quick Start
 
-Vibe-Guard catches the security mistakes we all make when we're coding fast. You know the drill you're in the zone, AI is helping you code, or you're quickly prototyping something, and suddenly you've got API keys in your code or forgot to add auth to that admin endpoint. We've all been there.
-
-### The Core Philosophy
-
-- **Catch real issues** - Not theoretical vulnerabilities that don't matter
-- **Zero false positives** - If it flags something, it's actually a problem
-- **Fast enough to use daily** - Scans your entire project in seconds
-- **Works everywhere** - macOS, Linux, Windows, Docker, CI/CD
-- **No setup required** - Download and run, that's it
-
-## Quick Start (The "Just Show Me Code" Section)
-
-### Option 1: Download Binary (Recommended)
 ```bash
-# macOS (Intel)
-curl -L https://github.com/Devjosef/vibe-guard/releases/download/v1.1.3/vibe-guard-macos-x64 -o vibe-guard
-chmod +x vibe-guard
-./vibe-guard scan .
-
-# macOS (Apple Silicon)
-curl -L https://github.com/Devjosef/vibe-guard/releases/download/v1.1.3/vibe-guard-macos-arm64 -o vibe-guard
-chmod +x vibe-guard
-./vibe-guard scan .
-
-# Linux
-curl -L https://github.com/Devjosef/vibe-guard/releases/download/v1.1.3/vibe-guard-linux-x64 -o vibe-guard
-chmod +x vibe-guard
-./vibe-guard scan .
-```
+# Install globally
+npm install -g vibe-guard
 
-### Option 2: Homebrew
-```bash
-brew install Devjosef/tap/vibe-guard
+# Scan your project
 vibe-guard scan .
-```
 
-### Option 3: One-liner Install
-```bash
-curl -fsSL https://raw.githubusercontent.com/Devjosef/vibe-guard/main/install.sh | sh
-```
-
-### Option 4: NPM
-```bash
-# One-time use
-npx vibe-guard scan .
+# Learn about security concepts
+vibe-guard learn xss-detection
 
-# Global install
-npm install -g vibe-guard
-vibe-guard scan .
+# Try with demo files
+vibe-guard demo
 ```
 
-### Option 5: Docker
-```bash
-docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
-```
-
-## The 25 Security Rules (What It Actually Catches)
-
-### 🚨 Critical Issues (7 Rules)
-These will get you hacked. Fix them immediately.
-
-- **Exposed Secrets**: API keys, tokens, credentials in code
-- **Hardcoded Sensitive Data**: Database passwords, JWT secrets, encryption keys  
-- **XSS Detection**: Cross-site scripting vulnerabilities
-
-### ⚠️ High-Risk Issues (12 Rules)
-These are serious but won't immediately compromise your app.
-
-- **Missing Authentication**: Unprotected admin routes and API endpoints
-- **SQL Injection**: String concatenation in database queries
-- **Directory Traversal**: Unsafe file path operations
-- **Open CORS**: Wildcard origins that let anyone access your API
-- **CSRF Protection**: Missing CSRF tokens in forms and unsafe cookies
-- **Insecure Deserialization**: Unsafe JSON parsing and eval usage
-- **Broken Access Control**: Missing authorization checks
-- **Insecure File Upload**: Unsafe file handling and validation
-- **Insecure Session Management**: Weak session secrets and insecure cookies
-
-### 📋 Medium Issues (13 Rules)
-These are security best practices that should be addressed.
-
-- **Unvalidated Input**: Direct use of user input without checks
-- **Insecure HTTP**: Using HTTP instead of HTTPS
-- **Insecure Dependencies**: Outdated packages with known security issues
-- **Missing Security Headers**: No helmet.js or manual security headers
-- **Insecure Random Generation**: Using Math.random() for security purposes
-- **Insecure Logging**: Sensitive data exposure in logs
-- **Insecure Error Handling**: Stack trace and information disclosure
-- **Insecure Configuration**: Debug mode and security features disabled
-- **AI-Generated Code Validation**: Detecting potentially unsafe AI-generated code
-- **AI Data Leakage Prevention**: Preventing sensitive data exposure in AI outputs
-- **Prompt Injection Detection**: Detecting potential prompt injection vulnerabilities
-- **AI Agent Access Control**: Ensuring proper access controls for AI agents
-- **MCP Server Security**: Detecting insecure Model Context Protocol configurations
-
-## Usage Examples
-
-```bash
-# Scan current directory (most common)
-vibe-guard scan .
-
-# Scan specific file
-vibe-guard scan app.js
+## Learning Security 
 
-# Multiple output formats
-vibe-guard scan . --format json    # JSON for CI/CD
-vibe-guard scan . --format sarif   # SARIF for GitHub/SonarQube
-vibe-guard scan . --format html    # HTML report
+Vibe-Guard is more than a scanner, it's an educational tool that teaches you about web security:
 
-# Configuration file
-vibe-guard scan . --config vibe-guard.json
+### **Understanding Vulnerabilities**
 
-# Quick syntax (same as scan)
-vibe-guard .
+**XSS (Cross-Site Scripting):**
+```javascript
+// ❌ Vulnerable code
+app.get('/user', (req, res) => {
+  const userInput = req.query.name;
+  res.send('<h1>Hello ' + userInput + '</h1>'); // XSS!
+});
 
-# Show version
-vibe-guard --version
-
-# Run performance benchmarks
-npm run benchmark
+// ✅ Secure code
+app.get('/user', (req, res) => {
+  const userInput = req.query.name;
+  res.send('<h1>Hello ' + escapeHtml(userInput) + '</h1>');
+});
 ```
 
-## CI/CD Integration
+**SQL Injection:**
+```javascript
+// ❌ Vulnerable code
+const query = 'SELECT * FROM users WHERE id = ' + userId; // SQL injection!
 
-### GitHub Actions
-```yaml
-- name: Security Scan
-  run: |
-    curl -L https://github.com/Devjosef/vibe-guard/releases/download/v1.1.3/vibe-guard-linux-x64 -o vibe-guard
-    chmod +x vibe-guard
-    ./vibe-guard scan .
+// ✅ Secure code
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
 ```
 
-### GitLab CI
-```yaml
-security_scan:
-  script:
-    - curl -L https://github.com/Devjosef/vibe-guard/releases/download/v1.1.3/vibe-guard-linux-x64 -o vibe-guard
-    - chmod +x vibe-guard
-    - ./vibe-guard scan .
-```
+**Exposed Secrets:**
+```javascript
+// ❌ Vulnerable code
+const API_KEY = 'sk-1234567890abcdef'; // Exposed in code!
 
-### Docker in CI
-```yaml
-- name: Security Scan
-  run: docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
+// ✅ Secure code
+const API_KEY = process.env.API_KEY; // Environment variable
 ```
 
-## Scanner Sensitivity (How It Works)
+### **Security Best Practices**
 
-Vibe-Guard is designed with **intelligent sensitivity** to balance detection accuracy with usability:
+1. **Input Validation** - Always validate and sanitize user input
+2. **Output Encoding** - Encode output to prevent XSS
+3. **Parameterized Queries** - Use prepared statements for SQL
+4. **Environment Variables** - Never hardcode secrets
+5. **Security Headers** - Implement proper HTTP security headers
 
-### Detection Characteristics
-- **Detection Rate**: ~50-70% of potential issues (focused on real problems)
-- **False Positive Rate**: Very low (designed for development workflows)
-- **Performance**: Optimized scanning with streamlined detection patterns
-- **Actionable Results**: Every issue includes specific fix suggestions
+## Security Rules
 
-### Automatic Filtering
-Vibe-Guard automatically filters out:
-- Comments and documentation
-- Test files and development code
-- Environment variables (`${VAR}`, `process.env.VAR`)
-- Safe patterns (parameterized queries, HTTPS, etc.)
-- Framework-specific safeguards
+Vibe-Guard detects 25 types of vulnerabilities:
 
-### Use Cases
-- **Development**: Current settings are well-balanced for daily use
-- **Production Audits**: Consider running with verbose mode and manual review
-- **Maximum Sensitivity**: Can be configured by modifying rule filters
+- **Authentication & Authorization**: Missing authentication, broken access control
+- **Input Validation**: SQL injection, XSS, unvalidated input
+- **Data Protection**: Exposed secrets, hardcoded sensitive data
+- **Configuration**: Insecure configuration, missing security headers
+- **Session Management**: Insecure session handling
+- **Error Handling**: Information disclosure through errors
+- **File Operations**: Directory traversal, insecure file uploads
+- **Dependencies**: Insecure dependencies, outdated packages
+- **AI/ML Security**: AI-generated code validation, prompt injection
+- **Modern Threats**: CSRF, CORS issues, insecure logging
 
-## Language Support
+## Use Cases
 
-Works with all the languages you actually use:
-- **JavaScript/TypeScript**: .js, .jsx, .ts, .tsx
-- **Python**: .py
-- **PHP**: .php
-- **Ruby**: .rb
-- **Go**: .go
-- **Java**: .java
-- **C#**: .cs
-- **Config files**: .json, .yaml, .yml, .env
-
-## Development
-
-Want to contribute or build from source?
+**CI/CD Integration:**
+```yaml
+# GitHub Actions
+- name: Security Scan
+  run: vibe-guard scan . --format sarif --output-file security-report.sarif
+```
 
+**Pre-commit Hook:**
 ```bash
-# Clone and build
-git clone https://github.com/Devjosef/vibe-guard.git
-cd vibe-guard
-npm install
-npm run build
+# .git/hooks/pre-commit
+#!/bin/sh
+vibe-guard scan . || exit 1
+```
 
-# Create binaries
-npm run package
+**Educational Tool:**
+```bash
+# Learn about security concepts
+vibe-guard learn sql-injection
+vibe-guard learn xss-detection
 
-# Run tests
-npm test
+# Practice with demo files
+vibe-guard demo
+```
 
-# Build documentation
-npm run docs:build
+## Installation
 
-# Start docs dev server
-npm run docs:dev
+**NPM:**
+```bash
+npm install -g vibe-guard
 ```
 
-### Project Structure
-```
-src/
-├── types/           # TypeScript definitions
-├── rules/           # All 25 security rule implementations
-├── bin/             # CLI interface
-├── scanner.ts       # File scanning engine
-├── reporter.ts      # Output formatting
-├── config.ts        # Configuration loader
-└── index.ts         # Main application
-
-documents/           # Documentation website
-├── index.html       # Landing page
-├── docs.html        # Full documentation
-├── performance.html # Performance benchmarks
-├── rules.html       # Security rules guide
-└── styles.css       # Styling
-
-scripts/
-├── benchmark.js     # Performance testing
-└── maintenance.js   # Project maintenance
+**Homebrew:**
+```bash
+brew install devjosef/tap/vibe-guard
 ```
 
-## Why Choose Vibe-Guard?
-
-### What You Get
-- **Zero Setup**: Download and run, no dependencies
-- **Fast Scanning**: Optimized patterns for speed
-- **Real Issues**: Focused on actual vulnerabilities
-- **Cross-Platform**: Works everywhere
-- **CI/CD Ready**: Integrates seamlessly
-- **Clear Fixes**: Every issue comes with specific solutions
-
-### What You Don't Get
-- Complex configuration files
-- False positive spam
-- Framework lock-in
-- Slow scanning that kills your workflow
-- Cryptic error messages
-
-## Performance Benchmarks
-
-Vibe-Guard is engineered for speed. Here's how it performs:
-
-### ⚡ Speed Metrics
-- **Startup Time**: ~41ms (near-instant)
-- **Small Files (1KB)**: ~51ms (ultra-fast)
-- **Medium Files (5KB)**: ~51ms (very fast)
-- **Large Files (50KB)**: ~117ms (efficient)
-- **Memory Usage**: ~56KB (ultra-low footprint)
-
-### 🏃 Real-World Performance
-- **Small Projects (1-10 files)**: Complete in under 200ms
-- **Medium Projects (100-1000 files)**: Complete in 2-5 seconds
-- **Large Projects (1000+ files)**: Complete in 8-20 seconds
-- **Enterprise Codebases**: Handles 10,000+ files efficiently
-
-### 📊 Run Your Own Benchmarks
+**Direct Download:**
 ```bash
-npm run benchmark
-```
+# Linux
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-linux-x64 -o vibe-guard
+chmod +x vibe-guard
+
+# macOS
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-macos-x64 -o vibe-guard
+chmod +x vibe-guard
 
-## Comparison
+# Windows
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-windows-x64.exe -o vibe-guard.exe
+```
 
-| Feature | Vibe-Guard | Other Tools |
-|---------|------------|-------------|
-| Setup Time | 0 seconds | Minutes |
-| Startup Time | ~41ms | 2-5 seconds |
-| Small File Scan | ~51ms | 500ms-2s |
-| Large File Scan | ~117ms | 5-15s |
-| Memory Usage | ~56KB | 50-200MB |
-| Dependencies | Zero | 50-200 |
-| False Positives | Minimal | High |
-| Languages | All major ones | Limited |
-| CI/CD Ready | ✅ Yes | ⚠️ Complex |
-| Actually explains fixes | ✅ Yes | ❌ Cryptic |
-| ARM64 Support | ✅ Yes | ❌ Limited |
-| Security Rules | 25 comprehensive rules | Varies |
+## Documentation
 
-## Who This Is For
+- **[Getting Started](https://devjosef.github.io/vibe-guard/getting-started.html)** - Complete setup guide
+- **[Security Rules](https://devjosef.github.io/vibe-guard/rules.html)** - Detailed rule explanations
+- **[Performance Guide](https://devjosef.github.io/vibe-guard/performance.html)** - Optimization tips
+- **[API Reference](https://devjosef.github.io/vibe-guard/docs.html)** - Programmatic usage
 
-- **When you're coding with AI** - ChatGPT and Copilot are amazing, but they sometimes miss security basics
-- **Rapid prototyping** - Building something quick? Don't let security be an afterthought
-- **No-code/Low-code folks** - Generated code can have issues, this catches them
-- **Your CI/CD pipeline** - Catch problems before they hit production
-- **Code reviews** - Run this before you submit that PR
-- **Learning security** - Get real-time feedback on what can or is going wrong (and how to fix it)
+## 🤝 Community
 
-## Documentation & Resources
+**Join us in making the web more secure:**
 
-- **📖 [Full Documentation](https://devjosef.github.io/vibe-guard/)** - Complete guides and API reference
-- **⚡ [Performance Benchmarks](https://devjosef.github.io/vibe-guard/performance.html)** - Detailed speed metrics
-- **🛡️ [Security Rules](https://devjosef.github.io/vibe-guard/rules.html)** - All 25 rules explained
-- **🚀 [Getting Started](https://devjosef.github.io/vibe-guard/getting-started.html)** - Quick setup guide
+-  **Learn**: `vibe-guard learn [topic]` - Understand security concepts
+-  **Demo**: `vibe-guard demo` - Try with example vulnerabilities
+-  **Stats**: `vibe-guard stats` - See your security impact
+-  **Discuss**: [GitHub Discussions](https://github.com/Devjosef/vibe-guard/discussions)
+-  **Report**: [GitHub Issues](https://github.com/Devjosef/vibe-guard/issues)
+-  **Star**: [GitHub Repository](https://github.com/Devjosef/vibe-guard)
 
-## Roadmap
+##  Why Vibe-Guard?
 
-### ✅ Completed Features
-- **Configuration Files**: Full support for `vibe-guard.json` configuration
-- **Multiple Output Formats**: Table, JSON, SARIF, and HTML reports
-- **Documentation Site**: Beautiful, responsive documentation
-- **Performance Benchmarks**: Comprehensive speed testing
-- **GitHub Pages**: Automated deployment
+**Built for developers who code fast and need security that keeps up:**
 
-### 🚧 Planned Features
-- **Custom Rules**: User-defined security rules and patterns
-- **CI/CD Integration**: GitHub Actions and other CI/CD examples
-- **Performance Improvements**: Parallel processing, caching
-- **IDE Integration**: VS Code extension, editor plugins
+-  **Zero dependencies** - Lightweight and fast
+-  **25 security rules** - Comprehensive coverage
+-  **Cross-platform** - Works everywhere
+-  **Educational** - Learn while you scan
+-  **OWASP aligned** - Industry best practices
+-  **Developer-friendly** - Simple CLI interface
 
-## Contributing
+##  Impact
 
-1. **Add Security Rules**: Extend the rule engine with new patterns
-2. **Improve Detection**: Help reduce false positives
-3. **Add Languages**: Support more file types and frameworks
-4. **Better UX**: Improve CLI and output formatting
+Every scan makes the web a little more secure:
 
-See [SECURITY_RULES.md](SECURITY_RULES.md) for detailed rule documentation.
+- **600+ total downloads** on NPM
+- **25 security rules** covering modern threats
+- **Cross-platform** support (Linux, macOS, Windows)
+- **Zero dependencies** for maximum compatibility
+- **Educational focus** - teaching security concepts
 
-## License
+##  License
 
-MIT License - Use it anywhere, anytime!
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-**Built with love by developers who got tired of slow, complex security tools.**
-
-*Security shouldn't slow you down, but security holes definitely will.* 
+**Built for the greater good, like curl for security scanning.**