vibe-guard 1.1.5 → 2.1.0

package/README.md

@@ -1,42 +1,43 @@
 # ██ Vibe-Guard Security Scanner
 
-**Security Scanner** - Zero dependencies, instant setup, works everywhere. Optimized performance for security scanning. Current ruleset: 25 essential security rules.
+Vibe-Guard gives you a quick security pass over source code and configuration files, with 30 pattern-based rules covering common application, AI, dependency, and container risks. Findings include a suggested next step, so scans can also help you learn what to look for.
+
+It is a heuristic scanner, not a substitute for code review or a full security audit. It requires Node.js 20 or newer; npm installs its declared third-party runtime dependencies for you.
 
 [![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)
 
-## 🚀 Quick Start
+
+## Quick Start
 
 ```bash
 # Install globally
 npm install -g vibe-guard
 
+# Interactive menu (scan and view rules)
+vibe-guard start
+
 # Scan your project
 vibe-guard scan .
 
-# Learn about security concepts
-vibe-guard learn xss-detection
-
-# Try with demo files
-vibe-guard demo
+# Export a SARIF report
+vibe-guard scan . --format sarif --output-file security-report.sarif
 ```
 
-## Learning Security 
-
-Vibe-Guard is more than a scanner, it's an educational tool that teaches you about web security:
+`vibe-guard scan` requires a target path. Supported formats are `table`, `json`, `sarif`, and `html`. A scan with findings exits with code 1; scan errors exit with code 2. The interactive `start` menu lets you scan, view the rule list, and create or view a configuration file. There are no separate `learn`, `demo`, or `stats` commands.
 
-### **Understanding Vulnerabilities**
+## Common issues and safer patterns
 
 **XSS (Cross-Site Scripting):**
 ```javascript
-// ❌ Vulnerable code
+// Vulnerable code
 app.get('/user', (req, res) => {
   const userInput = req.query.name;
-  res.send('<h1>Hello ' + userInput + '</h1>'); // XSS!
+  res.send('<h1>Hello ' + userInput + '</h1>'); // XSS vulnerability!
 });
 
-// ✅ Secure code
+// Secure code
 app.get('/user', (req, res) => {
   const userInput = req.query.name;
   res.send('<h1>Hello ' + escapeHtml(userInput) + '</h1>');
@@ -45,47 +46,76 @@ app.get('/user', (req, res) => {
 
 **SQL Injection:**
 ```javascript
-// ❌ Vulnerable code
-const query = 'SELECT * FROM users WHERE id = ' + userId; // SQL injection!
+// Vulnerable code
+const query = 'SELECT * FROM users WHERE id = ' + userId; // SQL injection risk!
 
-// ✅ Secure code
+// Secure code
 const query = 'SELECT * FROM users WHERE id = ?';
 db.query(query, [userId]);
 ```
 
 **Exposed Secrets:**
 ```javascript
-// ❌ Vulnerable code
-const API_KEY = 'sk-1234567890abcdef'; // Exposed in code!
+// Vulnerable code
+const API_KEY = 'sk-1234567890abcdef'; // Secret exposed in source code!
 
-// ✅ Secure code
+// Secure code
 const API_KEY = process.env.API_KEY; // Environment variable
 ```
 
-### **Security Best Practices**
+**Container Security:**
+```yaml
+# 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:<real-image-digest>  # Replace with the registry's actual digest
+        securityContext:
+          runAsUser: 1000    # Non-root user
+          runAsNonRoot: true
+          allowPrivilegeEscalation: false
+```
+
+### Security Best Practices
 
 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
+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
 
-## Security Rules
+6. **Container Security** - Use non-root users, pinned image digests, and proper security contexts
 
-Vibe-Guard detects 25 types of vulnerabilities:
+## Comprehensive Security Coverage
 
-- **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
+Vibe-Guard detects 30 types of vulnerabilities across multiple categories:
 
-## Use Cases
+- **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**: AI provider tokens, unsafe LLM prompt construction, prompt injection, MCP security
+- **Dependencies**: Known vulnerable packages, floating versions, and mutable Git references
+- **Container Security**: Kubernetes security, Dockerfile vulnerabilities, container registry issues
+
+## Use it in your workflow
 
 **CI/CD Integration:**
 ```yaml
@@ -94,6 +124,10 @@ Vibe-Guard detects 25 types of vulnerabilities:
   run: vibe-guard scan . --format sarif --output-file security-report.sarif
 ```
 
+## SARIF test reporting
+
+For local Jest test-result reporting, see [TEST_SCANNING.md](docs/TEST_SCANNING.md); that utility is separate from scanning project code.
+
 **Pre-commit Hook:**
 ```bash
 # .git/hooks/pre-commit
@@ -101,19 +135,14 @@ Vibe-Guard detects 25 types of vulnerabilities:
 vibe-guard scan . || exit 1
 ```
 
-**Educational Tool:**
+**Interactive menu:**
 ```bash
-# Learn about security concepts
-vibe-guard learn sql-injection
-vibe-guard learn xss-detection
-
-# Practice with demo files
-vibe-guard demo
+vibe-guard start
 ```
 
-## Installation
+## Installation Options
 
-**NPM:**
+**NPM (Recommended):**
 ```bash
 npm install -g vibe-guard
 ```
@@ -123,60 +152,33 @@ npm install -g vibe-guard
 brew install devjosef/tap/vibe-guard
 ```
 
-**Direct Download:**
-```bash
-# 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
-
-# Windows
-curl -L https://github.com/Devjosef/vibe-guard/releases/latest/download/vibe-guard-windows-x64.exe -o vibe-guard.exe
-```
-
-## Documentation
-
-- **[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
-
-## 🤝 Community
-
-**Join us in making the web more secure:**
+Standalone binaries for Linux x64/arm64, macOS x64/arm64, and Windows x64 are built in CI and uploaded as workflow artifacts. They are not currently published as GitHub release downloads.
 
--  **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)
+## Documentation & Resources
 
-##  Why Vibe-Guard?
+- **[Getting Started](https://devjosef.github.io/vibe-guard/getting-started.html)** - Complete setup and configuration guide
+- **[Security Rules](https://devjosef.github.io/vibe-guard/features.html)** - Rule coverage and descriptions
+- **[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
 
-**Built for developers who code fast and need security that keeps up:**
+## Community & Support
 
--  **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
+**Questions, feedback, or a finding that looks wrong?**
 
-##  Impact
+- **Interactive menu**: `vibe-guard start` - Scan or view available rules
+- **SARIF export**: `vibe-guard scan . --format sarif --output-file report.sarif`
+- **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)
 
-Every scan makes the web a little more secure:
+## What to expect
 
-- **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
+- Findings include the rule, severity, file and line, explanation, and suggested remediation.
+- Pattern-based checks can miss issues or flag safe code; review findings in context and do not treat a clean scan as proof that code is secure.
+- `start` is a small interactive menu for scanning and browsing rule descriptions, not a guided course.
+- CI runs the Jest suite on Node.js 20 and 22. Binary builds are CI artifacts until attached to a release.
 
-##  License
+## License
 
 MIT License - see [LICENSE](LICENSE) for details.