perspectivegraph

# <img src="docs/logo.svg" alt="PerspectiveGraph logo" width="32" height="32"> PerspectiveGraph

[![CI](https://github.com/luiacuaniello/perspectivegraph/actions/workflows/ci.yml/badge.svg)](https://github.com/luiacuaniello/perspectivegraph/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/luiacuaniello/perspectivegraph?sort=semver)](https://github.com/luiacuaniello/perspectivegraph/releases)
[![Go](https://img.shields.io/github/go-mod/go-version/luiacuaniello/perspectivegraph?filename=backend%2Fgo.mod)](backend/go.mod)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13828/badge)](https://www.bestpractices.dev/projects/13828)
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/perspectivegraph)](https://artifacthub.io/packages/helm/perspectivegraph/perspectivegraph)

> **Catch the attack path in the pull request that opens it - then ship the fix as a PR.**

On every pull request, PerspectiveGraph (open source, Apache 2.0) answers one question against a
graph of your *real* environment - built from the scanners you already run (Trivy, Semgrep, Cloud
Custodian, Falco):

> *Does this change open a path from the internet, through excessive privilege, to something valuable?*

When it does, the **PR check goes red** - a required status you can block the merge on - and you get
the **fix as its own one-click pull request**. The reachable attack path is caught and closed in code
review, where it's cheapest, not months later in production. This is **shift-left attack-path
analysis**: not a scanner bolted onto CI, not a runtime CNAPP you log into after the fact - the
reachability question, answered *in the developer's workflow*.

That gate is powered by a full attack-path correlation engine, so the same graph also gives you the
rest: a queryable dashboard of your **~5 critical attack paths** (not 10,000 flat findings), triage,
runtime confirmation, an AI summary, and always-current architecture maps. **But the wedge is the
pull request.**


![PerspectiveGraph: from the day's exploitable routes to a generated fix](docs/demo.gif)

*Twenty 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.*

> ### What this has not done yet
>
> The engine reports probabilities, credible intervals and its own calibration - Brier
> score, ECE, a reliability diagram. **None of that has been calibrated against field
> data.** Nobody has yet run it over a real estate, tested the paths it surfaced, and fed
> the verdicts back. The machinery for that closed loop is built and tested; the loop has
> not been closed with real outcomes.
>
> So read a score as *"what this model believes, and how sure it says it is"*, not as a
> measured frequency. A path at 0.7 has not been shown to be exploited seven times in ten -
> it has been shown to be what the model concludes from the evidence it was given, and
> the interval beside it says how thin that evidence is.
>
> That is a statement about maturity, not about intent: the calibration harness exists
> precisely so that number can be earned rather than asserted, and the
> [CloudGoat benchmark](backend/testdata/cloudgoat/README.md) grades the path-finding itself on public,
> reproducible scenarios today. If you run this on a real environment and record what you
> find, [that is the contribution that matters most](CONTRIBUTING.md).

## 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:

```bash
# 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-1
```

It is **read-only and free**: every check is one `iam:SimulatePrincipalPolicy` call, a
dry run that evaluates policy without performing anything, so it creates nothing and
costs nothing. It needs `iam:SimulatePrincipalPolicy` and `iam:ListRoles` - both inside
`SecurityAudit`. Binaries for linux/macOS (amd64, arm64) and Windows are on the
[releases page](https://github.com/luiacuaniello/perspectivegraph/releases/latest),
signed with cosign and carrying SLSA build provenance. The signature covers `SHA256SUMS`,
so one check covers every archive:

```bash
cosign verify-blob --bundle SHA256SUMS.bundle \
  --certificate-identity-regexp 'https://github.com/luiacuaniello/perspectivegraph/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS && sha256sum -c SHA256SUMS --ignore-missing
```

Add `-compare` and it also runs the engine over the same account and **exits non-zero
where the two disagree** - each disagreement is a false positive or a miss, in the
engine or in your assumptions. That check is how the permission-boundary bug described
in the [manual](docs/MANUAL.md) was found, and how it stays closed.

That command is also stage 0 of a fuller trial: [how to evaluate this](docs/EVALUATION.md)
walks from here to a verdict in stages that each end in an answer - and says what the
trial will *not* tell you before you spend a fortnight finding out.

## See the whole engine in 90 seconds

```bash
make demo
```

Pulls the **published, cosign-signed images**, feeds them sample Trivy / Semgrep /
Custodian / Falco / Kubernetes / IAM / SSO output, waits for the analyzer, and prints the
top attack path with its generated fix. Dashboard on **http://localhost:3000**. Needs
Docker, `jq` and `curl` - no Go or Node toolchain, and nothing is compiled: measured at
**23 seconds** from an empty image cache. Tear down with `make down`.

Building it yourself instead is `make demo-build`, which is the same demo from your
working tree. The images the fast path runs are the release artefacts, so you can check
what you are about to run before you run it - the `cosign verify` command is at the top of
[`docker-compose.demo.yml`](docker-compose.demo.yml).

Prefer not to build? The release images are published to GHCR (`latest` also tracks the
newest release; the pinned tag is the one to use if you care about reproducibility):

```bash
docker pull ghcr.io/luiacuaniello/perspectivegraph:v1.13.3 # x-release-please-version
docker pull ghcr.io/luiacuaniello/perspectivegraph-dashboard:v1.13.3 # x-release-please-version
docker pull ghcr.io/luiacuaniello/perspectivegraph-postgres:v1.13.3 # x-release-please-version
```

On Kubernetes, the Helm chart is published the same way - no clone needed, and a version
you can pin and verify. It is listed on
[Artifact Hub](https://artifacthub.io/packages/helm/perspectivegraph/perspectivegraph) as an
**official** package from a verified publisher, which is Artifact Hub's way of saying the
chart is published by the people who wrote the software rather than by a third party
repackaging it:

```bash
helm install perspectivegraph oci://ghcr.io/luiacuaniello/charts/perspectivegraph \
  --version 1.13.3 # x-release-please-version
```

They are signed with cosign keyless and carry an SPDX SBOM plus a SLSA build
provenance attestation - verify before you run, rather than taking the supply chain
on trust:

```bash
cosign verify \
  --certificate-identity-regexp 'https://github.com/luiacuaniello/perspectivegraph/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/luiacuaniello/perspectivegraph:v1.13.3 # x-release-please-version
```

The dashboard opens on the decision, not the inventory: what is being exploited right
now, the fewest changes that remove the most risk, and how much the numbers can be
trusted.

![The day's decision surface](docs/screenshot-overview.png)

Routes are ranked by a composite triage priority - what the route reaches, whether
runtime confirmed it, how exposed the entry is - not by raw exploit score, so a
lower-scoring route can and does outrank a higher-scoring one.

| | |
|---|---|
| ![Attack path detail](docs/screenshot-paths.png) | ![Score calibration](docs/screenshot-trust.png) |
| Every hop, its probability, where that probability came from, and the ATT&CK technique. | Whether the engine's own scores held up against recorded outcomes. |

*Every screenshot on this page is `make demo`: sample scanner output and **seeded**
verdicts, not a real environment. That is why the calibration panel returns a verdict of
"underconfident" - across 14 seeded outcomes the engine predicted 60% where 71% held up.
Those outcomes were generated to exercise the instrument, not to flatter it. On a fresh
install the same page reads **"insufficient data"** and withholds a verdict until real
outcomes exist, because a risk score you cannot check is worth less than an honest blank.*

## Why?

Modern security teams don't suffer from a lack of tools - they suffer from **noise, fragmentation,
and missing context**.

| Role | Pain today | What PerspectiveGraph gives them |
| --- | --- | --- |
| **Developer** | CI/CD blocked by thousands of irrelevant CVEs | A PR check that goes red *only* when the change opens a real internet→sensitive-asset path - plus the fix as a one-click PR |
| **Security** | Triage on flat lists of 10,000 findings | A ranked list of ~5 critical **attack paths**, queryable like a database |
| **Architect** | No live view of how IaC becomes attack surface | Auto-generated, always-current architecture & data-flow maps + drift detection |


## Block the pull request that opens the path

**No deployment required.** The runner reads your estate read-only, ingests this pull
request's scan,