Offers security analysis for JavaScript code, detecting vulnerabilities like DOM-based XSS, code injection, and prototype pollution through AST parsing.
Optional integration for enhanced exploit generation, allowing the MCP server to use OpenAI GPT models to create more sophisticated educational security exploit examples.
Integrates OWASP security guidelines and references for vulnerability classifications and remediation advice, mapping detected issues to OWASP Top 10 categories.
Provides vulnerability detection and analysis for Python code, including AST-based parsing to identify SQL injection, command injection, unsafe deserialization, and other Python-specific security issues.
Detects SQL injection vulnerabilities specific to SQLite database interactions in application code.
Enables security scanning of TypeScript code to identify vulnerabilities like DOM-based XSS, code injection, and other TypeScript-specific security concerns.
Adversary MCP Server
Software security analysis with hybrid AI-powered threat detection and configurable built-in and custom rule management
Installation • Quick Start • AI-Powered Analysis • MCP Integration • Rule Management • CLI Reference
Installation
Prerequisites
- Python 3.10+ (3.11+ recommended)
- Cursor IDE with MCP support
Quick Install
Verify Installation
Quick Start
1. Initial Setup
2. Cursor IDE Integration
Create .cursor/mcp.json
in your project or ~/.cursor/mcp.json
globally:
3. Start Using in Cursor
Once configured, you can use these MCP tools in Cursor:
adv_scan_code
- Hybrid scanning with rules + AI analysisadv_scan_file
- file scanning with LLM supportadv_scan_folder
- folder scanningadv_diff_scan
- 🆕 Git diff-aware scanning - scans only changed files between branchesadv_generate_exploit
- exploit generationadv_configure_settings
- Configuration managementadv_get_status
- Check server status and AI availabilityadv_get_version
- Get version informationadv_mark_false_positive
- Mark false positiveadv_unmark_false_positives
- Unmark false positiveadv_list_false_postives
- List false positives
4. Run Demo (Optional)
Test the scanner with vulnerable code examples:
5. 🆕 Git Diff-Aware Scanning
Scan only changed files between git branches for efficient CI/CD integration:
** Scanning **
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.
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_folder | 🆕 Intelligent folder 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_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 |
adv_mark_false_positive | Mark false positive | Mark false positive |
adv_unmark_false_positive | Unmark flase positive | unmark false positive |
adv_list_false_positves | list false positives | list false positives |
🆕 Enhanced Tool Parameters
All scanning tools now support:
🆕 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:
Example Usage:
⚠️ Important Requirements:
- Must specify
working_directory
: The absolute path to your git repository - Valid git repository: The directory must contain a
.git
folder - Valid branches: Both source and target branches must exist
- Git available:
git
command must be available in PATH
🆕 Semgrep Integration
Overview
The Adversary MCP Server now includes integrated Semgrep static analysis as a third scanning engine, providing comprehensive security coverage through:
- Built-in Rules Engine (95+ custom rules)
- AI-Powered Analysis (LLM prompts and insights)
- Semgrep Static Analysis (industry-standard rule database)
Automatic Setup
Semgrep integration works out-of-the-box with automatic detection:
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
Semgrep Pro (Automatic Detection)
Usage in MCP Tools
All MCP scanning tools support the use_semgrep
parameter:
CLI Usage
Configuration Options
Semgrep behavior can be customized through configuration:
Or set via environment:
Smart Result Merging
The integration intelligently combines results from all three engines:
JSON Output with Semgrep
Get structured output including Semgrep findings:
Performance and Availability
- Graceful Degradation: If Semgrep is not installed, scanning continues with other engines
- Timeout Protection: Configurable timeouts prevent hung scans
- Automatic Cleanup: Temporary files are automatically cleaned up
- Error Handling: Clear error messages for configuration issues
Installation Requirements
Semgrep integration requires the Semgrep CLI tool:
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:
Rule Management
The adversary MCP server includes 95+ built-in security rules organized by language and category. Rules are automatically loaded and don't require manual management in the current CLI version.
Creating Custom Rules
- Copy template:
- Edit the rule:
- Restart the server: The new rule will be automatically loaded when the MCP server restarts.
Rule Configuration
The server automatically loads built-in rules from the rule directory structure. Custom rules can be added to the user's configuration directory for extended functionality.
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 mark-false-positive <UUID> | Mark a 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 |
adversary-mcp-cli reset | Reset all configuration and credentials |
adversary-mcp-cli reset-semgrep-key | Remove stored Semgrep API key from keyring |
False Positive Management
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
Configuration Commands
Command | Description |
---|---|
adversary-mcp-cli configure | Configure server settings |
adversary-mcp-cli status | Show current configuration and status |
adversary-mcp-cli reset | Reset all configuration and credentials |
Configure Options:
--severity-threshold
: Default severity threshold (low, medium, high, critical)--enable-safety-mode/--disable-safety-mode
: Enable/disable exploit safety mode
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 |
--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:
Additional Commands
Command | Description |
---|---|
adversary-mcp-cli demo | Run interactive vulnerability demonstration |
adversary-mcp-cli --version | Show version information |
adversary-mcp-cli --help | Show help information |
Security Coverage
🆕 Comprehensive Triple-Engine Analysis (95+ Rules + AI + Semgrep)
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
🆕 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 other 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
- 🆕 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.7 release features a triple-engine architecture combining multiple analysis engines:
🆕 Integration Architecture
Traditional Rules-Only Analysis
🆕 AI-Enhanced Analysis
🆕 Git Diff-Aware Scanning
🆕 Advanced Configuration
LLM Configuration
🆕 Confidence and Filtering
🆕 JSON Output & Auto-Save
Structured JSON Output
All MCP tools now support JSON output format for programmatic integration:
MCP Tool Usage
CLI Usage
Automatic JSON Generation
When using MCP tools with output_format: "json"
, results are automatically saved to the project root:
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
- Trend analysis: Track security metrics over time
- Reporting: Generate dashboards from structured data
🆕 Enhanced Reporting
Detailed Analysis Reports
🆕 Statistical Analysis
🆕 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
Advanced Usage
CI/CD Integration
🆕 Git Diff-Aware CI/CD Scanning
For efficient CI/CD pipelines, scan only newly added lines in pull requests:
Traditional Full Repository Scanning
Environment Configuration
Development
Development Setup
Project Structure
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name
- Make your changes and add tests
- Run the test suite:
make test
- Submit a pull request
Version Management
The project uses centralized version management - you only need to update the version in one place:
- Update version in
pyproject.toml
: - All components automatically use the updated version:
- CLI:
adversary-mcp-cli --version
- Server: MCP server initialization
- Package:
from adversary_mcp_server import __version__
- CLI:
- Lock file updates automatically:
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.10, 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
Contributing & Quality Standards
See CONTRIBUTING.md for:
- Development setup instructions
- Code quality requirements
- Testing guidelines
- Security standards
- Release process
Support
- Documentation: GitHub Wiki
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Built with ❤️ for secure development
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:
- Working Directory IssueSolution: Specify the correct working directory:
- Branch Not FoundSolution: Verify branch names exist:
- Not a Git RepositorySolution: Ensure you're pointing to a valid git repository:
- Git Not AvailableSolution: 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 justmain
)
Example Working Configuration:
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A security-focused server that integrates with Cursor IDE to provide real-time vulnerability detection, exploit generation, and security insights during software development.
Related MCP Servers
- -securityAlicense-qualityAn AI-powered development toolkit for Cursor providing intelligent coding assistance through advanced reasoning, UI screenshot analysis, and code review tools.Last updated -738326TypeScriptMIT License
- -securityAlicense-qualityA collection of Laravel helper tools for integration with Cursor IDE, providing features like log viewing, error searching, artisan command execution, and model information display directly within the editor.Last updated -12PythonMIT License
- -securityFlicense-qualityA TypeScript-based server project that can be integrated with Cursor IDE as an MCP (Model Control Protocol) server, enabling enhanced development capabilities.Last updated -137TypeScript
- AsecurityAlicenseAqualityA security testing tool that enables automated vulnerability detection including XSS and SQL injection, along with comprehensive browser interaction capabilities for web application penetration testing.Last updated -1296417JavaScriptMIT License