# Depfathom

> Use when checking a project's dependencies for known vulnerabilities from manifests or lockfiles, including package.json with no lockfile, requirements.txt, and version conflicts. Groups CVE, GHSA, and PYSEC aliases into one finding per advisory.

- Skill: `codejunkie99/depfathom` (Agent Skill)
- Install (CLI): `npx get-skill add codejunkie99/depfathom`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/depfathom/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/codejunkie99/depfathom

---


# depfathom: dependency advisories

## job
turn every declared dependency into an exact version, look it up in OSV, and report one finding per advisory group per package.

## gap it targets
- evidence (fixture): in our fixture run, two popular dependency scanners skipped a `package.json` with exact pins `lodash 4.17.15` and `minimist 1.2.0` because there was no lockfile.
- evidence (fixture): one scanner hit a `requests 2.19.0` versus `urllib3 1.24.1` conflict and only said so on stderr. this skill makes that a finding.
- evidence (fixture): one scanner emitted 60 records for the same 30 CVEs another reported once each. this skill groups aliases.

## inputs
- a repo path. reads `requirements*.txt`, `pyproject.toml`, `package.json`, `package-lock.json`. v2 adds poetry, uv, pnpm, yarn, go.mod, Cargo, Gemfile.

## method
1. find manifests and lockfiles. if a lockfile exists, use its exact versions.
2. no lockfile: exact pins (`"4.17.15"`, `==2.10`) are used as-is. ranges (`^4.17.0`, `>=2.0`) get two lookups, the lowest allowed and the newest allowed from the registry, and the finding says `resolved_without_lockfile: true`.
3. check pins against each other's declared requirements where you can (for pip, a package's own requirements list on PyPI). a pin outside another package's allowed range is a `ks.dep.resolution-conflict` finding.
4. query `https://api.osv.dev/v1/querybatch` with `{"package":{"ecosystem":"PyPI"|"npm","name":...},"version":...}`, then fetch each vuln for aliases and fixed versions.
5. group: two records that share any alias are one group. pick the CVE as the title ID when there is one.
6. severity: use the advisory's CVSS where given, otherwise `medium`, and say so.

## what counts as a finding
- a dependency version inside an advisory's affected range, or a pin conflict.
- not a finding: dev-only tools in a separate dev file, unless the user wants them (report them, marked `dev: true`).

## output
```json
{"command":"depfathom","rule_id":"ks.dep.known-advisory","kind":"dep","severity":"critical","confidence":"high","package":{"ecosystem":"PyPI","name":"pyyaml","version":"5.3","fixed_versions":["5.4"],"resolved_without_lockfile":false},"aliases":["CVE-2020-14343","GHSA-...","PYSEC-..."],"location":{"path":"requirements.txt","start_line":3},"sources":["depfathom"],"status":"open"}
```
check every alias and fixed version against OSV before you write it. never fill them in from memory.

## today vs later
- today: read manifests, call the OSV API with `curl`, and run `pip-audit`, `npm audit`, or any dependency scanner already installed. then add what they skipped (bare package.json, conflicts) and merge aliases.
- once the keelsec engine exists: `keelsec depfathom <path> --format json`, with an offline cache.

## stop and scope
- network use is limited to OSV.dev and package registry metadata. `--offline` means cache only.
- never upgrade or install packages to "check". suggest the fixed version and stop.

