agent-security-scanner-mcp 1.5.0 → 2.0.0

package/README.md

@@ -2,15 +2,40 @@
 
 A powerful MCP (Model Context Protocol) server for real-time security vulnerability scanning. Integrates with Claude Desktop, Claude Code, OpenCode.ai, Kilo Code, and any MCP-compatible client to automatically detect and fix security issues as you code.
 
-[![npm version](https://img.shields.io/npm/v/agent-security-scanner-mcp)](https://www.npmjs.com/package/agent-security-scanner-mcp)
-[![Downloads](https://img.shields.io/npm/dm/agent-security-scanner-mcp)](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)
+AI coding agents like **Claude Code**, **Cursor**, **Windsurf**, **Cline**, **Copilot**, and **Devin** are transforming software development. But they introduce attack surfaces that traditional security tools weren't designed to handle:
 
-**275+ Semgrep-aligned security rules** | **105 auto-fix templates** | **1M+ packages indexed** | **AI Agent prompt security**
+- **Prompt Injection** – Malicious instructions hidden in codebases hijack your AI agent
+- **Package Hallucination** – AI invents package names that attackers register as malware
+- **Data Exfiltration** – Compromised agents silently leak secrets to external servers
+- **Backdoor Insertion** – Manipulated agents inject vulnerabilities into your code
 
----
+**agent-security-scanner-mcp** is the first security scanner purpose-built for the agentic era. It protects AI coding agents in real-time via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+
+**275+ Semgrep-aligned security rules | 105 auto-fix templates | 1M+ packages indexed | AI Agent prompt security**
+
+## What's New in v2.0.0
+
+- **AST-based analysis** - tree-sitter powered parsing for 12 languages with higher accuracy
+- **Taint analysis** - Track data flow from sources (user input) to sinks (dangerous functions)
+- **Graceful fallback** - Works out-of-the-box with regex; enhanced detection when tree-sitter installed
+- **Metavariable patterns** - Semgrep-style `$VAR` patterns for structural matching
+- **Doctor command upgrade** - Now checks for AST engine availability
+
+### Enhanced Detection with tree-sitter (Optional)
+
+For maximum detection accuracy, install the AST engine:
+
+```bash
+pip install tree-sitter tree-sitter-python tree-sitter-javascript
+```
 
-## What's New in v1.4.5
+The scanner works without tree-sitter using regex-based detection, but AST analysis provides:
+- Fewer false positives through structural understanding
+- Taint tracking across function boundaries
+- Language-aware pattern matching
+
+## What's New in v1.5.0
 
 - **92% smaller package** - Only 2.7 MB (down from 84 MB)
 - **6 ecosystems included** - PyPI, RubyGems, crates.io, pub.dev, CPAN, raku.land
@@ -33,8 +58,6 @@ A powerful MCP (Model Context Protocol) server for real-time security vulnerabil
 - **Terraform support** - AWS S3, IAM, RDS, security groups, CloudTrail
 - **Kubernetes support** - Privileged containers, RBAC, network policies, secrets
 
----
-
 ## Features
 
 - **Real-time scanning** - Detect vulnerabilities instantly as you write code
@@ -44,8 +67,6 @@ A powerful MCP (Model Context Protocol) server for real-time security vulnerabil
 - **CWE & OWASP mapped** - Every rule includes CWE and OWASP references
 - **Hallucination detection** - Detect AI-invented package names across 7 ecosystems (4.3M+ packages)
 
----
-
 ## Installation
 
 ### Default Package (Lightweight - 2.7 MB)
@@ -70,12 +91,26 @@ Or run directly with npx:
 npx agent-security-scanner-mcp
 ```
 
-### Requirements
+## Requirements
 
 - Node.js >= 18.0.0
 - Python 3.x (for the analyzer engine)
-
----
+- tree-sitter (optional, for enhanced AST-based detection)
+
+## Works With All Major AI Coding Tools
+
+| Tool | Integration | Status |
+|------|-------------|--------|
+| **Claude Desktop** | Native MCP | ✅ Full Support |
+| **Claude Code** | Native MCP | ✅ Full Support |
+| **Cursor** | MCP Server | ✅ Full Support |
+| **Windsurf** | MCP Server | ✅ Full Support |
+| **Cline** | MCP Server | ✅ Full Support |
+| **Kilo Code** | MCP Server | ✅ Full Support |
+| **OpenCode** | MCP Server | ✅ Full Support |
+| **Cody** | MCP Server | ✅ Full Support |
+| **Zed** | MCP Server | ✅ Full Support |
+| **Any MCP Client** | MCP Protocol | ✅ Compatible |
 
 ## Quick Start
 
@@ -90,13 +125,13 @@ npx agent-security-scanner-mcp init <client>
 **Examples:**
 
 ```bash
-npx agent-security-scanner-mcp init claude-desktop
-npx agent-security-scanner-mcp init claude-code
-npx agent-security-scanner-mcp init opencode
-npx agent-security-scanner-mcp init kilo-code
 npx agent-security-scanner-mcp init cursor
+npx agent-security-scanner-mcp init claude-desktop
 npx agent-security-scanner-mcp init windsurf
 npx agent-security-scanner-mcp init cline
+npx agent-security-scanner-mcp init claude-code
+npx agent-security-scanner-mcp init kilo-code
+npx agent-security-scanner-mcp init opencode
 npx agent-security-scanner-mcp init cody
 ```
 
@@ -116,7 +151,7 @@ The init command auto-detects your OS, locates the config file, creates a timest
 | `--yes`, `-y` | Skip prompts, use safe defaults |
 | `--force` | Overwrite existing entry if present |
 | `--path <file>` | Override the config file path |
-| `--name <key>` | Custom server key name (default: `security-scanner`) |
+| `--name <key>` | Custom server key name (default: `agentic-security`) |
 
 **Advanced examples:**
 
@@ -131,19 +166,42 @@ npx agent-security-scanner-mcp init cline --force
 npx agent-security-scanner-mcp init claude-desktop --path ~/my-config.json --name my-scanner
 ```
 
-#### Safety
+### Diagnose Your Setup
 
-- Never deletes anything — only adds or updates entries
-- Always creates a timestamped backup before modifying (e.g., `config.json.bak-20250204-143022`)
-- Stops with a clear error if the config file contains invalid JSON
-- Shows a diff and asks for confirmation if an existing entry differs
-- Supports `--dry-run` to inspect changes before applying
+Check your environment and all client configurations:
 
----
+```bash
+npx agent-security-scanner-mcp doctor
+```
+
+Checks Node.js version, Python availability, analyzer engine, and scans all client configs for issues. Auto-fix trivial problems with `--fix`:
+
+```bash
+npx agent-security-scanner-mcp doctor --fix
+```
+
+### Try It Now
+
+Generate a vulnerable demo file and scan it instantly:
+
+```bash
+npx agent-security-scanner-mcp demo
+```
+
+Supports multiple languages:
+
+```bash
+npx agent-security-scanner-mcp demo --lang js    # JavaScript (default)
+npx agent-security-scanner-mcp demo --lang py    # Python
+npx agent-security-scanner-mcp demo --lang go    # Go
+npx agent-security-scanner-mcp demo --lang java  # Java
+```
+
+Creates a small file with 3 intentional vulnerabilities, runs the scanner, shows findings with CWE/OWASP references, and asks if you want to keep the file for testing.
 
-## Configuration
+---
 
-> **Tip:** Use `npx agent-security-scanner-mcp init <client>` for automatic setup instead of manual configuration below.
+## Manual Configuration
 
 ### Claude Desktop
 
@@ -161,7 +219,6 @@ Add to your `claude_desktop_config.json`:
 ```
 
 **Config file locations:**
-
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
@@ -243,9 +300,7 @@ Or if installed globally:
 }
 ```
 
-### Windows Users
-
-Use the cmd wrapper:
+**Windows users** - Use cmd wrapper:
 
 ```json
 {
@@ -258,8 +313,6 @@ Use the cmd wrapper:
 }
 ```
 
----
-
 ## Available Tools
 
 ### `scan_security`
@@ -279,7 +332,6 @@ Returns:
 ```
 
 **Example output:**
-
 ```json
 {
   "file": "/path/to/file.js",
@@ -359,7 +411,6 @@ Returns:
 | NONE | 0-24 | ALLOW |
 
 **Example - Malicious prompt (BLOCKED):**
-
 ```json
 {
   "action": "BLOCK",
@@ -385,7 +436,6 @@ Returns:
 ```
 
 **Example - Safe prompt (ALLOWED):**
-
 ```json
 {
   "action": "ALLOW",
@@ -400,7 +450,7 @@ Returns:
 **Attack Categories Detected (56 rules):**
 
 | Category | Rules | Examples |
-|----------|-------|---------|
+|----------|-------|----------|
 | Exfiltration | 10 | Send code to webhook, read .env files, push to external repo |
 | Malicious Injection | 11 | Add backdoor, create reverse shell, disable authentication |
 | System Manipulation | 9 | rm -rf /, modify /etc/passwd, add cron persistence |
@@ -417,7 +467,7 @@ Detect AI-hallucinated package names that don't exist in official registries. Pr
 **4,346,531 packages indexed across 7 ecosystems:**
 
 | Ecosystem | Packages | Registry | Source Dataset |
-|-----------|----------|----------|---------------|
+|-----------|----------|----------|----------------|
 | npm | 3,329,177 | npmjs.com | garak-llm/npm-20241031 |
 | PyPI | 554,762 | pypi.org | garak-llm/pypi-20241031 |
 | RubyGems | 180,693 | rubygems.org | garak-llm/rubygems-20241031 |
@@ -443,7 +493,6 @@ Returns:
 ```
 
 **Example:**
-
 ```json
 {
   "package": "flutter_animations",
@@ -472,7 +521,6 @@ Returns:
 ```
 
 **Example output:**
-
 ```json
 {
   "file": "/path/to/main.dart",
@@ -482,7 +530,7 @@ Returns:
   "hallucinated_count": 1,
   "hallucinated_packages": ["fake_flutter_pkg"],
   "legitimate_packages": ["flutter", "http", "provider", "shared_preferences"],
-  "recommendation": "Found 1 potentially hallucinated package(s): fake_flutter_pkg"
+  "recommendation": "⚠️ Found 1 potentially hallucinated package(s): fake_flutter_pkg"
 }
 ```
 
@@ -509,7 +557,7 @@ Show statistics about loaded package lists.
 
 Add your own package lists to `packages/` directory:
 
-```
+```bash
 # Format: one package name per line
 packages/
 ├── npm.txt       # 3,329,177 packages (JavaScript)
@@ -533,14 +581,14 @@ python scripts/fetch-garak-packages.py
 Package lists are sourced from [garak-llm](https://huggingface.co/garak-llm) Hugging Face datasets:
 
 | Ecosystem | Dataset | Snapshot Date |
-|-----------|---------|--------------|
-| npm | garak-llm/npm-20241031 | Oct 31, 2024 |
-| PyPI | garak-llm/pypi-20241031 | Oct 31, 2024 |
-| RubyGems | garak-llm/rubygems-20241031 | Oct 31, 2024 |
-| crates.io | garak-llm/crates-20250307 | Mar 7, 2025 |
-| Dart | garak-llm/dart-20250811 | Aug 11, 2025 |
-| Perl | garak-llm/perl-20250811 | Aug 11, 2025 |
-| Raku | garak-llm/raku-20250811 | Aug 11, 2025 |
+|-----------|---------|---------------|
+| npm | [garak-llm/npm-20241031](https://huggingface.co/datasets/garak-llm/npm-20241031) | Oct 31, 2024 |
+| PyPI | [garak-llm/pypi-20241031](https://huggingface.co/datasets/garak-llm/pypi-20241031) | Oct 31, 2024 |
+| RubyGems | [garak-llm/rubygems-20241031](https://huggingface.co/datasets/garak-llm/rubygems-20241031) | Oct 31, 2024 |
+| crates.io | [garak-llm/crates-20250307](https://huggingface.co/datasets/garak-llm/crates-20250307) | Mar 7, 2025 |
+| Dart | [garak-llm/dart-20250811](https://huggingface.co/datasets/garak-llm/dart-20250811) | Aug 11, 2025 |
+| Perl | [garak-llm/perl-20250811](https://huggingface.co/datasets/garak-llm/perl-20250811) | Aug 11, 2025 |
+| Raku | [garak-llm/raku-20250811](https://huggingface.co/datasets/garak-llm/raku-20250811) | Aug 11, 2025 |
 
 ---
 
@@ -549,41 +597,41 @@ Package lists are sourced from [garak-llm](https://huggingface.co/garak-llm) Hug
 ### By Language
 
 | Language | Rules | Categories |
-|----------|-------|-----------|
+|----------|-------|------------|
 | JavaScript/TypeScript | 31 | XSS, injection, secrets, crypto |
 | Python | 36 | Injection, deserialization, crypto, XXE |
 | Java | 27 | Injection, XXE, crypto, deserialization |
 | Go | 22 | Injection, crypto, race conditions |
-| PHP | 25 | SQL injection, XSS, command injection, deserialization |
-| Ruby/Rails | 25 | Mass assignment, CSRF, eval, YAML deserialization |
-| C/C++ | 25 | Buffer overflow, format string, memory safety |
-| Terraform/K8s | 35 | AWS misconfig, IAM, privileged containers, RBAC |
+| **PHP** | 25 | SQL injection, XSS, command injection, deserialization |
+| **Ruby/Rails** | 25 | Mass assignment, CSRF, eval, YAML deserialization |
+| **C/C++** | 25 | Buffer overflow, format string, memory safety |
+| **Terraform/K8s** | 35 | AWS misconfig, IAM, privileged containers, RBAC |
 | Dockerfile | 18 | Secrets, permissions, best practices |
 | Generic (Secrets) | 31 | API keys, tokens, passwords |
 
 ### By Category
 
 | Category | Rules | Auto-Fix |
-|----------|-------|---------|
-| Injection (SQL, Command, XSS) | 55 | Yes |
-| Hardcoded Secrets | 50 | Yes |
-| Weak Cryptography | 25 | Yes |
-| Insecure Deserialization | 18 | Yes |
-| Memory Safety (C/C++) | 20 | Yes |
-| Infrastructure as Code | 35 | Yes |
-| Path Traversal | 10 | Yes |
-| SSRF | 8 | Yes |
-| XXE | 8 | Yes |
-| SSL/TLS Issues | 12 | Yes |
-| CSRF | 6 | Yes |
-| Other | 28 | Yes |
-
-### Auto-Fix Templates (105 total)
+|----------|-------|----------|
+| **Injection (SQL, Command, XSS)** | 55 | Yes |
+| **Hardcoded Secrets** | 50 | Yes |
+| **Weak Cryptography** | 25 | Yes |
+| **Insecure Deserialization** | 18 | Yes |
+| **Memory Safety (C/C++)** | 20 | Yes |
+| **Infrastructure as Code** | 35 | Yes |
+| **Path Traversal** | 10 | Yes |
+| **SSRF** | 8 | Yes |
+| **XXE** | 8 | Yes |
+| **SSL/TLS Issues** | 12 | Yes |
+| **CSRF** | 6 | Yes |
+| **Other** | 28 | Yes |
+
+## Auto-Fix Templates (105 total)
 
 Every detected vulnerability includes an automatic fix suggestion:
 
 | Vulnerability | Fix Strategy |
-|--------------|-------------|
+|--------------|--------------|
 | SQL Injection | Parameterized queries with placeholders |
 | XSS (innerHTML) | Replace with `textContent` or DOMPurify |
 | Command Injection | Use `execFile()` / `spawn()` with `shell: false` |
@@ -595,8 +643,6 @@ Every detected vulnerability includes an automatic fix suggestion:
 | Eval/Exec | Remove or use safer alternatives |
 | CORS Wildcard | Specify allowed origins |
 
----
-
 ## Example Usage
 
 ### Scanning a file
@@ -604,7 +650,6 @@ Every detected vulnerability includes an automatic fix suggestion:
 Ask Claude: *"Scan my app.js file for security issues"*
 
 Claude will use `scan_security` and return:
-
 - All vulnerabilities found
 - Severity levels
 - CWE/OWASP references
@@ -615,17 +660,13 @@ Claude will use `scan_security` and return:
 Ask Claude: *"Fix all security issues in app.js"*
 
 Claude will use `fix_security` to:
-
 - Apply all available auto-fixes
 - Return the secured code
 - List all changes made
 
----
-
 ## Supported Vulnerabilities
 
 ### Injection
-
 - SQL Injection (multiple databases)
 - NoSQL Injection (MongoDB)
 - Command Injection (exec, spawn, subprocess)
@@ -635,7 +676,6 @@ Claude will use `fix_security` to:
 - Template Injection (Jinja2, SpEL)
 
 ### Secrets & Credentials
-
 - AWS Access Keys & Secret Keys
 - GitHub Tokens (PAT, OAuth, App)
 - Stripe API Keys
@@ -647,7 +687,6 @@ Claude will use `fix_security` to:
 - 25+ more token types
 
 ### Cryptography
-
 - Weak Hashing (MD5, SHA1)
 - Weak Ciphers (DES, RC4)
 - ECB Mode Usage
@@ -656,7 +695,6 @@ Claude will use `fix_security` to:
 - Weak TLS Versions
 
 ### Deserialization
-
 - Python pickle/marshal/shelve
 - YAML unsafe load
 - Java ObjectInputStream
@@ -664,7 +702,6 @@ Claude will use `fix_security` to:
 - Go gob decode
 
 ### Network & SSL
-
 - SSL Verification Disabled
 - Certificate Validation Bypass
 - SSRF Vulnerabilities
@@ -672,7 +709,6 @@ Claude will use `fix_security` to:
 - CORS Misconfiguration
 
 ### Memory Safety (C/C++)
-
 - Buffer Overflow (strcpy, strcat, sprintf, gets)
 - Format String Vulnerabilities
 - Use-After-Free
@@ -682,7 +718,6 @@ Claude will use `fix_security` to:
 - Unsafe temp files (mktemp, tmpnam)
 
 ### Infrastructure as Code
-
 - AWS S3 Public Access
 - Security Groups Open to World (SSH, RDP)
 - IAM Admin Policies (Action:*, Resource:*)
@@ -698,7 +733,6 @@ Claude will use `fix_security` to:
 - Cluster Admin Bindings
 
 ### Other
-
 - Path Traversal
 - XXE (XML External Entities)
 - CSRF Disabled
@@ -710,12 +744,6 @@ Claude will use `fix_security` to:
 - Mass Assignment (Rails)
 - Unsafe Eval/Constantize
 
----
-
-## Contributing
-
-Contributions welcome! Please see our [GitHub repository](https://github.com/sinewaveai/agent-security-layer-fork).
-
 ### Adding New Rules
 
 Rules are defined in YAML format in the `rules/` directory:
@@ -732,22 +760,16 @@ Rules are defined in YAML format in the `rules/` directory:
     owasp: "Category"
 ```
 
----
-
-## License
-
-MIT
+## Feedback & Support
 
----
+We welcome your feedback!
 
-## Links
+- 🐛 **Bug Reports:** [Report issues](https://github.com/sinewaveai/agent-security-scanner-mcp/issues)
+- 💡 **Feature Requests:** [Request features](https://github.com/sinewaveai/agent-security-scanner-mcp/issues)
+- 💬 **Questions:** [Ask questions](https://github.com/sinewaveai/agent-security-scanner-mcp/issues)
 
-- **npm:** https://www.npmjs.com/package/agent-security-scanner-mcp
-- **GitHub:** https://github.com/sinewaveai/agent-security-layer-fork
-- **Issues:** https://github.com/sinewaveai/agent-security-layer-fork/issues
+We actively monitor issues and prioritize based on community feedback.
 
----
-
-## Keywords
+## License
 
-mcp, model-context-protocol, claude, opencode, kilocode, security, scanner, vulnerability, sast, code-analysis, sql-injection, xss, secrets-detection, hallucination-detection, package-verification, supply-chain-security, prompt-injection, agent-security, llm-security, ai-safety, claude-desktop, claude-code, mcp-server, cursor, cody, cline, windsurf, agentic, devin, owasp, cwe, semgrep
+MIT