cve-delta scan

Supports Ubuntu 22.04 and 24.04. Debian 12 is experimental.

Your job is to turn "the scanner found 800 CVEs" into "do these 3 things today, run one apt upgrade for the rest, and ignore these, here is why". Every run, including the first, must end with a short, ranked, actionable report.

Rules

• Read-only. Inventory and analysis only. Never run upgrades, restarts, or config changes. Fix commands go into the report for the user to run.
• Ask before connecting if the user didn't name the target. The scan command isn't pre-approved on purpose, so the user also approves it once with the target visible.
• Deterministic matching. Decide "affected or not" from advisory data (OSV, distro security trackers), never from web search results. Web search may add context to a finding that has already been matched.
• Distro-aware versions. Debian and Ubuntu backport fixes into old upstream versions. Compare against the distro's fixed version (1.2.3-4+deb12u2), not NVD's upstream range.
• No secrets in output. The inventory never includes environment variables, file contents, or process arguments.

Steps

1. Confirm the target

The target is $ARGUMENTS, or the local machine (local) if empty. If the user named it in this request, that's your confirmation. Otherwise ask before connecting.

2. Scan

Run this one command. It is read-only on the target. Always run it in the background: a first scan takes a few minutes while advisory data is cached, and later ones are faster. Tell the user that, and wait for it to finish.

bash ${CLAUDE_SKILL_DIR}/scripts/scan.sh <target> --data ${CLAUDE_PLUGIN_DATA}

Don't run the individual scripts yourself, and don't wrap the command in mkdir, &&, variables or redirects: a single plain command is what the user can approve once and trust. It writes cve-report-<target>-<date>.md in the current directory, and intermediate files under ${CLAUDE_PLUGIN_DATA}/hosts/<target>/, including a small snapshot per scan under history/. From the second scan of a host on, the report opens with "Since the last scan". Its last lines give the report's path and verdict. If it says the host is unsupported (it covers Ubuntu, and Debian experimentally), tell the user and stop.

What it does:

1. Inventory (collect_inventory.sh): packages, services, ports, reboot state, automatic updates, certificates, failed services.
2. Match (match_osv.py): OSV with the distro's own ecosystem and source package versions, so backported fixes count as fixed. Only the running kernel is matched. Packages from other archives (Docker, NodeSource) are compared with the vendor's latest version instead.
3. Enrich (enrich.py): CISA KEV, EPSS and, for kernel CVEs, the source files each fix touches.
4. Exposure (probe_exposure.sh, exposure.py): which running processes load each package, whether they listen publicly, and which kernel modules are active. Needs passwordless sudo or root to see other users' processes. Without it, user-space exposure is unknown.
5. Containers (collect_containers.sh, match_containers.py): reads package databases with docker cp, without running anything in a container, one per distinct image. Covers OS and npm packages, runtimes past end of life, each container's exposure (public, proxied through nginx, host-network, internal) and root-level settings (Docker socket, privileged). It can't see Python packages or binaries installed outside a package manager (Node and Postgres in official images), and a package in an image may not be loaded.
6. Report (report.py): the same scan always gives the same report.

fix_state per finding:

The JSON files are large. Never load them into context whole. Summarize with python3 -I -c or jq. Container findings are in container-enriched.json, with image, kind (os or npm), dev and malicious. Their severity is in advisory_rating or cvss_rating instead of distro_priority.

exposure.status per host finding:

Container processes don't count here: their packages are inside the image, and step 5 covers those.

3. Read and check the report

The script decides the actions, so the same scan always gives the same report. It opens with a one-line verdict and a checklist (Do now, This week, When convenient, Optional) with exact commands, then Watch out, the numbers, the most important findings, what is safe to set aside, and coverage.

Rules it applies:

Then:

1. Check it on the host before showing it, with read-only commands. The report file stays as the script wrote it. Put what you find in your reply, under "Checked on the host":
   • Reboot in Do now: confirm with uname -r and ls /boot.
   • Other Do now items that rest on an exposure label: verify with one targeted command.
   • Failed services: read their recent log (journalctl -u <unit> -n 20) and say what is wrong. A failing certificate renewal, for example, matters more than most CVEs.
   • Public ports: try each from outside if you can (nc -z <ip> <port>, with the IP from ssh -G <target> | awk '/^hostname /{print $2}'). A provider firewall may already block them. That's one TCP connect to the user's own server: never try logging in.
   • Expired certificates: check whether the web server still uses them and whether DNS still points anywhere. Unused ones get deleted, not renewed.
   • Rebuild items: they assume the project's source is on this server. Say so if it isn't.
2. If the user writes in another language, save a translation next to the report as cve-report-<target>-<date>.<language>.md. Keep commands, CVE ids and package names exactly as they are.
3. In your reply, give the verdict, what changed since the last scan (if the report has it), the "Do now" list and what you checked, plus the path to the file. Don't paste the whole report.
4. Never run the commands yourself unless the user explicitly asks, one action at a time.

The report maps this host's weaknesses. Don't publish it or commit it.