Concepts

Clef Pro is a reporting and alerting layer for secrets governance. It never sees your encrypted files, key names, or recipient identities. The Clef CLI evaluates everything locally in your CI pipeline and sends only opaque summaries to the dashboard.

Integrations

An integration is a connection point between your CI pipeline and Clef Pro. You name it — it could map to a repo, a team, a service, or anything you choose. There's no coupling to a specific VCS provider.

Each integration has:

• One or more API keys for authenticating CI report submissions
• A collection config that controls what optional metadata the CLI sends
• Policy rules that define what triggers alerts
• Notification channels that define where alerts are sent

Reports

A report is a point-in-time snapshot of your secrets governance state, submitted by the CLI during a CI run. Each report is keyed by commit hash — one report per commit, always.

A report contains:

• Summary — files scanned, namespaces, environments, per-cell health status with human-readable descriptions
• Drift — per-namespace comparison across environments
• Policy results — pass/fail per policy rule with severity and message
• CI context (optional) — provider, pipeline URL, trigger type

What a report does NOT contain

No file paths, key names, recipient fingerprints, key types, rotation timestamps, or encryption scheme details. The CLI composes human-readable descriptions locally (e.g. "4 keys, 3 recipients, rotated 12d ago") but the raw metadata never leaves your CI environment.

The Matrix

The secret file matrix is a namespace × environment grid. Each cell shows the health status of that namespace/environment pair as reported by the CLI. The matrix is always derived from the latest report — it's not a separate data store.

Navigating through report history updates the matrix to show the state at that point in time.

Drift

Drift means a namespace has different encryption state across environments. The CLI computes this locally by comparing namespaces across environments and sends a summary:

{
  "namespace": "database",
  "isDrifted": true,
  "severity": "warning",
  "summary": "Development has an additional recipient"
}

The dashboard shows drift indicators per namespace row in the matrix. Drift is a fact reported by the CLI — Clef Pro does not recompute or validate it.

Policies

Policies are rules configured on each integration that the CLI evaluates locally. Examples:

• Missing encryption keys — a secret file references keys that aren't present
• Key rotation max age — keys haven't been rotated within N days
• Minimum recipients — a secret file has fewer than N encryption recipients

The CLI checks each rule against the actual secrets state and sends pass/fail results:

{
  "ruleId": "rotation_max_age",
  "ruleName": "Key rotation max age",
  "passed": false,
  "severity": "warning",
  "message": "Rotation overdue for api-keys/production (94 days)",
  "scope": "api-keys/production"
}

Policy results drive alerts.

Alerts

An alert is created when a policy result fails. Alerts have a clear lifecycle:

Status: Open vs Resolved

• Open — the violation exists in the code. The alert is opened when first detected and records which commit introduced it.
• Resolved — a subsequent report shows the rule+scope passing. The alert records which commit fixed it.

The open/closed status is a fact about the code, not a human action. The only way to close an alert is to fix the issue and push a clean report.

Acknowledged

Acknowledging an alert means "I've seen this, stop notifying me." It has exactly one effect: it stops notifications. It does NOT:

• Close the alert (it's still open)
• Hide it from the dashboard (it's still visible)
• Prevent it from counting as a violation
• Affect the open/resolved status in any way

Notification behavior

Alert state	Notification?
New alert opened	Yes — sends to configured channels
Recurring (still failing, unacknowledged)	Yes — notifies again each report
Recurring (still failing, acknowledged)	No — user said stop
Resolved	Future (plumbing exists, not active for MVP)

Alert lifecycle example

Commit abc → missing_keys fails for oauth/production
  → Alert created (open, unacknowledged)
  → Email sent to security@acme.com

Commit def → same violation still present
  → Alert unchanged (still open, unacknowledged)
  → Email sent again

User acknowledges the alert
  → Alert updated (still open, now acknowledged)
  → No more emails

Commit ghi → same violation still present
  → Alert unchanged (open, acknowledged)
  → No notification

Commit jkl → missing_keys passes for oauth/production
  → Alert resolved (resolvedByCommit: jkl)

Commit mno → missing_keys fails again for oauth/production
  → New alert created (fresh lifecycle)
  → Email sent

Notification channels

Each integration can have multiple notification channels:

{
  "notifications": [
    { "channel": "email", "target": "security@acme.com", "minSeverity": "critical" },
    { "channel": "email", "target": "dev-lead@acme.com", "minSeverity": "warning" }
  ]
}

Each channel has a minimum severity filter — a channel configured for critical won't receive warning alerts. For MVP, only email is supported. The architecture supports adding Slack, PagerDuty, webhooks, and other backends.

Backfill

When the CLI runs after a gap (multiple commits since the last report), it backfills all intermediate commits in a single batch request. This ensures complete history — every commit has a report.

The batch is transactional: all reports succeed or none do. Alerts and health updates are derived from the latest commit in the batch (HEAD). Retries are safe — reports are keyed by commit hash, so resubmitting the same batch overwrites identically.

Security model

Clef Pro is designed for security-conscious organizations. The backend is a display and alerting layer — it knows that something is wrong, not what the specifics are.

Stored	Not stored
Commit hash	File paths
Branch name	Key names
Cell health status + description	Recipient fingerprints
Drift summary per namespace	Key types or SOPS versions
Policy pass/fail + message	Rotation timestamps
CI provider + pipeline URL (optional)	Environment variables
	Repo URL or org name

An attacker who compromises Clef Pro learns that "oauth/production has a missing key as of commit abc123." They don't learn what key, what file, or how to exploit it.