| name | hydra-gate-composer-audit |
| description | Run `composer audit` to check composer.lock dependencies for known CVEs. Invoked by the builder before push and the reviewer's mandatory block. Mirrors the orchestrator's `composer-audit` quality gate. |
| metadata | {"category":"Hydra pipeline gate","tags":["hydra","mechanical-gate","composer","security","cve"]} |
Purpose
Composer packages ship with known CVEs occasionally. The orchestrator's composer-audit stage fails the recheck on any High/Critical CVE in installed deps. Letting vulnerable packages ship is both a security problem and a blocking gate.
Check
composer audit --format=plain
Exit 0 = clean. Exit non-zero = CVEs present. The plain-format output lists each advisory with its package, version, severity, and CVE ID.
Fix action
For each flagged package:
- Read the advisory to see the affected version range and the patched version
- Update
composer.json to a patched version constraint (e.g. "phpunit/phpunit": "^10.5.64" if 10.5.63 has a CVE)
- Run
composer update <package> to regenerate composer.lock
- Re-run the audit to confirm green
- Run
composer check:strict + tests — a dep bump sometimes breaks downstream code
If the advisory is in a dev-only dep (PHPUnit, PHPCS, Psalm, etc.), the bump is low-risk. Production deps need careful regression testing.
When NOT to bump
If the patched version breaks PHP-version compatibility (you're on PHP 8.3, patch needs 8.4) OR requires an ecosystem-wide migration, leave [unfixed: composer-audit — <CVE-ID>] with a note explaining the constraint. The applier will see it and decide whether to block.
Related
composer update --dry-run shows what WOULD change without modifying composer.lockcomposer why <package> shows who depends on a transitive dep you can't directly update
Verification
Sample gate output is in examples/:
- examples/pass.log — what stdout looks like when this gate is green on the diff
- examples/fail.log — what stdout looks like when this gate finds a violation; per-finding detail is in
/tmp/hydra-gate-composer-audit.log so the builder/reviewer can read line-by-line and apply Fix actions deterministically. Confirm the gate is green by running ./scripts/run-hydra-gates.sh --scope-to-diff from the app dir before pushing.
