@slashgear/gdpr-cookie-scanner 1.0.0

package/src/classifiers/network-classifier.ts

@@ -0,0 +1,65 @@
+import { TRACKER_DB, PIXEL_PATTERNS } from "./tracker-list.js";
+import type { TrackerCategory } from "../types.js";
+
+interface NetworkClassification {
+  isThirdParty: boolean;
+  trackerCategory: TrackerCategory | null;
+  trackerName: string | null;
+}
+
+export function classifyNetworkRequest(url: string, resourceType: string): NetworkClassification {
+  let hostname: string;
+
+  try {
+    hostname = new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return { isThirdParty: false, trackerCategory: null, trackerName: null };
+  }
+
+  // Check tracker database (exact match or suffix match)
+  for (const [domain, entry] of Object.entries(TRACKER_DB)) {
+    if (hostname === domain || hostname.endsWith(`.${domain}`)) {
+      return {
+        isThirdParty: true,
+        trackerCategory: entry.category,
+        trackerName: entry.name,
+      };
+    }
+  }
+
+  // Check pixel/beacon patterns in URL
+  if (PIXEL_PATTERNS.some((p) => p.test(url))) {
+    return {
+      isThirdParty: true,
+      trackerCategory: "pixel",
+      trackerName: "Tracking Pixel",
+    };
+  }
+
+  // Resource type heuristics
+  if (resourceType === "image" && isLikelyPixel(url)) {
+    return {
+      isThirdParty: true,
+      trackerCategory: "pixel",
+      trackerName: "Tracking Pixel (image)",
+    };
+  }
+
+  return {
+    isThirdParty: false,
+    trackerCategory: null,
+    trackerName: null,
+  };
+}
+
+/**
+ * Heuristic: 1x1 gif / tiny image with tracking params
+ */
+function isLikelyPixel(url: string): boolean {
+  const u = url.toLowerCase();
+  return (
+    (u.includes(".gif") || u.includes(".png")) &&
+    u.includes("?") &&
+    /[?&](uid|userid|sid|cid|vid|ts|t=|e=|ev=)/i.test(url)
+  );
+}

package/src/classifiers/tracker-list.ts

@@ -0,0 +1,105 @@
+import type { TrackerCategory } from "../types.js";
+
+interface TrackerEntry {
+  name: string;
+  category: TrackerCategory;
+}
+
+/**
+ * Known tracker domains and their categories.
+ * Based on open-source tracker databases (EasyPrivacy, Disconnect, DuckDuckGo Tracker Radar).
+ */
+export const TRACKER_DB: Record<string, TrackerEntry> = {
+  // ── Google ────────────────────────────────────────────────────
+  "google-analytics.com": { name: "Google Analytics", category: "analytics" },
+  "analytics.google.com": { name: "Google Analytics", category: "analytics" },
+  "googletagmanager.com": { name: "Google Tag Manager", category: "analytics" },
+  "googletagservices.com": { name: "Google Tag Services", category: "advertising" },
+  "googlesyndication.com": { name: "Google AdSense", category: "advertising" },
+  "doubleclick.net": { name: "Google DoubleClick", category: "advertising" },
+  "adservice.google.com": { name: "Google Ad Services", category: "advertising" },
+  "google.com/ads": { name: "Google Ads", category: "advertising" },
+  "googleadservices.com": { name: "Google Ad Services", category: "advertising" },
+  "pagead2.googlesyndication.com": { name: "Google PageAd", category: "advertising" },
+
+  // ── Meta / Facebook ───────────────────────────────────────────
+  "connect.facebook.net": { name: "Facebook SDK", category: "social" },
+  "graph.facebook.com": { name: "Facebook Graph API", category: "social" },
+  "facebook.com/tr": { name: "Meta Pixel", category: "advertising" },
+  "fbcdn.net": { name: "Facebook CDN", category: "social" },
+
+  // ── Microsoft ─────────────────────────────────────────────────
+  "bat.bing.com": { name: "Bing Ads", category: "advertising" },
+  "clarity.ms": { name: "Microsoft Clarity", category: "analytics" },
+  "ads.microsoft.com": { name: "Microsoft Ads", category: "advertising" },
+  "scorecardresearch.com": { name: "Scorecard Research", category: "analytics" },
+
+  // ── Hotjar ────────────────────────────────────────────────────
+  "hotjar.com": { name: "Hotjar", category: "analytics" },
+  "static.hotjar.com": { name: "Hotjar", category: "analytics" },
+
+  // ── LinkedIn ─────────────────────────────────────────────────
+  "snap.licdn.com": { name: "LinkedIn Insight Tag", category: "advertising" },
+  "platform.linkedin.com": { name: "LinkedIn", category: "social" },
+
+  // ── Twitter / X ──────────────────────────────────────────────
+  "static.ads-twitter.com": { name: "Twitter Ads", category: "advertising" },
+  "analytics.twitter.com": { name: "Twitter Analytics", category: "analytics" },
+  "t.co": { name: "Twitter URL shortener", category: "advertising" },
+
+  // ── TikTok ───────────────────────────────────────────────────
+  "analytics.tiktok.com": { name: "TikTok Analytics", category: "analytics" },
+  "ads-api.tiktok.com": { name: "TikTok Ads", category: "advertising" },
+
+  // ── Criteo ───────────────────────────────────────────────────
+  "dis.us.criteo.com": { name: "Criteo", category: "advertising" },
+  "rtax.criteo.com": { name: "Criteo Retargeting", category: "advertising" },
+  "static.criteo.net": { name: "Criteo", category: "advertising" },
+
+  // ── Segment / Amplitude / Mixpanel ───────────────────────────
+  "api.segment.io": { name: "Segment", category: "analytics" },
+  "cdn.segment.com": { name: "Segment", category: "analytics" },
+  "api2.amplitude.com": { name: "Amplitude", category: "analytics" },
+  "api.mixpanel.com": { name: "Mixpanel", category: "analytics" },
+
+  // ── Intercom / Drift / HubSpot ────────────────────────────────
+  "js.intercomcdn.com": { name: "Intercom", category: "analytics" },
+  "widget.intercom.io": { name: "Intercom Widget", category: "analytics" },
+  "hubspot.com": { name: "HubSpot", category: "analytics" },
+  "js.hs-scripts.com": { name: "HubSpot", category: "analytics" },
+  "drift.com": { name: "Drift", category: "analytics" },
+
+  // ── Fingerprinting ───────────────────────────────────────────
+  "fingerprintjs.com": { name: "FingerprintJS", category: "fingerprinting" },
+  "fpnpmcdn.net": { name: "FingerprintJS CDN", category: "fingerprinting" },
+
+  // ── Advertising networks ─────────────────────────────────────
+  "amazon-adsystem.com": { name: "Amazon Ads", category: "advertising" },
+  "pubmatic.com": { name: "PubMatic", category: "advertising" },
+  "rubiconproject.com": { name: "Rubicon Project", category: "advertising" },
+  "openx.net": { name: "OpenX", category: "advertising" },
+  "casalemedia.com": { name: "Casale Media", category: "advertising" },
+  "akamaized.net": { name: "Akamai", category: "cdn" },
+  "outbrain.com": { name: "Outbrain", category: "advertising" },
+  "taboola.com": { name: "Taboola", category: "advertising" },
+  "quantserve.com": { name: "Quantcast", category: "advertising" },
+  "chartbeat.com": { name: "Chartbeat", category: "analytics" },
+
+  // ── AB Testing ───────────────────────────────────────────────
+  "optimizely.com": { name: "Optimizely", category: "analytics" },
+  "vwo.com": { name: "VWO", category: "analytics" },
+  "app.convert.com": { name: "Convert", category: "analytics" },
+};
+
+/**
+ * Patterns for detecting tracking pixels and beacons by URL shape.
+ */
+export const PIXEL_PATTERNS: RegExp[] = [
+  /\/pixel(\.gif|\.png|\.php)?(\?|$)/i,
+  /\/beacon(\.gif|\.png|\.php)?(\?|$)/i,
+  /\/track(ing)?(\.gif|\.png|\.php)?(\?|$)/i,
+  /\/collect(\?|$)/i,
+  /\/event(\?|$)/i,
+  /\/(hit|ping|log)(\?|$)/i,
+  /\?.*(?:pixel|beacon|track|event|hit)=/i,
+];

package/src/cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { join, resolve } from "path";
+import { Scanner } from "./scanner/index.js";
+import { ReportGenerator } from "./report/generator.js";
+import type { ScanOptions } from "./types.js";
+
+const program = new Command();
+
+program
+  .name("gdpr-scan")
+  .description("Scan a website for GDPR cookie consent compliance")
+  .version("0.1.0");
+
+program
+  .command("scan")
+  .description("Scan a website and generate a GDPR compliance report")
+  .argument("<url>", "URL of the website to scan")
+  .option("-o, --output <dir>", "Output directory for the report", "./gdpr-reports")
+  .option("-t, --timeout <ms>", "Navigation timeout in milliseconds", "30000")
+  .option("--no-screenshots", "Disable screenshot capture")
+  .option("-l, --locale <locale>", "Browser locale for language detection", "fr-FR")
+  .option("-v, --verbose", "Show detailed output", false)
+  .action(async (url: string, opts) => {
+    console.log();
+    console.log(chalk.bold.blue("  GDPR Cookie Scanner"));
+    console.log(chalk.gray("  ─────────────────────────────────────"));
+    const normalizedUrl = normalizeUrl(url);
+    const hostname = new URL(normalizedUrl).hostname;
+    const outputDir = join(resolve(opts.output), hostname);
+
+    console.log(chalk.gray(`  Target : ${url}`));
+    console.log(chalk.gray(`  Output : ${outputDir}`));
+    console.log();
+
+    const options: ScanOptions = {
+      url: normalizedUrl,
+      outputDir,
+      timeout: parseInt(opts.timeout, 10),
+      screenshots: opts.screenshots !== false,
+      locale: opts.locale,
+      verbose: opts.verbose,
+    };
+
+    const spinner = ora("Launching browser...").start();
+
+    try {
+      const scanner = new Scanner(options);
+
+      spinner.text = "Loading page (before interaction)...";
+      const result = await scanner.run((phase) => {
+        spinner.text = phase;
+      });
+
+      spinner.succeed("Scan complete");
+      console.log();
+
+      const generator = new ReportGenerator(options);
+      const reportPath = await generator.generate(result);
+
+      console.log(
+        chalk.bold(
+          `  Compliance score: ${formatScore(result.compliance.total)} ${result.compliance.grade}`,
+        ),
+      );
+      console.log();
+
+      if (result.compliance.issues.length > 0) {
+        console.log(chalk.yellow(`  ${result.compliance.issues.length} issue(s) detected:`));
+        for (const issue of result.compliance.issues.slice(0, 5)) {
+          const icon = issue.severity === "critical" ? chalk.red("✗") : chalk.yellow("⚠");
+          console.log(`    ${icon} ${issue.description}`);
+        }
+        if (result.compliance.issues.length > 5) {
+          console.log(
+            chalk.gray(`    ... and ${result.compliance.issues.length - 5} more (see report)`),
+          );
+        }
+        console.log();
+      }
+
+      console.log(chalk.green(`  Report saved: ${reportPath}`));
+      console.log();
+
+      process.exit(result.compliance.grade === "F" ? 1 : 0);
+    } catch (err) {
+      spinner.fail("Scan failed");
+      console.error(chalk.red(`\n  Error: ${err instanceof Error ? err.message : String(err)}`));
+      if (opts.verbose && err instanceof Error && err.stack) {
+        console.error(chalk.gray(err.stack));
+      }
+      process.exit(2);
+    }
+  });
+
+program
+  .command("list-trackers")
+  .description("Show the built-in tracker database summary")
+  .action(async () => {
+    const { TRACKER_DB } = await import("./classifiers/tracker-list.js");
+    const categories = new Map<string, number>();
+    for (const entry of Object.values(TRACKER_DB)) {
+      const cat = entry.category;
+      categories.set(cat, (categories.get(cat) ?? 0) + 1);
+    }
+    console.log(chalk.bold("\n  Built-in tracker database:"));
+    for (const [cat, count] of categories.entries()) {
+      console.log(`    ${chalk.cyan(cat.padEnd(20))} ${count} domains`);
+    }
+    console.log(`\n  Total: ${Object.keys(TRACKER_DB).length} tracked domains\n`);
+  });
+
+program.parse(process.argv);
+
+function normalizeUrl(url: string): string {
+  if (!url.startsWith("http://") && !url.startsWith("https://")) {
+    return `https://${url}`;
+  }
+  return url;
+}
+
+function formatScore(score: number): string {
+  const colored =
+    score >= 80
+      ? chalk.green(score)
+      : score >= 60
+        ? chalk.yellow(score)
+        : score >= 40
+          ? chalk.hex("#FFA500")(score)
+          : chalk.red(score);
+  return `${colored}/100`;
+}