Understanding Veln's trust score
When Veln analyzes a package install, it produces a trust score from 0 to 100 and a verdict: ALLOW, HOLD, WARN, or BLOCK. The score is not a black box — every point is accounted for by specific signals with documented weights. Here's how it works.
The eight signals
Trust scores are calculated by adding points for positive signals and subtracting for negative ones. The maximum possible score is 100.
| Signal | Max points | What earns it |
|---|---|---|
| Version age meets threshold | 20 | Version has been published for at least min_version_age (default: 2h) |
| Consensus installs meet threshold | 25 | Version has at least min_installs community observations (default: 10) |
| Canary sandbox: clean | 20 | Lifecycle scripts in sandbox produced no suspicious behavioral signals |
| Publisher account age ≥ 365 days | 15 | The account that published this version is over a year old |
| Metadata coherence | 10 | Four checks pass: consistent package name, valid semver, valid license, no suspicious keywords in description |
| Signing key continuity | 5 | Publisher signing key matches key used for previous versions |
| No new undeclared install script | 5 | No postinstall/preinstall added in this version that wasn't in the previous version |
| Veln Lens: clean bonus | 5 | Veln Lens found zero obfuscation findings |
| Total possible | 105 | Capped at 100 |
Verdict thresholds
| Score range | Verdict | Meaning | |---|---|---| | ≥ 80 | ALLOW | All significant checks passed. Package installs. | | ≥ 40 and < 80 | HOLD | No active threat detected, but insufficient evidence. Awaits cooling or approval. | | ≥ 20 and < 40 | WARN | Suspicious patterns found. Requires reviewer approval. | | < 20 | BLOCK | Active threat signal. Install stopped. No approval path. |
These thresholds are configurable in veln.toml. You can tighten them (auto_approve_score = 90) for production environments or relax them (warn_score = 30) for experimental development work.
Hard block overrides
Certain findings block the install regardless of the total score:
- Consensus mismatch (minority hash detected): BLOCK unconditionally
- Binary magic bytes in a source file (ELF, PE, Mach-O in a .py or .js file): BLOCK unconditionally
- Canary sandbox: malicious verdict: BLOCK unconditionally
- Publisher signing key < 30 days old on a key change with no co-signature: BLOCK unconditionally
- Veln Lens score ≥ 71/100: BLOCK unconditionally
These cannot be approved. They cannot be overridden by score. They represent threat signals that are unambiguous enough that no amount of other positive signals changes the verdict.
Reading a trust score in practice
A package published yesterday by a new account with no prior packages would score approximately:
- Version age: 0 pts (published hours ago)
- Consensus: 0 pts (zero community installs)
- Sandbox: 20 pts (if clean)
- Publisher account age: 0 pts (account < 1 year old)
- Metadata: 10 pts (if coherent)
- Signing key: 0 pts (new key, no continuity)
- No new install script: 5 pts (if no hook)
- Lens clean: 5 pts (if no findings)
Total: approximately 40 pts → HOLD verdict.
The same package, published two years ago by a well-established account with thousands of prior installs: likely 95–100 pts → ALLOW.
Why the cooling signal is so heavy
The version age and consensus signals together are worth 45 points — nearly half the total score. This is intentional. The zero-day window (the period between publication and threat feed detection) is the highest-risk moment in a package's lifecycle. A package that is new and unobserved is not necessarily malicious, but it has provided no evidence that it isn't. The burden of proof is on the package to accumulate trust, not on the developer to prove danger.
Adjusting thresholds for different environments
Veln supports environment-specific policy overrides. A common configuration:
[policy]
mode = "enforce"
auto_approve_score = 80
[policy.production] # activated when VELN_ENV=production
auto_approve_score = 90
warn_score = 50
In production CI, a score of 89 that would be auto-approved on a developer machine is held for reviewer approval. The higher bar in production reflects the higher cost of getting it wrong.
Every component of Veln's trust score is documented and configurable.