feat(agent): evidence-backed attack-path MVP [Automation PR 2/5]

[TFT444]

Objective

Build one evidence-backed Azure attack-path family using authoritative relationships. This is PR 2 of 5 and depends on #311.

Reviewed path

Internet exposure -> Azure workload -> managed identity -> RBAC permission -> critical Key Vault target

Scope

Canonical evidence model

Add reversible migrations for resources, relationships, attack_paths, path steps, and evidence references. Every record is bound to tenant, subscription, snapshot/evidence version, and normalization version.

Collect only:

• internet_exposes
• identity_attached_to
• can_read
• can_write
• can_manage

Every relationship stores source/target IDs, type, evidence source, collector version, observation time, expiry, confidence category, Azure evidence reference, and collection outcome.

Truth and completeness rules

• An edge exists only from current authoritative Azure evidence.
• Missing permissions, partial pagination, throttling exhaustion, malformed responses, or collector failure produce UNKNOWN; they never create or prove an edge.
• Expired evidence cannot produce an actionable path. If retained for history, return it as stale/non-actionable.
• Resource IDs must be canonical and match the authorised tenant/subscription boundary.
• Cross-subscription traversal is denied unless every subscription is explicitly authorised and the reviewed template allows it; the MVP template does not.

Path engine

Use reviewed templates and bounded deterministic Python traversal over PostgreSQL-loaded data. Enforce maximum depth, maximum nodes visited, and query timeout. No graph database or LLM is required.

Return entry point, target, ordered steps, evidence references, supporting findings, choke points, path-breaking controls, transparent risk components, algorithm version, evidence freshness, and actionable status.

APIs

• GET /api/v1/attack-paths
• GET /api/v1/attack-paths/{attack_path_id}
• GET /api/v1/attack-paths/{attack_path_id}/remediation-options

All endpoints enforce server-controlled tenant/subscription authorization and bounded pagination.

Measurable acceptance criteria

• Reviewed connected fixtures produce the exact expected ordered path.
• Disconnected, wrong-direction, malformed, empty, incomplete, expired, and permission-failure fixtures produce no actionable false path.
• Cross-tenant and unauthorised cross-subscription fixtures return no data.
• Every returned step references an existing relationship and Azure evidence record.
• At least one valid choke point and path-breaking control is returned for the reviewed scenario.
• Reprocessing the same evidence version is idempotent.
• Relationship expiry invalidates affected actionable paths within one refresh transaction.
• Traversal respects configured depth/node/time bounds under adversarial graph fixtures.
• Risk components, confidence category, freshness, template version, and algorithm version are exposed.
• Upgrade/downgrade, unit, integration, authorization, pagination, retry, concurrency, and failure-path tests pass.

Delivery evidence attached to PR

• Reviewed path threat model and counterexamples.
• Collector permission matrix and evidence freshness policy.
• Synthetic fixture set including false-path cases.
• Performance results for the configured traversal bounds.
• CI-equivalent and security-scan output.
• Read-only deployment telemetry and measured false-positive review sample.
• Security-focused human review.

Deferred

General graph exploration, additional path families, LLM-generated edges, graph infrastructure, and full blast-radius analytics.

Dependencies and handoff

Requires #311. #313 begins only after paths are reproducible, tenant-isolated, evidence-linked, and deployed read-only.

---

Mandatory safety and automation checklist

Relationship truth

• Every relationship references current authoritative Azure evidence.
• Tenant, subscription, snapshot, collector, normalization, and evidence versions are stored.
• Missing permission, incomplete pagination, timeout, malformed data, and collector failure produce UNKNOWN.
• UNKNOWN and expired evidence cannot create an actionable attack path.
• Relationship expiry invalidates affected actionable paths transactionally.
• Resource IDs are canonicalized before graph construction.

Traversal safety

• Only the reviewed path template and five approved relationship types are accepted.
• Traversal has tested maximum depth, node-count, result-count, and timeout bounds.
• Edge direction and resource-type constraints are validated for every step.
• Disconnected findings cannot be joined through text similarity or AI inference.
• MVP traversal never crosses tenant or subscription boundaries.
• Risk components are deterministic, versioned, and explainable.

Authorization and disclosure

• Every endpoint enforces server-controlled tenant/subscription authorization.
• List endpoints use bounded pagination and safe filters.
• Evidence references reveal no secrets, tokens, or unauthorized resource details.
• Public-demo mode cannot expose real attack-path evidence.

Tests and proof

• Connected fixture returns the exact reviewed ordered path.
• Disconnected, wrong-direction, cross-boundary, expired, malformed, empty, and permission-failure fixtures return no actionable false path.
• Every path step resolves to an existing relationship and evidence record.
• Reprocessing identical evidence is idempotent under concurrency.
• Adversarial large-graph fixtures stay within configured resource/time bounds.
• Alembic upgrade/downgrade and unit, integration, authorization, retry, concurrency, pagination, and failure tests pass.
• Collector permission matrix, freshness policy, algorithm version, and counterexamples are documented.
• CI-equivalent validation and security scanning pass with evidence attached.
• Security-focused human review is approved.
• Read-only telemetry and a manually reviewed false-positive sample are recorded before feat(agent): typed remediation proposals and read-only agent [Automation PR 3/5] #313 begins.

Exit gate

• No graph relationship or path is generated by an LLM.
• No known critical/high security defect remains open.
• Maintainer confirms feat(agent): evidence-backed attack-path MVP [Automation PR 2/5] #312 acceptance criteria and this checklist are complete before merge.