@trust-assurance-protocol/owaspscan 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,413 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@trust-assurance-protocol/owaspscan?color=blue&label=npm" alt="npm version" />
+  <img src="https://img.shields.io/badge/OWASP-Top%2010%20%2B%20LLM%20Top%2010-orange" alt="OWASP Coverage" />
+  <img src="https://img.shields.io/badge/languages-10-green" alt="Languages" />
+  <img src="https://img.shields.io/badge/rules-30%2B-red" alt="Rules" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
+</p>
+
+# OWASPScan
+
+**Security code auditor covering OWASP Top 10 + LLM Top 10.** Detects vulnerabilities in AI-generated and human-written code using AST analysis, taint tracking, and optional AI verification.
+
+Built for developers who ship fast and security teams who need coverage across the full OWASP attack surface — including AI-specific threats.
+
+```bash
+npx @trust-assurance-protocol/owaspscan scan ./src
+```
+
+```
+  [CRITICAL] OWASP-A03-001  A03:2021  SQL Injection via String Concatenation
+             src/db/users.ts:42  |  db.query(`SELECT * FROM users WHERE id = ${req.params.id}`)
+             Confidence: HIGH  Method: ast  CWE-89
+
+  [HIGH]     OWASP-A02-001  A02:2021  Hardcoded API Key / Secret
+             src/config.ts:8    |  const API_KEY = "sk-live-abc123..."
+             Confidence: HIGH  Method: regex  CWE-798
+
+  Score: 35/100 | 12 findings | 2 CRITICAL, 4 HIGH, 6 MEDIUM
+```
+
+---
+
+## Why OWASPScan
+
+- **AI-aware.** First scanner with native OWASP LLM Top 10 rules — catches prompt injection, sensitive data leakage to LLMs, excessive agency, and more.
+- **Deep analysis.** Three-tier detection: regex patterns, tree-sitter AST analysis with cross-file taint tracking, and optional Claude AI verification.
+- **10 languages.** JavaScript, TypeScript, Python, Java, Go, PHP, Ruby, C#, C/C++, Rust.
+- **CI/CD native.** SARIF output for GitHub Code Scanning, `--fail-on` for pipeline gates, JSON for dashboards.
+- **MCP server.** Plug directly into Claude Desktop, Cursor, or any MCP client — scan code from your AI assistant.
+- **Zero config.** Works out of the box. One command, instant results.
+
+---
+
+## Quick Start
+
+### Install globally
+
+```bash
+npm install -g @trust-assurance-protocol/owaspscan
+```
+
+### Scan a project
+
+```bash
+owaspscan scan ./my-project
+```
+
+### Scan a single file
+
+```bash
+owaspscan scan src/auth/login.ts
+```
+
+### Scan code from stdin
+
+```bash
+cat src/handler.js | owaspscan check --lang javascript
+```
+
+### Use without installing
+
+```bash
+npx @trust-assurance-protocol/owaspscan scan ./src
+```
+
+---
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Scan with specific OWASP categories
+owaspscan scan ./src --rules A03,A07,LLM01
+
+# Output as SARIF for GitHub Code Scanning
+owaspscan scan ./src --format sarif > results.sarif
+
+# Fail CI if critical or high findings exist
+owaspscan scan ./src --fail-on high
+
+# Run with SCA dependency scanning
+owaspscan scan ./src --sca
+
+# AI-powered verification (requires ANTHROPIC_API_KEY)
+owaspscan scan ./src --ai-verify
+
+# Filter by confidence level
+owaspscan scan ./src --min-confidence HIGH
+
+# List all rules
+owaspscan rules
+owaspscan rules --category A03 --severity HIGH
+```
+
+### Full CLI Reference
+
+| Flag | Description |
+|------|-------------|
+| `-r, --rules <categories>` | Filter by OWASP categories (e.g., `A01,A03,LLM01`) |
+| `-f, --format <format>` | Output: `console`, `json`, `sarif`, `llm` |
+| `--fail-on <severity>` | Exit code 1 at threshold: `critical`, `high`, `medium`, `low` |
+| `--sca` | Scan dependencies against OSV CVE database |
+| `--ai-verify` | Verify findings with Claude AI |
+| `--ai-verify-limit <n>` | Max AI verification calls (default: 50) |
+| `--min-confidence <level>` | Minimum confidence: `HIGH`, `MEDIUM`, `LOW` |
+| `--exclude <patterns>` | Glob patterns to exclude |
+| `--max-findings <n>` | Stop after N findings |
+| `--verbose` | Show fix suggestions and references |
+| `--config <path>` | Path to config file |
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Security Scan
+  run: |
+    npx @trust-assurance-protocol/owaspscan scan ./src \
+      --format sarif \
+      --fail-on high \
+      > results.sarif
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+### GitLab CI
+
+```yaml
+security-scan:
+  script:
+    - npx @trust-assurance-protocol/owaspscan scan ./src --format sarif --fail-on high > gl-sast-report.sarif
+  artifacts:
+    reports:
+      sast: gl-sast-report.sarif
+```
+
+### Pre-commit Hook
+
+```bash
+# .husky/pre-commit
+npx @trust-assurance-protocol/owaspscan scan ./src --fail-on critical --format console
+```
+
+---
+
+## MCP Server — AI Assistant Integration
+
+OWASPScan runs as an [MCP](https://modelcontextprotocol.io) server, letting AI assistants scan code directly.
+
+### Claude Desktop / Cursor / Cline
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "owaspscan": {
+      "command": "npx",
+      "args": ["@trust-assurance-protocol/owaspscan", "scan", "--mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `scan_file` | Scan a single file for vulnerabilities |
+| `scan_directory` | Recursively scan a project directory |
+| `scan_code` | Scan a code snippet — ideal for reviewing AI-generated code before committing |
+| `get_rules` | List rules with filtering by category, language, severity |
+| `explain_finding` | Get detailed explanation and fix for a rule |
+| `get_owasp_category` | Describe an OWASP category with related rules |
+
+---
+
+## Detection Coverage
+
+### OWASP Top 10:2021
+
+| Category | Rules | Examples |
+|----------|-------|----------|
+| **A01** Broken Access Control | 3 | Missing auth middleware, path traversal, IDOR |
+| **A02** Cryptographic Failures | 4 | Hardcoded secrets, weak hashing, insecure TLS |
+| **A03** Injection | 6 | SQL, command, NoSQL, XSS, template, LDAP injection |
+| **A04** Insecure Design | 2 | Missing rate limiting, mass assignment |
+| **A05** Security Misconfiguration | 4 | Debug mode, CORS wildcard, default credentials |
+| **A06** Vulnerable Components | 1 | Outdated packages (via SCA) |
+| **A07** Auth Failures | 4 | JWT none algorithm, no password hashing, weak sessions |
+| **A08** Data Integrity | 2 | Unsafe deserialization, dynamic code execution |
+| **A09** Logging Failures | 2 | Sensitive data in logs, missing error handling |
+| **A10** SSRF | 2 | Unvalidated fetch, open redirect |
+
+### Analysis Methods
+
+OWASPScan uses a tiered approach — each method adds confidence:
+
+| Tier | Method | Languages | Confidence |
+|------|--------|-----------|------------|
+| 1 | **Regex patterns** | All 10 languages | MEDIUM |
+| 2 | **AST analysis** (tree-sitter) | JS, TS, Python | HIGH |
+| 3 | **Taint tracking** | All (regex-based for non-AST languages) | HIGH |
+| 4 | **AI verification** (Claude) | All | HIGH (verified) |
+
+**Cross-file taint tracking**: For JS/TS projects, OWASPScan traces data flows across module boundaries — if one file exports a function that returns user input, downstream files using that function are flagged.
+
+---
+
+## Programmatic API
+
+Use OWASPScan as a library in your own tools:
+
+```typescript
+import { scanDirectory, scanCode, scanFile, registry } from '@trust-assurance-protocol/owaspscan';
+
+// Scan a directory
+const result = await scanDirectory('./src', {
+  rules: ['A03', 'A07'],
+  recursive: true,
+  failOn: 'high',
+  verbose: false,
+});
+
+console.log(`Score: ${result.securityScore}/100`);
+console.log(`Findings: ${result.totalFindings}`);
+
+// Scan inline code
+const codeResult = await scanCode(
+  'db.query("SELECT * FROM users WHERE id = " + userId)',
+  'javascript',
+);
+
+// Access rule metadata
+const allRules = registry.getAll();
+const injectionRules = registry.filterByCategories(['A03']);
+```
+
+### Types
+
+```typescript
+import type {
+  Rule,
+  Finding,
+  ScanResult,
+  FileResult,
+  Severity,
+  OWASPCategory,
+  SupportedLanguage,
+} from '@trust-assurance-protocol/owaspscan/types';
+```
+
+---
+
+## Configuration
+
+Create `owaspscan.config.json` in your project root:
+
+```json
+{
+  "rules": ["A01", "A02", "A03", "A07"],
+  "exclude": ["**/*.test.ts", "**/*.spec.js", "migrations/**"],
+  "failOn": "high",
+  "minConfidence": "MEDIUM",
+  "format": "console",
+  "verbose": true,
+  "sca": true,
+  "aiVerify": false,
+  "aiVerifyLimit": 50
+}
+```
+
+CLI flags override config file values. Config is auto-discovered from the scan target directory.
+
+---
+
+## Plugin System
+
+OWASPScan supports external rule packages. Create custom rules that integrate seamlessly:
+
+```typescript
+import type { Rule } from '@trust-assurance-protocol/owaspscan/types';
+import { registry } from '@trust-assurance-protocol/owaspscan';
+
+const myRule: Rule = {
+  id: 'CUSTOM-001',
+  name: 'My Custom Rule',
+  owasp: 'A03:2021',
+  cwe: 'CWE-89',
+  severity: 'HIGH',
+  languages: ['javascript', 'typescript'],
+  description: 'Detects a custom vulnerability pattern',
+  patterns: [{ pattern: /dangerousFunction\(/ }],
+  fix: 'Use safeFunction() instead',
+  references: ['https://example.com/docs'],
+  tags: ['custom', 'injection'],
+};
+
+registry.registerRules([myRule]);
+```
+
+---
+
+## Supported Languages
+
+| Language | Extensions | AST Analysis | Taint Tracking |
+|----------|-----------|:------------:|:--------------:|
+| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | Yes | Yes (AST) |
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | Yes | Yes (AST) |
+| Python | `.py`, `.pyw` | Yes | Yes (AST) |
+| Java | `.java` | — | Yes (regex) |
+| Go | `.go` | — | Yes (regex) |
+| PHP | `.php` | — | Yes (regex) |
+| Ruby | `.rb`, `.rake` | — | Yes (regex) |
+| C# | `.cs` | — | Yes (regex) |
+| C/C++ | `.c`, `.cpp`, `.h` | — | Yes (regex) |
+| Rust | `.rs` | — | Yes (regex) |
+
+---
+
+## Inline Suppression
+
+Suppress specific findings with comments:
+
+```javascript
+// owaspscan-suppress OWASP-A03-001
+db.query(trustedInternalQuery); // Known safe usage
+```
+
+---
+
+## Output Formats
+
+### Console (default)
+Human-readable colored output with severity grouping.
+
+### JSON
+```bash
+owaspscan scan ./src --format json | jq '.securityScore'
+```
+
+### SARIF
+GitHub Code Scanning and GitLab SAST compatible.
+```bash
+owaspscan scan ./src --format sarif > results.sarif
+```
+
+### LLM
+Compact, token-efficient format optimized for AI agents.
+```bash
+owaspscan scan ./src --format llm
+```
+
+---
+
+## SCA — Dependency Scanning
+
+Scan your dependencies for known CVEs using the [OSV](https://osv.dev) database:
+
+```bash
+owaspscan scan ./my-project --sca
+```
+
+Supports:
+- `package-lock.json` (npm)
+- `requirements.txt` (Python)
+
+No API key required. Results are integrated into the main scan output.
+
+---
+
+## AI Verification
+
+Use Claude to verify low-confidence findings and eliminate false positives:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+owaspscan scan ./src --ai-verify --ai-verify-limit 25
+```
+
+- Reviews code context (surrounding lines) to confirm real vulnerabilities
+- Detects sanitization, parameterization, and safe patterns
+- Upgrades confirmed findings from MEDIUM to HIGH confidence
+- Results cached for 24 hours to minimize API costs
+
+---
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Optional: `ANTHROPIC_API_KEY` for AI verification
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trust-assurance-protocol/owaspscan",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Professional OWASP Top 10 + LLM Top 10 security auditor for AI-generated and human-written code",
   "keywords": [
     "owasp",