Prevent

08 · Secrets by design: an architecture for never needing this toolkit

The rest of this repository is about responding to a leak. This page is about making leaks rare, cheap and short-lived: the controls, the architecture and the rollout plan an architect or platform lead can adopt for a whole organisation.

[!NOTE] Audience: architects, platform and DevOps leads, security engineers. Everything here is vendor-neutral; the ready-to-copy files are in prevention/.

Five principles

Reference architecture

flowchart LR
    subgraph DEV["Developer machine"]
        D1[".gitignore / .env.example"]
        D2["pre-commit: gitleaks +<br/>blocked file types"]
        D3["secrets injected at run time<br/>(no plaintext .env)"]
    end
    subgraph SRC["Source platform"]
        S1["Push protection<br/>(server-side block)"]
        S2["Org policy: no personal forks,<br/>visibility changes by admins only"]
    end
    subgraph CI["CI/CD"]
        C1["Full-history scan on every PR<br/>+ weekly full scan"]
        C2["OIDC → cloud<br/>(no stored keys)"]
        C3["Artifact scan: images,<br/>packages, IaC"]
    end
    subgraph RUN["Runtime"]
        R1["Secret manager / vault"]
        R2["Workload identity"]
        R3["Short-lived, auto-rotated<br/>credentials"]
    end
    subgraph OBS["Detect & respond"]
        O1["Audit logs + anomaly alerts"]
        O2["Public-leak monitoring<br/>+ provider alerts"]
        O3["This toolkit"]
    end
    DEV --> SRC --> CI --> RUN
    RUN --> OBS
    SRC -.-> OBS
    CI -.-> OBS
    R2 --> R1
    C2 --> R2

The control matrix

Each layer has a job in each phase. Gaps in this table are where leaks get through.

1 · Developer machine: stop it at the keyboard

.env files. The single most common leak path. The pattern that works:

Block at commit. Install the hook once per clone (pre-commit config, or the plain git hook with no framework). Both were tested: they block .env, private keys and cloud keys, and allow .env.example and normal files.

AI coding assistants. Assistants read files to build context and can write credentials into code. Keep secrets out of the files they can read, use each tool’s ignore file for secret paths, never paste a secret into a prompt, and review generated code for hard-coded keys. GitGuardian reported AI-service credentials leaking 81% more in 2025 than in 2024 (report).

2 · Repository: make the safe path the easy path

• Configuration is not a secret store. Settings files hold names and references (vault://payments/db), never values.
• Teach the scanner your formats. Internal tokens with a recognisable prefix (acme_live_…) are easy to detect; add a rule in gitleaks.toml.
• Keep allow-lists tiny. Every allow-listed path is a place secrets are not looked for.
• Score every repository: ./leak audit <path> checks ignore rules, tracked secret files, hooks, CI scanning, Docker hygiene and the full history, and gives a grade.

3 · Source platform: the enforcement point

4 · CI/CD: no stored cloud keys, ever

Workload identity federation (OIDC). The pipeline gets a token for about an hour, scoped to one repository and branch or environment. There is no key to store, rotate or leak. Copy-ready jobs for AWS, Azure and Google Cloud: prevention/oidc/github-to-clouds.yml. Restrict the trust to the token’s sub claim (repository plus branch or environment), never to the whole organisation.

Scan every change, and everything weekly. Pull requests are scanned over the full history; a weekly scheduled scan catches branches nobody touched. Templates: GitHub Actions, GitLab, Azure Pipelines, Bitbucket.

Logs are output. Masking only covers registered secrets; values derived from them (encoded, split, printed by tools) are not masked. Never echo a secret, avoid set -x around secret handling, and treat public CI logs as public.

5 · Artifacts: images, packages and infrastructure state

6 · Runtime: secret manager plus identity

flowchart LR
    W["Workload"] -->|"proves identity<br/>(managed / workload identity)"| V["Secret manager"]
    V -->|"short-lived secret,<br/>or none needed"| W
    W -->|"identity-based auth"| DB["Database / API"]
    V -.->|"audit log"| L["SIEM"]
    R["Rotation automation"] --> V

• Prefer identity-based authentication to secrets entirely where the service supports it (cloud databases, storage, queues).
• When a secret is unavoidable, the workload fetches it at start-up with its identity, and rotation is automated with an overlap so nothing breaks.
• Dynamic credentials (issued per session, expiring in minutes or hours) beat static ones: a leaked dynamic credential is already dead.
• Environment variables vs files: environment variables are easy but leak through crash dumps, debug pages and child processes. For high-value secrets prefer files mounted with tight permissions, and never log the environment.

7 · Observability: notice in minutes, not months

• Redact at the source: logging libraries filter known secret fields; error pages never print configuration.
• Alert on the use of credentials, not only their exposure: a service identity signing in from a new network, a new region, or spending in a service it never uses.
• Canary tokens: fake credentials placed where an attacker would look (old repositories, build servers). Any use is a high-confidence alarm.
• Public-leak monitoring for your domains, token formats and developer emails, plus provider exposure emails routed to a monitored mailbox, not one person’s inbox.

8 · People and process

• A one-page policy everyone signs: company code and secrets never go to personal or public places, with the safe alternative spelled out.
• Onboarding includes installing the hook; offboarding removes access on the last day.
• Reporting a mistake is praised, not punished. The engineer who reports a leaked key in five minutes saves the company hours.
• A rotation owner for every credential, recorded in the secret manager, and a quarterly drill.

Maturity model

A 90-day rollout

Measure it

Design-review checklist for a new service

• Does it authenticate to cloud services with identity, not keys?
• Where a secret is unavoidable: is it in the secret manager, fetched at start-up, with a named owner and automated rotation?
• Is every credential scoped to this service and this environment only?
• Does the pipeline deploy with OIDC, with trust limited to this repository and branch or environment?
• Does the repository have .env.example, ignore rules, the hook, and CI scanning (./leak audit grade A or B)?
• Is IaC state remote, encrypted and access-controlled?
• Are logs and error pages free of configuration values?
• Would we notice if one of its credentials were used from somewhere unexpected?
• Could we rotate every one of its credentials today, in minutes, without an outage?