feat(plugins): add WASM plugin system with security sandbox by Biztactix-Ryan · Pull Request #5231 · zeroclaw-labs/zeroclaw

Biztactix-Ryan · 2026-04-02T20:39:19Z

Summary

Base branch target (master for all contributions): master
Problem: ZeroClaw lacks an extension mechanism for adding custom tools without forking the core codebase
Why it matters: Users need domain-specific tools (CRM lookups, internal APIs, custom integrations) that are isolated, auditable, and hot-reloadable
What changed:
- Core WASM plugin runtime with wasmtime-based sandboxing
- Capability-based security model with host function enforcement
- Rust plugin SDK (zeroclaw-plugin-sdk crate)
- CLI commands: zeroclaw plugin {list,install,reload,audit,doctor}
- REST API endpoints for plugin management
- Web UI with plugin list and detail pages
- Comprehensive integration test suite (100+ tests)
- Full documentation (quickstart, manifest reference, SDK reference, security model, CLI/API reference)
What did not change (scope boundary): Core agent logic, existing tools, providers, channels, memory backends. Python and C# SDKs deferred to follow-up PR.

Label Snapshot (required)

Risk label (risk: low|medium|high): risk: high
Size label (size: XS|S|M|L|XL, auto-managed/read-only): (auto)
Scope labels: core, runtime, security, gateway, tool, docs, tests
Module labels: plugin: wasm, plugin: sdk
Contributor tier label: (auto-managed/read-only)
If any auto-label is incorrect, note requested correction: N/A

Change Metadata

Change type (bug|feature|refactor|docs|security|chore): feature
Primary scope (runtime|provider|channel|memory|security|ci|docs|multi): multi

Linked Issue

Closes # N/A (new feature)
Related # N/A
Depends on # N/A
Supersedes # N/A

Supersede Attribution (required when `Supersedes #` is used)

N/A

Validation Evidence (required)

Commands and result summary:

./dev/test.sh              # Full test suite passes
./dev/test.sh plugins      # Plugin-specific tests pass
cargo fmt --all -- --check # No formatting issues
cargo clippy --all-targets -- -D warnings # No warnings

Evidence provided (test/log/trace/screenshot/perf): Integration tests cover plugin loading, capability enforcement, hot-reload, error handling, memory operations, and wire format compatibility
If any command is intentionally skipped, explain why: N/A

Security Impact (required)

New permissions/capabilities? (Yes/No): Yes — plugin capability model with granular permissions
New external network calls? (Yes/No): Yes — plugins can declare network.http capability (enforced by host)
Secrets/tokens handling changed? (Yes/No): No
File system access scope changed? (Yes/No): Yes — plugins can declare fs.read/fs.write capabilities (sandboxed to allowed paths)
If any Yes, describe risk and mitigation:
- Risk: Malicious plugins could abuse granted capabilities
- Mitigation:
  - All capabilities must be declared in manifest and explicitly approved by operator
  - WASM sandbox prevents memory escape
  - Host functions enforce capability boundaries at runtime
  - Optional cryptographic signature verification
  - zeroclaw plugin audit command for security review
  - Rate limiting on host function calls

Privacy and Data Hygiene (required)

Data-hygiene status (pass|needs-follow-up): pass
Redaction/anonymization notes: Test fixtures use neutral project-scoped identifiers
Neutral wording confirmation: All examples use zeroclaw_user, ZeroClawAgent, etc.

Compatibility / Migration

Backward compatible? (Yes/No): Yes — new feature, no breaking changes
Config/env changes? (Yes/No): Yes — new [plugins] config section (optional, disabled by default)
Migration needed? (Yes/No): No
If yes, exact upgrade steps: N/A

i18n Follow-Through (required when docs or user-facing wording changes)

i18n follow-through triggered? (Yes/No): Yes
If Yes, locale navigation parity updated in README*, docs/README*, and docs/SUMMARY.md for supported locales: No — plugin docs are new, i18n can follow in subsequent PR
If any No/N.A., link follow-up issue/PR and explain scope decision: New feature docs; i18n to follow once stable

Human Verification (required)

What was personally validated beyond CI:

Verified scenarios: Plugin loading, capability enforcement, hot-reload, web UI plugin management
Edge cases checked: Invalid manifests, missing capabilities, WASM memory limits, malformed wire format
What was not verified: Production load testing (recommend monitoring after merge)

Side Effects / Blast Radius (required)

Affected subsystems/workflows: Plugin loader runs at startup; new gateway endpoints; doctor command extended
Potential unintended effects: Startup time increases slightly when plugins are enabled
Guardrails/monitoring for early detection: zeroclaw plugin doctor validates plugin health; metrics exposed for plugin execution time

Agent Collaboration Notes (recommended)

Agent tools used (if any): Claude Code
Workflow/plan summary (if any): Iterative development with test-driven approach
Verification focus: Security boundaries, capability enforcement, SDK ergonomics
Confirmation: naming + architecture boundaries followed (AGENTS.md + CONTRIBUTING.md): Yes

Rollback Plan (required)

Fast rollback command/path: git revert <merge-commit> or disable via config [plugins] enabled = false
Feature flags or config toggles (if any): [plugins] enabled (default: false)
Observable failure symptoms: Plugin load failures logged at ERROR level; zeroclaw plugin doctor surfaces issues

Risks and Mitigations

Risk: Plugin capability model has security holes
- Mitigation: Extensive integration tests; capability enforcement at host function level; code review focused on src/plugins/host_functions.rs
Risk: WASM runtime performance overhead
- Mitigation: wasmtime is production-grade; metrics exposed for monitoring; plugins are optional
Risk: Breaking changes to plugin manifest format post-merge
- Mitigation: Manifest schema versioned; SDK provides forward-compatible abstractions

…ration tests Add complete WASM plugin loader, host functions, security audit integration, and 30+ integration tests covering echo/fs/http/multi-tool plugins with strict/relaxed/paranoid security modes. Also excludes test plugin build artifacts from version control. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add dev/test.sh shell harness wrapping cargo fmt, clippy, build, and test with support for multiple modes (all, plugins, quick). Document usage in CLAUDE.md and add plugin-specific testing guide.

Ergonomic Rust SDK built on Extism PDK for developing WASM plugins. Provides four modules: memory (persistent storage), tools (registration and delegation), messaging (channel-based comms), and context (session, user identity, agent config access).

…orcement Implement capability-based security for plugins: memory, tool delegation, messaging, and context capabilities declared in manifests and enforced at runtime. Add host function registry bridging WASM plugins to agent subsystems with rate limiting and recursion guards. Introduce RiskLevel enum, WASM integrity verification via SHA-256 sidecar files, plugin diagnostics, enable/disable state, and wildcard delegation rejection.

Add three plugin management subcommands: reload (re-scan and re-instantiate plugins), audit (validate a manifest without installing), and doctor (run diagnostics on all installed plugins with pass/warn/fail status).

Add REST endpoints for plugin enable/disable, config patching, and individual plugin detail retrieval. Extract auth checking and plugin path resolution into shared helpers.

Add plugin list to integrations page with enable/disable toggles and capability badges. Add full plugin detail page with tools table, permissions display, inline config editor, and security audit section. Includes i18n support for en/zh/tr.

Add Smart Greeter example plugin demonstrating end-to-end SDK usage (context, memory, tool delegation). Include pre-compiled WASM artifact and register as workspace member.

Add 73 new integration tests covering plugin API endpoints, memory, messaging, context, reload, doctor diagnostics, hash verification, rate limiting, timeouts, tool delegation, capabilities, host functions, config display, security audit, and SDK modules. Update existing tests for host_capabilities field and new tool count.

Add comprehensive plugin documentation covering quickstart guide, manifest reference, SDK API reference, security model, CLI commands, and REST API endpoints. Register new section in docs SUMMARY.

Replace stub WasmChannel send() with real channel_send/channel_listen WASM calls. Add DTO types for JSON marshalling, channel-plugin test crate, pre-built WASM artifact, and integration test.

Add Python plugin SDK under sdks/python/, build script for compiling Python plugins to WASM, SDK reference docs, two test plugins (echo, sdk-example), and 9 integration tests covering roundtrip, context, memory, tool delegation, and manifest compatibility.

Add C# plugin SDK targeting .NET 8 WASI under sdks/csharp/ with entry point marshalling, Extism PDK bindings, and unit tests. Include 5 integration tests covering SDK structure, build, PDK reference, JSON marshalling, and test attribute conventions.

Add check_plugin_health() to surface loaded/failed/disabled plugin counts and per-plugin errors/warnings in zeroclaw doctor output. Add diagnose_plugins() for structured JSON in the /api/doctor response. Include category display names, hint text for plugin issues, and unit + integration tests.

Formatting-only changes: line wrapping, brace style, import ordering, and argument alignment in plugin core, gateway, security, and tools modules.

Alphabetically sort mod declarations in tests/integration/mod.rs and apply rustfmt formatting across all plugin integration test files.

Adds Send() and GetChannels() methods that call zeroclaw_send_message and zeroclaw_get_channels host functions via Extism shared memory, with snake_case JSON marshalling matching the Rust SDK wire format.

Adds ToolCall() method that calls zeroclaw_tool_call host function via Extism shared memory, with snake_case JSON marshalling matching the Rust SDK wire format. Includes C# unit tests and Rust integration tests covering API surface, host function binding, wire format, error handling, and success output.

… wire format Validates that Memory.cs error paths throw PluginException with descriptive messages, and that request/response JSON marshalling matches the Rust SDK wire format exactly.