|
| 1 | +# 0.5.15 Slice 10 — Gitleaks secret-scan implementation plan |
| 2 | + |
| 3 | +**Status:** repository-controlled implementation complete locally — updated |
| 4 | +2026-08-15. External GitHub merge-blocking enforcement remains pending; see |
| 5 | +`10-gitleaks-ci-secret-scan-status.md` for the exact evidence and limitation. |
| 6 | + |
| 7 | +## Admission check |
| 8 | + |
| 9 | +| Gate | Current evidence | Required before implementation starts | |
| 10 | +| --- | --- | --- | |
| 11 | +| Previous slice closure | Slices 0–5 and Slice 6 are complete; Slice 6 includes Slice 10 with external enforcement conditional. | **Passed.** Recheck the decision and all changes since this plan before beginning the slice. | |
| 12 | +| Draft contract | Slice 3 proposes DFR-35/DAC-35, and Slice 4 confirms isolated architecture alignment. | Ratify the draft as the Slice 10 contract at slice start. | |
| 13 | +| Security design review | `70-gitleaks-ci-secret-scan-design.md` and review `71` conditionally pass. | Security reviewer confirms the current pins, 38-entry baseline, and external-enforcement posture still match the accepted design. | |
| 14 | +| Repository authority | Wake records approval of the least-privilege control direction and scoped scanner ownership. | GitHub administrator confirms authority for a disposable PR, required check, branch protection, and code-owner enforcement. | |
| 15 | + |
| 16 | +Until all four gates pass, do not commit, push, enable the workflow, configure |
| 17 | +GitHub settings, add dependencies, or claim that merge-blocking enforcement is |
| 18 | +active. |
| 19 | + |
| 20 | +## Changes since the original design |
| 21 | + |
| 22 | +| Original assumption | Current reconciled state | Plan update | |
| 23 | +| --- | --- | --- | |
| 24 | +| Slice 0 found an incomplete Python 3.11 environment. | The worktree was rebuilt on Python 3.12.3 with `make sync && make verify`; the ordinary non-live CI baseline, docs, lint, mypy, Docker build, and audit passed. | Treat this as a healthy pre-feature baseline only. Slice 10 has no Python/runtime dependency and must not add one. | |
| 25 | +| Local and historical baselines needed reconciliation. | `.gitleaksignore` now has 38 exact entries: the original local findings plus the 16 reviewed commit-qualified history findings described by design review 71. | Re-review the entries as exact fingerprints; do not broaden paths, disable rules, or add wildcard suppression. Prove both directory and history scans before commit. | |
| 26 | +| Action SHAs were to be resolved. | The untracked workflow pins checkout v6 to `d23441a48e516b6c34aea4fa41551a30e30af803` and Gitleaks Action v3 to `e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e`; scanner remains `8.30.0`. | Independently reconfirm release provenance at slice start. Do not substitute mutable tags or combine this work with Actions-major PR #44. | |
| 27 | +| Gitleaks and pre-commit tooling were absent from `PATH`. | They remain absent; only `actionlint` is presently available. | Use a reviewed, ephemeral pinned local-tool invocation or a checksum-verified Gitleaks 8.30.0 binary without adding it to `pyproject.toml`, `uv.lock`, Docker, or Airlock runtime. Record the exact invocation and version in the slice status. | |
| 28 | +| Controls were proposed repository changes. | `.gitleaksignore`, `.pre-commit-config.yaml`, `.github/CODEOWNERS`, and `.github/workflows/gitleaks.yml` are still untracked worktree baseline. | Preserve them exactly until review; stage only these named files and the Slice 10 status/documentation files—never broad staging. | |
| 29 | + |
| 30 | +## Scope and non-goals |
| 31 | + |
| 32 | +**In scope:** an isolated Gitleaks GitHub workflow; a Gitleaks 8.30.0 |
| 33 | +pre-commit hook; a narrow exact-fingerprint baseline; scanner-file code |
| 34 | +ownership; minimal developer instructions; local, disposable-PR, and external |
| 35 | +GitHub-enforcement evidence. |
| 36 | + |
| 37 | +**Out of scope:** Airlock runtime code, `config.yaml`, Docker image, provider |
| 38 | +credentials, deployment/release workflows, Dependabot PRs, Action major |
| 39 | +upgrades, GitHub Advanced Security/code scanning uploads, broad scanner |
| 40 | +exceptions, and any secret-management redesign. |
| 41 | + |
| 42 | +## Implementation sequence |
| 43 | + |
| 44 | +1. **Ratify and snapshot scope.** Record the Slice 6 include decision, DFR-35/ |
| 45 | + DAC-35 acceptance criteria, designated security owner, GitHub administrator, |
| 46 | + and the reviewed file list. Recheck that the branch/worktree still contains |
| 47 | + only the known untracked baseline; preserve unrelated user files. |
| 48 | +2. **Re-verify supply chain and baseline.** Independently verify both full |
| 49 | + Action SHAs against the stated official releases. Obtain the exact Gitleaks |
| 50 | + `8.30.0` scanner by a reviewed ephemeral/checksum-verified path. Run |
| 51 | + redacted `gitleaks dir .` and `gitleaks git .`; review any result |
| 52 | + individually. A clean result is required before the controls are committed. |
| 53 | +3. **Record RED evidence.** In a disposable branch/PR, add a synthetic, |
| 54 | + non-usable detector fixture that is designed to be redacted. Demonstrate |
| 55 | + local-hook and CI failure without copying the value to logs, plans, or PR |
| 56 | + comments; remove the fixture immediately after evidence capture. |
| 57 | +4. **Review and commit the repository controls.** Review only |
| 58 | + `.pre-commit-config.yaml`, `.gitleaksignore`, `.github/CODEOWNERS`, and |
| 59 | + `.github/workflows/gitleaks.yml`. Confirm stable `gitleaks / scan` naming, |
| 60 | + full checkout, PR/push/manual/weekly triggers, read-only permissions, no |
| 61 | + `pull_request_target`, no OIDC/write scope, and comments/artifact/summary |
| 62 | + disabled. Add a short developer instruction only if review identifies an |
| 63 | + existing authoritative location; do not create duplicate authority. |
| 64 | +5. **Record GREEN evidence.** Re-run local directory/history scans, the staged |
| 65 | + pre-commit hook, and `actionlint`. Open a disposable PR, prove a redacted CI |
| 66 | + failure then a green run after fixture removal; validate manual dispatch and |
| 67 | + a normal `main`-equivalent push only through authorized repository workflow. |
| 68 | +6. **Apply external enforcement.** The GitHub administrator configures `main` |
| 69 | + to require `gitleaks / scan` and code-owner review for the three scanner |
| 70 | + files. Prove a failing scan and an unapproved scanner/baseline modification |
| 71 | + cannot merge. Do not report this as active before this external evidence. |
| 72 | +7. **Close the slice.** Write `10-gitleaks-ci-secret-scan-status.md` with |
| 73 | + ratified contract, exact pins/version, baseline review count, commands and |
| 74 | + redacted results, CI/PR URLs, GitHub-rule evidence, residual runtime-binary |
| 75 | + provenance risk, and rollback disposition. |
| 76 | + |
| 77 | +## Required verification and acceptance evidence |
| 78 | + |
| 79 | +| Boundary | Evidence | |
| 80 | +| --- | --- | |
| 81 | +| Local detection parity | Gitleaks `8.30.0` directory and reachable-history scans both produce zero reviewed findings; the hook invokes the same scanner version. | |
| 82 | +| False-positive discipline | Baseline entries are exact fingerprints, individually reviewed, and line/path or commit changes create a new finding. No rule, directory, or generic test/docs exemption is introduced. | |
| 83 | +| Workflow isolation | `actionlint` passes; workflow has only `contents: read` and `pull-requests: read`, full checkout, no repository/deployment secrets, no artifact/SARIF/comment/summary publication, and no runtime invocation. | |
| 84 | +| Detection regression | Disposable synthetic fixture fails locally and in CI with redaction, then removal restores green. The fixture is not retained in mainline or copied into durable evidence. | |
| 85 | +| Merge enforcement | GitHub administrator supplies branch-protection and code-owner proof that the stable check and designated review cannot be bypassed on `main`. | |
| 86 | +| Existing CI health | Re-run the affected workflow validation plus the repository’s ordinary CI evidence proportionate to touched files; no Python dependency or product-test expansion is expected. | |
| 87 | + |
| 88 | +## Failure handling and rollback |
| 89 | + |
| 90 | +- A new finding is treated as potentially real until security review proves it |
| 91 | + is a non-usable fixture. Rotate/revoke any usable credential before changing |
| 92 | + a baseline. |
| 93 | +- A false positive is resolved only by a reviewed exact fingerprint after |
| 94 | + preserving detector coverage. Never suppress the rule or an entire path to |
| 95 | + unblock a merge. |
| 96 | +- If the workflow itself is defective, revert the named scanner-control commit |
| 97 | + or have the GitHub administrator temporarily remove the required check with a |
| 98 | + recorded security decision. Do not use an unprotected direct push as a |
| 99 | + workaround. |
| 100 | +- If the official Action’s runtime-binary provenance becomes unacceptable, |
| 101 | + pause enforcement and design a separately reviewed digest-pinned alternative; |
| 102 | + do not add a second divergent scanner as an emergency replacement. |
| 103 | + |
| 104 | +## Completion criteria |
| 105 | + |
| 106 | +Slice 10 closes only when DFR-35/DAC-35 is ratified, repository controls are |
| 107 | +committed and reviewable, all local/CI redacted evidence passes, the controlled |
| 108 | +failure proof is complete, the GitHub administrator has demonstrated required |
| 109 | +check and code-owner enforcement, and the status record names all residual |
| 110 | +risks. If external GitHub authority is unavailable, close only the |
| 111 | +repository-controlled portion as conditional and explicitly state that |
| 112 | +merge-blocking enforcement is not active. |
0 commit comments