sharkyger/composer-cve-gate

# composer-cve-gate **Status — pre-stable (0.x).** API and exit codes are stable; defaults, detection heuristics, and recommendation logic may shift in minor versions while we iterate on real-world feedback. The **freshness-hold feature** (gap §2 below) is time-boxed: when Composer ships `minimum-release-age` (a reserved name in their policy roadmap), that specific feature is retired. The **install-from-lockfile advisory gap** (§1 below) is the durable reason for this tool to exist, so the **tool itself remains** as long as that gap is open — and will be archived only if Composer closes it upstream too. Composer 2.10+ ships `config.policy.advisories.block` (default true) for advisory blocking during `composer update` / `require` / `remove`, and `config.policy.malware.block` (default true) for malware blocking via the Aikido feed during `composer install`. **composer-cve-gate fills three gaps that `composer.policy` doesn't cover:** 1. **Advisory blocking at `composer install` time** — When a lockfile was clean at commit but a vulnerability is published for a locked version afterward, a subsequent `composer install` (the typical CI deploy) loads the vulnerable version with no block. `composer audit` can be opted in post-install but doesn't prevent it. 2. **3-day freshness hold** — Defends against zero-hour publish attacks before security researchers can inspect and report advisories. Time-limited (until Composer ships `minimum-release-age`, a reserved name in their roadmap — we archive when that ships). 3. **Post-install IoC scanning** — `safe-scan` walks `vendor/` looking for known compromise indicators (C2 domains, exfil URLs, attacker-injected file paths) after a supply-chain incident surfaces in the news. ## What it checks The scanner queries multiple CVE databases and applies time-based filtering. **Each signal covers different scope — see below for accuracy:** 1. **OSV.dev** — Google's aggregated advisory feed. - Scope: **top-level + transitive** (batch queried) - Covers: Google's data, which includes ecosystem-native disclosures 2. **GitHub Advisory Database** — GitHub's GHSA disclosures. - Scope: **top-level only** - Covers: composer ecosystem advisories, version-range filtered - Note: Composer's native `config.policy.advisories.block` primarily pulls from GHSA, so this is partially redundant with stock Composer. We query it so the install-from-lock gate has GHSA coverage on the locked set. 3. **NIST NVD** — National Vulnerability Database. - Scope: **top-level only** (budgeted fallback on clean OSV transitive deps) - Covers: upstream CVE metadata, CPE-version matches that OSV may miss - Note: Slow queries (rate-limited); we budget the first N transitive packages to avoid timeouts. 4. **Packagist freshness hold** — time-gate on publish date. - Scope: **top-level only** - Threshold: packages published < 3 days ago are held - Rationale: zero-hour malicious versions are typically flagged within 72 hours of publish. Override with `--min-age 0` when needed. - Lifespan: **temporary**. When Composer ships `minimum-release-age` as a native policy, we will archive this tool. 5. **OSSF Malicious Packages** — the OpenSSF [`ossf/malicious-packages`](https://github.com/ossf/malicious-packages) registry (local snapshot). - Scope: **top-level + transitive** - Covers: known malware, confirmed by the OSSF community - Note: Separate from `composer.policy.malware`, which uses the Aikido feed. We include OSSF for breadth. ### Packages we skip (and why) Two package shapes have no advisory data to query, so the gate skips them **before** any scan runs — silently in the install gate, with one informational line in `safe-scan`. Neither blocks the install: - **Path-type packages** (`composer.json` repositories of `"type": "path"`, or any package whose lockfile entry has `dist.type: "path"`) — your project's own bespoke `clientname/site-package`, a Drupal custom module, an in-house Laravel package. Not on Packagist, not in any vulnerability database. - **Composer dev-branch references** (`dev-main`, `dev-feature/x`, `1.x-dev`, etc.) — typically a private / in-development extension installed from a branch. Composer advisories are keyed to released versions and tags, not arbitrary branches. If you want to keep an eye on what got skipped, `composer safe-scan` lists each skipped package with the reason in its report and counts them in the summary line as `N skipped`. ## Why pre-install matters Composer dependency code can execute on the next autoload bootstrap or when loading a `composer-plugin` type package — both happen during `composer install` itself, before `composer audit` gets to inspect anything. If a vulnerable (or malicious) version isn't blocked **at install time from the lockfile**, the code runs before you have a chance to audit it. Pre-install and install-time gating are the only points in the lifecycle where blocking is still useful. `composer audit` post-install is a useful backstop, but too late if the malicious code already executed. ## Usage The plugin adds three commands: `safe-install`, `safe-upgrade` (aliased as `safe-update`), and `safe-scan`. ### Install a new package, scanned first composer safe-install monolog/monolog The plugin resolves `monolog/monolog` plus its full transitive tree, queries every package against OSV / GHSA / NVD plus the freshness hold, and only proceeds with the actual install if everything is clean. Output on a clean scan: safe-install: scanning monolog/monolog [standard composer require output follows] If something is blocked, you'll see a structured report and **nothing installs**: safe-install: scanning evil/pkg BLOCKED: evil/pkg@1.0.0 — status=vulnerable [CRITICAL] CVE-2026-XXXX — info-stealer in post-install script safe-install: blocked 1 of 1 package(s). Nothing installed. Exit code is `1`. Your project is untouched — no download, no `vendor/` write, no post-install scripts run. ### Install a dev dependency composer safe-install --dev phpstan/phpstan `--dev` is forwarded to `composer require`, so the package lands in `require-dev` as expected. ### Upgrade all dependencies composer safe-upgrade (Also available as `composer safe-update` — alias for discoverability.) Scans every direct dependency from your `composer.json`, then delegates to `composer update` with no package args — composer resolves the full graph (including transitive-only updates). ### Upgrade one package composer safe-upgrade vendor/pkg Scans then runs `composer update vendor/pkg`. Works the same with `safe-update`. ### Install a brand-new release The 3-day freshness hold blocks installs of packages published less than 72 hours ago — that's the window where a compromised version is most often up on Packagist but not yet in any CVE database. If you know a particular fresh release is fine (e.g. a patch you've been waiting for from a maintainer you trust), pin to that version and disable the hold: composer safe-install --min-age 0 vendor/just-released:1.2.3 ### Audit what's already installed composer safe-scan === safe-scan report === INFECTED — 1 package(s): evil/pkg@1.0.0 [url] https://evil.test/exfil → vendor/evil/pkg/src/payload.php safe-scan — 12 clean, 0 suspicious, 1 infected (of 13 scanned). | Status | Meaning | |--------------|------------------------------------------------------------------| | `CLEAN` | No findings, no IoC matches. | | `SUSPICIOUS` | Vulnerability database hit, but no IoC strings on disk. | | `INFECTED` | IoC strings or marker files found inside the installed package. | ### Reading exit codes `safe-install` / `safe-upgrade`: | Exit code | Meaning | |-----------|------------------------------------------------------| | `0` | Scan clean, install proceeded | | `10` | At least one package blocked, **nothing installed** | | `1` | Scanner errored (network, missing Python, etc.) | `safe-scan`: | Exit code | Meaning | |-----------|---------------------------------------------------------------| | `0` | Clean | | `1` | Infected (IoC matches found on disk) | | `2` | Suspicious (vulnerability findings but no IoCs on disk) | | `3` | Scanner error (lockfile missing, malformed, etc.) | When you see a `BLOCKED` line, the next step is to look up the CVE or advisory ID it cites and decide whether the issue actually applies to your usage. If it doesn't, you have two paths: - Pin to a patched version explicitly: `composer safe-install vendor/pkg:^2.1.4` - Disable the freshness hold for a one-off (only if the block came from `FRESH-HOLD`, not from a CVE): `composer safe-install --min-age 0 vendor/pkg` ## Install composer require sharkyger/composer-cve-gate --dev That's it — the plugin self-registers and all three subcommands appear in `composer list` immediately. No config file, no per-project setup. ### Requirements | Component | Version | Why | |-------------|------------|-------------------------------------------------------| | Composer | `^2.0` | Plugin uses the modern `composer-plugin-api` v2 hook | | PHP | `^8.2` | Modern constructor promotion, `readonly`, `enum` | | Python | `≥ 3.11` | Scanner uses `datetime.UTC` (Python 3.11+) | The bundled scanner (`bin/dependency_security_check.py`) is invoked as a subprocess — `python3` must be on `PATH`. The scanner has zero third-party Python dependencies (only stdlib + the optional `certifi` bundle on macOS for SSL trust). If Python is missing at activation, the plugin **fails loud immediately** rather than disabling itself silently. ## Configure the install-from-lock gate The install-from-lock gate is **on by default in advisory mode** — plain `composer install` loads the lockfile, scans the locked set, warns on any findings, and proceeds. To fail the build on findings, switch to `block` mode via the root `composer.json`: { "extra": { "composer-cve-gate": { "install-gate": "advisory", "install-gate-min-age": 3, "install-gate-cache-ttl": 21600 } } } Any subset of these keys works — unspecified keys keep their defaults. | Key | Type | Default | Behaviour | |---|---|---|---| | `install-gate` | string | `advisory` | `advisory` warns and proceeds · `block` aborts the install with a non-zero exit **before any download or post-install script runs** · `off` is a silent permanent disable | | `install-gate-min-age` | int (days) | `3` | Freshness hold applied to every locked package's publish date. `0` disables the hold (re-introduces the zero-hour-publish gap). | | `install-gate-cache-ttl` | int (seconds) | `21600` (6h) | Per-package clean-verdict cache under `~/.cache/composer-cve-gate/install-gate/` (or `%USERPROFILE%\.cache\…` on Windows). `0` disables caching. Only clean verdicts are cached; flagged or errored verdicts are always re-scanned. | Invalid or malformed values fall back to these defaults silently — the gate prefers a slightly-too-strict configuration over a silently disabled one. The flip side: a typo like `"install-gate": "blok"` silently degrades to advisory, so if block mode is critical, sanity-check your config by triggering a known finding once after editing it and confirming the gate's output names the mode you expect. ### `COMPOSER_CVE_GATE_DISABLE` (emergency bypass) To skip the gate for a single command without editing `composer.json`, set `COMPOSER_CVE_GATE_DISABLE=1` in the environment: COMPOSER_CVE_GATE_DISABLE=1 composer install Any non-empty value other than the string `0` enables the bypass — so `1`, `true` and `yes` all work, **and so does the string `false`**, which is *not* falsy here. To re-enable the gate, unset the variable or set it to `0`. It is loud by design — a warning is printed to the build log so a disabled gate stays visible — and it works in all modes, including `block`. Use it as an emergency lever for a single command (e.g. an urgent hotfix deploy where you've already verified the finding); for a permanent silent disable in `composer.json`, use `install-gate: off` instead. **Precedence:** `install-gate: off` short-circuits first (no scan, no log line). Otherwise, `COMPOSER_CVE_GATE_DISABLE` (when set to a non-`0` value) takes priority over the `install-gate` mode in `composer.json`. ## Verify the install-from-lock gate The core claim — blocking a flagged package **at `composer install` time, before any download or post-install script runs** — ships as an end-to-end test you can reproduce yourself in a throwaway container. The test builds a project whose `composer.lock` pins a flagged package (an inert, fixture-only stub — no real package or malware), runs a **real `composer install`**, and asserts the gate proceeds-with-a-warning in advisory mode and **aborts before the operation runs** in block mode (the package is never written to `vendor/`). The verdict is driven by a local advisory fixture, so it is deterministic and needs no live network lookup. Any Linux base with PHP 8.2+, Python 3.11+, git and Composer 2 works. Start a disposable container (`--rm` auto-removes it on exit): docker run --rm -it debian:trixie bash # Debian / Ubuntu (apt) # or: docker run --rm -it almalinux:10 bash # RHEL / AlmaLinux / UBI (dnf) Then, inside it: # 1) dependencies — Debian/Ubuntu (apt): apt update && apt install -y php-cli php-mbstring php-xml php-zip git unzip python3 python3-venv python3-pip # RHEL/AlmaLinux/UBI instead (dnf): # dnf install -y php-cli php-mbstring php-xml git unzip python3 python3-pip # 2) Composer — hash-verified official installer: php -r "copy('https://getcomposer.org/installer','composer-setup.php');" php -r "if (hash_file('sha384','composer-setup.php') === trim(file_get_contents('https://composer.github.io/installer.sig'))) { echo 'verified'.PHP_EOL; } else { unlink('composer-setup.php'); exit(1); }" php composer-setup.php --install-dir=/usr/local/bin --filename=composer # 3) run the proof: git clone https://github.com/sharkyger/composer-cve-gate.git && cd composer-cve-gate python3 -m venv .venv && . .venv/bin/activate pip install pytest -r requirements.txt pytest tests/integration/ -v # -> 2 passed `2 passed` confirms the gate fired on a real `composer install` on that platform. It has been reproduced this way across both major packaging families — Debian/Ubuntu (apt) and RHEL/AlmaLinux including unregistered UBI (dnf) — on PHP 8.3–8.5 and Python 3.12–3.14. The same end-to-end test runs in CI on every change. ## Scope `composer-cve-gate` is a **supplement to `config.policy`, not a replacement**. It does not replace: - **`composer audit`** — post-install lockfile scanning, included in every Composer project by default. Run it regularly. - **`config.policy.advisories.block`** — native advisory blocking during `composer update` / `require` / `remove` (Composer 2.10+, default true). We run in parallel for the install-from-lock gap it doesn't cover. - **`config.policy.malware.block`** — native malware blocking via Aikido during `composer install` (Composer 2.10+, default true). We provide additional OSSF ingestion. ### Temporary tool When Composer ships `minimum-release-age` (a reserved name in their policy roadmap), the freshness-hold differentiator disappears and we will archive. We're a stopgap for a known gap, not a permanent product. Maintain without long-term lock-in fear. ## DDEV If your project uses DDEV (TYPO3, Drupal, Laravel, Symfony, Magento, …), install the addon instead of the composer plugin directly. The addon runs the scanner **inside** the web container against the container's PHP version — which is the version your application actually runs — rather than whatever PHP happens to be on your host. ddev add-on get sharkyger/composer-cve-gate That registers three custom commands and auto-installs the composer plugin into your project (if `composer.json` exists): ddev safe-install monolog/monolog ddev safe-upgrade ddev safe-scan Each one runs in the web container and applies the same 5-signal gate the plain-composer commands do. No host shim — your host PHP version is irrelevant. Remove the addon with `ddev add-on remove composer-cve-gate`, which also removes the composer plugin from your project. ## Related projects `composer-cve-gate` is part of the safe-install family: **Shipped:** - `homebrew-safe-upgrade` — `brew safe-install` / `brew safe-upgrade` - `claude-code-cve-gate` — Claude Code hook (intercepts AI installs) - `mistral-code-cve-gate` — Mistral Code hook - **This project** — `composer safe-install`, `composer safe-upgrade`, and the install-from-lock gate (plain `composer install` from a lockfile) **Roadmap:** - `pip-cve-gate` — `pip safe-install` / `pip safe-upgrade` - `npm-cve-gate` — `npm safe-install` / `npm safe-upgrade` All share the OSV + GHSA + NVD + freshness-hold pattern. Composer has a native plugin API, so we use it here. pip and npm will use prefixed binaries instead. ## License MIT. See [LICENSE](LICENSE). ## Security Report vulnerabilities privately to **sharky@augatho.com**. See [SECURITY.md](SECURITY.md). This repo does not accept public bug reports for security topics.

标签：ffuf