feat(plugin): add OpenClaw install gate

[jesse-merhi]

What Problem This Solves

OpenClaw can enforce ClawScan policy before installing or updating a staged skill or plugin. The plugin maps trustworthy ClawScan artifacts to the host hook contract: pass continues silently, warnings become structured findings, blocks stop installation, and scanner/process/artifact failures fail closed.

Why This Change Was Made

ClawScan's declarative JSON gate policy had no OpenClaw runtime adapter. This adds a separate @openclaw/clawscan-plugin package so loading the hook never imports the CLI wrapper's process-spawning code. It uses OpenClaw's bounded runtime command API and an exact-version dependency on the matching binary package.

Runtime flow:

1. OpenClaw discovers the explicitly trusted before_install provider.
2. The plugin runs SkillSpector plus clawscan-static in Docker, or visibly degrades to static-only scanning when Docker is unavailable.
3. The plugin validates the complete clawscan-run-v1 artifact and every selected scanner result.
4. Pass continues silently, warnings become bounded structured findings, and blocks or invalid/incomplete evidence stop installation.

User Impact

• openclaw plugins install @openclaw/clawscan-plugin explicitly trusts and enables this config-free plugin. Alternate placement requires openclaw plugins enable clawscan and inclusion in plugins.allow when that allowlist is configured.
• The manifest declares both activation.onHooks: ["before_install"] and activation.onCapabilities: ["hook"].
• This package requires the cold install-provider contract in openclaw/openclaw#115197, covering CLI and Gateway install/update operations. Older prerelease behavior that only ran already-loaded hooks is unsupported.
• The shipped declarative profile runs SkillSpector without LLM analysis plus clawscan-static in Docker. Ambient model-provider configuration and credentials are scrubbed before the scan command starts. SkillSpector still sends dependency names to OSV.dev for CVE lookup.
• If Docker is unavailable, installation is checked by static rules only and receives an explicit degraded warning.
• The binary release and npm package include Windows ARM64 as well as Windows x64, so native-Windows degraded scanning remains available on both architectures.
• The first installation cannot scan itself because the hook is not active yet; enabled installations scan later updates, including their own.

Evidence

The packed release smoke built both scoped tarballs, installed them together, loaded the compiled plugin runtime, confirmed the plugin's exact @openclaw/clawscan version, resolved the packaged manifest/profile, and ran the installed CLI against the repository README.

The final net diff contains 22 files with no branch-only churn. Review fixes preserve actionable scanner evidence, map production fired-rule fields to bounded host findings, fail closed on ambiguous npm publish-state responses, declare the narrow host activation hook, and prevent provider credentials from entering the scanner container.

Security / Trust Impact

• Security/trust impact explained

Untrusted source material never controls config discovery. The plugin resolves explicit shipped and operator-configured paths through api.resolvePath, compares their resolved identities before applying shipped-profile guarantees, forces CLAWSCAN_SKILLSPECTOR_LLM=0, clears SkillSpector provider/model/key variables inherited from OpenClaw, bounds command output and returned finding fields, rejects incomplete or schema-incompatible scanner evidence, and blocks on malformed artifacts or expected execution failures.

Checks

• TMPDIR=/private/tmp go test -count=1 ./...
• TMPDIR=/private/tmp go vet ./...
• 52 Node tests across the plugin, binary resolver, and packaging helpers
• actionlint on all changed workflows
• node scripts/build-npm-package.mjs --version v0.0.0 --pack --smoke
• make release VERSION=v0.0.0-test
• git diff --check
• Proof pack: base d8e57e3, head 373a534, 22 net changed files, no branch-only churn
• Two consecutive clean whole-diff native review passes on the identical tree
• Fresh context-free cold review passed clean on the identical tree
• Full Docker self-scan locally: the runtime image pull exhausted this machine's Docker storage, so SkillSpector correctly reported failed; the added manually triggered CI workflow requires both scanners to complete and the gate to pass.
• Docs site proof: N/A; no docs-site source changed.

Implementation Notes

This is stacked on jesse/openclaw-native-gate-policy at d8e57e3. OpenClaw host support is tracked in openclaw/openclaw#115197. Before the first registry release, @openclaw/clawscan-plugin must receive the repository's documented one-time npm bootstrap publication so release.yml can become its sole trusted publisher.

The PR remains draft because the stacked ClawScan policy and OpenClaw host PRs are not merged, the external npm bootstrap is outstanding, and the full local Docker self-scan is blocked by Docker storage.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​openclaw/​clawscan@​0.0.0-dev	N/A	N/A	N/A	N/A	N/A

View full report

[clawsweeper]

Codex review: found issues before merge. Reviewed July 29, 2026, 4:12 PM ET / 20:12 UTC.

ClawSweeper review

What this changes

This PR adds an @openclaw/clawscan-plugin package that converts ClawScan scan artifacts into allow, warn, or block decisions before OpenClaw installs or updates skills and plugins, alongside npm/release packaging updates.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep this member-authored draft open. The plugin’s central security promise depends on OpenClaw cold discovery of before_install providers, but the PR itself says that host contract is still tracked in an unmerged OpenClaw change; the current >=2026.7.2 compatibility declaration can therefore permit installation on hosts that never invoke the gate.

Likely related people: jesse-merhi is the recent install-gate contributor (medium confidence).

Priority: P2
Reviewed head: 373a5348c959cd378763197567324a225f41255f
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The implementation has meaningful tests and packaging validation, but a blocking host-compatibility defect remains unresolved.
Proof confidence	🌊 off-meta tidepool	Not applicable: This member-authored PR is exempt from the external-contributor proof gate, but merge readiness still requires a redacted real OpenClaw CLI or Gateway install/update transcript after the host contract releases.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This member-authored PR is exempt from the external-contributor proof gate, but merge readiness still requires a redacted real OpenClaw CLI or Gateway install/update transcript after the host contract releases.
Evidence reviewed	4 items	Unreleased host dependency: The PR description and plugin README state that cold discovery of trusted before_install providers is required for CLI and Gateway install/update operations and is tracked by the still-unmerged external OpenClaw pull request. The proposed package nevertheless declares compatibility with >=2026.7.2. Compatibility declaration permits unsupported hosts: The package advertises openclaw peer compatibility and a minimum host version of >=2026.7.2, without tying publication to a released host version that implements cold install-provider discovery. Prior review continuity: The prior completed ClawSweeper cycle raised the same P1 concern at the identical reviewed head 373a5348c959cd378763197567324a225f41255f; the supplied PR body still states the host support is unmerged, so the blocker remains unresolved rather than newly discovered.
Findings	1 actionable finding	[P1] Gate publication on released host hook support
Security	Needs attention	Advertised gate can be inactive on allowed hosts: The plugin’s enforcement depends on cold host discovery of before_install providers, while the package accepts a host range that the PR says predates that released contract. This can silently remove the expected pre-install scan.

How this fits together

ClawScan runs configured scanners and emits a versioned gate artifact describing the scan result. The proposed OpenClaw plugin would register an install hook, invoke ClawScan on the staged installation candidate, and turn trustworthy artifact results into installation decisions.

flowchart LR
  Candidate[Staged skill or plugin] --> Hook[OpenClaw before-install hook]
  Hook --> Plugin[ClawScan install-gate plugin]
  Plugin --> Scan[ClawScan scanner run]
  Scan --> Artifact[Versioned gate artifact]
  Artifact --> Gate[Allow, warn, or block]
  Gate --> Install[OpenClaw install or update]

Loading

Decision needed

Question	Recommendation
Should this package remain unpublished until OpenClaw releases cold discovery of trusted before_install providers, with the plugin minimum host version raised to that release?	Gate publication on the released host contract: Keep the plugin unpublished, raise its minimum host version once the required OpenClaw release exists, and add an end-to-end host install/update proof.

Why: The PR intentionally depends on external host behavior that its current semver range does not prove is available, so maintainers must choose the supported release boundary before this security feature can be published.

Before merge

• Gate publication on released host hook support (P1) - The package allows openclaw >=2026.7.2, but the PR states that cold discovery of before_install providers remains in an unmerged OpenClaw change. A user can therefore install a claimed fail-closed gate on an allowed host whose CLI or Gateway installation path never invokes it. Raise the host floor only after that contract releases and cover a real host install/update path. This repeats the unresolved prior finding at the same head.
• Resolve security concern: Advertised gate can be inactive on allowed hosts - The plugin’s enforcement depends on cold host discovery of before_install providers, while the package accepts a host range that the PR says predates that released contract. This can silently remove the expected pre-install scan.
• Resolve merge risk (P1) - Publishing with openclaw >=2026.7.2 before the cold install-provider contract ships can leave existing supported host versions without any pre-install scan, despite the package’s fail-closed security positioning.
• Resolve merge risk (P2) - The added gate executes scanners on untrusted installation candidates; its advertised security boundary needs a real host install/update proof, including the Docker-unavailable fallback, before release.
• Complete next step (P2) - A maintainer must choose the release boundary for the external OpenClaw hook contract; this cannot be safely repaired by an automated branch change before the upstream contract ships.

Findings

• [P1] Gate publication on released host hook support — npm/clawscan-plugin/package.json:30
• [high] Advertised gate can be inactive on allowed hosts — npm/clawscan-plugin/package.json:30

Agent review details

Security

Needs attention: The patch is security-conscious, but its current host-version declaration can expose users to a non-invoked install gate and therefore an unenforced security boundary.

Review metrics

Metric	Value	Why it matters
Changed surface	22 files; 2,453 additions and 92 deletions	The PR spans a new runtime package plus packaging and release workflows, so host-version compatibility needs review across both runtime and publication paths.
Host-runtime proof	0 demonstrated OpenClaw install/update runs	The PR provides packaging smoke evidence but explicitly lacks a completed Docker self-scan and does not show the required host hook executing.

Merge-risk options

Maintainer options:

1. Release only with a proven host floor (recommended)
   Change the minimum supported OpenClaw version only after the cold hook contract is released, then prove a real install/update invokes and enforces the gate.
2. Pause publication until host support lands
   Leave this draft stacked on the host work rather than shipping a security gate that supported hosts may not execute.

Technical review

Best possible solution:

Wait for the cold before_install provider contract to ship in OpenClaw, then set the plugin’s minimum host version to that released version and add a redacted end-to-end CLI or Gateway install/update test proving that pass, warn, block, scanner failure, and Docker-unavailable behavior reach the host hook.

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

No current released-host reproduction is available. Source and the PR’s own compatibility statement establish a high-confidence path: install this plugin on an allowed host lacking cold before_install discovery and verify that an install/update does not invoke the gate.

Is this the best way to solve the issue?

No. The plugin architecture is a reasonable direction, but publishing against a broad host range before the required hook contract is released is not a safe solution; the minimum host version and end-to-end proof must follow the released contract.

Full review comments:

• [P1] Gate publication on released host hook support — npm/clawscan-plugin/package.json:30
  The package allows openclaw >=2026.7.2, but the PR states that cold discovery of before_install providers remains in an unmerged OpenClaw change. A user can therefore install a claimed fail-closed gate on an allowed host whose CLI or Gateway installation path never invokes it. Raise the host floor only after that contract releases and cover a real host install/update path. This repeats the unresolved prior finding at the same head.
  Confidence: 0.97

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This member-authored PR is exempt from the external-contributor proof gate, but merge readiness still requires a redacted real OpenClaw CLI or Gateway install/update transcript after the host contract releases.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P2: This is a significant but optional install-policy feature with a bounded release-readiness blocker rather than an active user regression.
• merge-risk: 🚨 compatibility: The package accepts hosts from >=2026.7.2 although its required cold hook-discovery behavior is described as not yet merged upstream.
• merge-risk: 🚨 security-boundary: A host that installs the plugin but never invokes its install hook bypasses the feature’s advertised pre-install enforcement boundary.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This member-authored PR is exempt from the external-contributor proof gate, but merge readiness still requires a redacted real OpenClaw CLI or Gateway install/update transcript after the host contract releases.

Evidence

Security concerns:

• [high] Advertised gate can be inactive on allowed hosts — npm/clawscan-plugin/package.json:30
  The plugin’s enforcement depends on cold host discovery of before_install providers, while the package accepts a host range that the PR says predates that released contract. This can silently remove the expected pre-install scan.
  Confidence: 0.97

What I checked:

• Unreleased host dependency: The PR description and plugin README state that cold discovery of trusted before_install providers is required for CLI and Gateway install/update operations and is tracked by the still-unmerged external OpenClaw pull request. The proposed package nevertheless declares compatibility with >=2026.7.2. (npm/clawscan-plugin/README.md:5, 373a5348c959)
• Compatibility declaration permits unsupported hosts: The package advertises openclaw peer compatibility and a minimum host version of >=2026.7.2, without tying publication to a released host version that implements cold install-provider discovery. (npm/clawscan-plugin/package.json:30, 373a5348c959)
• Prior review continuity: The prior completed ClawSweeper cycle raised the same P1 concern at the identical reviewed head 373a5348c959cd378763197567324a225f41255f; the supplied PR body still states the host support is unmerged, so the blocker remains unresolved rather than newly discovered. (npm/clawscan-plugin/package.json:30, 373a5348c959)
• Repository policy applied: The checked-out repository policy requires scanner and release changes to have focused validation and keeps the public CLI general-purpose; this separate plugin package is directionally consistent, but release readiness still requires proof of the host integration. (AGENTS.md:1, ef760b176da7)

Likely related people:

• jesse-merhi: The available PR history attributes all 14 install-gate and related packaging commits to this person, including the current head that defines the compatibility boundary. (role: recent install-gate contributor; confidence: medium; commits: 34cc64d6edff, 373a5348c959; files: npm/clawscan-plugin/package.json, npm/clawscan-plugin/src/register.ts, npm/clawscan-plugin/src/gate-handler.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Raise the minimum OpenClaw version only after the cold hook contract is released.
• Add a redacted end-to-end CLI or Gateway install/update proof covering enforcement and the Docker-unavailable fallback.

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 (6 earlier review cycles)

• reviewed 2026-07-28T15:22:05.755Z sha 067801e :: needs maintainer review before merge. :: none
• reviewed 2026-07-28T15:56:37.969Z sha 0acea12 :: found issues before merge. :: [P1] Gate publication on a released host hook API
• reviewed 2026-07-28T16:37:04.486Z sha b7f8b1e :: found issues before merge. :: [P1] Use the host install policy for enforcement | [P1] Gate publication on a released host hook contract
• reviewed 2026-07-29T12:57:56.555Z sha 373a534 :: found issues before merge. :: [P1] Gate publication on released host hook support
• reviewed 2026-07-29T18:11:21.269Z sha 373a534 :: found issues before merge. :: [P1] Gate publication on a released host hook contract
• reviewed 2026-07-29T19:09:31.876Z sha 373a534 :: found issues before merge. :: [P1] Gate publication on released host hook support

[jesse-merhi]

/clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.