Attack Path Intelligence Engine
From exposure to compromise.
PivotMap is an open-source Python-based attack path intelligence engine for offensive security professionals. It does not perform active scanning. Instead, it ingests scan results, correlates vulnerabilities, builds an attack graph, and identifies realistic compromise paths.
- Vulnerability lists are not intelligence
- CVSS alone is insufficient
- Attack paths matter more than raw findings
- Context determines exploitability
- Correlation over enumeration
- Ingestion Layer: Parse Nmap XML and Nuclei JSON scan results
- Correlation Engine: Match services to CVEs with fuzzy version matching
- Graph Engine: Build directed attack graphs with networkx
- Pivot Engine: Compute shortest, highest impact, and lowest complexity paths
- PivotScore System: Multi-factor scoring (exploitability × exposure × privilege × network position × criticality)
- Reporting: Generate Markdown, HTML, and JSON reports
- Operating System: Windows 10/11, Linux, macOS
- Python: Version 3.12 or higher
- Memory: Minimum 4GB RAM (8GB recommended for large graphs)
- Disk Space: 500MB for installation, additional space for CVE database
Install from PyPI when published:
pip install pivotmapWith optional dependencies:
# With Redis support for background jobs
pip install pivotmap[redis]
# With visualization support
pip install pivotmap[viz]
# With all optional features
pip install pivotmap[all]Clone the repository and install in development mode:
# Clone repository
git clone https://github.com/tworjaga/pivotmap.git
# Enter directory
cd pivotmap
# Create virtual environment (recommended)
python -m venv .venv
# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Install package in editable mode
pip install -e .For Windows users, use the provided batch file:
# Download or clone the repository
git clone https://github.com/tworjaga/pivotmap.git
cd pivotmap
# Run the setup script
start.batThe start.bat script will:
- Check Python installation
- Create virtual environment
- Install all dependencies
- Install PivotMap in development mode
- Display usage instructions
Run PivotMap in a containerized environment:
# Clone repository
git clone https://github.com/tworjaga/pivotmap.git
cd pivotmap
# Build and run with Docker Compose
docker-compose up -d
# Or build manually
docker build -t pivotmap .
# Run container
docker run -p 8000:8000 -v ./data:/app/data pivotmapDocker Compose includes:
- PivotMap API server (port 8000)
- Optional Redis for background jobs
- Persistent data volumes
- Health checks
# Check CLI is working
pivotmap --version
# Check API can be imported
python -c "from pivotmap.api import app; print('API OK')"
# Run tests
pytest tests/Download test scan files to get started:
# Create test directory
mkdir test_data
cd test_data
# Download sample Nmap XML (replace with your own scan)
# Example: nmap -sV -oX scan.xml target.com
# Download sample Nuclei JSON (replace with your own results)
# Example: nuclei -u target.com -json -o vulns.json# Import scan results
pivotmap import scan.xml
pivotmap import vulns.json --format nuclei
# Build attack graph
pivotmap analyze --nmap scan.xml --nuclei vulns.json
# Find top attack paths
pivotmap paths --top 10
# Generate report
pivotmap report --format html --output report.html# Start API server
uvicorn pivotmap.api:app --reload
# Import and analyze
curl -X POST -F "file=@scan.xml" http://localhost:8000/import
curl -X POST http://localhost:8000/analyze
# Get attack paths
curl http://localhost:8000/paths?top=5
# Generate report
curl http://localhost:8000/report?format=markdownpivotmap/
├── core/ # Data models, scoring, graph builder
├── ingest/ # Nmap/Nuclei parsers
├── knowledge/ # CVE database, exploit metadata
├── engine/ # Pivot engine, path finder
├── reporting/ # Report generators
├── cli.py # Command-line interface
├── api.py # FastAPI endpoints
└── config.py # Configuration management
| Package | Version | Purpose |
|---|---|---|
| Python | >=3.12 | Runtime |
| FastAPI | >=0.109.0 | API framework |
| Typer | >=0.9.0 | CLI framework |
| Rich | >=13.7.0 | Terminal output |
| Pydantic | >=2.5.0 | Data validation |
| SQLModel | >=0.0.14 | ORM |
| networkx | >=3.2.0 | Graph engine |
| httpx | >=0.26.0 | HTTP client |
| WeasyPrint | >=60.0 | PDF generation |
| PyYAML | >=6.0.1 | YAML parsing |
| Jinja2 | >=3.1.3 | Template engine |
| Package | Purpose |
|---|---|
| redis | Background job queue |
| rq | Job processing |
| pyvis | Interactive graph visualization |
| matplotlib | Static graph plots |
- Source code: ~150KB
- Dependencies: ~50-100MB
- CVE database (optional): ~500MB
Problem: pip install fails with Python version error
Solution: Ensure Python 3.12+ is installed: python --version
Problem: ModuleNotFoundError after installation
Solution: Install in editable mode: pip install -e .
Problem: WeasyPrint installation fails Solution: Install system dependencies (GTK+) from https://weasyprint.org
Problem: Out of memory with large graphs
Solution: Enable graph pruning in config: graph.pruning_enabled = true
Problem: Slow CVE matching
Solution: Use SQLite backend: cve.backend = "sqlite"
MIT License - see LICENSE file for details.
Contributions welcome. Please follow conventional commits format.
- Fork the repository
- Create feature branch:
git checkout -b feat/new-feature - Commit changes:
git commit -m "feat: add new feature" - Push to branch:
git push origin feat/new-feature - Open Pull Request
- GitHub: https://github.com/tworjaga
- Telegram: @al7exy
- Project: https://github.com/tworjaga/pivotmap
See CHANGELOG.md for version history.