AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

signals-scout-csp-violations

Signals scout for Content Security Policy violations. Watches `$csp_violation` events for blocked-URL clusters, per-directive bursts, post-deploy regressions, and suspicious third- party domains.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--signals-scout-csp-violations at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 1

SKILL.md · 24000

Almost always a single user with a misbehaving browser extension, or a bot probing the page. Skip — write a noise:csp_violations:<blocked_domain> scratchpad entry so future runs short-circuit.

Common skippable patterns:

  • chrome-extension:// / moz-extension:// / safari-extension:// blocked URLs
  • Brave / DuckDuckGo / privacy-browser injected scripts
  • about:blank, data: URIs from translation tooling or password managers

Disposition shift

Group by properties.$csp_disposition. A team running report-only for a long time and then flipping to enforce will see violations turn into actual blocks. If the project profile shows count for disposition='enforce' rising sharply (recent_24h_count materially above baseline) while report-only shows a corresponding fall, the team has flipped enforcement — write a pattern:csp_violations:disposition-flip scratchpad entry and file a report only if a critical page is suddenly seeing enforced blocks.

Policy improvement (advisory lenses)

The regression lenses above answer "did something change?". These three answer "could the policy be better?" — proactive findings, filed sparingly under the advisory conventions in Decide. They matter most for teams parked in report-only: the point of collecting violation reports is to eventually enforce, and these reports are the path there.

Enforcement readiness

The highest-value advisory report. For a directive running report-only, when a long window (~30 days) shows a closed set of blocked domains — every domain either vetted (allowlist: memory) or negligible-reach — the team can flip that directive to enforce. File a report with the exact policy delta (the allowlist additions required) and the measured blast radius: the distinct users and documents that would have been affected in the window had enforcement been on. Pull the current header the same way as any other policy-widen report, disposition filtered to report-only — the delta still needs a corroborated base. A directive is not ready while fresh unvetted domains keep appearing; record progress in pattern:csp_violations:enforce-readiness-<directive> instead and let it ripen.

Inline-script debt

The regression queries drop empty-domain violations (blocked_domain != '') as baseline noise — correct for triage, but it makes standing unsafe-inline / eval debt invisible. Periodically run a pass without that filter, scoped to the team's own documents: sustained inline/eval violation volume with broad reach is policy debt worth one report naming the top routes as nonce/hash migration candidates. The same lens covers overly-wide wildcards or missing directives when the violation shape reveals them.

Reporting noise budget

When a large share of the team's $csp_violation volume is structurally non-actionable — session-replay playback of third-party origins, self-hosted instances reporting against their own policies, browser-extension schemes — quantify it and file one report recommending how to scope the reporting endpoint or filter at ingestion, with the events/day saved. One-off per project: re-file only if the noise composition changes materially (track via report:csp_violations:advisory-noise-budget).

Save memory as you go

Memory is a continuous activity. Write a scratchpad entry whenever you observe something a future CSP run should know. Encode the "category" in the key prefix — pattern:, noise:, addressed:, dedupe:, allowlist: — so future runs find it with a single text= search:

  • key pattern:csp_violations:baseline — "Project's healthy $csp_violation baseline: ~800/day across ~120 distinct users, mostly img-src from *.googletagmanager.com and *.googlesyndication.com. Anything above 1.5× this baseline is fresh."
  • key allowlist:csp_violations:gtm — "*.googletagmanager.com, *.googlesyndication.com, *.doubleclick.net are the team's expected analytics/ads domains — known, vetted, do not re-surface."
  • key noise:csp_violations:chrome-extension-scheme — "Blocked URL pattern chrome-extension://* is a recurring browser-extension noise source for this team — skip unless disposition=enforce and effective_directive=script-src."
  • key addressed:csp_violations:cdn.suspicious.example.com — "Surfaced fresh script-src cluster from cdn.suspicious.example.com on 2026-05-12; team confirmed it was a legitimate new vendor, allowlisted in policy on 2026-05-13. Do not re-file unless the domain re-appears after policy was widened."
  • key dedupe:csp_violations:a1b2c3d4 — "Fingerprint a1b2c3d4... (script-src | evil.example.com/x.js | /checkout | bundle.js) — surfaced 2026-05-08, report still open in inbox, reach ~120 users/24h. If this exact fingerprint fires again at the same reach, re-confirm here (date + level) and skip; edit the report only on material movement (see Decide). Never author fresh while the report is live."
  • key report:csp_violations:<blocked_domain>-<directive> — the report_id of a report you filed for a cluster on this domain/directive, so the next run can re-find it instead of duplicating — and edit it only on material movement (see Decide), not to log an unchanged re-observation.
  • key reviewer:csp_violations:<area> — a resolved owner (bare lowercase GitHub login) for the security / frontend / policy surface, so reports route to a human faster.

By run #5 you'll have a per-team domain allowlist in the scratchpad, known browser-extension noise patterns, and the typical per-directive shape — and burn near-zero time on cold-start exploration.

Decide

The generic report mechanics — searching the inbox for your own prior reports (via the report:csp_violations:* pointer, else an inbox-reports-list search on the specific blocked domain / directive, not a broad word like script-src), edit-vs-author, the status rules, reviewer routing, the retry and cross-run deduplication rules, and the priority / repository fields — live in the harness prompt and in authoring-scouts → references/report-contract.md. Do not re-derive them here. This section is only the CSP judgment layered on top:

  • Edit when a still-live report already tracks the same domain/directive cluster and the picture moved materially — reach grew past the last noted level, disposition flipped report-only → enforce, a new document surface joined, or the verdict changed. (A new document page is reach, not a new entity: the cluster's identity is the domain/directive because the remediation is one policy change however many pages the block surfaces on — per-page reports for one blocked domain would fragment the inbox.) A persistent cluster is one report across runs, but it is not a run log: a window that merely confirms "still blocked, same reach" updates the dedupe: scratchpad entry (re-confirmed date + level), not the report — appending same-shape notes every tick drowns the report's original ask. A different blocked domain or directive is a different cluster: author fresh, never append it to a sibling's report.
  • Author when nothing live covers the cluster. A report-worthy finding names the blocked domain, the effective directive(s), the document URL(s), the distinct-user count, and a time range in the evidence, with an explicit lens (policy widen / compromise / vendor drift). Attach the domain's daily violation series via charts — for a fresh burst show the onset; a standing-enforced block has none, so show just its plateau over the observed window. Default to actionability=requires_human_input + repository=NO_REPO. A policy-widen finding can be PR-shaped, but two independent things must be trusted first, not one. The destination repo must be named by a trusted, human-authored source (a steering note, business knowledge, or a connected repository holding the policy — a headers config, a CSP template; never a repo inferred from telemetry). The blocked domain itself must be confirmed an intended dependency, by an allowlist: entry the team vetted, business knowledge, a steering note, or by being first-party / own-infra (the blocked host is the team's own surface). Reach never confirms that second one. The CSP report endpoint is public: anyone holding the project token can post crafted $csp_violation payloads and vary distinct_id until a domain they own clears the reach gates. Widening script-src or connect-src on that evidence hands an attacker the allowlist entry they wanted, through a draft PR nobody asked for. With both trusted, write the exact allowlist addition and file immediately_actionable with that repo. With only the repo trusted, it stays requires_human_input — say in the summary that the domain is unvetted and that vetting it is the gate. A third thing gates the delta: the header itself. Every policy-widen report carries the observed policy (nonces normalized, labelled by provenance) and names the directive actually doing the blocking — one that makes the reader go and find the policy is below the bar. But a corrected header only goes in when the domain is vetted and the observed header is corroborated against a trusted policy artefact; uncorroborated, it is a client-reported string an attacker can choose. See Read the policy from code, and reconcile. Every requires_human_input policy-widen report must hand off explicitly in the summary: who owns the policy, the exact directive change, and the success criterion (enforced violations for the domain at ~0 after the change, over a named window). The other two lenses get their own handoff, and never a directive delta. For a suspected compromise the safe action is to keep enforcement and remove or trace the injected source, so hand off the source file, the affected documents, and containment — proposing an allowlist addition there would allowlist the attack. For vendor drift the action is removing the caller, so hand off where the script is still loaded from. Both still need an owner and a success criterion; neither needs a policy widen. Priority: a disposition=enforce block on a script-src / connect-src directive with broad reach, or a suspected compromise, is P1–P2 (functionality broken / possible security incident); a policy-allowlist-gap or vendor-drift finding is P2–P3 by reach. After authoring, write the report:csp_violations:<domain>-<directive> pointer so the next run can re-find it (and edit only on material change).
  • Own-surface check before authoring. Violations name the document's deployment, and a project can receive reports from deployments its readers do not operate (self-hosted instances of the team's product, staging clones, third-party embedders). When the affected document hosts sit outside the surfaces this team runs, the reader cannot change that policy — never file a report asking them to. State the ownership boundary explicitly ("this policy is configured on <host>, which this team does not operate"), and name who does operate it where a trusted, human-authored source identifies them (a steering note, business knowledge, an account owner) — "someone else owns this" is not an owner, and a report with no named actor on either side of the boundary is below the bar. Then report only the action the reader can take: the same-shape gap appearing across two or more independent deployments suggests they inherit one default policy, template, or docs page. Matching violation shapes are the reason to go looking, not proof the shared artifact exists — identify it before filing, and name it (the file, template, or docs page a trusted source confirms those deployments inherit). A byte-identical normalized $csp_original_policy across those hosts is the strongest pointer you have that the artifact is real, so group by policy before you go looking — a pointer to check, not the confirmation itself, since forged reports can agree with each other. Can't find one, and the correlation is all you have? That's pattern: memory, not a report against a target you inferred. With the artifact identified, file one report against it, routed to whoever owns it, with the per-instance clusters as evidence and the same enforced-violation success criterion. A single foreign instance's own misconfiguration is pattern: memory, not a report.
  • Advisory reports (enforcement readiness / inline-script debt / noise budget) are priority=P3, actionability=requires_human_input, repository=NO_REPO, at most one report per category per week, and need broad reach (≥ 100 distinct users for an inline-script-debt finding). Write a report:csp_violations:advisory-<category> pointer after filing so the weekly cap holds across runs. These must be rarer and better-argued than incident reports — an advisory report a reviewer dismisses is a strong signal to raise your bar, not to rephrase and re-file.
  • Remember if below the bar but worth carrying forward (a fresh domain with only 3 distinct users — let it ripen), or to record what you ruled out.
  • Skip with a one-line note if a noise: / allowlist: / addressed: / dedupe: entry, or an existing inbox report, already covers it.

The push path is the key dedupe partner. The companion push emission (source_product=csp_reporting) already drops one raw signal per violation fingerprint into the same inbox. Cross-check it (inbox-reports-list filtered to source_product=csp_reporting) before authoring: your aggregated report should reference those raw signals as evidence (by fingerprint) rather than re-state them, and stay quiet when a single raw fingerprint already covers the whole story — author only when the aggregation adds cross-fingerprint context the push path can't see.

Close out

Summarize the run — one paragraph: looked at what, which reports you authored or edited, remembered what, ruled out what. The harness writes that summary to the run row as searchable prose; future runs read it via scout-runs-list. Do not write a separate "run metadata" scratchpad entry — the run summary already serves that role.

Disqualifiers (skip these)

  • Single user, single document, single fingerprint — almost always a personal browser extension or a niche client. Low count AND distinct_users ≤ 2.
  • Blocked URL scheme is chrome-extension:// / moz-extension:// / about: / data: — browser-side, not server-side; team can't fix.
  • Domain matches an allowlist: scratchpad entry — the team has already vetted this vendor; skip without re-surfacing.
  • disposition=report-only with no enforcement signal — the team is deliberately collecting violations to refine policy. File a regression report only when reach / freshness / domain novelty is exceptional. (Report-only data is still the input for an advisory enforcement-readiness report — see Policy improvement.)
  • Fingerprint matches a dedupe: scratchpad entry from an open inbox report — the push-emission path already covered it; don't double-up.
  • Team has no signal_source_config row for csp_reporting — push emission is off for this team. Scout can still find clusters, but the user signal is "team hasn't opted in to CSP signals yet"; raise the bar accordingly — require exceptional reach before filing.

When in doubt, write a memory entry instead of filing a report.

MCP tools

Direct calls (read-only):

  • execute-sql against events (filtered to event = '$csp_violation') — primary drill-down. Group by domain($csp_blocked_url), $csp_effective_directive, $csp_document_url, $csp_source_file, and $csp_original_policy (nonces normalized out). The full property list is in posthog/api/csp.py.

  • read-data-schema (kind: event_properties, event_name: '$csp_violation') — discover the team's actual $csp_* property surface and sample values.

  • advanced-activity-logs-list — pair burst timestamps with recent deploys or feature-flag changes for cross-source convergence. Inbox & reviewer routing (mechanics in authoring-scouts → references/report-contract.md):

  • inbox-reports-list / inbox-reports-retrieve — the reports already in the inbox. Check your own prior reports (source_product=signals_scout) so you edit instead of duplicating, and the push path's raw signals (source_product=csp_reporting) so you don't re-state a fingerprint it already covers.

  • inbox-report-artefacts-list — a comparable report's artefact log; reviewer precedent.

  • scout-members-list — the in-run roster for routing suggested_reviewers to a security / frontend / policy owner.

Harness-level:

  • scout-project-profile-get / scout-scratchpad-search / scout-runs-list / scout-runs-retrieve — orientation + dedupe.
  • scout-emit-report / scout-edit-report — author a report / edit an existing one (the report-channel contract is in the harness prompt).
  • scout-scratchpad-remember — remember.

When to stop

  • $csp_violation row in profile is at baseline and the standing enforced / first-party block check is clean → close out empty. A steady baseline alone is not enough — a standing high-reach enforced (or first-party) block is a live problem even with no fresh burst.
  • A candidate matches a scratchpad entry with noise: / allowlist: / addressed: / dedupe: key prefix, or an existing inbox report → edit-or-skip with a one-line note.
  • You've validated some hypotheses and filed reports for what's solid → close out, even if there's more you could look at. Fewer, better reports.

"Looked but found nothing meaningful" is a real outcome.

How this relates to the push-based CSP source

The companion push path (posthog/tasks/csp_signal.py, behind per-team SignalSourceConfig opt-in) emits one raw signal per unique violation fingerprint with a 24h Redis dedup TTL. That gives the inbox raw coverage of every fresh (directive, blocked_url, document_url, source_file) tuple, but per-fingerprint and without cross-fingerprint context.

This scout is the aggregation layer above it. Its reports should:

  • Bundle multiple raw fingerprints into a single aggregated report with shared root cause (one new domain across many pages, one deploy regression across many directives, one compromise pattern across many users).
  • Use the push path's existing signals as evidence in the report's body (referenced by fingerprint / source_id) rather than re-deriving them.
  • Stay quiet when the push path's coverage is sufficient — a single raw fingerprint already in the inbox does not need a parallel scout report unless the aggregation adds new context.