Initial release of attackgraph library

Attack graph construction from network topology and vulnerability scan data
with MITRE ATT&CK mapping and risk scoring. Includes CLI, parsers for Nessus
and generic CSV, JSON/GraphML exporters, and 142 tests at 95% coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Ardis

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" 2>/dev/null || pip install -e .
+          pip install pytest pytest-cov ruff
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest --cov=attackgraph --cov-report=term-missing -v

.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.tar.gz
+*.whl

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ ./src/
+
+RUN pip install --no-cache-dir .
+
+ENTRYPOINT ["attackgraph"]
+CMD ["--help"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Wade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,191 @@
+# attackgraph
+
+**Attack graph construction from network topology and vulnerability scan data, with MITRE ATT&CK mapping and risk scoring.**
+
+## Problem
+
+Security teams face an overwhelming volume of vulnerability scan results but lack visibility into how those vulnerabilities chain together to form actual attack paths. A single medium-severity CVE on a web server might be the first step in a multi-hop path that reaches your crown jewel database. Without attack path analysis, teams waste time on isolated findings while critical chains go unaddressed.
+
+**attackgraph** solves this by:
+
+- Building directed attack graphs from network topology + vulnerability scan data
+- Computing which attack paths are actually feasible (network reachability, service matching, attack vector constraints)
+- Mapping each step to MITRE ATT&CK techniques
+- Scoring assets and paths by risk (CVSS, path length, asset criticality, cumulative probability)
+
+## Installation
+
+```bash
+pip install attackgraph
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/cwccie/attackgraph.git
+cd attackgraph
+pip install -e .
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from attackgraph import Asset, Vulnerability, AttackGraphBuilder
+from attackgraph.scoring import RiskScorer
+from attackgraph.models import AttackVector
+
+# Define assets
+web = Asset(
+    id="webserver",
+    ip="10.0.1.10",
+    hostname="web-01",
+    services=["http/80", "http/443"],
+    criticality=0.7,
+    network_zone="dmz",
+)
+db = Asset(
+    id="database",
+    ip="10.0.2.30",
+    hostname="db-01",
+    services=["mysql/3306"],
+    criticality=1.0,
+    network_zone="internal",
+)
+
+# Define vulnerabilities
+web_vuln = Vulnerability(
+    cve_id="CVE-2024-1001",
+    cvss=9.8,
+    affected_service="http/80",
+    attack_vector=AttackVector.NETWORK,
+    description="Remote code execution in HTTP server",
+)
+db_vuln = Vulnerability(
+    cve_id="CVE-2024-1007",
+    cvss=9.1,
+    affected_service="mysql/3306",
+    attack_vector=AttackVector.NETWORK,
+    description="MySQL remote code execution",
+)
+
+web.vulns.append(web_vuln)
+db.vulns.append(db_vuln)
+
+# Build the attack graph
+builder = AttackGraphBuilder(
+    topology={"webserver": ["database"]},
+    assets=[web, db],
+)
+graph = builder.build()
+
+print(f"Nodes: {graph.node_count}, Edges: {graph.edge_count}")
+
+# Score risks
+scorer = RiskScorer(graph)
+scores = scorer.score_assets()
+for asset_id, score in sorted(scores.items(), key=lambda x: x[1], reverse=True):
+    print(f"  {asset_id}: {score:.2f}")
+
+# Find attack paths to database
+paths = scorer.score_paths("database")
+for p in paths:
+    print(f"  Path: {' -> '.join(p['path'])}  Score: {p['score']:.2f}")
+```
+
+### CLI
+
+```bash
+# Build an attack graph from topology and vulnerability scan
+attackgraph build --topology topology.yaml --vulns scan.csv --output graph.json
+
+# Score assets in the graph
+attackgraph score graph.json
+
+# Find attack paths to a target
+attackgraph paths graph.json --target database
+```
+
+### Topology File Format (YAML)
+
+```yaml
+topology:
+  firewall: [webserver]
+  webserver: [appserver, workstation]
+  appserver: [database]
+
+assets:
+  firewall:
+    id: firewall
+    ip: 10.0.0.1
+    services: [http/443, ssh/22]
+    criticality: 0.9
+    network_zone: perimeter
+  webserver:
+    id: webserver
+    ip: 10.0.1.10
+    services: [http/80, http/443]
+    criticality: 0.7
+    network_zone: dmz
+```
+
+### Vulnerability CSV Format
+
+```csv
+ip,cve_id,cvss,service,attack_vector,description
+10.0.1.10,CVE-2024-1001,9.8,http/80,network,Remote code execution
+10.0.2.20,CVE-2024-1004,9.0,smb/445,network,SMB buffer overflow
+```
+
+Nessus CSV exports are also supported with `--format nessus`.
+
+## Scoring Model
+
+Risk scores combine multiple factors:
+
+- **CVSS severity** — weighted blend of max and average CVSS per asset
+- **Asset criticality** — user-defined weight (0.0–1.0) reflecting business importance
+- **Exposure** — in-degree in the attack graph (more inbound attack vectors = higher risk)
+- **Path probability** — cumulative exploitation probability along each path
+- **Path length** — shorter paths are more dangerous (fewer steps to compromise)
+
+All scores are normalized to a 0.0–10.0 scale.
+
+## MITRE ATT&CK Mapping
+
+Each attack step is automatically mapped to an ATT&CK technique using:
+
+1. **Keyword matching** on CVE descriptions (e.g., "SQL injection" → T1190, "privilege escalation" → T1068)
+2. **Service-based heuristics** (e.g., HTTP → T1190, SMB → T1210, VPN → T1133)
+3. **Default fallback** to T1210 (Exploitation of Remote Services)
+
+## Export Formats
+
+- **JSON** — full graph with metadata, suitable for further processing
+- **GraphML** — for visualization in Gephi, yEd, Cytoscape
+
+## Docker
+
+```bash
+docker build -t attackgraph .
+docker run attackgraph --help
+docker run -v $(pwd)/data:/data attackgraph build -t /data/topology.yaml -V /data/vulns.csv
+```
+
+## Development
+
+```bash
+pip install -e .
+pip install pytest pytest-cov ruff
+
+# Run tests
+pytest -v --cov=attackgraph
+
+# Lint
+ruff check src/ tests/
+```
+
+## License
+
+MIT License. Copyright (c) 2026 Corey Wade.

pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "attackgraph"
+version = "0.1.0"
+description = "Attack graph construction from network topology and vulnerability scan data, with MITRE ATT&CK mapping and risk scoring."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Corey Wade", email = "corey@example.com" },
+]
+keywords = ["security", "attack-graph", "vulnerability", "mitre-attack", "risk-scoring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "networkx>=3.0",
+    "numpy>=1.24",
+    "click>=8.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+attackgraph = "attackgraph.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/cwccie/attackgraph"
+Repository = "https://github.com/cwccie/attackgraph"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/attackgraph"]

src/attackgraph/__init__.py

@@ -0,0 +1,16 @@
+"""Attack graph construction from network topology and vulnerability scan data."""
+
+from attackgraph.builder import AttackGraphBuilder
+from attackgraph.graph import AttackGraph
+from attackgraph.models import Asset, AttackStep, Vulnerability
+from attackgraph.scoring import RiskScorer
+
+__version__ = "0.1.0"
+__all__ = [
+    "Asset",
+    "AttackStep",
+    "AttackGraph",
+    "AttackGraphBuilder",
+    "RiskScorer",
+    "Vulnerability",
+]