Deploying CSP: move from reports to controlled enforcement

What is a safe way to deploy Content Security Policy?#

A safe CSP deployment starts with the behavior your application legitimately needs, then narrows browser permissions around that behavior. The deployment is complete when users receive the intended enforcing policy, important workflows still operate, and the team can investigate a violation or restore the previous reviewed configuration. Copying a header from another site skips the dependency and delivery decisions that determine whether your policy is useful.

OWASP describes Content Security Policy as defense in depth and recommends HTTP response-header delivery for full policy capabilities. CSP can reduce the browser's ability to execute or load disallowed resources, but it does not repair an application vulnerability by itself. Keep server authorization, safe data handling and application fixes as their own responsibilities. Report-only observation also has a different status from active enforcement.

Inventory route families and interactions, including authenticated views, error pages, form submissions, uploads, external frames and requests made after a user action. For every outside dependency, name its purpose and owner. A help widget needed only by one workflow should not automatically expand permissions for the entire application. Review unnecessary dependencies before accommodating them in a policy.

Choose a script trust model the delivery path can maintain#

A nonce authorizes selected script elements using an unpredictable value that differs for each response. A script hash authorizes particular script content and must change when that content changes. MDN documents both models and the operational demands they place on dynamic and static delivery. The meaningful question is who produces the final HTML and can keep its script authorization consistent with the response policy.

For a dynamic application, identify the component that generates the nonce and inserts it only into intended scripts. For a static build, identify the build step that computes and publishes script hashes alongside the matching assets and headers. Do not choose a model merely because a framework example makes the first page render. Include route-specific scripts, lazy loading, error documents and third-party loaders in the review.

Define what trusting a script means. A trusted script can perform useful application work and may load additional code depending on the policy strategy. Assign responsibility for its content and dependencies. Broadly trusting a script loader to solve deployment friction is an architectural decision, not a harmless header adjustment. Record why that trust is required and how changes to the loader are reviewed.

Compare deployment choices before rollout#

Use this comparison to connect policy design to release ownership. The table describes implementation choices rather than complete ready-made policies. A deployment may use different mechanisms for separate route families, provided the team can explain which document receives which policy and verify the actual browser outcome.

Verify caches, headers and directive responsibilities#

Trace policy delivery through the origin, framework, reverse proxy, CDN and final browser response. Choose an authoritative configuration owner and check whether another layer adds a second policy. The W3C CSP specification explains that multiple policies are each applied; a more permissive second header does not simply override a restrictive first one. This matters during rollback and when infrastructure injects a policy independently of the application release.

Review directive responsibilities explicitly. The same specification defines form-action for form destinations and frame-ancestors for which parents may embed a document; those controls are not supplied by default-src fallback. A policy that restricts script sources alone leaves other browser decisions for separate review. Match each directive to the actual requirement instead of treating a long header as evidence of broad protection.

For nonces, reason about the document and header as one response unit. A cached document paired with a newly generated header can fail legitimate scripts because the values differ. Reusing a response-level nonce indiscriminately is a different problem. The safe deployment decision is to make generation, caching and any edge transformation explicit and test the combinations users receive, including cache hits and error paths.

Use report-only as an investigation stage#

Content-Security-Policy-Report-Only observes violations of a candidate without enforcing its restrictions. MDN documents reporting through report-to together with a Reporting-Endpoints header, while noting compatibility considerations and the deprecated report-uri mechanism. Select reporting behavior for the browsers the product supports. The presence of a report-only header must not be described as proof that the candidate restrictions are enforced.

Exercise representative workflows and group observations by route, effective directive, blocked resource and release. Investigate whether each group represents an essential dependency, an obsolete integration, an application change or environmental noise. Do not convert every report into an allowlist entry. A violation identifies a question about behavior, not an automatic permission requirement.

Give report handling an operational owner. A receiver accepting browser reports needs limits, access controls and a retention decision appropriate to its contents. Minimize diagnostic data and avoid collecting unnecessary sensitive page details. Reports are incomplete telemetry: browser settings, connectivity and support can affect delivery. Pair them with deliberate functional checks and browser observations so a quiet reporting dashboard is not mistaken for complete coverage.

Fictional worked example: a customer workspace with a hosted payment flow#

This fictional defensive example concerns Atlas Workspace, an invented application containing synthetic customer accounts. It renders authenticated dashboards dynamically, serves immutable assets through a CDN and embeds a hosted payment frame on one billing route. The team wants tighter browser permissions without disrupting sign-in, invoice creation or the payment flow. This is a proposed example, not evidence about a real client or a completed deployment.

The owner inventories three route families: public documents, authenticated workspace pages and billing. The dynamic application can coordinate nonce-bearing script elements with its response headers, while the static documentation build can publish reviewed hashes. The payment frame is required only for billing. An old support widget appears in the inventory but has no active owner or current requirement, so the team removes it from the proposed release instead of granting it application-wide access.

A report-only candidate is delivered in the owned test environment. The team checks fresh and cached responses, sign-in redirects, document upload, invoice validation and the hosted payment test mode. A billing report reveals a network call made after a user opens a payment dialog. The owner verifies that the call belongs to the approved payment integration, documents its purpose and adds the narrow requirement to the billing route's policy. It does not broaden every page because one workflow needs that connection.

The cache review finds that an edge layer could retain HTML independently of the header-producing application. The proposed fix treats nonce-bearing documents and policy generation as a coordinated delivery path. The release record includes a cache-hit test and a check of headers on error documents. A separate infrastructure-injected policy is also reviewed because it continues to apply alongside the application's header. The team tests the combined result, not just the source configuration.

The owner promotes the reviewed candidate through a controlled release with a named monitoring contact and a saved prior policy version. Functional checks confirm the legitimate flows and browser observations confirm enforcement. If the payment flow fails, the recovery procedure restores the last reviewed configuration at the responsible layer and identifies the unexpected dependency. It does not globally enable unrestricted script behavior. The handoff records the routes, supported browser checks, unresolved reports and evidence for the actual delivered policies.

Promote a candidate using explicit acceptance criteria#

Choose acceptance criteria before promoting the policy. The team should understand unresolved violation groups, have evidence for important allowed workflows and know which delivery layer can restore the reviewed previous configuration. A report-only period is useful when it answers those questions; simply waiting a fixed number of days does not establish readiness.

Verify the response users receive through the real delivery path. Compare the intended configuration with final headers and browser behavior, including authenticated routes, cache hits and failures. If public verification is unavailable, record deployment as unverified instead of treating a local preview as production evidence. Review headers and functionality together: a correctly delivered policy can still be too broad or incompatible with an important interaction.

• Map scripts, styles, images, frames, connection destinations and form actions for relevant route families.
• Name an owner and purpose for each outside resource or integration.
• Verify nonce or hash generation against the final HTML and release artifacts.
• Check cache hits, proxy additions, edge transformations and duplicate enforcing policies.
• Exercise sign-in, forms, uploads, frames, lazy-loaded features and error pages with owned test accounts.
• Confirm reports are triaged, access-controlled and retained only for the agreed diagnostic purpose.
• Verify final response headers and browser enforcement through the production delivery path when authorized.
• Test restoration of the prior reviewed policy and assign the recovery decision to a named owner.

Maintain dependencies instead of accumulating exceptions#

Treat a new dependency as a change to browser authority. The request should name the route, needed capability, owner and evidence that a narrower approach is insufficient. A growing collection of historical exceptions becomes difficult to reason about because the original requirement may no longer exist. Periodically compare the policy with the current dependency inventory and remove permissions whose purpose has ended.

Third-party scripts deserve particular scrutiny because a script is active application behavior, not merely an image hosted elsewhere. Review its necessity, delivery responsibility and ability to load further code. Where a product can replace a broad script with a simpler integration, CSP maintenance can become easier. Where the dependency is essential, make its trust and release monitoring explicit rather than promising the policy can neutralize every consequence of trusting it.

Keep development needs separate from released behavior. A development tool or debugging configuration may require permissions the production product does not. Verify the build and environment configuration so those permissions do not survive merely because they once resolved a local error.

State what the policy establishes and what remains to review#

CSP establishes a configured browser boundary on the documents that receive it, subject to supported behavior and the policy's actual permissions. It does not establish that the application's data flows are correct, that trusted code is harmless or that every route is covered. A header inspection cannot determine the full runtime dependency graph. A clean functional check cannot establish the absence of every injection flaw.

Begin with one consequential route family and an inventory the team can maintain. Choose the script strategy, verify coordinated delivery, observe the candidate and promote it with recovery ownership. Keep the intended policy, release revision, delivery evidence and known limits together. This creates a concrete next review when a dependency or framework changes, instead of an isolated security header whose purpose has been forgotten.