Skip to content

About

Blast Radius Analyser — a Neo4j-based security tool that maps NVD vulnerability data and your asset inventory into a graph, then lets you explore blast radius (which assets and dependencies are exposed to which CVEs) via structured queries and a Streamlit GraphRAG chat interface.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Blast Radius Analyser

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.

Architecture

  • 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.


Setup

Prerequisites

Tool Version Purpose
Python 3.12+ Runtime
uv latest Dependency management (recommended)
Docker latest Local Neo4j
Git latest Version control

1. Clone and install

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-groups

2. Configure environment

cp .env.example .env.local

Edit .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.yaml

3. Start Neo4j

make neo4j-up

Neo4j Browser: http://localhost:7474 (default auth in docker-compose.yml is neo4j / changeme).

To stop:

make neo4j-down

4. Install pre-commit hooks

make pre-commit-install

This installs a git hook that scans staged files for OpenAI and Neo4j secrets before each commit. See Commits below.

5. Prepare asset inventory (optional)

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.yaml

6. Ingest data (offline)

Quick 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 inventory

See docs/ingestion-runbook.md for the full runbook.

7. Run the app (online)

make run-app
# or: blast-radius-app

Try the sample queries once data is loaded.


Upload your own assets

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 assets

YAML 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-01

Validation rules (enforced at ingest time):

  • id must be unique across all assets
  • depends_on entries 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.yaml

Full schema and field reference: docs/inventory-format.md.


Update NVD data

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 file

Auto-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.


Sample queries

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.

Blast radius

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.

CVE impact

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).

CPE lookup

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.

GraphRAG chat

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.


Folder structure

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 boundaries

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/

Commits

Pre-commit checks

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 .env files

Run manually before pushing:

pre-commit run --all-files

What not to commit

File Reason
.env, .env.local, .env.prod Real credentials
data/nvd/** Large downloaded feeds
data/inventory/** Environment-specific assets
.venv/, __pycache__/ Generated artifacts

Commit message format

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 lint

CLI reference

blast-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]

Make targets

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

Testing

make test               # unit tests only
make test-all           # unit + integration (requires Neo4j)

License

Licensed under the Apache License, Version 2.0.

About

Blast Radius Analyser — a Neo4j-based security tool that maps NVD vulnerability data and your asset inventory into a graph, then lets you explore blast radius (which assets and dependencies are exposed to which CVEs) via structured queries and a Streamlit GraphRAG chat interface.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages