How it is put together¶
| Component | Job |
|---|---|
| Frontend | A single page served by the application; renders every value as text through the document interface with no markup sink, holds the session token in memory rather than browser storage, and runs under a content policy that forbids inline script and style (D-036). The look is tokens and a sidebar shell (D-075); the detail opens beside the list, every list has a skeleton and an empty state, and a real browser proves the page by use (D-077) |
| Routes | The trust boundary; authentication checked on every request, every response shaped by a declared model |
| Import parsing | Parses an imported identity export file, bounded on every axis, in memory, append-only |
| Derivation engine | Computes each identity's state and enrichment from the observation history at read time |
| Governance records | The human layer: owners, flags, attestations, written with attribution and an audit row in one transaction |
| Report builder | Produces the self-contained risk report and the escaped CSV and JSON exports |
| Audit trail | Records every governance action, written with the action in one transaction |
| PostgreSQL | Holds observations, governance records, and the audit trail; access controlled, with encryption at rest supplied by the deployment layer (D-020) |
| The tool's own cloud credential, not yet present | Version one holds none. The live pull phases add a read-only role in the target AWS account, and from that day it is the identity that must be governed best |
flowchart LR
O[Operator browser] -- session token --> R[Routes]
R --> I[Import parsing]
I -- observations, append only --> P[(PostgreSQL)]
R --> D[Derivation engine]
P -- history --> D
D -- derived inventory --> R
R --> G[Governance records]
G -- action plus audit, one transaction --> P
R --> X[Report builder]
D --> X
An import records observations and touches nothing else. A view derives the inventory from the history and stores nothing. A governance action is the only ordinary write besides ingestion, and it commits with its audit row as one unit. The report builder consumes the same derived inventory the view does, so a report can never disagree with the screen.
The data model shape¶
The tables, the diagram of their relations, and the reasons for their shape are in ARCHITECTURE.md.
The route surface¶
The complete surface, stated so it can be counted. A test asserts this block against the application's actual route table, so this list and the API cannot silently disagree; the health routes and the page shell are public, and every other route answers to the role matrix.
GET /
GET /health
GET /health/database
POST /auth/login
GET /auth/me
POST /auth/logout
POST /auth/step-up
GET /admin/users
POST /admin/users
POST /admin/users/{username}/sessions/revoke
POST /admin/users/{username}/bindings
POST /admin/users/{username}/bindings/{binding_id}/revoke
GET /admin/scopes
POST /admin/scopes
GET /admin/tokens
POST /admin/tokens
POST /admin/tokens/{token_id}/revoke
GET /admin/settings
PUT /admin/settings
POST /imports/credential-report
POST /imports/authorization-details
POST /imports/github-organization
POST /imports/kubernetes-rbac
POST /imports/google-cloud
POST /imports/azure-tenant
POST /imports/okta-org
POST /imports/active-directory
POST /imports/sharphound
POST /imports/observed/dry-run
POST /imports/observed
GET /imports
GET /identities
GET /identities/{identity_id}
GET /groups
POST /identities/{identity_id}/governance
POST /groups/{group_id}/governance
POST /identities/{identity_id}/attest
POST /groups/{group_id}/attest
DELETE /governance/{record_id}
GET /identities/{identity_id}/authorizations
POST /identities/{identity_id}/authorizations
POST /authorizations/{authorization_id}/revoke
GET /relationships
POST /relationships/authorize
POST /relationships/{authorization_id}/revoke
GET /role-definitions
POST /role-definitions/authorize
POST /role-definitions/{authorization_id}/revoke
GET /alerts
GET /delta
GET /identities/{identity_id}/delta
GET /identities/{identity_id}/observed-grants
GET /export/observed-grants.csv
GET /mappings
POST /mappings
POST /authorizations/import/dry-run
POST /authorizations/import
POST /campaigns
GET /campaigns
GET /campaigns/rollup
GET /campaigns/{campaign_id}
POST /campaigns/{campaign_id}/items/{item_id}/disposition
POST /campaigns/{campaign_id}/close
GET /export.csv
GET /export.json
GET /report.html
GET /campaigns/{campaign_id}/evidence
GET /campaigns/{campaign_id}/evidence.csv
GET /api/v1/identities
GET /api/v1/delta
GET /api/v1/changes
GET /identities is paged, because the sample estates' seventy-seven
rows say nothing about an account with thousands: it takes q (a
name substring), type, and tier as filters, applied on the server
rather than in the browser, plus sort and direction over a named
set of columns, applied to the whole matched set before the page is
cut, plus limit (default 100, at most 500)
and offset. The response carries the page of rows, the count the
filters matched, and account-wide dashboard tiles that no filter
changes, so the payload is bounded at any inventory size while state
stays derived at read (D-006).
Repository map¶
The package is split by part, and each part owns its own tables, its own routes, and nothing else: core holds who may act and where, observe holds what was seen, authorize holds what people allowed, decide holds the reviews and the alerts.
| Path | Role |
|---|---|
manifest_identity/main.py |
Application assembly: routes, security headers, the static shell |
manifest_identity/models.py |
One import surface over every part's tables |
manifest_identity/core/roles.py |
The role matrix, single source: who may call what |
manifest_identity/core/scope.py |
The scope tree and the one authority question, asked nowhere else |
manifest_identity/core/deps.py |
Authentication, the matrix check, the scope check, and the write budget |
manifest_identity/core/models.py |
Users, sessions, scope nodes, role bindings, settings, the audit chain |
manifest_identity/core/audit.py |
The audit spine: the record commits with the action |
manifest_identity/core/spreadsheet.py |
The formula-injection gate every CSV export passes through, in every part |
manifest_identity/core/verify_chain.py |
The offline verifier: recompute the chain, compare to an anchor |
manifest_identity/observe/providers/ |
The nine parsers, AWS, GitHub, Kubernetes, Google Cloud, Azure, Okta, and Active Directory through its cmdlets and through SharpHound: bounded, in memory, distrusting their own preconditions. The type and size checks they share, and their one rejection error, live once in parsing.py |
manifest_identity/observe/importer.py |
AWS records become neutral rows; the vocabulary ends here |
manifest_identity/observe/estate.py |
What every native importer does the same way, written once: the root node, the identities at it, one observation per import |
manifest_identity/observe/github_importer.py |
GitHub records become the same neutral rows: teams as groups, permission levels as capability documents |
manifest_identity/observe/kubernetes_importer.py |
A cluster's dump becomes the same rows: rules read as capabilities, bindings as grants at the namespace or the cluster |
manifest_identity/observe/google_cloud_importer.py |
A project export becomes the same rows: user-managed keys as credentials, every member form a policy writes, roles read from permissions, a table, or a name |
manifest_identity/observe/azure_importer.py |
A tenant export becomes the same rows: members with passwords and guests without, secrets and certificates as credentials, directory roles held or eligible, assignments at the subscription or resource group |
manifest_identity/observe/okta_importer.py |
An organization export becomes the same rows: passwords only where Okta holds them, roles reaching members through their groups, every application assignment a grant |
manifest_identity/observe/active_directory_importer.py |
A domain, from either door, becomes the same rows: the built-in groups as definitions reaching members through every nesting, a control right as access to obtain, a trust as a relationship |
manifest_identity/observe/models.py |
Imports, identities, credentials, grants, role definitions, relationships |
manifest_identity/observe/derive.py |
State from history at read time; the freshest value per field |
manifest_identity/observe/principals.py |
Who a trust policy names, one principal per row, allow statements only |
manifest_identity/observe/paths.py |
How access reaches an identity: direct, through a group, by assuming a role |
manifest_identity/observe/findings.py |
Credential findings, each explaining itself with its OWASP anchor |
manifest_identity/observe/policy_analysis.py |
What a policy document grants, read by capability, and what one version has that another did not |
manifest_identity/observe/privilege.py |
The privilege picture with source attribution; shadow admin detection |
manifest_identity/observe/assessment.py |
The one computation the page, the campaigns, and the exports all read |
manifest_identity/authorize/authorizations.py |
The authorization write path: attributed, append-only, bounded |
manifest_identity/authorize/lifecycle.py |
The rules the three authorized records share: the authorizer from the session, revocation as a closing row, expiry from the clock |
manifest_identity/authorize/from_observed.py |
The observed side in the authorized side's shape, prefill and export |
manifest_identity/authorize/relationships.py |
Authorizing the door: the trust itself, appended and superseded |
manifest_identity/authorize/role_definitions.py |
Authorizing a custom definition as written, bound to the hash that was agreed |
manifest_identity/compare/delta.py |
The difference between the two records, nine classes, stored nowhere |
manifest_identity/authorize/csv_import.py |
The file door: rows become the same request the form builds |
manifest_identity/observe/mapping.py |
The bounded table reader and the mapping every door shares |
manifest_identity/observe/generic_import.py |
The observed side's file door: any provider's table becomes the neutral rows |
manifest_identity/api/deps.py |
Authenticating an integration token, a second credential with its own door and budget |
manifest_identity/api/routes_read.py |
The read-only surface: identities, the delta, and the change feed from a cursor |
manifest_identity/authorize/governance.py |
The human layer: typed owners, purposes, flags, attestations |
manifest_identity/core/options.py |
Administrator settings, secure by default, audited on every change |
manifest_identity/decide/campaigns.py |
Recommendations with reasons, and the delta since last certification |
manifest_identity/decide/alerts.py |
The alert record, the delivery interface, and the one deliverer that records rather than sends |
manifest_identity/decide/reports.py |
The ranked report and the escaped exports |
manifest_identity/sample_data.py |
The deterministic sample account generator |
frontend/ |
One page, no build step; every value rendered as text |
migrations/ |
The schema from the first table |
sample-data/ |
The generated demo estates and one sample table per provider, committed and checked |
recipes/ |
Each provider's own export turned into the table door's file; the jq ones run in the suite |
tests/ |
The attack checklist; the matrix walked row by row |
scripts/ |
The gates: docs-truth, digest parity, the mutation check |
diagrams/ |
Working sketches under the drawing doctrine |
DEPENDENCIES.md |
Every runtime package with its canonical source, its role, and what brought it in, checked against the tree |
requirements*.in / *.txt |
Chosen packages, and the hash-pinned trees that install |
Dockerfile / docker-compose.yml |
Digest-pinned base, non-root user, the composed stack |
.github/workflows/ |
The pipeline: tests, types, scanners, the container jobs, and the software bill of materials each run delivers |
.pre-commit-config.yaml |
Secret scan, writing rules, lint, types, the page lint, and the truth gates at commit time |
badges/ |
The score badge the README shows, written by the doctrine's scorer and compared against a fresh one in the pipeline |
scripts/audit.sh |
Every pinned tree audited against known vulnerabilities, with no exceptions |
eslint.config.mjs / package.json |
The page's one lint rule and its pinned tools |
.env.example |
Documents required configuration without containing it |