vuln-scanner

Files (2)

• SKILL.md
• riva.md

SKILL.md (first lines)

<!-- autoresearch: variation B — responsible-disclosure-first: private reports for code vulns, public PRs only for already-disclosed dep CVEs -->

> **${var}** — Action selector, shaped `[<action>][:<owner/repo>]`. Empty or a bare `owner/repo` → **scan** arm (audit that repo, or auto-select a trending one). `resubmit` / `resubmit:owner/repo` → **re-submit** arm (probe the security watchlist for repos that just enabled PVR and submit any queued advisory). `disclose` / `email` → **disclose** arm (queue armed out-of-band email disclosures for sending). Examples:
> - `` → scan, auto-select from trending
> - `openai/whisper` → scan `openai/whisper`
> - `resubmit` → probe the whole watchlist and re-submit what flipped
> - `resubmit:vercel/next.js` → probe just that repo (one-off)
> - `disclose` (alias `email`) → arm & queue eligible disclosure emails
> - `poc-smoke` → exercise the PoC gate against a benign real Base fork (no audit or disclosure)
> - `riva:owner/repo` → scan with the Riva research kernel (shadow/proposal only)

Today is ${today}. Read `memory/MEMORY.md` and the last 30 days of `memory/logs/` before starting.

## Why this skill exists

This is the **write / action arm of the vuln-disclosure loop** — one skill covering the full responsible-disclosure lifecycle:

- **Scan** — a security scanner that dumps unpatched vulnerabilities into public PRs is a zero-day publisher, not a helper. This skill matches industry practice: **Private Vulnerability Reporting (PVR) for code flaws, public PRs only for dependency CVEs that are already public**. Bad disclosure burns credibility and puts users at risk.
- **Re-submit** — when a scan finds a HIGH/CRITICAL issue in a repo with no PVR, no `SECURITY.md`, and no reachable contact, it has no safe channel — so it logs the finding as `"channel": "skipped"` in `memory/vuln-scanned.json` and stages a watchlist row. Without a weekly probe those findings silently age until the responsible-disclosure window closes. The re-submit arm closes that loop.
- **Disclose** — when the only responsible path is a private email to the maintainer, drafts sit in `memory/pending-disclosures/` with `status: pending-operator-send`, waiting for a human. The disclose arm finds drafts **explicitly armed for auto-send**, composes the email, and **sends it in-run** (Resend via `./secretcurl`) behind a set of fail-closed caps — the send is the arm's final action.

## Dispatch — parse `${var}`, then run one arm

Parse the selector once, in your head rather than in a shell script (a `case` block or an `X=...` assignment is refused; see **Shell shape** in the Network note), then jump to the matching arm below:

- `SEL` = `${var}`, the raw selector. `ACTION` = the token before the first `:` (or the whole thing). `TARGET` = the token after the first `:` (empty if there is no `:`).
- Map `ACTION` to an arm, first match wins:

  | ACTION | ARM | Also |
  |---|---|---|
  | `resubmit`, `watchlist`, `pvr` | `resubmit` (→ Arm B) | |
  | `disclose`, `email` | `disclose` (→ Arm C) | |
  | `poc-smoke`, `verify-gate` | `poc-smoke` (→ Arm D) | |
  | `riva`, `research` | `scan` (→ Arm A, Riva kernel) | `KERNEL=riva` |
  | `shadow`, `compare` | `scan` (→ Arm A, private comparison) | `KERNEL=shadow` |
  | empty, `scan` | `scan` (→ Arm A, auto-select if TARGET empty) | |
  | contains a `/` (bare owner/repo) | `scan` (scan that repo) | `TARGET` = the whole `SEL` |
  | anything else | `scan` (unknown → default to scan) | |

- Legacy remains the safe default while Riva is evaluated. `shadow` produces a private comparison artifact; only an explicit `riva` selector or a reviewed environment override selects it for a scan. Neither mode changes disclosure authority or bypasses A4/A4.5. So when the table set no `KERNEL`, read the environment override with one call:
  ```bash
  echo "kernel=${VULN_RESEARCH_KERNEL:-legacy}"
  ```
  `KERNEL` = what it printed. Any value other than `legacy`, `shadow` or `riva` becomes `legacy`.

- `ARM=scan` → **Arm A — SCAN** (target = `$TARGET`, or auto-select if empty).
- `ARM=resubmit` → **Arm B — RE-SUBMIT** (probe `$TARGET` if set, else the whole watchlist).
- `ARM=disclose` → **Arm C — DISCLOSE** (queue armed email drafts).
- `ARM=poc-smoke` → **Arm D — PoC GATE SMOKE** (benign live-fork verification only).

Each arm is independently executable. The operational arms share the same GitHub token and the same `memory/` state (`vuln-scanned.json`, `security-watchlist.md`, `pending-disclosures/`, `email-log.json`) — that shared state is exactly how the arms hand off to each other. The smoke arm does not read or modify that state.

---

## Arm A — SCAN

Find one trending repo, run purpose-built scanners (not raw grep), triage to real exploitable findings, and route each finding to the correct disclosure channel — PVR, `SECURITY.md` contact, or dependency-bump PR.

### A1. Pick a target

If `TARGET` is set, use it. Otherwise, one Bash call per step:

1. **Prefer chained output from the github-trending skill.** Check `output/.chains/github-trending.md` with Glob. If it is there and not empty, pull the link candidates:
   ```bash
   grep -oE '\[[^]]+/[^]]+\]\(https?://[^)]+\)|https?://github\.com/[^/ )]+/[^/ )]+' output/.chains/github-trending.md
   ```
   Parse owner/repo targets from what it printed (yourself; `sed` is not an allowed command). Accept BOTH the markdown form [owner/repo](url) and a bare github.com/owner/repo permalink (a feeder degraded under read-only can emit the latter). For each match, take the path after `github.com/` when the match has one, else the `[...]` text; keep only clean `owner/repo` values (exactly one `/`, no spaces) and dedupe them. A repo name with no owner is NOT a candidate. These are CANDS; pick the first CANDS entry that matches the criteria below.
2. **If the feed was absent OR present-but-unparseable** (zero owner/repo lines, e.g. a header-only / prose-only notify body), do NOT stop here - that starves the scan:
   - `KERNEL=shadow`: shadow runs have no GitHub credentials by design. A bare shadow selector may consume the chained trending output above, but otherwise must fail closed and be retried as shadow:owner/repo. Record `VULN_SCANNER_SKIPPED shadow-target-required: use shadow:owner/repo or provide github-trending chain output` and stop.
   - Otherwise get the cutoff date:
     ```bash
     date -u -d '14 days ago' +%Y-%m-%d
     ```
     It prints SINCE. Then search, SINCE written in literally:
     ```bash
     gh api "search/repositories?q=created:><SINCE>&sort=stars&order=desc&per_page=25" \
       --jq '.items[] | select(.fork==false) | select(.stargazers_count>=50) | {full_name, language, description, security_and_analysis}'
     ```

Selection criteria:
- Language you can reason about (JS/TS, Python, Go, Rust, Solidity)
- ≥50 stars, not a fork, active in last 6 months
- Handles untrusted input: auth, crypto, network, file I/O, templating
- **Skip** if scanned in last 30 days (grep `memory/logs/` for the repo name)
- **Skip** deliberately vulnerable teaching repos (DVWA, juice-shop, webgoat, vulnerable-*, *-ctf, hackme-*)
- **Skip** repos with no `SECURITY.md` AND `security_and_analysis.private_vulnerability_reporting.status != "enabled"` — you have no safe channel to report code flaws (you can still run a dep-scan and skip code audit; see step A5)

### A2. Fork and clone

`REPO` = the chosen `owner/repo`, written into each command literally. One call, by kernel:

- `KERNEL=shadow`:
  ```bash
  git clone --depth 200 --quiet "https://github.com/<REPO>.git"
  ```
- Otherwise:
  ```bash
  gh repo fork "<REPO>" --clone --default-branch-only -- --depth 200 --quiet
  ```

Then step into the clone, its own call (NAME = the repo part of REPO, after the `/`):
```bash
cd <NAME>
```

### A3. Run purpose-built scanners

Raw grep produces too many false positives. Use tools with dataflow reachability and verified-secret matching.

The workflow step `scripts/stage-vuln-scanner.sh` stages the scanners into `/tmp/bin`
before the run starts: the Go binaries (osv-scanner, trufflehog) are pinned release
assets checked against their sha256 digests, and semgrep/slither come from pip. In-run,
only `python3 -m pip install …` is used, as a fallback for the Python tools (semgrep,
slither); never download a scanner binary in-run. Put `/tmp/bin` on `PATH` and invoke
each tool by **bare name** — the bare names (`semgrep`, `trufflehog`,
`osv-scanner`, `slither`) are exactly what the capability allowlist
(`scripts/skill_mode.sh`) grants, so `claude -p` is permitted to execute them. If
a binary is missing, log `VULN_SCANNER_SKIPPED` and continue (it records `fail`
in `sources.txt` below) — never abort the whole run for one tool.

From aeonfun/aeon, MIT.

More from aeonfun/aeon