mirror of
https://github.com/waybarrios/opencode-power-pack.git
synced 2026-11-18 18:03:43 +00:00
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:
@@ -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",
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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"
|
||||
|
||||
@@ -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" }
|
||||
@@ -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
@@ -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.
|
||||
@@ -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)
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
|
||||
Reference in New Issue
Block a user