AI-Powered Security Vulnerability Detection and Fixing
Patchsmith combines the power of CodeQL static analysis with Claude AI to automatically detect, triage, and fix security vulnerabilities in your codebase.
Patchsmith's CLI interface with real-time progress tracking, intelligent triage, and comprehensive security reports
- 🔍 Static Analysis - Powered by GitHub's CodeQL engine
- 🤖 AI Triage - Intelligent prioritization and grouping of security findings
- 🔗 Smart Grouping - Automatically groups similar findings to avoid redundant analysis
- 🔬 Detailed Assessment - Comprehensive security analysis with attack scenarios
- 🎯 Custom Queries - AI-generated CodeQL queries tailored to your project
- 🛠️ Automated Fixing - AI-generated patches for vulnerabilities
- 📊 Rich Reports - Detailed reports in Markdown and HTML
- 🎨 Beautiful CLI - Intuitive interface with progress tracking
- 🔄 Git Integration - Automatic branching and commits for fixes
-
Python 3.10+
python --version # Should be 3.10 or higher -
CodeQL CLI (required for analysis)
# Download from GitHub releases # https://github.com/github/codeql-cli-binaries/releases # On macOS with Homebrew: brew install codeql # Verify installation: codeql version
pipx install "git+https://github.com/eschnou/patchsmith.git"# Clone the repository
git clone https://github.com/yourusername/patchsmith.git
cd patchsmith
# Install with Poetry
poetry install
# Run Patchsmith
poetry run patchsmith --helpUsing Poetry Shell for Other Repositories
To analyze other projects without prefixing every command with poetry run, activate the Poetry virtual environment:
# From the patchsmith directory, activate the virtual environment
poetry shell
# Now you can use patchsmith directly on any repository
cd /path/to/your/project
patchsmith init
patchsmith analyze --investigate
# Exit the virtual environment when done
exitThis approach is especially useful when working with multiple projects, as you can navigate anywhere and run patchsmith commands directly without the poetry run prefix.
cd /path/to/your/project
patchsmith init# Quick triage (fast, groups findings, assigns priorities)
patchsmith analyze
# Full analysis with deep investigation of top 10 groups
patchsmith analyze --investigate
# Analyze specific project
patchsmith analyze /path/to/project --investigate
# Save results to file
patchsmith analyze -o results.json# Generate project-specific CodeQL queries
patchsmith finetune
# Focus on specific security concerns
patchsmith finetune --focus "SQL injection and authentication bypass"
# Use custom queries in analysis
patchsmith analyze --investigate# List all findings with grouping info
patchsmith list
# Show only critical findings
patchsmith list --severity critical# Deep investigation of a specific finding
patchsmith investigate F-20# Generate markdown report
patchsmith report
# Generate HTML report
patchsmith report --format html# Interactive mode (recommended)
patchsmith fix --interactive
# Fix specific finding
patchsmith fix <finding-id>
# Auto-apply fix (use with caution!)
patchsmith fix <finding-id> --apply# Clean cached results (keeps database)
patchsmith clean
# Remove everything including database
patchsmith clean --allPatchsmith uses a two-tier analysis system:
-
Triage (Always Runs) - Fast analysis that:
- Groups similar findings (e.g., 6 instances of same pattern → 1 group)
- Assigns priority scores to all groups
- Marks top 10 groups for deep investigation
- Takes ~5-20 minutes
-
Investigation (Optional with
--investigate) - Deep AI analysis that:- Analyzes top 10 priority groups in detail
- Generates attack scenarios and impact assessments
- Provides exploitability scores and remediation guidance
- Takes additional ~10-30 minutes
Grouping Example:
50 raw findings → 15 distinct groups → top 10 investigated
Grouping Indicators:
F-20- Single findingF-20 🔗×6- Group of 6 similar findings
This approach saves time and API costs while ensuring thorough analysis of critical issues.
- CLI Guide - Complete command reference and examples
- Architecture - Technical design and architecture
- Requirements - Full requirements specification
┌──────────────────────────────────────────────────────────┐
│ Layer 4: Presentation │
│ • CLI (Rich UI) │
│ • HTTP API (coming soon) │
├──────────────────────────────────────────────────────────┤
│ Layer 3: Orchestration │
│ • Workflow management │
│ • Exception and error handling │
│ • Progress tracking │
├──────────────────────────────────────────────────────────┤
│ Layer 2: Custom Agents │
│ • Analysis agents (triage, investigation) │
│ • Brainstorming agents (vulnerability suggestions) │
│ • Review agents (fix validation) │
│ • Code generation agents (query, patch) │
├──────────────────────────────────────────────────────────┤
│ Layer 1: Tools Wrapper │
│ • CodeQL CLI │
│ • Git │
│ • GitHub API │
└──────────────────────────────────────────────────────────┘
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov
# Run manual end-to-end test
poetry run python tests/manual_test_service_layer.py /path/to/projectPatchsmith is free and open-source software licensed under the GNU General Public License v3.0 (GPL-3.0).
This means you can:
- ✅ Use Patchsmith for any purpose (commercial or personal)
- ✅ Study and modify the source code
- ✅ Distribute copies of Patchsmith
- ✅ Distribute modified versions
Requirements:
- 📋 Any distributed modifications must also be open-source under GPL-3.0
- 📋 You must include the original license and copyright notices
- 📋 You must state significant changes made to the software
See the LICENSE file for the full license text.
Why GPL-3.0? We believe security tools should be transparent and open. The GPL ensures that improvements to Patchsmith remain available to the entire security community.
- CodeQL - Semantic code analysis by GitHub
- Claude AI - AI assistant by Anthropic
- Rich - Beautiful terminal formatting
Made with ❤️ by Transcode for secure software development