airgap.js as a Browser Security Control
How airgap.js enforces a browser-side network boundary, how it compares to a Content Security Policy, and where it fits in a security program.
Overview
This page is for security teams evaluating airgap.js. After reading it, you can decide how airgap.js fits next to your Content Security Policy (CSP), which settings to turn on, and what you still need from other tools.
A common question from security teams is: "If we write a strict CSP, do we still need a consent tool?"
Keep your CSP. airgap.js can generate one for you from your data flows and each user's consent. It also covers runtime behavior that a CSP header cannot express, such as consent state, request paths and query parameters, and navigations. In short, airgap.js is a browser-side network boundary that produces a CSP as a byproduct.
airgap.js protects its own state and APIs from other scripts on the page. See Privacy and Security for Consent for those self-protection controls.
Where a CSP stops
A CSP is a static allowlist that the browser enforces. That model has limits:
| Limit | What happens in practice |
|---|---|
| Not consent-aware | A CSP cannot change per user. Every visitor gets the same allowlist, whatever they consented to. |
| Host-level only | CSP sources match scheme, host, port, and path. They cannot match query parameters or regular expressions, so they cannot tell a safe request from a tracking request to the same host. |
| No navigation control | A CSP does not regulate top-level navigations, such as link clicks or location assignments. A script on an allowed host can still send data away by navigating the user to another site. |
| Maintenance cost | Every new vendor, subdomain, or property needs a header change and a deploy. Policies drift across sites and teams. |
| Hard to roll out | Third-party scripts load other scripts. Teams often cannot list every host they need until something breaks. |
What airgap.js does at runtime
airgap.js loads as the first script on the page. It inspects network requests, DOM insertions, cookies, and (optionally) navigations before they happen. It then allows, blocks, quarantines, or rewrites each one based on your rules. See Installing airgap.js for load order requirements.
Block unknown requests by default
Set your Unknown Request Policy to Block in Consent Management → Developer Settings. airgap.js then blocks requests to any host you have not classified in your data flows. This turns your data flow inventory into an allowlist.
With this policy, airgap.js keeps protections on for every user, including users who consented to all purposes. See the unknown request policy reference.
Regulate dynamic requests and injected scripts
airgap.js regulates requests at the JavaScript API and DOM level. This covers requests that scripts build at runtime, including:
fetch,XMLHttpRequest,navigator.sendBeacon,WebSocket,WebTransport,EventSource, and workers- Elements that scripts insert, such as
<script>,<img>,<iframe>,<link>, media, and forms - HTML strings written through
innerHTML,outerHTML,iframe.srcdoc, anddocument.write - Same-origin iframes and other same-origin windows, which airgap.js protects automatically
Rules can match full URLs, paths, query parameters, and regular expressions. A CSP cannot express these.
Generate a CSP from your data flows
When the Unknown Request Policy is Block, airgap.js adds a generated CSP to the page as a <meta> tag. The browser then enforces the policy for any request airgap.js does not see directly. airgap.js captures CSP violations and reports them in telemetry.
| Mode | Setting | What the CSP allows | Consent change |
|---|---|---|---|
| Lax (default) | data-csp="allow-known-hosts allow-subdomains" | All hosts classified in your data flows, and their subdomains | Takes effect with no page refresh |
| Strict | data-csp="strict" | Only hosts the user consented to | airgap.js refreshes the page |
| Off | data-csp="off" | No generated CSP | Not applicable |
Lax mode blocks hosts you have never reviewed. airgap.js still applies consent at runtime, so users can change consent without a refresh. Strict mode also blocks at the browser level for interfaces that airgap.js does not yet regulate directly, such as CSS and SVG subresources. See Content Security Policies for setup and the CSP protection reference for all options.
Browsers enforce every CSP on a page. If you also send a CSP header, a request must pass both policies. Add the Transcend hosts listed in Integrating with an existing CSP to your header.
Control navigations
Navigation control applies your request rules to navigations. This includes most link clicks, form submissions, location assignments, history navigations, and window.open(). You can allow, block, or rewrite each navigation before the browser commits it. For example, you can strip query parameters from cross-origin links or block navigations to hosts that are not on your list.
Set data-regulate-navigation="on" to enforce, or data-regulate-navigation="report-only" to log navigations in telemetry without blocking them.
Rewrite and inspect requests with overrides
Event overrides let your own code inspect and change requests, links, and navigations before they leave the page. Overrides run on the same engine as blocking and navigation control. Use them for rules that depend on page context, such as removing identifiers from a URL on checkout pages only.
Report before you enforce
Set data-report-only="on" to run airgap.js without blocking anything. airgap.js records the requests, cookies, and hosts it sees in telemetry, and does not generate a CSP. Use this mode to build an inventory before you turn on enforcement.
Security use cases
Payment page script control (PCI DSS 6.4.3 and 11.6.1)
PCI DSS 4.0 requirement 6.4.3 asks you to inventory every script on payment pages, authorize each one, and justify why it is there. Requirement 11.6.1 asks you to detect unauthorized changes to payment pages.
airgap.js helps with both:
- Telemetry lists every host that payment pages contact, including hosts that third-party scripts load at runtime.
- Block mode makes your data flows the authorized list. airgap.js blocks scripts and requests from hosts that are not on it.
- A new or unexpected host shows up in telemetry, which gives you a signal when a page starts loading something new.
A typical rollout on payment pages:
- Turn on report-only mode and collect telemetry.
- Classify every host you see in your data flows.
- Set the Unknown Request Policy to Block (lax CSP).
- Turn on navigation control on checkout pages.
- Review new hosts in telemetry as part of your change process.
airgap.js authorizes scripts by URL and host. It does not hash script contents or analyze what a script does. A compromised script on an allowed host can still run. Pair airgap.js with Subresource Integrity, a header-level CSP, and a script change-detection tool. Your Qualified Security Assessor (QSA) decides whether your combined controls meet each requirement.
Phishing and exfiltration through navigation
An attacker who gets code onto your page can send data out by navigating the user away. For example, a script can set location to an attacker URL with form data in the query string. A CSP does not block this.
With navigation control on, airgap.js treats each navigation as a regulated request. Navigations to unknown hosts are blocked, and overrides can strip data from the URL. Start with report-only to see where users go today, then enforce.
Inventory of internal and AI-generated apps
Internal tools, prototypes, and apps built with AI coding tools often add third-party requests that no one reviews. External scanners miss pages behind login and paths behind feature flags.
airgap.js runs in each real user's browser, so it sees authenticated pages and flagged features. Deploy it in report-only mode to build an inventory of every host these apps contact. Then move apps to Block one at a time.
Limitations
- Navigation control cannot intercept navigations that the browser UI starts, such as typing in the address bar or using the back and forward buttons.
- Most navigation coverage needs the Navigation API. Without it, navigation control covers only form submissions and
window.open(). - Navigation control can allow, block, or redirect a form submission. It cannot change the form data.
- Strict CSP mode refreshes the page when consent changes. Lax mode does not.
- The generated CSP allows inline scripts and
eval('unsafe-inline' 'unsafe-eval') so that existing site code keeps working. It limits where the page can connect. It does not replace a nonce-based or hash-basedscript-srcpolicy for cross-site scripting (XSS) defense. Keep that policy in your header. - The generated CSP is a
<meta>tag. Browsers ignore some directives in<meta>CSPs, such asframe-ancestorsandreport-uri. Send those in a header. - Browsers ignore CSP host sources that contain underscores. If a data flow host contains an underscore, add a rule for its parent domain.
- Without a strict CSP, airgap.js does not yet regulate CSS, SVG subresources, or ShadowRealms directly. See the regulation roadmap.
- airgap.js must load before other scripts. A script that runs before airgap.js is not regulated.
What you still need
airgap.js controls where the browser can connect. A complete client-side security program also needs:
- A header CSP with nonce-based or hash-based
script-src - Subresource Integrity for scripts you load from fixed URLs
- Behavioral analysis of third-party scripts, if you need to know what a script does on an allowed host
- Change records and audit evidence for compliance reviews