PerspectiveGraph manual
The complete reference: how the engine models risk, how to run it, how to deploy it and how to operate it. The README is the short version - what this is, how to see it working in ninety seconds, and what it does not yet claim.
It is split into pages, one per subject, and published with search at
docs.a3thinker.it. The pages here in docs/manual/ are the
source of that site: a change to either is a change to both.
Contents
Section titled “Contents”| Page | What it covers |
|---|---|
| How it works | What an attack path is, the architecture that finds one, and the data model underneath. |
| Scoring and priority | How a route gets its probability, how honest that probability is, and what decides which route to fix first. |
| Accuracy: calibration and validation | How the engine grades its own scores against real outcomes, and what it does with the result. |
| Quick start | Running the stack, feeding it sample data, and seeing the first attack path. |
| Attack paths in the pull request | The merge gate - GitHub Action, CLI and Trivy plugin - and what a developer sees on the pull request. |
| Sources and integrations | Agentless connectors, topology discovery, supply-chain provenance, identity resolution and threat intelligence. |
| Working the findings | Remediation and detection-as-code, the choke-point optimizer, triage and suppression, and trends over time. |
| AI assistant and MCP | Asking the attack surface questions in plain language, and letting an agent query it. |
| Security, authentication and hardening | Data hygiene, tenants and SSO, authentication and audit, and hardening the containers and the application. |
| Deploy to Kubernetes | The Helm chart, a local cluster with the SSO demo, and hardening a real deployment. |
| Running it: freshness, backup and scaling | Keeping the graph fresh, backing it up and restoring it, and scaling the analyzer. |
| Onboarding runbook | Pointing it at your own environment, source by source, until the first path appears. |
Where each section went
Section titled “Where each section went”This manual was one page until it passed three thousand lines. Links into that page still arrive here: every section it had is listed below, with the page it moved to.
| Section | Now in |
|---|---|
| The core idea | How it works |
| Architecture | How it works |
| The ontology | How it works |
| Risk scoring | Scoring and priority |
| Scaling the analyzer | Scoring and priority |
| Beyond the single best path | Scoring and priority |
| Closing the loop: calibration against observed outcomes | Accuracy: calibration and validation |
| Event contract | How it works |
| Component map | How it works |
| Tech stack | How it works |
| Quick start | Quick start |
| The wedge: attack paths in your pull request | Attack paths in the pull request |
| Agentless connectors: pull, don’t wait for an upload | Sources and integrations |
| Topology discovery (no hand-stitched IDs) | Sources and integrations |
| Supply-chain provenance (SBOM, signing, SLSA) | Sources and integrations |
| Closing the loop: drift, detection-as-code, SIEM export | Working the findings |
| Choke-point remediation optimizer | Working the findings |
| Ask your attack surface (AI-native - Claude or HuggingFace) | AI assistant and MCP |
| Letting an agent query it (MCP) | AI assistant and MCP |
| Honest probabilities: provenance, not false precision | Scoring and priority |
| Triage priority: what to fix first, not 500 findings | Scoring and priority |
| Data hygiene: a map of the attack surface, never a vault of secrets | Security, authentication and hardening |
| Multi-tenant isolation & SSO login | Security, authentication and hardening |
| Validated against reality (precision & recall) | Accuracy: calibration and validation |
| Quantified risk, what-if & compliance export | Scoring and priority |
| Triage & suppression (close the false-positive loop) | Working the findings |
| Trends, MTTR & regressions (the temporal layer) | Working the findings |
| Identity resolution you can trust (confidence + explainability) | Sources and integrations |
| Threat-intel: KEV + EPSS (optional) | Sources and integrations |
| KEV holdout: a calibration dataset that builds itself (optional) | Accuracy: calibration and validation |
| Auth, multi-tenancy & audit (optional, but do it before production) | Security, authentication and hardening |
| Developer feedback on the PR | Attack paths in the pull request |
| Container & compose hardening | Security, authentication and hardening |
| Application hardening | Security, authentication and hardening |
| Deploy to Kubernetes | Deploy to Kubernetes |
| Local cluster (Docker Desktop / kind / minikube) + SSO demo | Deploy to Kubernetes |
| Hardening a real deployment (beyond a trusted cluster) | Deploy to Kubernetes |
| Operating it: freshness, backup & DR | Running it: freshness, backup and scaling |
| Scaling the analyzer | Running it: freshness, backup and scaling |
| Onboarding runbook | Onboarding runbook |
| 0. Prerequisites | Onboarding runbook |
| 1. The order that builds a correct graph | Onboarding runbook |
| 2. Per-source snippets | Onboarding runbook |
| 3. The two markers that make paths appear | Onboarding runbook |
| 4. Identifier correlation (the make-or-break detail) | Onboarding runbook |
| 5. Network topology - now auto-discovered | Onboarding runbook |
| 6. Verify a path formed | Onboarding runbook |
| 7. Troubleshooting - “I see no attack paths” | Onboarding runbook |
| 8. Run it continuously | Onboarding runbook |