Ask any web developer whether their site is GDPR-compliant for cookies and the answer is almost always the same: “Yes, we have a cookie banner.” That is not the same thing. A cookie banner is a user interface element. GDPR compliance is about what actually happens under the hood, specifically whether tracking cookies are set before a user clicks anything, whether those cookies are properly secured, and whether the site can actually prove what it is doing and why. Here’s why we had Cookie Audit in mind…
The gap between “we have a banner” and “we are compliant” is where most violations live. Analytics scripts that fire on page load regardless of consent. Marketing pixels that run before the user has seen the banner. Session cookies missing basic security flags that have been standard practice for a decade. These are not edge cases; they are the norm, and they are invisible unless you specifically look for them.
The problem is that looking for them manually is genuinely tedious. You open DevTools, go to the Application tab, inspect each cookie one by one, cross-reference the names against documentation for Google Analytics, Meta Pixel, HubSpot, and a dozen other platforms, check the flags on each one, and try to figure out whether the consent banner is actually blocking anything or just decorating the page. It takes time, it requires knowledge of a lot of different platforms, and it is easy to miss things.
We built cookie-audit to automate that entire process.
cookie-audit is an open-source command-line tool that opens any website in a headless browser, captures every cookie the page sets, classifies each one by vendor and purpose, checks for GDPR and ePrivacy compliance issues, and outputs a graded report in your terminal (or as JSON, CSV, or Markdown for client handoff).
👉🇫🇷 Read this article in french here | Lire cet article en français ici
👉🇮🇹 Read this article in italian here | Leggere questo articolo in italiani qui
What the tool actually does
When you run cookie-audit example.com, it launches a headless Chromium browser, navigates to the URL, waits for the page to fully load (including any JavaScript-rendered content), and then uses the Chrome DevTools Protocol to capture every cookie in the browser’s cookie store. This matters because it catches cookies set by third-party scripts, cookies set asynchronously after page load, and cookies injected by tag managers. All things that a simple HTTP header inspection would miss.
Once it has the full cookie list, it runs each one through a classification engine backed by a database of over 150 known cookies. The database covers:
- Analytics platforms: Google Analytics, Hotjar, Mixpanel, Amplitude, Segment
- Advertising and retargeting: Meta Pixel, Google Ads, LinkedIn Insight Tag, TikTok, Pinterest, Microsoft Clarity
- CRMs and marketing automation: HubSpot, Intercom, Drift
- E-commerce: Shopify, Stripe
- Infrastructure: Cloudflare
- Consent management platforms: Cookiebot, OneTrust, CookieYes, Complianz, Didomi, IAB TCF
Cookies that do not match the database are classified by heuristic (name patterns, domain, and lifetime), and any that remain unidentified are flagged as unknown for manual review.
After classification, the analyzer runs a set of compliance checks and produces a letter grade from A to F.
The compliance checks
This is the part that makes the tool useful rather than just informational. Knowing which cookies a site sets is interesting. Knowing which ones are breaking the rules is actionable.
The checks are organized by severity.
Critical issues are things that are likely GDPR violations. The most common one is non-essential cookies set before user consent: analytics and marketing cookies that appear in the initial page load, before the user has interacted with the consent banner at all. This is the most widespread cookie compliance problem on the web, and it is also the one that regulators focus on. The second critical issue is the absence of any consent mechanism on a site that sets tracking cookies (no banner, no CMP, nothing).
High severity issues cover security problems with the cookies themselves. A cookie missing the Secure flag can be transmitted over unencrypted HTTP connections. A session or authentication cookie missing the HttpOnly flag is accessible via document.cookie in JavaScript, which increases the attack surface for XSS exploits. Cookies with SameSite=None but no Secure flag will be silently rejected by modern browsers, which often causes subtle breakage that is hard to diagnose.
Medium severity issues include cookies with lifetimes exceeding 13 months (395 days), which exceeds the guidance from the French CNIL and several other EU data protection authorities. Third-party cookies are also flagged at medium severity given the ongoing browser restrictions. First-party cookies without a SameSite attribute are flagged for CSRF exposure.
Low severity issues are informational: unclassified cookies that need manual review for the cookie policy, and cookies scoped to the parent domain unnecessarily.
The grading logic is straightforward: any critical issue gives an F. Three or more high-severity issues gives a D. One or two high-severity issues gives a C. And so on down to A, which means no issues were found.
The consent scan
The most useful feature for compliance work is the -c flag, which runs a two-phase scan. In the first phase, the tool captures cookies exactly as they appear on initial page load, before any user interaction. In the second phase, it attempts to click the consent banner (it recognizes Cookiebot, OneTrust, CookieYes, Complianz, Didomi, Axeptio, Termly, IAB TCF banners, and generic “Accept all” buttons in English, Italian, French, German, and Spanish) and then re-scans to capture any additional cookies that appear after consent is granted.
The difference between the two phases is the actual test of whether a consent implementation is working. Cookies that appear only in the second phase are properly consent-gated. Cookies that appear in the first phase should be exclusively necessary cookies: session management, security tokens, load balancing. If analytics or marketing cookies appear in the first phase, the consent setup is broken, regardless of what the banner looks like.
cookie-audit example.com -c
Output formats
The default output is a formatted terminal table, useful for quick checks during development. For anything that needs to be shared or stored, there are three other formats.
| Format | Flag | Best for |
|---|---|---|
table |
default | quick terminal review during development |
json |
-f json |
feeding results into dashboards, scripts, or CI pipelines |
csv |
-f csv |
spreadsheet analysis, client handoff |
markdown |
-f markdown |
reports, documentation, Jira or Linear tickets |
The Markdown output is particularly useful for client-facing work. It produces a structured report with the compliance score, a summary table, each issue with its severity and remediation guidance, and a full cookie inventory. You can export it, paste it into Google Docs or Notion, add your branding, and send it as a deliverable.
cookie-audit clientsite.com -f markdown -o "ClientName - Cookie Audit - 2026-01.md"
Batch scanning
If you need to audit multiple URLs (a client’s main domain plus their blog, shop, and landing pages), you can either pass them as arguments directly or put them in a text file and pass the file path.
# Multiple URLs as arguments
cookie-audit site1.com site2.com site3.com -f csv -o audit.csv
# From a file
cookie-audit urls.txt -f json -o results.json
Lines starting with # in the file are treated as comments, so you can annotate the list. Each URL is scanned sequentially and the results are concatenated in the output file.
CI/CD integration
The tool returns exit code 0 when no critical issues are found, 1 when critical compliance issues are detected, and 2 on a fatal error. This makes it straightforward to add to a deployment pipeline as a compliance gate, similar to how you might use Lighthouse Dashboard for performance monitoring in your CI/CD workflow.
cookie-audit staging.example.com || echo "Cookie compliance check failed — review before deploying"
You can also use it programmatically as a Node.js module if you want to build the scan results into a custom dashboard or reporting workflow.
import { scan, classify, analyze, formatMarkdown } from "@dishine/cookie-audit";
const result = await scan("https://example.com", { waitMs: 5000 });
const classified = classify(result.cookiesBeforeConsent);
const report = analyze(result, classified);
console.log(formatMarkdown(report));
Getting started
The only requirements are Node.js 18 or later and an internet connection. Chromium is downloaded automatically by Puppeteer on the first run (about 300 MB, and it only happens once).
# Install globally
npm install -g @dishine/cookie-audit
# Or run without installing
npx @dishine/cookie-audit example.com
Run your first scan:
cookie-audit yoursite.com
If you want the consent scan:
cookie-audit yoursite.com -c
If you want a Markdown report saved to a file:
cookie-audit yoursite.com -f markdown -o report.md
The tool is open source and MIT licensed. The source code, issue tracker, and contribution guidelines are all on GitHub.
A few limitations
The consent scan works well with the major CMPs but is not guaranteed to click every banner correctly. Some custom implementations or heavily styled banners may not be recognized. In those cases you can use --no-headless to watch the browser in action and debug what is happening.
The tool scans a single page load. It does not crawl the entire site, so if different pages set different cookies (which is common on large sites with page-specific tracking tags), you will need to scan each relevant URL separately or use the batch mode.
The classification database covers the most common cookies but is not exhaustive. Unknown cookies are flagged for manual review rather than guessed at, which is the right behavior but means some manual work remains.
And finally, a passing grade from this tool is not a legal certification. It tells you what cookies are being set and flags the most common compliance issues. Whether your specific implementation satisfies the requirements of your jurisdiction is ultimately a question for a lawyer, not a CLI tool.
We build compliance and performance tools for digital consultants and agencies. If you want to learn more about our approach to AI-powered process auditing or our portable consulting toolkit, check out our other open-source projects.