These are the notes for Cybersecurity Fundamentals (defensive), episode 59. In episodes 56 to 58 one toy file kept appearing: a database password. This episode is about that password, and every secret like it: where apps keep them, how they leak (into code, chats and git history), how scanners find them, where they should live instead (secret managers), how to make them expire, and exactly what to do when one leaks anyway. Every term is defined the first time it appears; the Glossary collects them.
Scope. Defensive and educational only. Every program is a toy that works on its own files; every key shown is fake; no real account or system is touched. Compiler samples were run on 13 Nov 2026 in the SyntaxPilot compiler (Python 3.13 with git). The detect-secrets 1.5.0 output was produced the same day on the same machine. Commit IDs and folder names differ on your machine.
What a secret is
- Secret: any piece of information that grants access by itself: a password, an API key (a long string an app sends to prove it may use a service), a token (a temporary pass), a private key, a database connection string. Whoever holds it gets in; nobody checks who they are.
- Credential: something used to prove identity or access; secrets are the credentials a program uses.
- A secret is different from ordinary configuration (a port number, a feature flag): leaking a port number is harmless, leaking a key is not.
Step 1: hardcoded credentials and secret sprawl
Real-life example: writing your ATM PIN on the back of the card. Convenient, and when the card is lost, so is the money. And photocopies of the card carry the PIN too.
- Hardcoded credentials: a secret written directly into source code, e.g.
DB_PASSWORD = "chai123"inconfig.py. - Why it is bad: code is copied everywhere: every developer's laptop, every clone and fork, every backup, CI build logs, screenshots in chats. Each copy carries the secret, and anyone who can read the code (including future employees, contractors, or an attacker who reads one laptop) can use it. You also can't change the secret without changing and redeploying code.
- Secret sprawl: the same secret scattered across code,
.envfiles, chats, wikis, tickets, CI settings and laptops, so nobody knows how many copies exist or who has them.
Step 2: environment variables and .env files
- Environment variable: a named value the operating system hands a program when it starts, outside the code (e.g.
DB_PASSWORD=...). In Python:os.environ["DB_PASSWORD"]. .envfile: a local text file ofNAME=valuelines, loaded into environment variables at start-up (the python-dotenv library does this; our toyload_envdoes the same)..gitignore: a file listing paths git must ignore, sogit add .never picks them up..env.example: a committed file with the variable names and no values, so teammates know what to set.
Demo 1: read the secret from the environment
# Read the password from the ENVIRONMENT, not from the code.
import os, subprocess
def load_env(path): # what python-dotenv does
for line in open(path):
line = line.strip()
if line and not line.startswith("#"):
key, _, value = line.partition("=")
os.environ.setdefault(key, value)
try:
password = os.environ["DB_PASSWORD"]
except KeyError as e:
print("no secret yet -> KeyError:", e) # fail loudly, never a default
open(".env", "w").write("# local only, never commit\nDB_PASSWORD=chai123\n")
load_env(".env")
password = os.environ["DB_PASSWORD"]
print("from .env ->", password[:2] + "*" * (len(password) - 2))
open(".gitignore", "w").write(".env\n") # keep .env out of git
subprocess.run(["git", "init", "-q"])
r = subprocess.run(["git", "check-ignore", "-v", ".env"],
capture_output=True, text=True)
print("git check-ignore->", r.stdout.strip())
Real output:
no secret yet -> KeyError: 'DB_PASSWORD'
from .env -> ch*****
git check-ignore-> .gitignore:1:.env .env
Lessons: fail loudly when a secret is missing (never os.environ.get("DB_PASSWORD", "admin"), which silently runs with a guessable default: that "fails open"); never print or log secrets (we masked all but two letters); and git check-ignore -v proves which .gitignore rule ignores a file. A .env file is fine for your own laptop; servers should get secrets from a secret manager (Step 5).
Step 3: git never forgets
Real-life example: on Monday the password is committed, on Tuesday someone "removes" it. Today's file looks clean, but Monday's snapshot is still in the history.
- Git: a version control system. Each commit is a saved snapshot of the whole project, kept so you can go back.
- Git history: all commits, which every clone carries in full.
git log -S <text>: lists the commits where<text>was added or removed (a "pickaxe" search of history).git show <commit>:<file>: prints a file as it was in that commit.HEAD~1means "one commit before the latest".
Demo 2: a "deleted" password is still in history
# Commit a password by mistake, "delete" it, then look at git history.
import subprocess, os
def git(*args):
who = ["-c", "user.name=Asha", "-c", "user.email=asha@example.com"]
r = subprocess.run(["git", *who, *args], capture_output=True, text=True)
return r.stdout.strip().replace("\n", " | ")
git("init", "-q", "shop")
os.chdir("shop")
open("config.py", "w").write('DB_PASSWORD = "chai123"\n')
git("add", ".")
git("commit", "-qm", "add config")
open("config.py", "w").write('DB_PASSWORD = os.environ["DB_PASSWORD"]\n')
git("commit", "-qam", "remove password") # "fixed"... right?
print("today's file :", open("config.py").read().strip())
print("git log :", git("log", "--oneline"))
print("has chai123 :", git("log", "-S", "chai123", "--oneline"))
print("old version :", git("show", "HEAD~1:config.py")) # still there!
Real output (commit IDs differ every run):
today's file : DB_PASSWORD = os.environ["DB_PASSWORD"]
git log : a8b10e5 remove password | b929340 add config
has chai123 : a8b10e5 remove password | b929340 add config
old version : DB_PASSWORD = "chai123"
So: once a secret has been pushed, treat it as leaked. Tools such as git filter-repo can rewrite history to remove it, but they cannot reach clones, forks, caches and backups that already exist. The only real fix is to revoke and rotate the secret (Steps 6 and 7). Rewriting history afterwards is cleanup, not the fix.
Step 4: secret scanning
- Secret scanning: automatically searching code (and its history) for things that look like secrets.
- Scanners use two tricks:
- Patterns: many providers' keys have a fixed shape. An AWS access key ID starts with
AKIAfollowed by 16 capital letters and digits; a scanner can matchAKIA[0-9A-Z]{16}. - Entropy: how random a string looks, measured in bits per character (Shannon entropy). English words repeat letters and score low; random keys score high.
- False positive: a harmless string flagged by mistake. False negative: a real secret missed. Scanners have both, so findings need a person to check them.
Demo 3: a toy scanner (patterns + entropy)
# A tiny secret scanner: known PATTERNS + random-looking strings (entropy).
import re, math
from collections import Counter
code = ['db_password = "chai123"',
'aws_key = "AKIAQ3EXAMPLE7KZ2M4P"',
'token = "q8ZpV2xL9tR4mW7nB1cY6dK3"',
'greeting = "hello everyone, welcome"']
PATTERNS = {"AWS access key id": r"AKIA[0-9A-Z]{16}",
"password assignment": r"(?i)password\s*=\s*\"[^\"]+\""}
def entropy(s): # bits per character: how random it looks
n = len(s)
return -sum(c / n * math.log2(c / n) for c in Counter(s).values())
for no, line in enumerate(code, 1):
for name, rx in PATTERNS.items():
if re.search(rx, line):
print(f"line {no}: {name}")
for word in re.findall(r'"([^"]{16,})"', line):
e = entropy(word)
verdict = "HIGH -> looks like a key" if e > 4 else "low -> text"
print(f"line {no}: entropy {e:.2f} {verdict}")
Real output:
line 1: password assignment
line 2: AWS access key id
line 2: entropy 3.68 low -> text
line 3: entropy 4.58 HIGH -> looks like a key
line 4: entropy 3.35 low -> text
The fake AWS key was caught only by its pattern (its entropy, 3.68, looked like text), and the random token only by entropy. That is why real scanners use both.
Real scanners and pre-commit hooks
- Pre-commit hook: a script git runs before every commit; if it exits non-zero, the commit is blocked.
- detect-secrets (by Yelp): scans files; a baseline file (
.secrets.baseline) records findings already reviewed so only new secrets are reported;detect-secrets-hookis its pre-commit hook.
Real output (detect-secrets 1.5.0, fake keys):
$ detect-secrets scan config.py (findings, one per line)
config.py:3 AWS Access Key
config.py:4 Secret Keyword
$ detect-secrets scan config.py > .secrets.baseline
$ echo 'api_token = "q8ZpV2xL9tR4mW7nB1cY6dK3"' >> config.py
$ detect-secrets-hook --baseline .secrets.baseline config.py
ERROR: Potential secrets about to be committed to git repo!
Secret Type: Base64 High Entropy String
Location: config.py:5
...
$ echo $?
1
- gitleaks: a free scanner for git repositories, files and CI; it can scan the whole history, not just today's files.
- TruffleHog (Truffle Security): "Find, verify, and analyze leaked credentials"; it classifies hundreds of secret types and can verify a finding by checking whether the key is still live, which cuts false positives. Only verify keys that belong to you or your organisation.
- Run a scanner in a pre-commit hook, in every CI build, and once over the full history of every existing repository.
Push protection
- Push protection (GitHub): "blocks pushes that contain secrets before they reach your repository". It sits between your commit and the shared repository.
- For user accounts it "is enabled by default" (for public repositories on GitHub.com). For repositories it is "disabled by default"; an admin, organisation owner or security manager turns it on.
- Bypass: someone with write access can push anyway by giving a reason ("used in tests", "false positive", "I'll fix it later"); each bypass creates an alert, is recorded in the audit log, and emails owners.
- Three gates in order: pre-commit hook (laptop) → push protection (server, at push) → repository secret scanning alerts (everything already stored).
Step 5: secret managers
Real-life example: gold in a drawer at home with a copy of the key under every doormat, versus a bank locker: one place, ID checked at the door, every visit written in a register.
- Secret manager: a service that stores secrets encrypted, gives each app access only to its own secrets (access control), and records every read (audit log). The app fetches the secret at runtime, so it never appears in code, images or git.
- AWS's docs put the idea simply: "You replace hard-coded credentials with a runtime call to the Secrets Manager service to retrieve credentials dynamically when you need them."
| Product | What its docs say |
|---|---|
| HashiCorp Vault | runs on any cloud or your own servers; issues dynamic secrets, each with a lease |
| AWS Secrets Manager | manage, retrieve and rotate "database credentials, application credentials, OAuth tokens, API keys, and other secrets"; automatic rotation schedules |
| Azure Key Vault | "a secure secrets store, providing management for secrets, keys, and certificates, all backed by Hardware Security Modules" |
| Google Cloud Secret Manager | stores "API keys, usernames, passwords, certificates" and more, as versions you can roll back to |
- HSM (hardware security module): a special tamper-resistant device that stores and uses cryptographic keys without ever letting them out.
- Secret version: each change to a secret is kept as a numbered version, so an app can pin one and you can roll back.
Typical use in Python (AWS shown; the others are similar):
import boto3, json
client = boto3.client("secretsmanager")
secret = json.loads(client.get_secret_value(SecretId="shop/db")["SecretString"])
password = secret["password"] # fetched at runtime, never in the code
Step 6: dynamic secrets, rotation, short-lived credentials, workload identity
Even a secret fetched from a locker can leak from a running app (a crash dump, a debug log, a compromised server). So make it expire.
- Dynamic secret: a secret created on demand, unique to one app or one request, that expires on its own.
- Lease / TTL (time to live): how long a secret stays valid. Vault: "All dynamic secrets in Vault are required to have a lease"; "When a lease is revoked, it invalidates that secret immediately and prevents any further renewals."
- Revoke: make a secret stop working, now.
- Blast radius: how much damage one leaked secret can do. Per-app, short-lived secrets keep it small, and the audit log shows exactly which app did what.
Demo 4: a toy vault with leases
# A toy secrets manager: each app gets its OWN short-lived password.
import secrets, time
class ToyVault:
leases = {} # lease id -> (password, expiry)
def issue(self, app, ttl): # a "dynamic secret"
lease = f"{app}-{secrets.token_hex(2)}"
self.leases[lease] = (secrets.token_urlsafe(9), time.time() + ttl)
return lease, self.leases[lease][0]
def check(self, lease, password):
if lease not in self.leases:
return "DENIED (revoked)"
pw, expiry = self.leases[lease]
if time.time() > expiry:
return "DENIED (expired)"
return "OK" if secrets.compare_digest(pw, password) else "DENIED"
def revoke(self, lease):
self.leases.pop(lease, None)
v = ToyVault()
a, a_pw = v.issue("billing", ttl=1.0) # lives for 1 second
b, b_pw = v.issue("reports", ttl=60)
print("billing now :", v.check(a, a_pw))
time.sleep(1.2)
print("billing at 1.2s :", v.check(a, a_pw)) # expired by itself
print("reports :", v.check(b, b_pw))
v.revoke(b) # leaked? kill it now
print("reports, revoked:", v.check(b, b_pw))
Real output:
billing now : OK
billing at 1.2s : DENIED (expired)
reports : OK
reports, revoked: DENIED (revoked)
- Secret rotation: replacing a secret with a new one (on a schedule, e.g. every 30 days, or right after a leak), updating every app that uses it, then retiring the old one. With a secret manager, apps fetch the new value automatically.
- Short-lived credentials: credentials that expire by themselves in minutes or hours, like a hotel key card that stops working at checkout.
- Workload: any running program: a web app, a container, a build job.
- Workload identity: the platform a workload runs on vouches for it (like a company ID badge the building issues), and the cloud exchanges that proof for a short-lived token. There is no stored secret to leak or rotate. Examples: a cloud server's attached role, a Kubernetes service account, a CI job's signed identity token (episode 63 covers CI-to-cloud federation).
Step 7: when a secret leaks: revoke, rotate, review
- Revoke at the source (the provider's console, the database, the cloud IAM page), right away. Deleting the line from the code does not stop the key working.
- Rotate: issue a new secret, store it in the secret manager, and update every app that used the old one.
- Review: check the logs. Was the old secret used, when, by whom, from where? If it was used by someone else, it is now a security incident (episode 75 covers incident response). Then fix the cause: add the scanner, the hook, or the push protection that would have caught it.
The whole chain
- A password in the code → hardcoded credentials; copies everywhere → secret sprawl.
- → environment variables,
.envin.gitignore,.env.examplecommitted. - Committed once → still in git history → treat as leaked.
- → secret scanning (patterns + entropy), pre-commit hooks, push protection, history scans.
- → one secret manager: Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager.
- Still leaks from a running app → dynamic, short-lived secrets, rotation, workload identity.
- Leaked anyway → revoke, rotate, review.
Common mistakes (and the fix)
| Mistake | What you see | Why | Fix |
|---|---|---|---|
DB_PASSWORD = "chai123" in config.py |
old version : DB_PASSWORD = "chai123" |
git keeps every snapshot | os.environ[...] + a secret manager |
git add . with a .env file |
.env in the commit |
not in .gitignore |
add .env to .gitignore; git check-ignore -v .env |
os.environ.get("DB_PASSWORD", "admin") |
app runs with a guessable password | fails open | os.environ["DB_PASSWORD"] → KeyError |
print(password) / logging the secret |
the secret in log files | logs are widely readable | log a mask (ch*****) or nothing |
| "deleting" a leaked key and pushing | the key still works | not revoked | revoke, rotate, review |
| one shared password for all apps | can't tell which app leaked it | big blast radius | one secret per app, short-lived |
| secret pasted in a chat or ticket | secret sprawl | uncontrolled copies | share a secret-manager path, never the value |
| bypassing push protection with "I'll fix it later" | open alert, key in the repo | still leaked | remove and rotate before pushing |
Mini project: move a toy app's secrets out of the code
Take any small app of yours with a hardcoded key. (1) Search its history: git log -p -S "<part of the key>". (2) Move the key to an environment variable that is read with os.environ[...], add .env to .gitignore, and commit a .env.example. (3) Add a detect-secrets (or gitleaks) pre-commit hook and a baseline. (4) Rotate the key at its provider, since the old one is in history. (5) Optionally, store it in a secret manager's free tier or a local Vault dev server and fetch it at start-up. Write down what you would do if the key had been public.
Practice
1. Why is os.environ.get("API_KEY", "test-key") a bad idea in production code?
Solution
If the variable is missing (a typo, a misconfigured server), the app silently runs with a known, guessable key: it fails open. Use os.environ["API_KEY"] so a missing secret stops the app with KeyError, which you notice immediately.
2. Write the commands that prove a secret was ever committed in a repository, and show the old file.
Solution
git log -S "chai123" --oneline --all # which commits added/removed it
git show <commit>~1:config.py # the file just before it was removed
git log -p -S "chai123" --all # full diffs
3. Extend the toy scanner with a rule for private keys (-----BEGIN ... PRIVATE KEY-----).
Solution
PATTERNS["private key"] = r"-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----"
4. Add a renew(lease, ttl) method to the toy vault.
Solution
def renew(self, lease, ttl):
if lease not in self.leases:
return False # revoked leases can't be renewed
pw, _ = self.leases[lease]
self.leases[lease] = (pw, time.time() + ttl)
return True
Real Vault also enforces a maximum TTL, so a lease can't be renewed forever.
5. A teammate pasted a production database password in a team chat. List the steps, in order.
Solution
- Revoke: change the database password (or disable that user) now. 2. Rotate: put the new password in the secret manager; restart or refresh the apps that use it. 3. Review: check database logs for logins with the old password since it was pasted; delete the chat message (cleanup only). 4. Fix the cause: share secret-manager paths, never values, and give each app its own credentials.
6. What is the difference between rotation and a dynamic secret?
Solution
Rotation replaces one long-lived shared secret on a schedule (every app gets the new value). A dynamic secret is created on demand for one app with its own short lease, so it expires by itself and each app has a different one.
Quick quiz
$ git log --oneline
9f2c1aa add payment config <- has PAYMENT_API_KEY
A: delete the line and push again
B: make the repository private
C: revoke the key at the provider
D: rewrite history with git filter-repo
An API key was pushed to a public repository an hour ago. What is the first step?
Answer
C. Assume anyone may already have the key: revoke it at the provider first so it stops working, then rotate (issue a new key into the secret manager), then review the logs. A, B and D only hide the key; copies already made still work until it is revoked.
Interview questions
- What is a secret, and why are hardcoded credentials dangerous? Data that grants access by itself; in code it is copied to every clone, backup and log, can't be changed without redeploying, and lives in git history forever.
- Is a
.envfile secure? It keeps secrets out of code and git (if ignored), but it is still a plain-text file on disk; fine for local development, not a replacement for a secret manager on servers. - You removed a key in a new commit. Is it gone? No: it remains in history and every clone. Revoke and rotate it; history rewriting is optional cleanup.
- How do secret scanners work? Provider-specific patterns plus entropy, with baselines and allow-lists for false positives; some verify whether keys are live.
- What is push protection? A server-side check that blocks a push containing secrets before it reaches the repository; bypasses need a reason and create alerts.
- What does a secret manager give you over environment variables? Encrypted storage, per-app access control, audit logs, versions, rotation and dynamic secrets, fetched at runtime.
- What is a dynamic secret? A credential created on demand with a lease (TTL), unique per consumer, revocable immediately.
- What is workload identity and why is it better than a stored key? The platform attests to the workload's identity and the cloud issues short-lived tokens; nothing long-lived is stored to leak or rotate.
- What do you do after a secret leaks? Revoke, rotate, review (logs for use), then fix the cause.
Glossary
| Term | Meaning |
|---|---|
| secret | information that grants access by itself (password, API key, token, private key) |
| credential | something that proves identity or access |
| API key | a long string an app sends to prove it may use a service |
| token | a temporary pass that grants access |
| hardcoded credentials | a secret written directly into source code |
| secret sprawl | the same secret scattered across code, chats, wikis, CI and laptops |
| environment variable | a named value the OS gives a program at start-up, outside the code |
.env file |
a local file of NAME=value lines loaded into environment variables |
| python-dotenv | a Python library that loads .env files |
.gitignore |
a file listing paths git must ignore |
.env.example |
a committed file with variable names and no values |
| fail open / fail loudly | continue insecurely when something is missing / stop with a clear error |
| git | a version control system |
| commit | a saved snapshot of the whole project |
| git history | all commits, carried in full by every clone |
git log -S |
find commits where a piece of text was added or removed |
git show <commit>:<file> |
print a file as it was in a commit |
HEAD~1 |
the commit before the latest |
git filter-repo |
a tool that rewrites git history (cleanup after rotation) |
| secret scanning | automatically searching code and history for secrets |
| pattern (secret) | the fixed shape of a provider's keys, e.g. AKIA + 16 characters |
| entropy | how random a string looks, in bits per character |
| false positive / false negative | a harmless string flagged / a real secret missed |
| pre-commit hook | a script git runs before each commit; non-zero exit blocks it |
| baseline | a file of already-reviewed findings so only new ones are reported |
| detect-secrets | Yelp's secret scanner and pre-commit hook |
| gitleaks | a free scanner for git history, files and CI |
| TruffleHog | a scanner that finds and can verify leaked credentials |
| verification (scanner) | checking whether a found key still works |
| push protection | blocking a push that contains secrets before it reaches the repository |
| bypass | pushing anyway with a recorded reason; creates an alert |
| audit log | a tamper-resistant record of who did what, when |
| secret manager | a service that stores secrets encrypted with access control and audit logs |
| HashiCorp Vault | a secret manager that runs anywhere and issues dynamic secrets |
| AWS Secrets Manager | AWS's secret manager with rotation schedules |
| Azure Key Vault | Azure's store for secrets, keys and certificates, backed by HSMs |
| Google Cloud Secret Manager | Google Cloud's secret manager with versions |
| HSM (hardware security module) | a tamper-resistant device that stores and uses keys |
| secret version | a numbered copy of a secret's value, for pinning and rollback |
| runtime | while the program is running |
| dynamic secret | a secret created on demand for one consumer that expires |
| lease / TTL | how long a secret stays valid (time to live) |
| revoke | make a secret stop working immediately |
| blast radius | how much damage one leaked secret can do |
| secret rotation | replacing a secret with a new one and retiring the old |
| short-lived credentials | credentials that expire by themselves in minutes or hours |
| workload | any running program: an app, a container, a build job |
| workload identity | the platform vouches for a workload; the cloud issues it short-lived tokens; no stored secret |
| revoke-rotate-review | the three steps after a leak |
| security incident | an event where security was actually breached (e.g. a leaked key was used) |
Summary
- A secret grants access by itself; written into code it is copied everywhere and kept in git history forever.
- Read secrets from the environment, fail loudly if missing, never log them, keep
.envin.gitignore. - Pushed once means leaked: revoke and rotate; history rewriting is only cleanup.
- Scan with patterns and entropy: pre-commit hooks, push protection, and full-history scans (detect-secrets, gitleaks, TruffleHog).
- Keep secrets in one secret manager (Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager), fetched at runtime.
- Prefer dynamic, short-lived secrets, or none at all with workload identity; rotate the rest.
- On a leak: revoke, rotate, review.
- Next episode: secure SDLC and DevSecOps.
Sources (fetched 13 Nov 2026)
- GitHub Docs, About push protection: https://docs.github.com/en/code-security/concepts/secret-security/about-push-protection
- HashiCorp Vault, Lease, renew, and revoke: https://developer.hashicorp.com/vault/docs/concepts/lease
- AWS Secrets Manager, What is AWS Secrets Manager?: https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html
- Microsoft Learn, About Azure Key Vault: https://learn.microsoft.com/azure/key-vault/general/overview
- Google Cloud, Secret Manager overview: https://docs.cloud.google.com/secret-manager/docs/overview
- TruffleHog README (via ecosyste.ms): https://awesome.ecosyste.ms/projects/github.com%2Ftrufflesecurity%2Ftrufflehog
- detect-secrets 1.5.0 (Yelp), installed from PyPI; output produced 13 Nov 2026