adversary-mcp-server

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 • Quick Start • Claude Code Setup • Cursor Setup • CLI Usage • MCP Tools • Architecture

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)

Quick Install

# 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

adv --version
adv status

Quick Start

1. Configure Security Engine

# 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

# 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

# Launch interactive telemetry dashboard
adv dashboard

Claude Code Setup

Configure MCP Server

Create or update ~/.config/claude-code/mcp.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:

{
    "mcpServers": {
        "adversary": {
            "command": "uvx",
            "args": ["adversary-mcp-server"]
        }
    }
}

Alternative Cursor setups (click to expand)

Using pip installation:

{
  "mcpServers": {
    "adversary": {
      "command": "python",
      "args": ["-m", "adversary_mcp_server.sync_main"]
    }
  }
}

For development:

{
  "mcpServers": {
    "adversary": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "adversary_mcp_server.sync_main"]
    }
  }
}

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

# 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

# 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

# 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

--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

// 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:

# 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.

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

New Architecture Benefits

• Separation of Concern: Business logic isolated from infrastructure
• Dependency Inversion: High-level modules don't depend on low-level details
• Testability: Pure domain logic enables comprehensive unit testing
• Maintainability: Changes to infrastructure don't affect business rules
• Scalability: New scan strategies and validators easily pluggable
• 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

• Input Processing: ScanRequest created with ScanContext (file/directory/code)
• Domain Orchestration: ScanOrchestrator coordinates scanning strategies
• Parallel Analysis: Multiple IScanStrategy implementations execute concurrently
• Threat Aggregation: ThreatAggregator deduplicates and merges findings
• Validation Pipeline: ValidationService filters false positives using AI
• Result Assembly: Rich ScanResult with comprehensive metadata
• 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

• Multi-Engine Analysis: Parallel execution of Semgrep static analysis and LLM AI analysis
• Intelligent Validation: LLM-powered false positive reduction with confidence scoring
• Threat Aggregation: Smart deduplication and merging using fingerprint and proximity strategies
• Performance Optimization: Async processing, caching, and batch operations
• Comprehensive Telemetry: SQLAlchemy-backed metrics with interactive Chart.js dashboard
• Git Integration: Diff-aware scanning for efficient CI/CD pipeline integration
• Zero-Config Operation: Auto-discovery and configuration with sensible defaults

Configuration

Environment Variables

# 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:

# 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

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

# 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

# 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
• Report Issues
• Discussions
• Contact: [e-mail]

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Made with ❤️ for software security.