OSV Architecture

What is OSV?

The Open Source Vulnerabilities (OSV) database is a Google-backed, open schema for describing security vulnerabilities in open-source packages. It aggregates data from npm security advisories, GitHub Advisory Database, and community takedown records into a single unified format.

OSV covers 216,000+ vulnerability and malicious-package records across the npm ecosystem. Each record contains the affected package name, affected version ranges, severity, and a structured description of the threat.

Agentinel bundles a snapshot of the relevant npm subset of this database at publish time. When you npm install agentinel, the DB comes with it.

Local database bundling

The OSV data is stored as a compact binary index inside the Agentinel package. At scan time, Node.js reads this file from the local filesystem. There is no HTTP request, no CDN, and no DNS lookup.

The DB is updated each time you update the agentinel package itself. Running npm update agentinel pulls the latest OSV snapshot.

Version-exact matching algorithm

When Agentinel receives a package name and version string from an agent hook, it performs a two-pass lookup:

1. 1. Name lookup

   The package name is looked up in the OSV index. If no record exists, the package is clean from a vulnerability perspective (but may still trigger heuristics).

2. 2. Version range evaluation

   For each OSV record matching the package name, the requested version is tested against the affected version range using semver range evaluation. A match produces a BLOCK or WARN signal depending on mode.

The result of the matching algorithm is a structured decision object:

{
  "package": "react-router-v7-beta",
  "version": "1.0.0",
  "decision": "BLOCK",
  "source": "OSV_MATCH",
  "osvId": "MAL-2024-8821",
  "reason": "Package matches OSV malicious package record MAL-2024-8821"
}

Heuristic scanning layer

The OSV DB catches known malware. The heuristic layer catches unknown threats before they make it into OSV. These five signals run on every package scan, in parallel with the DB lookup.

Fail Open implementation

Every scan is wrapped in a top-level error boundary. If any part of the OSV lookup or heuristic evaluation throws an unexpected exception, the scanner catches it and emits an ALLOW decision with a warning written to stderr.

async function scanPackage(name: string, version: string): Promise<Decision> {
  try {
    const osvResult = await checkOsvDatabase(name, version);
    if (osvResult.matched) return { action: "BLOCK", source: "OSV_MATCH", ...osvResult };

    const heuristicResult = await runHeuristics(name, version);
    if (heuristicResult.flagged) return { action: "WARN", source: "HEURISTIC", ...heuristicResult };

    return { action: "ALLOW" };
  } catch (err) {
    process.stderr.write(`[agentinel] scan error: ${err}. Failing open.
`);
    return { action: "ALLOW", source: "ERROR_FAILOPEN" };
  }
}

Known limitations