Skip to main content

CC5.2 — Selection and development of general controls over technology

Status: Implemented Owner: Agent #38 (Senior Compliance Lead, SOC 2 + ISO 27001) Last reviewed: 2026-05-28 Next review: 2026-08-28

Trust Services Criteria reference​

The entity also selects and develops general control activities over technology to support the achievement of objectives. The control covers infrastructure-level controls (deploy pipelines, branch protection, secrets handling), application-level controls (input validation, error handling, audit logging), and cryptographic controls (key management, version pinning, certificate handling).

How ZeroAuth meets this control​

The general-IT-controls (GITC) layer is anchored in five ADRs landed in Phase 0.

ADR 0011 — Branching workflow (commit 51bc705). dev + main only. main is force-push-disabled, PR-required, CI-required, linear-history-required. PRs from dev to main only when a phase or sprint exit gate is met. No feature branches. Hotfixes go straight to dev followed by a same-day PR to main. The pre-commit hook (per C-001) blocks Co-Authored-By: Claude, secrets, and dependency-without-ADR. --no-verify is forbidden. The CI mirror gates: tsc --noEmit clean, eslint . clean, npm test green, secret scan clean, forbidden-payload-key scan clean, ADR-trail scan clean, commit-message gate (≤ 72 chars, imperative, no feat: / fix: / WIP prefix, no emoji).

ADR 0013 — Audit log hash chain (commit 27ed93c). Every audit_events row carries previous_hash + event_hash columns; the hash is SHA-256(canonical_json(event_data) || previous_hash) per RFC 8785 JCS. The chain is per-tenant. The genesis row uses the literal "genesis" for previous_hash. All writes route through appendAuditEvent in src/services/audit.ts; direct INSERT INTO audit_events is forbidden in application code, enforced by tests/audit-chain.test.ts::"every audit-writing surface uses appendAuditEvent" (commit c09c081). Implementation: commit a475ed8. Verification endpoint: commit d634b2d. Tamper-evidence for in-DB tampering.

ADR 0014 — On-chain anchor cadence (commit 27ed93c). Each tenant's audit-chain terminal hash is anchored once per day on Base L2 via the AuditAnchor contract (commit d6c6a4e). Anchor job runs 00:30 IST. The (tenantIdHash, dayUtc) is a write-once unique key in the contract. Tamper-evidence for full-DB tampering — the bank's auditor can independently verify the chain via verify-audit-chain.sh with zero ZeroAuth runtime dependencies. Phase 0 + Phase 1 anchors land on Base Sepolia; Phase 4 mainnet migration tracked in compliance roadmap D-Q4-04 (week 46).

ADR 0015 — Circuit version pinning (commit 27ed93c). src/services/zkp.ts exports EXPECTED_CIRCUIT_VERSION + EXPECTED_VKEY_SHA256. At boot, the verifier reads verification_key.json, canonicalises it (JCS), computes SHA-256, and asserts equality with the expected hash. Mismatch → throws on boot, service does not start. Implementation: commit e98d158. Tests: tests/zkp-version.test.ts. No --force flag.

ADR 0016 — zod input validation (commit 76f8d4e). Pin to zod@3.23.x. Every /v1/* and /api/console/* POST/PUT/PATCH handler gets a zod schema with .strict() + .refine() against the biometric-payload forbidden-key list (image, template, pixel, depth, frame, raw_face, raw_finger, biometric_data, photo). Defence-in-depth with the source-grep test from C-8. Install lands C-022 sprint 2 (zod added to package.json); the ADR is the rationale-trail commit.

The cryptographic-control story is consolidated by these five ADRs plus the trusted-setup ceremony runbook at docs/cryptography/trusted-setup-ceremony.md (commit bb682f3). Boot-time verification + per-tenant chain + on-chain anchor + circuit version pinning + (forthcoming) HSM signer migration in week 48 form the v1 cryptographic-control set. The HSM migration (compliance roadmap D-Q4-06) takes the operator out of the signer-key custody loop entirely.

Supply-chain controls: every dependency requires an ADR per the dep-add skill (.claude/skills/dep-add/SKILL.md); the scripts/check-dep-trail.sh script audits the dep tree against /adr/. The nightly CVE monitor (scripts/cve-monitor.sh, commit f8a756c) catches newly disclosed vulnerabilities. The grandfathered initial deps are listed in ADR 0000.

Infrastructure controls: the multi-stage Dockerfile + docker-compose stack lives in the repo with prod / dev / test profiles. The Caddyfile pins TLS termination + reverse-proxy rules. Production deploy goes through .github/workflows/deploy.yml triggered on push to main. The VPS at 104.207.143.14 is documented in docs/threat_model.md "Threat surface inventory" with the two authorized SSH principals.

Evidence references​

  • ADR 0011-branching-workflow.md (commit 51bc705) — branch protection + CI gate definitions.
  • ADR 0013-audit-log-hash-chain.md (commit 27ed93c) — audit chain construction.
  • ADR 0014-on-chain-anchor-cadence.md (commit 27ed93c) — daily on-chain anchor.
  • ADR 0015-circuit-version-pinning.md (commit 27ed93c) — vkey boot-check.
  • ADR 0016-zod-input-validation.md (commit 76f8d4e) — input validation layer.
  • Commit a475ed8 — audit hash chain implementation.
  • Commit d634b2d — /api/admin/audit-integrity endpoint.
  • Commit c09c081 — appendAuditEvent + biometric grep enforcement.
  • Commit e98d158 — boot-time vkey hash check.
  • Commit d6c6a4e — AuditAnchor.sol contract.
  • Commit f8a756c — nightly CVE monitor.
  • Commit bb682f3 — trusted-setup ceremony runbook.
  • scripts/cve-monitor.sh, scripts/check-dep-trail.sh — supply-chain audit scripts.

Open gaps + remediation roadmap​

  • Trusted-setup ceremony execution (v1.2 circuit) — target Phase 1 week 10 (2026-07-27), per compliance-roadmap-v1.md D-Q2-14.
  • HSM-backed signer migration — target week 48 (2027-04-12), D-Q4-06.
  • RS256 JWT + JWKS publication — audit finding C-11 open-sprint-2.
  • Postgres-backed session + rate-limit (replace in-memory) — audit findings C-9 + C-10 open-sprint-2.
  • Per-tenant CORS allowlist (replace wildcard) — audit finding C-13 open-sprint-2.

Test or audit query​

ls adr/ | wc -l returns ≥ 17. git log --oneline -- src/services/audit.ts src/services/zkp.ts contracts/AuditAnchor.sol scripts/cve-monitor.sh lists the implementing commits for each control. cat tests/biometric-rejection.test.ts shows the 9-key forbidden-list.