Neo4j-based blast-radius analysis combining NVD vulnerability data with a custom asset inventory. Offline ingestion loads the graph; a Streamlit interface serves read-only queries online.
- Offline ingestion — NVD CVE feeds + asset inventory → Neo4j
- Online interface — Streamlit app querying blast radius read-only
See docs/architecture.md and docs/graph-model.md for details.
Learning GraphRAG? Follow the phased checklist in LEARNING_PATH.md.
| Tool | Version | Purpose |
|---|---|---|
| Python | 3.12+ | Runtime |
| uv | latest | Dependency management (recommended) |
| Docker | latest | Local Neo4j |
| Git | latest | Version control |
git clone <repo-url> blast-radius-analysis
cd blast-radius-analysis
# Install all dependency groups (core, ingestion, app, dev)
make install
# or: uv sync --all-groupscp .env.example .env.localEdit .env.local with your credentials. Required variables:
| Variable | Example | Description |
|---|---|---|
NEO4J_URI |
bolt://localhost:7687 |
Neo4j Bolt endpoint |
NEO4J_USER |
neo4j |
Neo4j username |
NEO4J_PASSWORD |
(your password) | Neo4j password |
DATA_DIR |
./data |
Staging dir for NVD feeds |
INVENTORY_PATH |
./data/inventory/assets.yaml |
Asset inventory file |
Never commit .env.local. Placeholders belong in .env.example only.
Optional: copy non-secret defaults for batch sizes and feed URLs:
cp config/settings.yaml.example config/settings.yamlmake neo4j-upNeo4j Browser: http://localhost:7474 (default auth in docker-compose.yml is neo4j / changeme).
To stop:
make neo4j-downmake pre-commit-installThis installs a git hook that scans staged files for OpenAI and Neo4j secrets before each commit. See Commits below.
Copy the sample fixture or create your own file — see Upload your own assets below.
mkdir -p data/inventory
cp tests/fixtures/inventory/sample_assets.yaml data/inventory/assets.yamlQuick start with bundled sample data:
make schema-apply
make ingest-nvd-sample # sample CVE feed (CVE-2024-0001 → nginx CPE)
make ingest-inventory # sample assets (web-server-01, api-gateway-01)For production NVD feeds and custom inventory paths, see Update NVD data and Upload your own assets.
Full ingest in one step:
make ingest-all # schema + NVD feeds + asset inventorySee docs/ingestion-runbook.md for the full runbook.
make run-app
# or: blast-radius-appTry the sample queries once data is loaded.
Asset inventory files describe your infrastructure and dependency graph. They are loaded separately from NVD data.
Default path: data/inventory/assets.yaml (override with the INVENTORY_PATH env var in .env.local).
Start from the sample fixture:
mkdir -p data/inventory
cp tests/fixtures/inventory/sample_assets.yaml data/inventory/assets.yaml
# edit data/inventory/assets.yaml with your assetsYAML format (each asset needs a unique id and name; cpes and depends_on are optional):
assets:
- id: web-server-01
name: Production Web Server
cpes:
- cpe:2.3:a:nginx:nginx:1.24.0:*:*:*:*:*:*:*
depends_on:
- api-gateway-01Validation rules (enforced at ingest time):
idmust be unique across all assetsdepends_onentries must reference existing asset ids- CPE strings should conform to CPE 2.3 format
Load into Neo4j:
make ingest-inventory
# or specify a custom path:
blast-radius ingest inventory --file path/to/my-assets.yamlFull schema and field reference: docs/inventory-format.md.
NVD CVE feeds (JSON 2.0 format) are stored under data/nvd/ (gitignored). Ingest them offline into Neo4j:
make ingest-nvd # ingest all local files in data/nvd/
blast-radius ingest nvd --year 2024 # download and ingest a specific year
blast-radius ingest nvd --file path/to/feed.json # ingest a single local fileAuto-download: when data/nvd/ is empty, make ingest-nvd (or blast-radius ingest nvd with no flags) downloads the current year's feed automatically. Pass --no-download to fail instead of downloading.
Quick dev sample (no download required):
make ingest-nvd-sample # loads tests/fixtures/nvd/sample_feed.json (CVE-2024-0001)Idempotent re-runs: re-ingesting the same feeds or inventory is safe — writes use MERGE, so you can refresh data without clearing the graph first.
Operational details and troubleshooting: docs/ingestion-runbook.md.
After ingesting the sample fixture (make ingest-nvd-sample + make ingest-inventory), the graph includes assets web-server-01 and api-gateway-01, linked by dependency, and CVE CVE-2024-0001 affecting nginx 1.24.0 on web-server-01.
Find assets and CVEs reachable from a seed asset through DEPENDS_ON edges.
CLI (GraphRAG):
make ask Q="What is the blast radius of web-server-01?"
blast-radius ask "Which CVEs affect web-server-01 and its dependencies?"Streamlit: open Blast Radius, enter web-server-01, set depth to 3, click Analyse blast radius.
Find assets impacted by a specific CVE (via CPE match and dependency traversal).
CLI:
make ask Q="Which assets are impacted by CVE-2024-0001?"Streamlit: open CVE Lookup → By CVE tab, enter CVE-2024-0001, click Find impacted assets. Expect web-server-01 (direct CPE match) and api-gateway-01 (upstream dependency).
List CVEs that affect a given CPE string.
CLI:
make ask Q="What CVEs affect cpe:2.3:a:nginx:nginx:1.24.0:*:*:*:*:*:*:*?"Streamlit: open CVE Lookup → By CPE tab, enter the nginx CPE above, click Find CVEs for CPE. Expect CVE-2024-0001.
Natural-language questions across blast radius, CVE impact, and inventory.
CLI:
make ask Q="Explain the blast radius from web-server-01 for CVE-2024-0001"Streamlit: open GraphRAG Chat and ask the same question in the chat input.
OPENAI_API_KEY in .env.local is optional. Without it, GraphRAG returns structured graph fallback text; with it, answers are natural-language summaries grounded in retrieved graph context.
blast-radius-analysis/
├── README.md
├── pyproject.toml # package config, dependency groups, CLI entry points
├── uv.lock # locked dependencies (uv)
├── Makefile # common tasks (neo4j, ingest, test, lint)
├── docker-compose.yml # local Neo4j with APOC
├── .env.example # credential placeholders (safe to commit)
├── .pre-commit-config.yaml # git hooks (secret scanning, formatting)
│
├── config/
│ ├── settings.yaml.example # non-secret defaults (feed URLs, batch sizes)
│ └── logging.yaml # logging config for CLI and ingestion
│
├── cypher/
│ ├── schema.cypher # constraints and indexes (idempotent)
│ └── migrations/ # future schema versions
│
├── data/ # gitignored staging area
│ ├── nvd/ # downloaded NVD JSON feeds
│ └── inventory/ # user asset inventory files
│
├── docs/
│ ├── architecture.md # module boundaries and data flow
│ ├── graph-model.md # Neo4j node/relationship schema
│ ├── ingestion-runbook.md # offline ingest procedures
│ └── inventory-format.md # asset inventory YAML schema
│
├── scripts/
│ ├── bootstrap_neo4j.sh # apply cypher/schema.cypher
│ ├── download_nvd.sh # NVD ingest wrapper
│ ├── run_streamlit.sh # Streamlit entry wrapper
│ └── hooks/
│ └── scan_secrets.py # pre-commit secret scanner
│
├── src/
│ └── blast_radius/ # main Python package
│ ├── config/ # pydantic-settings (Neo4j, paths, feed URLs)
│ ├── domain/ # shared data models (CVE, CPE, Asset)
│ ├── ingestion/ # offline write path → Neo4j
│ │ ├── nvd/ # download, parse, transform NVD feeds
│ │ ├── inventory/ # read, validate, transform asset files
│ │ ├── neo4j/ # driver, batched loader, schema apply
│ │ └── pipeline.py # orchestrates ingest runs
│ ├── graph/ # online read path ← Neo4j
│ │ ├── repository.py # parameterized Cypher queries
│ │ ├── blast_radius.py # traversal logic
│ │ └── queries/ # .cypher query files
│ ├── app/ # Streamlit UI (must not import ingestion/)
│ │ ├── main.py # app entry point
│ │ ├── components/ # search, graph viz, severity badges
│ │ └── pages/ # Blast Radius, CVE Lookup, Asset Inventory, GraphRAG Chat
│ └── cli/ # Typer CLI for offline jobs
│ ├── ingest.py # blast-radius ingest nvd|inventory|all
│ ├── ask.py # blast-radius ask (GraphRAG)
│ └── schema.py # blast-radius schema apply
│
└── tests/
├── conftest.py # shared fixtures
├── fixtures/ # sample NVD JSON and inventory YAML
├── unit/ # fast, isolated tests
│ ├── domain/
│ ├── ingestion/
│ ├── graph/
│ └── hooks/ # pre-commit scanner tests
└── integration/ # Neo4j-dependent tests (@pytest.mark.integration)
| Module | Writes Neo4j | Reads Neo4j | Notes |
|---|---|---|---|
ingestion/ |
Yes | Yes | Offline only |
graph/ |
No | Yes | Shared by app and tests |
app/ |
No | Via graph/ |
Never imports ingestion/ |
Every commit runs hooks automatically (after make pre-commit-install):
- Merge conflict markers
- Trailing whitespace and end-of-file fixes
- OpenAI and Neo4j secret scan — blocks real API keys, passwords, and
.envfiles
Run manually before pushing:
pre-commit run --all-files| File | Reason |
|---|---|
.env, .env.local, .env.prod |
Real credentials |
data/nvd/** |
Large downloaded feeds |
data/inventory/** |
Environment-specific assets |
.venv/, __pycache__/ |
Generated artifacts |
Use Conventional Commits with a lowercase type prefix:
<type>: <short summary in imperative mood>
[optional body explaining why, not what]
| Type | When to use | Example |
|---|---|---|
feat |
New feature | feat: add NVD JSON 2.0 parser |
fix |
Bug fix | fix: handle missing CVSS score in transformer |
docs |
Documentation only | docs: document inventory YAML schema |
test |
Tests only | test: add parser fixtures for CVE records |
refactor |
Code change, no behaviour change | refactor: extract Neo4j batch loader |
chore |
Tooling, deps, CI | chore: add pre-commit secret scanner |
Examples:
git commit -m "feat: implement NVD feed downloader"
git commit -m "fix: skip placeholder values in secret scanner"
git commit -m "docs: update README setup and folder structure"Keep commits focused — one logical change per commit. Run tests and lint before committing:
make test
make lintblast-radius ingest nvd [--year YYYY] [--file PATH] [--no-download]
blast-radius ingest inventory [--file PATH]
blast-radius ingest all
blast-radius schema apply
blast-radius ask "your question" [--depth N]| Target | Description |
|---|---|
make install |
Install all dependency groups |
make pre-commit-install |
Install git hooks |
make neo4j-up / neo4j-down |
Start / stop Neo4j container |
make schema-apply |
Apply Neo4j schema |
make ingest-nvd |
Ingest NVD feeds from data/nvd/ (auto-download if empty) |
make ingest-nvd-sample |
Ingest bundled sample NVD feed |
make ingest-inventory |
Ingest asset inventory |
make ingest-all |
Schema + both ingests |
make ask Q="..." |
GraphRAG CLI query (requires quoted Q=) |
make run-app |
Start Streamlit UI |
make test |
Unit tests |
make test-all |
Unit + integration tests |
make lint |
Ruff check and format |
make test # unit tests only
make test-all # unit + integration (requires Neo4j)Licensed under the Apache License, Version 2.0.