@opencookies/scanner

Static AST detection of cookie writes and vendor scripts

Static cookie and vendor detection for OpenCookies. Scans your source for known third-party scripts and the cookies they (or your code) set.

The scanner is a pure library. The Vite plugin (@opencookies/vite) and the audit CLI (@opencookies/cli) are built on top of it.

Install#

bun add -D @opencookies/scanner

Usage#

import { scan } from "@opencookies/scanner";

const result = await scan({ cwd: process.cwd() });
console.log(result.cookies); // Cookie[]
console.log(result.vendors); // VendorHit[]
console.log(result.ungated); // Ungated[]

ScanOptions:

field	default	notes
`cwd`	required	the project root
`include`	`*/.{js,jsx,ts,tsx,vue,svelte,mjs,cjs,mts,cts}`	tinyglobby patterns
`exclude`	`node_modules`, `dist`, `.next`, `.svelte-kit`, `coverage`, `*.d.ts`	tinyglobby patterns
`rules`	every built-in rule	override to run a subset
`vendors`	bundled registry	override or extend the vendor list
`concurrency`	`os.availableParallelism()`	per-file workers

What it detects#

Rule	Pattern
`document-cookie`	`document.cookie = "..."`
`js-cookie`	`Cookies.set/...` from `js-cookie`
`cookies-next`	`setCookie(...)` from `cookies-next` or `nookies`
`react-cookie`	the setter from `useCookies()`
`next-headers`	`cookies().set(...)` from `next/headers`
`set-cookie-header`	`Set-Cookie` in a `Response` / `Headers` / `NextResponse`
`vendor-imports`	imports, dynamic imports, and global calls for the bundled vendor registry

The bundled vendor registry covers Google Analytics / Tag Manager, Meta Pixel, PostHog, Segment, Mixpanel, Hotjar, Intercom, LinkedIn Insight, Twitter/X Pixel, TikTok Pixel, Reddit Pixel, Sentry, and Datadog. Pass vendors: to extend or replace it.

Suppression comments#

// opencookies-ignore-next-line
document.cookie = "experiment=on";

// opencookies-ignore-file
// — placed in the first 10 lines, suppresses all hits in this file.

The "ungated" heuristic#

A hit is reported as ungated when the scanner cannot find evidence that it runs only after the user has consented. The heuristic is intentionally conservative — it favours false negatives over false positives.

A hit is treated as gated when any ancestor in its AST path is one of:

a JSX element named <ConsentGate>
an if / ternary whose test contains a .has(...) call (matches both consent.has("analytics") and cookies.has("session"))
a function named acceptAll, acceptNecessary, or any name beginning with set (catches the common setSessionCookie / setLocaleCookie shape)

This is not a control-flow analysis. Treat the ungated array as a "please double-check" list, not a definitive enforcement signal — the runtime is what enforces consent. See OpenCookies core for the runtime story.

Custom rules#

import { defineRule, scan, defaultRules } from "@opencookies/scanner";

const banPlausible = defineRule({
  name: "plausible-import",
  visit: (ctx) => {
    if (ctx.node.type !== "ImportDeclaration") return;
    const src = (ctx.node as { source?: { value?: string } }).source?.value;
    if (src === "plausible-tracker") {
      const { line, column } = ctx.position(ctx.node.start);
      ctx.report({
        file: ctx.file,
        line,
        column,
        vendor: "plausible",
        category: "analytics",
        via: "import",
      });
    }
  },
});

await scan({ cwd: process.cwd(), rules: [...defaultRules, banPlausible] });

Vendor registry contributions#

The bundled list lives in src/vendors.json. Each entry has the shape:

{
  "vendor": "stripe",
  "category": "payments",
  "imports": ["@stripe/stripe-js", "stripe"],
  "globals": ["Stripe"],
  "scriptUrls": ["https://js.stripe.com/v3/"]
}

PRs that add or correct entries are welcome. Please include a one-liner about the categorisation in your commit message; the categories are deliberately informal and align loosely with the GDPR/CCPA buckets the runtime uses.

Tests#

bun test (or vp test) runs:

per-rule fixtures under __fixtures__/rules/<rule>/
integrated synthetic projects under __fixtures__/projects/
hand-authored real-world snippets under __fixtures__/real-world/
a 1000-file synthetic perf assertion (must complete in under 2s)

OPENCOOKIES_REAL_WORLD=1 vp test additionally downloads pinned tarballs of Cal.com and Documenso into tests/real-world/.cache/ (gitignored) and runs the scanner against them, asserting zero false positives on a curated allowlist of known-clean files. The cache is reused across runs.

License#

Apache-2.0