ai-security-mcp 1.0.32
Thin client MCP server for AI Security Scanner - connects to cloud-hosted 27 agents (100% OWASP coverage)
Requires Python: >=3.10
Keywords: security, ai, agentic, llm, owasp, vulnerability, scanner, mcp, claude, claude-code, agent, multi-agent, asi, prompt-injection, cybersecurity, devsecops, static-analysis, security-testing

# AI Security Scanner MCP - Cloud Edition

World's first comprehensive agentic AI security scanner with 27 specialized
agents covering 100% OWASP ASI + LLM vulnerabilities. This thin client
connects to our secure cloud infrastructure where all scanning happens.

**Current Version**: 1.0.31 | **Python**: >=3.10 | **Package Size**: ~50KB

## 🏗️ Architecture

This package is a **lightweight cloud proxy** (~50KB) that connects Claude Code
to our cloud-hosted security scanning infrastructure. All 27 security agents
run in our secure Google Cloud environment, not on your local machine.

**Benefits of Cloud Architecture**:
- Always up-to-date security rules
- No local compute resources needed
- Proprietary agent logic protected
- Consistent scanning environment
- Sub-second scan execution
- **NEW**: Automatic report file generation

## 🚀 Quick Start

### Step 1: Get Your API Key

1. Visit [https://app.ai-threat-scanner.com/dashboard/api-keys](https://app.ai-threat-scanner.com/dashboard/api-keys)
2. Sign up for free account
3. Generate new API key
4. Copy your key (format: `ciso_live_abc123xyz`)

### Step 2: Install Thin Client (uvx recommended)

**Recommended: Use uvx** (no installation required):
```bash
claude mcp add ai-security-scanner \
  -e AI_SECURITY_API_KEY=ciso_live_abc123xyz \
  -- uvx --python=3.12 ai-security-mcp@1.0.31
```

**Alternative: Traditional pip install**:
```bash
pip install ai-security-mcp==1.0.31
claude mcp add ai-security-scanner \
  -e AI_SECURITY_API_KEY=ciso_live_abc123xyz \
  -- ai-security-mcp
```

Replace `ciso_live_abc123xyz` with your actual API key.

### Step 3: Start Scanning

Open Claude Code and ask:
```
Scan this repository for AI security vulnerabilities
```

The thin client will connect to our cloud infrastructure, execute all 27
security agents, and return comprehensive vulnerability findings.

**Reports are automatically saved** to `AIThreatScannerReports/{repository}/` with:
- Agentic Security Report (vulnerability findings)
- Comprehensive Analysis (detailed context)
- Coverage Report (OWASP testing metrics)
- Scan Summary (JSON format)

## 📋 Complete Setup Example (macOS)

This example walks through the complete setup process from scratch:

```bash
# 1. Install uvx (if not already installed)
pip install uv

# 2. Get your API key from https://app.ai-threat-scanner.com/dashboard/api-keys
# (Sign up for free account if needed)

# 3. Configure Claude desktop MCP server
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json <<'EOF'
{
  "mcpServers": {
    "ai-security-scanner": {
      "command": "/Users/$(whoami)/.local/bin/uvx",
      "args": ["--python=3.12", "ai-security-mcp@1.0.31"],
      "env": {
        "AI_SECURITY_API_KEY": "your_api_key_here",
        "AI_SECURITY_MCP_URL": "https://ciso-mcp-server-production.up.railway.app/api/tools/call"
      }
    }
  }
}
EOF

# 4. Replace "your_api_key_here" with your actual API key
# Edit the file and update the API key:
# open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 5. Restart Claude to load the MCP server
killall Claude && sleep 3 && open -a Claude

# 6. Verify MCP server is running (wait ~10 seconds after Claude starts)
ps aux | grep "ai-security-mcp"
# Expected output: Shows uvx running ai-security-mcp@1.0.31

# 7. In Claude, ask: "Scan this repository for AI security vulnerabilities"

# 8. After scan completes, check for report files
ls -lh AIThreatScannerReports/
# Expected: Directory with subdirectories for each scanned repository

# Example output after scanning a repo named "my-app":
# AIThreatScannerReports/my-app/
#   ├── AgenticSecurityReport_20251028_143022_abc123.md
#   ├── ComprehensiveAnalysis_20251028_143022_abc123.md
#   ├── CoverageReport_20251028_143022_abc123.md
#   └── ScanSummary_20251028_143022_abc123.json
```

**Verification checklist:**
- ✅ uvx installed (`which uvx`)
- ✅ Config file has valid JSON syntax
- ✅ API key format: `ciso_live_...`
- ✅ MCP server process running (`ps aux | grep ai-security-mcp`)
- ✅ Claude shows AI Security Scanner in MCP menu
- ✅ Scan completes and shows results
- ✅ Report files created in AIThreatScannerReports/

## 📊 What You Get

### 27 Cloud-Hosted Security Agents

**OWASP ASI (17 agents)**: Memory Poisoning, Tool Misuse, Privilege Compromise,
Resource Overload, Cascading Hallucination, Intent Breaking, Misaligned Behaviors,
Repudiation, Identity Spoofing, Overwhelming HITL, Unexpected RCE, Agent
Communication Poisoning, Rogue Agents, Human Attacks, Human Manipulation,
Insecure Protocol, Supply Chain

**OWASP LLM Top 10 (10 agents)**: Prompt Injection, Insecure Output Handling,
Training Data Poisoning, Model DoS, Supply Chain, Information Disclosure,
Insecure Plugin Design, Excessive Agency, Overreliance, Model Theft

## 🔒 Security & Privacy

**Cloud Processing**: Your code is analyzed in our secure cloud
infrastructure with enterprise-grade security controls.

**Data Handling**:
- Code analyzed in isolated containers
- Results returned via encrypted HTTPS
- No permanent storage of your code
- Scan metadata tracked for quota management

**Authentication**: API keys use secure Bearer token authentication with
per-user quota tracking and access control.

## 📖 Usage Examples

### Basic Repository Scan
```
Scan this repository for agentic AI vulnerabilities
```

### Check Specific Files
```
Use the AI Security Scanner to check these files for prompt injection:
- src/prompts.py
- src/llm_integration.py
```

### Get Scan History
```
Show my recent AI security scans
```

## 🛠️ Troubleshooting

### MCP Server Not Starting

**Check if MCP server is running:**
```bash
ps aux | grep "ai-security-mcp"
```

**If not running**, check Claude desktop logs or restart Claude app:
```bash
# macOS
killall Claude && sleep 3 && open -a Claude

# Check config file
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Common causes:**
- Claude desktop config has syntax errors
- API key environment variable not set
- Wrong Python version (need 3.10+)
- uvx not installed (`pip install uv`)

### "API Key Required" Error

You need to set your API key. Get it from:
https://app.ai-threat-scanner.com/dashboard/api-keys

Then reconfigure:
```bash
claude mcp remove ai-security-scanner
claude mcp add ai-security-scanner \
  -e AI_SECURITY_API_KEY=your_actual_key \
  -- uvx --python=3.12 ai-security-mcp@1.0.31
```

### "Connection Failed" Error

Check cloud service status:
```bash
curl https://ciso-mcp-server-production.up.railway.app/health
```

**Expected response**: `{"status":"healthy"}`

If service is down, check status page: https://status.ai-threat-scanner.com

### "Quota Exceeded" Error

You've reached your scan limit. View usage at:
https://app.ai-threat-scanner.com/dashboard/usage

Upgrade your plan or wait for quota reset.

### Report Files Not Created

**Verify MCP server is running** (see above).

**Check directory permissions:**
```bash
ls -la AIThreatScannerReports/
```

**Expected after scan**: 4 files per scan (3 Markdown + 1 JSON)

**Verify version** (must be 1.0.31+):
```bash
uvx --python=3.12 ai-security-mcp@1.0.31 --version
```

## 💰 Pricing

- **Free Tier**: 10 scans/day, 100 scans/month
- **Pro Tier**: 100 scans/day, unlimited monthly
- **Enterprise**: Custom quotas and dedicated support

View pricing: https://ai-threat-scanner.com/pricing

## 📚 Documentation

- **Dashboard**: https://app.ai-threat-scanner.com
- **Full Documentation**: https://ai-threat-scanner.com/docs
- **OWASP ASI Specification**: https://owasp.org/www-project-ai-security-and-privacy-guide/
- **Bug Reports**: https://github.com/ai-security-scanner/ai-security-mcp/issues

## 🏢 Architecture Details

This package contains only the thin client proxy. The actual security scanning
happens in our cloud infrastructure:

```
Your Machine          Cloud Infrastructure
┌─────────────┐      ┌──────────────────────┐
│ Claude Code │─────▶│ Cloud MCP Server     │
│             │      │ - 27 Security Agents │
│ Thin Client │◀─────│ - Vulnerability DB   │
│ (~50KB)     │      │ - Analysis Engine    │
└─────────────┘      └──────────────────────┘
```

**Thin Client Responsibilities**:
- MCP protocol (stdio) with Claude Code
- HTTPS proxy to cloud server
- API key authentication
- Request/response forwarding

**Cloud Server Responsibilities**:
- API key validation
- Agent execution (all 27)
- Vulnerability analysis
- Report generation
- Quota tracking

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- **Website**: https://ai-threat-scanner.com
- **Dashboard**: https://app.ai-threat-scanner.com
- **GitHub**: https://github.com/ai-security-scanner/ai-security-mcp
- **PyPI**: https://pypi.org/project/ai-security-mcp/
- **Support**: support@ai-threat-scanner.com