docs(security): Rejustify internal reusable workflow SHA-pin exemption as risk acceptance

Merged
YU
1d ago
+214-83

Summary

Replaces the factually incorrect rationale for the internal reusable workflow SHA-pin exemption ("Dependabot cannot propose updates") with a threat-model-accurate one, and fixes documentation contradictions around it.

  • What changed?
    • docs/security/workflow-hardening.md: the exemption note is now an Internal Reusable Workflows subsection separating the two cases. Local ./ references are structurally immutable (resolved at the caller's commit); cross-repo @main references are a deliberate risk acceptance, not a security equivalent of SHA pinning. High-privilege consumers may pin a full-length SHA.
    • README.md: the reusable-workflow note now states the risk-acceptance rationale; consumer examples use @main (they previously showed @<pin-sha> while the note allowed @main); the "Always pin" rollout note is aligned with the policy.
    • docs/security/dependency-security.md: the consumer caller example uses @main with a link to the exemption policy.
    • AGENTS.md: regenerated for the current repo state; SHA-pinning, consumer-exception, and anti-pattern entries aligned with the rejustified exemption.
    • profile/README.md: new organization profile; MD026 exception scoped to the H1 because "Inc." is an abbreviation, not trailing punctuation.
  • Why is this needed? Dependabot can update SHA-pinned action references (including untagged SHAs via branch-HEAD tracking), so the old rationale did not hold. The exemption is kept, but now rests on the defensible grounds: structural immutability for local paths, and an explicit, documented trust-boundary risk acceptance for @main.

Related Issues

  • None

Change Type

  • Documentation

Changelog

  • Category: None
  • User-facing note: Internal policy documentation only; no consumer-facing behavior change.

Changelog update:

  • Not needed because this change is not user-facing

Checklist

General

  • PR title follows Conventional Commits format:
    type(scope): Summary
  • This PR does not expose backend/internal implementation details in a public repo.
  • No secrets, tokens, keys, or private endpoints are included.
  • Changes stay within this repository's intended scope.

CI/Workflow Changes (if applicable)

Not applicable: no workflow or CI/CD configuration changes.

Protocol / Compatibility Impact

  • No protocol/spec impact

Testing

  • Lint and format pass
  • Manual verification performed

Describe test evidence: bun run lint:md reports 0 issues across all 19 Markdown files (including the MD026-scoped profile heading); bun run format:check reports all files formatted; residual scan confirms no remaining @<pin-sha> placeholders or the old Dependabot rationale. Local cubic review ran before commit; the one remaining P2 (base64 badge SVG) is a disputed style preference on the standard shields.io custom-logo mechanism.

Documentation

  • README updated
  • Spec/docs updated
  • Changelog decision completed above

Rollout / Risk

  • Risk level: Low
  • Rollback plan: Revert the three commits on this branch; no behavioral or CI impact.

Reviewer Checklist

  • Scope is clear and minimal
  • Security and boundary checks passed
  • Tests and docs are sufficient
  • Compatibility impact is correctly handled