Skip to content

fix: name the umask cause when service install refuses a writable venv - #31399

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/22407-umask-apparmor-hint
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/22407-umask-apparmor-hint

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When kirocrew service install refuses a venv made under umask 002, it says why and how to fix it, and the pip install docs say to use umask 022.

On a host that restricts unprivileged user namespaces (Ubuntu 24.04 and later), kirocrew service install loads no AppArmor profile for a pip or python -m venv install made under umask 002. Both tools follow the umask, so <venv>/bin and the kirocrew launcher come out 0775, and the writable-path check refuses them. The refusal then tells the user to move "the AppImage", which a pip user does not have, and agent sandbox spawns fail closed.

Why it matters

002 is a common default umask for ordinary users on Ubuntu and Fedora, and the documented pip commands use the caller's umask. A user who follows the docs gets a service whose sandbox fails, plus advice meant for a different install type.

Not a goal

  • Relaxing the writable-path check. Whether group write is safe under a per-user private group is a security call for the owner; the check is unchanged.
  • Changing the AppImage launcher's refusal text.

What changed (motivation → approach → change)

When the service refuses a group- or world-writable path, the message now names the likely cause and the fix: if the venv was made under umask 002, run chmod -R g-w <venv> on the venv that holds the launcher; otherwise tighten the named path. Then re-run kirocrew service install. The AppImage launcher keeps its old advice, and what the check accepts and refuses is unchanged.

The two texts split on expected_uid. The same function already uses it to word its ownership refusal: the service passes the service account's uid, and the AppImage launcher passes none.

The pip commands in getting-started.md now start with umask 022, followed by a short note: create the venv under that umask too, and how to repair an existing install. The pip section of docs/guides/install.md says the same in one paragraph.

Backwards compatibility

Compatible: only the advice text of one refusal and the docs change; every path accepted or refused before still is.

Removes nothing: the check, its verdicts and the AppImage message stay; the service case swaps advice that named the wrong install type.

Tests

  • test_a_group_writable_venv_names_the_umask_cause_and_the_chmod (test/test_service_launcher_profile.py): a launcher in a 0775 kc/bin directory, checked with the service's expected_uid, is refused. The message names that directory, umask 002 and chmod -R g-w <venv>, and does not give the AppImage advice.
  • test_a_group_writable_file_is_refused gains one assertion: the launcher case (no expected_uid) still gives the AppImage advice and does not mention umask.

Proof: PROVEN test/test_service_launcher_profile.py::TestExpectedUidOverride::test_a_group_writable_venv_names_the_umask_cause_and_the_chmod (head 60c103d)

Determinism: both tests passed 20 runs at -n0, and 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 alongside test/test_service_apparmor.py. The whole file also passed in shuffled order (seed 20718).

Manual verification

N/A — unit coverage sufficient: the change is message text and docs, and the test drives the real validate_exec_path on a real 0775 directory.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #22407

Sibling sweep

Swept: git grep -nE "pip install (--pre kirocrew|-e)" -- '*.md'; git grep -n "AppImage" -- src/kiro_crew/service/apparmor.py
Sibling: docs/guides/install.md:445 -- changed here
Sibling: docs/build/release.md:574 -- not affected -- a maintainer's check of the channel index, not a host install that runs service install
Sibling: docs/guides/windows-install.md:260 -- not affected -- Windows has no AppArmor profile to refuse
Sibling: src/kiro_crew/service/apparmor.py:846 -- not affected -- the shared-interpreter refusal; the service attaches to the venv console script, which that rule never matches

Pattern harvest

Not generalizable: one refusal shared by two callers carried only one caller's advice, and the function already words its other refusal per caller through the same argument.

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 6, 2026 12:06
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 12:06
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 12:13
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/22407-umask-apparmor-hint branch from a804d13 to 60c103d Compare November 6, 2026 14:57
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/cli_doctor.py, src/kiro_crew/cli_server.py, src/kiro_crew/doctor_checks/install.py, test/test_service_apparmor.py since this head went green (b764e20 -> 85ce466); CI re-running.

[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 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ebea776

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ebea776070a564abd7250d525ce1f03d94a9f5ce 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 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the advice text is chosen from expected_uid, which the service path always passes and the AppImage path never does, and the check's verdicts are unchanged.

[DESIGN-REVIEWED] ebea776

Description read

[DESCRIPTION-READ] 3fd64c2bab97dcc3d65d4cfd3fee883574803dcb7e93a3cefb41cb169186826a

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 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ebea776070a564abd7250d525ce1f03d94a9f5ce — 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

Nothing blocks: the fix changes refusal text and docs, links issue #22407, and leaves the check's verdicts unchanged.

What this change ships

Inventory (4 items) — 4 justified

Intent: a pip or venv user whose service install is refused under umask 002 learns the cause and the fix. This is a FIX.

  1. The kirocrew service install writable-path refusal now names umask 002 and chmod -R g-w <venv> instead of AppImage advice — justified
  2. The pip block in getting-started.md now starts with umask 022 and adds a repair note — justified
  3. The source-checkout block in getting-started.md now starts with umask 022 — justified
  4. The pip section of docs/guides/install.md gains a umask paragraph — justified

[FIRST-PRINCIPLES-REVIEWED] ebea776

Description read

[DESCRIPTION-READ] e4ef96a473e0cc6c5a0de411d90c4bfe9cd475c00d5b60e1e8ac045e9766eabd

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ebea776

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

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

@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 6, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The three red checks on 60c103d (Backend Tests shard 2 on Linux and Windows, and the Coverage Gate that follows them) come from one test, test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget. It fails on main too: the security package measures 34,733 lines on main against a 34,699 budget, and this PR changes no file in that package. #31469 raises the budget to the size on main. This PR waits for it to merge, then rebases onto it and re-runs CI; no override is requested for this red.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] #31469 landed, but main went red on the same test again after #30774: test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget now counts 34753 lines against a budget of 34733 on a rebase onto 9cea993. This PR changes nothing under the security package, so the rebase would still be red there. The budget fix is #31625. This PR waits for it to merge, then gets rebased.

On an AppArmor userns-restricted host, a pip or venv install made under
umask 002 leaves the venv group-writable, so service install refuses the
launcher. Its refusal gave AppImage-only advice. The service case now
names the umask cause and the chmod -R g-w <venv> fix, the AppImage
wording is unchanged, and the pip install docs set umask 022 first.
The writable-path check itself is unchanged.

Closes #22407
@bolichen97
bolichen97 force-pushed the fix/22407-umask-apparmor-hint branch from 60c103d to ebea776 Compare November 6, 2026 23:05
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026

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

Approved for the on-call. Review lanes pass on ebea776, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit d18b76e into main Nov 7, 2026
97 of 100 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/22407-umask-apparmor-hint branch November 7, 2026 00:45
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
buluoray pushed a commit that referenced this pull request Nov 8, 2026
#31399)

On an AppArmor userns-restricted host, a pip or venv install made under
umask 002 leaves the venv group-writable, so service install refuses the
launcher. Its refusal gave AppImage-only advice. The service case now
names the umask cause and the chmod -R g-w <venv> fix, the AppImage
wording is unchanged, and the pip install docs set umask 022 first.
The writable-path check itself is unchanged.

Closes #22407

(cherry picked from commit d18b76e)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

service install skips the AppArmor profile on a pip install made under umask 002

2 participants