vibe-guard 1.1.4 → 1.2.0

package/README.md

@@ -1,343 +1,223 @@
-# Vibe-Guard Security Scanner
+# ██ Vibe-Guard Security Scanner
 
-**The security scanner that actually catches real vulnerabilities without the noise**
+**Professional Security Scanner** - Zero dependencies, instant setup, works everywhere. Optimized performance for security scanning. Current ruleset: 28 essential security rules including container security.
 
-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 .
+# Install globally
+npm install -g vibe-guard
 
-# 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 .
-```
+# Start interactive session
+vibe-guard start
 
-### 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 .
 
-# Global install
-npm install -g vibe-guard
-vibe-guard scan .
-```
+# Learn about security concepts
+vibe-guard learn xss-detection
 
-### Option 5: Docker
-```bash
-docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
+# Try with demo files
+vibe-guard demo
 ```
 
-## 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 .
+## Interactive Security Learning
 
-# Scan specific file
-vibe-guard scan app.js
+Vibe-Guard is more than a scanner—it's an educational platform that teaches you about web security through hands-on experience:
 
-# 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
+### Understanding Vulnerabilities
 
-# Configuration file
-vibe-guard scan . --config vibe-guard.json
+**XSS (Cross-Site Scripting):**
+```javascript
+// ❌ Vulnerable code
+app.get('/user', (req, res) => {
+  const userInput = req.query.name;
+  res.send('<h1>Hello ' + userInput + '</h1>'); // XSS vulnerability!
+});
 
-# Quick syntax (same as scan)
-vibe-guard .
-
-# 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 risk!
 
-### 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'; // Secret exposed in source code!
+
+// ✅ Secure code
+const API_KEY = process.env.API_KEY; // Environment variable
 ```
 
-### Docker in CI
+**Container Security:**
 ```yaml
-- name: Security Scan
-  run: docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
+# ❌ Vulnerable Kubernetes manifest
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  template:
+    spec:
+      containers:
+      - name: app
+        image: nginx:latest  # Latest tag vulnerability
+        securityContext:
+          runAsUser: 0       # Root user vulnerability
+          privileged: true   # Privileged container vulnerability
+
+# ✅ Secure Kubernetes manifest
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  template:
+    spec:
+      containers:
+      - name: app
+        image: nginx:1.21.6@sha256:abc123...  # Pinned digest
+        securityContext:
+          runAsUser: 1000    # Non-root user
+          runAsNonRoot: true
+          allowPrivilegeEscalation: false
 ```
 
-## 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 attacks
+3. **Parameterized Queries** - Use prepared statements for database operations
+4. **Environment Variables** - Never hardcode secrets in source code
+5. **Security Headers** - Implement proper HTTP security headers
+6. **Container Security** - Use non-root users, pinned image digests, and proper security contexts
 
-### 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
+## Comprehensive Security Coverage
 
-### 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 28 types of vulnerabilities across multiple categories:
 
-### 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, session management
+- **Input Validation**: SQL injection, XSS, unvalidated input, directory traversal
+- **Data Protection**: Exposed secrets, hardcoded sensitive data, insecure logging
+- **Configuration**: Insecure configuration, missing security headers, CORS issues
+- **Modern Threats**: CSRF protection, AI-generated code validation, prompt injection
+- **Dependencies**: Insecure dependencies, outdated packages, vulnerability assessment
+- **Container Security**: Kubernetes security, Dockerfile vulnerabilities, container registry issues
 
-## Language Support
+## Professional 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
+**CI/CD Integration:**
+```yaml
+# GitHub Actions
+- name: Security Scan
+  run: vibe-guard scan . --format sarif --output-file security-report.sarif
+```
 
-Want to contribute or build from source?
+**Pre-commit Hook:**
+```bash
+# .git/hooks/pre-commit
+#!/bin/sh
+vibe-guard scan . || exit 1
+```
 
+**Interactive Learning:**
 ```bash
-# Clone and build
-git clone https://github.com/Devjosef/vibe-guard.git
-cd vibe-guard
-npm install
-npm run build
+# Start interactive session
+vibe-guard start
 
-# Create binaries
-npm run package
+# Learn specific 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 Options
 
-# Start docs dev server
-npm run docs:dev
+**NPM (Recommended):**
+```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
-
-| 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 |
-
-## Who This Is For
-
-- **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)
+# Windows
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-windows-x64.exe -o vibe-guard.exe
+```
 
 ## Documentation & Resources
 
-- **📖 [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
+- **[Getting Started](https://devjosef.github.io/vibe-guard/getting-started.html)** - Complete setup and configuration guide
+- **[Security Rules](https://devjosef.github.io/vibe-guard/rules.html)** - Detailed rule explanations and examples
+- **[Performance Guide](https://devjosef.github.io/vibe-guard/performance.html)** - Optimization and best practices
+- **[API Reference](https://devjosef.github.io/vibe-guard/docs.html)** - Programmatic usage and integration
 
-## Roadmap
+## Community & Support
 
-### ✅ 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
+**Join our community of security professionals and developers:**
 
-### 🚧 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
+- **Interactive Learning**: `vibe-guard start` - Begin your security journey
+- **Educational Commands**: `vibe-guard learn [topic]` - Master security concepts
+- **Hands-on Practice**: `vibe-guard demo` - Test with example vulnerabilities
+- **Performance Insights**: `vibe-guard stats` - Track your security impact
+- **Community Discussion**: [GitHub Discussions](https://github.com/Devjosef/vibe-guard/discussions)
+- **Issue Reporting**: [GitHub Issues](https://github.com/Devjosef/vibe-guard/issues)
+- **Repository**: [GitHub Repository](https://github.com/Devjosef/vibe-guard)
+
+## Why Choose Vibe-Guard?
 
-## Contributing
+**Built for developers who code fast and need security that keeps up:**
 
-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
+- **Zero Dependencies** - Lightweight, fast, and reliable
+- **28 Security Rules** - Comprehensive coverage of modern threats including container security
+- **Cross-Platform** - Works seamlessly across all operating systems
+- **Educational Focus** - Learn security while you scan
+- **OWASP Aligned** - Industry best practices and standards
+- **Developer-Friendly** - Simple, intuitive CLI interface
+- **Interactive Mode** - Guided learning with `vibe-guard start`
+- **Container Security** - Kubernetes, Dockerfile, and registry security scanning
 
-See [SECURITY_RULES.md](SECURITY_RULES.md) for detailed rule documentation.
+## Impact & Adoption
+
+Every scan contributes to a more secure web ecosystem:
+
+- **500+ total downloads** on NPM with growing adoption
+- **28 security rules** covering contemporary threat vectors including container security
+- **Cross-platform support** for Linux, macOS, and Windows
+- **Zero dependencies** ensuring maximum compatibility
+- **Educational approach** - building security awareness
+- **Container security** - Kubernetes, Dockerfile, and registry vulnerability detection
 
 ## 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.**