hexblot / composer-remediate

v0.6.1 2026-09-10 16:49 UTC

Requires

• php: ^8.1
• composer-plugin-api: ^2.0
• symfony/yaml: ^5.4 || ^6.4 || ^7.0 || ^8.0

Requires (Dev)

• composer/composer: ^2.9
• justinrainbow/json-schema: ^5.2 || ^6.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5

Suggests

• ext-pdo_sqlite: Required to build or read a local advisory database (remediate db:build, --database-location)
• ext-zip: Required by remediate db:build to read the OSV and FriendsOfPHP archives

MIT

• Nikolaos Andriopoulos

• security
• plugin
• composer
• Audit
• dependencies
• vulnerability
• remediation

Published on Packagist.org on 2026-09-10 16:49 UTC

README

From vulnerable dependency to verified Composer fix.

composer audit tells you which packages are vulnerable. composer remediate searches for the least invasive composer update command that removes the vulnerability, proves each candidate with Composer's own dependency solver, and recommends the best verified one. The search is bounded and ranked, not exhaustive: the report says when a limit was hit.

$ composer remediate

CVE-2026-XXXXX  symfony/http-foundation 6.4.21
  Introduced by
    root
    └── drupal/core-recommended 11.4.2
        └── symfony/http-foundation 6.4.21
  Recommended remediation
    drupal/core-recommended 11.4.2 -> 11.4.3   (3 packages updated, 0 added, 0 removed)
  Composer validation
    PASS
  Recommended command
    composer update drupal/core-recommended -W -m

Status: released as 0.x on Packagist; every release so far recommends and never modifies your project. Phases 0 to 3 and 6 of the roadmap are complete (seventeen real historical fixtures); global planning (Phase 4) and --apply (Phase 5) are ahead. Three rounds of adversarial adoption review are answered in the changelog, each finding with a test. Current state, fixtures and evidence: hexblot.github.io/composer-remediate.

Using it as a CI gate

The command exits 0 when the lock is clean, 1 when vulnerabilities have a verified fix, 2 when at least one has no verified fix yet, and 3 to 5 for tool, advisory-data or network errors. A typical gate fails on 1 (apply the recommended command), warns on 2, and keeps the HTML or JSON report as an artifact:

composer global config --no-plugins allow-plugins.hexblot/composer-remediate true
composer global require hexblot/composer-remediate
composer remediate --no-dev --output=remediation-report.html --output=remediation-report.json

Add --fail-on high to let low and medium findings pass, --output=results.sarif for GitHub Code Scanning annotations, or --output=sbom.cdx.json for a CycloneDX SBOM with the fixes attached.

For a project you do not trust, run the shipped composer-remediate binary instead of composer remediate: it boots Composer with plugins and scripts disabled from the first instruction and never includes a project's autoloader, so nothing from the analysed project executes during planning.

Ready-made GitHub Actions and GitLab CI jobs, and jq recipes for severity-based gates, are in the CI integration guide. Every command and option is listed in the CLI reference.

Development

PHP and Composer run inside ddev:

ddev start
ddev composer install
ddev composer check      # phpstan + phpunit

Documentation is built with MkDocs (pipx run --spec mkdocs --pip-args=pymdown-extensions mkdocs serve) and published from main to GitHub Pages. The CLI reference and case-studies pages are generated (ddev composer cli-reference, ddev composer case-studies) and checked in CI.

Acknowledgement

This project was inspired by CVE Lite CLI, an OWASP project that gives JavaScript and TypeScript developers local-first, lockfile-based vulnerability scanning with copy-and-run fix commands and parent-aware guidance for transitive dependencies. Composer Remediate brings the same idea to the PHP ecosystem, with the addition that every recommendation is proven by Composer's own dependency solver before it is shown.

License

MIT. See LICENSE.