# 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/)
**Software security analysis with hybrid AI-powered threat detection and configurable built-in and custom rule management**
[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.10+** (3.11+ recommended)
- **Cursor IDE** with MCP support
### Quick Install
```bash
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
# View available rules and setup
adversary-mcp-cli rules stats
```
### 2. Cursor IDE Integration
Create `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
```json
{
"mcpServers": {
"adversary-security": {
"command": "/Users/<user>/envs/.venv/bin/python",
"args": ["-m", "adversary_mcp_server.server"],
"env": {
"ADVERSARY_CONFIG_DIR": "~/.local/share/adversary-mcp-server"
}
}
}
}
```
### 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_directory` - directory scanning
- `adv_diff_scan` - **🆕 Git diff-aware scanning** - scans only changed files between branches
- `adv_list_rules` - List all 95+ security rules
- `adv_get_rule_details` - Get details about specific rules
- `adv_generate_exploit` - exploit generation
- `adv_configure_settings` - Configuration management
- `adv_get_status` - Check server status and AI availability
- `adv_get_version` - Get version information
### 4. Enable Hot-Reload (Optional)
For real-time rule updates during development:
```bash
# Start hot-reload service
adversary-mcp-cli watch start
# Now edit rules and they'll automatically reload
```
### 5. **🆕 Git Diff-Aware Scanning**
Scan only changed files between git branches for efficient CI/CD integration:
```bash
# Scan changes in your current branch vs main
adversary-mcp-cli scan --diff
# Scan changes between specific branches
adversary-mcp-cli scan --diff --source-branch=develop --target-branch=feature/auth
# Scan with high severity filter
adversary-mcp-cli scan --diff --severity=high --use-llm=true
```
---
### ** Scanning **
```bash
# Scan with AI enhancement (hybrid mode)
Use adv_scan_code with use_llm=true for comprehensive analysis
# Traditional rules-only scanning
Use adv_scan_code with use_llm=false for simple analysis
```
### **AI Analysis Features**
- **🎯 Smart Threat Detection**: Identifies vulnerabilities that traditional rules miss
- **📊 Confidence Scoring**: Each finding includes AI-generated confidence levels
- **🔍 Detailed Explanations**: Natural language descriptions of vulnerabilities
- **🏷️ CWE/OWASP Mapping**: Automatic categorization with industry standards
- **⚡ Intelligent Deduplication**: Merges similar findings from multiple engines
### **LLM Integration**
The scanner integrates with the existing models in your client application.
```bash
adversary-mcp-cli status
```
**Note**: LLM analysis is provided through prompts that can be used with your preferred LLM service. The scanner generates structured prompts for:
- Security analysis
- Exploit generation
- Code review
- Vulnerability explanations
---
## MCP Integration
### Available Tools
| Tool | Description | **🆕 AI Features** |
|------|-------------|-------------------|
| `adv_scan_code` | **🆕 Hybrid scan** of source code | ✅ LLM prompts, confidence scoring |
| `adv_scan_file` | **🆕 Enhanced** file scanning | ✅ AI-powered prompts, detailed explanations |
| `adv_scan_directory` | **🆕 Intelligent** directory scanning | ✅ Batch LLM prompts, statistical insights |
| `adv_diff_scan` | **🆕 Git diff-aware scanning** - scans only newly added lines | ✅ Smart change detection, branch comparison, requires `working_directory` |
| `adv_generate_exploit` | **🆕 AI-enhanced** exploit generation | ✅ Context-aware prompts, safety mode |
| `adv_list_rules` | List all 95+ threat detection rules | Enhanced with AI rule categories |
| `adv_get_rule_details` | Get detailed rule information | Improved formatting and examples |
| `adv_configure_settings` | **🆕 Advanced** configuration management | ✅ LLM settings, validation |
| `adv_get_status` | Get server status and **🆕 AI availability** | ✅ LLM configuration status |
| `adv_get_version` | Get version information | Shows AI capabilities |
### **🆕 Enhanced Tool Parameters**
All scanning tools now support:
```json
{
"use_llm": true, // Enable LLM prompts
"severity_threshold": "medium", // Filter by severity
"include_exploits": true, // Include exploit examples
"confidence_threshold": 0.8 // AI confidence filtering
}
```
### Example Usage in Cursor
```
# NEW: AI-powered vulnerability scanning
Use adv_scan_code with use_llm=true to analyze this function
# NEW: Git diff-aware scanning
Use adv_diff_scan to scan only changed files between branches
# NEW: Generate AI-enhanced exploits
Use adv_generate_exploit for this SQL injection
# NEW: Check AI analysis availability
Use adv_get_status to get the MCP server status
```
### **🆕 Git Diff-Aware Scanning**
The new `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
This prevents false positives from flagging existing code as new vulnerabilities.
#### **MCP Tool Parameters:**
```json
{
"source_branch": "main", // Branch to compare from
"target_branch": "feature/new", // Branch to compare to
"working_directory": "/absolute/path/to/repo", // ⚠️ REQUIRED: Working directory for git operations
"severity_threshold": "medium", // Filter results by severity
"include_exploits": true, // Include exploit examples
"use_llm": true // Enable AI analysis
}
```
#### **Example Usage:**
```
# Scan changes in current branch vs main
Use adv_diff_scan with source_branch="main", target_branch="HEAD", and working_directory="/path/to/your/repo"
# Scan changes between specific branches
Use adv_diff_scan with source_branch="staging", target_branch="production", and working_directory="/path/to/your/repo"
# Scan with high severity filter
Use adv_diff_scan with severity_threshold="high" and working_directory="/path/to/your/repo"
```
#### **⚠️ Important Requirements:**
1. **Must specify `working_directory`**: The absolute path to your git repository
2. **Valid git repository**: The directory must contain a `.git` folder
3. **Valid branches**: Both source and target branches must exist
4. **Git available**: `git` command must be available in PATH
---
## Rule Management
### **🆕 Enhanced Rule Engine**
- **95+ Built-in Rules** (expanded from 85)
- **🆕 AI-Enhanced Categories** with better organization
- **🆕 Confidence-Based Filtering** for more accurate results
- **🆕 Hybrid Rule Validation** using both static and AI analysis
### Rule Directory Structure
Rules are automatically organized in your user directory:
```
~/.local/share/adversary-mcp-server/rules/
├── built-in/ # Core security rules (95 rules)
│ ├── python-rules.yaml # 🆕 Enhanced Python rules
│ ├── javascript-rules.yaml # 🆕 Enhanced JavaScript rules
│ ├── typescript-rules.yaml # 🆕 Enhanced TypeScript rules
│ ├── web-security-rules.yaml # 🆕 Enhanced Web security
│ ├── api-security-rules.yaml # 🆕 Enhanced API security
│ ├── cryptography-rules.yaml # 🆕 Enhanced Crypto rules
│ └── configuration-rules.yaml # 🆕 Enhanced Config rules
├── custom/ # Your custom rules
├── organization/ # Company/team rules
└── templates/ # 🆕 Enhanced rule templates
```
### **🆕 AI-Enhanced Rule Management**
```bash
# View enhanced rules with AI categories
adversary-mcp-cli list-rules --show-ai-categories
# Validate rules with AI assistance
adversary-mcp-cli rules validate --use-ai
# Enhanced rule statistics
adversary-mcp-cli rules stats --detailed
```
### Quick Rule Management
```bash
# View rules directory and contents
adversary-mcp-cli show-rules-dir
# List all loaded rules with source files
adversary-mcp-cli list-rules
# List rules with full file paths
adversary-mcp-cli list-rules --verbose
# View detailed rule statistics
adversary-mcp-cli rules stats
# Export rules for backup/sharing
adversary-mcp-cli rules export my-rules.yaml
# Import custom rules
adversary-mcp-cli rules import-rules external-rules.yaml
# Validate all rules
adversary-mcp-cli rules validate
# Reload rules after changes
adversary-mcp-cli rules reload
```
### Creating Custom Rules
1. **Copy template:**
```bash
cp ~/.local/share/adversary-mcp-server/rules/templates/rule-template.yaml \
~/.local/share/adversary-mcp-server/rules/custom/my-rule.yaml
```
2. **Edit the rule:**
```yaml
rules:
- id: api_key_hardcode
name: Hardcoded API Key
description: Detects hardcoded API keys in source code
category: secrets
severity: critical
languages: [python, javascript, typescript]
conditions:
- type: pattern
value: "API_KEY\\s*=\\s*['\"][a-zA-Z0-9-_]{20,}['\"]"
remediation: |
Store API keys in environment variables:
- Use os.getenv('API_KEY') instead of hardcoding
- Implement proper secrets management
references:
- https://owasp.org/Top10/A05_2021-Security_Misconfiguration/
cwe_id: CWE-798
owasp_category: A05:2021
```
3. **Reload rules:**
```bash
adversary-mcp-cli rules reload
```
---
## Hot-Reload Service
Enable real-time rule updates without server restart:
### Start Hot-Reload
```bash
# Start with default settings
adversary-mcp-cli watch start
# Start with custom directories and debounce time
adversary-mcp-cli watch start \
--directory /path/to/project/rules/ \
--debounce 2.0
```
### Monitor Status
```bash
# Check service status
adversary-mcp-cli watch status
# Test hot-reload functionality
adversary-mcp-cli watch test
```
### Development Workflow
```bash
# Terminal 1: Start hot-reload service
adversary-mcp-cli watch start
# Terminal 2: Edit rules (auto-reloads)
vim ~/.local/share/adversary-mcp-server/rules/custom/my-rule.yaml
# Changes are automatically detected and rules reload!
```
---
## CLI Reference
### Core Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli configure` | Initial setup and configuration |
| `adversary-mcp-cli status` | Show server status and configuration |
| `adversary-mcp-cli scan <target>` | Scan files/directories for vulnerabilities |
| `adversary-mcp-cli scan --diff` | **🆕 Git diff-aware scanning** - scan only newly added lines (no context) |
| `adversary-mcp-cli server` | Start MCP server (used by Cursor) |
### Rule Management Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli list-rules` | List all rules with source files |
| `adversary-mcp-cli rule-details <id>` | Get detailed rule information |
| `adversary-mcp-cli rules stats` | Show comprehensive rule statistics |
| `adversary-mcp-cli rules export <file>` | Export rules to YAML/JSON |
| `adversary-mcp-cli rules import-rules <file>` | Import external rules |
| `adversary-mcp-cli rules validate` | Validate all loaded rules |
| `adversary-mcp-cli rules reload` | Reload rules from files |
### Hot-Reload Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli watch start` | Start hot-reload service |
| `adversary-mcp-cli watch status` | Show service status |
| `adversary-mcp-cli watch test` | Test hot-reload functionality |
### **🆕 Git Diff-Aware Scanning Options**
The `scan` command now supports git diff-aware scanning with the following options:
| Option | Description | Default |
|--------|-------------|---------|
| `--diff/--no-diff` | Enable git diff-aware scanning | `false` |
| `--source-branch` | Source branch for comparison | `main` |
| `--target-branch` | Target branch for comparison | `HEAD` |
| `--severity` | Minimum severity threshold | `medium` |
| `--include-exploits/--no-exploits` | Include exploit examples | `true` |
| `--use-llm/--no-llm` | Enable AI analysis | `true` |
| `--output` | Output results to JSON file | None |
#### **Diff Scanning Examples:**
```bash
# Basic diff scan (main vs current branch) - scans only newly added lines
adversary-mcp-cli scan --diff
# Compare specific branches - scans only new code between branches
adversary-mcp-cli scan --diff --source-branch=develop --target-branch=feature/auth
# High severity threats only - filters results to high/critical severity
adversary-mcp-cli scan --diff --severity=high
# Save diff scan results to JSON file
adversary-mcp-cli scan --diff --output=security-diff.json
# Comprehensive diff analysis with AI - includes LLM prompts for enhanced analysis
adversary-mcp-cli scan --diff --use-llm=true --include-exploits=true
# Specify custom directory for git operations
adversary-mcp-cli scan /path/to/repo --diff --source-branch=main --target-branch=HEAD
```
### Utility Commands
| Command | Description |
|---------|-------------|
| `adversary-mcp-cli show-rules-dir` | Show rules directory location |
| `adversary-mcp-cli demo` | Run interactive demo |
| `adversary-mcp-cli reset` | Reset all configuration |
---
## Security Coverage
### **🆕 Comprehensive Hybrid Analysis (95+ Rules + AI)**
#### **Traditional Rule-Based Detection**
- **Python** (25+ rules): SQL injection, command injection, deserialization, path traversal
- **JavaScript/TypeScript** (30+ rules): XSS, prototype pollution, eval injection, CORS issues
- **Web Security** (18+ rules): CSRF, clickjacking, security headers, session management
- **API Security** (15+ rules): Authentication bypass, parameter pollution, mass assignment
- **Cryptography** (15+ rules): Weak algorithms, hardcoded keys, poor randomness
- **Configuration** (15+ rules): Debug mode, default credentials, insecure settings
#### **🆕 AI-Powered 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
### **🆕 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
- **🆕 MITRE ATT&CK** - Threat modeling integration
- **🆕 ASVS** - Application Security Verification Standard
### **Full Language Support**
- **Python** - AST-based analysis + AI semantic understanding
- **JavaScript** - Modern ES6+ and Node.js patterns + AI context analysis
- **TypeScript** - Type safety vulnerabilities + AI-powered type inference analysis
### **Limited Language Support**
- TBD
---
## 🏗️ Enhanced Architecture
The v0.7.1 release features a **hybrid architecture** combining multiple analysis engines:
```mermaid
graph TB
A[Source Code] --> B[Enhanced Scanner]
B --> C[AST Scanner]
B --> D[🆕 LLM Analyzer]
C --> E[Rule Engine]
E --> F[95+ Built-in Rules]
E --> G[Custom Rules]
D --> H[LLM Service]
H --> I[AI Security Analysis]
C --> J[Threat Matches]
D --> K[LLM Findings]
J --> L[🆕 Intelligent Merger]
K --> L
L --> M[Enhanced Results]
M --> N[Confidence Scoring]
M --> O[Deduplication]
M --> P[Statistical Analysis]
subgraph "🆕 AI Enhancement"
D
H
I
K
end
subgraph "Traditional Analysis"
C
E
F
G
J
end
subgraph "🆕 Hybrid Output"
L
M
N
O
P
end
```
### **🆕 Integration Architecture**
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Cursor IDE │───▶│🆕 Enhanced MCP │───▶│🆕 Hybrid Engine │
│ │ │ Server │ │ │
│ • Code editing │ │ • adv_* tools │ │ • AST Analysis │
│ • Chat interface│ │ • AI integration│ │ • LLM Analysis │
│ • Tool calling │ │ • Protocol │ │ • Hot-reload │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ ▼ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│🆕 Enhanced Rules│ │ Custom Rules │ │Organization Rules│
│ (95+ rules) │ │ User defined │ │ Company policies│
│ Multi-language │ │ Project specific│ │ Compliance │
│ + AI Categories │ │ + AI Templates │ │ + AI Validation │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ ▼ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 🆕 LLM Service │ │🆕 Confidence │ │🆕 Statistical │
│ Integration │ │ Scoring │ │ Analysis │
│ • External APIs │ │ • Reliability │ │ • Detailed │
│ • Context-aware │ │ • Deduplication │ │ Metrics │
│ • NL Explanations│ │ • Smart Merging │ │ • Trend Analysis│
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
---
#### **Traditional Rules-Only Analysis**
```bash
# Fast, deterministic scanning
adversary-mcp-cli scan myproject/ --use-llm=false --severity=medium
```
#### **🆕 AI-Enhanced Analysis**
```bash
# Comprehensive hybrid analysis with LLM prompts
adversary-mcp-cli scan myproject/ --use-llm=true --confidence-threshold=0.8
```
#### **🆕 Git Diff-Aware Scanning**
```bash
# Scan only newly added lines between branches (no context lines)
adversary-mcp-cli scan --diff --source-branch=main --target-branch=HEAD
# Scan changes with specific severity threshold - only new code
adversary-mcp-cli scan --diff --source-branch=staging --target-branch=production --severity=high
# Scan current branch changes with AI analysis - includes LLM prompts for new code
adversary-mcp-cli scan --diff --use-llm=true --include-exploits=true
# Specify repository directory for git operations
adversary-mcp-cli scan /path/to/repo --diff --source-branch=main --target-branch=feature/new
```
### **🆕 Advanced Configuration**
#### **LLM Configuration**
```bash
# Configure LLM analysis settings
adversary-mcp-cli configure --enable-llm-analysis=true
adversary-mcp-cli configure --exploit-safety-mode=true
```
#### **🆕 Confidence and Filtering**
```bash
# Filter by AI confidence levels
adversary-mcp-cli scan . --confidence-threshold 0.9 --use-llm=true
# Combine rules and AI with custom thresholds
adversary-mcp-cli scan . --severity=high --confidence-threshold=0.7
```
### **🆕 Enhanced Reporting**
#### **Detailed Analysis Reports**
```bash
# Generate comprehensive reports with AI insights
adversary-mcp-cli scan . --format=detailed --include-ai-analysis --output=report.json
```
#### **🆕 Statistical Analysis**
```bash
# Get detailed statistics about threats found
adversary-mcp-cli scan . --stats --use-llm=true
```
### **🆕 Integration Capabilities**
#### **IDE Integration**
The enhanced MCP server provides seamless integration with development environments:
- **Real-time Analysis**: Instant feedback as you type
- **Context-Aware Suggestions**: AI understands your specific codebase
- **Intelligent Deduplication**: No duplicate alerts from multiple engines
- **Confidence Indicators**: Know which findings are most reliable
#### **🆕 LLM Prompt Generation**
```python
# Use the enhanced scanner programmatically
from adversary_mcp_server.enhanced_scanner import EnhancedScanner
scanner = EnhancedScanner(enable_llm_analysis=True)
result = scanner.scan_code(source_code, file_path, language, use_llm=True)
# Access hybrid results
print(f"Total threats: {len(result.all_threats)}")
print(f"Rules-based: {len(result.rules_threats)}")
print(f"LLM prompts generated: {len(result.llm_prompts)}")
print(f"High confidence: {len(result.get_high_confidence_threats())}")
```
---
## Advanced Usage
### CI/CD Integration
#### **🆕 Git Diff-Aware CI/CD Scanning**
For efficient CI/CD pipelines, scan only newly added lines in pull requests:
```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 . --diff \
--source-branch=origin/main \
--target-branch=HEAD \
--severity=medium \
--output=security-diff.json
env:
GITHUB_WORKSPACE: ${{ github.workspace }}
- name: Full Security Scan (Push to main)
if: github.ref == 'refs/heads/main'
run: |
adversary-mcp-cli scan . \
--severity medium \
--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_RULES_DIR="~/.local/share/adversary-mcp-server/rules"
export ADVERSARY_LOG_LEVEL="INFO"
export ADVERSARY_SEVERITY_THRESHOLD="medium"
export ADVERSARY_HOT_RELOAD="enabled"
```
---
## 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
```
### Project Structure
```
adversary-mcp-server/
├── src/adversary_mcp_server/
│ ├── server.py # MCP server with adv_* tools
│ ├── threat_engine.py # Rule engine with source file tracking
│ ├── ast_scanner.py # Static analysis engine
│ ├── exploit_generator.py # Educational exploit generation
│ ├── hot_reload.py # Real-time rule updates
│ └── cli.py # Command-line interface
├── rules/ # Packaged rules (copied to user directory)
│ ├── built-in/ # 95+ core security rules
│ └── templates/ # Rule creation templates
└── tests/ # Comprehensive test suite (332 tests)
```
---
## 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`.
---
## 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`)
#### **Example Working Configuration:**
```json
{
"source_branch": "origin/main",
"target_branch": "HEAD",
"working_directory": "/Users/username/my-project",
"severity_threshold": "medium",
"include_exploits": true,
"use_llm": false
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "adversary-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "adversary, cursor, mcp, red-team, security, vulnerability",
"author": null,
"author_email": "Brett Bergin <brettberginbc@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/e0/66/e7274fd3f82d629f4eee7d93057f4597f955fa3415c994cec7dafafa85f5/adversary_mcp_server-0.7.7.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**Software security analysis with hybrid AI-powered threat detection and configurable built-in and custom rule management**\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.10+** (3.11+ recommended)\n- **Cursor IDE** with MCP support\n\n### Quick Install\n\n```bash\npip 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# View available rules and setup\nadversary-mcp-cli rules stats\n```\n\n### 2. Cursor IDE Integration\n\nCreate `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:\n\n```json\n{\n \"mcpServers\": {\n \"adversary-security\": {\n \"command\": \"/Users/<user>/envs/.venv/bin/python\",\n \"args\": [\"-m\", \"adversary_mcp_server.server\"],\n \"env\": {\n \"ADVERSARY_CONFIG_DIR\": \"~/.local/share/adversary-mcp-server\"\n }\n }\n }\n}\n```\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_directory` - directory scanning\n- `adv_diff_scan` - **\ud83c\udd95 Git diff-aware scanning** - scans only changed files between branches\n- `adv_list_rules` - List all 95+ security rules\n- `adv_get_rule_details` - Get details about specific rules\n- `adv_generate_exploit` - exploit generation\n- `adv_configure_settings` - Configuration management\n- `adv_get_status` - Check server status and AI availability\n- `adv_get_version` - Get version information\n\n### 4. Enable Hot-Reload (Optional)\n\nFor real-time rule updates during development:\n\n```bash\n# Start hot-reload service\nadversary-mcp-cli watch start\n\n# Now edit rules and they'll automatically reload\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 in your current branch vs main\nadversary-mcp-cli scan --diff\n\n# Scan changes between specific branches\nadversary-mcp-cli scan --diff --source-branch=develop --target-branch=feature/auth\n\n# Scan with high severity filter\nadversary-mcp-cli scan --diff --severity=high --use-llm=true\n```\n\n---\n\n### ** Scanning **\n\n```bash\n# Scan with AI enhancement (hybrid mode)\nUse adv_scan_code with use_llm=true for comprehensive analysis\n\n# Traditional rules-only scanning\nUse adv_scan_code with use_llm=false for simple analysis\n```\n\n### **AI Analysis Features**\n\n- **\ud83c\udfaf Smart Threat Detection**: Identifies vulnerabilities that traditional rules miss\n- **\ud83d\udcca Confidence Scoring**: Each finding includes AI-generated confidence levels\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\n### **LLM Integration**\n\nThe scanner integrates with the existing models in your client application.\n\n```bash\nadversary-mcp-cli status\n```\n\n**Note**: LLM analysis is provided through prompts that can be used with your preferred LLM service. The scanner generates structured prompts for:\n- Security analysis\n- Exploit generation\n- Code review\n- Vulnerability explanations\n\n---\n\n## MCP Integration\n\n### Available Tools\n\n| Tool | Description | **\ud83c\udd95 AI Features** |\n|------|-------------|-------------------|\n| `adv_scan_code` | **\ud83c\udd95 Hybrid scan** of source code | \u2705 LLM prompts, confidence scoring |\n| `adv_scan_file` | **\ud83c\udd95 Enhanced** file scanning | \u2705 AI-powered prompts, detailed explanations |\n| `adv_scan_directory` | **\ud83c\udd95 Intelligent** directory scanning | \u2705 Batch LLM prompts, statistical insights |\n| `adv_diff_scan` | **\ud83c\udd95 Git diff-aware scanning** - scans only newly added lines | \u2705 Smart change detection, branch comparison, requires `working_directory` |\n| `adv_generate_exploit` | **\ud83c\udd95 AI-enhanced** exploit generation | \u2705 Context-aware prompts, safety mode |\n| `adv_list_rules` | List all 95+ threat detection rules | Enhanced with AI rule categories |\n| `adv_get_rule_details` | Get detailed rule information | Improved formatting and examples |\n| `adv_configure_settings` | **\ud83c\udd95 Advanced** configuration management | \u2705 LLM settings, validation |\n| `adv_get_status` | Get server status and **\ud83c\udd95 AI availability** | \u2705 LLM configuration status |\n| `adv_get_version` | Get version information | Shows AI capabilities |\n\n### **\ud83c\udd95 Enhanced Tool Parameters**\n\nAll scanning tools now support:\n\n```json\n{\n \"use_llm\": true, // Enable LLM prompts\n \"severity_threshold\": \"medium\", // Filter by severity\n \"include_exploits\": true, // Include exploit examples\n \"confidence_threshold\": 0.8 // AI confidence filtering\n}\n```\n\n### Example Usage in Cursor\n\n```\n# NEW: AI-powered vulnerability scanning\nUse adv_scan_code with use_llm=true to analyze this function\n\n# NEW: Git diff-aware scanning\nUse adv_diff_scan to scan only changed files between branches\n\n# NEW: Generate AI-enhanced exploits\nUse adv_generate_exploit for this SQL injection\n\n# NEW: Check AI analysis availability\nUse adv_get_status to get the MCP server status\n```\n\n### **\ud83c\udd95 Git Diff-Aware Scanning**\n\nThe new `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#### **\ud83c\udfaf 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\nThis prevents false positives from flagging existing code as new vulnerabilities.\n\n#### **MCP Tool Parameters:**\n```json\n{\n \"source_branch\": \"main\", // Branch to compare from\n \"target_branch\": \"feature/new\", // Branch to compare to\n \"working_directory\": \"/absolute/path/to/repo\", // \u26a0\ufe0f REQUIRED: Working directory for git operations\n \"severity_threshold\": \"medium\", // Filter results by severity\n \"include_exploits\": true, // Include exploit examples\n \"use_llm\": true // Enable AI analysis\n}\n```\n\n#### **Example Usage:**\n```\n# Scan changes in current branch vs main\nUse adv_diff_scan with source_branch=\"main\", target_branch=\"HEAD\", and working_directory=\"/path/to/your/repo\"\n\n# Scan changes between specific branches\nUse adv_diff_scan with source_branch=\"staging\", target_branch=\"production\", and working_directory=\"/path/to/your/repo\"\n\n# Scan with high severity filter\nUse adv_diff_scan with severity_threshold=\"high\" and working_directory=\"/path/to/your/repo\"\n```\n\n#### **\u26a0\ufe0f Important Requirements:**\n1. **Must specify `working_directory`**: The absolute path to your git repository\n2. **Valid git repository**: The directory must contain a `.git` folder\n3. **Valid branches**: Both source and target branches must exist\n4. **Git available**: `git` command must be available in PATH\n\n---\n\n## Rule Management\n\n### **\ud83c\udd95 Enhanced Rule Engine**\n- **95+ Built-in Rules** (expanded from 85)\n- **\ud83c\udd95 AI-Enhanced Categories** with better organization\n- **\ud83c\udd95 Confidence-Based Filtering** for more accurate results\n- **\ud83c\udd95 Hybrid Rule Validation** using both static and AI analysis\n\n### Rule Directory Structure\n\nRules are automatically organized in your user directory:\n\n```\n~/.local/share/adversary-mcp-server/rules/\n\u251c\u2500\u2500 built-in/ # Core security rules (95 rules)\n\u2502 \u251c\u2500\u2500 python-rules.yaml # \ud83c\udd95 Enhanced Python rules\n\u2502 \u251c\u2500\u2500 javascript-rules.yaml # \ud83c\udd95 Enhanced JavaScript rules \n\u2502 \u251c\u2500\u2500 typescript-rules.yaml # \ud83c\udd95 Enhanced TypeScript rules\n\u2502 \u251c\u2500\u2500 web-security-rules.yaml # \ud83c\udd95 Enhanced Web security\n\u2502 \u251c\u2500\u2500 api-security-rules.yaml # \ud83c\udd95 Enhanced API security\n\u2502 \u251c\u2500\u2500 cryptography-rules.yaml # \ud83c\udd95 Enhanced Crypto rules\n\u2502 \u2514\u2500\u2500 configuration-rules.yaml # \ud83c\udd95 Enhanced Config rules\n\u251c\u2500\u2500 custom/ # Your custom rules\n\u251c\u2500\u2500 organization/ # Company/team rules\n\u2514\u2500\u2500 templates/ # \ud83c\udd95 Enhanced rule templates\n```\n\n### **\ud83c\udd95 AI-Enhanced Rule Management**\n\n```bash\n# View enhanced rules with AI categories\nadversary-mcp-cli list-rules --show-ai-categories\n\n# Validate rules with AI assistance\nadversary-mcp-cli rules validate --use-ai\n\n# Enhanced rule statistics\nadversary-mcp-cli rules stats --detailed\n```\n\n### Quick Rule Management\n\n```bash\n# View rules directory and contents\nadversary-mcp-cli show-rules-dir\n\n# List all loaded rules with source files \nadversary-mcp-cli list-rules\n\n# List rules with full file paths\nadversary-mcp-cli list-rules --verbose\n\n# View detailed rule statistics\nadversary-mcp-cli rules stats\n\n# Export rules for backup/sharing\nadversary-mcp-cli rules export my-rules.yaml\n\n# Import custom rules\nadversary-mcp-cli rules import-rules external-rules.yaml\n\n# Validate all rules\nadversary-mcp-cli rules validate\n\n# Reload rules after changes\nadversary-mcp-cli rules reload\n```\n\n### Creating Custom Rules\n\n1. **Copy template:**\n```bash\ncp ~/.local/share/adversary-mcp-server/rules/templates/rule-template.yaml \\\n ~/.local/share/adversary-mcp-server/rules/custom/my-rule.yaml\n```\n\n2. **Edit the rule:**\n```yaml\nrules:\n - id: api_key_hardcode\n name: Hardcoded API Key\n description: Detects hardcoded API keys in source code\n category: secrets\n severity: critical\n languages: [python, javascript, typescript]\n \n conditions:\n - type: pattern\n value: \"API_KEY\\\\s*=\\\\s*['\\\"][a-zA-Z0-9-_]{20,}['\\\"]\"\n \n remediation: |\n Store API keys in environment variables:\n - Use os.getenv('API_KEY') instead of hardcoding\n - Implement proper secrets management\n \n references:\n - https://owasp.org/Top10/A05_2021-Security_Misconfiguration/\n \n cwe_id: CWE-798\n owasp_category: A05:2021\n```\n\n3. **Reload rules:**\n```bash\nadversary-mcp-cli rules reload\n```\n\n---\n\n## Hot-Reload Service\n\nEnable real-time rule updates without server restart:\n\n### Start Hot-Reload\n\n```bash\n# Start with default settings\nadversary-mcp-cli watch start\n\n# Start with custom directories and debounce time\nadversary-mcp-cli watch start \\\n --directory /path/to/project/rules/ \\\n --debounce 2.0\n```\n\n### Monitor Status\n\n```bash\n# Check service status\nadversary-mcp-cli watch status\n\n# Test hot-reload functionality\nadversary-mcp-cli watch test\n```\n\n### Development Workflow\n\n```bash\n# Terminal 1: Start hot-reload service\nadversary-mcp-cli watch start\n\n# Terminal 2: Edit rules (auto-reloads)\nvim ~/.local/share/adversary-mcp-server/rules/custom/my-rule.yaml\n# Changes are automatically detected and rules reload!\n```\n\n---\n\n## CLI Reference\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli configure` | Initial setup and configuration |\n| `adversary-mcp-cli status` | Show server status and configuration |\n| `adversary-mcp-cli scan <target>` | Scan files/directories for vulnerabilities |\n| `adversary-mcp-cli scan --diff` | **\ud83c\udd95 Git diff-aware scanning** - scan only newly added lines (no context) |\n| `adversary-mcp-cli server` | Start MCP server (used by Cursor) |\n\n### Rule Management Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli list-rules` | List all rules with source files |\n| `adversary-mcp-cli rule-details <id>` | Get detailed rule information |\n| `adversary-mcp-cli rules stats` | Show comprehensive rule statistics |\n| `adversary-mcp-cli rules export <file>` | Export rules to YAML/JSON |\n| `adversary-mcp-cli rules import-rules <file>` | Import external rules |\n| `adversary-mcp-cli rules validate` | Validate all loaded rules |\n| `adversary-mcp-cli rules reload` | Reload rules from files |\n\n### Hot-Reload Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli watch start` | Start hot-reload service |\n| `adversary-mcp-cli watch status` | Show service status |\n| `adversary-mcp-cli watch test` | Test hot-reload functionality |\n\n### **\ud83c\udd95 Git Diff-Aware Scanning Options**\n\nThe `scan` command now supports git diff-aware scanning with the following options:\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--diff/--no-diff` | Enable git diff-aware scanning | `false` |\n| `--source-branch` | Source branch for comparison | `main` |\n| `--target-branch` | Target branch for comparison | `HEAD` |\n| `--severity` | Minimum severity threshold | `medium` |\n| `--include-exploits/--no-exploits` | Include exploit examples | `true` |\n| `--use-llm/--no-llm` | Enable AI analysis | `true` |\n| `--output` | Output results to JSON file | None |\n\n#### **Diff Scanning Examples:**\n```bash\n# Basic diff scan (main vs current branch) - scans only newly added lines\nadversary-mcp-cli scan --diff\n\n# Compare specific branches - scans only new code between branches\nadversary-mcp-cli scan --diff --source-branch=develop --target-branch=feature/auth\n\n# High severity threats only - filters results to high/critical severity\nadversary-mcp-cli scan --diff --severity=high\n\n# Save diff scan results to JSON file\nadversary-mcp-cli scan --diff --output=security-diff.json\n\n# Comprehensive diff analysis with AI - includes LLM prompts for enhanced analysis\nadversary-mcp-cli scan --diff --use-llm=true --include-exploits=true\n\n# Specify custom directory for git operations\nadversary-mcp-cli scan /path/to/repo --diff --source-branch=main --target-branch=HEAD\n```\n\n### Utility Commands\n\n| Command | Description |\n|---------|-------------|\n| `adversary-mcp-cli show-rules-dir` | Show rules directory location |\n| `adversary-mcp-cli demo` | Run interactive demo |\n| `adversary-mcp-cli reset` | Reset all configuration |\n\n---\n\n## Security Coverage\n\n### **\ud83c\udd95 Comprehensive Hybrid Analysis (95+ Rules + AI)**\n\n#### **Traditional Rule-Based Detection**\n- **Python** (25+ rules): SQL injection, command injection, deserialization, path traversal\n- **JavaScript/TypeScript** (30+ rules): XSS, prototype pollution, eval injection, CORS issues \n- **Web Security** (18+ rules): CSRF, clickjacking, security headers, session management\n- **API Security** (15+ rules): Authentication bypass, parameter pollution, mass assignment\n- **Cryptography** (15+ rules): Weak algorithms, hardcoded keys, poor randomness\n- **Configuration** (15+ rules): Debug mode, default credentials, insecure settings\n\n#### **\ud83c\udd95 AI-Powered 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 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- **\ud83c\udd95 MITRE ATT&CK** - Threat modeling integration\n- **\ud83c\udd95 ASVS** - Application Security Verification Standard\n\n### **Full Language Support**\n\n- **Python** - AST-based analysis + AI semantic understanding\n- **JavaScript** - Modern ES6+ and Node.js patterns + AI context analysis\n- **TypeScript** - Type safety vulnerabilities + AI-powered type inference analysis\n\n### **Limited Language Support**\n- TBD\n---\n\n## \ud83c\udfd7\ufe0f Enhanced Architecture\n\nThe v0.7.1 release features a **hybrid architecture** combining multiple analysis engines:\n\n```mermaid\ngraph TB\n A[Source Code] --> B[Enhanced Scanner]\n B --> C[AST Scanner]\n B --> D[\ud83c\udd95 LLM Analyzer]\n \n C --> E[Rule Engine]\n E --> F[95+ Built-in Rules]\n E --> G[Custom Rules]\n \n D --> H[LLM Service]\n H --> I[AI Security Analysis]\n \n C --> J[Threat Matches]\n D --> K[LLM Findings]\n \n J --> L[\ud83c\udd95 Intelligent Merger]\n K --> L\n \n L --> M[Enhanced Results]\n M --> N[Confidence Scoring]\n M --> O[Deduplication]\n M --> P[Statistical Analysis]\n \n subgraph \"\ud83c\udd95 AI Enhancement\"\n D\n H\n I\n K\n end\n \n subgraph \"Traditional Analysis\"\n C\n E\n F\n G\n J\n end\n \n subgraph \"\ud83c\udd95 Hybrid Output\"\n L\n M\n N\n O\n P\n end\n```\n\n### **\ud83c\udd95 Integration Architecture**\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Cursor IDE \u2502\u2500\u2500\u2500\u25b6\u2502\ud83c\udd95 Enhanced MCP \u2502\u2500\u2500\u2500\u25b6\u2502\ud83c\udd95 Hybrid Engine \u2502\n\u2502 \u2502 \u2502 Server \u2502 \u2502 \u2502\n\u2502 \u2022 Code editing \u2502 \u2502 \u2022 adv_* tools \u2502 \u2502 \u2022 AST Analysis \u2502\n\u2502 \u2022 Chat interface\u2502 \u2502 \u2022 AI integration\u2502 \u2502 \u2022 LLM Analysis \u2502\n\u2502 \u2022 Tool calling \u2502 \u2502 \u2022 Protocol \u2502 \u2502 \u2022 Hot-reload \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u25bc \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502\ud83c\udd95 Enhanced Rules\u2502 \u2502 Custom Rules \u2502 \u2502Organization Rules\u2502\n \u2502 (95+ rules) \u2502 \u2502 User defined \u2502 \u2502 Company policies\u2502\n \u2502 Multi-language \u2502 \u2502 Project specific\u2502 \u2502 Compliance \u2502\n \u2502 + AI Categories \u2502 \u2502 + AI Templates \u2502 \u2502 + AI Validation \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u25bc \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \ud83c\udd95 LLM Service \u2502 \u2502\ud83c\udd95 Confidence \u2502 \u2502\ud83c\udd95 Statistical \u2502\n \u2502 Integration \u2502 \u2502 Scoring \u2502 \u2502 Analysis \u2502\n \u2502 \u2022 External APIs \u2502 \u2502 \u2022 Reliability \u2502 \u2502 \u2022 Detailed \u2502\n \u2502 \u2022 Context-aware \u2502 \u2502 \u2022 Deduplication \u2502 \u2502 Metrics \u2502\n \u2502 \u2022 NL Explanations\u2502 \u2502 \u2022 Smart Merging \u2502 \u2502 \u2022 Trend Analysis\u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n---\n\n\n#### **Traditional Rules-Only Analysis**\n```bash\n# Fast, deterministic scanning\nadversary-mcp-cli scan myproject/ --use-llm=false --severity=medium\n```\n\n#### **\ud83c\udd95 AI-Enhanced Analysis**\n```bash\n# Comprehensive hybrid analysis with LLM prompts\nadversary-mcp-cli scan myproject/ --use-llm=true --confidence-threshold=0.8\n```\n\n#### **\ud83c\udd95 Git Diff-Aware Scanning**\n```bash\n# Scan only newly added lines between branches (no context lines)\nadversary-mcp-cli scan --diff --source-branch=main --target-branch=HEAD\n\n# Scan changes with specific severity threshold - only new code\nadversary-mcp-cli scan --diff --source-branch=staging --target-branch=production --severity=high\n\n# Scan current branch changes with AI analysis - includes LLM prompts for new code\nadversary-mcp-cli scan --diff --use-llm=true --include-exploits=true\n\n# Specify repository directory for git operations\nadversary-mcp-cli scan /path/to/repo --diff --source-branch=main --target-branch=feature/new\n```\n\n### **\ud83c\udd95 Advanced Configuration**\n\n#### **LLM Configuration**\n```bash\n# Configure LLM analysis settings\nadversary-mcp-cli configure --enable-llm-analysis=true\nadversary-mcp-cli configure --exploit-safety-mode=true\n```\n\n#### **\ud83c\udd95 Confidence and Filtering**\n```bash\n# Filter by AI confidence levels\nadversary-mcp-cli scan . --confidence-threshold 0.9 --use-llm=true\n\n# Combine rules and AI with custom thresholds\nadversary-mcp-cli scan . --severity=high --confidence-threshold=0.7\n```\n\n### **\ud83c\udd95 Enhanced Reporting**\n\n#### **Detailed Analysis Reports**\n```bash\n# Generate comprehensive reports with AI insights\nadversary-mcp-cli scan . --format=detailed --include-ai-analysis --output=report.json\n```\n\n#### **\ud83c\udd95 Statistical Analysis**\n```bash\n# Get detailed statistics about threats found\nadversary-mcp-cli scan . --stats --use-llm=true\n```\n\n### **\ud83c\udd95 Integration Capabilities**\n\n#### **IDE Integration**\nThe enhanced MCP server provides seamless integration with development environments:\n\n- **Real-time Analysis**: Instant feedback as you type\n- **Context-Aware Suggestions**: AI understands your specific codebase\n- **Intelligent Deduplication**: No duplicate alerts from multiple engines\n- **Confidence Indicators**: Know which findings are most reliable\n\n#### **\ud83c\udd95 LLM Prompt Generation**\n```python\n# Use the enhanced scanner programmatically\nfrom adversary_mcp_server.enhanced_scanner import EnhancedScanner\n\nscanner = EnhancedScanner(enable_llm_analysis=True)\nresult = scanner.scan_code(source_code, file_path, language, use_llm=True)\n\n# Access hybrid results\nprint(f\"Total threats: {len(result.all_threats)}\")\nprint(f\"Rules-based: {len(result.rules_threats)}\")\nprint(f\"LLM prompts generated: {len(result.llm_prompts)}\")\nprint(f\"High confidence: {len(result.get_high_confidence_threats())}\")\n```\n\n---\n\n## Advanced Usage\n\n### CI/CD Integration\n\n#### **\ud83c\udd95 Git Diff-Aware CI/CD Scanning**\n\nFor efficient CI/CD pipelines, scan only newly added lines in pull requests:\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 . --diff \\\n --source-branch=origin/main \\\n --target-branch=HEAD \\\n --severity=medium \\\n --output=security-diff.json\n env:\n GITHUB_WORKSPACE: ${{ github.workspace }}\n \n - name: Full Security Scan (Push to main)\n if: github.ref == 'refs/heads/main'\n run: |\n adversary-mcp-cli scan . \\\n --severity medium \\\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_RULES_DIR=\"~/.local/share/adversary-mcp-server/rules\"\nexport ADVERSARY_LOG_LEVEL=\"INFO\"\nexport ADVERSARY_SEVERITY_THRESHOLD=\"medium\"\nexport ADVERSARY_HOT_RELOAD=\"enabled\"\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### Project Structure\n\n```\nadversary-mcp-server/\n\u251c\u2500\u2500 src/adversary_mcp_server/\n\u2502 \u251c\u2500\u2500 server.py # MCP server with adv_* tools\n\u2502 \u251c\u2500\u2500 threat_engine.py # Rule engine with source file tracking\n\u2502 \u251c\u2500\u2500 ast_scanner.py # Static analysis engine\n\u2502 \u251c\u2500\u2500 exploit_generator.py # Educational exploit generation\n\u2502 \u251c\u2500\u2500 hot_reload.py # Real-time rule updates\n\u2502 \u2514\u2500\u2500 cli.py # Command-line interface\n\u251c\u2500\u2500 rules/ # Packaged rules (copied to user directory)\n\u2502 \u251c\u2500\u2500 built-in/ # 95+ core security rules\n\u2502 \u2514\u2500\u2500 templates/ # Rule creation templates\n\u2514\u2500\u2500 tests/ # Comprehensive test suite (332 tests)\n```\n\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## 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\n#### **Example Working Configuration:**\n```json\n{\n \"source_branch\": \"origin/main\",\n \"target_branch\": \"HEAD\", \n \"working_directory\": \"/Users/username/my-project\",\n \"severity_threshold\": \"medium\",\n \"include_exploits\": true,\n \"use_llm\": false\n}\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for adversarial security analysis and vulnerability detection",
"version": "0.7.7",
"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": [
"adversary",
" cursor",
" mcp",
" red-team",
" security",
" vulnerability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fca9538520e783879686a828a8074d72ad30784c69d6a4d93003813512ad1b71",
"md5": "e62fa09fd7ee5a7607da2d1fb535e152",
"sha256": "ff1942c8353e88a3ff9cf71073aa62d788177a6cf5f95de396b198a8f0d41179"
},
"downloads": -1,
"filename": "adversary_mcp_server-0.7.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e62fa09fd7ee5a7607da2d1fb535e152",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 84874,
"upload_time": "2025-07-10T03:48:52",
"upload_time_iso_8601": "2025-07-10T03:48:52.671029Z",
"url": "https://files.pythonhosted.org/packages/fc/a9/538520e783879686a828a8074d72ad30784c69d6a4d93003813512ad1b71/adversary_mcp_server-0.7.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e066e7274fd3f82d629f4eee7d93057f4597f955fa3415c994cec7dafafa85f5",
"md5": "266f107e77c7efa1ce8258f24f9c3518",
"sha256": "45b420ef333e08a499414ae37b248a26e7b578aa617b78805f40ffd8eda05f2e"
},
"downloads": -1,
"filename": "adversary_mcp_server-0.7.7.tar.gz",
"has_sig": false,
"md5_digest": "266f107e77c7efa1ce8258f24f9c3518",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 260827,
"upload_time": "2025-07-10T03:48:57",
"upload_time_iso_8601": "2025-07-10T03:48:57.312954Z",
"url": "https://files.pythonhosted.org/packages/e0/66/e7274fd3f82d629f4eee7d93057f4597f955fa3415c994cec7dafafa85f5/adversary_mcp_server-0.7.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 03:48:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brettbergin",
"github_project": "adversary-mcp-server#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "adversary-mcp-server"
}
JSON
