mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:01:30 +00:00
shankar0123
558d350933
Two CI guards on origin/master failed against the Sprint-12 commit (30940108) because they didn't know about new files introduced by earlier Phase 9 sprints. Both are pure mechanical relocation fall-out — no actual regression in functionality. 1. scripts/ci-guards/no-new-synthetic-admin.sh — A-8 guard ==================================================================== Sprint 5 (commit51f9cf13) extracted the Auth-family from internal/config/config.go to internal/config/auth.go. The 4 'actor-demo-anon' references moved with the Auth-family code: - Line 255: 'actor-demo-anon is wired with AdminKey=true' documentation comment alongside the AdminKey wiring narrative. - Lines 283/289/293: residual-grants detector + cleanup SQL examples explaining why 'ar-demo-anon-admin' is reserved. These are the SAME comments that were previously in config.go (which IS in the allowlist), just relocated to the new sibling file. The references were always present in the codebase; the A-8 guard was just unaware of the new file location. Fix: add './internal/config/auth.go' to the ALLOWLIST with a rationale comment pointing at commit51f9cf13. Local verification: A-8 guard PASS — actor-demo-anon references confined to the declared 19-entry allowlist (was 18, now 19). 2. internal/ciparity/surface_parity_test.go — mcpToolFiles list ==================================================================== Sprint 10 (commitfbe053aa) split internal/mcp/tools.go (1867 LOC, 121 mcp.AddTool registrations) into six tool-domain sibling files: tools_certificates.go (22 tools — cert + CRL/OCSP + renewal + verify) tools_agents.go (16 tools — agents + agent groups) tools_resources.go (40 tools — issuers + targets + policies + profiles + teams + owners + notifications + intermediate-CAs) tools_jobs.go (9 tools — jobs + approvals) tools_discovery.go (10 tools — network-scan + discovery) tools_admin.go (24 tools — audit + stats + digest + metrics + health + health-check) The TestSurfaceParity_MCPToolCatalogue hard-gate counts mcp.AddTool registrations across mcpToolFiles() — a hard-coded 5-file list. After the split, only 34 tools sat in the 5 known files (tools.go itself went to 0 tools post-split; only the 4 pre-existing tools_*.go siblings carried any). The actual cross-file count is 155 (above the 150 floor). Fix: expand mcpToolFiles() to include the 6 new Sprint-10 sibling files. Doc-comment explains the Sprint-10 split + the union-of-files intent. Local verification: PASS: TestSurfaceParity_MCPToolCatalogue MCP tool catalogue: 155 tools (baseline floor 150) 3. docs/testing/skip-inventory.md — line-number drift ==================================================================== Adding the 8-line doc-comment to mcpToolFiles() (item 2) shifted the location of readFileOrSkip from line 97 to line 113 in surface_parity_test.go. The skip-inventory.md is auto-generated and records every t.Skip() site with its file:line; the skip-inventory-drift CI guard re-runs the generator and diffs. Fix: bump the inventory entry from :97 to :113. One-line tracking update; same skip site, new line number. (No t.Skip() was added or removed.) Behavior preservation contract ============================== - Zero runtime change. All three diffs touch only CI-guard metadata (allowlist string, file-list slice, doc line-number). - A-8 guard re-runs clean post-fix. - TestSurfaceParity_MCPToolCatalogue runs and reports 155 tools. - skip-inventory drift detection re-pins to the live line number. - gofmt + go vet + staticcheck remain clean on the touched files (verified pre-commit; the sandbox /sessions partition is full so the broader 'all guards' loop was interrupted on a tmpfile write, not on a real regression — the deterministic fix above matches the CI failure output byte-for-byte). Closes: CI failures on commit30940108across Frontend Build (A-8 guard) + Go Build & Test (TestSurfaceParity_MCPToolCatalogue).
scripts/ci-guards/ — Regression-guard scripts
Each <id>.sh script in this directory pins one closed audit finding from
regressing. CI runs the full set on every push via the
Regression guards step in .github/workflows/ci.yml. Operators can
run any script locally:
bash scripts/ci-guards/G-3-env-docs-drift.sh
Contract
Every script in this directory MUST:
- Be exit-code 0 on a clean repo (no regression present).
- Be exit-code non-zero on regression, with a
::error::annotation prefix so PR reviewers see the failing line in the GitHub Actions UI. - Be runnable from repo root via
bash scripts/ci-guards/<id>.shwith NO arguments and NO env-var requirements. The CI loop step (for g in scripts/ci-guards/*.sh; do bash "$g"; done) iterates every.shhere without args; any script that requires an arg or env var WILL fail in that loop. - Carry a head-comment block matching the in-source justification from the original ci.yml entry: the audit-finding reference, the closure rationale, the exempt-surface list (if any).
- Use
set -eearly to fail-fast on internal command errors. - Produce no output on the happy path beyond a final
echo "<id>: clean."confirmation line.
Helpers vs guards
Scripts that consume input artifacts (a test-output log, a
coverage.out file) or env vars (PR_NUMBER, GH_TOKEN) are
HELPERS, not guards. They live in scripts/, NOT scripts/ci-guards/.
Current helpers:
scripts/vendor-e2e-skip-check.sh— consumestest-output.logarg from the deploy-vendor-e2e jobscripts/coverage-pr-comment.sh— consumescoverage.out+PR_NUMBER+GH_TOKENenv from the go-build-and-test jobscripts/check-coverage-thresholds.sh— consumescoverage.out.github/coverage-thresholds.yml
Adding a new guard
- Drop a new
<id>.shin this directory with the head-comment block describing the audit finding it closes. - Make it executable:
chmod +x scripts/ci-guards/<id>.sh. - Verify it fails on a deliberate regression and passes on clean repo.
- CI auto-picks up new scripts via the
for g in scripts/ci-guards/*.shloop in theRegression guardsstep — no ci.yml change required.
Guards in this directory
Count: re-derive on demand via ls scripts/ci-guards/*.sh | wc -l. The table below names each one — keep it in sync as guards are added.
Per-finding regression guards
| ID | Finding | Catches |
|---|---|---|
G-1-jwt-auth-literal |
G-1 JWT silent auth downgrade | "jwt" literal in additive auth-type surfaces |
L-001-insecure-skip-verify |
L-001 unjustified InsecureSkipVerify | InsecureSkipVerify: true without //nolint:gosec |
H-001-bare-from |
H-001 (CWE-829) tag-swap attack | Bare FROM line without @sha256 digest pin |
M-012-no-root-user |
M-012 (CWE-250) container-as-root | Dockerfile missing terminal USER <non-root> |
H-009-readme-jwt |
H-009 README JWT advertising | README.md re-introducing JWT-as-supported claim |
G-2-api-key-hash-json |
G-2 cat-s5-apikey_leak | api_key_hash in JSON-emitting surface |
U-2-plaintext-healthcheck |
U-2 healthcheck protocol mismatch | Plaintext http:// in HEALTHCHECK directive |
U-3-migration-mount |
U-3 seed initdb schema drift | Migration file mounted into postgres initdb |
D-1-D-2-statusbadge-phantom |
D-1 + D-2 dead keys + TS phantoms | StatusBadge dead keys + 5 Certificate / 5 Agent / 1 Issuer / 1 Notification phantom fields |
L-1-bulk-action-loop |
L-1 client-side bulk loops | for ... await triggerRenewal/updateCertificate in CertificatesPage |
B-1-orphan-crud |
B-1 orphan-CRUD client fns | 8 update/create/delete fns lose their page consumer |
S-2-strings-contains-err |
S-2 brittle error-dispatch | strings.Contains(err.Error(), "not found"|"violates foreign key") in handlers |
G-3-env-docs-drift |
G-3 env-var docs drift | CERTCTL_* env var defined OR documented but not both |
test-naming-convention |
I-001-extended | func TestXxx (lowercase first letter) — Go silently skips |
S-1-hardcoded-source-counts |
S-1 stale numeric prose | Hardcoded "N issuer connectors" / "N MCP tools" in README + docs |
P-1-documented-orphan-fns |
P-1 documented orphans | 16 read-fn names removed from client.ts exports |
T-1-frontend-page-coverage |
T-1 untested frontend pages | New page in web/src/pages/ without sibling .test.tsx and not on the deferred allowlist |
bundle-8-L-015-target-blank-rel-noopener |
L-015 (CWE-1022) reverse-tabnabbing | target="_blank" without rel="noopener noreferrer" |
bundle-8-L-019-dangerously-set-inner-html |
L-019 (CWE-79) XSS | dangerouslySetInnerHTML outside safeHtml.ts |
bundle-8-M-009-bare-usemutation |
M-009 + M-029 mutation contract | Bare useMutation() outside useTrackedMutation wrapper |
H-1-encryption-key-min-length |
H-1 closure follow-up (post-Phase-5 surfacing) | CERTCTL_CONFIG_ENCRYPTION_KEY literal in any deploy/docker-compose*.yml shorter than the 32-byte floor enforced by internal/config/config.go::Validate() |
test-compose-scep-coherence |
post-Phase-5 surfacing of dead SCEP test config | CERTCTL_SCEP_ENABLED=true in test compose without (a) a CI job that runs the SCEP integration test, (b) the ra.crt + ra.key + intune_trust_anchor.pem fixtures committed to deploy/test/fixtures/, AND (c) the matching volume mount |
Forward-looking guards (Auditable Codebase Bundle, post-v2.1.0 anti-rot)
These guards catch defect classes BEFORE they get audit findings — they pin invariants on the codebase that the v2.0 audit history showed are easy to lose.
| ID | Item | Catches |
|---|---|---|
complete-path-config-coverage |
post-v2.1.0 / item-1 | "Lying field" — CERTCTL_* env var defined in internal/config/config.go that no consumer outside internal/config/ actually reads. Operator-facing config that the docs claim works but the code never honors. Companion Go test at internal/config/coverage_test.go. |
doc-rot-detector |
post-v2.1.0 / item-5 | Docs older than 90 days warn (yellow), older than 120 days fail (red). Uses HEAD commit timestamp for reproducibility. docs/archive/ allowlisted in bulk. |
The cold-DB compose smoke (post-v2.1.0 / item-6) is NOT a script in this directory — it is inlined directly into .github/workflows/ci.yml::cold-db-compose-smoke because there is no value in a developer running it locally (the whole point of the gate is that CI owns the cold-DB state). To inspect or modify the smoke logic, read that workflow job; there is intentionally no scripts/ci-guards/cold-db-compose-smoke.sh.
The fourth Bundle artifact (internal/ciparity/) is Go tests, not shell guards — runs under the standard Go test step. Pins the MCP tool catalogue floor + naming convention; reports CLI/MCP/OpenAPI surface counts as a trend metric.
Running the full set locally
for g in scripts/ci-guards/*.sh; do
echo "=== $(basename "$g") ==="
bash "$g" || echo " FAILED"
done