Package auditor

Checks denied packages, suspiciously similar names, and dependency source changes.

User notes

Package identity checks need no enrichment. In a diff audit, the auditor also warns when a known dependency source changes to Git or a URL. Use --fail-on source-change when that change should fail.

What the package auditor does

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

1. Denylist — flag any package (or any package in a denied group/namespace) you have decided to ban outright.
2. Typosquat — flag packages whose names are suspiciously close to a package you trust, catching reqeusts, loadsh, or cross-env-style lookalikes.
3. Source change — in a diff, warn when a dependency that had a known source now comes from Git or an arbitrary URL. This asks for review; it does not claim the change is malicious.

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

Options

--typosquat-mode controls only the policy status of typosquat findings, not how names are compared. The two accepted values are warn (the default) and fail. Note that 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 actually 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 package names from the base graph to the protected-name set. It skips a head-side package when its ID or display name already existed in the base graph. This limits typosquat checks to newly introduced names. Each new name is compared with both your --protected-package list and the package 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 canonical source transitions. A move to Git uses 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 source 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, SwiftPM, and the pip, Pipenv, Poetry, and uv Python paths report source details when their lockfile or tool output proves the origin. Other detectors leave the source unknown when their input cannot distinguish a registry package from another origin.
• Only Git and URL moves are review signals. Moves to project, workspace, or file sources remain 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 because they do not produce dependency detail transitions.
• Source changes need context. Git and URL sources 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 of diff, Bomly only checks lookalikes against names you pass with --protected-package; it does not infer a baseline of "popular" packages.