secutils-dev/secutils/csp

Secutils.dev: Content Security Policies

The CSP utility stores reusable Content Security Policy templates. Each template owns a set of directives keyed by directive name (e.g. default-src, script-src, style-src, frame-ancestors, upgrade-insecure-requests) and a list of source expressions. A template can be serialized into either an HTTP header value or an inline <meta http-equiv="Content-Security-Policy"> tag, and can be shared read-only through a tokenised URL.

Imports can either fetch a live policy from a remote URL (header or report-only header or meta tag) or parse a serialized policy string the user supplies directly. The serialized representation round-trips losslessly with the structured representation.

Guide: <https://secutils.dev/docs/guides/web_security/csp>. Full reference: <https://secutils.dev/api-docs/openapi.json>.

Endpoints (tag: web_security)

Authenticate with the Kratos session cookie or Authorization: Bearer su_ak_<token> (see secutils-api-keys).

Create-policy payload

POST /api/web_security/csp accepts ContentSecurityPoliciesCreateParams:

{
  "name": "my-csp",
  "content": {
    "type": "serialized",
    "value": "default-src 'self'; script-src 'self' https://cdn.example.com"
  },
  "tagIds": []
}

content is a tagged union driven by type:

Successful POST returns the created ContentSecurityPolicy including its normalised directives and computed enforcement metadata.

Serialize payload

POST /api/web_security/csp/{policy_id}/_serialize body:

{
  "source": "enforcingHeader"   // "enforcingHeader" | "reportOnlyHeader" | "meta"
}

Response:

{ "serialized": "default-src 'self'; script-src 'self' ..." }

For meta the serialised value is an HTML snippet, e.g. <meta http-equiv="Content-Security-Policy" content="default-src 'self'">.

Example flow (curl)

# Import the CSP that google.com sends in report-only mode
CSP=$(curl -sX POST https://secutils.dev/api/web_security/csp \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Google (report-only)",
    "content": { "type": "remote", "url": "https://www.google.com", "source": "reportOnlyHeader" },
    "tagIds": []
  }')
ID=$(echo "$CSP" | jq -r '.id')
 
# Render it as an HTML <meta> tag
curl -sX POST "https://secutils.dev/api/web_security/csp/$ID/_serialize" \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source":"meta"}' | jq -r '.serialized'

Caveats

• remote import follows redirects but does not execute JavaScript, so

CSPs injected only via inline scripts will not be discovered. Use the meta source on the rendered HTML when the live page sets the policy through <meta http-equiv>.

• Directive order is preserved on round-trip but source expression order

inside a directive is normalised to the canonical CSP grammar (keywords first, then schemes, then hosts).

• Sharing a CSP exposes only its directives, not its name or tags.
• To exercise a CSP end-to-end, pair this skill with secutils-webhooks:

create a responder that returns an HTML page with the policy's meta tag in <head> and request it from a browser.

See also

• Human-readable guide: <https://secutils.dev/docs/guides/web_security/csp>
• Related skill: secutils-webhooks (for hosting an HTML page that

serves the policy as a header or meta tag)

• OpenAPI: <https://secutils.dev/api-docs/openapi.json>