Onboarding + make M15 gate catch the plant + M17 override (#6,#17,#18,#19,#29) (#58)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>

modules/15-security-scanning/README.md

@@ -287,9 +287,14 @@ that key had been real and ever pushed, removing it now is not enough; you'd hav
 because it's in history. (Proper secret management is Module 17; this is just the catch.)
 
 > **Stretch — Gate 3 (SAST):** install a static analyzer for your language (for Python,
-> `pip install bandit`, then `bandit -r .`) and see it flag insecure patterns — including, often, the
-> very hardcoded secret from Part C, from a different angle. Note how much noisier it is than the
-> first two gates. That noise is why it's the one you tune.
+> `pip install bandit`, then `bandit -r .`) and watch it flag insecure *code you wrote* — here, the
+> MD5-based request signing in `config.py` (weak crypto, CWE-327). Now note what it does **not**
+> flag: the hardcoded `SYNC_API_KEY`. Bandit's hardcoded-credential checks (B105–107) key on
+> *password-named* identifiers — `password`, `secret`, `token` — so a key named `SYNC_API_KEY` slips
+> right past them. Catching that string is a secret scanner's job (Gate 2), not SAST's. Same file,
+> two distinct flaws, caught by two different gates with two different blind spots — which is exactly
+> why you run all three rather than trusting one. And note how much noisier SAST is than the first
+> two gates: that noise is why it's the one you tune.
 
 ### Part D — Wire the gates into CI
 
@@ -298,13 +303,32 @@ runs on every push and blocks the merge.
 
 1. Copy `lab/security-scan.sh` into your project. It runs the SCA and secret-scan gates and **exits
    non-zero on any finding** — which is what makes CI go red. Make it executable
-   (`chmod +x security-scan.sh`) and run it locally first:
+   (`chmod +x security-scan.sh`).
+
+   Before you run it, **stage the starter files** so the secret gate can see them:
+
+   ```bash
+   git add config.py requirements.txt
+   ```
+
+   This is not a footnote. `detect-secrets scan` with no path argument scans the files Git
+   *tracks* — an *untracked* `config.py` is invisible to it, so the gate would report "no secrets"
+   on a file that's full of them (a silent false pass, the worst kind). Staging puts the file in
+   front of the scanner. It's the same reason the explicit `detect-secrets scan config.py` in
+   Part C worked, and the same reason "secrets live in history": the moment Git knows about a file,
+   so does the gate.
+
+   To watch the gate catch both planted problems at once, restore the original booby-trapped files
+   first (you fixed them in Parts B and C) — re-copy `config.py` and `requirements.txt` from this
+   module's starter, re-stage, then run:
 
    ```bash
    ./security-scan.sh
    ```
 
-   With the bad starter files in place it should fail. With your Part B/C fixes applied, it should
+   It should **fail on both gates** — the SCA gate on the unresolvable/vulnerable dependencies and
+   the secret gate on the hardcoded key — and you should be able to point at which finding caused
+   each non-zero exit. Re-apply your Part B/C fixes (and re-stage), run it once more, and it should
    pass.
 
 2. Add a security step to your pipeline that calls it. `lab/ci-security.yml` is a provider-neutral

modules/15-security-scanning/lab/config.py

@@ -1,15 +1,18 @@
 """Cloud-sync config for tasks-app — a realistic snapshot of what an AI hands you.
 
 Asked to "sync tasks to a cloud service," a model will cheerfully produce something like this: it
-works, it reads naturally, it passes lint and tests... and it has a live credential baked straight
-into the source. That is the *exact* failure mode Module 15's secret-scanning gate exists to catch.
+works, it reads naturally, it passes lint and tests... and it carries two planted flaws — a live
+credential baked straight into the source (caught by Gate 2, secret scanning) and a weak-crypto
+"signature" using MD5 (caught by Gate 3, SAST). Two different gates, two different blind spots.
 
-DO NOT copy this pattern. The point of this file is to be caught by a scanner, not imitated.
+DO NOT copy these patterns. The point of this file is to be caught by a scanner, not imitated.
 The fix (read from the environment) is shown at the bottom, commented out, so you can see the
 difference once Part C of the lab is done.
 """
 
-# --- The problem the scanner should flag -------------------------------------------------------
+import hashlib
+
+# --- The problem the SECRET scanner should flag (Gate 2) ---------------------------------------
 # A hardcoded API key. Looks like a normal string literal; lint and tests will never complain.
 SYNC_API_KEY = "sk_live_9c3f2a7b41d84e0fa6b2c5d8e1f09a73bdac46"
 SYNC_ENDPOINT = "https://api.example-task-cloud.com/v1/sync"
@@ -19,6 +22,14 @@ def sync_headers() -> dict:
     return {"Authorization": f"Bearer {SYNC_API_KEY}"}
 
 
+# --- The problem the SAST scanner should flag (Gate 3) -----------------------------------------
+# AI-classic: "sign" the request body with a quick hash. MD5 is broken for anything
+# security-relevant — a textbook weak-crypto idiom. A secret scanner won't catch this (it's not a
+# secret); a SAST tool like bandit will (it's insecure code you wrote). DO NOT imitate.
+def sign_payload(body: str) -> str:
+    return hashlib.md5(body.encode()).hexdigest()
+
+
 # --- The fix (Part C) --------------------------------------------------------------------------
 # Read the secret from the environment instead of committing it. Proper secret management — env
 # files, secret stores, per-environment config — is Module 17. This is just enough to make the

modules/15-security-scanning/lab/security-scan.sh

@@ -14,6 +14,13 @@
 
 set -u  # treat unset vars as errors; we manage exit codes explicitly below.
 
+# A security gate must fail CLOSED. If the interpreter the secret gate needs isn't here, abort with a
+# non-zero exit rather than sailing past the check and reporting a false "passed".
+command -v python3 >/dev/null 2>&1 || {
+  echo ">> python3 is required for the secret gate but was not found. Aborting." >&2
+  exit 2
+}
+
 status=0
 
 echo "=== Gate 1: SCA / dependency scan (pip-audit) ==="
@@ -28,16 +35,33 @@ fi
 
 echo
 echo "=== Gate 2: secret scan (detect-secrets) ==="
-# detect-secrets prints a JSON report of any secrets it finds. We treat a non-empty results set as a
-# failure. `python -c` keeps this portable (no jq dependency).
+# detect-secrets prints a JSON report of any secrets it finds. NOTE: with no path it scans the files
+# git TRACKS, so stage the starter files (`git add`) before running this, or an untracked file is
+# invisible to the gate. We parse the JSON with `python3` (no jq dependency) and fail CLOSED: the
+# parser returns 0=secrets found, 1=clean, anything else=couldn't tell — and "couldn't tell" must
+# count as a failure, never a silent pass.
 report="$(detect-secrets scan)"
-if printf '%s' "$report" | python -c 'import sys, json; sys.exit(0 if json.load(sys.stdin).get("results") else 1)'; then
-  echo "$report"
-  echo ">> SECRET gate FAILED: a credential was detected in the tree. See report above." >&2
-  status=1
-else
-  echo "no secrets detected."
-fi
+printf '%s' "$report" | python3 -c 'import sys, json
+try:
+    found = bool(json.load(sys.stdin).get("results"))
+except Exception:
+    sys.exit(2)
+sys.exit(0 if found else 1)'
+secret_rc=$?
+case "$secret_rc" in
+  0)
+    echo "$report"
+    echo ">> SECRET gate FAILED: a credential was detected in the tree. See report above." >&2
+    status=1
+    ;;
+  1)
+    echo "no secrets detected."
+    ;;
+  *)
+    echo ">> SECRET gate ERROR: could not parse the scan output (exit $secret_rc). Failing closed." >&2
+    status=1
+    ;;
+esac
 
 echo
 if [ "$status" -ne 0 ]; then