https://github.com/amarjaleelbanbhan/veripatch
Verified remediation for npm vulnerabilities — scan, sandbox-verify fixes are safe, and get audit-grade evidence reports.
https://github.com/amarjaleelbanbhan/veripatch
cli cve devsecops docker github-actions nodejs npm sca security supply-chain-security typescript vulnerability-scanner
Last synced: 15 days ago
JSON representation
Verified remediation for npm vulnerabilities — scan, sandbox-verify fixes are safe, and get audit-grade evidence reports.
- Host: GitHub
- URL: https://github.com/amarjaleelbanbhan/veripatch
- Owner: amarjaleelbanbhan
- License: apache-2.0
- Created: 2026-07-03T10:45:51.000Z (16 days ago)
- Default Branch: main
- Last Pushed: 2026-07-03T18:11:42.000Z (16 days ago)
- Last Synced: 2026-07-03T19:16:40.819Z (16 days ago)
- Topics: cli, cve, devsecops, docker, github-actions, nodejs, npm, sca, security, supply-chain-security, typescript, vulnerability-scanner
- Language: TypeScript
- Size: 454 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# VeriPatch
> Verified remediation for npm vulnerabilities — don't just detect, **prove the fix is safe**.
[](https://github.com/amarjaleelbanbhan/VeriPatch/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/veripatch)
[](https://www.npmjs.com/package/veripatch)
[](LICENSE)
Detection of vulnerable npm dependencies is commoditized (`npm audit`, Dependabot, Snyk).
**Verified remediation is not.** Engineers don't apply fixes because of alert fatigue, fear
of breakage, and lack of evidence. VeriPatch closes the gap:
1. **Scan** — rank vulnerabilities by severity × fix feasibility (via [OSV.dev](https://osv.dev)).
2. **Verify** — apply the fix in a hardened Docker sandbox, re-scan to prove the vulnerability
left the resolved tree, run your build and tests to prove nothing breaks.
3. **Report** — emit audit-grade evidence reports (Markdown + JSON) with deterministic
confidence verdicts.
| | `npm audit` | Dependabot | Snyk | VeriPatch |
| --------------------------------------------------- | :---------: | :--------: | :--: | :-------: |
| Detects known vulnerabilities | ✅ | ✅ | ✅ | ✅ |
| Ranks by severity | ✅ | ✅ | ✅ | ✅ |
| Opens a fix PR | ❌ | ✅ | ✅ | ❌ (yet) |
| **Actually runs the fix in isolation** | ❌ | ❌ | ❌ | ✅ |
| **Independently re-scans to prove the CVE is gone** | ❌ | ❌ | ❌ | ✅ |
| **Runs your real build/test before you merge** | ❌ | ❌ | ❌ | ✅ |
| Verdict from exit codes only, never heuristics | n/a | n/a | n/a | ✅ |
| Free, self-hosted, no account | ✅ | ✅ | ❌ | ✅ |
## Quickstart
```bash
npm install -g veripatch
veripatch doctor # diagnose environment (Node, Docker, lockfile, network)
veripatch scan # ranked vulnerability table in <15s
veripatch verify GHSA-... # sandboxed proof a fix is safe
veripatch update GHSA-... # apply a verified fix to your working tree
veripatch report GHSA-... # re-render evidence without re-running anything
```
`scan` and `report` work everywhere; `verify` requires a reachable Docker daemon.
`scan` understands `package-lock.json` (v2/v3), `yarn.lock` (classic and berry), and
`pnpm-lock.yaml` (v6/v9), auto-detected. `verify`/`update` currently replay fixes with npm, so
they refuse yarn/pnpm projects explicitly rather than corrupting them.
### As a GitHub Action
```yaml
- uses: actions/checkout@v4
- uses: amarjaleelbanbhan/VeriPatch@v0.1.0
with:
severity-threshold: high
fail-on: new
```
See [examples/workflow.yml](examples/workflow.yml) for the full example (triggers, permissions,
baseline mode) and [action.yml](action.yml) for every input.
## How it works
```
scan → parse lockfile → OSV advisories → rule engine → ranked, fix-resolved report
verify → stage a copy → apply the bump → install (sandboxed, scripts off)
→ re-scan the copy to prove the vuln is gone → build/test (network off)
→ deterministic verdict from exit codes + the re-scan alone
```
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full data flow and layering.
## Design principles
- **Verification-first** — confidence verdicts derive only from exit codes and VeriPatch's own
re-scan, never from log-text heuristics (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)).
- **Security-first** — untrusted project code only ever executes inside a hardened,
network-restricted container. Zero telemetry. No secrets required. See
[docs/SECURITY.md](docs/SECURITY.md).
- **CI-native** — machine-readable `report.json` ([docs/API.md](docs/API.md)), deterministic
exit codes, baseline mode so pre-existing debt doesn't fail builds.
## Documentation
| | |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| [docs/CLI.md](docs/CLI.md) | Full command reference, flags, exit codes |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | `.veripatchrc` reference and precedence |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Layering, data flow, confidence rules |
| [docs/API.md](docs/API.md) | `report.json` schema, ports, OSV usage |
| [docs/SECURITY.md](docs/SECURITY.md) | Threat model, sandbox guarantees, disclosure policy |
| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Setup, layering rules, fixture-adding guide |
| [docs/ROADMAP.md](docs/ROADMAP.md) | What's shipped, what's next |
| [docs/adr/](docs/adr/) | Why OSV over NVD, SQLite over Postgres, Docker over subprocess, etc. |
## Status
All MVP milestones (scan, verify, report/update/doctor/cache, GitHub Action) are implemented
and tested. Pre-1.0: the CLI contract and `report.json` schema are considered stable but not
yet field-proven — see [docs/ROADMAP.md](docs/ROADMAP.md) for what's tracked toward v1.0.
## Contributing
See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). Issues and discussion are welcome.
## License
[Apache-2.0](LICENSE)