From ee53e7d8e7de362029d3ff8e8e0d41bbc0669bd2 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Sun, 15 Mar 2026 10:00:25 +0100 Subject: [PATCH] docs: document contributor security posture checks --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CONTRIBUTING.md | 29 ++++++++++++++++++++++++ docs/contributors/quality-bar.md | 14 +++++++++++- docs/contributors/security-guardrails.md | 2 ++ 4 files changed, 45 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5ff65179..174e3550 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -23,6 +23,7 @@ Use this only when the PR should auto-close an issue: - [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`, or `unknown` for legacy/unclassified content). - [ ] **Triggers**: The "When to use" section is clear and specific. - [ ] **Security**: If this is an _offensive_ skill, I included the "Authorized Use Only" disclaimer. +- [ ] **Safety scan**: If this PR adds or modifies `SKILL.md` command guidance, remote/network examples, or token-like strings, I ran `npm run security:docs` (or equivalent hardening check) and addressed any findings. - [ ] **Local Test**: I have verified the skill works locally. - [ ] **Repo Checks**: I ran `npm run validate:references` if my change affected docs, workflows, or infrastructure. - [ ] **Source-Only PR**: I did not manually include generated registry artifacts (`CATALOG.md`, `skills_index.json`, `data/*.json`) in this PR. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc2cda8d..53f249b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -265,6 +265,34 @@ Do **not** commit generated registry artifacts in a normal PR. These files are c - `data/bundles.json` - `data/aliases.json` +### Security-Sensitive Review (New Skills) + +If your skill contains: + +- shell commands or command-like examples (`curl`, `wget`, `bash`, `powershell`, `irm`, etc.), +- network instructions or credential/token examples, +- direct file-system, process, or mutation guidance, + +add one extra preflight pass: + +```bash +npm run security:docs +npm test +``` + +Expected outcome: + +- ✅ no blocked high-risk examples unless justified, +- ✅ explicit allowlist comments for any deliberate high-risk documentation command patterns + (``), +- ✅ an explicit note in the PR description if examples are intentionally risky and the intended usage requires local admin/hosted environments. + +For offensive or destructive-capability skills, also verify: + +- `risk:` is set to `offensive` or `critical` as appropriate, +- any user confirmation and authorization preconditions are explicit in the instructions, +- the standard "Authorized Use Only" disclaimer is present in the skill when relevant. + Optional hardening pass: ```bash @@ -413,6 +441,7 @@ Before submitting your contribution: - [ ] I've tested the skill with an AI assistant - [ ] I've run `npm run validate` - [ ] I've run `npm run validate:references` and `npm test` when my change affects docs, workflows, or infrastructure +- [ ] I ran the docs security scan (`npm run security:docs`) for any skill containing commands, network access, credentials, or destructive guidance - [ ] I did **not** include generated registry artifacts (`CATALOG.md`, `skills_index.json`, `data/*.json`) in this PR - [ ] My commit message is clear (e.g., "feat: add docker-compose skill") - [ ] I enabled **Allow edits from maintainers** on the PR diff --git a/docs/contributors/quality-bar.md b/docs/contributors/quality-bar.md index 2cd628f7..997be9c9 100644 --- a/docs/contributors/quality-bar.md +++ b/docs/contributors/quality-bar.md @@ -4,7 +4,7 @@ To transform **Antigravity Awesome Skills** from a collection of scripts into a ## The "Validated" Badge ✅ -A skill earns the "Validated" badge only if it meets these **5 quality checks**. Some are enforced automatically today, while others still require reviewer judgment: +A skill earns the "Validated" badge only if it meets these **6 quality checks**. Some are enforced automatically today, while others still require reviewer judgment: ### 1. Metadata Integrity @@ -42,6 +42,16 @@ A list of known edge cases or things the skill _cannot_ do. - _Example_: "Does not work on Windows without WSL." +### 6. Instruction Safety Review + +If a skill includes command examples, remote fetch steps, secrets, or mutation guidance, the PR must document the risk and pass `npm run security:docs` in addition to normal validation. + +`npm run security:docs` enforces a repo-wide scan for: + +- command pipelines like `curl ... | bash`, `wget ... | sh`, `irm ... | iex`, +- inline token/secret-style command examples, +- deliberate allowlisted high-risk documentation commands via ``. + --- ## Support Levels @@ -64,10 +74,12 @@ The canonical validator is `tools/scripts/validate_skills.py`, but the recommend npm run validate npm run validate:references npm test +npm run security:docs ``` Notes: - `npm run validate` is the operational contributor gate. +- `npm run security:docs` is required for command-heavy or risky skill content. - `npm run validate:strict` is a useful hardening pass, but the repository still contains legacy skills that do not yet satisfy strict validation. - Examples and limitations remain part of the quality bar even when they are not fully auto-enforced by the current validator. diff --git a/docs/contributors/security-guardrails.md b/docs/contributors/security-guardrails.md index feb26cf3..3b8edfd2 100644 --- a/docs/contributors/security-guardrails.md +++ b/docs/contributors/security-guardrails.md @@ -39,6 +39,8 @@ _Examples: Linting, Log Analysis, Configuration Auditing._ - **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent. - **Non-Destructive**: Audits should be read-only by default. +- **Documentation review**: Defensive skills with command examples must still be reviewed for unsafe command patterns. +- **High-risk examples** (`curl|bash`, `wget|sh`, etc.) must use explicit allowlisting comments and clear warning context in the skill body when retained for operational examples. ---