diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index 936b76d9..b22c9074 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -231,7 +231,7 @@ Rules: ## 3. 🛡️ Governance & Quality Bar -### A. The 5-Point Quality Check +### A. The 6-Point Quality Check Reject any PR that fails this: @@ -239,7 +239,8 @@ Reject any PR that fails this: 2. **Safety**: `risk: offensive` used for red-team tools? 3. **Clarity**: Does it say _when_ to use it? 4. **Examples**: Copy-pasteable code blocks? -5. **Limitations / Safety Notes**: Edge cases and risk boundaries are stated clearly. +5. **Risk Limits**: If the skill includes shell/network/filesystem/mutation guidance, instructions include explicit prerequisites and warnings. +6. **Repo Security Scan**: Run `npm run security:docs` for command-heavy, network-execution, or token-like guidance in `SKILL.md`. ### B. Risk Labels (V4) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53f249b7..e73c6e58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,9 @@ cp docs/contributors/skill-template.md skills/my-awesome-skill/SKILL.md # 5. Edit and validate npm run validate +# For SKILL.md with shell/network/credential/mutation guidance: +npm run security:docs + # 6. Open a PR git add skills/my-awesome-skill/ git commit -m "feat: add my-awesome-skill for [purpose]" diff --git a/docs/contributors/skill-anatomy.md b/docs/contributors/skill-anatomy.md index 61e262c1..5d0ca23c 100644 --- a/docs/contributors/skill-anatomy.md +++ b/docs/contributors/skill-anatomy.md @@ -158,7 +158,26 @@ More instructions... **Solution:** How to fix it ``` -#### 8. Related Skills +#### 8. Security & Safety Notes (for command/network/offensive skills) + +If your skill includes: + +- shell commands or command-like examples, +- remote fetch/install or token usage guidance, +- file mutation, destructive actions, or privileged operations, + +add a dedicated section before final wrap-up: + +```markdown +## Security & Safety Notes + +- This is safe/unsafe scope +- Required confirmation or authorization +- Example allowlist notes (if needed): + `` +``` + +#### 9. Related Skills ```markdown ## Related Skills diff --git a/docs/contributors/skill-template.md b/docs/contributors/skill-template.md index 3aa67fb4..6e6c0f13 100644 --- a/docs/contributors/skill-template.md +++ b/docs/contributors/skill-template.md @@ -54,6 +54,17 @@ More instructions... - ❌ Don't do this - ❌ Avoid this +## Security & Safety Notes + +- If this skill includes shell commands, command-like examples, network fetches, token/capability strings, or direct mutation guidance, add explicit preconditions and caveats. +- For deliberate risky examples (for example `curl ... | bash`, `wget ... | sh`, credential examples), include a reviewer-visible reason and add an allowlist comment: + +```markdown + +``` + +- If the skill can alter files/systems or run dangerous actions, document confirmation gates and environment expectations (`local-only`, `authorized test environment`, etc.). + ## Common Pitfalls - **Problem:** Description diff --git a/docs/maintainers/audit.md b/docs/maintainers/audit.md index 1e3d40d8..2c93a4a7 100644 --- a/docs/maintainers/audit.md +++ b/docs/maintainers/audit.md @@ -15,7 +15,7 @@ This document summarizes the repository coherence audit performed after the `app ### 1. Conteggi -- `README.md`, `package.json`, and generated artifacts are aligned to the current collection size (`1,254+` skills). +- `README.md`, `package.json`, and generated artifacts are aligned to the current collection size. - `npm run sync:all` and `npm run catalog` are the canonical commands for keeping counts and generated files synchronized. ### 2. Validazione skill @@ -23,6 +23,10 @@ This document summarizes the repository coherence audit performed after the `app - `npm run validate` is the operational contributor gate. - `npm run validate:strict` is currently a diagnostic hardening pass: it still surfaces repository-wide legacy metadata/content gaps across many older skills. - The validator accepts `risk: unknown` for legacy/unclassified skills while still preferring concrete risk values for new skills. +- Repo-wide documentation risk guidance is now covered by `npm run security:docs`: + - detects high-risk command guidance in `SKILL.md`, + - requires explicit allowlists for deliberate command-delivery patterns, + - and blocks token-like examples that look exploitable. ### 3. Riferimenti incrociati @@ -58,6 +62,7 @@ This document summarizes the repository coherence audit performed after the `app npm run validate # validazione skill (soft) npm run validate:strict # hardening / diagnostic pass npm run validate:references # workflow, bundle, and docs/users/bundles.md references +npm run security:docs # documentation command-risk scan (required for security-sensitive guidance) npm run build # chain + catalog npm test # suite test ``` diff --git a/docs/maintainers/release-process.md b/docs/maintainers/release-process.md index ebb3f1b8..896f75a4 100644 --- a/docs/maintainers/release-process.md +++ b/docs/maintainers/release-process.md @@ -17,7 +17,15 @@ This is the maintainer playbook for cutting a repository release. Historical rel npm run release:preflight ``` -2. Optional hardening pass: +2. Mandatory documentation hardening (repo-wide SKILL.md security scan): + +```bash +npm run security:docs +``` + +This is required so every release validates repo-wide risky command patterns and inline token-like examples before publishing. + +3. Optional hardening pass: ```bash npm run validate:strict @@ -25,13 +33,13 @@ npm run validate:strict Use this as a diagnostic signal. It is useful for spotting legacy quality debt, but it is not yet the release blocker for the whole repository. -3. Update release-facing docs: +4. Update release-facing docs: - Add the release entry to [`CHANGELOG.md`](../../CHANGELOG.md). - Confirm `README.md` reflects the current version and generated counts. - Confirm Credits & Sources, contributors, and support links are still correct. -4. Prepare the release commit and tag locally: +5. Prepare the release commit and tag locally: ```bash npm run release:prepare -- X.Y.Z @@ -47,7 +55,7 @@ This command: - creates `chore: release vX.Y.Z` - creates the local tag `vX.Y.Z` -5. Publish the GitHub release: +6. Publish the GitHub release: ```bash npm run release:publish -- X.Y.Z @@ -55,7 +63,7 @@ npm run release:publish -- X.Y.Z This command pushes `main`, pushes `vX.Y.Z`, and creates the GitHub release object from the matching `CHANGELOG.md` section. -6. Publish to npm if needed: +7. Publish to npm if needed: ```bash npm publish diff --git a/docs/users/faq.md b/docs/users/faq.md index 0cd9bc05..a8b2d101 100644 --- a/docs/users/faq.md +++ b/docs/users/faq.md @@ -219,6 +219,24 @@ The repository enforces automated quality control. Your skill might be missing: 2. Usage examples. Run `npm run validate` locally to check before you push. +### My PR failed "security docs" check. What should I do? + +Run the security docs gate locally and address the findings: + +```bash +npm run security:docs +``` + +Common fixes: + +- Replace risky examples like `curl ... | bash`, `wget ... | sh`, `irm ... | iex` with safer alternatives. +- Remove or redact token-like command-line examples. +- For intentional high-risk guidance, add explicit justification via: + +```markdown + +``` + ### Can I update an "Official" skill? **No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead. diff --git a/docs/users/getting-started.md b/docs/users/getting-started.md index e4ff206b..c61ca2f4 100644 --- a/docs/users/getting-started.md +++ b/docs/users/getting-started.md @@ -118,6 +118,8 @@ We classify skills so you know what you're running: - 🔵 **Safe**: Community skills that are non-destructive (Read-only/Planning). - 🔴 **Risk**: Skills that modify systems or perform security tests (Authorized Use Only). +When adding new skills, high-risk guidance is extra-reviewed with repository-wide `security:docs` scanning before release. + _Check the [Skill Catalog](../../CATALOG.md) for the full list._ ---