Skip to content

docs: match the windows secret-at-rest guide to its dual-grant dacl - #34016

Merged
bolichen97 merged 1 commit into
mainfrom
fix/32735-windows-secret-dacl-docs
Nov 11, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/32735-windows-secret-dacl-docs

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An operator who checks a Kiro Crew secret file on Windows with icacls can tell from the install guide that the two full-control entries they see are the intended lockdown, and finds .env, the vault and the relay token among the files it covers.

The Windows install guide's "Secret-at-rest posture on Windows" section describes a one-grant DACL (Owner Rights, S-1-3-4) and gives icacls /inheritance:r /grant:r "*S-1-3-4:F" as its equivalent. restrict_to_owner grants two: Owner Rights and the invoking user's own SID, and it refuses to apply Owner Rights alone. So icacls on a locked-down file prints a second (F) entry the guide says is not there. The guide's file list also leaves out .env, the vault key and store, and the relay token file, which get the same lockdown.

Why it matters

The guide invites an icacls check. An operator who runs one sees an extra full-control entry and cannot tell an intended grant from tampering without reading the source. The files they most want to confirm (.env with the chat-channel tokens, the vault, the relay token) are not on the list, so they cannot check those against the guide at all.

Not a goal

  • Any change to restrict_to_owner, restrict_dir_to_owner, or which files they lock down. The code is right; only the guide and one test docstring were stale.
  • The directory-lockdown and memory-store paragraphs later in the same section. They already match their code.

What changed (motivation → approach → change)

The guide now describes the lockdown the code already applies, so an icacls check on a secret file matches what the operator reads. The code is unchanged.

The guide said The guide says
one grant, Owner Rights two grants: Owner Rights for the file's current owner, and the user's own SID so a file another principal created (an elevated first run, a backup restore, a SYSTEM service) stays readable by that user
nothing on a missing SID the SID comes from the process token; when it cannot be read the lockdown raises and applies nothing, never Owner Rights alone
icacls ... /grant:r "*S-1-3-4:F" as the equivalent icacls <file> /inheritance:r /grant:r "*S-1-3-4:F" /grant:r "*<your-user-SID>:F" as the equivalent on a new file (on a file with another account's explicit entry, icacls keeps it and the in-process call removes it), plus what icacls <file> prints: two (F) entries and no inherited (I)
five files, all under the data home the rule that picks the files (anything passed to restrict_to_owner or written by atomic_write(restrict_to_owner=True)), naming .env, .vault\.vault_key, .vault\secrets.enc and the relay token file, and placing the cron secret temp file in %TEMP%, where it is created

The TestRestrictToOwner docstring in test/test_platform_compat_owner_only.py said the DACL is applied through icacls with Owner Rights; it now says in-process, with both grants.

Backwards compatibility

Compatible: documentation and one test docstring only; no code, setting or assertion changes.

Removes nothing: every file the old list named is still named, and the section heading is unchanged.

Tests

No assertion changes. The existing two-SID pin in test/test_platform_compat_owner_only.py is what the new wording describes. ./scripts/docs-lint.sh passes on the changed guide.

Manual verification

Every claim was checked against the code: the two grants and the refusal (platform_owner_compat.restrict_to_owner and its DACL helper), full control as FILE_ALL_ACCESS and the whole-DACL replacement (windows_acl.apply_owner_only), .env through hidden_leaf_staging.publish_env, the vault key and store (secrets/vault.py), the cron secret file's mkstemp in the temp directory (cron_script.py), and the relay token's direct two-grant lockdown (remote_session/relay.py). The issue's Windows 11 run (3 trials, icacls after restrict_to_owner on a fresh file) printed OWNER RIGHTS:(F) and the user's (F) with no (I), which is what the guide now says. Not re-run on Windows for this PR.

Related Issues

Closes #32735

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 9, 2026 17:37
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d84675c967a28c4e950a51d4c0a62e6ef80c85e3 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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision d84675c967a28c4e950a51d4c0a62e6ef80c85e3 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the change only touches docs and one test docstring, and the code confirms the two-grant claim (platform_owner_compat.py:649). The patch takes nothing away and renders no new surface.

[DESIGN-REVIEWED] d84675c

Description read

[DESCRIPTION-READ] d41fab4cb228d69047e6b38b3f3c39e63313741927facb6008bff1e3e118a85d

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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d84675c

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

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

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d84675c

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 17:47
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 9, 2026
@bolichen97
bolichen97 force-pushed the fix/32735-windows-secret-dacl-docs branch from bd78922 to f84a8e9 Compare November 10, 2026 01:02
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/guides/windows-install.md since this head's CI ran (2caa69b -> 01fcf6d); CI re-running.

The two Backend Tests shard 6 reds (Linux and Windows) were test/test_dashboard_server_composition_contract.py::test_the_lazy_imports_stay_inside_the_functions_that_need_them (assert 144 == 143) on the merge with main, fixed on main by #34010. The Analyze (python) red was the CodeQL upload hitting an API rate limit. The diff is unchanged.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/32735-windows-secret-dacl-docs branch from f84a8e9 to e1d20c0 Compare November 10, 2026 18:41
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/guides/windows-install.md since this head's CI ran (73e3275 -> ed80c1d); CI re-running.

The Backend Tests (3.12, 6) red on f84a8e9 was test/test_taskq_timeline.py::test_the_route_finds_a_channel_or_cron_parents_log_with_no_tab_open[cron:job1-cron-job1] (job 129558083876), the case #34256 tracks. Its fix, #34257, merged after this PR's base and is in the new one. The other reds on that head (the review lanes, Sensitive Change Review, Dependency License Gate, Analyze (actions), and the Coverage Gate that waits on shard 6) failed on a GitHub API rate limit inside CI, not on a finding. The diff is unchanged.

[operator: bolichen97]

@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 labels Nov 10, 2026

@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.

Approve on e1d20c0. Pure rebase of the approved f84a8e9 (identical patch-id dfaae8f7); the Windows secret-at-rest guide's two-grant DACL, refusal and file-list claims all still hold against source at the live head; GPT and Opus both PASS with no findings, no BLOCK-MERGE. Decisive lines: src/kiro_crew/platform_owner_compat.py:538, src/kiro_crew/platform_owner_compat.py:641-649, src/kiro_crew/windows_acl.py:813-850, src/kiro_crew/remote_session/relay.py:340-346, src/kiro_crew/hidden_leaf_staging.py:255, src/kiro_crew/cron_script.py:325, src/kiro_crew/secrets/vault.py:82-84

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 10, 2026
The Windows install guide said a secret file gets one Owner Rights
grant, while restrict_to_owner grants Owner Rights plus the invoking
user's SID and refuses to apply Owner Rights alone. An operator who
checked a secret file with icacls saw a second full-control entry the
guide said was not there, and the guide's file list left out .env, the
vault key and store, and the relay token.

Name both grants and why the second exists, give the two-grant icacls
equivalent and say it matches only on a file with no explicit entries
of its own, and replace the file list with the rule that selects the
files, naming the ones that were missing. Place the cron secret temp
file in %TEMP%, where it is created, not under the data home. Fix the
test docstring that carried the old wording.

Closes #32735
@bolichen97
bolichen97 force-pushed the fix/32735-windows-secret-dacl-docs branch from e1d20c0 to d84675c Compare November 11, 2026 04:31
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/guides/ (docker.md, install.md and telemetry-otlp-export.md, the same directory as this PR's guide) since this head's CI ran (ed80c1d -> ba3d142); CI re-running.

The Backend Tests reds on e1d20c0 (shards 4-7 on Linux and Windows, plus the Coverage Gate that waits on them) are main's. The same code-channel trust-card tests (AttributeError: ... no attribute 'approval_instance' on the shared slot double) and the test_session_markdown.py::test_a_condition_one_opener_is_closed_as_the_parser_reads_it[long-s] case failed on main at 34f545d, the base this head's CI merged with (https://github.com/kirodotdev/KiroCrew/actions/runs/42877490249). #34646 fixed both on main after that base, and the new base carries it. The only other red, TestSelfModuleIndexIsLinear::test_the_scan_is_linear_not_quadratic on Linux shard 7, is the wall-clock flake tracked in #28212.

The patch is unchanged: the same patch-id as e1d20c0, no file of this PR changed on main, and the body is unchanged.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 11, 2026
@bolichen97
bolichen97 merged commit 36631eb into main Nov 11, 2026
99 of 100 checks passed
@bolichen97
bolichen97 deleted the fix/32735-windows-secret-dacl-docs branch November 11, 2026 11:54
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants