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_violationbaseline: ~800/day across ~120 distinct users, mostlyimg-srcfrom*.googletagmanager.comand*.googlesyndication.com. Anything above 1.5× this baseline is fresh." - key
allowlist:csp_violations:gtm— "*.googletagmanager.com,*.googlesyndication.com,*.doubleclick.netare the team's expected analytics/ads domains — known, vetted, do not re-surface." - key
noise:csp_violations:chrome-extension-scheme— "Blocked URL patternchrome-extension://*is a recurring browser-extension noise source for this team — skip unlessdisposition=enforceandeffective_directive=script-src." - key
addressed:csp_violations:cdn.suspicious.example.com— "Surfaced freshscript-srccluster fromcdn.suspicious.example.comon 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— "Fingerprinta1b2c3d4...(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>— thereport_idof 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 viacharts— for a fresh burst show the onset; a standing-enforced block has none, so show just its plateau over the observed window. Default toactionability=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 anallowlist: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_violationpayloads and varydistinct_iduntil a domain they own clears the reach gates. Wideningscript-srcorconnect-srcon 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 fileimmediately_actionablewith that repo. With only the repo trusted, it staysrequires_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. Everyrequires_human_inputpolicy-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: adisposition=enforceblock on ascript-src/connect-srcdirective 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 thereport: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_policyacross 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'spattern: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 ispattern: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 areport: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
countANDdistinct_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-onlywith 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_configrow forcsp_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-sqlagainstevents(filtered toevent = '$csp_violation') — primary drill-down. Group bydomain($csp_blocked_url),$csp_effective_directive,$csp_document_url,$csp_source_file, and$csp_original_policy(nonces normalized out). The full property list is inposthog/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 inauthoring-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 routingsuggested_reviewersto 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_violationrow 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.