Skip to content

docs: add user-facing security / defense-in-depth page - #22637

Open
dodgeblaster wants to merge 1 commit into
mainfrom
kc-wt-4748
Open

dodgeblaster wants to merge 1 commit into
mainfrom
kc-wt-4748

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

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 under src/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 ~/.aws shell-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

  • No code or behavior change — this is documentation only.
  • Not the dashboard Settings/Security surface cross-link into this page (a frontend change); this adds the doc and the in-docs indexing only.
  • Not a rewrite of the contributor 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 from README.md and index.md, cross-linking the existing Security section.

Every claim is grounded in docs/architecture/security-deep-dive.md and 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/gh and ~/.npmrc/~/.pypirc/~/.netrc/~/.git-credentials visible, and network.egress bounds 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.sh passes (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.sh from the worktree — exit 0, no findings referencing the new file. Read the rendered doc for accuracy against security-deep-dive.md and 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

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality (N/A — docs only; docs-lint green)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 473a7d22e811016492ec1fcaf3197a9626afd232 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 473a7d22e811016492ec1fcaf3197a9626afd232 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • This page restates sandbox residuals that change often, such as the sel_hmac.key visibility and the standard-tier credential dirs. Add it to the "Read first" row for security//sandbox.py in AGENTS.md, so a change to a disposition has to update this page in the same commit. Otherwise the user-facing promise drifts out of date without anyone noticing.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 473a7d22e811016492ec1fcaf3197a9626afd232 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 1 — oversized: the page describes the Windows unconfined-KAS posture three times, at diff lines 276–297, 393–401 and 441–445. It describes "delegated path, masks do not apply" twice, at diff lines 294–297 and 409–415. Each copy is another place that has to be updated when that behaviour changes. Subtraction: keep each fact once, under ## Where the layers stop, and replace the other copies with the #where-the-layers-stop anchor link the page already uses.

What this change ships

Inventory (3 items) — 2 justified

Intent: give users one shipped page that explains how the security layers fit together and where they stop. This is an ADDITION.

  1. New user doc security-model.md covering the layers, the governance ceiling, the limits and posture guidance — oversized (the same residuals are restated within the page)
  2. The page is listed in the docs README table and the index's Doc list — justified
  3. The index's Security section links to the new page — justified

[FIRST-PRINCIPLES-REVIEWED] 473a7d2

Description read

[DESCRIPTION-READ] e2b13bc5f6826a0ae560379298cb9867277e6cdb80f5bb2b0a923277de66c911

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 473a7d22e811016492ec1fcaf3197a9626afd232 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 473a7d2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 473a7d22e811016492ec1fcaf3197a9626afd232 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 473a7d22e811016492ec1fcaf3197a9626afd232 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 473a7d2

Verdict parsed from the review's SHA-scoped output markers for commit 473a7d22e811016492ec1fcaf3197a9626afd232.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 473a7d22e811016492ec1fcaf3197a9626afd232 false-positive: <reason, 20 to 500 characters>

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • sel_hmac.key / ceiling-file dispositions overstated (span=e1c23f82a176)

fixed in df0f72f. Verified against sandbox_leaves.py: security_policy.json, profiles and denied_commands.json are in _CREW_READONLY_LEAVES (readable by a sandboxed shell, not writable — hiding a ceiling resolves it to the permissive default), and sel_hmac.key is in _CREW_SANDBOX_VISIBLE_LEAVES (AGENTS.md records it as a knowingly-carried VISIBLE residual, readable AND writable in every mode). The trust-root section now states read-only vs hidden per leaf; the audit section and a new Where-the-layers-stop bullet state the HMAC key is not OS-fenced, so audit-chain forgery from inside the agent is possible. The "cannot read or write" claims at the intro and governance are corrected to "cannot write (can read)".

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • trust root overstated in a shipped security page (span=838bef99bc90)

fixed in df0f72f. The trust-root section now gives each leaf its real disposition: credential .env and the secret vault are HIDDEN (not readable); the governance policy/profiles, denied-command state and runtime config are READ-ONLY (readable by a shell, not writable, because hiding a ceiling resolves it to the permissive default); and the SEL HMAC key is called out as VISIBLE/unfenced. The audit section no longer implies the chain cannot be forged from inside the agent, and the HMAC-key residual is added to Where the layers stop. This matches sandbox_leaves.py (_CREW_READONLY_LEAVES / _CREW_SANDBOX_VISIBLE_LEAVES) and AGENTS.md.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • per-tier path lists duplicated configuration.md (span=ac34c79c62a0)

fixed in df0f72f. Removed the per-tier directory lists from the OS sandbox section; security-model.md now points to configuration.md as the single place that enumerates which paths each tier hides, and keeps only the behavioural point (standard leaves /.aws//.ssh/~/.kube visible; strict masks them). No fourth copy, nothing to drift.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • command-gate limit restated blocked-commands.md (span=6afc8b236075)

fixed in df0f72f. Condensed the denied-command limit to one sentence (the gate reads the command line, so a program the line only names is not matched) plus the defense-in-depth framing, and deferred the "why it is deliberate / friction not a fence / no number of patterns" argument to the blocked-commands.md link it already carries. The near-verbatim restatement is gone.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • filesystem gate wrongly credited with covering shell cat / open() (span=e1c23f82a176)

fixed in b22d627. Correct — the path tier skips shell command text (_is_exempt_command_text) and is_sensitive_bash_command has no path matcher, so a cat / python -c open() is NOT caught by the filesystem gate. Rewrote the sentence: the gate covers every file-read/file-edit TOOL regardless of how it opens the file, and the limit paragraph now states explicitly that a raw shell cat / python -c open() is not path-matched (nor by the command gate) and is the OS sandbox's job. This matches blocked-commands.md and security-deep-dive.md.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • sandbox section only mentioned Windows delegation, contradicting the limits section (span=38fcc1b42a9d)

fixed in b22d627. The OS sandbox section now says delegation happens on BOTH Windows (no Crew backend) and macOS (when kiro-cli internal sandbox is enabled, since the two seatbelt sandboxes cannot nest — verified against sandbox_delegation.py: delegated = sys.platform=="darwin" and kiro_internal_sandbox_enabled(), EPERM on nesting). The two sections now agree that on any delegated path Crew's credential masks do not apply.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • "un-disableable from inside the agent" overstated; the seal is absent when the sandbox is off (span=e1c23f82a176)

fixed in 078ba9c. Correct — the read-only write seal is a Kiro Crew sandbox bind, and wrap_argv returns argv unconfined under mode=="off" and on the no-backend path (Windows), so a shell can write the ceiling again there. Qualified the claim to "wherever the Kiro Crew sandbox is active" and added the caveat that off / unconfined paths restore writability, so an enterprise host pins it via the governance sandbox.min_level floor (verified: _clamp_sandbox_mode_to_floor overrides the config opt-in).

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • default approval mode stated backwards: shipped default is auto, not prompt (span=e1c23f82a176)

fixed in 04a810a. Correct — AgentConfig.approval_mode defaults to "auto" (sections_agent.py; configuration.md row confirms default "auto"), which auto-approves. The Interactive-approval section now leads with that: the default auto approves tool calls, and interactive is the opt-in (agent.approval_mode="interactive"). The layers-table row and the corporate-host posture guidance are corrected to match (set interactive to get prompts), and the YOLO sentence no longer conflates the ad-hoc escalation with the config default.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • "agent config cannot weaken the gate" overstated for the Claude backend (span=e1c23f82a176)

fixed in 04a810a. Correct — the Claude backend seeds permissions.deny from the agent spec (client_claude_seed.py), so backend-native tool permissions do come from config. Narrowed the structural claim to the denied-command + governance tier (which is Kiro Crew's own, gateway-enforced, un-weakenable by agent config), and added that an ACP backend's native tool permissions are configuration like any other, so Kiro Crew's gate is the floor rather than a wrapper around every capability the harness exposes.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • delegated-path bullet wrongly credited the command gate with covering credential directories (span=e1c23f82a176)

fixed in 670ba36. Correct — security/paths.py:627 states the command gate does NOT match paths in command text, so it does not cover a credential DIRECTORY. Rewrote the bullet: on the delegated paths a credential directory is covered by the file-tool gate (for file tools) and the delegated sandbox itself, not the command gate, with redaction still scrubbing credentials that reach output.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • pinned command categories stated as a fixed set rather than policy-derived (span=e1c23f82a176)

fixed in 670ba36. Correct — pins come from the governance policy commands-scope (denied_rules.pinned_builtin_command_ids), not a hardcoded category set. The wording I used was lifted from blocked-commands.md; I removed the specific category list, now say the policy pins denied-command rules (which ones set by the commands scope, tightest-wins) and defer the typical-category detail to blocked-commands.md. This also drops the duplication that kept drawing precision findings.

@dodgeblaster
dodgeblaster force-pushed the kc-wt-4748 branch 2 times, most recently from f430098 to 47f95ed Compare October 29, 2026 22:44
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • computer use described as outside governance despite the capabilities.computer_use key (span=e1c23f82a176)

fixed in 47f95ed. Correct: enable_state.is_enabled() ANDs the opt-in with locked_by_policy(), which calls policy_permits("capabilities.computer_use"). The page now says governance reaches computer use through that one on/off key (enterprise build off until a policy enables it) and that nothing finer (apps, actions, approval) is governed; the Related bullet says the same.

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

self-added: no

  • network.egress offered as a bound on arbitrary agent egress (span=e1c23f82a176)

fixed in 47f95ed. Correct: governance_parts/tool_calls.py maps only kind=fetch (url) to network.egress, and the governance spec says it governs the dedicated fetch tool only; a shell curl is classified under commands. The residuals bullet now says network.egress bounds only the fetch tool, shell/subprocess traffic is governed only by commands patterns, and a network namespace or host firewall is still needed for a real boundary.

@dodgeblaster
dodgeblaster marked this pull request as ready for review October 29, 2026 23:31
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners October 29, 2026 23:31

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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:

  1. Default-tier exposure (security-model.md lines 189-201 and the first "Where the layers stop" bullet). The page now names ~/.config/gh, ~/.npmrc, ~/.pypirc, ~/.netrc and ~/.git-credentials next to ~/.aws, ~/.ssh and ~/.kube, and says strict hides them. This matches the agent.sandbox help text in config/sections_agent.py:496-506, including ~/.ssh keeping only known_hosts.
  2. network.egress scope ("no network egress control" bullet). It now covers web fetch, web search and the host an MCP call carries. That matches platform/governance.py:123-124 (BUILTIN_TOOL_SCOPES maps both web_fetch and web_search) and governance.py:323 (arg_scopes includes network.egress for an @server grant). The restart note for agent.approval_mode (lines 66-67) matches sections_agent.py:83-92 (restart=True).

Blocking, false on current main:

  1. 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-rules tier 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 and auto claim 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 and auto never 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.

  2. 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_exec resolves 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:310 and :376 already say this. The agent.sandbox help text (sections_agent.py:509-512) says strict changes nothing on Windows, so "set strict so 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, say strict does nothing on Windows and list the real options: the Kiro CLI harness, declaring agent.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. .env and .vault are hidden (sandbox_leaves.py:155, sandbox_precreate.py:591). security_policy.json, denied_commands.json and config.json are read-only (sandbox_leaves.py:485, :493, :517). sel_hmac.key and 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 its deny_exception write 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 is auto. kirocrew policy explain exists (cli_parser_admin.py:243). Windows uses Job Object limits (pod/_windows_job.py). The page is indexed in docs/README.md:20 and docs/index.md:129, and scripts/docs-lint.sh passes 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) and agent.dangerously_skip_permissions. Also, on a managed host a permission_mode / approval_modes rule 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) and crons.json stay 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).

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

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)

  • security-model.md:81-84: approval, trust, YOLO and auto never route a deny through; the only way past a denied-command rule is the owner's own click on the override card.
  • security-model.md:95-107: new paragraph. When a deny-rules refusal hits a shell command in a dashboard chat the owner is driving, the card offers Allow once / Allow for this session / Deny. An allow re-judges with only that rule waived, each waiver is audited (refused if the write fails), and the session waiver lives in memory for that chat and ends with the chat or a gateway restart. Trust, YOLO and auto never answer the card, and app, cron and channel chats get none. Self-protection, credential-exfiltration, policy-pinned and overlay rules are never offered. Checked against dashboard/deny_override.py:1-26 and docs/system-specs/modules/security.md ("A person's in-session override").
  • security-model.md:357-361: matching line in "Where the layers stop".
  • There is no user-facing doc for the override under src/kiro_crew/docs/ yet (grep for the card labels finds none), so there is nothing to link.

2. Windows default posture (KiroCrewCaptain, 11-07; confirmed by buluoray)

  • security-model.md:235-248: the delegation bullet now says only an official Kiro CLI spawn delegates. KAS, the default chat harness, and MCP servers, hooks and script crons run unconfined under the Windows default, because an undeclared agent.sandbox_allow_unsandboxed_exec resolves to allow (config/loader_document.py unsandboxed_exec_platform_default(); DEFAULT_ACP_BACKEND = ACP_BACKEND_KAS in agent_sdk/backends.py). They take the refusal only once =false is declared, which also refuses a KAS chat, and strict changes nothing on Windows (config/sections_agent.py agent.sandbox help text). The bullet links the Windows install guide.
  • security-model.md:349-355: the point is repeated once in "Where the layers stop".
  • security-model.md:392-400: the corporate-host bullet scopes strict to Linux and macOS, says it does nothing on Windows, and lists the options you gave: the Kiro CLI harness, declaring agent.sandbox_allow_unsandboxed_exec=false, or a VM, with a link to the Windows guide.

Optional items also taken

  • :47-51: dashboard auth, the Slack owner lock and apps now link dashboard.md, slack-integration.md and apps.md instead of saying they are "described further down".
  • :177-180: "regardless of destination" is narrowed. The credential check applies to any destination, a valid S3 presigned URL is exempt (security/exfil_url_rules.py _is_safe_presigned), and an allowed host skips the length and base64 checks.
  • :76-78: a declared YOLO grant (gateway --approval yolo, agent.dangerously_skip_permissions) is installed again at every start (safety_override.py module docstring).

Not changed here: the Fixes #4748 → Part of #4748 question, and the managed-host trust-mode and .local_secret / crons.json notes. Those are left for the maintainer pass.

scripts/docs-lint.sh passes on this head. The wording sign-off on the limits and host-versus-container sections, asked for in the crew-pr-reviewer hold, is still with a maintainer.

@buluoray @KiroCrewCaptain could you re-review on 9694938?

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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; strict does 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:

  1. security-model.md lines 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 in docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md says 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. Under agent.sandbox_allow_unsandboxed_exec=false the 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 declaring agent.sandbox_allow_unsandboxed_exec=false (which refuses unconfined spawns) or a VM as the Windows options. docs/guides/windows-install.md makes 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_secret and crons.json are sandbox-visible next to sel_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.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 14, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 14, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 50829a28f5 · 430 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 14, 2026
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
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

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:

  • docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md: a stored "kiro" backend runs on the KAS path once the installed kiro-cli offers its v3 engine. It keeps the v2 Kiro CLI launch only when kiro-cli lacks v3 (or the check, the bundle route or a policy keeps it there).
  • agent_sdk/backends_launch.py, the comment above ACP_BACKENDS_RELAY_INTERNAL_SANDBOX: Windows is not covered, because the relay's KAS child runs unconfined there (measured on kiro-cli 2.35.1).

The three places now say:

  • security-model.md:234-249 (delegation bullet): only a Kiro CLI spawn on its v2 engine delegates. Once kiro-cli offers v3, a Kiro CLI choice runs on KAS, which kiro-cli does not confine on Windows. Declaring agent.sandbox_allow_unsandboxed_exec=false refuses that chat rather than confining it.
  • security-model.md:351-359 ("Where the layers stop"): a Kiro CLI choice delegates only while it stays on v2; on v3 it is unconfined too.
  • security-model.md:396-402 (corporate-host bullet): the Kiro CLI harness is no longer listed as a Windows option. The options left are declaring agent.sandbox_allow_unsandboxed_exec=false (which refuses unconfined spawns, KAS chat included) or a VM.

docs/guides/windows-install.md makes the same claim on main. It is outside this PR's three files, so I've drafted a separate issue for it rather than widening this change. As you say, a maintainer should confirm the intended Windows story.

Optional items: left for the maintainer pass. These are narrowing the trust-root sentence (or naming .local_secret and crons.json next to the audit key), replacing the repeated tier path lists with a link, and stating each residual once. The same goes for Fixes #4748 versus Part of #4748.

scripts/docs-lint.sh and the brand gate pass on this head.

@KiroCrewCaptain @buluoray could you re-review on 473a7d2?

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 14, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 auto decision never answers the card, and names the rules never offered (self-protection, credential-exfiltration, policy-pinned, overlay). A limits bullet says the same. This matches dashboard/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 strict changes 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?

@bolichen97
bolichen97 enabled auto-merge (squash) November 14, 2026 08:28
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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 auto approval default, the standard-tier credential paths, the HIDDEN / READONLY / VISIBLE trust-root split, the deny-override eligibility rules, the Windows KAS posture, and audit-or-deny on delegation. Every link and anchor resolves. The page also states the uncomfortable defaults plainly instead of softening them.

Optional:

  • Line 152: the trust-root caveat names off and unconfined Windows, but a spawn delegated to kiro-cli's own sandbox also skips Kiro Crew's read-only seal. configuration.md already lists that third case.
  • Line 361: the deny-override residual could add that agent.deny_override=false keeps every denied-command rule a flat refusal with no card.
  • "Part of docs: User-facing sandboxing / defense-in-depth documentation #4748" would keep the Settings/Security and root README cross-links tracked, since this PR does not deliver them.

@KiroCrewCaptain
KiroCrewCaptain dismissed their stale review November 14, 2026 08:41

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.

@bolichen97
bolichen97 disabled auto-merge November 18, 2026 01:52
@bolichen97

Copy link
Copy Markdown
Contributor

[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 Fixes #4748 to Part of #4748 in both the PR description and the commit message. The PR stays with @dodgeblaster. I have turned auto-merge off, so this merges only after a fresh approval on the new head; a person then merges it or re-arms auto-merge.

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.

  1. @buluoray's 11-08 change request: both points are answered on 473a7d2.

    • Denied-command override: lines 81-84, 95-107 and 361-365 match src/kiro_crew/dashboard/deny_override.py (Allow once / Allow for this session / Deny, a re-judge with only that rule waived, audit or refuse, the session waiver kept in memory, no answer from trust, YOLO or auto, never offered for self-guard, policy-pinned or overlay rules, no card for app or channel chats).
    • Windows posture: lines 234-248, 351-359 and 396-403 match unsandboxed_exec_platform_default() in config/loader_document.py, the note above ACP_BACKENDS_RELAY_INTERNAL_SANDBOX in agent_sdk/backends_launch.py, and the agent.sandbox help text in config/sections_agent.py.
  2. "Where the layers stop" and "Choosing a posture for your host": signed off in substance, with one required edit. Main moved after this head. Credential redaction is now one owner switch, Settings → Security → Redaction, off by default; on a host where an administrator's policy governs, it stays on unless that policy allows turning it off (docs/decisions/2026-11-15-credential-redaction-off-by-default.md). With it off, credentials appear as written in your own dashboard session, your Files view, your 1:1 DM with the crew bot (where Kiro Crew can tell it is one), and the conversation replayed into the model's prompt. What a channel or group with other members, a Shared Crew teammate, an allowlist link or an app can see stays redacted. The request-blocking credential checks on commands and URLs run either way. The URL checks the section credits to redaction (lines 177-180) are no longer part of it: a flagged link is now a rendering decision, shown as a Blocked link card in the dashboard, that applies with redaction on or off (security/blocked_links.py), and redaction itself masks only the credential value inside a URL. Please reword:

    • the layers-table row (line 42) and the "Output redaction" section (lines 172-189) to that behaviour, with the URL checks at lines 177-180 moved out of redaction;
    • "Redaction blunts the credential case" (lines 315-316), to credit the request-blocking checks and the credential-exfiltration rules instead;
    • "redaction still scrubs any credential that reaches output" (line 373), to say it does so only while redaction is on.

    The Security list in index.md on main already states the switch in one sentence.

  3. Part of #4748. The issue also asks for cross-links from the root README and the Settings → Security surface. This PR leaves both out (the Settings link by its own "Not a goal"), so the issue stays open for them. This repo's squash merge keeps the commit message, so a Fixes #4748 left there would still close the issue.

  4. Windows story for a Kiro CLI pick: the page's wording is the intended story. It matches docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md: a Kiro CLI choice keeps its v2 launch, the one that delegates, until the gateway confirms kiro-cli offers v3 and KAS is selectable, and then runs on KAS. The note above ACP_BACKENDS_RELAY_INTERNAL_SANDBOX in agent_sdk/backends_launch.py records that KAS child as unconfined on Windows, so it runs unconfined by default and is refused under agent.sandbox_allow_unsandboxed_exec=false. docs/guides/windows-install.md still says a Kiro CLI pick keeps chat in kiro-cli's sandbox: at lines 321-331 of the section this page links to (which tell Windows users to pick it for that), and at lines 378 and 390. That is outside this PR's three files; please link the follow-up issue you drafted for it from this PR once it is filed.

Optional, your call, not blocking: name .local_secret and crons.json beside the audit key in the trust-root sentence; state each repeated residual once in "Where the layers stop"; add to the corporate-host strict advice that a macOS spawn delegated to kiro-cli's own sandbox is confined by that profile instead.

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: User-facing sandboxing / defense-in-depth documentation

5 participants