@sandcheck/core

Core lookup library for Sandcheck. Loads the curated compromised-package dataset, validates it against the JSON Schema, and resolves package@version queries against it.

This package is the shared library powering both the sandcheck CLI and the @sandcheck/mcp server. You can also consume it directly from your own tooling.

Install

pnpm add @sandcheck/core

Quick start

import { loadDatasetFromUrl, lookupPackage } from '@sandcheck/core';

const dataset = await loadDatasetFromUrl(); // canonical raw GitHub URL
const result = lookupPackage('some-package-name', '1.2.3', { dataset });

if (result.status === 'compromised') {
  for (const entry of result.entries) {
    console.error(`${entry.package}@${result.version} — ${entry.summary}`);
  }
}

API

• loadDatasetFromUrl(url?, options?) — fetch and validate the dataset. Defaults to the canonical raw GitHub URL.
• loadDatasetFromFile(path) — load and validate a local dataset file.
• validateDataset(data) — validate an already-parsed object against the JSON Schema.
• lookupPackage(name, version, { dataset }) / lookupMany(packages, { dataset }).
• detectAndParseLockfile(pathOrDir) — accepts either a project directory or a direct lockfile path / parsePackageLock / parsePnpmLock / parseYarnLock.

The dataset shape is described by schema/compromised.schema.json and the matching TypeScript types are exported from this package.

Security posture

No install-time lifecycle scripts. ESM only. Strict TypeScript.

Disclaimer

Provided "as is", without warranty of any kind. The dataset is a best-effort aggregation and may be incomplete, lag behind newly-disclosed compromises, or contain errors propagated from upstream sources. Use Sandcheck as one signal in your supply-chain hygiene, not the only one. To the maximum extent permitted by law, the maintainers and contributors are not liable for any damages arising from use of this library or its data. See the Apache-2.0 license for the full warranty and liability disclaimers.

License

Apache-2.0.