Elizabeth W
54 lines
4.8 KiB
Markdown
54 lines
4.8 KiB
Markdown
# Architecture Decision Record: Secret Scanning Strategy
|
|
**Date:** April 16, 2026
|
|
**Status:** Accepted
|
|
**Decision:** Implement a dual-layer secret scanning approach using both **Gitleaks** (locally via pre-commit) and **TruffleHog OSS** (in CI/CD via GitHub Actions).
|
|
|
|
### Context & Background
|
|
For solo personal projects, a complex CI/CD security pipeline is usually overkill. Initially, the plan was to rely solely on developer discipline to avoid committing secrets. However, the introduction of **AI coding agents** into the workflow fundamentally changes the threat model. AI agents can write code, hallucinate credentials, and potentially push commits that bypass local development environments entirely. A formal, automated mechanism is required to prevent live secrets from entering the repository and remaining in the Git history.
|
|
|
|
---
|
|
|
|
### Considered Alternatives & Rejected Options
|
|
|
|
#### 1. Rejected: Relying Solely on "Being Careful" (Do Nothing)
|
|
* **Description:** Assume the sole developer and AI agents will perfectly manage `.gitignore` files and environment variables.
|
|
* **Reason for Rejection:** Humans make mistakes, especially when tired. More importantly, AI agents are unpredictable and do not have intrinsic context regarding which strings are sensitive live keys versus dummy data. The risk of a "financially fatal" leak (e.g., AWS root keys) is too high to rely purely on diligence.
|
|
|
|
#### 2. Rejected: Only Using Gitleaks (Local Pre-commit Hook Only)
|
|
* **Description:** Install Gitleaks locally to block secrets before they are committed.
|
|
* **Reason for Rejection:**
|
|
* **The AI Blindspot:** AI agents pushing code via API or operating in remote cloud environments do not trigger local pre-commit hooks.
|
|
* **Bypassable:** Human developers can bypass local hooks with `git commit --no-verify`.
|
|
* **No active verification:** Gitleaks cannot tell if a matching regex is a live, dangerous key or a dead, revoked key.
|
|
|
|
#### 3. Rejected: Only Using TruffleHog in CI/CD (No Local Scanning)
|
|
* **Description:** Skip the local pre-commit hook and just let TruffleHog catch secrets after they are pushed to GitHub.
|
|
* **Reason for Rejection:** Once a secret is pushed to GitHub, it is permanently embedded in the Git history. Even if TruffleHog catches it immediately and fails the pipeline, the developer must now undertake the tedious and risky process of rewriting the Git commit history (e.g., using `git filter-repo`) or completely rotating the live credential. Blocking the secret *before* the commit is vastly superior for developer experience.
|
|
|
|
#### 4. Rejected: Paid/Commercial Scanners (GitHub Advanced Security, Snyk, etc.)
|
|
* **Description:** Use enterprise-grade platforms to scan the repository.
|
|
* **Reason for Rejection:** This is a personal project. Commercial tools introduce unnecessary financial costs, whereas the open-source versions of Gitleaks and TruffleHog provide enterprise-grade capabilities for free.
|
|
|
|
---
|
|
|
|
### The Chosen Solution: Dual-Layer Approach
|
|
|
|
#### Layer 1: Gitleaks (The Local Guard)
|
|
* **Where:** Local developer machine (Pre-commit Hook).
|
|
* **Why:** Uses fast, static regex matching. Runs in milliseconds and acts as a "spell-check for secrets," preventing the human developer from accidentally embedding secrets into the local Git history.
|
|
|
|
#### Layer 2: TruffleHog (The CI/CD Safety Net)
|
|
* **Where:** GitHub Actions / CI Pipeline (Post-commit).
|
|
* **Why:** Uses active verification. If a secret slips past (via an AI agent pushing directly or a bypassed local hook), TruffleHog actively calls out to external APIs to verify if the key is live. By using the `--only-verified` flag, it guarantees zero false positives and only fails the pipeline if it proves a key is an active threat.
|
|
|
|
---
|
|
|
|
### Tradeoffs & Accepted Risks
|
|
|
|
By choosing this dual-layer architecture, we are accepting the following tradeoffs:
|
|
|
|
1. **Pipeline Overhead:** Adding TruffleHog to the CI/CD pipeline adds approximately 10 to 30 seconds to the build time. We accept this minor delay in exchange for the security guarantee.
|
|
2. **Tool Sprawl/Maintenance:** We are maintaining two separate tools rather than one. However, since both tools are relatively "set it and forget it," the maintenance burden is negligible.
|
|
3. **Local Developer Friction:** Gitleaks is "noisy" and relies strictly on regex. It may occasionally block a local commit because a dummy test string looks like a secret. The developer will occasionally need to update a `.gitleaksignore` file or manually bypass the hook.
|
|
4. **Blindspots with `--only-verified`:** Because we are configuring TruffleHog in CI/CD to only alert on *verified* secrets (to avoid pipeline noise), if an AI agent leaks an internal/custom secret that TruffleHog doesn't know how to verify via an API call, the pipeline will pass. We accept this risk, relying on local Gitleaks regexes as the primary defense for custom/unverifiable secrets.
|