How Veln Consensus works

Of all the checks Veln runs on a package install, the one that catches the most sophisticated attacks is also the simplest to explain: does the file you just downloaded match what everyone else downloaded?

The threat it's designed for

Most supply chain attacks serve the same malicious package to everyone. A compromised maintainer account publishes a malicious version, and everyone who installs that version gets the same malicious code. These attacks are relatively quick to detect — one security researcher downloads the package, notices the malicious code, reports it, and the package is removed.

The more sophisticated attack serves different packages to different users. This is called a targeted supply chain attack. The attacker doesn't need to compromise millions of installs to achieve their goal — they just need to compromise one specific target (a particular company, a specific developer with access to valuable infrastructure). They serve the malicious package only to IP addresses associated with that target, and serve the legitimate package to everyone else.

From the perspective of any individual user, the install looks normal. From the perspective of the npm or PyPI registry, nothing is wrong — the legitimate package is still available. No security researcher who downloads the package from their own machine will see any malicious code.

This is the attack that Veln Consensus is designed to detect.

How the consensus network works

When a Veln user successfully installs a package, the agent pushes an observation to the Veln platform:

Package name
Package version
SHA-256 hash of the downloaded tarball
Country code (derived server-side from the user's IP — not the IP itself)

That's the complete observation. No source code, no project structure, no user identity, no exact IP address.

The platform aggregates observations from all participating users. For any given (ecosystem, name, version) tuple, it knows: how many observations exist, what hashes were observed, and from which geographic regions.

When you install lodash@4.17.21, Veln checks the platform: what hash did everyone else get for this version? If 18,441 other installs all received sha256:abc123... and you received sha256:def456..., you are being served a different binary.

What a hash mismatch looks like

veln  ✕ block   npm:lodash@4.17.21             consensus mismatch
                                               your sha256:       def456...
                                               community sha256:  abc123... (18,441 installs)
                                               no approval path — remove this dependency

The install is blocked immediately. No approval path exists for a consensus mismatch — this is a hard block. The developer is shown both hashes and the community observation count, giving them enough information to report the incident.

The minority hash threshold

Not every hash divergence is a targeted attack. Some packages have legitimate reasons for hash variation — platform-specific binary wheels, for example, where different operating systems receive different files.

Veln accounts for this. The minority hash detection threshold is 10%: a hash is flagged as anomalous only if it represents less than 10% of total observations for that version. A package with 10 users split 6/4 across two hashes would not trigger a consensus mismatch. A package with 18,441 users where 1 user gets a different hash — that's the signal.

What Veln Consensus cannot detect

Consensus is powerful but not omnipotent. It cannot detect an attack where the malicious package was served to enough users to reach the 10% threshold. A targeted attack against a large organization — affecting 1,000 out of 10,000 total users — would not trigger the minority threshold.

For this reason, Veln Consensus is one layer of a three-tier pipeline, not a standalone solution. The cooling gate, Veln Lens, and the canary sandbox provide complementary detection that doesn't depend on community-scale observations.

Privacy

Participation in Veln Consensus is opt-in. When disabled, Veln still performs all local analysis (Tiers 1–3) but does not push observations or query the consensus network. The consensus check is the one component that requires a network connection; all others work entirely offline.

Veln Consensus catches targeted attacks that serve different binaries to different users — an attack class that hash-only and signature-only tools cannot detect on their own.