Metadata-Version: 2.5
Name: depquiet
Version: 0.4.0
Summary: Cut through vulnerability alert noise. Tells you which CVEs actually matter.
Project-URL: Homepage, https://github.com/samuelrojas-dev/depquiet
Project-URL: Repository, https://github.com/samuelrojas-dev/depquiet
Project-URL: Documentation, https://github.com/samuelrojas-dev/depquiet#readme
Project-URL: Issues, https://github.com/samuelrojas-dev/depquiet/issues
Project-URL: Changelog, https://github.com/samuelrojas-dev/depquiet/blob/main/CHANGELOG.md
Author-email: Samuel Rojas <sarojas123@icloud.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cve,dependabot,devsecops,epss,npm-audit,pip-audit,reachability,sarif,sca,security,supply-chain,triage,trivy,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# depquiet

[![CI](https://github.com/samuelrojas-dev/depquiet/actions/workflows/ci.yml/badge.svg)](https://github.com/samuelrojas-dev/depquiet/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/depquiet)](https://pypi.org/project/depquiet/)
[![Python versions](https://img.shields.io/pypi/pyversions/depquiet)](https://pypi.org/project/depquiet/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![codecov](https://codecov.io/gh/samuelrojas-dev/depquiet/graph/badge.svg)](https://codecov.io/gh/samuelrojas-dev/depquiet)

**Cut through vulnerability alert noise. Surface the signal.**

`depquiet` triages your `npm audit` / `pip-audit` / `trivy` / `grype` / Dependabot / Snyk alerts and tells you which CVEs actually matter — in seconds, not hours.

```
$ depquiet

depquiet scan — npm (847 packages)

✅ FILTERED: 89 alerts (92%)
   ├─ 34 unreachable — vulnerable function never imported
   ├─ 28 devDependency only — never reaches production
   ├─ 19 EPSS < 10% — no known exploits in the wild
   └─  8 community template — confirmed false positive

⚠️  REVIEW: 5 alerts
   CVE-2024-48930       lodash                    moderate   EPSS 3%
   CVE-2024-21538       semver                    moderate   EPSS 1%
   ...

🔴 ACTION REQUIRED: 3 alerts
   • CVE-2024-4068  braces  EPSS 67%  FIX: update to 3.0.3
     → src/config/parser.ts
     → src/utils/glob.ts
     Uncontrolled resource consumption in braces

Total: 97 alerts — 3 actionable | 5 review | 89 filtered
You just saved ~178 minutes of triage time.
```

## The problem

Developers spend **3.5 hours per week** triaging vulnerability alerts that are mostly noise:

- **60-80% of CVEs are unreachable** — the vulnerable function is never called
- **npm audit is "broken by design"** — 80% false positive rate ([Dan Abramov](https://overreacted.io/npm-audit-broken-by-design/))
- **Dependabot is a "noise machine"** — Filippo Valsorda recommends [disabling it entirely](https://words.filippo.io/dependabot)

The result? **Alert fatigue.** Teams either waste hours triaging noise, or ignore alerts entirely and miss the real threats.

## How it works

depquiet applies four deterministic filters to separate signal from noise:

| Filter | What it catches | Impact |
|---|---|---|
| **Reachability** | Package/function never imported in your source code | 40-60% reduction |
| **Dev dependencies** | Vulnerabilities in devDependencies that never reach production | 10-20% reduction |
| **EPSS scoring** | CVEs with near-zero probability of real-world exploitation | 5-15% reduction |
| **Community templates** | Known false positives confirmed by the community (nuclei-style YAML) | Growing over time |

### Zero false negatives by design

depquiet is **conservative**: it would rather let a false positive through than dismiss a real vulnerability. Python reachability uses AST parsing (immune to false positives from comments, docstrings, and strings); JS/TS uses string matching. Both only filter when there are **zero real references** to the package in your source code.

## Install

```bash
pip install depquiet
```

## Usage

```bash
# Auto-detect package manager and scan
depquiet

# Scan a specific directory
depquiet --path ./my-app

# Pipe in existing audit output
npm audit --json | depquiet --stdin
pip-audit --format json | depquiet --stdin
trivy fs --format json . | depquiet --stdin
grype dir:. -o json | depquiet --stdin
snyk test --json | depquiet --stdin
gh api /repos/OWNER/REPO/dependabot/alerts --paginate | depquiet --stdin

# Fully offline (skip EPSS API)
depquiet --offline

# SARIF output for GitHub Code Scanning
depquiet --sarif results.sarif

# JSON output for scripting
depquiet --json

# Custom EPSS threshold
depquiet --epss-threshold 0.05

# Use a custom config file
depquiet --config ./ci-config.yaml
```

## CI Integration

### Exit codes

- `0` — No ACTION items (safe to pass)
- `1` — ACTION items found (fail the build)

### GitHub Actions (Marketplace)

```yaml
- name: Triage vulnerabilities
  uses: samuelrojas-dev/depquiet@v0
  with:
    sarif: results.sarif
    epss-threshold: "0.1"
```

The action installs depquiet, runs it, uploads SARIF to GitHub Code Scanning, and fails the build if ACTION items are found.

### GitHub Actions (manual)

```yaml
- name: Triage vulnerabilities
  run: |
    pip install depquiet
    depquiet --sarif results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

## Community templates

depquiet ships with **21 built-in templates** and uses [nuclei-style](https://github.com/projectdiscovery/nuclei-templates) YAML to encode community knowledge about known false positives:

| Template | CVE | What it catches |
|---|---|---|
| lodash prototype pollution | CVE-2020-8203, CVE-2019-10744 | Only merge/defaultsDeep affected |
| semver ReDoS | CVE-2022-25883 | Only untrusted input to `semver.clean()` |
| express open redirect | CVE-2024-29041 | Only unvalidated `res.redirect()` |
| axios SSRF | CVE-2023-45857 | Server-side only, cookies header |
| json5 prototype pollution | CVE-2022-46175 | Only `parse()` with `reviver` |
| webpack-dev-middleware | CVE-2024-29180 | devDependency only |
| ip SSRF | CVE-2023-42282 | `isPrivate()` bypass, private networks only |
| requests proxy-auth leak | CVE-2023-32681 | Only proxy + redirect |
| cryptography null dereference | CVE-2024-0727 | Only PKCS12 loading |
| minimist prototype pollution | CVE-2021-44906, CVE-2020-7598 | Only direct argv parsing |
| nth-check ReDoS | CVE-2021-3803 | Only attacker-controlled CSS selectors |
| postcss ReDoS | CVE-2023-44270 | Only attacker-controlled CSS input |
| glob-parent ReDoS | CVE-2020-28469 | Only attacker-controlled glob patterns |
| node-forge timing attack | CVE-2022-24771 | Network-level timing measurement needed |
| shell-quote injection | CVE-2021-42740 | Only untrusted input to shell-quote |
| qs prototype pollution | CVE-2022-24999 | Mitigated by Express 4.x defaults |
| word-wrap ReDoS | CVE-2023-26115 | Only very long strings without spaces |
| tough-cookie prototype pollution | CVE-2023-26136 | Only attacker-controlled cookie jar |
| js-yaml code execution | CVE-2013-4660 | Only `yaml.load()` with default schema |
| certifi root CA removal | CVE-2023-37920 | Only chains through distrusted CAs |

```yaml
id: prototype-pollution-lodash
reason: "Only defaultsDeep/merge are affected. Other lodash functions are safe."
cves:
  - CVE-2020-8203
  - CVE-2019-10744
not-imported: ["lodash.defaultsDeep", "lodash.merge"]
```

### Contributing a template

1. Create a YAML file in `templates/dismiss/`
2. Add the CVE, affected package, and dismiss conditions
3. Open a PR — the community reviews and merges

Templates are the growth engine: each contribution helps every depquiet user.

## Configuration

Create `.depquiet.yaml` in your project root (or pass `--config path/to/config.yaml`):

```yaml
# EPSS threshold (default: 0.1 = 10%)
epss_threshold: 0.05

# Extra template directories
template_dirs:
  - ./my-templates

# Packages to always flag (never filter)
always_flag:
  - lodash
  - express

# Skip EPSS API (fully offline)
offline: false
```

CLI flags override config values. `template_dirs` from both sources are merged.

## Benchmarks

Tested against realistic audit output from popular project types (offline mode, all filters active):

| Scenario | Parser | Alerts | Filtered | Rate |
|----------|--------|-------:|---------:|-----:|
| Express web app | npm | 15 | 13 | **87%** |
| Django web app | pip | 9 | 8 | **89%** |
| Node.js container | trivy | 8 | 8 | **100%** |
| Python container | grype | 6 | 5 | **83%** |
| **Total** | | **38** | **34** | **89%** |

**89% noise reduction** — from 38 alerts down to 4 that actually matter. All scans complete in under 10ms.

Run the benchmarks yourself: `python -I benchmarks/run_benchmark.py`

## Compared to

| Tool | Approach | Limitation |
|---|---|---|
| `npm audit` | Flags everything | 80% false positives |
| `pip-audit` | Flags everything | No triage, no context |
| Trivy | Multi-scanner, flags everything | Great detection, no triage |
| Grype | Container scanner, flags everything | Great detection, no triage |
| Dependabot | GitHub-only, flags everything | No triage, overwhelming noise |
| Snyk | SaaS, paid | $100K+/year for reachability |
| GitHub Dependabot Reachability | AST analysis (Oct 2026) | JS/TS only, Enterprise Cloud only, preview |
| Mend / Black Duck | SaaS, paid | Enterprise pricing, vendor lock-in |
| **depquiet** | Deterministic triage, community templates | Free, offline, works everywhere |

## License

MIT

## Contributing

depquiet is designed to grow through community templates. Every template you contribute helps thousands of developers skip a false positive.

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
