immune-check

name

immune-check

description

A pre-flight reflex that scans any outbound artifact — a commit, a publish, a release, a message, a payload to an external service — for foreign or dangerous material before it crosses the boundary out of the body. Catches secrets, keys, tokens, credentials, personal/medical data, private paths, and oversized vendored deps. Wraps whatever secret scanner you have (Argus, gitleaks, trufflehog, detect-secrets, git-secrets) and falls back to a built-in pattern pass. TRIGGERS: 'immune check', 'scan before publish', 'is this safe to push', 'check this before it goes out', 'pre-flight scan', 'about to make this public', 'leak check', 'scan the diff'. Run before anything leaves the body: publishing a repo, pushing a commit, cutting a release, sending an artifact outward.

Immune Check — scan before anything leaves the body

A boundary defense. Before any artifact crosses out of the body — into a public repo, an external service, a release, someone else's inbox — this is the reflex that scans it for foreign or dangerous material, so an infection never spreads in the first place. It is far cheaper to never leak than to scrub a leak after the fact.

This is the immune organ of an agent's nervous system: it distinguishes self (safe to expose) from non-self (must not cross the membrane), responds proportionally, and remembers every antigen so the next scan is faster.

What counts as an outbound boundary

Any moment an artifact leaves your control and becomes hard to recall:

• Making a repo or file public (the highest-stakes membrane — public is forever, even after deletion).
• Pushing a commit, cutting a release, opening a PR to an upstream you don't own.
• Sending a payload to an external API, a webhook, a paste service, a third-party tool.
• Attaching files to a message going outside the trusted circle.

If it can be un-done with a local edit, it's still inside the body — no scan needed. If recalling it means asking someone else to forget, scan first.

Stack-agnostic by design

The scan adapts to whatever you have. Detect a scanner in this order and use the first available; if none, fall back to the built-in pattern pass:

1. Argus — argus on PATH (the reference organ this skill was modeled on).
2. gitleaks — gitleaks detect/gitleaks dir.
3. trufflehog — trufflehog filesystem/git.
4. detect-secrets — detect-secrets scan.
5. git-secrets — git secrets --scan.
6. Built-in fallback — a grep/ripgrep pass over the diff for the antigen patterns below. Always available, no install.

Report which scanner ran, so the user knows the depth of coverage.

The reflex

1. Define the boundary (self vs non-self)

State, in one line: what is about to leave and to where. "Making ~/Foo public on GitHub." "Pushing 3 commits to an upstream fork." "Sending report.json to a Slack channel." The destination sets the stakes — a public repo is maximal, an internal push is lower. Confirm the membrane before scanning.

2. Recognize antigens (scan)

Run the detected scanner over exactly what crosses — the diff being pushed, the files being published, the payload being sent (not the whole working tree if only part leaves). The antigen classes, whatever the tool:

• Secrets / keys / tokens — API keys, OAuth tokens, private keys (-----BEGIN ... PRIVATE KEY-----), .env contents, cloud credentials, connection strings with passwords.
• Credentials — hardcoded passwords, basic-auth URLs, session cookies.
• Personal / medical data (PII / PHI) — real names, emails, phone numbers, addresses, health/medical records, IDs. (This class is why the skill exists — a real medical-data leak to a public repo is the scar behind it.)
• Private identity / paths — internal hostnames, absolute home paths revealing a username, internal URLs, ticket/customer identifiers.
• Oversized / vendored material — node_modules, build artifacts, large binaries, committed dependency trees that bloat and may carry their own secrets.

3. Triage the response (don't be autoimmune)

Classify every finding — overreaction is also a failure mode; an immune system that blocks everything kills the host:

• Pathogen → a real secret, live credential, or real PII. Block. The outbound action does not proceed.
• Allergen → looks dangerous but may be benign (an example key, a test fixture, a placeholder). Pause and confirm with the human — never auto-clear, never auto-block.
• Self → confirmed false positive (a public key, a hash, a documented sample). Pass, and record it (step 5) so it stops tripping the alarm.

4. Quarantine / remediate

For pathogens:

• Stop the outbound action first — before any cleanup.
• Remove or redact the material from the artifact.
• If it was already committed, scrubbing the working copy is not enough — the history carries it. Rewrite history (e.g. git filter-repo) or, if already pushed/public, treat the secret as compromised.
• Rotate any live secret that crossed or may have crossed. Exposure already happened the moment it left; removal hides it, rotation neutralizes it.

5. Immune memory (adaptive immunity)

Every real encounter should make the next scan smarter. After triage:

• Allowlist confirmed false positives so they stop tripping (the scanner's ignore file, or a noted exception).
• Add a pattern for any antigen the scanner missed.
• Record the incident — if a pathogen got close, write a durable note (a feedback memory if you keep one): what leaked, how it nearly crossed, what now guards it. This is the antibody.

6. Clear or block (report)

Report a verdict:

• CLEAR ✅ — scanner used, what was scanned, nothing pathogenic. Safe to cross.
• BLOCKED 🛑 — the pathogen(s), where (file:line), and the exact remediation. The outbound action must not proceed until resolved.
• HOLD ⏸️ — allergens needing a human call, listed with the question for each.

Principles

• Scan before the membrane, not after. Public is forever; recall means asking others to forget. Cheaper to never leak.
• Tune for the pathogen, not paranoia. Blocking everything is autoimmune — it kills throughput and trains people to bypass the check.
• Adaptive immunity. Every real hit teaches the next scan: allowlist self, add missed patterns, record the incident.
• Rotate, don't just delete, live secrets. The moment it crossed, exposure happened. Removal hides; rotation neutralizes.
• Scan what crosses, not the whole body. The diff, the payload, the published subset — proportional to what actually leaves.
• Stack-agnostic. Whatever scanner you have, the antigen classes are universal; the built-in pass means there's never an excuse to skip the check.