Check a credential registry against the places it describes, without reading a single value.
A registry such as systemspec-credential says which credentials should exist, where each is stored, who uses it and how it rotates. credforge observes the stores and consumers themselves (a repository's Actions secrets and the secrets its workflows read, a parameter store's names) and reports where they disagree with the registry and its event log: the secret a workflow needs that was never set, the token regenerated at the issuer but never updated in one repository, the value changed with nothing recorded.
Status: v0.1.0 checks and records; it never writes a value. Installing and rotating values through OmniVault providers follows. See the roadmap.
| State | Meaning |
|---|---|
missing |
A listed store does not hold the credential |
stale |
A store was set before the credential's current value was made |
unregistered |
A workflow reads a secret the registry stores nowhere it can be read |
changed |
A store was set after the log's latest event, with nothing recorded |
unrecorded |
A store holds a credential the log has no event for |
unlisted |
A store holds a name no credential in use names |
unobserved |
No binding reaches the store |
present |
As recorded |
go install github.com/plexusone/credforge/cmd/credforge@latestBeside the registry and its event log, write a targets file that says how each store is reached. It holds no secrets:
{
"formatVersion": "1",
"bindings": [
{ "store": "github-actions", "account": "example-org/*", "github": {} },
{ "store": "aws-ssm", "account": "hosting", "aws": { "profile": "hosting", "region": "us-west-2" } }
],
"scan": { "githubRepositories": ["example-org/web", "example-org/api"] }
}Then check:
export GITHUB_TOKEN=$(gh auth token)
credforge check --registry credentials.json --events events.json --targets targets.jsonlisted 3 scope(s): 0 missing, 1 stale, 1 unregistered, 0 changed, 1 unrecorded, 1 unlisted, 1 unobserved, 0 present
stale app/ci/deploy github-actions:example-org/web:DEPLOY_TOKEN set 2026-03-01, before the current value was made on 2026-03-11
unregistered - github-actions:example-org/api:DEPLOY_TOKEN a consumer reads this name, and no credential stores it here (.github/workflows/ci.yaml)
unrecorded app/prod/DB aws-ssm:hosting:/app/prod/DB set 2026-03-01; the log has no event for it
unlisted - aws-ssm:hosting:/app/prod/OLD no credential stores this name
| Flag | What it does |
|---|---|
--record |
Logs unrecorded stores as created and changed ones as deployed |
--fail-on |
States that make the exit status 1; default missing,stale,unregistered |
--include-planned |
Also compares planned credentials |
--only |
Compares only credentials whose ID matches a pattern, such as 'app/prod/*' |
--grace |
How far a store's change and the log's event may differ; default 24h |
--format |
text or json |
--all |
Lists present and unobserved stores, not only their counts |
The exit status is 0 when nothing is in a --fail-on state, 1 when
something is, and 2 on an error.
| Store | What is listed | Never called |
|---|---|---|
GitHub Actions secrets (github-actions) |
Repository secret names and when each was set; workflow files' secrets.NAME |
Secret values cannot be read through GitHub's API |
AWS Systems Manager Parameter Store (aws-ssm) |
Parameter names and last change, one directory level at a time | GetParameter, GetParameters |
The comparison is a pure function, and the commands mount in a host tool
that builds its registry in Go: cli.New as a command tree of its own, or
cli.Check as one command beside the host's, such as systemspec-credential's:
cmd := cli.New(cli.Options{
Use: "observe",
Registry: buildRegistry, // func() (*credspec.Registry, error)
Targets: func() (*targets.File, error) { return myTargets, nil },
})
credentials.AddCommand(cli.Check(cli.Options{Registry: buildRegistry, Targets: buildTargets}))rep := credforge.Compare(reg, log, scopes, observations, references, credforge.Options{
Grace: credforge.DefaultGrace,
})
events, err := credforge.Record(reg, log, rep, credforge.DefaultGrace)