feat(preflight): add raw-socket capability probe

[steipete]

Summary

• add the opt-in raw_socket preflight capability for Linux and WSL2
• report stable direct, sudo, unavailable, or probe_missing states using python3 then python
• keep the probe diagnostic-only: it opens and immediately closes one raw socket, never binds, connects, sends, receives, installs software, grants capabilities, or elevates the workload
• isolate interpreter imports, suppress bytecode writes, reject ambiguous protocol output, and run sudo fallback only through trusted executable locations with a fixed root-side interpreter path

Verification

• go test -race ./internal/cli -run 'TestRawSocket|TestPreflight|TestPythonPreflight|TestRemoteCapabilityPreflight' -count=1 -timeout=10m
• go vet ./internal/cli
• git diff --check origin/main...HEAD
• node scripts/build-docs-site.mjs
• clean P1 maintainer autoreview after addressing portability, protocol-noise, bytecode, and multi-sudo-candidate findings

A broad local CLI race run encountered unrelated host-sensitive controller/listener timing failures and timed out under concurrent test load; every reported failing test passed when rerun independently. Exact-head CI is the authoritative broad gate.

Exact-head live proof

Built from exact head 3d44f9c95428b16ab377c6ca92a2a771609d3d9b:

binary_sha256=72874b482cfc66399109ae5668b38cf56f90c5d845aa84eb620a615437f635df
provider=local-container runtime=docker server=29.4.0 image=python:3.13-slim

$ crabbox run --provider local-container --local-container-runtime docker \
    --local-container-image python:3.13-slim --no-sync \
    --preflight --preflight-tools raw_socket -- true
provisioning provider=local-container lease=<redacted> keep=false
provisioned lease=<redacted> container=<redacted> state=ready
remote preflight workspace=raw hydrate_supported=true
remote preflight raw_socket=sudo
running on 127.0.0.1 true
command complete exit=0
releasing <redacted>
lease cleanup stopped=true policy=auto lease=<redacted>

$ docker ps -a --filter label=com.crabbox.lease=<redacted>
<no output>
$ crabbox claims list --json | jq '[.claims[] | select(.leaseId == "<redacted>")] | length'
0

The execution user could not open the raw socket directly; the identical bounded probe succeeded through non-interactive sudo. The ordinary workload remained unprivileged, the user command completed normally, and cleanup left no proof-owned container or claim. Separate Docker controls observed permission denial without NET_RAW, direct success with NET_RAW, and sudo-assisted success from an unprivileged user.

Maintainer decision: retain the Unreleased changelog entry. Repository policy requires changelog coverage for user-visible features; release preparation consumes that maintained section rather than replacing normal feature entries.

Closes #1258

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 17, 2026, 7:10 AM ET / 11:10 UTC.

ClawSweeper review

What this changes

The PR adds an opt-in Linux/WSL2 raw-socket preflight probe that reports direct, sudo-assisted, unavailable, or missing-interpreter capability without elevating the workload.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for maintainer product-direction review: the exact-head terminal proof and focused coverage support the safety boundary, but this adds a supported preflight contract with a sudo -n fallback. Likely related people: steipete (medium confidence).

Priority: P3
Reviewed head: 3d44f9c95428b16ab377c6ca92a2a771609d3d9b
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Exact-head live output and focused coverage provide strong evidence for a bounded implementation, subject to the maintainer’s product-direction choice.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.
Evidence reviewed	6 items	Implementation boundary: The PR registers raw_socket only for Linux-family preflight selection, runs a bounded direct probe first, and permits the sudo fallback only through fixed sudo locations and a fixed root-side PATH. Regression coverage: Focused tests cover target filtering, opt-in behavior, all result states, ambiguous-output rejection, timeout handling, and preventing root-side interpreter resolution through the workload PATH. Current-main and release check: Current main has no raw_socket implementation in the CLI or docs, and no release tag contains the PR head; this is new work rather than an already-landed fix.
Findings	None	None.
Security	None	None.

How this fits together

crabbox run --preflight inspects a remote execution target after workspace setup and before the user workload starts. This change adds one optional capability result to that diagnostic output while leaving the workload’s privileges unchanged.

flowchart LR
A[Run configuration] --> B[Preflight tool selection]
B --> C{Linux or WSL2 target?}
C -->|raw socket requested| D[Bounded socket probe]
D --> E[Direct or sudo capability state]
E --> F[Remote workload]
C -->|unsupported or not requested| F

Loading

Decision needed

Question	Recommendation
Should Crabbox support raw_socket as a documented opt-in preflight capability, including its fixed-command non-interactive sudo diagnostic fallback?	Adopt the opt-in probe: Approve the narrow documented capability check and retain its static sudo fallback as a diagnostic-only path.

Why: The implementation is bounded and proof-positive, but deciding whether this privileged diagnostic belongs in the public preflight contract is product and security-boundary policy rather than a mechanical repair.

Before merge

• Resolve merge risk (P1) - When explicitly requested, an account lacking direct raw-socket permission may cause Crabbox to invoke a fixed root-side Python probe through sudo -n; maintainers should explicitly accept that diagnostic security boundary and its four stable output states.
• Complete next step (P2) - A maintainer must decide whether the new privileged diagnostic belongs in the supported preflight surface; there is no narrow mechanical repair to dispatch.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and coverage	production +201/-42, tests +394, docs/changelog +28/-8	The new security-sensitive capability path has substantial focused regression coverage alongside its operator documentation.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1258
Summary: This PR explicitly presents itself as the candidate implementation for the requested raw-socket preflight capability in #1258.

Members:

• canonical: feat(preflight): add an opt-in raw-socket capability probe #1258 - The issue specifies the same opt-in capability, target scope, states, and non-elevation requirements implemented by this PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Approve the bounded diagnostic boundary (recommended)
   Accept the opt-in fixed-command sudo probe after confirming that this public preflight contract is desired.
2. Pause the feature direction
   Do not merge if a privileged diagnostic does not fit the intended preflight scope.

Technical review

Best possible solution:

Land the opt-in probe only after a product owner accepts the documented privileged diagnostic boundary and treats its result strings as a supported preflight contract.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a defect report; the PR provides a high-confidence exact-head after-fix terminal run demonstrating the new capability result and cleanup behavior.

Is this the best way to solve the issue?

Unclear pending product approval: the implementation is a narrow extension of the existing preflight registry, but accepting a privileged diagnostic fallback is a maintainer policy choice.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 829679307534.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is an optional diagnostic feature and does not report a broken existing workflow.
• merge-risk: 🚨 security-boundary: The opt-in probe can use non-interactive sudo to run a static root-side capability check.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body contains an exact-head live terminal transcript showing the sudo-assisted state, an unprivileged workload, and successful cleanup; identifiers are redacted.

Evidence

What I checked:

• Implementation boundary: The PR registers raw_socket only for Linux-family preflight selection, runs a bounded direct probe first, and permits the sudo fallback only through fixed sudo locations and a fixed root-side PATH. (internal/cli/run_observability.go:519, 3d44f9c95428)
• Regression coverage: Focused tests cover target filtering, opt-in behavior, all result states, ambiguous-output rejection, timeout handling, and preventing root-side interpreter resolution through the workload PATH. (internal/cli/run_test.go:4515, 3d44f9c95428)
• Current-main and release check: Current main has no raw_socket implementation in the CLI or docs, and no release tag contains the PR head; this is new work rather than an already-landed fix. (internal/cli/run_observability.go, 829679307534)
• Area provenance: The most recent current-main change to the preflight implementation was authored by Peter Steinberger, supporting steipete as the current routing candidate. (internal/cli/run_observability.go:152, 83dc17f99acb)
• After-fix behavior proof: The PR body includes an exact-head local-container terminal transcript showing raw_socket=sudo, an unprivileged workload completing, and lease/container cleanup with no remaining claim. (3d44f9c95428)
• Structured review availability: The repository autoreview helper stopped before its model pass because TruffleHog is unavailable; the verdict above is based on direct source, test, proof, and history inspection.

Likely related people:

• steipete: Peter Steinberger authored the latest current-main change to the preflight implementation, and the supplied PR metadata maps this identity to steipete. (role: recent area contributor; confidence: medium; commits: 83dc17f99acb; files: internal/cli/run_observability.go)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-08-17T09:35:40.750Z sha 8d89aae :: needs real behavior proof before merge. :: [P2] Remove the release-owned changelog entry
• reviewed 2026-08-17T10:15:28.701Z sha a7af8f3 :: needs real behavior proof before merge. :: [P2] Remove the release-owned changelog entry
• reviewed 2026-08-17T11:04:18.076Z sha 3d44f9c :: needs real behavior proof before merge. :: [P2] Remove the release-owned changelog entry

[steipete]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/32023802604
• Updated: 2026-08-17T11:12:28.388Z

[steipete]

Maintainer decision: accept the opt-in raw_socket preflight boundary and its stable direct, sudo, unavailable, and probe_missing states. The sudo path runs only the fixed, bytecode-free socket-open/close probe through sudo -n; it never elevates the workload or performs packet I/O. The Unreleased changelog entry remains under repository policy for user-visible features.