PerspectiveGraph
PerspectiveGraph's MCP server lets an agent query a security graph read-only to understand, prioritize, and test fixes for attack paths.
Get an environment posture overview, including path counts, mapped assets, sensitive targets, applications, and overall simulated compromise risk.
List ranked attack paths with pagination and application filtering, including scores, priority bands, confidence, and runtime confirmation.
Explain a specific attack path hop by hop, including MITRE ATT&CK mapping, probability provenance, credible intervals, and remediation suggestions.
Enumerate the best distinct routes to a chosen sensitive target and identify shared choke points.
Generate a remediation plan showing the fewest changes that cut the most risk, with affected route counts and risk coverage.
Simulate cutting graph edges to test whether a fix would remove paths or reduce risk, without changing anything.
Search indexed assets and findings by name, CVE, or keyword when OpenSearch is enabled.
Check whether scores and priority rankings are calibrated or trustworthy against recorded red-team/BAS outcomes.
All exposed tools are read-only, idempotent, and non-destructive.
Ingests Falco runtime security scanner output as a data source for attack-path analysis and runtime confirmation.
Runs attack-path analysis on pull requests, reports PR check statuses, and generates one-click fix pull requests.
Ingests Kubernetes output as a data source for attack-path analysis and environment mapping.
PerspectiveGraph joins what you already run - Trivy, Semgrep, Cloud Custodian, Falco, plus your AWS and Kubernetes state - into one graph of your real environment, and asks a single question of it: can someone get from the internet, through privilege that is too broad, to something worth stealing?
On a pull request it asks that question before the merge: the check goes red only when this change opens a route, and the fix comes back as its own pull request. Open source (Apache 2.0), runs on your infrastructure, collects no telemetry.

Twelve seconds of make demo: what is exploitable now → the ranked routes → one route's kill
chain and the fix it generates → whether the scores can be trusted. Sample scanner output and
seeded verdicts, not a real environment.
See it running - the same dashboard, published read-only. Nothing to install.
Read the documentation - the manual, one page per subject, with search.
Check your own AWS account - one read-only command, no deployment.
Put it on your pull requests - ten lines of YAML.
A score here is what the model concludes from the evidence it was given, not a measured frequency: nothing has been calibrated against field data yet, and the engine says so itself rather than rounding up. What is measured, and what is not.
Check your own account in 30 seconds
No deployment, no Docker, nothing ingested. One static binary asks AWS's own policy evaluator which of your roles can reach administrator - applying the service control policies, permission boundaries and condition keys that a policy reader on its own does not see:
# macOS (Apple silicon); swap darwin_arm64 for linux_amd64, linux_arm64 or darwin_amd64
curl -sSL https://github.com/luiacuaniello/perspectivegraph/releases/latest/download/perspectivegraph_darwin_arm64.tar.gz | tar xz
./perspectivegraph redteam -roles -region eu-west-1It is read-only and free: each check is one iam:SimulatePrincipalPolicy dry run, which
creates nothing and costs nothing, and the only permissions it needs are that and
iam:ListRoles, both inside SecurityAudit. Windows builds are on the
releases page; every binary
is signed with cosign and carries SLSA provenance, and two commands
verify both before you run anything.
Add -compare and it also runs the engine over the same account, exiting non-zero where the
two disagree. That is how the engine's
first real false positive
was found, and how it stays fixed. If it disagrees on yours,
report it: no report is more useful. From here, how to evaluate this walks to a
verdict on your own estate in stages that each end in an answer.
Related MCP server: cloud-pathfinder
See the whole engine in 90 seconds
make demoPulls the published, cosign-signed images, feeds them sample Trivy / Semgrep / Custodian /
Falco / Kubernetes / IAM / SSO output, and prints the top attack path with its generated fix.
Dashboard on http://localhost:3000, make down to tear it down. It needs Docker, jq and
curl, compiles nothing, and takes about 23 seconds from an empty image cache; make demo-build
is the same demo built from your working tree.
On Kubernetes, the chart is an official package on Artifact Hub:
helm install perspectivegraph oci://ghcr.io/luiacuaniello/charts/perspectivegraph \
--set secrets.generate=true \
--version 1.39.4 # x-release-please-versionA default install is authenticated, and the chart will not render one that does not say
where its credentials come from: secrets.generate=true generates them and keeps them
across upgrades, and the install notes print how to read the admin token back.
The chart's page has the other choices.
On one machine - a VM with Docker and a DNS name - one command sets up TLS, generated credentials, an authenticated bus and daily backups, and starts it: production on one machine.
make prod-init DOMAIN=perspectivegraph.example.comThe chart and the three images it runs (ghcr.io/luiacuaniello/perspectivegraph, -dashboard
and -postgres) are signed with cosign keyless and carry an SPDX SBOM and SLSA provenance:
verify them rather than taking the supply chain on trust.
The dashboard opens on the decision, not the inventory: what is being exploited now, the fewest changes that remove the most risk, and how far the numbers can be trusted. Routes are ranked by triage priority - what the route reaches, whether runtime confirmed it, how exposed the entry is - so a lower-scoring route can outrank a higher-scoring one.

|
|
Why the route is P1, one probability with its range, and every hop with what it lets the attacker do and where its probability came from. | Whether the engine's own scores held up against recorded outcomes - and whether there are enough of them to say. |
The screenshots are make demo with seeded verdicts: make seed-validation records
synthetic outcomes on part of the routes, the way a BAS run tests part of an estate, which is why
the calibration panel has something to show - and why it still says not enough outcomes yet:
the handful it records is far short of the 30 a verdict needs. The counts in the pictures are
those of the release they were taken on; the sample data has grown since, so yours differ by a
route or two. A fresh install and the public demo report
insufficient data instead, until real outcomes exist. The public demo runs on one free VM, so
treat it as best-effort.
Why?
A scanner reports that a container carries a critical CVE. It cannot report that the container sits behind an internet-facing load balancer, runs with a role that reads the production database, and is therefore the one finding out of ten thousand worth fixing this week. That needs the other tools' output in the same graph, which is what this builds. A developer gets a check that goes red only when their change opens a real route; a security team gets a short ranked list of attack paths instead of a flat list of findings.
Block the pull request that opens the path
No deployment required. The runner reads your estate read-only, ingests this pull request's scan, and answers in-process with the same engine:
- uses: luiacuaniello/perspectivegraph@v1
with:
mode: local
aws-region: eu-west-1 # read-only; give the job an OIDC role with SecurityAudit
report: trivy.jsonThe check goes red when this change opens a route to a sensitive asset - or makes one likelier - not when it adds a critical CVE: a critical on a host nothing routes to does not fail the build, and a medium on a container that now reaches the production database does. Routes that were there before the change do not count, even when they run through what it touches: the scan is applied to a copy of the estate and compared with it, and nothing is written. It also has a third outcome, because a pipeline whose scan never arrived must not get the same green tick as one that is clean:
Verdict | Exit | Meaning |
| 0 | The engine analysed this change: it opens or worsens no critical path |
| 1 | It opens or worsens critical attack paths - the check names them |
| 2 | Nobody analysed it. The scan, the ingest or the SHA is wrong |
A Terraform plan goes through the same gate before anything is deployed: source: terraform
with the output of terraform show -json, judged on its own or against the live estate. A
security group rule, a policy attachment or a bucket policy that opens a route fails the check
in the pull request that writes it - see Terraform plans.
Outside GitHub Actions it is one command, and it installs as a Trivy plugin too:
perspectivegraph gate -local -aws-region eu-west-1 -report trivy.json -slug owner/name -sha "$COMMIT_SHA"
trivy plugin install github.com/luiacuaniello/perspectivegraph
trivy image -f json myapp:pr-42 | trivy perspectivegraph gate -local -aws-region eu-west-1 -report -Fork pull requests get no secrets, so the gate fails closed as unknown on them. Do not
work around it with pull_request_target: that runs your secrets - in local mode, cloud
credentials - against the contributor's code.
On a public repository, a blocked check prints the route (real asset names, the CVE, the
sensitive asset) into a public job log. Use soft-fail and post the detail somewhere private.
The manual covers the rest:
pointing the action at a deployed engine, gating rendered manifests, a pre-collected estate,
rolling the gate out, and every input in action.yml.
Let an agent query it
A language model cannot enumerate thousands of edges reliably or run Dijkstra, and asked for "the attack paths in my account" it will invent plausible ones. So the engine speaks MCP: the agent asks, and reasons over answers it could not have made up.
perspectivegraph mcp --api http://localhost:8080 # or https://demo.a3thinker.it, no credential neededEight tools, every one read-only and declared so on the wire. The one worth the integration
is simulate_fix: it re-runs the simulation with the given edges cut and reports what actually
changes. The server is in the official MCP Registry
and on Glama; the tools and the
client configuration are in the manual.
Project status & maturity
The engine and its public API are complete, documented and tested. The scores are not yet calibrated. Nobody has run this over a real estate, tested the paths it surfaced and fed the verdicts back: the machinery for that loop is built and tested, the loop is not closed. So read a score as what the model believes and how sure it says it is, not as a measured frequency. Use it to find and cut routes; don't put its percentage in front of a board. If you run it over yours, tell us how it went. Positioning spells out what is and isn't claimed.
What is measured today, as of v1.39.4.
make bench-cloudgoat grades the engine in CI on four
CloudGoat-shaped scenarios:
Scenario | Expects | Result |
| a path | found it, invented none |
| a path (leaked-credential origin) | found it, invented none |
| no path (open SG, private subnet) | produced none |
| no path (explicit Deny wins) | produced none |
Precision and recall are 1.00 on all four: four known shapes, two of them negative controls, so a
regression gate rather than a measure of accuracy on your estate. On real AWS,
make reachability-lab-aws checks exposure the same way for free, and make redteam-aws grades
the engine's escalation claims against AWS's own policy evaluator. That grading has already
caught one false positive, a permissions boundary the engine ignored; it is fixed, and
make boundary-lab-aws fails whenever the engine and AWS disagree. make entrypoints-lab-aws
puts bucket policies and function URLs to AWS the same way; its first run caught four errors,
also fixed. make public-access-lab-aws does it, for free, for Block Public Access set on the
whole account, and make terraform-lab-aws applies the Terraform plans the merge gate judged and
asks the internet whether each one opened a way in. Each of these labs writes what it found
into the build, and the dashboard's Accuracy page shows it under Checked against AWS: every
question, AWS's answer, the engine's, and the version it was asked of.
Clouds. AWS is live and verified against a real account; reading several accounts in one pass is exercised on fixtures, not yet against real ones. Azure is fixtures only, and there is no connector for GCP or for OpenStack: the roadmap says what is planned for each.
Interface. The GraphQL schema is frozen and drift-guarded, so a breaking change comes with a major version, never in a patch: API stability.
Deployment. The backend is distroless and non-root on a read-only root filesystem, the images are pinned by digest, and under Helm every workload meets the
restrictedPod Security Standard, asserted in CI. The compose defaults are open on purpose;PG_ENV=productionrefuses to start unless API and ingest are authenticated. A real rollout needs more (TLS, backups,TRUSTED_PROXY_CIDRSbehind a proxy, a database you can fail over): on one machinemake prod-initdoes the first three, and CI restores one of its backups on every change; the operations runbook lists the rest.Support. The newest release only, with a clock on security fixes (Critical 7 days, High 30): SUPPORT.md.
Telemetry. None. Out of the box it opens no outbound connection; GitHub, the AI assistant and the KEV/EPSS feeds each stay off until you configure them.
Scope. The reachable attack-path question, in the developer workflow. It is not a scanner, a CNAPP or a compliance product, and replaces none of them.
How it is written. By a human working with Claude (Anthropic): the design decisions and what ships are the maintainer's, and much of the implementation and its tests came out of that collaboration. Check it rather than trust it:
make test,make bench-cloudgoat,govulncheck ./..., and CONTRIBUTING.
Documentation
Concepts in plain words - route, score, interval, priority, outcome, calibration: the words the dashboard uses
Connect your own infrastructure - your AWS accounts and Kubernetes clusters, from a laptop, one machine, EKS or any cluster
Manual - architecture, scoring, every integration, deployment, and the runbook for your own environment
Evaluation - trying it on your own estate, in stages that each end in an answer
Positioning - what is claimed, what is not, and how to check
License
Apache License 2.0. Licensing is declared for every file, in the form REUSE defines, and checked in CI: REUSE.toml.
Available Tools
8 toolsexplain_attack_pathARead-onlyIdempotent
Give the full kill chain for one route: every hop, the relationship type, that hop's probability, where the probability came from (kev/epss/runtime are observed evidence; cvss/severity/heuristic are estimates), and the MITRE ATT&CK technique. Use this before explaining or acting on a route - the hop provenance is what tells you which parts of the story are evidence and which are assumption.
Inputs: path_id (required). Returns: id, nodes, score, steps, +16 more
get_postureARead-onlyIdempotent
Summarize the environment: how many attack routes are open, how many are runtime-confirmed, how many assets and relationships are mapped, and which sensitive assets an attacker can currently reach. Start here to orient before enumerating anything: it also gives the names the other tools take - the sensitive assets routes_to_target accepts and the applications app arguments accept.
Inputs: no named parameters. Returns: posture, applications, riskSimulation
get_score_trustARead-onlyIdempotent
Report how well the engine's probabilities have matched reality, measured against recorded red-team or BAS outcomes: the verdict (well-calibrated / calibrated-on-average / overconfident / underconfident / insufficient-data; calibrated-on-average means only the average matches, so no individual score may be quoted as a probability), the predicted-versus-observed rates, and what to do about the gap. Call this before quoting any score as a probability. If it reports insufficient-data, the numbers are expert estimates and must be presented as the model's own estimate, not as odds. It also reports discrimination - whether the score, and separately the triage Priority order, put confirmed paths above refuted ones (AUC with a 95% interval). Do not present the ranking as evidence of which path is most dangerous unless priorityDiscrimination reads 'discriminates'; 'insufficient-data' or 'indistinguishable-from-chance' means the order has not been shown to beat a coin, and must be said so.
Inputs: no named parameters. Returns: validation, calibration
list_attack_pathsARead-onlyIdempotent
List the ranked routes from internet exposure to a sensitive asset, highest triage priority first. score is the modelled end-to-end exploit probability and priority (0-100, banded P1/P2/P3) is the triage order that also weighs corroboration and target sensitivity. IMPORTANT: these probabilities are expert estimates, not measurements calibrated against real outcomes - call get_score_trust before presenting any of them as a probability, and prefer the ranking over the absolute values. It returns one page: when nextOffset is not null more routes exist, and passing it as offset returns the next ones. Routes an analyst has suppressed are listed too, marked suppressed.
Inputs: app, limit, offset. Returns: offset, nextOffset, attackPaths
list_fixesARead-onlyIdempotent
Return the remediation plan: the fewest changes that remove the most risk, choke points first, each with the share of critical-path risk it eliminates and how many routes it cuts. This is usually the right answer to 'what should we do' - a hundred routes typically collapse into a handful of changes.
Inputs: app. Returns: remediationPlan
routes_to_targetARead-onlyIdempotent
Enumerate the k best distinct routes that reach a named sensitive asset. Answers 'how many ways in are there, and do they share a choke point' - which single-path views hide. Cutting a hop that every route traverses removes them all; cutting one that appears in a single route removes one. Each route comes with its hops, ready to hand to simulate_fix. It returns the best k and has no further page.
Inputs: target (required), k, from. Returns: kShortestPaths
search_assetsARead-onlyIdempotent
Full-text search across indexed assets and findings by name, CVE id, or keyword. Use it to resolve a name a human mentioned into the node ids the other tools take. It needs OpenSearch on the deployment: where that is off it answers with an error saying so, never with an empty list, and get_posture and list_attack_paths are then where names come from. It returns the best size matches and has no further page: narrow the query instead.
Inputs: query (required), size. Returns: search
simulate_fixARead-onlyIdempotent
Ask what actually happens if specific relationships are cut: re-runs the whole simulation with those edges removed and reports how many routes disappear and how the compromise probability moves. This is the tool to reach for before recommending a change - it is a deterministic counterfactual over the real graph, not an estimate, so it settles 'would this help' instead of arguing about it. It changes nothing: the graph, the environment and every recorded decision stay as they are, so it needs no confirmation and can be repeated freely.
Inputs: cuts (required). Returns: whatIf
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a distinct role: get_posture orients, list_attack_paths enumerates globally, explain_attack_path details one route, routes_to_target enumerates to a named asset, list_fixes gives remediation, search_assets resolves names, get_score_trust reports calibration, and simulate_fix runs counterfactuals. The descriptions explicitly disambiguate the potentially overlapping route tools (global listing vs target-specific k-best vs single-route detail) and when to reach for each.
Seven of eight names follow a clean snake_case verb_noun pattern (get_posture, list_attack_paths, explain_attack_path, list_fixes, search_assets, get_score_trust, simulate_fix). Only routes_to_target breaks the convention with a noun_to_noun form, a minor deviation but still readable.
Eight tools is well-scoped for an attack-path exposure analysis domain, with each tool covering a genuine capability (orientation, enumeration, detail, target analysis, remediation, search, calibration, simulation). No tool feels redundant or padded.
Coverage of the analysis lifecycle is strong: orient, enumerate, explain, remediate, verify, and self-assess score trust. Minor gaps exist—no tool manages the analyst suppression referenced by list_attack_paths, and there is no export/report operation—but core workflows are complete for a read-only analytical surface.
Maintenance
Related MCP Connectors
IaC attack-path auditor: finds internet-to-crown-jewel chains in Terraform/CFN/K8s.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only FalkorDB tools for cross-bank AML investigations: rings, money paths, echo-proof claims.
Cloud cost, inventory and governance on AWS/Azure/GCP. Read-only by default, optional scoped writes
Related MCP Servers
- AlicenseAqualityDmaintenanceA local-first AWS security tool that uses graph theory to discover attack paths (e.g., Internet → Role → DB) and prioritize remediations. It allows agents to perform read-only security audits and generate Terraform fixes without data exfiltration.154Apache 2.0
- AlicenseAqualityDmaintenanceMCP server for auditing infrastructure-as-code attack paths, finding multi-hop chains from public internet to sensitive resources.2MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI to scan AWS accounts, analyze attack paths, and verify security fixes on a read-only graph of cloud resources.5-
- AlicenseBqualityCmaintenanceEnables read-only scanning and graph mapping of a cloud estate, revealing public exposure, connectivity, firewall and NSG rules, identity permissions, and RBAC with cited evidence.16MIT

