Package auditor

Checks denied packages, suspiciously similar names, and dependency source changes, using data detectors already provide.

What the package auditor does

It guards the identity and origin of your dependencies with three checks:

All three checks use dependency details that detection already produced. A move to Git or a URL may also mean registry-based vulnerability checks no longer cover that dependency.

Options

--typosquat-mode only sets the policy status of typosquat findings. It does not change how names are compared. Even in fail mode a finding still has to match --fail-on to change the exit code, so a typical strict gate is --typosquat-mode fail --fail-on any.

Examples

# Ban a known-bad package
bomly scan --enrich --audit --deny-package event-stream --fail-on any

# Ban an entire namespace
bomly scan --enrich --audit --deny-group com.evil --fail-on any

# Catch typosquats of the packages you depend on, and fail on them
bomly scan --enrich --audit \
  --protected-package react --protected-package lodash \
  --typosquat-threshold 0.85 --typosquat-mode fail \
  --fail-on any

# Reject a dependency that changes to Git or a URL
bomly diff --base main --head HEAD --enrich --audit \
  --fail-on source-change

Diff and baselines

Under bomly diff, the base side acts as a trusted baseline for the typosquat check. Bomly adds the package names from the base graph to the protected set. It skips a head-side package whose ID or display name already existed in the base graph, so only newly introduced names are checked. Each new name is compared with your --protected-package list and with the names from the base graph. A long-standing package is not flagged, while a new lookalike can be. Findings are then classified as introduced, resolved, or persisted like findings from other auditors; see AUDITORS.md.

The same diff audit receives the source transitions. A move to Git uses the rule dependency-source-change-to-git. A move to a URL uses dependency-source-change-to-url. Both warn by default and explain that registry-based vulnerability checks may no longer cover the dependency. Use --fail-on source-change when either change should fail. --warn-only still downgrades a configured failure.

Limitations

• Names, not behavior. This auditor cannot tell whether a package is malicious, only whether its name is denied or resembles a protected one. Pair it with the vulnerability auditor for content risk.
• Source-change checks need detector evidence. Cargo, Bundler, npm, pnpm, Yarn, Bun, pub, and SwiftPM report source details, as do the pip, Pipenv, Poetry, and uv Python paths. Each does so only when its lockfile or tool output proves the origin. Other detectors leave the source unknown when their input cannot tell a registry package from another origin.
• Only Git and URL moves are review signals. Moves to project, workspace, or file sources stay informational, even when registry matching eligibility changes.
• Source-change policy is diff only. --fail-on source-change is accepted by other audited commands but cannot match there, because they do not produce dependency transitions.
• Source changes need context. A Git or URL source can be intentional. The warning asks a reviewer to confirm the new origin and pinned reference.
• Typosquat tuning is a trade-off. A lower threshold catches more lookalikes but raises false positives on legitimately similar names. Tune --typosquat-threshold per project.
• Protected lists are explicit. Outside diff, Bomly only checks lookalikes against names you pass with --protected-package. It does not infer a list of popular packages.