Skip to content

credforge

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.

What it reports

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

Install

go install github.com/plexusone/credforge/cmd/credforge@latest

Use

Beside 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.json
listed 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.

Connectors

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

In Go

The comparison is a pure function, and the command tree mounts in a host tool that builds its registry in Go:

cmd := cli.New(cli.Options{
    Use:      "observe",
    Registry: buildRegistry,                       // func() (*credspec.Registry, error)
    Targets:  func() (*targets.File, error) { return myTargets, nil },
})
rep := credforge.Compare(reg, log, scopes, observations, references, credforge.Options{
    Grace: credforge.DefaultGrace,
})
events, err := credforge.Record(reg, log, rep, credforge.DefaultGrace)

Documentation

License

MIT