feat(graph): BFS attack path traversal and API endpoints

[TFT444]

Summary

PR 3/3 of the attack graph series. Depends on #353 (node and edge population).

After nodes and edges are populated, this PR computes shortest attack paths from every finding-linked node via BFS and exposes them through three new API endpoints.

New modules

alembic/versions/f2a3b4c5d6e7_attack_paths.py

• attack_paths table: path_id UUID PK, tenant_id, scan_id, source_node_id FK, target_node_id FK, path_node_ids UUID[], path_length, min_confidence, relationship_types text[], computed_at
• Unique index on (source_node_id, target_node_id, scan_id) for idempotent re-runs

scanner/graph/path_traversal.py

• compute_attack_paths(scan_id, tenant_id, dsn) -> int — BFS from each finding-linked node; paths capped at 8 hops; writes to attack_paths via ON CONFLICT DO NOTHING; returns 0 and logs on any DB error (non-fatal)
• _bfs_from(start, adj) — pure BFS returning shortest path metadata per reachable node

scanner/graph/graph_populator.py (extended)

• Adds step 4: call compute_attack_paths after finding-link step; failure is non-fatal

api/routes/attack_graph.py

• GET /api/attack-graph — nodes and edges for caller's tenant (filtered by tenant_id JWT claim or query param)
• GET /api/attack-paths?scan_id=<uuid> — pre-computed paths ordered by length and confidence
• GET /api/attack-paths/<path_id> — single path with full hop node detail
• Registered in api/app.py as attack_graph_bp

Security

All three endpoints gate on tenant_id (from JWT tenant_id claim or explicit query param) before any DB query. No cross-tenant rows are ever returned.

Test coverage

• tests/test_graph_path_traversal.py — 6 tests: isolated node, single hop, two hops, no-revisit, zero-paths, DB error
• tests/test_attack_graph_api.py — 5 tests: empty graph response, missing scan_id, invalid UUID (paths list), invalid UUID (single path), 404 not found

Merge order

1. feat(graph): evidence graph foundation - resource inventory schema and scan wiring #352 — foundation (graph tables + engine snapshot wiring)
2. feat(graph): evidence graph node and edge population #353 — node and edge population
3. This PR — path traversal and API endpoints

Closes #333. Depends on #353.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[parthrohit22]

The BFS itself is clean and easy to reason about. The hop cap and the tenant filter on every endpoint query are good, and moving tenant resolution off the query param onto the verified principal was the right fix.

I'm requesting changes, mostly because of what's upstream. With the #352/#353 issues this step always has nothing to work on: no snapshot in real scans, and even with one, finding_graph_nodes is empty because linking runs before save_scan. So compute_attack_paths returns 0 on every scan, and the API only ever serves empty lists. Once those are fixed, a few things here are worth sorting before merge:

1. Edge direction doesn't match "attack path from a finding"

BFS follows edges source → target, but the edge directions from #353 are mixed: EXPOSES is PublicIP→NIC, HAS_IDENTITY is identity→resource, REACHABLE_VIA is storage→PE, MEMBER_OF is resource→subnet. Starting from a flagged storage account you reach its private endpoint. But starting from a flagged VM/NIC you can never reach the public IP that exposes it, and that's the path people will actually care about. Could you either define edge direction as "attacker can move from A to B" consistently, or traverse with per-relationship direction rules?

2. Row growth

Every scan writes one row per (finding node × reachable node), and nothing ever deletes old scans' paths. On a subscription with a few hundred findings in a connected VNet this grows quickly. At minimum, keep only the latest scan per subscription, or add a retention step. Also, _write_paths returns len(rows) even when ON CONFLICT DO NOTHING skips them, so the logged count can overstate what was written.

3. Tenant resolution in shared-secret mode

In shared-secret mode tenant is always None, so every non-admin caller gets 400 tenant_id not available. Admins can pass any X-Tenant-Id. If that's intentional for now, please mention it in the API docs. Otherwise a 400 for a normal viewer feels like the wrong status (403, or scoping by subscription like the rest of the API).

Small

• /api/attack-graph returns edges where only one end is in the page of nodes, so the client gets dangling node_ids. Filtering with AND instead of OR, or returning the other endpoints too, would keep the payload consistent.
• _conn() opens a raw connection per request. The other routes go through DatabaseManager, which shares the pool metrics in api/observability.py. Reusing it would keep /metrics accurate.

Happy to re-review once #352 and #353 settle.

[TFT444]

Both items addressed:

1. BFS bidirectional traversal: _load_adjacency() now adds reverse edges to the adjacency map (with _REV suffix on the relationship type). BFS from a flagged resource can now reach nodes that point TO it, e.g. a VM with a finding can reach the PublicIP that EXPOSES it.
2. AND filter on /api/attack-graph edges: Changed OR to AND in the edge query so only edges where both endpoints appear in the returned node page are included. No more dangling node references on the client.

[parthrohit22]

Re-reviewed 63c223c. The AND filter on /api/attack-graph edges is right: no more dangling node IDs.

This head brings back the bug #353 just fixed, though.

1. Regression: populate_graph() runs inside run_scan() again

Commit 830ca7a ("wire post-scan node and edge population into ScanEngine") sits on top of #353's fix. It re-adds the in-engine call at scanner/engine.py:205-211, while scanner/worker.py:219-226 still calls it after save_scan(). On this head every scan therefore populates the graph twice:

• first inside run_scan(), before findings are saved, so link_findings_to_nodes links 0 findings and compute_attack_paths has no sources;
• then again from the worker.

It looks like a rebase artefact. Please drop 830ca7a (or remove that block) so the worker is the only caller.

2. Fully bidirectional BFS turns the graph into an undirected one

Adding a _REV edge for every edge answers "the VM can't reach the public IP that exposes it". But it also lets BFS walk any relationship backwards. For example, MEMBER_OF reversed goes subnet → every other member, so every resource sharing a subnet with a flagged resource becomes reachable within two hops. On a real VNet the path count becomes roughly findings × subnet size, which is also why the row growth below matters. What I asked for was per-relationship direction ("attacker can move from A to B"):

• Reverse: EXPOSES (reach the exposing public IP) and HAS_IDENTITY (reach the identity a resource runs as).
• Forward only: MEMBER_OF and PROTECTS.

A small {relationship: (forward, reverse)} table in path_traversal.py does it. Please add a test with two unrelated VMs in one subnet, asserting that a finding on one does not produce a path to the other.

3. Still open from my first review

• Row growth: paths are written per scan and never pruned, and _write_paths still returns len(rows) even when ON CONFLICT DO NOTHING skips rows. With 2 in place this is worse. Keep only the latest scan's paths per subscription, or add retention, and return cur.rowcount.
• Shared-secret mode: every non-admin caller still gets 400 tenant_id not available. If that's intended until OIDC is the only mode, say so in docs/api-reference.md. Otherwise 403, or scoping by subscription like the rest of the API, is the right response.
• _conn(): it still opens a raw psycopg2 connection per request instead of going through DatabaseManager. Those connections are invisible to the pool metrics in /metrics.

CI

• Lint fails with the same unused MagicMock import in tests/test_graph_engine_post_scan.py.
• Backend Tests fails with the same 5 failures and 1 error inherited from #352's down_revision.

A second migration (f2a3b4c5d6e7_attack_paths.py) stacks on e1f2a3b4c5d6. Once #352 changes to a single parent, check that alembic heads is still one head across the stack.