Secrets Tools

Secrets Tools Skill

Secrets scanning and redaction for publish gates. High-risk surface with strict output contract.

Invocation

Always invoke via the shim:

bash .claude/scripts/demoswarm.sh secrets <command> [options]

Do not set PATH or call helpers directly. The shim handles resolution.

CRITICAL: Never Print Secret Content

This skill has a strict output contract:

1. NEVER print matched secret values to stdout, stderr, or any file
2. NEVER store raw secret values in JSON or any artifact
3. Only output: file path, line number, secret type, redacted snippet (first/last 4 chars)
4. Redacted format: <prefix>…<suffix> (e.g., ghp_…abcd)

Violations of this contract are security incidents.

Operating Invariants

Repo root only

• Assume working directory is repo root.
• All paths are repo-root-relative.

Scan scope

• Only scan the publish surface (current flow directory + staged files)
• Never scan the entire repository

No git / no GitHub

This skill does not run git or gh. File lists are passed as arguments.

Allowed Users

Primary:

• secrets-sanitizer (the publish gate agent)

Secondary (read-only scan):

• repo-operator (for hygiene checks)

Not allowed:

• Cleanup agents (they read receipts, not scan for secrets)
• Author agents
• Critic agents

Command Reference

Quick Examples

Scan for secrets

# Scan a file or directory
bash .claude/scripts/demoswarm.sh secrets scan \
  --path ".runs/feat-auth/signal" \
  --output ".runs/feat-auth/signal/secrets_scan.json"
# stdout: CLEAN | SECRETS_FOUND | SCAN_PATH_MISSING
# JSON findings written to --output file

Output JSON format:

{
  "status": "SECRETS_FOUND",
  "findings": [
    {
      "file": ".runs/feat-auth/signal/github_research.md",
      "type": "github-token",
      "lines": "42,87"
    }
  ]
}

Scan a single file

bash .claude/scripts/demoswarm.sh secrets scan \
  --path ".runs/feat-auth/signal/github_research.md" \
  --output ".runs/feat-auth/signal/secrets_scan.json"
# stdout: CLEAN (if no secrets found)

Redact a specific type

# Redact GitHub tokens in a file
bash .claude/scripts/demoswarm.sh secrets redact \
  --file ".runs/feat-auth/signal/github_research.md" \
  --type "github-token"
# stdout: ok | FILE_NOT_FOUND | null
# File is modified in-place

Secret Types

Contract Rules

1. stdout scan: Status string (CLEAN | SECRETS_FOUND | SCAN_PATH_MISSING)
2. stdout redact: Status string (ok | FILE_NOT_FOUND | null)
3. JSON output: Written to --output file path, not stdout
4. exit code: 0 always (errors expressed in output, not exit code)
5. No secrets in output: Any output containing secret values is a bug

Error Handling

Missing scan path

# stdout: SCAN_PATH_MISSING

{
  "status": "SCAN_PATH_MISSING",
  "findings": []
}

File not found (redact)

# stdout: FILE_NOT_FOUND

Read error (redact)

# stdout: null

For Agent Authors

In secrets-sanitizer:

1. Use secrets-tools — bash .claude/scripts/demoswarm.sh secrets ...
2. Never grep for secrets manually — the patterns are standardized here
3. Check stdout status — CLEAN, SECRETS_FOUND, or SCAN_PATH_MISSING
4. Read JSON from file — findings are in the --output file, not stdout
5. Redact in-place — use secrets redact for allowlist artifacts

Example pattern:

# Scan the publish surface
SCAN_OUTPUT=".runs/${RUN_ID}/${FLOW}/secrets_scan.json"
STATUS=$(bash .claude/scripts/demoswarm.sh secrets scan \
  --path ".runs/${RUN_ID}/${FLOW}" \
  --output "$SCAN_OUTPUT")

if [[ "$STATUS" == "SECRETS_FOUND" ]]; then
  # Read findings from JSON file
  FINDINGS=$(cat "$SCAN_OUTPUT" | jq -r '.findings[] | "\(.file) \(.type)"')

  # Redact each finding type
  bash .claude/scripts/demoswarm.sh secrets redact \
    --file ".runs/${RUN_ID}/${FLOW}/github_research.md" \
    --type "github-token"
fi

Installation

The Rust implementation is preferred:

cargo install --path tools/demoswarm-runs-tools --root .demoswarm

The shim will automatically use the installed binary.