honesty first
Security model
Exactly what betternpm checks, how it checks it, and — just as important — what it does not protect against yet.
What the free inspection does
Every betternpx / betternpm install run inspects the package before anything executes, using deterministic checks that run locally:
- Known vulnerabilities — queries OSV.dev for the exact package@version. Hits are blocking (override requires
--force-install). - Typosquat detection — Damerau-Levenshtein edit distance plus homoglyph normalization (
l0dash,rеactwith a Cyrillic е) against a curated list of ~200 popular packages. - Install scripts — any
preinstall/install/postinstallis flagged high severity; these run arbitrary code at install time and are the most common supply-chain attack vector. - Source scan — downloads the tarball (verifying its registry integrity hash), then scans contents for credential/token references (
.npmrc,.ssh,.env), environment harvesting,child_process, dynamic code (eval,new Function), outbound network calls, and obfuscation signals. - Metadata checks — package age (very new versions are risky), download counts, missing repository/license, and optional direct-dependency auditing (
--audit-deps).
The inspected tarball is never executed. After you approve, execution is delegated to the standard npm exec / npm install — betternpm adds a decision point, it does not replace npm.
How AI audits work (BYOK)
- AI audits are bring-your-own-key: your Anthropic or OpenAI key is sent over HTTPS only to run your audit, relayed to the provider, and never stored — not in the database, not in logs. It exists only in the in-flight request and the queue message that processes it.
- The audit server independently downloads the tarball, verifies its integrity hash against the npm registry, and lets the model explore the real package contents with read-only tools:
list_files,read_file,search_code,decode_strings(decodes base64/hex payloads), anddiff_previous_version(compares against the previous release — where malicious code usually arrives). - Coverage is enforced mechanically: the agent's verdict is rejected until it has read every install-script file, bin entrypoint, and the main entry. The full investigation transcript is stored with each audit and viewable on the package page.
- Verdicts are floored by deterministic facts: a package with known OSV vulnerabilities cannot be rated low by an enthusiastic model.
- Results are cached and shared publicly by exact
package @ version + integrity + scanner profile + provider + model, so one person's audit benefits everyone. Some demo audits are seeded by the platform operator and labeled with their provider/model like any other audit. - Audits are attributed only to verified GitHub identities — handles cannot be free-texted, so leaderboard credit cannot be impersonated.
What we store
- Audit results (package identity, risk verdict, findings) — public by design.
- Request IPs on audit requests, for abuse control. Never shown publicly.
- If you sign in: your GitHub login and id. Nothing else from your account.
- In your browser / on your machine: provider choice, BYOK keys, and session tokens stay in localStorage /
~/.config/betternpm(chmod 600). They never touch our database.
What we do not protect against (yet)
- Novel, well-hidden malware. Heuristics are patterns and AI review is probabilistic — a determined attacker can evade both. A low-risk verdict is evidence, not proof.
- Transitive dependencies. Only the target package (and, with
--audit-deps, its direct dependencies) are inspected — not the full tree. - Runtime behavior. We analyze statically; we do not sandbox or trace execution. Behavior that only appears at runtime (time bombs, C2 triggers) can pass.
- Compromised maintainers publishing plausible code. If malicious code looks like ordinary code, static review may miss it.
- Typosquats of niche packages. The popular-package list catches attacks on well-known names; imitations of small packages may not be flagged.
- Model mistakes. AI verdicts can be wrong in both directions — for example, heavily minified (but legitimate) packages have been rated risky. Findings link to the evidence so you can judge for yourself.
Treat betternpm as a fast, evidence-gathering first line — not a guarantee. For high-stakes code, read the source.
Report a vulnerability
Found a security issue in betternpm itself? Open a private security advisory on GitHub. The CLI and audit pipeline are open source — audit the auditor.