Skip to content

SOP-084 — Secrets hygiene, dependency scan & PR security review

Guide

<!-- last-reviewed: 2026-06-01 · owner: Security & Privacy (Security Analyst) -->

SOP-084 — Secrets hygiene, dependency scan & PR security review

SOP · owner: Security & Privacy (Security Analyst). Layer: SOP/Runbook (docs/canon.md). The operational-security procedure, three modes: (a) secrets hygiene, (b) dependency CVE audit, © PR/diff security review. One SOP with branches beats three near-duplicates (GR-4). Policy frame: hr/policies/security.md, SOP-004.

Interface Contract

  • Inputs: Engineering PR / diff to review ← from <Engineering Director / Staff Engineer> · trigger: review requested
  • Inputs: dependency added/removed/changed → CVE re-scan ← from <Engineering Director> · trigger: dependency changed
  • Outputs: severity-ranked finding report → to Archivist · trigger: artifact approved
  • Outputs: PR security verdict (pass / blocking findings) → to Engineering Director · trigger: review passed
  • Outputs: finding needing a policy call → to Security Director · trigger: review requested
  • Handoff trigger (in): a scheduled sweep is due, a dependency changed fires, or an Engineering PR is handed for review
  • Handoff trigger (out): the scan/review is complete, every finding is severity-ranked with a remediation path, and the report is archived
  • Definition of Done before handoff:
    • [ ] The verdict is explicit — clean scans reported as clean, never omitted
    • [ ] Every finding: severity (Critical/High/Medium/Low) · file:line · issue · remediation
    • [ ] Critical findings surfaced immediately (not held for the report cycle)
    • [ ] Policy calls escalated to the Security Director with a recommendation (not decided here)
    • [ ] Finding report handed to the Archivist (artifact approved); 0 drift
    • [ ] Learnings captured to docs/knowledge/security/ if any

Triggers are drawn verbatim from docs/handoff-triggers.md (review requested, dependency changed, artifact approved, review passed). The Analyst→Director escalation reuses review requested (a finding handed for a policy call) — a distinct finding escalated phrase is proposed to Operations (below) if the reconciler needs it; until then this edge reads pending.

Purpose

Catch secrets where they should not be, keep dependencies free of known CVEs, and stop the bug classes that create real risk (injection, broken auth, insecure defaults) before they merge — reporting negatives as negatives so a clean result is a fact, not silence.

When to use

A scheduled secrets/dependency sweep; a dependency changed event from Engineering; an Engineering PR/diff handed for security review.

Flow

flowchart LR
  T{"Mode"} -->|secrets| S["grep + git ls-files<br/>+ .gitignore"]
  T -->|deps| D["npm audit<br/>triage severity"]
  T -->|PR| P["read full diff<br/>injection/auth/defaults"]
  S --> R["severity-ranked<br/>finding report"]
  D --> R
  P --> R
  R --> A["Archivist<br/>artifact approved"]
  R -->|policy call| E["Security Director"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class S,D,P,R,A,E s
  class T d

Text fallback: pick the mode (secrets / deps / PR) → run the matching scan → write a severity-ranked finding report → hand it to the Archivist (artifact approved); any finding needing a policy call escalates to the Security Director with a recommendation.

Steps — mode (a): secrets hygiene

  1. Grep for patterns — API-key prefixes (sk-…), Bearer …, AKIA…, PEM headers (-----BEGIN), connection strings, base64 blobs in source.
  2. Check .gitignore — .env, .env.*, *.pem, *.key listed; git ls-files shows no secret tracked (only .env.example is acceptable — confirmed clean 2026-06-01).
  3. Enumerate credential files — *.pem, *.key, *.p12, *.pfx, credentials.*.
  4. Spot-check history — git log --all --oneline on commits touching .env*/config.
  5. Report — file:line · pattern · severity · action. A live secret in a tracked file is Critical → surface immediately; revoke + rotate per SOP-004 (do not just delete the commit).

Steps — mode (b): dependency audit

  1. cd intranet && npm audit --json; parse output.
  2. Triage: Critical/High → immediate upgrade recommendation; Moderate → sprint-level; Low → noted, non-blocking.
  3. For each High/Critical: patched version, no breaking API change, exact npm install.
  4. Hand remediation to the Engineering Director; report all findings.

Steps — mode ©: PR / diff security review

  1. Read the full diff before forming an opinion (Read + Grep).
  2. Check — unsanitized input → HTML (XSS); string interpolation into shell (command injection); user-built file paths (path traversal); missing auth guards on new routes; hardcoded credentials; eval/exec/child_process misuse; swallowed error paths (e.g. the H2 app_uninstalled catch returning 200 — slack/events.ts:301-308).
  3. Per finding — quote the line(s), name the vuln class, one-sentence attack scenario, concrete fix. If clean, say “No security issues found in this diff” explicitly.
  4. Verdict — review passed to Engineering, or blocking findings with remediation.

Live review on the books — H2

When the H2 fix PR lands (intranet/src/pages/api/slack/events.ts), the Analyst is the review eyes: acceptance criterion — the app_uninstalled deletion failure no longer returns a silent 200 (it surfaces/alerts). Confirm the cleanup-check 500 path logs row counts only, not contents (Phase 0 A4). The fix is Engineering’s; the risk record is the Director’s (SOP-083).

Roles / approvers

Run by the Security Analyst. Policy calls → Security Director. Code fixes → Engineering. CI scanning steps → proposed to the Process Engineer (not built here).

Proposed triggers (to Operations, not invented inline)

  • finding escalated (Security Analyst → Security Director) — a finding handed up for a policy call. Until registered, reuse review requested; edge reads pending. Request via interface-contract-spec.md §1.2.

Guardrails

  • Report negatives — clean is reported as clean, never omitted.
  • Do not decide policy — escalate to the Director with a recommendation.
  • Do not write the fix — route to Engineering; verify, don’t author.
  • Do not edit CI config — recommend the scan step to the Process Engineer.
  • Personal information is PA-only — never access it; route through the PA.

Job aid: ✓ docs/units/security-privacy/job-aids/secrets-scan-and-pr-review.md. See also: docs/units/security-privacy/manuals/security-analyst.md · SOP-004 · SOP-083 · hr/policies/security.md · reports/phase0-reviews/security-analyst-codebase-review.md.