wasm-plugin-sandbox

Policy-driven WASM sandbox for running untrusted plugins with deterministic budgets and explainable deny logs.

What it enforces

• CPU fuel budget
• Wall-clock timeout
• Memory ceiling
• Filesystem path allowlists + read/write byte quotas
• Network host/port allowlists + connection/egress quotas
• Structured allow/deny events (decision, rule_id, reason_code, context)

Architecture

• cmd/sandbox-cli: CLI surface (run, explain, policy lint, policy template)
• crates/runtime: Wasmtime runtime + capability broker + policy engine integration
• policies/: policy examples
• examples/plugins/: sample WAT plugins (allowed and deny-heavy)
• docs/threat-model.md: security scope and assumptions
• docs/benchmarks.md: benchmark methodology

One-command demos (Phase 5)

./scripts/phase5_show_hn_demo.sh

This script builds the CLI, runs allowed/deny-heavy plugins, explains a deny event, lints policy, and prints a benchmark snapshot.

For a cleaner automated run with saved artifacts and summary:

./scripts/usage_run.sh

usage_run.sh also covers:

• full test run (optional)
• explain flow via --report-file and --event-json
• baseline lint + noisy lint warning coverage
• strict/balanced/dev policy template generation
• benchmark harness run (optional)
• artifact bundle and run summary

Optional:

ITERATIONS=25 ARTIFACT_DIR=/tmp/my_sandbox_run ./scripts/usage_run.sh

Fast mode (skip tests and benchmarks):

RUN_TESTS=0 RUN_BENCH=0 ./scripts/usage_run.sh

Additional knobs:

RUN_TESTS=1 RUN_BENCH=1 ITERATIONS=30 ARTIFACT_DIR=/tmp/wasm_sandbox_usage ./scripts/usage_run.sh

Core commands

Run plugin:

cargo run -p sandbox-cli -- run --policy policies/phase2-demo.yaml --plugin examples/plugins/capability_allowed.wat --pretty

Explain deny event from report:

cargo run -p sandbox-cli -- explain --report-file /tmp/report.json --event-index 1 --pretty

Lint policy:

cargo run -p sandbox-cli -- policy lint --policy policies/phase2-demo.yaml --pretty

Generate template policy:

cargo run -p sandbox-cli -- policy template --preset balanced --output /tmp/policy.yaml

Run benchmark harness:

ITERATIONS=25 ./scripts/phase4_bench.sh

Current benchmark snapshot

Generated by ITERATIONS=10 ./scripts/phase4_bench.sh on this machine after a warm build.

case	iterations	min_ms	median_ms	p95_ms	max_ms	mean_ms
allowed_flow	10	9.87	11.01	11.50	14.24	11.08
deny_heavy_flow	10	9.80	10.72	12.81	13.55	11.16

Update this table with your own local run before posting Show HN.

Limitations

• This is an app-layer sandbox, not a kernel isolation boundary.
• Host operations are capability-mediated imports (sandbox.*), not transparent full syscall interception.
• Security guarantees depend on policy quality and runtime engine correctness.

Launch assets

• Show HN draft: docs/show-hn-launch.md
• Threat model: docs/threat-model.md
• Bench docs: docs/benchmarks.md
• Usage artifacts include: allowed_report.json, denied_report.json, explain_events/*.json, policy_lint_noisy.json, benchmark.json