# Adversary MCP Server
<div align="center">
[](https://badge.fury.io/py/adversary-mcp-server)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/brettbergin/adversary-mcp-server)
[](https://github.com/brettbergin/adversary-mcp-server)
[](https://pypi.org/project/adversary-mcp-server/)
**🔒 Clean Architecture security analysis with AI-powered vulnerability detection and validation**
**We think about your vulns so you don't have to.**
[Installation](#installation) • [Quick Start](#quick-start) • [Claude Code Setup](#claude-code-setup) • [Cursor Setup](#cursor-ide-setup) • [CLI Usage](#cli-usage) • [MCP Tools](#mcp-tools) • [Architecture](#architecture)
</div>
---
## Features
- **AI-Powered Analysis** - OpenAI/Anthropic LLM integration for intelligent vulnerability detection
- **Smart Validation** - Reduces false positives with LLM validation (70% confidence threshold)
- **Multi-Engine Scanning** - Combines Semgrep static analysis & AI analysis
- **Automatic Persistence** - Auto-saves scan results in JSON, Markdown, and CSV formats
- **MCP Integration** - Native support for Claude Code and Cursor IDE
- **Comprehensive CLI** - Full command-line interface with all scanning capabilities
- **Rich Telemetry** - Comprehensive tracking with dashboard visualization
## Installation
### Prerequisites
- **Python 3.10+** (tested on 3.11, 3.12, 3.13)
- **Semgrep** - Static analysis engine ([install](https://semgrep.dev/docs/))
### Quick Install
```bash
# Install python uv
brew install uv
# Install Semgrep (required)
brew install semgrep # macOS
# or
pip install semgrep # Other platforms
# Install Adversary MCP Server
uv pip install adversary-mcp-server
```
### Verify Installation
```bash
adv --version
adv status
```
## Quick Start
### 1. Configure Security Engine
```bash
# Initial setup (interactive)
adv configure setup
# Or configure directly with options
adv configure --llm-provider openai --llm-api-key $OPENAI_API_KEY
adv configure --llm-provider anthropic --llm-api-key $ANTHROPIC_API_KEY
# Check configuration status
adv status
```
### 2. Run Your First Scan
```bash
# Scan a single file (basic)
adv scan-file path/to/file.py
# Scan with AI analysis and validation (recommended)
adv scan-file path/to/file.py --use-llm --use-validation
# Scan entire directory
adv scan-folder ./src --use-llm --use-validation
# Scan code snippet directly
adv scan-code "print('Hello World')" --language python
```
### 3. View Comprehensive Dashboard
```bash
# Launch interactive telemetry dashboard
adv dashboard
```
## Claude Code Setup
### Configure MCP Server
Create or update `~/.config/claude-code/mcp.json`:
```json
{
"mcpServers": {
"adversary": {
"command": "uvx",
"args": ["adversary-mcp-server"]
}
}
}
```
### Using MCP Tools in Claude Code
Once configured, these tools are available in Claude Code:
- **Ask Claude**: "Scan this file for security issues using adv_scan_file"
- **Ask Claude**: "Check for vulnerabilities in the current project with adv_scan_folder"
- **Ask Claude**: "Analyze this code snippet for security issues using adv_scan_code"
## Cursor IDE Setup
### Configure MCP Server
Create `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"adversary": {
"command": "uvx",
"args": ["adversary-mcp-server"]
}
}
}
```
<details>
<summary>Alternative Cursor setups (click to expand)</summary>
#### Using pip installation:
```json
{
"mcpServers": {
"adversary": {
"command": "python",
"args": ["-m", "adversary_mcp_server.sync_main"]
}
}
}
```
#### For development:
```json
{
"mcpServers": {
"adversary": {
"command": "/path/to/.venv/bin/python",
"args": ["-m", "adversary_mcp_server.sync_main"]
}
}
}
```
</details>
### Using MCP Tools in Cursor
Once configured, these tools are available in Cursor's chat:
- **Ask Cursor**: "Scan this file for security issues using adv_scan_file"
- **Ask Cursor**: "Check for vulnerabilities in the current project with adv_scan_folder"
- **Ask Cursor**: "Analyze this code snippet for security issues using adv_scan_code"
## CLI Usage
### Basic Commands
```bash
# Configure the scanner
adv configure setup
# Check status and configuration
adv status
# Scan individual files
adv scan-file <file-path> [options]
# Scan directories
adv scan-folder <directory-path> [options]
# Scan code snippets
adv scan-code <code-content> --language <lang> [options]
# Launch comprehensive telemetry dashboard
adv dashboard
```
### Scanning Examples
```bash
# Basic file scan
adv scan-file app.py
# Scan with AI analysis and validation (recommended)
adv scan-file app.py --use-llm --use-validation
# Directory scan with full analysis
adv scan-folder ./src --use-llm --use-validation
# Code snippet scan
adv scan-code "SELECT * FROM users WHERE id = ?" --language sql
# Scan with specific severity threshold
adv scan-file app.py --severity high
# Output results in different formats
adv scan-file app.py --output-format json --output-file results.json
adv scan-file app.py --output-format markdown --verbose
```
### Configuration Commands
```bash
# Interactive setup
adv configure setup
# Direct configuration
adv configure --llm-provider openai --llm-api-key your-key
adv configure --llm-provider anthropic --llm-api-key your-key
# Reset configuration
adv configure reset
# Check current configuration
adv status
```
### Available Options
```bash
--use-llm / --no-llm # Enable/disable AI analysis
--use-validation / --no-validation # Enable/disable false positive filtering
--use-semgrep / --no-semgrep # Enable/disable Semgrep analysis (default: true)
--severity [low|medium|high|critical] # Minimum severity threshold
--output-format [json|markdown|csv] # Output format for results
--output-file <file> # Save results to specific file
--verbose # Verbose output with detailed information
```
## MCP Tools
### Available Tools
| Tool | Description | Example Usage |
|------|-------------|---------------|
| `adv_scan_code` | Scan code snippets directly | "Scan this code for vulnerabilities" |
| `adv_scan_file` | Scan specific files with full analysis | "Check security issues in auth.py" |
| `adv_scan_folder` | Scan entire directories recursively | "Analyze the src folder for vulnerabilities" |
| `adv_get_status` | Check server status and capabilities | "Is the security scanner configured?" |
| `adv_get_version` | Get server version information | "What version is running?" |
| `adv_mark_false_positive` | Mark findings as false positives | "Mark finding XYZ as false positive" |
| `adv_unmark_false_positive` | Remove false positive marking | "Unmark finding ABC as false positive" |
### MCP Tool Examples
```typescript
// In Claude Code or Cursor, ask the AI assistant:
// Scan current file with full analysis
"Use adv_scan_file to check this file for security issues with LLM validation"
// Scan directory with specific options
"Run adv_scan_folder on the src directory with severity threshold of high"
// Scan code snippet
"Use adv_scan_code to analyze this SQL query for injection vulnerabilities"
// Check scanner status
"Use adv_get_status to see what scan engines are available"
```
### Automatic Result Persistence
All MCP tools automatically save scan results in multiple formats:
- **JSON**: `.adversary.json` - Machine-readable results with full metadata
- **Markdown**: `.adversary.md` - Human-readable report with remediation guidance
- **CSV**: `.adversary.csv` - Spreadsheet-compatible format for analysis
Results are automatically placed alongside scanned files/directories with intelligent conflict resolution.
## Dashboard & Telemetry
### Comprehensive HTML Dashboard
The scanner includes a rich web-based dashboard for comprehensive telemetry analysis:
```bash
# Launch interactive dashboard
adv dashboard
```
**Dashboard Features:**
- **MCP Tool Analytics** - Track tool usage, success rates, and performance
- **Scan Engine Metrics** - Monitor Semgrep, LLM, and validation performance
- **Threat Analysis** - Categorize findings by severity and confidence
- **System Health** - Performance monitoring and statistics
- **Language Analysis** - Track scanning efficiency by programming language
- **Recent Activity** - Timeline view of recent scans and operations
### Telemetry System
Adversary MCP Server includes comprehensive telemetry tracking:
- **Automatic Collection** - All MCP tools, CLI commands, and scan operations are automatically tracked
- **Local Storage** - All data stored locally, never transmitted to external services
- **Zero Configuration** - Telemetry works out-of-the-box with no setup required
- **Performance Insights** - Identify bottlenecks and optimize scanning workflows
- **Usage Analytics** - Understand tool usage patterns and effectiveness
## Architecture
### Implementation
Adversary MCP Server is built using **Clean Architecture** principles with Domain-Driven Design (DDD), ensuring separation of concerns, maintainability, and testability.
<div align="center">
```mermaid
graph TB
subgraph "🖥️ **Presentation Layer**"
A[Cursor IDE]
B[CLI Interface]
C[Web Dashboard]
end
subgraph "🔧 **Application Layer**"
D[MCP Server]
E[CLI Commands]
F[Adapters]
subgraph "Adapters"
F1[SemgrepAdapter]
F2[LLMAdapter]
F3[ValidationAdapter]
end
end
subgraph "🏛️ **Domain Layer (Business Logic)**"
subgraph "Entities"
G[ScanRequest]
H[ScanResult]
I[ThreatMatch]
end
subgraph "Value Objects"
J[ScanContext]
K[SeverityLevel]
L[ConfidenceScore]
M[FilePath]
end
subgraph "Domain Services"
N[ScanOrchestrator]
O[ThreatAggregator]
P[ValidationService]
end
subgraph "Interfaces"
Q[IScanStrategy]
R[IValidationStrategy]
end
end
subgraph "⚙️ **Infrastructure Layer**"
S[SemgrepScanner]
T[LLMScanner]
U[LLMValidator]
V[SQLAlchemy Database]
W[File System]
X[Git Operations]
Y[Telemetry System]
end
A -->|MCP Protocol| D
B --> E
C --> Y
D --> F
E --> F
F1 --> N
F2 --> N
F3 --> P
N --> O
N --> P
G --> N
H --> O
I --> P
J --> G
K --> I
L --> I
M --> G
N --> Q
P --> R
F1 -.-> S
F2 -.-> T
F3 -.-> U
S --> W
T --> W
U --> V
Y --> V
X --> W
style N fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
style O fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
style P fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
style G fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style H fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style I fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style F1 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
style F2 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
style F3 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
```
</div>
### New Architecture Benefits
1. **Separation of Concern**: Business logic isolated from infrastructure
2. **Dependency Inversion**: High-level modules don't depend on low-level details
3. **Testability**: Pure domain logic enables comprehensive unit testing
4. **Maintainability**: Changes to infrastructure don't affect business rules
5. **Scalability**: New scan strategies and validators easily pluggable
6. **Type Safety**: Rich domain models with comprehensive validation
### Architectural Layers
#### **Domain Layer** (Core Business Logic)
- **Entities**: `ScanRequest`, `ScanResult`, `ThreatMatch` - Rich business objects
- **Value Objects**: `ScanContext`, `SeverityLevel`, `ConfidenceScore`, `FilePath` - Immutable domain concepts
- **Domain Services**: `ScanOrchestrator`, `ThreatAggregator`, `ValidationService` - Pure business orchestration
- **Interfaces**: `IScanStrategy`, `IValidationStrategy` - Contracts for external dependencies
#### **Application Layer** (Use Cases & Coordination)
- **MCP Server**: Handles Cursor IDE integration via Model Context Protocol
- **CLI Commands**: Command-line interface for security scanning operations
- **Adapters**: Bridge domain interfaces with infrastructure implementations
- `SemgrepAdapter` - Adapts Semgrep scanner to domain `IScanStrategy`
- `LLMAdapter` - Adapts LLM scanner to domain `IScanStrategy`
- `ValidationAdapter` - Adapts LLM validator to domain `IValidationStrategy`
#### **Infrastructure Layer** (External Services)
- **SemgrepScanner**: Static analysis engine integration
- **LLMScanner**: AI-powered vulnerability detection
- **LLMValidator**: False positive filtering with LLM analysis
- **SQLAlchemy Database**: Persistent storage for telemetry and results
- **File System**: Code file access and Git operations
- **Telemetry System**: Performance tracking and dashboard generation
### Data Flow Architecture
1. **Input Processing**: `ScanRequest` created with `ScanContext` (file/directory/code)
2. **Domain Orchestration**: `ScanOrchestrator` coordinates scanning strategies
3. **Parallel Analysis**: Multiple `IScanStrategy` implementations execute concurrently
4. **Threat Aggregation**: `ThreatAggregator` deduplicates and merges findings
5. **Validation Pipeline**: `ValidationService` filters false positives using AI
6. **Result Assembly**: Rich `ScanResult` with comprehensive metadata
7. **Presentation**: Results formatted for CLI, MCP, or dashboard consumption
### Key Design Patterns
- **Strategy Pattern**: Pluggable scan and validation strategies
- **Adapter Pattern**: Infrastructure integration without domain coupling
- **Factory Pattern**: Bootstrap and dependency injection
- **Value Objects**: Immutable domain concepts with validation
- **Domain Services**: Complex business logic coordination
### How It Works
1. **Multi-Engine Analysis**: Parallel execution of Semgrep static analysis and LLM AI analysis
2. **Intelligent Validation**: LLM-powered false positive reduction with confidence scoring
3. **Threat Aggregation**: Smart deduplication and merging using fingerprint and proximity strategies
4. **Performance Optimization**: Async processing, caching, and batch operations
5. **Comprehensive Telemetry**: SQLAlchemy-backed metrics with interactive Chart.js dashboard
6. **Git Integration**: Diff-aware scanning for efficient CI/CD pipeline integration
7. **Zero-Config Operation**: Auto-discovery and configuration with sensible defaults
## Configuration
### Environment Variables
```bash
# Core settings (optional)
ADVERSARY_LOG_LEVEL=INFO # Set logging level
ADVERSARY_WORKSPACE_ROOT=/path # Override workspace detection
```
### Configuration File
Settings are automatically managed through the CLI and stored in `~/.adversary/config.json`:
```bash
# Interactive configuration
adv configure setup
# Direct configuration
adv configure --llm-provider openai --llm-api-key your-key
# Check current settings
adv status
```
## CI/CD Integration
### GitHub Actions
```yaml
name: Security Scan
on: [pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install dependencies
run: |
pip install adversary-mcp-server
- name: Run security scan
run: |
adv scan-directory . \
--use-llm \
--use-validation \
--severity medium \
--output-format json \
--output-file scan-results.json
- name: Upload results
uses: actions/upload-artifact@v3
with:
name: security-scan
path: scan-results.json
```
## Development
### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/brettbergin/adversary-mcp-server.git
cd adversary-mcp-server
# Create virtual environment (using uv or standard venv)
source .venv/bin/activate # Activate existing venv
# Install in development mode
uv pip install -e .[dev]
# Run tests
make test
```
### Running Tests
```bash
# Full test suite with coverage
make test
# Specific test categories
make test-unit # Unit tests only
make test-integration # Integration tests only
make test-security # Security tests only
# Code quality checks
make format # Auto-format code
make mypy # Type checking
make lint # Run all linting
make pre-commit # Run same pre-commit in git commits.
```
## Support
- [Documentation](https://github.com/brettbergin/adversary-mcp-server/wiki)
- [Report Issues](https://github.com/brettbergin/adversary-mcp-server/issues)
- [Discussions](https://github.com/brettbergin/adversary-mcp-server/discussions)
- Contact: brettberginbc@yahoo.com
## License
MIT License - see [LICENSE](LICENSE) for details.
## Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
---
<div align="center">
Made with ❤️ for software security.
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "adversary-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "mcp, scanner, security, static-analysis, vulnerability",
"author": null,
"author_email": "Brett Bergin <brettberginbc@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/38/68/4a1e16081d979a26e8898c3e7cce6bf27bf22babcb4193cf94b07cd60ed3/adversary_mcp_server-1.11.1.tar.gz",
"platform": null,
"description": "# Adversary MCP Server\n\n<div align=\"center\">\n\n[](https://badge.fury.io/py/adversary-mcp-server)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/brettbergin/adversary-mcp-server)\n[](https://github.com/brettbergin/adversary-mcp-server)\n[](https://pypi.org/project/adversary-mcp-server/)\n\n**\ud83d\udd12 Clean Architecture security analysis with AI-powered vulnerability detection and validation**\n\n**We think about your vulns so you don't have to.**\n\n[Installation](#installation) \u2022 [Quick Start](#quick-start) \u2022 [Claude Code Setup](#claude-code-setup) \u2022 [Cursor Setup](#cursor-ide-setup) \u2022 [CLI Usage](#cli-usage) \u2022 [MCP Tools](#mcp-tools) \u2022 [Architecture](#architecture)\n\n</div>\n\n---\n\n## Features\n\n- **AI-Powered Analysis** - OpenAI/Anthropic LLM integration for intelligent vulnerability detection\n- **Smart Validation** - Reduces false positives with LLM validation (70% confidence threshold)\n- **Multi-Engine Scanning** - Combines Semgrep static analysis & AI analysis\n- **Automatic Persistence** - Auto-saves scan results in JSON, Markdown, and CSV formats\n- **MCP Integration** - Native support for Claude Code and Cursor IDE\n- **Comprehensive CLI** - Full command-line interface with all scanning capabilities\n- **Rich Telemetry** - Comprehensive tracking with dashboard visualization\n\n## Installation\n\n### Prerequisites\n\n- **Python 3.10+** (tested on 3.11, 3.12, 3.13)\n- **Semgrep** - Static analysis engine ([install](https://semgrep.dev/docs/))\n\n### Quick Install\n\n```bash\n# Install python uv\nbrew install uv\n\n# Install Semgrep (required)\nbrew install semgrep # macOS\n# or\npip install semgrep # Other platforms\n\n# Install Adversary MCP Server\nuv pip install adversary-mcp-server\n```\n\n### Verify Installation\n\n```bash\nadv --version\nadv status\n```\n\n## Quick Start\n\n### 1. Configure Security Engine\n\n```bash\n# Initial setup (interactive)\nadv configure setup\n\n# Or configure directly with options\nadv configure --llm-provider openai --llm-api-key $OPENAI_API_KEY\nadv configure --llm-provider anthropic --llm-api-key $ANTHROPIC_API_KEY\n\n# Check configuration status\nadv status\n```\n\n### 2. Run Your First Scan\n\n```bash\n# Scan a single file (basic)\nadv scan-file path/to/file.py\n\n# Scan with AI analysis and validation (recommended)\nadv scan-file path/to/file.py --use-llm --use-validation\n\n# Scan entire directory\nadv scan-folder ./src --use-llm --use-validation\n\n# Scan code snippet directly\nadv scan-code \"print('Hello World')\" --language python\n```\n\n### 3. View Comprehensive Dashboard\n\n```bash\n# Launch interactive telemetry dashboard\nadv dashboard\n```\n\n## Claude Code Setup\n\n### Configure MCP Server\n\nCreate or update `~/.config/claude-code/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"uvx\",\n \"args\": [\"adversary-mcp-server\"]\n }\n }\n}\n```\n\n### Using MCP Tools in Claude Code\n\nOnce configured, these tools are available in Claude Code:\n\n- **Ask Claude**: \"Scan this file for security issues using adv_scan_file\"\n- **Ask Claude**: \"Check for vulnerabilities in the current project with adv_scan_folder\"\n- **Ask Claude**: \"Analyze this code snippet for security issues using adv_scan_code\"\n\n## Cursor IDE Setup\n\n### Configure MCP Server\n\nCreate `.cursor/mcp.json` in your project:\n\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"uvx\",\n \"args\": [\"adversary-mcp-server\"]\n }\n }\n}\n```\n\n<details>\n<summary>Alternative Cursor setups (click to expand)</summary>\n\n#### Using pip installation:\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"adversary_mcp_server.sync_main\"]\n }\n }\n}\n```\n\n#### For development:\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"/path/to/.venv/bin/python\",\n \"args\": [\"-m\", \"adversary_mcp_server.sync_main\"]\n }\n }\n}\n```\n</details>\n\n### Using MCP Tools in Cursor\n\nOnce configured, these tools are available in Cursor's chat:\n\n- **Ask Cursor**: \"Scan this file for security issues using adv_scan_file\"\n- **Ask Cursor**: \"Check for vulnerabilities in the current project with adv_scan_folder\"\n- **Ask Cursor**: \"Analyze this code snippet for security issues using adv_scan_code\"\n\n## CLI Usage\n\n### Basic Commands\n\n```bash\n# Configure the scanner\nadv configure setup\n\n# Check status and configuration\nadv status\n\n# Scan individual files\nadv scan-file <file-path> [options]\n\n# Scan directories\nadv scan-folder <directory-path> [options]\n\n# Scan code snippets\nadv scan-code <code-content> --language <lang> [options]\n\n# Launch comprehensive telemetry dashboard\nadv dashboard\n```\n\n### Scanning Examples\n\n```bash\n# Basic file scan\nadv scan-file app.py\n\n# Scan with AI analysis and validation (recommended)\nadv scan-file app.py --use-llm --use-validation\n\n# Directory scan with full analysis\nadv scan-folder ./src --use-llm --use-validation\n\n# Code snippet scan\nadv scan-code \"SELECT * FROM users WHERE id = ?\" --language sql\n\n# Scan with specific severity threshold\nadv scan-file app.py --severity high\n\n# Output results in different formats\nadv scan-file app.py --output-format json --output-file results.json\nadv scan-file app.py --output-format markdown --verbose\n```\n\n### Configuration Commands\n\n```bash\n# Interactive setup\nadv configure setup\n\n# Direct configuration\nadv configure --llm-provider openai --llm-api-key your-key\nadv configure --llm-provider anthropic --llm-api-key your-key\n\n# Reset configuration\nadv configure reset\n\n# Check current configuration\nadv status\n```\n\n### Available Options\n\n```bash\n--use-llm / --no-llm # Enable/disable AI analysis\n--use-validation / --no-validation # Enable/disable false positive filtering\n--use-semgrep / --no-semgrep # Enable/disable Semgrep analysis (default: true)\n--severity [low|medium|high|critical] # Minimum severity threshold\n--output-format [json|markdown|csv] # Output format for results\n--output-file <file> # Save results to specific file\n--verbose # Verbose output with detailed information\n```\n\n## MCP Tools\n\n### Available Tools\n\n| Tool | Description | Example Usage |\n|------|-------------|---------------|\n| `adv_scan_code` | Scan code snippets directly | \"Scan this code for vulnerabilities\" |\n| `adv_scan_file` | Scan specific files with full analysis | \"Check security issues in auth.py\" |\n| `adv_scan_folder` | Scan entire directories recursively | \"Analyze the src folder for vulnerabilities\" |\n| `adv_get_status` | Check server status and capabilities | \"Is the security scanner configured?\" |\n| `adv_get_version` | Get server version information | \"What version is running?\" |\n| `adv_mark_false_positive` | Mark findings as false positives | \"Mark finding XYZ as false positive\" |\n| `adv_unmark_false_positive` | Remove false positive marking | \"Unmark finding ABC as false positive\" |\n\n### MCP Tool Examples\n\n```typescript\n// In Claude Code or Cursor, ask the AI assistant:\n\n// Scan current file with full analysis\n\"Use adv_scan_file to check this file for security issues with LLM validation\"\n\n// Scan directory with specific options\n\"Run adv_scan_folder on the src directory with severity threshold of high\"\n\n// Scan code snippet\n\"Use adv_scan_code to analyze this SQL query for injection vulnerabilities\"\n\n// Check scanner status\n\"Use adv_get_status to see what scan engines are available\"\n```\n\n### Automatic Result Persistence\n\nAll MCP tools automatically save scan results in multiple formats:\n\n- **JSON**: `.adversary.json` - Machine-readable results with full metadata\n- **Markdown**: `.adversary.md` - Human-readable report with remediation guidance\n- **CSV**: `.adversary.csv` - Spreadsheet-compatible format for analysis\n\nResults are automatically placed alongside scanned files/directories with intelligent conflict resolution.\n\n## Dashboard & Telemetry\n\n### Comprehensive HTML Dashboard\n\nThe scanner includes a rich web-based dashboard for comprehensive telemetry analysis:\n\n```bash\n# Launch interactive dashboard\nadv dashboard\n```\n\n**Dashboard Features:**\n- **MCP Tool Analytics** - Track tool usage, success rates, and performance\n- **Scan Engine Metrics** - Monitor Semgrep, LLM, and validation performance\n- **Threat Analysis** - Categorize findings by severity and confidence\n- **System Health** - Performance monitoring and statistics\n- **Language Analysis** - Track scanning efficiency by programming language\n- **Recent Activity** - Timeline view of recent scans and operations\n\n### Telemetry System\n\nAdversary MCP Server includes comprehensive telemetry tracking:\n\n- **Automatic Collection** - All MCP tools, CLI commands, and scan operations are automatically tracked\n- **Local Storage** - All data stored locally, never transmitted to external services\n- **Zero Configuration** - Telemetry works out-of-the-box with no setup required\n- **Performance Insights** - Identify bottlenecks and optimize scanning workflows\n- **Usage Analytics** - Understand tool usage patterns and effectiveness\n\n## Architecture\n\n### Implementation\n\nAdversary MCP Server is built using **Clean Architecture** principles with Domain-Driven Design (DDD), ensuring separation of concerns, maintainability, and testability.\n\n<div align=\"center\">\n\n```mermaid\ngraph TB\n subgraph \"\ud83d\udda5\ufe0f **Presentation Layer**\"\n A[Cursor IDE]\n B[CLI Interface]\n C[Web Dashboard]\n end\n\n subgraph \"\ud83d\udd27 **Application Layer**\"\n D[MCP Server]\n E[CLI Commands]\n F[Adapters]\n subgraph \"Adapters\"\n F1[SemgrepAdapter]\n F2[LLMAdapter]\n F3[ValidationAdapter]\n end\n end\n\n subgraph \"\ud83c\udfdb\ufe0f **Domain Layer (Business Logic)**\"\n subgraph \"Entities\"\n G[ScanRequest]\n H[ScanResult]\n I[ThreatMatch]\n end\n subgraph \"Value Objects\"\n J[ScanContext]\n K[SeverityLevel]\n L[ConfidenceScore]\n M[FilePath]\n end\n subgraph \"Domain Services\"\n N[ScanOrchestrator]\n O[ThreatAggregator]\n P[ValidationService]\n end\n subgraph \"Interfaces\"\n Q[IScanStrategy]\n R[IValidationStrategy]\n end\n end\n\n subgraph \"\u2699\ufe0f **Infrastructure Layer**\"\n S[SemgrepScanner]\n T[LLMScanner]\n U[LLMValidator]\n V[SQLAlchemy Database]\n W[File System]\n X[Git Operations]\n Y[Telemetry System]\n end\n\n A -->|MCP Protocol| D\n B --> E\n C --> Y\n\n D --> F\n E --> F\n F1 --> N\n F2 --> N\n F3 --> P\n\n N --> O\n N --> P\n\n G --> N\n H --> O\n I --> P\n J --> G\n K --> I\n L --> I\n M --> G\n\n N --> Q\n P --> R\n\n F1 -.-> S\n F2 -.-> T\n F3 -.-> U\n\n S --> W\n T --> W\n U --> V\n Y --> V\n X --> W\n\n style N fill:#e1f5fe,stroke:#0277bd,stroke-width:3px\n style O fill:#e1f5fe,stroke:#0277bd,stroke-width:3px\n style P fill:#e1f5fe,stroke:#0277bd,stroke-width:3px\n style G fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n style H fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n style I fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n style F1 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n style F2 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n style F3 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n```\n\n</div>\n\n### New Architecture Benefits\n\n1. **Separation of Concern**: Business logic isolated from infrastructure\n2. **Dependency Inversion**: High-level modules don't depend on low-level details\n3. **Testability**: Pure domain logic enables comprehensive unit testing\n4. **Maintainability**: Changes to infrastructure don't affect business rules\n5. **Scalability**: New scan strategies and validators easily pluggable\n6. **Type Safety**: Rich domain models with comprehensive validation\n\n### Architectural Layers\n\n#### **Domain Layer** (Core Business Logic)\n- **Entities**: `ScanRequest`, `ScanResult`, `ThreatMatch` - Rich business objects\n- **Value Objects**: `ScanContext`, `SeverityLevel`, `ConfidenceScore`, `FilePath` - Immutable domain concepts\n- **Domain Services**: `ScanOrchestrator`, `ThreatAggregator`, `ValidationService` - Pure business orchestration\n- **Interfaces**: `IScanStrategy`, `IValidationStrategy` - Contracts for external dependencies\n\n#### **Application Layer** (Use Cases & Coordination)\n- **MCP Server**: Handles Cursor IDE integration via Model Context Protocol\n- **CLI Commands**: Command-line interface for security scanning operations\n- **Adapters**: Bridge domain interfaces with infrastructure implementations\n - `SemgrepAdapter` - Adapts Semgrep scanner to domain `IScanStrategy`\n - `LLMAdapter` - Adapts LLM scanner to domain `IScanStrategy`\n - `ValidationAdapter` - Adapts LLM validator to domain `IValidationStrategy`\n\n#### **Infrastructure Layer** (External Services)\n- **SemgrepScanner**: Static analysis engine integration\n- **LLMScanner**: AI-powered vulnerability detection\n- **LLMValidator**: False positive filtering with LLM analysis\n- **SQLAlchemy Database**: Persistent storage for telemetry and results\n- **File System**: Code file access and Git operations\n- **Telemetry System**: Performance tracking and dashboard generation\n\n### Data Flow Architecture\n\n1. **Input Processing**: `ScanRequest` created with `ScanContext` (file/directory/code)\n2. **Domain Orchestration**: `ScanOrchestrator` coordinates scanning strategies\n3. **Parallel Analysis**: Multiple `IScanStrategy` implementations execute concurrently\n4. **Threat Aggregation**: `ThreatAggregator` deduplicates and merges findings\n5. **Validation Pipeline**: `ValidationService` filters false positives using AI\n6. **Result Assembly**: Rich `ScanResult` with comprehensive metadata\n7. **Presentation**: Results formatted for CLI, MCP, or dashboard consumption\n\n### Key Design Patterns\n\n- **Strategy Pattern**: Pluggable scan and validation strategies\n- **Adapter Pattern**: Infrastructure integration without domain coupling\n- **Factory Pattern**: Bootstrap and dependency injection\n- **Value Objects**: Immutable domain concepts with validation\n- **Domain Services**: Complex business logic coordination\n\n### How It Works\n\n1. **Multi-Engine Analysis**: Parallel execution of Semgrep static analysis and LLM AI analysis\n2. **Intelligent Validation**: LLM-powered false positive reduction with confidence scoring\n3. **Threat Aggregation**: Smart deduplication and merging using fingerprint and proximity strategies\n4. **Performance Optimization**: Async processing, caching, and batch operations\n5. **Comprehensive Telemetry**: SQLAlchemy-backed metrics with interactive Chart.js dashboard\n6. **Git Integration**: Diff-aware scanning for efficient CI/CD pipeline integration\n7. **Zero-Config Operation**: Auto-discovery and configuration with sensible defaults\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Core settings (optional)\nADVERSARY_LOG_LEVEL=INFO # Set logging level\nADVERSARY_WORKSPACE_ROOT=/path # Override workspace detection\n```\n\n### Configuration File\n\nSettings are automatically managed through the CLI and stored in `~/.adversary/config.json`:\n\n```bash\n# Interactive configuration\nadv configure setup\n\n# Direct configuration\nadv configure --llm-provider openai --llm-api-key your-key\n\n# Check current settings\nadv status\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Security Scan\non: [pull_request]\n\njobs:\n security:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n - name: Install dependencies\n run: |\n pip install adversary-mcp-server\n\n - name: Run security scan\n run: |\n adv scan-directory . \\\n --use-llm \\\n --use-validation \\\n --severity medium \\\n --output-format json \\\n --output-file scan-results.json\n\n - name: Upload results\n uses: actions/upload-artifact@v3\n with:\n name: security-scan\n path: scan-results.json\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/brettbergin/adversary-mcp-server.git\ncd adversary-mcp-server\n\n# Create virtual environment (using uv or standard venv)\nsource .venv/bin/activate # Activate existing venv\n\n# Install in development mode\nuv pip install -e .[dev]\n\n# Run tests\nmake test\n```\n\n### Running Tests\n\n```bash\n# Full test suite with coverage\nmake test\n\n# Specific test categories\nmake test-unit # Unit tests only\nmake test-integration # Integration tests only\nmake test-security # Security tests only\n\n# Code quality checks\n\nmake format # Auto-format code\nmake mypy # Type checking\nmake lint # Run all linting\nmake pre-commit # Run same pre-commit in git commits.\n```\n\n## Support\n\n- [Documentation](https://github.com/brettbergin/adversary-mcp-server/wiki)\n- [Report Issues](https://github.com/brettbergin/adversary-mcp-server/issues)\n- [Discussions](https://github.com/brettbergin/adversary-mcp-server/discussions)\n- Contact: brettberginbc@yahoo.com\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n---\n\n<div align=\"center\">\nMade with \u2764\ufe0f for software security.\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for security vulnerability scanning and detection",
"version": "1.11.1",
"project_urls": {
"Documentation": "https://github.com/brettbergin/adversary-mcp-server#readme",
"Homepage": "https://github.com/brettbergin/adversary-mcp-server",
"Issues": "https://github.com/brettbergin/adversary-mcp-server/issues",
"Repository": "https://github.com/brettbergin/adversary-mcp-server.git"
},
"split_keywords": [
"mcp",
" scanner",
" security",
" static-analysis",
" vulnerability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7e5a8f3f63043b5ed1cf4c0ef131b533db67ff2ade25c4c957661e0ca763a527",
"md5": "e937016403a7c947f157673882817767",
"sha256": "6eb68647780479647d8ec1a42424b2ddf3138b912e2cfd9e554c0a4e857fa92d"
},
"downloads": -1,
"filename": "adversary_mcp_server-1.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e937016403a7c947f157673882817767",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 453576,
"upload_time": "2025-08-24T21:16:48",
"upload_time_iso_8601": "2025-08-24T21:16:48.308734Z",
"url": "https://files.pythonhosted.org/packages/7e/5a/8f3f63043b5ed1cf4c0ef131b533db67ff2ade25c4c957661e0ca763a527/adversary_mcp_server-1.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "38684a1e16081d979a26e8898c3e7cce6bf27bf22babcb4193cf94b07cd60ed3",
"md5": "140debb51ae429d9a83f1b9237c8904c",
"sha256": "004956852c7987843befb3ef4216c3f543e3b5aa7138423443109e1c4166b1e4"
},
"downloads": -1,
"filename": "adversary_mcp_server-1.11.1.tar.gz",
"has_sig": false,
"md5_digest": "140debb51ae429d9a83f1b9237c8904c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 972513,
"upload_time": "2025-08-24T21:16:53",
"upload_time_iso_8601": "2025-08-24T21:16:53.200982Z",
"url": "https://files.pythonhosted.org/packages/38/68/4a1e16081d979a26e8898c3e7cce6bf27bf22babcb4193cf94b07cd60ed3/adversary_mcp_server-1.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 21:16:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brettbergin",
"github_project": "adversary-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "adversary-mcp-server"
}
JSON
