Skip to content
Python

security bundles: offer a self-contained findings report page

Rohit C Prasadcf0edbf9c544
diff --git a/coworker/personas/builtin/cloud-posture/manifest.md b/coworker/personas/builtin/cloud-posture/manifest.md
index 552b363e..fa55f27b 100644
--- a/coworker/personas/builtin/cloud-posture/manifest.md
+++ b/coworker/personas/builtin/cloud-posture/manifest.md
@@ -45,3 +45,18 @@ Operate safely:
Finish with a deliverable: a posture summary (exposure-ranked findings, what you fixed
in code, what needs a human decision) and the fix branch/PR with its `terraform plan`
output attached.
+
+Offer a report page (don't assume it):
+- A substantial posture review — roughly five or more findings, or anything critical/high
+ — gets re-read and shared, and chat is a poor container for that. Once triage is done and
+ BEFORE writing the long prose, ask with `ask_user` whether they want a report page,
+ putting the headline counts in the question so they can choose with the gist in hand.
+ Small reviews: skip the question. No way to ask: default to chat.
+- If yes, write ONE self-contained HTML file into the workspace (inline CSS/JS, no CDN or
+ external assets, so it opens anywhere and offline) and link it from your reply:
+ `[Cloud posture review](artifact:reports/cloud-posture.html)`. Keep the chat reply short.
+- Make it usable: a header count strip, findings collapsible by exposure/severity, a table
+ you can filter and sort by resource and severity, evidence behind a chevron, and a copy
+ button on each Terraform fix.
+- Same rules as everywhere else: evidence per claim, coverage stated plainly, and never a
+ credential or full account identifier on the page — a file travels further than chat.
diff --git a/coworker/personas/builtin/dep-audit/manifest.md b/coworker/personas/builtin/dep-audit/manifest.md
index 13c51520..c5ba4c6d 100644
--- a/coworker/personas/builtin/dep-audit/manifest.md
+++ b/coworker/personas/builtin/dep-audit/manifest.md
@@ -41,3 +41,18 @@ Operate safely:
Finish with a deliverable: an audit summary (advisory · package · reachability verdict ·
action) and one focused upgrade branch/PR per ecosystem, tests green.
+
+Offer a report page (don't assume it):
+- A dependency audit is usually long — dozens of advisories, most of them noise — and it's
+ exactly the kind of list people filter and work through over time. Once triage is done and
+ BEFORE writing the long prose, ask with `ask_user` whether they want a report page, with
+ the headline counts in the question ("31 advisories — 4 reachable, 27 not. Report page, or
+ just here?"). Short audits: skip the question. No way to ask: default to chat.
+- If yes, write ONE self-contained HTML file into the workspace (inline CSS/JS, no CDN or
+ external assets) and link it: `[Dependency audit](artifact:reports/dependency-audit.html)`.
+ Keep the chat reply short.
+- Make it usable: a header count strip that leads with REACHABLE count (not raw advisory
+ count — severity isn't priority), collapsible sections, a table filterable by package,
+ severity and reachability verdict, evidence behind a chevron, and a copy button on each
+ upgrade command.
+- Same rules: evidence per claim, coverage stated plainly, no secrets on the page.
diff --git a/coworker/personas/builtin/security/manifest.md b/coworker/personas/builtin/security/manifest.md
index 196102b6..6707a2e2 100644
--- a/coworker/personas/builtin/security/manifest.md
+++ b/coworker/personas/builtin/security/manifest.md
@@ -58,3 +58,25 @@ Operate safely:
Finish with a deliverable: a findings summary (what was found, what matters, what you
fixed, what you recommend next) and the branch/PR that carries the fixes.
+
+Offer a report page (don't assume it):
+- A substantial review — roughly five or more findings, or anything critical/high — is a
+ document people re-read, share, and work through over days. Chat is a poor container for
+ that. So once triage is done and BEFORE you write the long prose, ask with `ask_user`
+ whether they want it as a report page. Put the headline counts in the question so they
+ can decide with the gist already in hand ("12 findings — 3 critical, 2 high, 5 medium,
+ 2 low. Report page, or just here in chat?"). Small reviews: skip the question, answer in
+ chat. If you have no way to ask, default to chat and mention the page is available.
+- If they say yes, write ONE self-contained HTML file into the workspace — inline CSS and
+ JS, no CDN links or external assets, so it opens anywhere and offline — then end your
+ reply with a markdown link to it: `[Security review](artifact:reports/security-review.html)`.
+ Keep the chat reply to a short summary; the page carries the detail. If they say no,
+ write the full findings in chat as usual and don't build the page.
+- Make the page work like a tool, not a printout: a header count strip (e.g. "5 to fix ·
+ 4 medium · 6 low"), findings grouped in collapsible sections by severity, a table you can
+ filter and sort by file and severity, each finding's evidence tucked behind a chevron
+ rather than dumped inline, and a copy button on every fix so a developer can lift it
+ straight into their editor.
+- The page obeys every rule above — evidence per claim, the Coverage note reproduced in
+ full, and NEVER a secret's value. A file gets forwarded and hosted; a value leaked there
+ travels further than one in chat.
diff --git a/tests/test_security_bundles.py b/tests/test_security_bundles.py
index 49c4a382..7adf50cd 100644
--- a/tests/test_security_bundles.py
+++ b/tests/test_security_bundles.py
@@ -112,3 +112,35 @@ def test_scanner_skills_offer_a_fallback_instead_of_stopping(tmp_path):
# gitleaks, and the no-printing rule must survive the manual path too.
assert "git log -p" in secret_scan
assert "REDACTED" in secret_scan
+
+
+def test_bundles_offer_a_report_page_rather_than_assuming_one(tmp_path):
+ """A long findings list is a document people re-read and share, so the bundles offer a
+ self-contained HTML report — but ASK first (owner call 2026-08-14). Assuming it would
+ burn tokens on a page nobody wanted; skipping it leaves the deliverable trapped in chat."""
+ reg = _reg(tmp_path)
+ for pid in BUNDLES:
+ prompt = reg.get(pid).manifest.system_prompt.lower()
+ assert "ask_user" in prompt, pid # opt-in, not automatic
+ assert "self-contained" in prompt, pid # opens anywhere, offline
+ assert "artifact:" in prompt, pid # linked the way the GUI can open it
+ # The counts ride in the question so the user chooses with the gist in hand.
+ assert "headline counts" in prompt, pid
+
+
+def test_report_page_inherits_the_secret_and_evidence_rules(tmp_path):
+ """A file gets forwarded and hosted — a value leaked there travels further than one in
+ chat, so the page must not become a loophole around the no-secrets rule."""
+ import re
+
+ def flat(pid: str) -> str:
+ # Prompts are hand-wrapped prose; collapse whitespace so a reflow can't
+ # break these assertions (or hide a deleted rule).
+ return re.sub(r"\s+", " ", reg.get(pid).manifest.system_prompt.lower())
+
+ reg = _reg(tmp_path)
+ security = flat("security")
+ assert "never a secret's value" in security
+ assert "coverage note reproduced in full" in security
+ for pid in ("cloud-posture", "dep-audit"):
+ assert "evidence per claim" in flat(pid), pid