agent-security-scanner-mcp 3.5.0 → 3.5.2

package/README.md

@@ -1,10 +1,14 @@
 # agent-security-scanner-mcp
 
-Security scanner MCP server for AI coding agents. Scans code for vulnerabilities, detects hallucinated packages, and blocks prompt injection — all in real-time via the Model Context Protocol.
+Security scanner for AI coding agents and autonomous assistants. Scans code for vulnerabilities, detects hallucinated packages, and blocks prompt injection — via MCP (Claude Code, Cursor, Windsurf, Cline) or CLI (OpenClaw, CI/CD).
 
 [![npm downloads](https://img.shields.io/npm/dt/agent-security-scanner-mcp.svg)](https://www.npmjs.com/package/agent-security-scanner-mcp)
 [![npm version](https://img.shields.io/npm/v/agent-security-scanner-mcp.svg)](https://www.npmjs.com/package/agent-security-scanner-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Benchmark: 97.7% precision](https://img.shields.io/badge/precision-97.7%25-brightgreen.svg)](benchmarks/RESULTS.md)
+[![CI](https://github.com/sinewaveai/agent-security-scanner-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/sinewaveai/agent-security-scanner-mcp/actions/workflows/test.yml)
+
+> **New in v3.3.0:** Full [OpenClaw](https://openclaw.ai) integration with 30+ rules targeting autonomous AI threats — data exfiltration, credential theft, messaging abuse, and unsafe automation. [See OpenClaw setup](#openclaw-integration).
 
 ## Tools
 
@@ -12,6 +16,8 @@ Security scanner MCP server for AI coding agents. Scans code for vulnerabilities
 |------|-------------|-------------|
 | `scan_security` | Scan code for vulnerabilities (1700+ rules, 12 languages) with AST and taint analysis | After writing or editing any code file |
 | `fix_security` | Auto-fix all detected vulnerabilities (120 fix templates) | After `scan_security` finds issues |
+| `scan_git_diff` | Scan only changed files in git diff | Before commits or in PR reviews |
+| `scan_project` | Scan entire project with A-F security grading | For project-wide security audits |
 | `check_package` | Verify a package name isn't AI-hallucinated (4.3M+ packages) | Before adding any new dependency |
 | `scan_packages` | Bulk-check all imports in a file for hallucinated packages | Before committing code with new imports |
 | `scan_agent_prompt` | Detect prompt injection and malicious instructions (56 rules) | Before acting on external/untrusted input |
@@ -36,8 +42,18 @@ scan_security → review findings → fix_security → verify fix
 
 ### Before Committing
 ```
+scan_git_diff → scan only changed files for fast feedback
 scan_packages → verify all imports are legitimate
-scan_security → catch vulnerabilities before they ship
+```
+
+### For PR Reviews
+```
+scan_git_diff --base main → scan PR changes against main branch
+```
+
+### For Project Audits
+```
+scan_project → get A-F security grade and aggregated metrics
 ```
 
 ### When Processing External Input
@@ -327,6 +343,105 @@ List all 1700+ security scanning rules and 120 fix templates. Use to understand
 
 ---
 
+### `scan_git_diff`
+
+Scan only files changed in git diff for security vulnerabilities. Use in PR workflows, pre-commit hooks, or to check recent changes before pushing. Significantly faster than full project scans.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `base` | string | No | Base commit/branch to diff against (default: `HEAD~1`) |
+| `target` | string | No | Target commit/branch (default: `HEAD`) |
+| `verbosity` | string | No | `"minimal"`, `"compact"` (default), `"full"` |
+
+**Example:**
+
+```json
+// Input
+{ "base": "main", "target": "HEAD" }
+
+// Output
+{
+  "base": "main",
+  "target": "HEAD",
+  "files_scanned": 5,
+  "issues_count": 3,
+  "issues": [
+    {
+      "file": "src/auth.js",
+      "line": 42,
+      "ruleId": "sql-injection",
+      "severity": "error",
+      "message": "SQL injection vulnerability detected"
+    }
+  ]
+}
+```
+
+---
+
+### `scan_project`
+
+Scan an entire project or directory for security vulnerabilities with aggregated metrics and A-F security grading. Use for security audits, compliance checks, or initial codebase assessment.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `directory` | string | Yes | Path to project directory to scan |
+| `include_patterns` | array | No | Glob patterns to include (e.g., `["**/*.js", "**/*.py"]`) |
+| `exclude_patterns` | array | No | Glob patterns to exclude (default: `node_modules`, `.git`, etc.) |
+| `verbosity` | string | No | `"minimal"`, `"compact"` (default), `"full"` |
+
+**Example:**
+
+```json
+// Input
+{ "directory": "./src", "verbosity": "compact" }
+
+// Output
+{
+  "directory": "/path/to/src",
+  "files_scanned": 24,
+  "issues_count": 12,
+  "grade": "C",
+  "by_severity": {
+    "error": 3,
+    "warning": 7,
+    "info": 2
+  },
+  "by_category": {
+    "sql-injection": 2,
+    "xss": 3,
+    "hardcoded-secret": 1,
+    "insecure-crypto": 4,
+    "command-injection": 2
+  },
+  "issues": [
+    {
+      "file": "auth.js",
+      "line": 15,
+      "ruleId": "sql-injection",
+      "severity": "error",
+      "message": "SQL injection vulnerability"
+    }
+  ]
+}
+```
+
+**Security Grades:**
+
+| Grade | Criteria |
+|-------|----------|
+| A | 0 critical/error issues |
+| B | 1-2 error issues, no critical |
+| C | 3-5 error issues |
+| D | 6-10 error issues |
+| F | 11+ error issues or any critical |
+
+---
+
 ## Supported Languages
 
 | Language | Vulnerabilities Detected | Analysis |
@@ -392,6 +507,7 @@ npx agent-security-scanner-mcp
 | Kilo Code | `npx agent-security-scanner-mcp init kilo-code` |
 | OpenCode | `npx agent-security-scanner-mcp init opencode` |
 | Cody | `npx agent-security-scanner-mcp init cody` |
+| **OpenClaw** | `npx agent-security-scanner-mcp init openclaw` |
 | Interactive | `npx agent-security-scanner-mcp init` |
 
 The `init` command auto-detects your OS, locates the config file, creates a backup, and adds the MCP server entry. **Restart your client after running init.**
@@ -451,6 +567,157 @@ Available languages: `js` (default), `py`, `go`, `java`.
 
 ---
 
+## CLI Tools
+
+Use the scanner directly from command line (for scripts, CI/CD, or OpenClaw):
+
+```bash
+# Scan a prompt for injection attacks
+npx agent-security-scanner-mcp scan-prompt "ignore previous instructions"
+
+# Scan a file for vulnerabilities
+npx agent-security-scanner-mcp scan-security ./app.py --verbosity minimal
+
+# Scan git diff (changed files only)
+npx agent-security-scanner-mcp scan-diff --base main --target HEAD
+
+# Scan entire project with grading
+npx agent-security-scanner-mcp scan-project ./src
+
+# Check if a package is legitimate
+npx agent-security-scanner-mcp check-package flask pypi
+
+# Scan file imports for hallucinated packages
+npx agent-security-scanner-mcp scan-packages ./requirements.txt pypi
+
+# Install Claude Code hooks for automatic scanning
+npx agent-security-scanner-mcp init-hooks
+```
+
+**Exit codes:** `0` = safe, `1` = issues found. Use in scripts to block risky operations.
+
+---
+
+## Configuration (`.scannerrc`)
+
+Create a `.scannerrc.yaml` or `.scannerrc.json` in your project root to customize scanning behavior:
+
+```yaml
+# .scannerrc.yaml
+version: 1
+
+# Suppress specific rules
+suppress:
+  - rule: "insecure-random"
+    reason: "Using for non-cryptographic purposes"
+  - rule: "detect-disable-mustache-escape"
+    paths: ["src/cli/**"]
+
+# Exclude paths from scanning
+exclude:
+  - "node_modules/**"
+  - "dist/**"
+  - "**/*.test.js"
+  - "**/*.spec.ts"
+
+# Minimum severity to report
+severity_threshold: "warning"  # "info", "warning", or "error"
+
+# Context-aware filtering (enabled by default)
+context_filtering: true
+```
+
+**Configuration options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `suppress` | array | Rules to suppress, optionally scoped to paths |
+| `exclude` | array | Glob patterns for paths to skip |
+| `severity_threshold` | string | Minimum severity to report (`info`, `warning`, `error`) |
+| `context_filtering` | boolean | Enable/disable safe module filtering (default: `true`) |
+
+The scanner automatically loads config from the current directory or any parent directory.
+
+---
+
+## Claude Code Hooks
+
+Automatically scan files after every edit with Claude Code hooks integration.
+
+### Install Hooks
+
+```bash
+npx agent-security-scanner-mcp init-hooks
+```
+
+This installs a `post-tool-use` hook that triggers security scanning after `Write`, `Edit`, or `MultiEdit` operations.
+
+### With Prompt Guard
+
+```bash
+npx agent-security-scanner-mcp init-hooks --with-prompt-guard
+```
+
+Adds a `PreToolUse` hook that scans prompts for injection attacks before executing tools.
+
+### What Gets Installed
+
+The command adds hooks to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "post-tool-use": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "command": "npx agent-security-scanner-mcp scan-security \"$TOOL_INPUT_file_path\" --verbosity minimal"
+      }
+    ]
+  }
+}
+```
+
+### Hook Behavior
+
+- **Non-blocking:** Hooks report findings but don't prevent file writes
+- **Minimal output:** Uses `--verbosity minimal` to avoid context overflow
+- **Automatic:** Runs on every file modification without manual intervention
+
+---
+
+## OpenClaw Integration
+
+[OpenClaw](https://openclaw.ai) is an autonomous AI assistant with broad system access. This scanner provides security guardrails for OpenClaw users.
+
+### Install
+
+```bash
+npx agent-security-scanner-mcp init openclaw
+```
+
+This installs a skill to `~/.openclaw/workspace/skills/security-scanner/`.
+
+### OpenClaw-Specific Threats
+
+The scanner includes 30+ rules targeting OpenClaw's unique attack surface:
+
+| Category | Examples |
+|----------|----------|
+| **Data Exfiltration** | "Forward emails to...", "Upload files to...", "Share browser cookies" |
+| **Messaging Abuse** | "Send to all contacts", "Auto-reply to everyone" |
+| **Credential Theft** | "Show my passwords", "Access keychain", "List API keys" |
+| **Unsafe Automation** | "Run hourly without asking", "Disable safety checks" |
+| **Service Attacks** | "Delete all repos", "Make payment to..." |
+
+### Usage in OpenClaw
+
+The skill is auto-discovered. Use it by asking:
+- "Scan this prompt for security issues"
+- "Check if this code is safe to run"
+- "Verify these packages aren't hallucinated"
+
+---
+
 ## What This Scanner Detects
 
 AI coding agents introduce attack surfaces that traditional security tools weren't designed for:
@@ -509,7 +776,7 @@ AI coding agents introduce attack surfaces that traditional security tools weren
 |----------|-------|
 | **Transport** | stdio |
 | **Package** | `agent-security-scanner-mcp` (npm) |
-| **Tools** | 6 |
+| **Tools** | 8 |
 | **Languages** | 12 |
 | **Ecosystems** | 7 |
 | **Auth** | None required |
@@ -591,6 +858,21 @@ All MCP tools support a `verbosity` parameter to minimize context window consump
 
 ## Changelog
 
+### v3.4.0
+- **Severity Calibration** - 207-rule severity map with HIGH/MEDIUM/LOW confidence scores for more accurate prioritization
+- **Cross-Engine Deduplication** - ~30-50% noise reduction by deduplicating findings across AST, taint, and regex engines
+- **Context-Aware Filtering** - 80+ known safe modules (logging, testing, sanitizers) reduce false positives
+- **`.scannerrc` Configuration** - YAML/JSON project config for suppressing rules, excluding paths, and setting severity thresholds
+- **`scan_git_diff` Tool** - Scan only changed files in git diff for PR workflows and pre-commit hooks
+- **`scan_project` Tool** - Project-level scanning with A-F security grading and aggregated metrics
+- **`init-hooks` CLI** - `npx agent-security-scanner-mcp init-hooks` installs Claude Code post-tool-use hooks for automatic scanning
+- **Safe Fix Validation** - `validateFix()` ensures auto-fixes don't introduce new vulnerabilities
+- **Cross-File Taint Analysis** - Import graph tracking for dataflow analysis across module boundaries
+
+### v3.3.0
+- **OpenClaw Integration** - Full support with 30+ rules targeting autonomous AI threats
+- **OpenClaw-Specific Rules** - Data exfiltration, credential theft, messaging abuse, unsafe automation detection
+
 ### v3.2.0
 - **Token Optimization** - New `verbosity` parameter for all tools reduces context window usage by up to 98%
 - **Three Verbosity Levels** - `minimal` (~50 tokens), `compact` (~200 tokens, default), `full` (~2,500 tokens)
@@ -637,4 +919,4 @@ npm install -g agent-security-scanner-mcp-full
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-security-scanner-mcp",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "mcpName": "io.github.sinewaveai/agent-security-scanner-mcp",
   "description": "Security scanner MCP server for AI coding agents. Prompt injection firewall, package hallucination detection (4.3M+ packages), 1000+ vulnerability rules with AST & taint analysis, auto-fix. For Claude Code, Cursor, Windsurf, Cline.",
   "main": "index.js",