Architecture¶
How passmcp-graph turns evidence into answers, for contributors. The user's
view is the manual; the decisions behind this shape are in
adr/.
The flow¶
attestations, reports, ingest .passmcp-graph/graph.json
client configurations ──────────────────▶ (passmcp-reporting's graph format)
│
┌──────────────┬─────────────────┼──────────────┐
▼ ▼ ▼ ▼
analyze query check export
(risks, privilege) (paths) (forbidden paths) (json, graphml,
cypher)
Every command but ingest and import reads the store and writes nothing
back. What analyze derives is recomputed from the graph on every run, so
correcting the evidence corrects the answer.
Packages¶
| Package | Does | Reads | Writes |
|---|---|---|---|
cmd/passmcp-graph |
Hands os.Args, the standard streams and the clock to cli.Run and exits with its status |
— | — |
internal/cli |
Global flags, the command table, output formats, exit statuses, shell completions | the store, policy files | stdout (results), stderr (diagnostics) |
internal/ingest |
Recognises each input and adds its facts to the graph | files and directories the operator names | the graph in memory |
internal/analyze |
Inherited critical findings, over-privileged identities | the graph | — |
internal/query |
Parses and evaluates the query language | the graph | — |
internal/policy |
Parses a policy file and runs each forbidden-path query | the graph | — |
internal/export |
JSON, GraphML and Cypher writers; JSON import | the graph, an export file | stdout |
internal/schema |
Validates a JSON export against the published graph schema | — | — |
internal/netguard |
--offline: replaces the default HTTP transport with one that refuses |
— | — |
internal/fixture |
Builds the evidence the tests and the published fixture use | — | testdata/fixture/graph.json on make fixture-update |
The data model — node and edge kinds, graph.ServerID, Load and Save —
is the graph package of
passmcp-reporting,
Apache-2.0, so other tools can read the same store.
What each input supplies¶
| Input | Supplies |
|---|---|
| passmcp attestation | A server's score, grade and failing checks, and the attestation node (digest, predicate type, ranAt, file) |
passmcp check --output json report |
The server's tools and their annotations, how it admits clients, and the identity passmcp authenticated as, with its scopes |
| Claude Desktop, Cursor, VS Code or Zed configuration | Agents, and the servers each uses; server names, URLs and commands only |
All three name a server by graph.ServerID(transport, endpoint), so the
same server from three inputs is one node
(ADR 0003).
Invariants and where they are tested¶
| Invariant | Test |
|---|---|
| No secret from a configuration reaches the store | TestConfigsBecomeAgentsAndNoSecretIsStored (internal/ingest) |
No command makes a network request, with or without --offline |
TestNoCommandContactsTheNetwork (internal/cli) |
Only internal/netguard imports net or net/http |
TestOnlyTheOfflineGuardImportsTheNetwork (internal/cli) |
| Ingesting the same evidence twice changes nothing | TestAttestationsBecomeServersAndIngestingTwiceChangesNothing (internal/ingest) |
| A JSON export validates and re-imports without loss | TestExportsValidateAndReimportWithoutLoss (internal/export) |
| The published fixture answers every published query | TestQueriesOverThePublishedFixtureReturnExactlyTheExpectedPaths (internal/query) |
Output and exit statuses¶
Results go to stdout in the selected format (text or json, or an
export format); diagnostics go to stderr. The exit status is 0 on success,
1 when check finds a forbidden path, and 2 on any error.