Sensitive data element remediation skill

---
name: sde-remediation
description: |
  Remediate a sensitive-data-element (SDE) finding in the current
  working tree — hard-coded secrets, PII in logs, credentials in
  source. Replace the literal with a reference to the approved
  secret store, add a regression guard, and open a PR. If the SDE
  is already-exposed (in history, a public log, or a shipped
  artifact), stop and write TRIAGE.md with a rotation + disclosure
  checklist.
---

# Sensitive data element remediation

## Inputs

All inputs are optional. Infer first from session context — the
chat message / slash-command arguments, a linked GitHub issue or
scanner payload, the triggering push-protection block. When
nothing provides a finding and no scanner MCP is wired in,
discover candidate SDEs yourself using local tooling.

- `FINDING_ID`   — scanner id (e.g. `GITLEAKS-AWS-001`,
                   `WIZ-SECRET-42931`). If absent, synthesize a
                   local id after discovery (e.g. `LOCAL-GITLEAKS-<rule>-<sha>`).
- `FILE_PATH`    — take from the scanner payload or prompt body.
                   Otherwise produced by discovery.
- `LINE`         — same sources as `FILE_PATH`.
- `SDE_CLASS`    — one of `secret`, `pii`, `pci`, `phi`, `token`.
                   Take from the prompt body or the scanner's
                   rule id; otherwise classify from the
                   discovery output (AWS-access-key rule →
                   `secret`; Stripe-live-key → `secret`;
                   email-in-logs → `pii`; etc.).

## Discovery path (no finding provided)

When nothing is supplied and no scanner MCP is available:

1. Run the lightest-weight secret/PII scanner installed, in this
   order: `gitleaks detect --source . --no-banner`,
   `trufflehog filesystem . --json`,
   `detect-secrets scan --all-files`, `trivy fs --scanners secret .`
   as a multi-scanner fallback.
2. Restrict discovery to the working tree only — do NOT scan
   commit history. History-resident SDEs are a rotation
   problem, not a code-edit problem, and require a separate
   runbook.
3. Pick one high-confidence finding per run and proceed as if
   it had been supplied. Note in the PR body that it was
   self-discovered and which scanner produced it.
4. If no scanner is available, stop and write `TRIAGE.md`
   listing what to install (with a one-line justification per
   tool) so a human can wire it up.

Never grep for a secret literal yourself — leave pattern
matching to the scanner so the literal never enters your
reasoning trace.

## Procedure

1. **Confirm the finding is live in the working tree.**
   - Read `FILE_PATH:LINE`; if the literal value is not present,
     the finding may have been fixed already. Write `TRIAGE.md`
     with "not-reproduced" and stop.
   - Do **not** grep the commit history — that's the
     secret-rotation runbook's job.

2. **Classify the exposure scope.**
   - If the file is in a **public** repo, or has been pushed to a
     shared remote branch, OR the secret appears in CI logs: this
     is an **exposed** SDE. Skip to step 7.
   - Otherwise, this is a **pre-exposure** SDE and you may
     remediate in-place.

3. **Pick the replacement pattern from the allowlist.**
   - `secret` / `token` → read from the repo's approved secret
     store client. Consult `docs/security/secrets.md` for the
     project's chosen store; if absent, stop and triage.
   - `pii` / `pci` / `phi` → replace with a synthetic fixture in
     tests; in runtime code, route through the project's
     redaction helper (grep for `redact(`, `Redactor`, or
     `mask_pii`). If none exists, stop and triage — do not invent
     one.

4. **Apply the replacement.**
   - Minimal edit: remove the literal, insert the reference /
     redaction call, update the smallest surrounding context
     needed to compile.
   - Never rename files, never reformat unrelated code in the
     same commit.

5. **Add a regression guard.**
   - If the repo has `gitleaks` / `trufflehog` / `detect-secrets`
     config, add an allowlist entry **only for the
     synthetic-fixture path**, with a comment citing the finding
     id.
   - For code paths: add a unit test that asserts the offending
     value is no longer present (string match against the
     removed literal).

6. **Verify and open a PR.**
   - Run the project's lint + test commands.
   - Commit message: `fix(sec): remove <SDE_CLASS> <FINDING_ID>`.
   - PR title: `fix(sec): remove <SDE_CLASS> from <file>
     (<FINDING_ID>)`.
   - PR body:
     - Finding id.
     - **Rotation status:** "N/A — pre-exposure, no rotation
       required" (only for pre-exposure fixes; an exposed SDE
       never reaches this step).
     - Blast radius (files touched, callers changed).
   - Apply labels: `security`, `sde-remediation`.

7. **Exposed SDE — stop and triage.**
   - Write `TRIAGE.md` on a fresh branch `sde-triage/<FINDING_ID>`
     with:
     - Finding id, file, line.
     - **Rotation checklist** (tick each when done):
       - [ ] Revoke the credential at the issuer.
       - [ ] Rotate in the approved secret store.
       - [ ] Re-deploy consumers.
       - [ ] Invalidate any cached sessions / tokens.
     - **Disclosure checklist:**
       - [ ] File an incident in the IR tracker.
       - [ ] Notify the service owner.
       - [ ] Determine if a customer / regulator notification is
         required (route to legal).
     - Suggested next owner (team / on-call rotation).
   - Do **not** edit the offending file yet — rotation happens
     first.

## Guardrails

- **Never** edit git history from this skill. History rewrites
  require a documented runbook and a human.
- **Never** inline the replacement value you just retrieved from
  the secret store into a log line, an error message, or a
  comment.
- **Never** bypass a `PreToolUse` hook that blocks writing to
  secret-material paths — record the block in `TRIAGE.md` and
  stop.
- **Never** commit a `.env` or `credentials.json` file, even to
  remove it — those need `git filter-repo` treatment, not a
  normal commit.

## Outputs

- Success (pre-exposure): a pushed branch + opened PR, plus a
  passing regression-guard test.
- Exposed SDE: a triage branch with `TRIAGE.md`, zero code
  edits on the offending file.