Skip to main content

Secrets, Dependencies, and Supply Chain

What This Concept Is​

Three adjacent security problems that share one failure mode -- "we trusted something we did not verify":

  • Secrets: credentials, API keys, signing keys, tokens. The question is where they live, who can read them, how they are rotated, and what happens when they leak.
  • Dependencies: the libraries you pull from package managers. The question is what you depend on, which version, whether it is still maintained, and whether its known CVEs affect you.
  • Supply chain: the pipeline from source code to running artifact. The question is who can inject code, whether the artifact you run is the artifact you built, and how you would prove that to an auditor.

For a capstone, you do not need enterprise tooling. You need a policy on one page and the minimal plumbing to uphold it. The SLSA framework gives you the vocabulary (Build L0 through L3); OWASP Top 10 (A06: Vulnerable and Outdated Components, A08: Software and Data Integrity Failures) and the NIST Cybersecurity Framework's Protect function give you the outcomes to justify each control to an examiner.

The three problems are adjacent because a compromise of any one gives the attacker the others. A leaked CI token (secret) lets an attacker push a malicious dependency (supply chain) that reads production secrets (secret) and exfiltrates data. You have to harden all three or you have hardened none.

Why It Matters Here (In the Capstone)​

These three are the most common way small systems get breached, and the breaches tend to be the boring kind -- leaked keys on GitHub, an abandoned dependency with an unpatched CVE, or a compromised build step. Your capstone will be examined, and "I was going to set this up" is not a defense. The PRR has three rows -- items 9, 10, and 11 of concept 15 -- that point directly at this concept.

The high-profile supply-chain incidents of the last five years (SolarWinds, event-stream, colors/faker, xz-utils) all affected projects smaller than your capstone. Tamper-evident builds and signed provenance are increasingly the baseline, not the luxury.

Concrete Example(s) -- from a real capstone​

One-page policy for the webhook-handler capstone. File this at library/raw/security-policy.md.

Secrets​

  • Storage: AWS Secrets Manager (or GCP Secret Manager / HashiCorp Vault). No secrets in environment variables at rest, no secrets in the repo.
  • Injection: runtime fetches secrets via instance role at startup; secrets never appear in logs, CI output, or error messages. A logger middleware scrubs Authorization and any header matching *secret* / *token*.
  • Rotation: provider webhook secret rotated every 90 days; database password rotated every 30 days; all service-to-service tokens rotated on every deploy (short-lived OIDC tokens, not static).
  • Leak response: library/raw/runbooks/leaked-secret.md covers: revoke in provider console, rotate in Secrets Manager, redeploy, run git rev-list --all | xargs git grep <fragment> to confirm clean history, file incident.
  • Detection: pre-commit hook runs gitleaks; CI runs trufflehog on every PR; GitHub secret scanning enabled on the repo.

Dependencies​

  • Source of truth: requirements.txt with pinned versions and hashes (--require-hashes), committed to the repo.
  • Upgrade cadence: dependency updates reviewed weekly via Dependabot / Renovate PRs.
  • Vulnerability scanning: pip-audit (or npm audit / cargo audit) runs on every CI build; any HIGH / CRITICAL fails the build. The OWASP Top 10 A06 "Vulnerable and Outdated Components" item is exactly this control.
  • Transitive review: new direct dependency requires a one-line justification in library/raw/dependencies.md; transitives counted quarterly.
  • Maintenance signal: any dependency without a release in 24 months is flagged for replacement or fork.

Supply chain​

  • Build isolation: production artifacts built only in CI (hosted runners), never from a developer laptop.
  • Provenance: CI emits a signed attestation (cosign attest or GitHub Attestations) describing the source commit, the builder, and the inputs.
  • Admission: deploy step verifies the attestation before rollout. If verification fails, the deploy aborts.
  • Minimum viable SLSA level: aim for SLSA Build L2 (scripted builds, provenance generated, provenance authenticated by a hosted builder). L3+ (hardened builder with tamper-proof metadata) is out of scope for a solo capstone, but the L2 pattern is the ceiling you commit to.

That is the entire policy. Roughly forty lines, defensible to a senior engineer, and mapped to named frameworks (SLSA, OWASP Top 10, NIST CSF).

Incident scenario -- leaked API key (what library/raw/runbooks/leaked-secret.md actually looks like):

T+0     detect: gitleaks in CI or GitHub secret-scan alert
T+1m    revoke in provider console (Stripe/GitHub/etc.)
T+3m    rotate in Secrets Manager; redeploy services reading that secret
T+5m    verify old key is rejected; new key works (staging canary + one prod call)
T+10m   grep git history with BFG or `git rev-list --all | xargs git grep <fragment>`
T+15m   file incident in library/raw/postmortems/; notify any affected external party
T+24h   check logs for unauthorised activity using the leaked key between creation
        and revocation

That runbook, rehearsed once, is what separates a three-hour incident from a three-week one.

Common Confusion / Misconceptions​

"We use .env files; that's fine." A .env file on disk is a secret at rest that is not encrypted, not access-controlled, and tends to get git add-ed by accident. Moving to Secrets Manager + IAM role costs one afternoon and removes an entire category of incident.

"Our lock file pins versions, we are fine." Pinning is necessary, not sufficient. You still need scanning, a rotation cadence, and a human signal for unmaintained packages. A pinned-but-unpatched CVE is worse than an unpinned one because it feels "handled."

"Supply chain is for big companies." The biggest supply-chain incidents of the last five years (SolarWinds, event-stream, colors/faker, xz-utils) all affected projects smaller than your capstone. Tamper-evident builds and signed provenance are increasingly the baseline, not the luxury.

"Rotation is painful so we skip it." Rotation is painful because you skipped it. Build the rotation hook once, with a single command that does the full dance (generate new, update secret store, trigger redeploy, revoke old). Then use it.

How To Use It (In Your Capstone)​

  1. Write the one-page policy above, adapted to your stack and cloud.
  2. For each section, name the specific tool you will use and the cadence you will run it.
  3. Implement the minimum viable version of each: a secrets manager, a scanning CI step, and a signed-attestation build step.
  4. Add a "leaked secret" runbook before you need it. Rehearse it once in staging with a fake secret.
  5. Wire the SLSA attestation verification into the deploy pipeline: failed verification aborts the deploy.
  6. Put the policy link in the PRR checklist. At PRR time you read the policy, tool-by-tool, and confirm each is actually running.
  7. Re-read the policy quarterly. A policy without review dates is a policy that has already rotted.

See also (integrative)​

Check Yourself​

  1. Why is a pinned-but-unpatched dependency more dangerous in practice than an unpinned one?
  2. What is the minimum evidence that a build artifact is actually the one your CI produced?
  3. Describe, in under four bullets, what you would do in the first 15 minutes after discovering a committed API key.
  4. What is the difference between SLSA Build L1 and L2, stated in operational terms?
  5. Why does OWASP Top 10 A08 (Software and Data Integrity Failures) specifically call out CI/CD pipelines and dependency systems, and how does your policy cover it?
  6. Why is pre-commit gitleaks insufficient on its own, and what server-side control complements it?

Mini Drill or Application (Capstone-scoped)​

  1. In 90 minutes: audit your capstone for committed secrets -- run gitleaks detect and trufflehog filesystem . on the repo. Remediate anything found.
  2. Move every environment-variable secret in your deploy to Secrets Manager (or equivalent). Confirm the process can no longer see the secret value on disk.
  3. Add pip-audit / npm audit to CI with a HIGH-or-CRITICAL fail threshold.
  4. Enable build-provenance generation in CI (e.g., actions/attest-build-provenance) and verify the artifact at deploy time.
  5. Write and rehearse library/raw/runbooks/leaked-secret.md using a fake secret in staging. Measure end-to-end revoke-rotate-redeploy time -- aim for under 15 minutes.
  6. Commit the one-page policy as library/raw/security-policy.md. Link it from the PRR checklist (items 9, 10, 11).

Source Backbone​

Capstone operations applies security, reliability, and distributed-systems material. These books are the source backbone for readiness review.