vibe-guard 1.1.3 → 1.1.5

package/README.md

@@ -1,259 +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.
+```bash
+# Install globally
+npm install -g vibe-guard
 
-### The Core Philosophy
+# Scan your project
+vibe-guard scan .
 
-- **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
+# Learn about security concepts
+vibe-guard learn xss-detection
 
-## Quick Start (The "Just Show Me Code" Section)
+# Try with demo files
+vibe-guard demo
+```
 
-### 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 .
+## Learning Security 
 
-# 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 .
+Vibe-Guard is more than a scanner, it's an educational tool that teaches you about web security:
 
-# 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 .
-```
+### **Understanding Vulnerabilities**
 
-### Option 2: NPM
-```bash
-# One-time use
-npx vibe-guard scan .
+**XSS (Cross-Site Scripting):**
+```javascript
+// ❌ Vulnerable code
+app.get('/user', (req, res) => {
+  const userInput = req.query.name;
+  res.send('<h1>Hello ' + userInput + '</h1>'); // XSS!
+});
 
-# Global install
-npm install -g vibe-guard
-vibe-guard scan .
+// ✅ Secure code
+app.get('/user', (req, res) => {
+  const userInput = req.query.name;
+  res.send('<h1>Hello ' + escapeHtml(userInput) + '</h1>');
+});
 ```
 
-### Option 3: Docker
-```bash
-docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
+**SQL Injection:**
+```javascript
+// ❌ Vulnerable code
+const query = 'SELECT * FROM users WHERE id = ' + userId; // SQL injection!
+
+// ✅ Secure code
+const query = 'SELECT * FROM users WHERE id = ?';
+db.query(query, [userId]);
 ```
 
-## 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
+**Exposed Secrets:**
+```javascript
+// ❌ Vulnerable code
+const API_KEY = 'sk-1234567890abcdef'; // Exposed in code!
 
-```bash
-# Scan current directory (most common)
-vibe-guard scan .
+// ✅ Secure code
+const API_KEY = process.env.API_KEY; // Environment variable
+```
 
-# Scan specific file
-vibe-guard scan app.js
+### **Security Best Practices**
 
-# JSON output for CI/CD
-vibe-guard scan . --format json
+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
 
-# Quick syntax (same as scan)
-vibe-guard .
+## Security Rules
 
-# Show version
-vibe-guard --version
-```
+Vibe-Guard detects 25 types of vulnerabilities:
 
-## CI/CD Integration
+- **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
 
-### 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 .
-```
+## Use Cases
 
-### 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 .
-```
-
-### Docker in CI
+**CI/CD Integration:**
 ```yaml
+# GitHub Actions
 - name: Security Scan
-  run: docker run --rm -v $(pwd):/code vibe-guard/vibe-guard:1.1.3 scan /code
+  run: vibe-guard scan . --format sarif --output-file security-report.sarif
 ```
 
-## Scanner Sensitivity (How It Works)
-
-Vibe-Guard is designed with **intelligent sensitivity** to balance detection accuracy with usability:
-
-### 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
-
-### 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
+**Pre-commit Hook:**
+```bash
+# .git/hooks/pre-commit
+#!/bin/sh
+vibe-guard scan . || exit 1
+```
 
-### 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
+**Educational Tool:**
+```bash
+# Learn about security concepts
+vibe-guard learn sql-injection
+vibe-guard learn xss-detection
 
-## Language Support
+# Practice with demo files
+vibe-guard demo
+```
 
-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
+## Installation
 
-## Development
+**NPM:**
+```bash
+npm install -g vibe-guard
+```
 
-Want to contribute or build from source?
+**Homebrew:**
+```bash
+brew install devjosef/tap/vibe-guard
+```
 
+**Direct Download:**
 ```bash
-# Clone and build
-git clone https://github.com/Devjosef/vibe-guard.git
-cd vibe-guard
-npm install
-npm run build
+# Linux
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-linux-x64 -o vibe-guard
+chmod +x vibe-guard
 
-# Create binaries
-npm run package
+# macOS
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-macos-x64 -o vibe-guard
+chmod +x vibe-guard
 
-# Run tests
-npm test
+# Windows
+curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-windows-x64.exe -o vibe-guard.exe
 ```
 
-### Project Structure
-```
-src/
-├── types/           # TypeScript definitions
-├── rules/           # All 25 security rule implementations
-├── bin/             # CLI interface
-├── scanner.ts       # File scanning engine
-├── reporter.ts      # Output formatting
-└── index.ts         # Main application
-```
+## Documentation
 
-## Why Choose Vibe-Guard?
+- **[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
 
-### 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
+## 🤝 Community
 
-### What You Don't Get
-- Complex configuration files
-- False positive spam
-- Framework lock-in
-- Slow scanning that kills your workflow
-- Cryptic error messages
+**Join us in making the web more secure:**
 
-## Comparison
+-  **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)
 
-| Feature | Vibe-Guard | Other Tools |
-|---------|------------|-------------|
-| Setup Time | 0 seconds | Minutes |
-| Dependencies | Zero | Many |
-| False Positives | Minimal | High |
-| Speed | ⚡ Fast | 🐌 Slow |
-| 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 |
+##  Why Vibe-Guard?
 
-## Who This Is For
+**Built for developers who code fast and need security that keeps up:**
 
-- **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)
+-  **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.**