{"canonical_url":"https://engineer.company/glossary/secret/","content_markdown":"# Operational secret\n\n## What it is\n\nAn operational secret is a value that lets software, or the person who runs it, act on a system, and\nthat gives the same power to anyone else who reads it. A database connection password, an API token,\nthe private half of an SSH key pair and the passphrase that encrypts a backup are all operational\nsecrets. In everyday use the word shrinks to secrets, and the work of creating, storing, rotating\nand destroying them is called secrets management.\n\nTwo things set them apart from the code around them. The first is the reader. A user's password sits\nin someone's memory and is typed at a prompt, while an operational secret is read by a program, a\ndeploy script or a scheduled job, and nobody has to remember it. The OWASP Secrets Management Cheat\nSheet therefore gives it a lifecycle of its own: generated with the least privilege it needs,\nrotated on a schedule, revoked when it may have leaked, and set to expire where the platform allows,\nwith lifetimes from minutes to years. User passwords sit outside that regular rotation. The second\nis the line between a secret and the configuration that points at it. A hostname or a backup\nrepository path says where something is. The secret is the part that lets the holder in, and the\npart whose copies have to be counted.\n\nSecrets also nest. The store that holds them needs a secret of its own, and the cheat sheet notes\nthat this primary secret, such as a cloud provider's root credentials, usually has to be kept\nsomewhere else.\n\n## Why it matters\n\nA secret works for whoever presents it. A token carries no record of who was meant to hold it, so\neach copy widens the set of people and programs that can use it. A source repository is the worst\nplace for one to land: every clone carries the full history, so a value committed once travels to\nevery laptop, build runner and mirror that pulls, and it stays in that history after the line\nholding it is deleted.\n\nThe standards turn this into requirements. The OWASP Application Security Verification Standard asks\nfor a secrets management solution such as a key vault to create, store, control access to and\ndestroy backend secrets, and states that secrets must not be included in application source code or\nin build artefacts. It asks for least privilege on access to them and, at its highest level, for\nthem to expire and rotate. NIST SP 800-53 adds control enhancement IA-5(7): unencrypted static\nauthenticators must not be embedded in applications or other static storage. Its guidance closes a\nloophole too, since a value used exactly as it is stored counts as unencrypted, whatever file it\nsits in.\n\nThe trade-offs are real. A central store is one more system that has to be up when it is needed\nmost, and the cheat sheet points out that in an incident people expect new credentials quickly.\nSharing one secret among several services saves work and costs attribution, because after a leak\nthere is no telling which holder lost it. Manual handling grows with every secret, which is why the\ncheat sheet favours automated rotation, and it warns that restarting an application leaves a stolen\ncredential working. Only revoking it ends that.\n\n## What it looks like in practice\n\nThis site states its rule on\n[the page about how the company works securely](/security/):\nsecrets stay out of the repository. Credentials are held in a secret store or in the deployment\nlayer, kept out of source and out of anything a build produces, and an automated scan runs on every\ncommit and stops the commit when it finds one.\n\nThe engineering notes for the repository fill in the how. The scanner is gitleaks, run over the\nworking tree on every commit and again in the full quality check, and a hit is a hard stop that\nnobody is meant to allowlist away. The dependency folder and the generated output trees are\nexcluded, because they are copies rebuilt from scratch. The notes also record a quieter failure:\nwhen a file disappears mid-scan, gitleaks prints an error line and still exits successfully, so the\ntask that runs it fails on any error line. The site itself is static and holds no application\nsecrets, and it deploys over SSH with keys the owner keeps.\n\nKeeping secrets out of the repository moves them somewhere its checks cannot reach, and\n[a preflight play for secrets](/portfolio/added-a-one-second-preflight-for-secrets/)\ndeals with that gap. The secrets had just been split per host and the code was right, but the\noperator's encrypted vault, kept on the operator's own machine and out of sight of the quality gate,\nstill held the old single-host value. The first converge reached the live host, ran eight tasks and\nrefused on the ninth, after it had already written swap settings to production. The answer was a\nplay that contacts no host, gathers no facts and runs the same two task files as the real converge\nagainst the vault, in about a second, before provisioning does anything else. Reusing the code\nrather than restating the rule keeps the check and the converge from drifting apart. A bad secret\nnow costs a two-second refusal on a laptop.\n\nThe split itself is\n[the move to one value per host for every operational secret](/portfolio/split-every-operational-secret-per-host/).\nThe platform had one host and was about to have two, and several secrets had been written as single\nvalues, among them the backup repository, its passphrase and an alert switch. Each became a map\nkeyed by inventory hostname, and two reasons are recorded beside the configuration. A dead-man's\nswitch shared by two hosts stays green while either one still checks in, so the second host hides\nthe death of the first. Separate restic repositories can have distinct master keys even when they use\nthe same passphrase. But someone who obtains that passphrase and can read both\nrepositories' encrypted data and key files can unlock both, so sharing it\ncouples their exposure rather than isolating the hosts. The existing host appears in\nall four maps with its repository and both switches left empty, which says the wiring exists and the\nvalue is still owed by the operator.\n\n## Where it goes wrong\n\n**A secret lands in a commit.** A scanner flags a value in a diff, or someone spots a token in a\npushed file, because it sat in a configuration file or a test fixture when the commit was made. The\nOWASP cheat sheet gives the order of repair: revoke the exposed value first, then rotate it, and\nonly then remove it from the code or the logs. Rewriting history to drop the commit changes every\nlater commit and breaks links to them, so it needs planning. Detection belongs before the commit, in\na pre-commit hook or the editor, where a hit costs nothing.\n\n**The scan passes over files it never read.** A run ends green while part of the tree went\nunexamined: a file vanished mid-walk, an exclusion was drawn too wide, or the secret has no\nrecognisable shape. Pattern rules catch tokens with a fixed format and miss a password a person made\nup, which is why the cheat sheet suggests more than one tool. Treat any scanner error as a failure,\nand keep exclusions to copies a build recreates.\n\n**One secret serves many holders.** Two hosts, two services or a whole team use the same value. When\nit leaks, the logs cannot say which copy went, and replacing it means touching every holder at once.\nSP 800-53 asks for the authenticators of group or role accounts to change whenever membership\nchanges, and a secret per holder makes that one replacement instead of a coordinated one.\n\n**The secret ships with the build or reaches a log.** A container image, a bundled script or a debug\nline carries the value out of the place it was meant to stay. ASVS names build artefacts next to\nsource code, and the cheat sheet asks that secrets stay out of logs, masked where a line has to\nrefer to one. Scan what the build produces as well as the repository.\n\n## Further reading\n\n- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)\n  — the lifecycle of a secret, detection before the commit and the order of repair after a leak.\n- [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/)\n  — the secret management requirements in group 13.3: a vault, least privilege and rotation.\n- [NIST SP 800-53 Rev. 5](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final)\n  — authenticator management in IA-5, with IA-5(7) against embedded static authenticators.\n- [Gitleaks](https://github.com/gitleaks/gitleaks)\n  — the scanner this site runs over its working tree on every commit.\n\n\u003chttps://engineer.company/glossary/secret/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How operational secrets are kept out of source code and build artefacts, why one value shared by two hosts fails quietly, and what to do once one has leaked.","formats":{"gemtext":"https://engineer.company/glossary/secret/index.gmi","gopher":"https://engineer.company/glossary/secret/gophermap","html":"https://engineer.company/glossary/secret/","json":"https://engineer.company/glossary/secret/index.json","markdown":"https://engineer.company/glossary/secret/index.md","pdf":"https://engineer.company/glossary/secret/index.pdf"},"kind":"page","language":"en","title":"What is an operational secret?","url":"https://engineer.company/glossary/secret/","version":1}