# π Security Scanner MCP
Your **intelligent security partner** that automatically detects vulnerabilities in AI-generated code and suggests fixes.
[](https://www.npmjs.com/package/security-scanner-mcp)
[](https://www.npmjs.com/package/security-scanner-mcp)
[](https://ongjin.github.io/security-scanner-mcp)
**[English](#english)** | **[νκ΅μ΄](README.md)** | **[π Documentation](https://ongjin.github.io/security-scanner-mcp)**
## Demo
<!-- Add your demo GIF here -->
## Why do you need this?
Research shows that AI-generated code contains **322% more security vulnerabilities** than human-written code.
This MCP server goes beyond simple scanning:
- π‘ **Auto-generates fix suggestions** for vulnerabilities
- ποΈ **Scans IaC files** (Dockerfile, Kubernetes, Terraform)
- π **Creates Mermaid diagrams and SARIF reports** for visualization
- π³ **Runs safely in Docker sandbox** for isolation
**One scan before commit, one scan before deploy.** That's all you need.
## β¨ Key Features
### π― Code Security Scanning
| Tool | Description |
|------|-------------|
| `scan-security` | **Comprehensive security scan** - runs all checks at once |
| `scan-secrets` | Detect hardcoded API keys, passwords, and tokens |
| `scan-injection` | Find SQL/NoSQL/Command injection vulnerabilities |
| `scan-xss` | Identify Cross-Site Scripting risks |
| `scan-crypto` | Check cryptographic weaknesses (weak hashes, insecure random, etc.) |
| `scan-auth` | Audit authentication/session security (JWT, cookies, CORS) |
| `scan-path` | Find file/path vulnerabilities (Path Traversal, uploads, etc.) |
| `scan-dependencies` | Check for vulnerable dependencies in package.json |
### ποΈ Infrastructure as Code (IaC) Scanning
| Tool | Description |
|------|-------------|
| `scan-iac` | Security scanning for **Dockerfile, Kubernetes, Terraform** |
- **Dockerfile**: 15 rules based on CIS Docker Benchmark
- **Kubernetes**: 13 rules based on Pod Security Standards (PSS)
- **Terraform**: 15 rules for AWS/GCP/Azure security configurations
### π οΈ Auto-Fix & Advanced Features
| Tool | Description |
|------|-------------|
| `get-fix-suggestion` | **Auto-generate fixed code** for detected vulnerabilities |
| `generate-security-report` | Create comprehensive reports with **Mermaid diagrams + SARIF + CVE info** |
| `scan-in-sandbox` | Run scans safely in **Docker isolated environment** |
## Installation
### Install from npm (Recommended)
```bash
npm install -g security-scanner-mcp
```
### Or build from source
```bash
git clone https://github.com/ongjin/security-scanner-mcp.git
cd security-scanner-mcp
npm install && npm run build
```
## Register with Claude Code
```bash
# After global npm install
claude mcp add --scope project security-scanner -- security-scanner-mcp
# Or if built from source
claude mcp add --scope project security-scanner -- node /path/to/security-scanner-mcp/dist/index.js
```
## Quick Setup (Auto-approve tools)
If you find it tedious to approve tool usage every time, set up auto-approval:
### π₯οΈ Claude Desktop App Users
1. Restart the Claude app.
2. Ask a question that uses the `security-scanner` tool.
3. When the notification appears, check **"Always allow requests from this server"** and click **Allow**.
(You won't be asked again.)
### β¨οΈ Claude Code (CLI) Users
If you're using the terminal environment (`claude` command), use permission management commands:
1. Run `claude` in your terminal.
2. Type `/permissions` in the prompt and press Enter.
3. Select **Global Permissions** (or Project Permissions) > **Allowed Tools**.
4. Enter `mcp__security-scanner__scan-security` for just the main tool, or `mcp__security-scanner__*` to allow all tools.
> π‘ **Tip**: In most cases, allowing **`scan-security`** alone is sufficient, as it performs all security checks in one go.
## Usage Examples
### π Basic Code Scan
```
Me: Scan this code for security issues
const apiKey = "AIzaSyC1234567890abcdef";
const query = `SELECT * FROM users WHERE id = ${userId}`;
element.innerHTML = userInput;
Claude: [calls scan-security]
## β οΈ Security Vulnerabilities Found!
### π΄ Critical (1 issue)
- **Google API Key** (line 1)
- Google API Key is hardcoded in the source code
- π‘ Fix: Use environment variables and set API key restrictions
### π High (2 issues)
- **Template Literal SQL** (line 2)
- SQL query uses template literals with variables
- π‘ Fix: Use prepared statements
- **innerHTML Assignment** (line 3)
- Dynamic value assigned to innerHTML
- π‘ Fix: Use textContent or sanitize with DOMPurify
```
### π οΈ Get Auto-Fix Suggestions
```
Me: Show me how to fix the innerHTML vulnerability
Claude: [calls get-fix-suggestion]
## β
Fixed Code
// β Before (vulnerable)
element.innerHTML = userInput;
// β
After (safe)
element.textContent = userInput;
// Or if HTML is needed:
import DOMPurify from 'dompurify';
element.innerHTML = DOMPurify.sanitize(userInput);
```
### ποΈ IaC File Scanning
```
Me: Scan my Dockerfile for security issues
Claude: [calls scan-iac]
## π³ Dockerfile Security Vulnerabilities Found!
### π΄ Critical (2 issues)
- **DOC001**: Running as root user
- π‘ Fix: Set non-root user with USER command
- **DOC005**: Hardcoded secrets
- π‘ Fix: Use ARG and build secrets
### π High (3 issues)
- **DOC002**: Using latest tag
- π‘ Fix: Use explicit version tags (e.g., node:20-alpine)
...
```
### π Generate Comprehensive Report
```
Me: Show me a full security report with Mermaid diagrams
Claude: [calls generate-security-report]
# π‘οΈ Security Scan Dashboard
## π Overall Summary
**8 vulnerabilities** found in total.
## π― Severity Distribution
```mermaid
pie title Vulnerability Distribution by Severity
"π΄ Critical" : 2
"π High" : 3
"π‘ Medium" : 2
"π’ Low" : 1
\```
## βοΈ Potential Attack Scenarios
```mermaid
flowchart TD
Start([Attacker]) --> Recon[Reconnaissance]
Recon --> Secrets[Hardcoded<br/>Secrets Found]
Secrets --> Access[Bypass Auth]
...
\```
+ SARIF Report (GitHub Code Scanning compatible)
+ CVE/OWASP detailed information
```
### π³ Sandbox Scanning
```
Me: Scan this code safely in a sandbox
Claude: [calls scan-in-sandbox]
## π³ Sandbox Scan Results
β
**Scan Complete**
### π Sandbox Configuration
- **Memory Limit**: 512MB
- **CPU Limit**: 0.5 cores
- **Timeout**: 30000ms
- **Network**: Disabled
- **Privileges**: Minimal
```
## Detected Vulnerabilities
### π Hardcoded Secrets
- AWS Access Key / Secret Key
- Google API Key / OAuth Secret
- GitHub Token / Slack Token
- Database Connection Strings
- Private Keys (RSA, EC, etc.)
- JWT Tokens
- Kakao / Naver API Keys
- Stripe / Twilio API Keys
### π Injection Attacks
- SQL Injection (string concatenation, template literals)
- NoSQL Injection (MongoDB)
- Command Injection (exec, spawn)
- LDAP Injection
### π Cross-Site Scripting (XSS)
- dangerouslySetInnerHTML (React)
- innerHTML / outerHTML
- jQuery .html() / Vue v-html
- eval() / new Function()
- document.write()
### π Cryptographic Issues
- Weak hashing (MD5, SHA1)
- Insecure random (Math.random)
- Hardcoded encryption keys/IVs
- SSL certificate validation disabled
- Vulnerable TLS versions (1.0, 1.1)
### π Authentication & Sessions
- JWT misconfigurations (none algorithm, no expiration)
- Insecure cookie settings
- CORS wildcards
- Weak password policies
### π File & Path Issues
- Path Traversal
- Dangerous file deletions
- Insecure file uploads
- Zip Slip (Java)
- Pickle deserialization (Python)
### ποΈ Infrastructure as Code
**Dockerfile** (CIS Docker Benchmark):
- Running as root
- Hardcoded secrets
- Using latest tags
- Unnecessary port exposure
- Missing health checks
**Kubernetes** (Pod Security Standards):
- Privileged containers
- Root execution
- Host network/PID/IPC usage
- Dangerous capability additions
- Missing resource limits
**Terraform** (Multi-Cloud):
- Public IP assignment
- Encryption disabled
- Firewall open to all (0.0.0.0/0)
- Publicly accessible resources
### π¦ Vulnerable Dependencies
- npm audit integration
- Python requirements.txt scanning
- Go go.mod scanning
## Supported Languages
- β
JavaScript / TypeScript
- β
Python
- β
Java
- β
Go
- β
Dockerfile
- β
Kubernetes YAML
- β
Terraform HCL
## π¨ Report Formats
- **Markdown**: Human-readable text reports
- **Mermaid**: Visual diagrams (Pie, Bar, Flowchart)
- **SARIF**: GitHub Code Scanning / VS Code compatible format
- **CVE Enrichment**: NVD database integration
- **OWASP Mapping**: OWASP Top 10:2021 + CWE mapping
## π³ Docker Sandbox
Protect your host system from potentially malicious code by running scans in an isolated Docker environment.
### Prepare Docker Image
#### Pull from Docker Hub (Recommended)
```bash
# Download pre-built image (includes Trivy, GitLeaks, Checkov)
docker pull ongjin/security-scanner-mcp:latest
docker tag ongjin/security-scanner-mcp:latest security-scanner-mcp:latest
```
**Included External Security Tools**:
- Trivy v0.50.4 - Container/IaC vulnerability scanner
- GitLeaks v8.18.4 - Secret detection
- Checkov - Infrastructure as Code security scanner
#### Build from Source (Optional)
```bash
npm run docker:build
```
> Note: Building takes 5-10 minutes and the image size is approximately 500MB.
### Run Sandbox Scan
From Claude Code:
```
scan-in-sandbox invocation
```
**Security Settings**:
- Memory limit: 128MB ~ 2GB
- CPU limit: 0.1 ~ 2.0 cores
- Timeout: 5s ~ 5min
- Network: Disabled by default
- Filesystem: Read-only
- Privileges: Minimal (no-new-privileges, drop all capabilities)
## Demo
```bash
# Run demo
npm run demo
```
## Architecture
```
src/
βββ index.ts # MCP server (12 tools)
βββ scanners/ # Code scanners (8)
β βββ secrets.ts
β βββ injection.ts
β βββ xss.ts
β βββ ...
βββ iac-scanners/ # IaC scanners (3)
β βββ dockerfile.ts # 15 rules
β βββ kubernetes.ts # 13 rules
β βββ terraform.ts # 15 rules
βββ remediation/ # Auto-fix
β βββ code-fixer.ts # AST-based code transformation
β βββ templates/ # Fix templates
βββ reporting/ # Reporting
β βββ mermaid-generator.ts # Diagram generation
β βββ sarif-generator.ts # SARIF format
β βββ markdown-formatter.ts
βββ external/ # External APIs
β βββ cve-lookup.ts # NVD API integration
β βββ owasp-database.ts # OWASP Top 10 DB
βββ sandbox/ # Sandbox
βββ docker-manager.ts # Docker execution management
```
## π₯οΈ CLI Mode (CI/CD Integration)
Run the scanner independently without Claude. Works with Jenkins, GitHub Actions, GitLab CI, and any CI/CD platform.
### Basic Usage
```bash
# Scan a file
npx security-scanner-mcp scan ./src/app.js
# Scan a directory
npx security-scanner-mcp scan ./src
# Save results to file
npx security-scanner-mcp scan ./src --output report.txt
```
### Output Formats
```bash
# JSON format (for parsing)
npx security-scanner-mcp scan ./src --format json
# SARIF format (GitHub Code Scanning compatible)
npx security-scanner-mcp scan ./src --format sarif --output report.sarif
```
### CI/CD Options
```bash
# Fail build on critical vulnerabilities (exit code 1)
npx security-scanner-mcp scan ./src --fail-on critical
# Fail build on high or above
npx security-scanner-mcp scan ./src --fail-on high
# Include specific files only
npx security-scanner-mcp scan ./src --include "*.ts,*.js"
# Exclude specific folders
npx security-scanner-mcp scan ./src --exclude "node_modules,dist,test"
```
### Jenkins Example
```groovy
pipeline {
agent any
stages {
stage('Security Scan') {
steps {
sh 'npx security-scanner-mcp scan ./src --format json --output security-report.json --fail-on high'
}
}
}
post {
always {
archiveArtifacts artifacts: 'security-report.json', fingerprint: true
}
}
}
```
### GitHub Actions Example
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Security Scan
run: npx security-scanner-mcp scan ./src --format sarif --output results.sarif --fail-on critical
- name: Upload SARIF to GitHub
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: results.sarif
```
### GitLab CI Example
```yaml
security_scan:
stage: test
script:
- npx security-scanner-mcp scan ./src --format json --output gl-security-report.json --fail-on high
artifacts:
reports:
security: gl-security-report.json
```
## Roadmap
- [x] OWASP Top 10 based scanning
- [x] Multi-language support (JS/TS/Python/Java/Go)
- [x] IaC scanning (Dockerfile, Kubernetes, Terraform)
- [x] Auto-fix suggestions (AST-based)
- [x] Advanced reporting (Mermaid, SARIF)
- [x] External vulnerability DB integration (NVD, OWASP)
- [x] Docker sandbox execution
- [x] CLI mode (CI/CD pipeline integration)
- [ ] GitHub Actions Marketplace
- [ ] VS Code extension
## Contributing
PRs are welcome! We're especially interested in:
- New security pattern additions
- Support for additional languages (Rust, C#, PHP, etc.)
- IaC rule expansion (Ansible, CloudFormation, etc.)
- Documentation improvements
## License
MIT
---
Made with β€οΈ by zerry
**Beyond simple scanning, your intelligent security partner.**
