# 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/)
**Enterprise-grade security analysis with real AI-powered vulnerability detection and validation. Features integrated OpenAI/Anthropic LLM support, intelligent false positive filtering, and batch processing optimization for large repositories. Implemented as an MCP server as well as a command-line interface.**
**We think about your vulns so you dont have to.**
[Installation](#installation) • [Quick Start](#quick-start) • [AI-Powered Analysis](#ai-powered-analysis) • [MCP Integration](#mcp-integration) • [Rule Management](#rule-management) • [CLI Reference](#cli-reference)
</div>
---
## Installation
### Prerequisites
- **Python 3.11+** (3.11+ recommended)
- **uv** (https://astral.sh/uv/)
- **semgrep** (https://semgrep.dev/docs/)
- **Cursor IDE** with MCP support
### Quick Install
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```bash
brew install semgrep
```
```bash
uv pip install adversary-mcp-server
```
### Verify Installation
```bash
adversary-mcp-cli --version
adversary-mcp-cli status
```
---
## Quick Start
### 1. Initial Setup
```bash
# Configure the security engine
adversary-mcp-cli configure
# Configure LLM provider (OpenAI or Anthropic) for AI-powered analysis
adversary-mcp-cli configure --llm-provider openai
# or
adversary-mcp-cli configure --llm-provider anthropic
# Check server status
adversary-mcp-cli status
```
### 2. Cursor IDE Integration
Create `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
#### **Recommended: Using `uv` (Modern Python Package Manager)**
```json
{
"mcpServers": {
"adversary": {
"command": "uv",
"args": ["run", "adversary-mcp-server"],
"env": {
"ADVERSARY_WORKSPACE_ROOT": "/path/to/your/project"
}
}
}
}
```
#### **Alternative: Using `pip` Installation**
```json
{
"mcpServers": {
"adversary": {
"command": "python",
"args": [
"-m",
"adversary_mcp_server.server"
],
"env": {
"ADVERSARY_WORKSPACE_ROOT": "/path/to/your/project"
}
}
}
}
```
#### **Development: Local Repository**
```json
{
"mcpServers": {
"adversary": {
"command": "~/code/adversary-mcp-server/.venv/bin/python",
"args": [
"-m",
"adversary_mcp_server.server"
],
"env": {
"ADVERSARY_WORKSPACE_ROOT": "/path/to/your/project"
}
}
}
}
```
**💡 Workspace Path Resolution:**
If you experience issues with @ mentioned files/folders not being found, set the `ADVERSARY_WORKSPACE_ROOT` environment variable to your actual project directory. This is especially useful when:
- Using @ mentions in Cursor that reference relative paths
- The MCP server's working directory doesn't match your project workspace
- Scanning files/folders from different directories
- **🆕 Large monorepos**: Ensures efficient path resolution for repositories with thousands of files
### 3. Start Using in Cursor
Once configured, you can use these MCP tools in Cursor:
- `adv_scan_code` - Hybrid scanning with rules + AI analysis
- `adv_scan_file` - file scanning with LLM support
- `adv_scan_folder` - directory scanning
- `adv_diff_scan` - scans only changed files between branches
- `adv_configure_settings` - Configuration management
- `adv_get_status` - Check server status and AI availability
- `adv_get_version` - Get version information
- `adv_mark_false_positive` - Mark false positive
- `adv_unmark_false_positive` - Unmark false positive
### 🏗️ System Architecture
```mermaid
graph TB
subgraph "Client Layer"
A[Cursor IDE]
B[CLI Interface]
end
subgraph "Protocol Layer"
C[MCP Server]
D[CLI Commands]
end
A -->|MCP Protocol| C
B --> D
subgraph "Core Engine"
E[ScanEngine]
F[GitDiffScanner]
end
C --> E
D --> E
C --> F
D --> F
subgraph "Security Scanners"
G[SemgrepScanner]
H[LLMScanner]
end
E --> G
E --> H
F --> E
subgraph "Validation & Enhancement"
I[LLMValidator]
J[ExploitGenerator]
end
E --> I
I --> J
subgraph "Support Services"
K[FalsePositiveManager]
L[CredentialManager]
end
E --> K
E --> L
I --> L
subgraph "Data Flow"
M[ThreatMatch Objects]
N[ValidationResults]
O[EnhancedScanResult]
end
G --> M
H --> M
M --> I
I --> N
N --> O
style E fill:#e1f5fe
style I fill:#f3e5f5
style G fill:#e8f5e8
style H fill:#fff3e0
```
### 4. Run Demo (Optional)
Test the scanner with vulnerable code examples:
```bash
# Run interactive demonstration
adversary-mcp-cli demo
```
### 5. **🆕 Git Diff-Aware Scanning**
Scan only changed files between git branches for efficient CI/CD integration:
```bash
# Scan changes between branches
adversary-mcp-cli scan --source-branch=main --target-branch=feature/auth
# Scan with high severity filter
adversary-mcp-cli scan --source-branch=main --target-branch=HEAD --severity=high --use-llm --use-semgrep
```
### 6. **🆕 Large Monorepo Support**
The scanner now supports large corporate monorepos with advanced scalability features:
#### **Key Monorepo Features:**
- **🚀 Unlimited File Scanning**: Removed 50-file limit, can handle 100K+ files
- **⚡ Parallel Processing**: Concurrent file processing with intelligent batching
- **🧠 Smart File Filtering**: Respects `.gitignore`, excludes binaries, and filters by size
- **💾 Streaming Architecture**: Memory-efficient handling of large files
- **📊 Batch Processing**: Progressive results without memory overflow
#### **MCP Tool Usage for Large Codebases:**
```bash
# Scan large monorepo with intelligent filtering
adv_scan_folder
directory_path=@/path/to/large-monorepo
recursive=true
use_llm=true
use_semgrep=true
output_format=json
output=@/.adversary.json
# Efficient diff scanning for monorepos (CI/CD optimized)
adv_diff_scan
source_branch="main"
target_branch="HEAD"
working_directory="/path/to/monorepo"
severity_threshold="medium"
```
#### **Performance Optimizations:**
- **Directory-level Semgrep**: Runs once per directory instead of per file
- **Intelligent Batching**: Processes files in optimized batches of 50
- **Memory Management**: Streaming prevents memory issues with large codebases
- **Concurrent Workers**: Uses `min(32, cpu_count + 4, file_count)` for optimal performance
---
### ** MCP Tool Scanning **
```bash
# Scan with Semgrep + LLM
adv_scan_folder
directory_path=@/path/to/repo
recursive=true
include_exploits=false
use_llm=true
use_semgrep=true
output_format=text
output=@/path/to/.adversary.json
```
```bash
# Scan with Semgrep Only
adv_scan_folder
directory_path=@/path/to/repo
recursive=true
include_exploits=false
use_llm=false
use_semgrep=true
output_format=text
output=@/path/to/.adversary.json
```
### **🚀 Real LLM Integration (NEW)**
The Adversary MCP Server now features **real AI integration** with OpenAI and Anthropic, replacing the previous client-based stub system:
#### **Key Features:**
- **🤖 Multiple LLM Providers**: Support for OpenAI (GPT-4) and Anthropic (Claude 3.5)
- **🔐 Secure API Key Storage**: Uses system keyring for secure credential management
- **🎯 Intelligent Validation**: LLMValidator reduces false positives by up to 70%
- **📦 Batch Processing**: Optimized for large repositories with intelligent file batching
- **💰 Cost Optimization**: Token usage tracking and smart content truncation
- **🔄 Retry Logic**: Automatic retry with exponential backoff for API reliability
#### **Configuration:**
```bash
# Configure OpenAI
adversary-mcp-cli configure --llm-provider openai
# Enter your OpenAI API key when prompted
# Optional: Choose model (default: gpt-4-turbo-preview)
# Configure Anthropic
adversary-mcp-cli configure --llm-provider anthropic
# Enter your Anthropic API key when prompted
# Optional: Choose model (default: claude-3-5-sonnet-20241022)
# Clear LLM configuration
adversary-mcp-cli configure --clear-llm
```
#### **Available Models:**
- **OpenAI**: gpt-4-turbo-preview, gpt-4o, gpt-4, gpt-3.5-turbo
- **Anthropic**: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-latest
### **AI Analysis Features**
- **🎯 Smart Threat Detection**: Context-aware vulnerability identification
- **📊 Confidence Scoring**: Each finding includes confidence levels (0.0-1.0)
- **🔍 Detailed Explanations**: Natural language descriptions of vulnerabilities
- **🏷️ CWE/OWASP Mapping**: Automatic categorization with industry standards
- **⚡ Intelligent Deduplication**: Merges similar findings from multiple engines
- **🛡️ False Positive Filtering**: LLMValidator analyzes and filters noise
- **💡 Exploitation Analysis**: Generates proof-of-concept exploits with safety warnings
---
## MCP Integration
### Available Tools
| Tool | Description | **🆕 AI Features** |
|------|-------------|-------------------|
| `adv_scan_code` | source code scanning | confidence scoring |
| `adv_scan_file` | file scanning | AI-powered prompts, detailed explanations |
| `adv_scan_folder` | directory scanning | statistical insights |
| `adv_diff_scan` | scans only newly added lines | Smart change detection, branch comparison, requires `working_directory` |
| `adv_configure_settings` | configuration management | LLM settings, validation |
| `adv_get_status` | Get server status | LLM configuration status |
| `adv_get_version` | Get version information | Shows AI capabilities |
| `adv_mark_false_positive` | Mark false positive | Mark false positive |
| `adv_unmark_false_positive` | Unmark false positive | unmark false positive |
### **🆕 Git Diff-Aware Scanning**
The `adv_diff_scan` tool enables intelligent scanning of only changed files between git branches:
#### **Key Features:**
- **Smart Change Detection**: Analyzes only modified code, not entire repository
- **Branch Comparison**: Compares any two branches (main vs. feature, staging vs. production)
- **Line-Level Precision**: Scans **only newly added lines** (lines with `+` in git diff), ignoring context lines and removed code
- **Statistics Generation**: Provides comprehensive diff statistics and threat metrics
- **Full Integration**: Works with all existing scan options (LLM, exploits, severity filtering)
#### **Scanning Scope (Updated)**
- ✅ **Newly added lines** (lines starting with `+` in git diff)
- ❌ **Context lines** (unchanged code shown for reference)
- ❌ **Removed lines** (deleted code)
- ❌ **Existing code** in the repository
#### **Example MCP Tool Usage:**
```bash
# Scan changes in current branch vs main
adv_diff_scan
source_branch="main"
target_branch="HEAD"
working_directory="/path/to/your/repo"
```
```bash
# Scan with high severity filter
adv_diff_scan
source_branch="main"
target_branch="HEAD"
severity_threshold="high"
working_directory="/path/to/your/repo"
```
## **🆕 Semgrep Integration**
### **Overview**
The Adversary MCP Server includes integrated Semgrep static analysis as a third party scanning engine.
### **Automatic Setup**
Semgrep integration works out-of-the-box with automatic detection:
```bash
# Check if Semgrep is available
adversary-mcp-cli status
# The status command will show:
# ✅ Semgrep: Available (Free tier)
# or
# ✅ Semgrep: Available (Pro tier) - if SEMGREP_APP_TOKEN is set
```
### **Free vs Pro Semgrep**
The integration automatically detects your Semgrep configuration:
#### **Free Semgrep** (Default)
- Uses Semgrep's built-in rule database
- No configuration required
- Community rules and patterns
### **Usage in MCP Tools**
- All MCP scanning tools support the `use_semgrep` parameter:
### **CLI Usage**
```bash
# Enable Semgrep in CLI scans
adversary-mcp-cli scan myproject/ --use-semgrep
# Combine all three engines (Rules + AI + Semgrep)
adversary-mcp-cli scan myproject/ --use-llm --use-semgrep
# Semgrep-only scanning (disable other engines)
adversary-mcp-cli scan myproject/ --no-llm --use-semgrep
# Semgrep with git diff scanning
adversary-mcp-cli scan --use-semgrep --source-branch=main --target-branch=HEAD
```
### **Configuration Options**
Semgrep behavior can be customized through configuration:
```bash
# Configure Semgrep settings
adversary-mcp-cli configure
# This will prompt for:
# - Semgrep timeout (default: 60 seconds)
# - Custom Semgrep config path (optional)
# - Specific rules to use (optional)
```
### **Smart Result Merging**
The integration intelligently combines results from all three scan engines:
```bash
# Example output showing merged results
adversary-mcp-cli scan app.py --use-llm --use-semgrep
# Results will show:
# Rules Engine: 2 threats found
# Semgrep: 3 threats found
# LLM Analysis: 1 additional threat found
# Total (after deduplication): 4 unique threats
```
### **JSON Output with Semgrep**
Get structured output including Semgrep findings:
```bash
# JSON output with all engines
adversary-mcp-cli scan app.py --use-semgrep --output=results.json
# The JSON will include:
# - semgrep_threats: Findings from Semgrep
# - llm_analysis: AI-generated prompts (if enabled)
# - scan_metadata: Detailed statistics
```
### **Installation Requirements**
Semgrep integration requires the Semgrep CLI tool:
```bash
# Install Semgrep (if not already installed)
pip install semgrep
# Verify installation
semgrep --version
# Check availability in Adversary MCP
adversary-mcp-cli status
```
## CLI Reference
### Core Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli configure` | Configure server settings, security thresholds, and Semgrep API key |
| `adversary-mcp-cli status` | Show current server status and configuration |
| `adversary-mcp-cli scan [TARGET]` | Scan files/directories for vulnerabilities |
| `adversary-mcp-cli demo` | Run demonstration of vulnerability scanner |
| `adversary-mcp-cli reset` | Reset all configuration and credentials |
| `adversary-mcp-cli reset-semgrep-key` | Remove stored Semgrep API key from keyring |
#### **Configure Options:**
- `--severity-threshold`: Default severity threshold (low, medium, high, critical)
- `--enable-safety-mode/--disable-safety-mode`: Enable/disable exploit safety mode
- `--llm-provider [openai|anthropic]`: Configure LLM provider for AI analysis
- `--clear-llm`: Clear all LLM configuration and API keys
### False Positive Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli mark-false-positive <UUID>` | Mark finding as false positive |
| `adversary-mcp-cli unmark-false-positive <UUID>` | Remove false positive marking |
| `adversary-mcp-cli list-false-positives` | List all false positive findings |
#### **False Positive Options:**
- `--reason TEXT`: Reason for marking as false positive
- `--reviewer TEXT`: Name of reviewer making the decision
### Scan Command Options
The `scan` command supports the following options:
| Option | Description | Default |
|--------|-------------|---------|
| `--source-branch` | Source branch for git diff scanning | None |
| `--target-branch` | Target branch for git diff scanning | None |
| `--language` | Target language (python, javascript, typescript) | Auto-detect |
| `--use-llm/--no-llm` | Enable/disable LLM analysis | `true` |
| `--use-semgrep/--no-semgrep` | Enable/disable Semgrep analysis | `true` |
| `--use-validation/--no-validation` | Enable/disable LLM validation (false positive filtering) | `true` |
| `--severity` | Minimum severity threshold (low, medium, high, critical) | None |
| `--output` | Output file for results (JSON format) | None |
| `--include-exploits` | Include exploit examples in results | `false` |
#### **Scanning Examples:**
```bash
# Scan a single file
adversary-mcp-cli scan app.py
# Scan a directory
adversary-mcp-cli scan /path/to/project
# Git diff scanning - compare branches
adversary-mcp-cli scan --source-branch=main --target-branch=feature/auth
# 🆕 Large monorepo scanning with optimization
adversary-mcp-cli scan /path/to/large-monorepo --use-semgrep --use-llm --severity=medium
# 🆕 Memory-efficient scanning for massive codebases
adversary-mcp-cli scan /path/to/monorepo --no-llm --use-semgrep --output=scan-results.json
# 🆕 Scan with LLM validation disabled (show all findings)
adversary-mcp-cli scan app.py --no-validation
# 🆕 Scan with all features enabled
adversary-mcp-cli scan app.py --use-llm --use-semgrep --use-validation --include-exploits
```
### **🆕 LLM Validation & False Positive Filtering**
The LLMValidator provides intelligent false positive filtering:
#### **How It Works:**
1. **Finding Analysis**: Each vulnerability is analyzed for legitimacy
2. **Confidence Scoring**: Assigns confidence levels (0.0-1.0) to findings
3. **Contextual Review**: Considers code context and patterns
4. **Exploit Generation**: Validates findings by generating proof-of-concepts
#### **Configuration:**
```bash
# Default confidence threshold: 0.7 (70%)
# Findings below this threshold are marked as false positives
# Disable validation to see all raw findings
adversary-mcp-cli scan app.py --no-validation
# Results show validation statistics:
# - Total findings: 10
# - Legitimate: 6 (60%)
# - False positives: 4 (40%)
# - Average confidence: 0.82
```
### Additional Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli --version` | Show version information |
| `adversary-mcp-cli --help` | Show help information |
---
## Security Coverage
#### **🆕 AI-Powered Vulnerability Detection**
- **Context-Aware Analysis**: Understands complex vulnerability patterns
- **Business Logic Flaws**: Identifies application-specific issues
- **Advanced Injection Variants**: Detects novel attack vectors
- **Compliance Violations**: Recognizes regulatory requirement breaches
- **Security Anti-Patterns**: Identifies poor security practices
#### **🆕 Semgrep Static Analysis**
- **Industry-Standard Scanning**: Leverages Semgrep's extensive rule database
- **Free & Pro Support**: Automatically detects `SEMGREP_APP_TOKEN` for Pro features
- **Smart Deduplication**: Intelligently merges Semgrep findings with LLM scanner engine results
- **Category Mapping**: Automatically maps Semgrep rule IDs to threat categories
- **Performance Optimized**: Efficient scanning with configurable timeouts
### **🆕 Enhanced Standards Compliance**
- **OWASP Top 10 2021** - Complete coverage with AI enhancement
- **CWE** - Common Weakness Enumeration mappings + AI categorization
- **NIST** - Security framework alignment with intelligent analysis
- **Industry best practices** - SANS, CERT guidelines + AI insights
## 🏗️ System Architecture
The Adversary MCP Server features a **hybrid multi-engine architecture** with integrated validation and **🆕 monorepo scalability**:
```mermaid
graph TB
subgraph "Client Layer"
A[Cursor IDE]
B[CLI Interface]
end
subgraph "Protocol Layer"
C[MCP Server]
D[CLI Commands]
end
A -->|MCP Protocol| C
B --> D
subgraph "Core Engine"
E[ScanEngine]
F[GitDiffScanner]
end
C --> E
D --> E
C --> F
D --> F
subgraph "Security Scanners"
G[SemgrepScanner]
H[LLMScanner]
end
E --> G
E --> H
F --> E
subgraph "Validation & Enhancement"
I[LLMValidator]
J[ExploitGenerator]
end
E --> I
I --> J
subgraph "Support Services"
K[FalsePositiveManager]
L[CredentialManager]
end
E --> K
E --> L
I --> L
subgraph "Data Flow"
M[ThreatMatch Objects]
N[ValidationResults]
O[EnhancedScanResult]
end
G --> M
H --> M
M --> I
I --> N
N --> O
style E fill:#e1f5fe
style I fill:#f3e5f5
style G fill:#e8f5e8
style H fill:#fff3e0
```
### **Multi-Engine Security Analysis**
The system combines three analysis approaches:
1. **Static Analysis (Semgrep)**: Industry-standard rule-based scanning
2. **AI Analysis (LLM)**: Real OpenAI/Anthropic integration for context-aware detection
3. **Intelligent Validation**: AI-powered false positive filtering with confidence scoring
### **Key Architecture Features**
- **Hybrid Engine Design**: Static + AI + Validation for comprehensive coverage
- **Real LLM Integration**: Direct API integration with OpenAI and Anthropic
- **Git-Aware Scanning**: Analyzes only changed code for efficient CI/CD
- **AI-Powered Validation**: LLMValidator reduces false positives by up to 70%
- **Batch Processing**: Intelligent file grouping for optimal LLM usage
- **Educational Enhancement**: AI-generated exploits with safety warnings
- **Rich Metadata**: Token usage, cost estimation, and performance metrics
### **🆕 Monorepo Scalability Features**
- **Unlimited File Processing**: No hardcoded limits, handles 100K+ files efficiently
- **Parallel Processing Engine**: AsyncIO-based concurrent file processing with semaphore control
- **Intelligent File Filtering**:
- Respects `.gitignore` and `.semgrepignore` patterns
- Excludes binary files automatically (400+ known extensions)
- Configurable file size limits (default: 10MB)
- Cross-platform path resolution (handles macOS symlinks)
- **Streaming Architecture**: Memory-efficient processing of large files with chunked I/O
- **Batch Processing**: Progressive results with configurable batch sizes (default: 50 files)
- **Performance Optimization**: Directory-level Semgrep scans instead of per-file execution
### **🆕 Advanced LLM Batch Processing**
The LLM scanner now features sophisticated batch processing for repository-scale analysis:
#### **Intelligent File Preprocessing:**
- **Complexity Scoring**: Analyzes code patterns to prioritize high-risk files
- **Language Grouping**: Batches files by language for optimal context
- **Dynamic Sizing**: Adjusts batch size based on token estimates
- **Smart Truncation**: Preserves code structure when reducing large files
#### **Batch Optimization Algorithm:**
```python
# Files are scored and batched based on:
1. Complexity indicators (eval, exec, SQL, crypto patterns)
2. File size and estimated token count
3. Language-specific considerations
4. Maximum token limits per batch
```
#### **Performance Benefits:**
- **70% faster** analysis for large repositories
- **50% reduction** in API costs through intelligent batching
- **Better context** for cross-file vulnerability detection
- **Automatic retry** with exponential backoff for reliability
### **🆕 Advanced Configuration**
### **🆕 JSON Output & Auto-Save**
#### **Structured JSON Output**
All MCP tools now support JSON output format for programmatic integration:
#### **Automatic JSON Generation**
When using MCP tools with `output_format: "json"`, results are automatically saved to the project root:
```
your-project/
├── .adversary.json
```
#### **Version Control Integration**
JSON files are automatically generated in your project root, making them perfect for:
- **Git tracking**: Commit scan results alongside code changes
- **CI/CD integration**: Parse JSON results in build pipelines
```bash
# Example CI/CD workflow
adversary-mcp-cli scan --source-branch=main --target-branch=HEAD --output=security-scan.json
git add security-scan.json
git commit -m "Security scan results for PR"
```
---
## Advanced Usage
### CI/CD Integration
#### **🆕 Git Diff-Aware CI/CD Scanning for Monorepos**
For efficient CI/CD pipelines in large codebases, scan only newly added lines in pull requests (perfect for monorepos with 10K+ files):
```yaml
# .github/workflows/security.yml
name: Security Analysis
on: [push, pull_request]
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Required for git diff analysis
- uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install Adversary MCP
run: pip install adversary-mcp-server
- name: Diff Security Scan (PR) - Scans only newly added lines
if: github.event_name == 'pull_request'
run: |
adversary-mcp-cli scan . \
--source-branch=origin/main \
--target-branch=HEAD \
--severity=medium \
--use-semgrep \
--use-llm \
--output=security-diff.json
env:
GITHUB_WORKSPACE: ${{ github.workspace }}
- name: Monorepo Security Scan (Push to main) - Optimized for large codebases
if: github.ref == 'refs/heads/main'
run: |
adversary-mcp-cli scan . \
--severity=medium \
--use-semgrep \
--no-llm \
--output=security-full.json
- name: Upload Results
uses: actions/upload-artifact@v3
with:
name: security-report
path: security-*.json
```
#### **Traditional Full Repository Scanning**
```yaml
# Traditional approach (scans entire repository)
- name: Full Security Scan
run: |
adversary-mcp-cli scan . \
--severity=medium \
--format=json \
--output=security-report.json
```
### Environment Configuration
```bash
# Configuration environment variables
export ADVERSARY_CONFIG_DIR="~/.local/share/adversary-mcp-server"
export ADVERSARY_LOG_LEVEL="INFO"
export ADVERSARY_SEVERITY_THRESHOLD="medium"
```
---
## Development
### Development Setup
```bash
# Clone repository
git clone https://github.com/brettbergin/adversary-mcp-server.git
cd adversary-mcp-server
# Install with uv (recommended)
pip install uv
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
# Or with traditional pip
make install
# Run tests
make test
# Code quality checks
make lint
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
---
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run the test suite: `make test`
5. Submit a pull request
### Version Management
The project uses centralized version management - you only need to update the version in one place:
1. **Update version in `pyproject.toml`:**
```toml
[project]
version = "0.7.5" # Update this line only
```
2. **All components automatically use the updated version:**
- CLI: `adversary-mcp-cli --version`
- Server: MCP server initialization
- Package: `from adversary_mcp_server import __version__`
3. **Lock file updates automatically:**
```bash
uv sync # Updates uv.lock with new version
```
**No manual updates needed** in `server.py` or elsewhere - the version is read dynamically from `pyproject.toml`.
---
## CI/CD Pipeline
### Automated Testing & Quality Assurance
The project uses GitHub Actions for comprehensive CI/CD automation:
#### **🔄 Continuous Integration** (`.github/workflows/ci.yml`)
**Multi-Environment Testing:**
- **Python versions**: 3.11, 3.12
- **Operating systems**: Ubuntu, macOS, Windows
- **Dependencies**: Automatic uv-based installation
**Quality Gates:**
- ✅ **Unit Tests**: 400+ tests with 80% coverage requirement
- ✅ **Code Quality**: Ruff linting, MyPy type checking, Black formatting
- ✅ **Security Scans**: Bandit, Semgrep, Safety dependency checks
- ✅ **Build Verification**: Package building and installation testing
- ✅ **Integration Tests**: Real CLI and scanning functionality
#### **🚀 Release Automation** (`.github/workflows/release.yml`)
**Automated Publishing:**
- Version consistency validation
- Security scan verification
- PyPI package publishing
- Docker image building
- GitHub release creation
#### **🔒 Dependency Management** (`.github/workflows/dependency-updates.yml`)
**Weekly Security Monitoring:**
- Automated dependency updates
- Vulnerability scanning
- Security issue creation
- PR generation for updates
#### **📊 Status Monitoring** (`.github/workflows/status-badges.yml`)
**Live Project Metrics:**
- Test count and status tracking
- Coverage percentage monitoring
- Version and rule count updates
- Automated badge updates
### Development Workflow
```bash
# All checks run automatically on push/PR
git push origin feature-branch
# Manual quality checks
make check-all # Run all linting, tests, and security scans
```
### Contributing & Quality Standards
See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for:
- Development setup instructions
- Code quality requirements
- Testing guidelines
- Security standards
- Release process
---
## Support
- **Documentation**: [GitHub Wiki](https://github.com/brettbergin/adversary-mcp-server/wiki)
- **Issues**: [GitHub Issues](https://github.com/brettbergin/adversary-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/brettbergin/adversary-mcp-server/discussions)
---
<div align="center">
**Built with ❤️ for secure development**
</div>
## Important Notes
### Diff Scanning Scope
The `adv_diff_scan` tool **only scans newly added lines** (lines starting with `+` in git diff), not context lines or existing code. This prevents false positives from flagging existing code as new vulnerabilities.
**What gets scanned:**
- ✅ Newly added lines (actual changes)
- ❌ Context lines (unchanged code shown for reference)
- ❌ Removed lines (deleted code)
This means you'll only see security issues for code you've actually added or modified, not for existing code in the repository.
## Troubleshooting
### Git Diff Scanning Issues
If you encounter the error `"Failed to get diff summary"` when using `adv_diff_scan`, this is typically caused by one of these issues:
#### **Common Causes & Solutions:**
1. **Working Directory Issue**
```
Error: Tool adv_diff_scan failed: Diff scanning failed: Git diff operation failed: Failed to get diff summary
```
**Solution:** Specify the correct working directory:
```json
{
"source_branch": "main",
"target_branch": "feature/my-branch",
"working_directory": "/path/to/your/git/repository"
}
```
2. **Branch Not Found**
```
Error: Branch validation failed: Branch not found
```
**Solution:** Verify branch names exist:
```bash
cd /path/to/your/repo
git branch -a # List all branches
```
3. **Not a Git Repository**
```
Error: Git command failed: fatal: not a git repository
```
**Solution:** Ensure you're pointing to a valid git repository:
```json
{
"working_directory": "/path/to/valid/git/repo"
}
```
4. **Git Not Available**
```
Error: Git command not found
```
**Solution:** Install git or ensure it's in your PATH.
#### **Best Practices:**
- Always specify the `working_directory` parameter when the repository is not in the current directory
- Use full/absolute paths for `working_directory` to avoid confusion
- Verify branch names with `git branch -a` before running scans
- For remote branches, use the full name (e.g., `origin/main` not just `main`)
Raw data
{
"_id": null,
"home_page": null,
"name": "adversary-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"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/03/ec/6a04ab1f2bfaa92fd4682a1b31435ad9a062a4697647f9a62907bb4e919a/adversary_mcp_server-1.0.3.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**Enterprise-grade security analysis with real AI-powered vulnerability detection and validation. Features integrated OpenAI/Anthropic LLM support, intelligent false positive filtering, and batch processing optimization for large repositories. Implemented as an MCP server as well as a command-line interface.**\n\n**We think about your vulns so you dont have to.**\n\n[Installation](#installation) \u2022 [Quick Start](#quick-start) \u2022 [AI-Powered Analysis](#ai-powered-analysis) \u2022 [MCP Integration](#mcp-integration) \u2022 [Rule Management](#rule-management) \u2022 [CLI Reference](#cli-reference)\n\n</div>\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Python 3.11+** (3.11+ recommended)\n- **uv** (https://astral.sh/uv/)\n- **semgrep** (https://semgrep.dev/docs/)\n- **Cursor IDE** with MCP support\n\n### Quick Install\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n```bash\nbrew install semgrep\n```\n```bash\nuv pip install adversary-mcp-server\n```\n\n### Verify Installation\n\n```bash\nadversary-mcp-cli --version\nadversary-mcp-cli status\n```\n\n---\n\n## Quick Start\n\n### 1. Initial Setup\n\n```bash\n# Configure the security engine\nadversary-mcp-cli configure\n\n# Configure LLM provider (OpenAI or Anthropic) for AI-powered analysis\nadversary-mcp-cli configure --llm-provider openai\n# or\nadversary-mcp-cli configure --llm-provider anthropic\n\n# Check server status\nadversary-mcp-cli status\n```\n\n### 2. Cursor IDE Integration\n\nCreate `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:\n\n#### **Recommended: Using `uv` (Modern Python Package Manager)**\n\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"adversary-mcp-server\"],\n \"env\": {\n \"ADVERSARY_WORKSPACE_ROOT\": \"/path/to/your/project\"\n }\n }\n }\n}\n```\n\n#### **Alternative: Using `pip` Installation**\n\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"python\",\n \"args\": [\n \"-m\",\n \"adversary_mcp_server.server\"\n ],\n \"env\": {\n \"ADVERSARY_WORKSPACE_ROOT\": \"/path/to/your/project\"\n }\n }\n }\n}\n```\n\n#### **Development: Local Repository**\n\n```json\n{\n \"mcpServers\": {\n \"adversary\": {\n \"command\": \"~/code/adversary-mcp-server/.venv/bin/python\",\n \"args\": [\n \"-m\",\n \"adversary_mcp_server.server\"\n ],\n \"env\": {\n \"ADVERSARY_WORKSPACE_ROOT\": \"/path/to/your/project\"\n }\n }\n }\n}\n```\n\n**\ud83d\udca1 Workspace Path Resolution:**\n\nIf you experience issues with @ mentioned files/folders not being found, set the `ADVERSARY_WORKSPACE_ROOT` environment variable to your actual project directory. This is especially useful when:\n\n- Using @ mentions in Cursor that reference relative paths\n- The MCP server's working directory doesn't match your project workspace\n- Scanning files/folders from different directories\n- **\ud83c\udd95 Large monorepos**: Ensures efficient path resolution for repositories with thousands of files\n\n### 3. Start Using in Cursor\n\nOnce configured, you can use these MCP tools in Cursor:\n\n- `adv_scan_code` - Hybrid scanning with rules + AI analysis\n- `adv_scan_file` - file scanning with LLM support\n- `adv_scan_folder` - directory scanning\n- `adv_diff_scan` - scans only changed files between branches\n- `adv_configure_settings` - Configuration management\n- `adv_get_status` - Check server status and AI availability\n- `adv_get_version` - Get version information\n- `adv_mark_false_positive` - Mark false positive\n- `adv_unmark_false_positive` - Unmark false positive\n\n\n### \ud83c\udfd7\ufe0f System Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n A[Cursor IDE]\n B[CLI Interface]\n end\n\n subgraph \"Protocol Layer\"\n C[MCP Server]\n D[CLI Commands]\n end\n\n A -->|MCP Protocol| C\n B --> D\n\n subgraph \"Core Engine\"\n E[ScanEngine]\n F[GitDiffScanner]\n end\n\n C --> E\n D --> E\n C --> F\n D --> F\n\n subgraph \"Security Scanners\"\n G[SemgrepScanner]\n H[LLMScanner]\n end\n\n E --> G\n E --> H\n F --> E\n\n subgraph \"Validation & Enhancement\"\n I[LLMValidator]\n J[ExploitGenerator]\n end\n\n E --> I\n I --> J\n\n subgraph \"Support Services\"\n K[FalsePositiveManager]\n L[CredentialManager]\n end\n\n E --> K\n E --> L\n I --> L\n\n subgraph \"Data Flow\"\n M[ThreatMatch Objects]\n N[ValidationResults]\n O[EnhancedScanResult]\n end\n\n G --> M\n H --> M\n M --> I\n I --> N\n N --> O\n\n style E fill:#e1f5fe\n style I fill:#f3e5f5\n style G fill:#e8f5e8\n style H fill:#fff3e0\n```\n\n### 4. Run Demo (Optional)\n\nTest the scanner with vulnerable code examples:\n\n```bash\n# Run interactive demonstration\nadversary-mcp-cli demo\n```\n\n### 5. **\ud83c\udd95 Git Diff-Aware Scanning**\n\nScan only changed files between git branches for efficient CI/CD integration:\n\n```bash\n# Scan changes between branches\nadversary-mcp-cli scan --source-branch=main --target-branch=feature/auth\n\n# Scan with high severity filter\nadversary-mcp-cli scan --source-branch=main --target-branch=HEAD --severity=high --use-llm --use-semgrep\n```\n\n### 6. **\ud83c\udd95 Large Monorepo Support**\n\nThe scanner now supports large corporate monorepos with advanced scalability features:\n\n#### **Key Monorepo Features:**\n- **\ud83d\ude80 Unlimited File Scanning**: Removed 50-file limit, can handle 100K+ files\n- **\u26a1 Parallel Processing**: Concurrent file processing with intelligent batching\n- **\ud83e\udde0 Smart File Filtering**: Respects `.gitignore`, excludes binaries, and filters by size\n- **\ud83d\udcbe Streaming Architecture**: Memory-efficient handling of large files\n- **\ud83d\udcca Batch Processing**: Progressive results without memory overflow\n\n#### **MCP Tool Usage for Large Codebases:**\n```bash\n# Scan large monorepo with intelligent filtering\nadv_scan_folder\n directory_path=@/path/to/large-monorepo\n recursive=true\n use_llm=true\n use_semgrep=true\n output_format=json\n output=@/.adversary.json\n\n# Efficient diff scanning for monorepos (CI/CD optimized)\nadv_diff_scan\n source_branch=\"main\"\n target_branch=\"HEAD\"\n working_directory=\"/path/to/monorepo\"\n severity_threshold=\"medium\"\n```\n\n#### **Performance Optimizations:**\n- **Directory-level Semgrep**: Runs once per directory instead of per file\n- **Intelligent Batching**: Processes files in optimized batches of 50\n- **Memory Management**: Streaming prevents memory issues with large codebases\n- **Concurrent Workers**: Uses `min(32, cpu_count + 4, file_count)` for optimal performance\n\n---\n\n### ** MCP Tool Scanning **\n\n```bash\n# Scan with Semgrep + LLM\nadv_scan_folder\n directory_path=@/path/to/repo\n recursive=true\n include_exploits=false\n use_llm=true\n use_semgrep=true\n output_format=text\n output=@/path/to/.adversary.json\n```\n```bash\n# Scan with Semgrep Only\nadv_scan_folder\n directory_path=@/path/to/repo\n recursive=true\n include_exploits=false\n use_llm=false\n use_semgrep=true\n output_format=text\n output=@/path/to/.adversary.json\n```\n\n### **\ud83d\ude80 Real LLM Integration (NEW)**\n\nThe Adversary MCP Server now features **real AI integration** with OpenAI and Anthropic, replacing the previous client-based stub system:\n\n#### **Key Features:**\n- **\ud83e\udd16 Multiple LLM Providers**: Support for OpenAI (GPT-4) and Anthropic (Claude 3.5)\n- **\ud83d\udd10 Secure API Key Storage**: Uses system keyring for secure credential management\n- **\ud83c\udfaf Intelligent Validation**: LLMValidator reduces false positives by up to 70%\n- **\ud83d\udce6 Batch Processing**: Optimized for large repositories with intelligent file batching\n- **\ud83d\udcb0 Cost Optimization**: Token usage tracking and smart content truncation\n- **\ud83d\udd04 Retry Logic**: Automatic retry with exponential backoff for API reliability\n\n#### **Configuration:**\n```bash\n# Configure OpenAI\nadversary-mcp-cli configure --llm-provider openai\n# Enter your OpenAI API key when prompted\n# Optional: Choose model (default: gpt-4-turbo-preview)\n\n# Configure Anthropic\nadversary-mcp-cli configure --llm-provider anthropic\n# Enter your Anthropic API key when prompted\n# Optional: Choose model (default: claude-3-5-sonnet-20241022)\n\n# Clear LLM configuration\nadversary-mcp-cli configure --clear-llm\n```\n\n#### **Available Models:**\n- **OpenAI**: gpt-4-turbo-preview, gpt-4o, gpt-4, gpt-3.5-turbo\n- **Anthropic**: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-latest\n\n### **AI Analysis Features**\n\n- **\ud83c\udfaf Smart Threat Detection**: Context-aware vulnerability identification\n- **\ud83d\udcca Confidence Scoring**: Each finding includes confidence levels (0.0-1.0)\n- **\ud83d\udd0d Detailed Explanations**: Natural language descriptions of vulnerabilities\n- **\ud83c\udff7\ufe0f CWE/OWASP Mapping**: Automatic categorization with industry standards\n- **\u26a1 Intelligent Deduplication**: Merges similar findings from multiple engines\n- **\ud83d\udee1\ufe0f False Positive Filtering**: LLMValidator analyzes and filters noise\n- **\ud83d\udca1 Exploitation Analysis**: Generates proof-of-concept exploits with safety warnings\n\n---\n\n## MCP Integration\n\n### Available Tools\n\n| Tool | Description | **\ud83c\udd95 AI Features** |\n|------|-------------|-------------------|\n| `adv_scan_code` | source code scanning | confidence scoring |\n| `adv_scan_file` | file scanning | AI-powered prompts, detailed explanations |\n| `adv_scan_folder` | directory scanning | statistical insights |\n| `adv_diff_scan` | scans only newly added lines | Smart change detection, branch comparison, requires `working_directory` |\n| `adv_configure_settings` | configuration management | LLM settings, validation |\n| `adv_get_status` | Get server status | LLM configuration status |\n| `adv_get_version` | Get version information | Shows AI capabilities |\n| `adv_mark_false_positive` | Mark false positive | Mark false positive |\n| `adv_unmark_false_positive` | Unmark false positive | unmark false positive |\n\n### **\ud83c\udd95 Git Diff-Aware Scanning**\n\nThe `adv_diff_scan` tool enables intelligent scanning of only changed files between git branches:\n\n#### **Key Features:**\n- **Smart Change Detection**: Analyzes only modified code, not entire repository\n- **Branch Comparison**: Compares any two branches (main vs. feature, staging vs. production)\n- **Line-Level Precision**: Scans **only newly added lines** (lines with `+` in git diff), ignoring context lines and removed code\n- **Statistics Generation**: Provides comprehensive diff statistics and threat metrics\n- **Full Integration**: Works with all existing scan options (LLM, exploits, severity filtering)\n\n#### **Scanning Scope (Updated)**\n- \u2705 **Newly added lines** (lines starting with `+` in git diff)\n- \u274c **Context lines** (unchanged code shown for reference)\n- \u274c **Removed lines** (deleted code)\n- \u274c **Existing code** in the repository\n\n\n#### **Example MCP Tool Usage:**\n```bash\n# Scan changes in current branch vs main\nadv_diff_scan\n source_branch=\"main\"\n target_branch=\"HEAD\"\n working_directory=\"/path/to/your/repo\"\n```\n```bash\n# Scan with high severity filter\nadv_diff_scan\n source_branch=\"main\"\n target_branch=\"HEAD\"\n severity_threshold=\"high\"\n working_directory=\"/path/to/your/repo\"\n```\n\n## **\ud83c\udd95 Semgrep Integration**\n\n### **Overview**\n\nThe Adversary MCP Server includes integrated Semgrep static analysis as a third party scanning engine.\n\n### **Automatic Setup**\nSemgrep integration works out-of-the-box with automatic detection:\n\n```bash\n# Check if Semgrep is available\nadversary-mcp-cli status\n\n# The status command will show:\n# \u2705 Semgrep: Available (Free tier)\n# or\n# \u2705 Semgrep: Available (Pro tier) - if SEMGREP_APP_TOKEN is set\n```\n\n### **Free vs Pro Semgrep**\n\nThe integration automatically detects your Semgrep configuration:\n\n#### **Free Semgrep** (Default)\n- Uses Semgrep's built-in rule database\n- No configuration required\n- Community rules and patterns\n\n### **Usage in MCP Tools**\n- All MCP scanning tools support the `use_semgrep` parameter:\n\n### **CLI Usage**\n\n```bash\n# Enable Semgrep in CLI scans\nadversary-mcp-cli scan myproject/ --use-semgrep\n\n# Combine all three engines (Rules + AI + Semgrep)\nadversary-mcp-cli scan myproject/ --use-llm --use-semgrep\n\n# Semgrep-only scanning (disable other engines)\nadversary-mcp-cli scan myproject/ --no-llm --use-semgrep\n\n# Semgrep with git diff scanning\nadversary-mcp-cli scan --use-semgrep --source-branch=main --target-branch=HEAD\n```\n\n### **Configuration Options**\n\nSemgrep behavior can be customized through configuration:\n\n```bash\n# Configure Semgrep settings\nadversary-mcp-cli configure\n# This will prompt for:\n# - Semgrep timeout (default: 60 seconds)\n# - Custom Semgrep config path (optional)\n# - Specific rules to use (optional)\n```\n\n### **Smart Result Merging**\n\nThe integration intelligently combines results from all three scan engines:\n\n```bash\n# Example output showing merged results\nadversary-mcp-cli scan app.py --use-llm --use-semgrep\n\n# Results will show:\n# Rules Engine: 2 threats found\n# Semgrep: 3 threats found\n# LLM Analysis: 1 additional threat found\n# Total (after deduplication): 4 unique threats\n```\n\n### **JSON Output with Semgrep**\n\nGet structured output including Semgrep findings:\n\n```bash\n# JSON output with all engines\nadversary-mcp-cli scan app.py --use-semgrep --output=results.json\n\n# The JSON will include:\n# - semgrep_threats: Findings from Semgrep\n# - llm_analysis: AI-generated prompts (if enabled)\n# - scan_metadata: Detailed statistics\n```\n\n### **Installation Requirements**\n\nSemgrep integration requires the Semgrep CLI tool:\n\n```bash\n# Install Semgrep (if not already installed)\npip install semgrep\n\n# Verify installation\nsemgrep --version\n\n# Check availability in Adversary MCP\nadversary-mcp-cli status\n```\n\n\n## CLI Reference\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli configure` | Configure server settings, security thresholds, and Semgrep API key |\n| `adversary-mcp-cli status` | Show current server status and configuration |\n| `adversary-mcp-cli scan [TARGET]` | Scan files/directories for vulnerabilities |\n| `adversary-mcp-cli demo` | Run demonstration of vulnerability scanner |\n| `adversary-mcp-cli reset` | Reset all configuration and credentials |\n| `adversary-mcp-cli reset-semgrep-key` | Remove stored Semgrep API key from keyring |\n\n#### **Configure Options:**\n\n- `--severity-threshold`: Default severity threshold (low, medium, high, critical)\n- `--enable-safety-mode/--disable-safety-mode`: Enable/disable exploit safety mode\n- `--llm-provider [openai|anthropic]`: Configure LLM provider for AI analysis\n- `--clear-llm`: Clear all LLM configuration and API keys\n\n### False Positive Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli mark-false-positive <UUID>` | Mark finding as false positive |\n| `adversary-mcp-cli unmark-false-positive <UUID>` | Remove false positive marking |\n| `adversary-mcp-cli list-false-positives` | List all false positive findings |\n\n#### **False Positive Options:**\n\n- `--reason TEXT`: Reason for marking as false positive\n- `--reviewer TEXT`: Name of reviewer making the decision\n\n### Scan Command Options\n\nThe `scan` command supports the following options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--source-branch` | Source branch for git diff scanning | None |\n| `--target-branch` | Target branch for git diff scanning | None |\n| `--language` | Target language (python, javascript, typescript) | Auto-detect |\n| `--use-llm/--no-llm` | Enable/disable LLM analysis | `true` |\n| `--use-semgrep/--no-semgrep` | Enable/disable Semgrep analysis | `true` |\n| `--use-validation/--no-validation` | Enable/disable LLM validation (false positive filtering) | `true` |\n| `--severity` | Minimum severity threshold (low, medium, high, critical) | None |\n| `--output` | Output file for results (JSON format) | None |\n| `--include-exploits` | Include exploit examples in results | `false` |\n\n#### **Scanning Examples:**\n```bash\n# Scan a single file\nadversary-mcp-cli scan app.py\n\n# Scan a directory\nadversary-mcp-cli scan /path/to/project\n\n# Git diff scanning - compare branches\nadversary-mcp-cli scan --source-branch=main --target-branch=feature/auth\n\n# \ud83c\udd95 Large monorepo scanning with optimization\nadversary-mcp-cli scan /path/to/large-monorepo --use-semgrep --use-llm --severity=medium\n\n# \ud83c\udd95 Memory-efficient scanning for massive codebases\nadversary-mcp-cli scan /path/to/monorepo --no-llm --use-semgrep --output=scan-results.json\n\n# \ud83c\udd95 Scan with LLM validation disabled (show all findings)\nadversary-mcp-cli scan app.py --no-validation\n\n# \ud83c\udd95 Scan with all features enabled\nadversary-mcp-cli scan app.py --use-llm --use-semgrep --use-validation --include-exploits\n```\n\n### **\ud83c\udd95 LLM Validation & False Positive Filtering**\n\nThe LLMValidator provides intelligent false positive filtering:\n\n#### **How It Works:**\n1. **Finding Analysis**: Each vulnerability is analyzed for legitimacy\n2. **Confidence Scoring**: Assigns confidence levels (0.0-1.0) to findings\n3. **Contextual Review**: Considers code context and patterns\n4. **Exploit Generation**: Validates findings by generating proof-of-concepts\n\n#### **Configuration:**\n```bash\n# Default confidence threshold: 0.7 (70%)\n# Findings below this threshold are marked as false positives\n\n# Disable validation to see all raw findings\nadversary-mcp-cli scan app.py --no-validation\n\n# Results show validation statistics:\n# - Total findings: 10\n# - Legitimate: 6 (60%)\n# - False positives: 4 (40%)\n# - Average confidence: 0.82\n```\n\n### Additional Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli --version` | Show version information |\n| `adversary-mcp-cli --help` | Show help information |\n\n---\n\n## Security Coverage\n\n#### **\ud83c\udd95 AI-Powered Vulnerability Detection**\n- **Context-Aware Analysis**: Understands complex vulnerability patterns\n- **Business Logic Flaws**: Identifies application-specific issues\n- **Advanced Injection Variants**: Detects novel attack vectors\n- **Compliance Violations**: Recognizes regulatory requirement breaches\n- **Security Anti-Patterns**: Identifies poor security practices\n\n#### **\ud83c\udd95 Semgrep Static Analysis**\n- **Industry-Standard Scanning**: Leverages Semgrep's extensive rule database\n- **Free & Pro Support**: Automatically detects `SEMGREP_APP_TOKEN` for Pro features\n- **Smart Deduplication**: Intelligently merges Semgrep findings with LLM scanner engine results\n- **Category Mapping**: Automatically maps Semgrep rule IDs to threat categories\n- **Performance Optimized**: Efficient scanning with configurable timeouts\n\n### **\ud83c\udd95 Enhanced Standards Compliance**\n\n- **OWASP Top 10 2021** - Complete coverage with AI enhancement\n- **CWE** - Common Weakness Enumeration mappings + AI categorization\n- **NIST** - Security framework alignment with intelligent analysis\n- **Industry best practices** - SANS, CERT guidelines + AI insights\n\n\n## \ud83c\udfd7\ufe0f System Architecture\n\nThe Adversary MCP Server features a **hybrid multi-engine architecture** with integrated validation and **\ud83c\udd95 monorepo scalability**:\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n A[Cursor IDE]\n B[CLI Interface]\n end\n\n subgraph \"Protocol Layer\"\n C[MCP Server]\n D[CLI Commands]\n end\n\n A -->|MCP Protocol| C\n B --> D\n\n subgraph \"Core Engine\"\n E[ScanEngine]\n F[GitDiffScanner]\n end\n\n C --> E\n D --> E\n C --> F\n D --> F\n\n subgraph \"Security Scanners\"\n G[SemgrepScanner]\n H[LLMScanner]\n end\n\n E --> G\n E --> H\n F --> E\n\n subgraph \"Validation & Enhancement\"\n I[LLMValidator]\n J[ExploitGenerator]\n end\n\n E --> I\n I --> J\n\n subgraph \"Support Services\"\n K[FalsePositiveManager]\n L[CredentialManager]\n end\n\n E --> K\n E --> L\n I --> L\n\n subgraph \"Data Flow\"\n M[ThreatMatch Objects]\n N[ValidationResults]\n O[EnhancedScanResult]\n end\n\n G --> M\n H --> M\n M --> I\n I --> N\n N --> O\n\n style E fill:#e1f5fe\n style I fill:#f3e5f5\n style G fill:#e8f5e8\n style H fill:#fff3e0\n```\n\n### **Multi-Engine Security Analysis**\n\nThe system combines three analysis approaches:\n\n1. **Static Analysis (Semgrep)**: Industry-standard rule-based scanning\n2. **AI Analysis (LLM)**: Real OpenAI/Anthropic integration for context-aware detection\n3. **Intelligent Validation**: AI-powered false positive filtering with confidence scoring\n\n### **Key Architecture Features**\n\n- **Hybrid Engine Design**: Static + AI + Validation for comprehensive coverage\n- **Real LLM Integration**: Direct API integration with OpenAI and Anthropic\n- **Git-Aware Scanning**: Analyzes only changed code for efficient CI/CD\n- **AI-Powered Validation**: LLMValidator reduces false positives by up to 70%\n- **Batch Processing**: Intelligent file grouping for optimal LLM usage\n- **Educational Enhancement**: AI-generated exploits with safety warnings\n- **Rich Metadata**: Token usage, cost estimation, and performance metrics\n\n### **\ud83c\udd95 Monorepo Scalability Features**\n\n- **Unlimited File Processing**: No hardcoded limits, handles 100K+ files efficiently\n- **Parallel Processing Engine**: AsyncIO-based concurrent file processing with semaphore control\n- **Intelligent File Filtering**:\n - Respects `.gitignore` and `.semgrepignore` patterns\n - Excludes binary files automatically (400+ known extensions)\n - Configurable file size limits (default: 10MB)\n - Cross-platform path resolution (handles macOS symlinks)\n- **Streaming Architecture**: Memory-efficient processing of large files with chunked I/O\n- **Batch Processing**: Progressive results with configurable batch sizes (default: 50 files)\n- **Performance Optimization**: Directory-level Semgrep scans instead of per-file execution\n\n### **\ud83c\udd95 Advanced LLM Batch Processing**\n\nThe LLM scanner now features sophisticated batch processing for repository-scale analysis:\n\n#### **Intelligent File Preprocessing:**\n- **Complexity Scoring**: Analyzes code patterns to prioritize high-risk files\n- **Language Grouping**: Batches files by language for optimal context\n- **Dynamic Sizing**: Adjusts batch size based on token estimates\n- **Smart Truncation**: Preserves code structure when reducing large files\n\n#### **Batch Optimization Algorithm:**\n```python\n# Files are scored and batched based on:\n1. Complexity indicators (eval, exec, SQL, crypto patterns)\n2. File size and estimated token count\n3. Language-specific considerations\n4. Maximum token limits per batch\n```\n\n#### **Performance Benefits:**\n- **70% faster** analysis for large repositories\n- **50% reduction** in API costs through intelligent batching\n- **Better context** for cross-file vulnerability detection\n- **Automatic retry** with exponential backoff for reliability\n\n### **\ud83c\udd95 Advanced Configuration**\n\n\n### **\ud83c\udd95 JSON Output & Auto-Save**\n\n#### **Structured JSON Output**\n\nAll MCP tools now support JSON output format for programmatic integration:\n\n\n#### **Automatic JSON Generation**\n\nWhen using MCP tools with `output_format: \"json\"`, results are automatically saved to the project root:\n\n```\nyour-project/\n\u251c\u2500\u2500 .adversary.json\n```\n\n#### **Version Control Integration**\n\nJSON files are automatically generated in your project root, making them perfect for:\n\n- **Git tracking**: Commit scan results alongside code changes\n- **CI/CD integration**: Parse JSON results in build pipelines\n\n```bash\n# Example CI/CD workflow\nadversary-mcp-cli scan --source-branch=main --target-branch=HEAD --output=security-scan.json\ngit add security-scan.json\ngit commit -m \"Security scan results for PR\"\n```\n\n---\n\n## Advanced Usage\n\n### CI/CD Integration\n\n#### **\ud83c\udd95 Git Diff-Aware CI/CD Scanning for Monorepos**\n\nFor efficient CI/CD pipelines in large codebases, scan only newly added lines in pull requests (perfect for monorepos with 10K+ files):\n\n```yaml\n# .github/workflows/security.yml\nname: Security Analysis\non: [push, pull_request]\n\njobs:\n security-scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0 # Required for git diff analysis\n\n - uses: actions/setup-python@v4\n with:\n python-version: '3.11'\n\n - name: Install Adversary MCP\n run: pip install adversary-mcp-server\n\n - name: Diff Security Scan (PR) - Scans only newly added lines\n if: github.event_name == 'pull_request'\n run: |\n adversary-mcp-cli scan . \\\n --source-branch=origin/main \\\n --target-branch=HEAD \\\n --severity=medium \\\n --use-semgrep \\\n --use-llm \\\n --output=security-diff.json\n env:\n GITHUB_WORKSPACE: ${{ github.workspace }}\n\n - name: Monorepo Security Scan (Push to main) - Optimized for large codebases\n if: github.ref == 'refs/heads/main'\n run: |\n adversary-mcp-cli scan . \\\n --severity=medium \\\n --use-semgrep \\\n --no-llm \\\n --output=security-full.json\n\n - name: Upload Results\n uses: actions/upload-artifact@v3\n with:\n name: security-report\n path: security-*.json\n```\n\n#### **Traditional Full Repository Scanning**\n\n```yaml\n# Traditional approach (scans entire repository)\n- name: Full Security Scan\n run: |\n adversary-mcp-cli scan . \\\n --severity=medium \\\n --format=json \\\n --output=security-report.json\n```\n\n### Environment Configuration\n\n```bash\n# Configuration environment variables\nexport ADVERSARY_CONFIG_DIR=\"~/.local/share/adversary-mcp-server\"\nexport ADVERSARY_LOG_LEVEL=\"INFO\"\nexport ADVERSARY_SEVERITY_THRESHOLD=\"medium\"\n```\n\n---\n\n## Development\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/brettbergin/adversary-mcp-server.git\ncd adversary-mcp-server\n\n# Install with uv (recommended)\npip install uv\nuv venv\nsource .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# Or with traditional pip\nmake install\n\n# Run tests\nmake test\n\n# Code quality checks\nmake lint\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Run the test suite: `make test`\n5. Submit a pull request\n\n### Version Management\n\nThe project uses centralized version management - you only need to update the version in one place:\n\n1. **Update version in `pyproject.toml`:**\n ```toml\n [project]\n version = \"0.7.5\" # Update this line only\n ```\n\n2. **All components automatically use the updated version:**\n - CLI: `adversary-mcp-cli --version`\n - Server: MCP server initialization\n - Package: `from adversary_mcp_server import __version__`\n\n3. **Lock file updates automatically:**\n ```bash\n uv sync # Updates uv.lock with new version\n ```\n\n**No manual updates needed** in `server.py` or elsewhere - the version is read dynamically from `pyproject.toml`.\n\n---\n\n## CI/CD Pipeline\n\n### Automated Testing & Quality Assurance\n\nThe project uses GitHub Actions for comprehensive CI/CD automation:\n\n#### **\ud83d\udd04 Continuous Integration** (`.github/workflows/ci.yml`)\n\n**Multi-Environment Testing:**\n- **Python versions**: 3.11, 3.12\n- **Operating systems**: Ubuntu, macOS, Windows\n- **Dependencies**: Automatic uv-based installation\n\n**Quality Gates:**\n- \u2705 **Unit Tests**: 400+ tests with 80% coverage requirement\n- \u2705 **Code Quality**: Ruff linting, MyPy type checking, Black formatting\n- \u2705 **Security Scans**: Bandit, Semgrep, Safety dependency checks\n- \u2705 **Build Verification**: Package building and installation testing\n- \u2705 **Integration Tests**: Real CLI and scanning functionality\n\n#### **\ud83d\ude80 Release Automation** (`.github/workflows/release.yml`)\n\n**Automated Publishing:**\n- Version consistency validation\n- Security scan verification\n- PyPI package publishing\n- Docker image building\n- GitHub release creation\n\n#### **\ud83d\udd12 Dependency Management** (`.github/workflows/dependency-updates.yml`)\n\n**Weekly Security Monitoring:**\n- Automated dependency updates\n- Vulnerability scanning\n- Security issue creation\n- PR generation for updates\n\n#### **\ud83d\udcca Status Monitoring** (`.github/workflows/status-badges.yml`)\n\n**Live Project Metrics:**\n- Test count and status tracking\n- Coverage percentage monitoring\n- Version and rule count updates\n- Automated badge updates\n\n### Development Workflow\n\n```bash\n# All checks run automatically on push/PR\ngit push origin feature-branch\n\n# Manual quality checks\nmake check-all # Run all linting, tests, and security scans\n```\n\n### Contributing & Quality Standards\n\nSee [CONTRIBUTING.md](.github/CONTRIBUTING.md) for:\n- Development setup instructions\n- Code quality requirements\n- Testing guidelines\n- Security standards\n- Release process\n\n---\n\n## Support\n\n- **Documentation**: [GitHub Wiki](https://github.com/brettbergin/adversary-mcp-server/wiki)\n- **Issues**: [GitHub Issues](https://github.com/brettbergin/adversary-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/brettbergin/adversary-mcp-server/discussions)\n\n---\n\n<div align=\"center\">\n\n**Built with \u2764\ufe0f for secure development**\n\n</div>\n\n## Important Notes\n\n### Diff Scanning Scope\n\nThe `adv_diff_scan` tool **only scans newly added lines** (lines starting with `+` in git diff), not context lines or existing code. This prevents false positives from flagging existing code as new vulnerabilities.\n\n**What gets scanned:**\n- \u2705 Newly added lines (actual changes)\n- \u274c Context lines (unchanged code shown for reference)\n- \u274c Removed lines (deleted code)\n\nThis means you'll only see security issues for code you've actually added or modified, not for existing code in the repository.\n\n## Troubleshooting\n\n### Git Diff Scanning Issues\n\nIf you encounter the error `\"Failed to get diff summary\"` when using `adv_diff_scan`, this is typically caused by one of these issues:\n\n#### **Common Causes & Solutions:**\n\n1. **Working Directory Issue**\n ```\n Error: Tool adv_diff_scan failed: Diff scanning failed: Git diff operation failed: Failed to get diff summary\n ```\n\n **Solution:** Specify the correct working directory:\n ```json\n {\n \"source_branch\": \"main\",\n \"target_branch\": \"feature/my-branch\",\n \"working_directory\": \"/path/to/your/git/repository\"\n }\n ```\n\n2. **Branch Not Found**\n ```\n Error: Branch validation failed: Branch not found\n ```\n\n **Solution:** Verify branch names exist:\n ```bash\n cd /path/to/your/repo\n git branch -a # List all branches\n ```\n\n3. **Not a Git Repository**\n ```\n Error: Git command failed: fatal: not a git repository\n ```\n\n **Solution:** Ensure you're pointing to a valid git repository:\n ```json\n {\n \"working_directory\": \"/path/to/valid/git/repo\"\n }\n ```\n\n4. **Git Not Available**\n ```\n Error: Git command not found\n ```\n\n **Solution:** Install git or ensure it's in your PATH.\n\n#### **Best Practices:**\n\n- Always specify the `working_directory` parameter when the repository is not in the current directory\n- Use full/absolute paths for `working_directory` to avoid confusion\n- Verify branch names with `git branch -a` before running scans\n- For remote branches, use the full name (e.g., `origin/main` not just `main`)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for security vulnerability scanning and detection",
"version": "1.0.3",
"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": "0622d4f8505c183d71dfe9f79b4a85112e50693ecd9989e874ac437396492dfa",
"md5": "d61365456dc4d739352d026ddb35070e",
"sha256": "f599d6e0e531e584432c1cf28d85d2a75ab54b5bbcebd6421c14d2599626c345"
},
"downloads": -1,
"filename": "adversary_mcp_server-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d61365456dc4d739352d026ddb35070e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 172300,
"upload_time": "2025-08-06T01:16:05",
"upload_time_iso_8601": "2025-08-06T01:16:05.323364Z",
"url": "https://files.pythonhosted.org/packages/06/22/d4f8505c183d71dfe9f79b4a85112e50693ecd9989e874ac437396492dfa/adversary_mcp_server-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "03ec6a04ab1f2bfaa92fd4682a1b31435ad9a062a4697647f9a62907bb4e919a",
"md5": "9aee75ac9fa5d975c5f138483732c6c1",
"sha256": "58dce97c9b1082328de974b3957ee9fae92c792e05d3fc1612f1ce7a46544997"
},
"downloads": -1,
"filename": "adversary_mcp_server-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "9aee75ac9fa5d975c5f138483732c6c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 396059,
"upload_time": "2025-08-06T01:16:06",
"upload_time_iso_8601": "2025-08-06T01:16:06.976781Z",
"url": "https://files.pythonhosted.org/packages/03/ec/6a04ab1f2bfaa92fd4682a1b31435ad9a062a4697647f9a62907bb4e919a/adversary_mcp_server-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 01:16:06",
"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
