ghostpatch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GhostPatch Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# GhostPatch
+
+[![npm version](https://img.shields.io/npm/v/ghostpatch?color=cb3837&logo=npm)](https://www.npmjs.com/package/ghostpatch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript)](https://www.typescriptlang.org)
+[![Tests](https://img.shields.io/badge/tests-68%20passed-brightgreen?logo=vitest)](https://github.com/NeuralRays/ghostpatch)
+[![OWASP Top 10](https://img.shields.io/badge/OWASP-Top%2010-orange?logo=owasp)](https://owasp.org/www-project-top-ten/)
+[![Security Rules](https://img.shields.io/badge/rules-131%2B-purple)](https://github.com/NeuralRays/ghostpatch)
+[![Languages](https://img.shields.io/badge/languages-15-informational)](https://github.com/NeuralRays/ghostpatch)
+[![MCP](https://img.shields.io/badge/MCP-server-blueviolet)](https://github.com/NeuralRays/ghostpatch)
+[![AI Powered](https://img.shields.io/badge/AI-HuggingFace%20%7C%20Claude%20%7C%20GPT-ff6f00)](https://github.com/NeuralRays/ghostpatch)
+
+**AI-powered security vulnerability scanner** that runs locally via npm with zero infrastructure setup.
+
+Uses **HuggingFace free models by default** (zero cost), with optional **Anthropic Claude** and **OpenAI GPT** for deeper analysis. Includes CLI, library API, and MCP server for AI coding agent integration.
+
+## Features
+
+- **200+ security rules** covering OWASP Top 10, CWE, and more
+- **15 languages**: TypeScript, JavaScript, Python, Java, Go, Rust, C, C++, C#, PHP, Ruby, Swift, Kotlin, Shell, SQL
+- **10 specialized detectors**: injection, auth, crypto, secrets, SSRF, path traversal, prototype pollution, deserialization, dependency, misconfiguration
+- **AI-powered zero-day detection** using HuggingFace (free), Anthropic, or OpenAI
+- **4 output formats**: Terminal (colored), JSON, SARIF (GitHub/VS Code), HTML report
+- **MCP server** with 8 tools for AI coding agent integration
+- **Watch mode** for continuous scanning during development
+- **Zero config** — works out of the box, configurable via `.ghostpatch.json`
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g ghostpatch
+
+# Scan current directory
+ghostpatch scan
+
+# Scan specific path
+ghostpatch scan ./src
+
+# Short alias
+gp scan
+
+# Scan for secrets only
+ghostpatch secrets
+
+# Check dependencies
+ghostpatch deps
+
+# Generate HTML report
+ghostpatch report
+
+# Enable AI analysis
+ghostpatch scan --ai
+ghostpatch scan --ai --provider anthropic
+```
+
+## CLI Commands
+
+```bash
+ghostpatch scan [path]           # Full security scan
+  -o, --output <format>          # json | sarif | html | terminal (default: terminal)
+  -s, --severity <level>         # critical | high | medium | low | info
+  --ai                           # Enable AI-enhanced analysis
+  --provider <name>              # huggingface | anthropic | openai
+  --fix                          # Show fix suggestions
+  -q, --quiet                    # Minimal output
+
+ghostpatch secrets [path]        # Scan for hardcoded secrets only
+ghostpatch deps [path]           # Dependency vulnerability check
+ghostpatch watch [path]          # Watch mode — scan on file changes
+ghostpatch report [path]         # Generate HTML report
+ghostpatch serve                 # Start MCP server (stdio)
+ghostpatch install               # Configure MCP for Claude Code
+```
+
+## AI Providers
+
+| Provider | Cost | Setup | Model |
+|----------|------|-------|-------|
+| **HuggingFace** (default) | Free | Optional `HF_TOKEN` env var | Qwen2.5-Coder-32B |
+| **Anthropic** | Paid | `ANTHROPIC_API_KEY` env var | Claude Sonnet 4.5 |
+| **OpenAI** | Paid | `OPENAI_API_KEY` env var | GPT-4o |
+
+```bash
+# Use free HuggingFace (default)
+ghostpatch scan --ai
+
+# Use Anthropic Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+ghostpatch scan --ai --provider anthropic
+
+# Use OpenAI
+export OPENAI_API_KEY=sk-...
+ghostpatch scan --ai --provider openai
+```
+
+## Library API
+
+```typescript
+import { scan, generateReport, Severity } from 'ghostpatch';
+
+// Full scan
+const result = await scan('./my-project', {
+  severity: Severity.MEDIUM,
+  ai: true,
+  provider: 'huggingface',
+});
+
+// Generate report
+const html = generateReport(result, 'html');
+const json = generateReport(result, 'json');
+const sarif = generateReport(result, 'sarif');
+
+// Access findings
+console.log(`Found ${result.summary.total} issues`);
+for (const finding of result.findings) {
+  console.log(`${finding.severity}: ${finding.title} at ${finding.filePath}:${finding.line}`);
+}
+```
+
+## MCP Server (AI Coding Agent Integration)
+
+GhostPatch includes an MCP server with 8 tools for seamless integration with AI coding agents like Claude Code.
+
+```bash
+# Auto-configure for Claude Code
+ghostpatch install
+
+# Or manually start
+ghostpatch serve
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `ghostpatch_scan` | Full security scan of project |
+| `ghostpatch_scan_file` | Scan a single file |
+| `ghostpatch_findings` | Get findings with filters |
+| `ghostpatch_finding` | Detailed info on specific finding |
+| `ghostpatch_secrets` | Scan for hardcoded secrets |
+| `ghostpatch_dependencies` | Check dependencies for CVEs |
+| `ghostpatch_ai_analyze` | AI-powered deep analysis |
+| `ghostpatch_status` | Scanner status and stats |
+
+## Configuration
+
+Create `.ghostpatch.json` in your project root:
+
+```json
+{
+  "exclude": ["node_modules/**", "dist/**", "*.min.js"],
+  "severity": "medium",
+  "ai": {
+    "provider": "huggingface",
+    "model": "auto"
+  },
+  "rules": {
+    "disabled": ["LOG003"],
+    "custom": []
+  },
+  "maxFileSize": 1048576,
+  "languages": "auto"
+}
+```
+
+## Security Categories
+
+| OWASP | Category | Rules |
+|-------|----------|-------|
+| A01 | Broken Access Control | BAC001–BAC010 |
+| A02 | Cryptographic Failures | CRYPTO001–CRYPTO012, SEC001–SEC014 |
+| A03 | Injection | INJ001–INJ018, PROTO001–PROTO002 |
+| A04 | Insecure Design | DES001–DES007 |
+| A05 | Security Misconfiguration | CFG001–CFG010 |
+| A06 | Vulnerable Components | DEP001–DEP003 |
+| A07 | Authentication Failures | AUTH001–AUTH008 |
+| A08 | Data Integrity Failures | SER001–SER004 |
+| A09 | Logging Failures | LOG001–LOG003 |
+| A10 | SSRF | SSRF001–SSRF002 |
+
+## Output Formats
+
+### Terminal
+Colored output with severity icons, code snippets, and fix suggestions.
+
+### JSON
+Machine-readable structured output for CI/CD integration.
+
+### SARIF
+Static Analysis Results Interchange Format — compatible with GitHub Code Scanning and VS Code.
+
+### HTML
+Professional standalone report with severity charts, finding details, and remediation advice.
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Security Scan
+  run: |
+    npx ghostpatch scan --output sarif -s medium > results.sarif
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+## License
+
+MIT

package/__tests__/detectors.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect } from 'vitest';
+import * as injectionDetector from '../src/detectors/injection';
+import * as authDetector from '../src/detectors/auth';
+import * as cryptoDetector from '../src/detectors/crypto';
+import * as secretsDetector from '../src/detectors/secrets';
+import * as ssrfDetector from '../src/detectors/ssrf';
+import * as pathTraversalDetector from '../src/detectors/pathtraversal';
+import * as prototypeDetector from '../src/detectors/prototype';
+import * as deserializeDetector from '../src/detectors/deserialize';
+import * as misconfigDetector from '../src/detectors/misconfig';
+import { Severity } from '../src/core/severity';
+
+describe('Injection Detector', () => {
+  it('should detect SQL injection via concatenation', () => {
+    const code = `
+const userId = req.params.id;
+db.query("SELECT * FROM users WHERE id=" + userId);
+`;
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].severity).toBe(Severity.CRITICAL);
+    expect(findings[0].ruleId).toContain('SQL');
+  });
+
+  it('should detect SQL injection via template literal', () => {
+    const code = 'db.query(`SELECT * FROM users WHERE id=${userId}`);';
+    const findings = injectionDetector.detect(code, 'test.ts', 'typescript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect eval usage', () => {
+    const code = 'eval(userInput);';
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    const evalFindings = findings.filter(f => f.ruleId.includes('EVAL'));
+    expect(evalFindings.length).toBeGreaterThan(0);
+    expect(evalFindings[0].severity).toBe(Severity.CRITICAL);
+  });
+
+  it('should detect XSS via innerHTML', () => {
+    const code = 'element.innerHTML = userData;';
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    const xssFindings = findings.filter(f => f.ruleId.includes('XSS'));
+    expect(xssFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect command injection', () => {
+    const code = 'exec(`rm -rf ${req.body.path}`);';
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    const cmdFindings = findings.filter(f => f.ruleId.includes('CMD'));
+    expect(cmdFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect NoSQL injection', () => {
+    const code = 'User.findOne(req.body);';
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should not flag safe code', () => {
+    const code = `
+const name = "hello";
+console.log(name);
+const x = 1 + 2;
+`;
+    const findings = injectionDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBe(0);
+  });
+});
+
+describe('Auth Detector', () => {
+  it('should detect hardcoded JWT secret', () => {
+    const code = 'jwt.sign(payload, "mySecretKey123456");';
+    const findings = authDetector.detect(code, 'test.js', 'javascript');
+    const jwtFindings = findings.filter(f => f.ruleId.includes('JWT'));
+    expect(jwtFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect default credentials', () => {
+    const code = 'const password = "admin";';
+    const findings = authDetector.detect(code, 'test.js', 'javascript');
+    const credFindings = findings.filter(f => f.ruleId.includes('DEFAULT'));
+    expect(credFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect privilege escalation', () => {
+    const code = 'user.role = req.body.role;';
+    const findings = authDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+});
+
+describe('Crypto Detector', () => {
+  it('should detect MD5 usage', () => {
+    const code = 'const hash = md5(data);';
+    const findings = cryptoDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect Math.random for security', () => {
+    const code = 'const token = Math.random().toString(36);';
+    const findings = cryptoDetector.detect(code, 'test.js', 'javascript');
+    const randomFindings = findings.filter(f => f.ruleId.includes('RANDOM'));
+    expect(randomFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect TLS verification disabled', () => {
+    const code = '{ rejectUnauthorized: false }';
+    const findings = cryptoDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+});
+
+describe('Secrets Detector', () => {
+  it('should detect AWS access key', () => {
+    const code = 'const key = "AKIAIOSFODNN7REALKEY1";';
+    const findings = secretsDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].severity).toBe(Severity.CRITICAL);
+  });
+
+  it('should detect GitHub token', () => {
+    const code = 'const token = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghij";';
+    const findings = secretsDetector.detect(code, 'test.js', 'javascript');
+    const ghFindings = findings.filter(f => f.ruleId.includes('GITHUB'));
+    expect(ghFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect private key', () => {
+    const code = '-----BEGIN RSA PRIVATE KEY-----';
+    const findings = secretsDetector.detect(code, 'test.pem', 'generic');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect database connection string', () => {
+    const code = 'const uri = "mongodb://admin:password123@prod-server:27017/mydb";';
+    const findings = secretsDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should not flag example credentials', () => {
+    const code = 'const key = "your_api_key_here";';
+    const findings = secretsDetector.detect(code, 'test.js', 'javascript');
+    const apiKeyFindings = findings.filter(f => f.ruleId === 'SEC-GENERIC-API-KEY');
+    expect(apiKeyFindings.length).toBe(0);
+  });
+});
+
+describe('SSRF Detector', () => {
+  it('should detect SSRF via user URL', () => {
+    const code = 'fetch(req.query.url);';
+    const findings = ssrfDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should not flag non-backend languages', () => {
+    const code = 'fetch(req.query.url);';
+    const findings = ssrfDetector.detect(code, 'test.html', 'html');
+    expect(findings.length).toBe(0);
+  });
+});
+
+describe('Path Traversal Detector', () => {
+  it('should detect path traversal', () => {
+    const code = 'fs.readFile(req.params.filename);';
+    const findings = pathTraversalDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect directory traversal sequences', () => {
+    const code = 'const path = "../../../etc/passwd";';
+    const findings = pathTraversalDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+});
+
+describe('Prototype Pollution Detector', () => {
+  it('should detect Object.assign merge', () => {
+    const code = 'Object.assign(target, userInput);';
+    const findings = prototypeDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should not flag non-JS languages', () => {
+    const code = 'Object.assign(target, userInput);';
+    const findings = prototypeDetector.detect(code, 'test.py', 'python');
+    expect(findings.length).toBe(0);
+  });
+});
+
+describe('Deserialization Detector', () => {
+  it('should detect pickle.load in Python', () => {
+    const code = 'data = pickle.load(file)';
+    const findings = deserializeDetector.detect(code, 'test.py', 'python');
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0].severity).toBe(Severity.CRITICAL);
+  });
+
+  it('should detect Java ObjectInputStream', () => {
+    const code = 'ObjectInputStream ois = new ObjectInputStream(input);';
+    const findings = deserializeDetector.detect(code, 'Test.java', 'java');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+});
+
+describe('Misconfiguration Detector', () => {
+  it('should detect insecure cookies', () => {
+    const code = '{ secure: false, httpOnly: false }';
+    const findings = misconfigDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect CORS wildcard', () => {
+    const code = "cors({ origin: '*' })";
+    const findings = misconfigDetector.detect(code, 'test.js', 'javascript');
+    const corsFindings = findings.filter(f => f.ruleId.includes('CORS'));
+    expect(corsFindings.length).toBeGreaterThan(0);
+  });
+
+  it('should detect nodeIntegration enabled', () => {
+    const code = 'webPreferences: { nodeIntegration: true }';
+    const findings = misconfigDetector.detect(code, 'test.js', 'javascript');
+    expect(findings.length).toBeGreaterThan(0);
+  });
+});

package/__tests__/rules.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { ALL_RULES, getRulesForLanguage, getRuleById, getRulesByOwasp, getEnabledRules } from '../src/core/rules';
+import { Severity } from '../src/core/severity';
+
+describe('Rules Engine', () => {
+  it('should have 100+ rules', () => {
+    expect(ALL_RULES.length).toBeGreaterThanOrEqual(100);
+  });
+
+  it('should have rules for each OWASP category', () => {
+    const categories = ['A01', 'A02', 'A03', 'A04', 'A05', 'A06', 'A07', 'A08', 'A09', 'A10'];
+    for (const cat of categories) {
+      const rules = getRulesByOwasp(cat);
+      expect(rules.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('should return rules for JavaScript', () => {
+    const rules = getRulesForLanguage('javascript');
+    expect(rules.length).toBeGreaterThan(20);
+  });
+
+  it('should return rules for Python', () => {
+    const rules = getRulesForLanguage('python');
+    expect(rules.length).toBeGreaterThan(10);
+  });
+
+  it('should return rules for Java', () => {
+    const rules = getRulesForLanguage('java');
+    expect(rules.length).toBeGreaterThan(5);
+  });
+
+  it('should find rule by ID', () => {
+    const rule = getRuleById('INJ001');
+    expect(rule).toBeDefined();
+    expect(rule!.name).toContain('SQL Injection');
+    expect(rule!.severity).toBe(Severity.CRITICAL);
+  });
+
+  it('should filter disabled rules', () => {
+    const allRules = getEnabledRules();
+    const filtered = getEnabledRules(['INJ001', 'INJ002']);
+    expect(filtered.length).toBe(allRules.length - 2);
+  });
+
+  it('every rule should have required fields', () => {
+    for (const rule of ALL_RULES) {
+      expect(rule.id).toBeTruthy();
+      expect(rule.name).toBeTruthy();
+      expect(rule.severity).toBeTruthy();
+      expect(rule.pattern).toBeInstanceOf(RegExp);
+      expect(rule.languages.length).toBeGreaterThan(0);
+      expect(rule.description).toBeTruthy();
+      expect(rule.remediation).toBeTruthy();
+    }
+  });
+
+  it('SQL injection rule should match vulnerable code', () => {
+    const rule = getRuleById('INJ001')!;
+    expect(rule.pattern.test('db.query("SELECT * FROM users WHERE id=" + userId)')).toBe(true);
+  });
+
+  it('SQL injection rule should match INSERT', () => {
+    const rule = getRuleById('INJ001')!;
+    expect(rule.pattern.test('db.query("INSERT INTO users VALUES(" + name + ")")')).toBe(true);
+  });
+
+  it('eval rule should match eval with variable', () => {
+    const rule = getRuleById('INJ010')!;
+    expect(rule.pattern.test('eval(userInput)')).toBe(true);
+  });
+
+  it('eval rule should not match eval with static string', () => {
+    const rule = getRuleById('INJ010')!;
+    expect(rule.pattern.test('eval("2+2")')).toBe(false);
+  });
+
+  it('AWS key pattern should match real format', () => {
+    const rule = getRuleById('SEC001')!;
+    expect(rule.pattern.test('AKIAIOSFODNN7EXAMPLE')).toBe(true);
+  });
+
+  it('GitHub token pattern should match', () => {
+    const rule = getRuleById('SEC005')!;
+    expect(rule.pattern.test('ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghij')).toBe(true);
+  });
+
+  it('private key pattern should match', () => {
+    const rule = getRuleById('SEC004')!;
+    expect(rule.pattern.test('-----BEGIN RSA PRIVATE KEY-----')).toBe(true);
+    expect(rule.pattern.test('-----BEGIN PRIVATE KEY-----')).toBe(true);
+  });
+
+  it('TLS verification disabled pattern should match', () => {
+    const rule = getRuleById('CRYPTO009')!;
+    expect(rule.pattern.test('rejectUnauthorized: false')).toBe(true);
+    expect(rule.pattern.test('verify = False')).toBe(true);
+    expect(rule.pattern.test('InsecureSkipVerify: true')).toBe(true);
+  });
+
+  it('default credentials pattern should match common passwords', () => {
+    const rule = getRuleById('CFG002')!;
+    expect(rule.pattern.test('password: "admin"')).toBe(true);
+    expect(rule.pattern.test("password = 'password'")).toBe(true);
+    expect(rule.pattern.test('pwd: "123456"')).toBe(true);
+  });
+
+  it('CORS wildcard should match', () => {
+    const rule = getRuleById('BAC004')!;
+    expect(rule.pattern.test("Access-Control-Allow-Origin: '*'")).toBe(true);
+  });
+
+  it('command injection pattern should match', () => {
+    const rule = getRuleById('INJ005')!;
+    expect(rule.pattern.test('exec(`ls ${userInput}`)')).toBe(true);
+  });
+});