Repository navigation
docs: add user-facing security / defense-in-depth page - #22637
dodgeblaster wants to merge 1 commit into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. This is a documentation-only addition: it removes nothing, renders no UI, and each new claim matches the security invariants in AGENTS.md. Notes
[DESIGN-REVIEWED] 473a7d2 Description read[DESCRIPTION-READ] fdac9b818b144191d6ed3ee805c12b19fc90c3e374ff849b12577b9c07f5943e That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS This adds docs only, for a gap that issue #4748 records. The page ships no surface beyond itself and its index entries, so nothing blocks. Notes
What this change shipsInventory (3 items) — 2 justifiedIntent: give users one shipped page that explains how the security layers fit together and where they stop. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 473a7d2 Description read[DESCRIPTION-READ] e2b13bc5f6826a0ae560379298cb9867277e6cdb80f5bb2b0a923277de66c911 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
fd26825 to
df0f72f
Compare
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
df0f72f to
b22d627
Compare
|
self-added: no
|
|
self-added: no
|
b22d627 to
078ba9c
Compare
|
self-added: no
|
078ba9c to
04a810a
Compare
|
self-added: no
|
|
self-added: no
|
04a810a to
670ba36
Compare
|
self-added: no
|
|
self-added: no
|
f430098 to
47f95ed
Compare
|
self-added: no
|
|
self-added: no
|
buluoray
left a comment
There was a problem hiding this comment.
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:
REQUEST_CHANGES at 23f53af. Both points from the 47f95ed change request are fixed. Re-checked against current main (1929944), the page still makes two false statements about shipped security behaviour, so it should not merge as written. Auto-merge is armed, which means an approval here would merge it.
What it does for users: it gives one page that says what each protection covers and where it stops, including the defaults most people never change (approval auto, the standard sandbox tier, no egress boundary). That page is worth having.
Earlier change request, both items fixed:
- Default-tier exposure (
security-model.mdlines 189-201 and the first "Where the layers stop" bullet). The page now names~/.config/gh,~/.npmrc,~/.pypirc,~/.netrcand~/.git-credentialsnext to~/.aws,~/.sshand~/.kube, and saysstricthides them. This matches theagent.sandboxhelp text inconfig/sections_agent.py:496-506, including~/.sshkeeping onlyknown_hosts. network.egressscope ("no network egress control" bullet). It now covers web fetch, web search and the host an MCP call carries. That matchesplatform/governance.py:123-124(BUILTIN_TOOL_SCOPESmaps bothweb_fetchandweb_search) andgovernance.py:323(arg_scopesincludesnetwork.egressfor an@servergrant). The restart note foragent.approval_mode(lines 66-67) matchessections_agent.py:83-92(restart=True).
Blocking, false on current main:
-
A person can now override a denied-command rule (lines 77-80 and 83-84). The page says some command shapes are "refused outright at the gate, whether or not you have approved anything", and that approval "can never override a deny". #27574 (merged 2026-11-03) shipped an in-session override. When the
deny-rulestier refuses a shell command in a dashboard chat the owner is driving, the owner gets a card with Allow once, Allow for this session, or Deny. An allow re-judges the call with that one rule waived (dashboard/deny_override.py:1-26;docs/system-specs/modules/security.md, "A person's in-session override"). The page's trust andautoclaim still holds: a trust or YOLO sweep never answers the card. Self-guard rules (self-protection and credential-exfiltration categories), rules a governance policy pins, and overlay rules are never offered. Smallest fix: say that most denied-command rules can be waived by the owner's own click on the dashboard card, for one call or for that chat session (in memory, cleared on restart). Say which rules can never be waived: self-protection, credential-exfiltration, and policy-pinned ones. Keep the point that trust, YOLO andautonever route a deny through. A matching line in "Where the layers stop" would help, and a link to the override's user documentation if there is one. -
Windows default posture (lines 213-216, the limits bullet at 317-323, and the corporate-host advice at 346-348). I confirmed the open change request from KiroCrewCaptain on this head independently. On Windows, an undeclared
agent.sandbox_allow_unsandboxed_execresolves to allow (config/loader_document.py:44-56). KAS is the default chat harness. So KAS, MCP servers, hooks and script crons run with no OS confinement. They do not "take the refusal above", and they are not a delegated path either.docs/guides/windows-install.md:310and:376already say this. Theagent.sandboxhelp text (sections_agent.py:509-512) saysstrictchanges nothing on Windows, so "setstrictso a shell cannot read the credential directories" is false there. Smallest fix: say that under the Windows default, KAS and every subprocess that is not a Kiro CLI spawn run unconfined, and that only the Kiro CLI harness delegates. Repeat that once in "Where the layers stop". In the corporate-host bullet, saystrictdoes nothing on Windows and list the real options: the Kiro CLI harness, declaringagent.sandbox_allow_unsandboxed_exec=false, or a VM. Link the Windows install guide.
Other claims re-checked against main, and they hold:
- Trust root dispositions.
.envand.vaultare hidden (sandbox_leaves.py:155,sandbox_precreate.py:591).security_policy.json,denied_commands.jsonandconfig.jsonare read-only (sandbox_leaves.py:485,:493,:517).sel_hmac.keyand the event log stay read-write in every mode (sandbox_leaves.py:827-834), so the audit-key residual is stated accurately. - Audit fail-closed cases. Sandbox delegation refuses on an audit failure (
sandbox_delegation.py:542). Auto-approve activation and renewal refuse too (safety_override_grant.py:447,:610). A deny exception is granted only after itsdeny_exceptionwrite succeeds. No dashboard view of security events exists on main, so the "no dashboard to browse" limit is still true. - The ad-hoc YOLO grant lives in memory and a restart ends it (
safety_override.py:66-67). The approval default isauto.kirocrew policy explainexists (cli_parser_admin.py:243). Windows uses Job Object limits (pod/_windows_job.py). The page is indexed indocs/README.md:20anddocs/index.md:129, andscripts/docs-lint.shpasses on this head.
Non-blocking follow-ups:
- Lines 72-73: a declared grant re-arms at every start, so it does not clear on restart. That covers
gateway --approval yolo(since #31487) andagent.dangerously_skip_permissions. Also, on a managed host apermission_mode/approval_modesrule can turn Trust and Trust-reads off (#30692), so the trust options listed for interactive mode may not all be offered. One sentence each would cover it. - The trust-root paragraph says the files carrying a live credential are hidden.
.local_secret(the dashboard internal-API credential) andcrons.jsonstay readable and writable from a sandboxed shell (sandbox_leaves.py:835-841), like the audit key. Consider adding them to the audit-key residual. - Lines 46-48 say dashboard request auth and the Slack owner lock "are described further down", but the page never covers them. Link the dashboard and Slack pages instead.
- Line 159: "regardless of destination" is slightly too strong. A valid S3 presigned URL is exempt, and allowed hosts skip the length and base64 checks.
- A maintainer editorial sign-off on the limits and posture sections is still pending under the open hold.
What I checked and what I did not: this is a docs-only diff (three files, +378), so no mutation testing applies. Every claim above was checked by reading source at main 1929944. I did not exercise any Windows or macOS behaviour on a real host. CI on this head: 75 success, 17 skipped, 2 failure. Both failures are "Re-run Sensitive Change Review" runs, and PR Readiness is failing on 1 blocking item. git merge-tree against main is clean (exit 0).
23f53af to
9694938
Compare
|
Author's fix report for the two change requests on 23f53af. New head: 9694938 (rebased onto main 89530fe, still one commit, same three files). Auto-merge is now off, so a re-approval will not merge it by itself. 1. Denied-command override (buluoray, 11-08)
2. Windows default posture (KiroCrewCaptain, 11-07; confirmed by buluoray)
Optional items also taken
Not changed here: the
@buluoray @KiroCrewCaptain could you re-review on 9694938? |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Thanks for the quick turnaround. Most of my earlier change request is addressed on this head, but one remedy I suggested turns out to be wrong on current main. I have to ask you to undo that part.
Earlier items from my 11-07 review:
- Windows default posture (KAS, MCP servers, hooks and script cron jobs run unconfined;
strictdoes nothing on Windows): fixed at lines 235-248, 349-355 and 392-400. The remedy I proposed does not hold, though; see item 1 below. - Optional, "regardless of destination": fixed at lines 177-180.
- Optional, "described further down": fixed at lines 47-51 with links.
- Optional, "Fixes #4748" versus "Part of #4748": not changed and left to the maintainer. It is still worth a decision before merge.
Blocking:
security-model.mdlines 243-245, 352-353 and 395-396. A Windows user with a current kiro-cli follows the page and picks the Kiro CLI harness in Settings → Agent Harness to stay confined. The decision recorded indocs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.mdsays a stored Kiro CLI choice runs on the KAS path once the installed kiro-cli offers its v3 engine. The v3 default switch landed on 2026-11-02.agent_sdk/backends_launch.py(ACP_BACKENDS_RELAY_INTERNAL_SANDBOX) says Windows is not covered there, because the relay's KAS child runs unconfined. So the pick gives an unconfined KAS chat under the default. Underagent.sandbox_allow_unsandboxed_exec=falsethe chat is refused, not confined. I suggested this wording in my last review, and I was wrong about it.
Smallest fix: in all three places, say that a Kiro CLI pick delegates to kiro-cli's sandbox only while it stays on the v2 launch. Once kiro-cli offers v3, the pick runs on KAS, which is unconfined on Windows (or refused under the opt-out). That leaves declaringagent.sandbox_allow_unsandboxed_exec=false(which refuses unconfined spawns) or a VM as the Windows options.docs/guides/windows-install.mdmakes the same claim on main and needs the same fix. A maintainer should confirm the intended Windows story.
Optional:
- Lines 26-29 say the agent cannot read any crew file that carries a live credential.
.local_secretandcrons.jsonare sandbox-visible next tosel_hmac.key, so you could narrow that sentence or name them in the audit-key bullet. - Lines 205-207 and 306-308 repeat the standard-tier path list from Configuration → Sandbox, right after line 200 says those lists live in one place. A link would avoid drift.
- Several residuals (Windows posture, audit key, denied-command waiver) are written out in full two to four times. Stating each one fully once, in "Where the layers stop", would make later fixes like item 1 a single edit.
9694938 to
065864a
Compare
065864a to
50829a2
Compare
Code change approver recommendation: A person should decideWhy: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 430 lines, more than the 400 it may approve on its own. Docs-only PR adding a user-facing security-model page plus two index entries. Verified the load-bearing claims against code: standard tier leaves ~/.aws, ~/.ssh, ~/.kube, ~/.config/gh visible and _CC_FILES (.npmrc/.pypirc/.netrc/.git-credentials) masked only in cc/strict (sandbox_tiers.py); .env/.vault HIDDEN, policy/profiles/denied_commands.json/config.json READONLY, sel_hmac.key VISIBLE (sandbox_leaves.py); off = unconfined (sandbox_wrap.py); approval_mode default auto with restart=True; no CLONE_NEWPID; Windows KAS-unconfined posture matches windows-install.md; deny-override exclusions match rfc-deny-session-override.md; no denied-rule count restated; page is indexed. Where it is imprecise, it overstates the risk rather than the guarantee. CI failures (CodeQL rate limit, a sandbox cleanup timeout, coverage gate) are unrelated to a markdown-only change. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
Add src/kiro_crew/docs/security-model.md, a shipped user doc explaining the sandboxing / defense-in-depth model: the layers (approval, denied commands, filesystem gate, trust root, input validation, output redaction, OS sandbox, audit) with what each protects against, the governance ceiling, an explicit limits section (default tier leaves ~/.aws shell-readable, no default egress control, shared host process namespace, delegated-path residual, unprotected shell rc files), and host-vs-container posture guidance. Index it from README.md and index.md and cross-link the Security section. Fixes #4748
50829a2 to
473a7d2
Compare
|
Author's fix report for your 11-11 review (on 9694938). New head: 473a7d2, still one commit, same three files. Thanks for catching the remedy I had taken from your earlier review; you're right that it no longer holds on main. Blocking item 1, Kiro CLI pick on Windows I checked the claim on main before changing anything:
The three places now say:
Optional items: left for the maintainer pass. These are narrowing the trust-root sentence (or naming
@KiroCrewCaptain @buluoray could you re-review on 473a7d2? |
bolichen97
left a comment
There was a problem hiding this comment.
Re-reviewed the full page at 473a7d2. It's docs only, with no code changes, so I'm approving.
I checked each blocking point from the open change requests on this head:
- Denied-command override (#27574). "The one way past a denied-command rule is your own click on its override card" now replaces "can never override a deny". The new paragraph names Allow once / Allow for this session / Deny and the re-judge with one rule waived. It also says that a trust, YOLO or
autodecision never answers the card, and names the rules never offered (self-protection, credential-exfiltration, policy-pinned, overlay). A limits bullet says the same. This matchesdashboard/deny_override.py. - Windows posture. The page now says that under the Windows default, KAS and every subprocess that isn't a Kiro CLI spawn run unconfined, and that
strictchanges nothing there. That's in the delegation bullet, in "Where the layers stop", and in the corporate-host advice. - Kiro CLI pick (Captain's 11-11 point). All three places now say a Kiro CLI choice delegates only while it stays on the v2 engine and runs on KAS once kiro-cli offers v3. They name
agent.sandbox_allow_unsandboxed_exec=false(refuses, doesn't confine) or a VM as the Windows options, and link the Windows install guide. - The earlier optional points are in: the S3 presigned and allowed-host exemption replaces "regardless of destination", and the Dashboard / Slack / Apps links replace "described further down".
One optional point is still open and doesn't block: the trust-root sentence says the files carrying a live credential are hidden, while .local_secret and crons.json stay sandbox-readable, like the audit key. Naming them in the audit-key bullet would close it.
@buluoray, both blocking points from your 11-08 change request read as fixed on 473a7d2. Could you re-review when you have a moment?
|
This docs-only page now has no blocking findings. It still needs a maintainer decision before it can merge. buluoray's change request from 11-08 is still open, and the editorial pass on "Where the layers stop" and the posture sections that #4748 asks for has not been posted yet. A maintainer will post the decision here. My earlier review (11-11):
On this head, the review checked these claims against main and found them accurate: the Optional:
|
Withdrawn: every item in this review is fixed or answered on the current head (see the follow-up comment). Other holds on this PR are listed there.
|
[operator: bolichen97] Maintainer decision: the page is accepted with one required edit before merge: its credential redaction text must match main, where redaction became one owner switch that is off by default (#37408, merged 2026-11-16). Please also change Reason: apart from the redaction text below, the claims the reviews checked still hold on current main (539737a), and the items below are the calls the reviews left to a maintainer.
Optional, your call, not blocking: name After your push, the new head needs a maintainer's approval, and @buluoray's re-review (or a dismissal of the 11-08 change request), before it can merge. |
Problem / Motivation
Goal: Give users one shipped page that explains the security / defense-in-depth model — the layers, what each protects against, and where they stop.
Users could see a lot of work had gone into the automatic denials and the isolation layers, but there was no user-facing page explaining how the pieces fit together or where the limits are. The only such document,
docs/architecture/security-deep-dive.md, is contributor-oriented and is not shipped in the user docs undersrc/kiro_crew/docs/; the README carried only a bullet summary. That left users unable to reason about trust decisions — what is safe to allow on a corporate machine versus an isolated container.Why it matters
Without this, the decision of what to point Kiro Crew at is made blind. A page that is honest about the limits (the default tier leaves
~/.awsshell-readable, there is no default network egress control, the agent shares the host process namespace) is what lets a user tell a throwaway container apart from a corporate laptop and tighten the posture when it matters.Not a goal
security-deep-dive.md; this is the user-facing companion, grounded in it.What changed (motivation → approach → change)
Users had no shipped page on how the security layers fit together or where they stop, so a trust decision about the host was made blind. The approach is a new user doc that names each layer in plain terms, then spends a full section on the residuals, because the limits are what the decision actually turns on. The change adds
src/kiro_crew/docs/security-model.md— the approval, denied-command, filesystem-gate, trust-root, validation, redaction, OS-sandbox and audit layers, each with what it protects against; the governance ceiling; an explicit limits section; and host-vs-container posture guidance — and indexes it fromREADME.mdandindex.md, cross-linking the existing Security section.Every claim is grounded in
docs/architecture/security-deep-dive.mdand the code (the Linux sandbox uses user + mount namespaces and no PID namespace, so the shared-process-namespace limit is stated honestly; the default standard tier leaves~/.aws/~/.ssh/~/.kube/~/.config/ghand~/.npmrc/~/.pypirc/~/.netrc/~/.git-credentialsvisible, andnetwork.egressbounds Kiro Crew's own network tools, not a shell). Where the framing of a guarantee is a judgement call, the text keeps to facts and flags the limit rather than over-promising.For maintainer review: a security page's wording is a representation the project stands behind, and the triaging maintainer (dwu96) asked for a human editorial pass to own the limitations section and the host-vs-container guidance. Those two sections (
## Where the layers stop,## Choosing a posture for your host) are the ones to read with that in mind.Backwards compatibility
Compatible: documentation only; no contract, field, or behavior changes.
Removes nothing: no path, record, key, or function is hidden, deleted, or renamed; the change only adds a doc and two index entries.
Tests
N/A — documentation only.
scripts/docs-lint.shpasses (exit 0): the new doc is reachable from its index, every internal link resolves, and it adds no fact-check findings.Manual verification
Ran
scripts/docs-lint.shfrom the worktree — exit 0, no findings referencing the new file. Read the rendered doc for accuracy againstsecurity-deep-dive.mdand the sandbox code.Screenshots / video
Why no screenshot: This PR touches no frontend surface — it adds a Markdown doc under
src/kiro_crew/docs/and two index entries, with no rendered UI change.Related Issues
Fixes #4748
Checklist