Security
Understand stored data, credential isolation, and operational safeguards.
GrantTrace keeps contracts identity-free and isolates GitHub App broker credentials during live proof. It does not sandbox test code, protect a compromised machine, or prove whole-application least privilege.
Trust boundary
recordruns trusted project code and inherits its ordinary environment. Its injected preload observes supported global-fetchtraffic only to exactlyhttps://api.github.com. Off-origin responses cannot contribute automatic runtime-header evidence. The recorder is not a network sandbox or a claim that every client was observed.provegives the child a restricted installation token through an allowlisted environment and injects only GrantTrace's recorder preload. This is credential isolation, not an OS sandbox.- Local observations, contracts, reports, runtime headers, and token responses are untrusted input and receive strict validation.
Stored data
| Artifact | Commit? | Contents |
|---|---|---|
granttrace.lock.json | Yes | Canonical routes, evidence, scenarios, permissions, and manual keeps |
.granttrace/observations/*.ndjson | No | Safe per-scenario observations |
.granttrace/reports/*.json | No | Identity-free ephemeral proof results |
GrantTrace never intentionally stores raw URLs, request or response bodies, headers, errors, commands, tokens, private keys, owners, repositories, or resource identifiers in those artifacts.
Proof reports include a source commit only when Git reports a clean index and
worktree. Modified, staged, untracked, unavailable, or non-Git source is
represented by sourceCommit: null; a report does not attribute dirty source
to HEAD.
Credential providers
Live proof accepts exactly one private-key provider:
- a protected multiline environment secret;
- an owned regular
0600file inside an owned0700directory; or - macOS Keychain.
Credentials never enter CLI arguments. The proof child receives only its restricted installation token, not the App private key, JWT, App ID, or installation ID.
Operational rules
- Never prove against a production App, installation, or repository.
- Never run live proof on untrusted pull requests.
- Never upload
.granttrace/as a CI artifact. - Inspect the fixture for residue after any cleanup failure.
- Treat the test process as trusted code capable of printing its own environment and token.
Read the full threat model and limitations for exact controls and residual risks.