From 65a868eb14e5b38d4045cdbd4cbf7ae19b6efaf2 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 17 Aug 2026 14:49:20 -0500 Subject: [PATCH 1/2] Present the native sandbox as a version 0.5.0 release highlight Add a complete README quick start for Codex, OpenCode, Claude Code, and Pi, explain capability profiles and platform requirements, preserve the shell-contained security boundary, and protect the documentation with regression coverage. --- README.md | 70 ++++++++++++++++++++++++++++++++++- tests/sandbox-policy.test.mjs | 16 ++++++++ 2 files changed, 84 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a5d9a8..6734a29 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ GitHub stars Last commit GitHub issues + HOL Guard scanner Skills: 54 Claude Code plugin OpenCode 1.18.7+ @@ -34,6 +35,25 @@ Credits

+## New in v0.5.0: Lightweight Native Sandboxes + +OpenCode Power Pack now includes an opt-in, fail-closed sandbox runner for safer command execution from **Codex, OpenCode, Claude Code, and Pi**. It gives all four agents one portable capability contract with four least-privilege profiles, while using native Seatbelt isolation on macOS and Bubblewrap on Linux. + +- **Lightweight:** one contained command tree, with no container image, daemon, or persistent sandbox to manage. +- **Portable:** the same CLI and skill policy work from all four supported coding agents. +- **Least privilege:** skills default to `observe`, `develop`, `network-read`, or `publish`, with explicit escalation checks. +- **Fail closed:** unavailable isolation, undeclared escalation, missing confirmation, or backend failure stops execution instead of retrying outside the sandbox. + +Install the CLI, verify the boundary from the active agent session, and run a command with the skill's trusted profile: + +```bash +npm install --global @waybarrios/opencode-power-pack@0.5.0 +opencode-power-pack sandbox doctor --json +opencode-power-pack sandbox exec --skill code-review -- git status --short +``` + +The current guarantee is intentionally precise: the command and its descendants are `shell-contained`. Automatic host routing and whole-agent isolation are not claimed yet. See [run the sandbox from each agent](#run-the-sandbox-from-each-agent) and the [complete compatibility specification](docs/sandbox-compatibility.md). + ## Claude Code Quick Install Run these commands inside Claude Code: @@ -130,7 +150,7 @@ Run the installer directly from the mirror after authentication: npx --registry=https://npm.pkg.github.com @waybarrios/opencode-power-pack list ``` -Maintainers publish the mirror with the `Publish GitHub Package` workflow. Release events publish automatically, while a manual run requires an existing release tag such as `v0.5.0`. The workflow verifies that the tag matches `package.json`, runs the complete `prepublishOnly` test suite, and authenticates with the repository-scoped `GITHUB_TOKEN`; no package token is stored in the repository. +Maintainers publish the mirror with the `Publish GitHub Package` workflow. Release events publish automatically, while a manual run requires an existing release tag such as `v0.5.0`. The workflow verifies that the tag matches `package.json`, uploads the artifact already verified by required release CI without rerunning lifecycle scripts, and authenticates with the repository-scoped `GITHUB_TOKEN`; no package token is stored in the repository. | Profile | Intended use | |---|---| @@ -149,9 +169,10 @@ The npm installer and the full Claude Code/Codex/OpenCode plugins are alternativ ## Sandbox Capability Contract -The package assigns every bundled skill a default least-capability profile and an explicit set of allowed escalations. Inspect the complete contract or resolve one skill from the CLI: +The package assigns every bundled skill a default least-capability profile and an explicit set of allowed escalations. Native plugin and package installations expose the skills but do not install the sandbox executable, so install the npm CLI in the same operating-system environment as the agent: ```bash +npm install --global @waybarrios/opencode-power-pack@0.5.0 opencode-power-pack sandbox doctor opencode-power-pack sandbox resolve --skill code-review opencode-power-pack sandbox resolve --sandbox-profile publish --json @@ -165,6 +186,51 @@ opencode-power-pack sandbox exec --skill code-review -- rg TODO . | `network-read` | Write | Explicitly approved | Denied | | `publish` | Write | Explicitly approved | Explicit confirmation required | +Run an allowed network escalation by naming the destination explicitly: + +```bash +opencode-power-pack sandbox exec \ + --skill code-review \ + --sandbox-profile network-read \ + --allow-domain api.github.com \ + -- curl https://api.github.com/repos/owner/repository +``` + +The literal `--` is required. Everything after it is the contained child command and its arguments. The runner preserves the child exit code and never falls back to an unsandboxed execution. + +### Run the sandbox from each agent + +Run `sandbox doctor` inside the same agent session that will execute the command. Success in a separate terminal does not prove the active agent can start the native backend. + +| Host | How to invoke the runner | +|---|---| +| Codex | Ask Codex to use its shell tool for `opencode-power-pack sandbox doctor`, then for the complete `sandbox exec` command. | +| OpenCode | Ask OpenCode to use its shell tool for `opencode-power-pack sandbox doctor`, then for the complete `sandbox exec` command. | +| Claude Code | Ask Claude Code to use Bash for `opencode-power-pack sandbox doctor`, then for the complete `sandbox exec` command. | +| Pi | Ask Pi to use its shell tool for `opencode-power-pack sandbox doctor`, then for the complete `sandbox exec` command. | + +Use this prompt in Codex, OpenCode, or Pi: + +```text +Use the shell tool to run `opencode-power-pack sandbox doctor`. +If it succeeds, run `opencode-power-pack sandbox exec --skill code-review -- git status --short`. +Do not run the child command separately and do not retry without the sandbox. +``` + +For Claude Code, use the same prompt with `Use Bash` in the first sentence. Keep the entire `sandbox exec` invocation in one host shell call. + +### Platform requirements + +The runner requires Node.js 20.11.0 or newer. + +| Platform | Status | Additional requirements | +|---|---|---| +| macOS | Supported | Native Seatbelt; `sandbox doctor` performs an operational preflight. | +| Linux | Supported | Trusted system installations of `bubblewrap`, `socat`, and `rg`, plus working unprivileged user and network namespaces. | +| WSL2 | Expected, dedicated CI pending | The same Linux dependencies and namespace support. | +| WSL1 | Unsupported | Required namespace primitives are unavailable. | +| Windows native | Fails closed | Platform-specific provisioning and boundary tests are not complete. | + The contract continues to report `advisory` because skill metadata does not enforce itself. The npm package also provides an opt-in `sandbox exec` runner backed by a pinned native runtime. When its operational preflight succeeds, `sandbox doctor` reports `shell-contained`; `Strict ready` remains `no` until a host adapter blocks ordinary tool bypasses. For `network-read`, the runner enforces conventional HTTP read methods (GET, HEAD, and OPTIONS). This is a best-effort side-effect boundary because an approved endpoint can still implement unsafe GET behavior. Use narrow destination grants and expose only credentials required for the retrieval. diff --git a/tests/sandbox-policy.test.mjs b/tests/sandbox-policy.test.mjs index 7135c57..9a6d4b1 100644 --- a/tests/sandbox-policy.test.mjs +++ b/tests/sandbox-policy.test.mjs @@ -23,6 +23,22 @@ function clone(value) { return structuredClone(value); } +test("README announces the sandbox and documents every supported host", async () => { + const readme = await readFile(path.join(REPO, "README.md"), "utf8"); + + assert.match(readme, /New in v0\.5\.0: Lightweight Native Sandboxes/); + assert.match(readme, /sandbox doctor --json/); + assert.match(readme, /sandbox exec --skill code-review -- git status --short/); + assert.match(readme, /Run the sandbox from each agent/); + for (const host of ["Codex", "OpenCode", "Claude Code", "Pi"]) { + assert.match(readme, new RegExp(`\\| ${host} \\|`)); + } + assert.match(readme, /shell-contained/); + assert.match(readme, /Automatic host routing and whole-agent isolation are not claimed yet/); + assert.match(readme, /bubblewrap.*socat.*rg/); + assert.match(readme, /Windows native.*Fails closed/); +}); + test("sandbox contract covers every packaged skill with four ordered profiles", async () => { const skills = await discoverSkills(REPO); const names = skills.map((skill) => skill.name); From 7f7f0912dcb0df70ab9fcd6b4cb2f6aab639f7c1 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Mon, 17 Aug 2026 14:51:12 -0500 Subject: [PATCH 2/2] Prepare OpenCode Power Pack for the HOL plugin registry Add a least-privilege HOL Guard workflow, scanner policy, security reporting guidance, dependency monitoring, and immutable GitHub Action references. Align the Codex marketplace with its local plugin source and keep scanner verification reproducible for the awesome-ai-plugins submission. --- .agents/plugins/marketplace.json | 5 ++-- .codexignore | 18 ++++++++++++ .github/dependabot.yml | 13 +++++++++ .github/workflows/ci.yml | 10 +++---- .github/workflows/claude-smoke.yml | 4 +-- .github/workflows/opencode-smoke.yml | 4 +-- .github/workflows/plugin-security-scan.yml | 29 +++++++++++++++++++ .github/workflows/publish-github-package.yml | 4 +-- .plugin-scanner.toml | 25 ++++++++++++++++ SECURITY.md | 30 ++++++++++++++++++++ skills/sharp-edges/SKILL.md | 4 +-- tests/codex-plugin.test.mjs | 7 ++--- 12 files changed, 133 insertions(+), 20 deletions(-) create mode 100644 .codexignore create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/plugin-security-scan.yml create mode 100644 .plugin-scanner.toml create mode 100644 SECURITY.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index fe241b5..caab921 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -7,9 +7,8 @@ { "name": "opencode-power-pack", "source": { - "source": "url", - "url": "https://github.com/waybarrios/opencode-power-pack.git", - "ref": "main" + "source": "local", + "path": "./" }, "policy": { "installation": "AVAILABLE", diff --git a/.codexignore b/.codexignore new file mode 100644 index 0000000..6d07e06 --- /dev/null +++ b/.codexignore @@ -0,0 +1,18 @@ +# Local environment and credential files +.env +.env.* +!.env.example +*.pem +*.key + +# Dependency and generated output +node_modules/ +coverage/ +dist/ +evals/reports/ + +# Editor and operating-system state +.DS_Store +.idea/ +.vscode/ +*.swp diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..50fcc0d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,13 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af1aa31..9dded26 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,13 +9,13 @@ jobs: lint-skills: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "lts/*" - run: npm ci - run: node --test - - uses: actions/setup-python@v5 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 with: python-version: "3.x" - name: Validate Agent Skills specification @@ -34,8 +34,8 @@ jobs: matrix: os: [ubuntu-latest, macos-latest] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "20.11.1" - name: Install Linux sandbox dependencies diff --git a/.github/workflows/claude-smoke.yml b/.github/workflows/claude-smoke.yml index 4b530ca..bd366bc 100644 --- a/.github/workflows/claude-smoke.yml +++ b/.github/workflows/claude-smoke.yml @@ -15,8 +15,8 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 5 steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "lts/*" - name: Validate plugin and marketplace manifests diff --git a/.github/workflows/opencode-smoke.yml b/.github/workflows/opencode-smoke.yml index 5b48fa1..599e396 100644 --- a/.github/workflows/opencode-smoke.yml +++ b/.github/workflows/opencode-smoke.yml @@ -15,8 +15,8 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 5 steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "24" - run: node scripts/opencode-smoke.mjs 1.18.7 diff --git a/.github/workflows/plugin-security-scan.yml b/.github/workflows/plugin-security-scan.yml new file mode 100644 index 0000000..55fa598 --- /dev/null +++ b/.github/workflows/plugin-security-scan.yml @@ -0,0 +1,29 @@ +name: Plugin Security Scan + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + scan: + name: HOL plugin scanner + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Check out repository + uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - name: Scan plugin package + uses: hashgraph-online/ai-plugin-scanner-action@55616c962cf86368423f7673b2ecdfdbe613d1af # v1.2.515 + with: + plugin_dir: "." + mode: scan + min_score: 80 + fail_on_severity: high + pr_comment: off diff --git a/.github/workflows/publish-github-package.yml b/.github/workflows/publish-github-package.yml index db46775..2648373 100644 --- a/.github/workflows/publish-github-package.yml +++ b/.github/workflows/publish-github-package.yml @@ -25,10 +25,10 @@ jobs: env: RELEASE_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.release.tag_name }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: ref: ${{ env.RELEASE_REF }} - - uses: actions/setup-node@v4 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "20" registry-url: "https://npm.pkg.github.com" diff --git a/.plugin-scanner.toml b/.plugin-scanner.toml new file mode 100644 index 0000000..30a2f7d --- /dev/null +++ b/.plugin-scanner.toml @@ -0,0 +1,25 @@ +[scanner] +profile = "public-marketplace" +# Tests and behavioral-evaluation fixtures are contributor-only and excluded +# from the published npm package. The two reference files intentionally contain +# insecure examples that their skills teach reviewers to detect. +ignore_paths = [ + "tests/*", + "evals/*", + "skills/insecure-defaults/references/examples.md", + "skills/sharp-edges/references/config-patterns.md", + "skills/agentic-actions-auditor/SKILL.md", + "skills/agentic-actions-auditor/references/*", + # Cisco's generic YARA rules treat these reviewed examples as command or + # prompt injection: a Ruby anti-pattern, a shell-free argv list, and HTML + # guidance that mentions a hidden input. + "skills/sharp-edges/references/lang-ruby.md", + "skills/hf-cloud-python-env-setup/scripts/setup_env.py", + "skills/huggingface-lora-space-builder/references/creative-mode.md", +] + +[rules] +# Network-capable Hugging Face skills intentionally document explicit remote +# reads. Keep the findings visible without classifying those expected examples +# as high-severity vulnerabilities. +severity_overrides = { RISKY_SKILL_INSTRUCTION = "medium" } diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..cafde5d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,30 @@ +# Security Policy + +## Supported versions + +Security fixes are applied to the latest published release and the `main` +branch. Older releases should be upgraded before reporting a version-specific +problem. + +## Reporting a vulnerability + +Please use GitHub's private vulnerability reporting flow for this repository: + + + +Include the affected version, host agent and operating system, reproduction +steps, expected security boundary, observed behavior, and any minimal proof of +concept needed to validate the report. Do not include real credentials, +personal data, or secrets. + +Please do not open a public issue for an undisclosed vulnerability. You can +expect an initial acknowledgement within seven days. We will coordinate +validation, remediation, release timing, and public disclosure through the +private advisory. + +## Scope + +Reports about sandbox boundary bypasses, credential exposure, unsafe package +installation, plugin loading, or workflow permission escalation are in scope. +The sandbox runner is currently documented as `shell-contained`; unrelated +host-native tools are not claimed to be isolated until host adapters land. diff --git a/skills/sharp-edges/SKILL.md b/skills/sharp-edges/SKILL.md index d4272a6..7172b4d 100644 --- a/skills/sharp-edges/SKILL.md +++ b/skills/sharp-edges/SKILL.md @@ -147,7 +147,7 @@ public function __construct( ) {} ``` -See [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters) for detailed patterns. +See [config-patterns.md](references/config-patterns.md) for detailed patterns. ### 5. Silent Failures @@ -286,4 +286,4 @@ Before concluding analysis: - [ ] Considered all three adversary types - [ ] Verified error paths don't bypass security - [ ] Checked configuration validation -- [ ] Constructor params validated (not just defaulted) - see [config-patterns.md](references/config-patterns.md#unvalidated-constructor-parameters) +- [ ] Constructor params validated (not just defaulted) - see [config-patterns.md](references/config-patterns.md) diff --git a/tests/codex-plugin.test.mjs b/tests/codex-plugin.test.mjs index fbcfd5b..f1667c0 100644 --- a/tests/codex-plugin.test.mjs +++ b/tests/codex-plugin.test.mjs @@ -57,7 +57,7 @@ test("Codex manifest does not declare absent plugin components", () => { assert.equal("hooks" in manifest, false); }); -test("repository marketplace installs the root plugin from main", () => { +test("repository marketplace installs the root plugin from its checkout", () => { assert.equal(marketplace.name, "opencode-power-pack"); assert.equal( marketplace.interface.displayName, @@ -68,9 +68,8 @@ test("repository marketplace installs the root plugin from main", () => { const [entry] = marketplace.plugins; assert.equal(entry.name, manifest.name); assert.deepEqual(entry.source, { - source: "url", - url: "https://github.com/waybarrios/opencode-power-pack.git", - ref: "main", + source: "local", + path: "./", }); assert.deepEqual(entry.policy, { installation: "AVAILABLE",