Document native sandboxes and prepare the plugin for HOL listing (#33)

Publish the version 0.5.0 sandbox documentation and add the security, marketplace, and CI requirements needed for the awesome-ai-plugins submission.
This commit is contained in:
Wayner Barrios
2026-08-17 15:57:44 -04:00
committed by GitHub
14 changed files with 217 additions and 22 deletions
+2 -3
View File
@@ -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",
+18
View File
@@ -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
+13
View File
@@ -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
+5 -5
View File
@@ -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
+2 -2
View File
@@ -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
+2 -2
View File
@@ -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
@@ -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
+2 -2
View File
@@ -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"
+25
View File
@@ -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" }
+68 -2
View File
@@ -14,6 +14,7 @@
<a href="https://github.com/waybarrios/opencode-power-pack/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/waybarrios/opencode-power-pack?style=flat-square&color=FFD60A"></a>
<a href="https://github.com/waybarrios/opencode-power-pack/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/waybarrios/opencode-power-pack?style=flat-square"></a>
<a href="https://github.com/waybarrios/opencode-power-pack/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/waybarrios/opencode-power-pack?style=flat-square"></a>
<a href="https://github.com/hashgraph-online/hol-guard"><img alt="HOL Guard scanner" src="https://img.shields.io/badge/HOL%20Guard-scanned-00a67e?style=flat-square"></a>
<img alt="Skills: 54" src="https://img.shields.io/badge/skills-54-FFD60A?style=flat-square&labelColor=0B0F14">
<img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-0B0F14?style=flat-square&labelColor=FFD60A">
<img alt="OpenCode 1.18.7+" src="https://img.shields.io/badge/opencode-1.18.7%2B-0B0F14?style=flat-square&labelColor=FFD60A">
@@ -34,6 +35,25 @@
<a href="#acknowledgments"><b>Credits</b></a>
</p>
## 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.
+30
View File
@@ -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:
<https://github.com/waybarrios/opencode-power-pack/security/advisories/new>
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.
+2 -2
View File
@@ -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)
+3 -4
View File
@@ -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",
+16
View File
@@ -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);