diff --git a/.github/SECURITY.md b/.github/SECURITY.md index bedfcaa..aa10f9c 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,4 +1,4 @@ -# Security Policy +# Security Policy & User Trust Model ## Supported Versions @@ -6,12 +6,56 @@ Only the latest release line of **SkillOps (`skillops-cli`)** receives active se | Version | Supported | Notes | | :--- | :---: | :--- | -| **`1.3.x`** | ✅ | 28 AI IDEs & CLIs Transpiler, Lip Gloss TrueColor TUI, SHA-256 Lockfile & Active LTS | +| **`1.3.x`** | ✅ | 28 AI IDEs & CLIs Transpiler, AST Security Scanner (`INV-SKILL-06`), Lip Gloss TUI, SHA-256 Lockfile & Active LTS | | **`1.2.x`** | ⚠️ | Critical security fixes only | | **`< 1.2.0`** | ❌ | End of life — upgrade via `npx skillops-cli@latest` | --- +## 5-Pillar Defense-in-Depth Architecture (Why SkillOps Is Safe to Run) + +Because AI coding Skills (`SKILL.md`), Subagents (`SUBAGENT.md`), and bundled helper scripts (`scripts/*.py`) run inside developer workspaces, **SkillOps** combines automated static analysis with mandatory human code review across 5 independent security pillars: + +### Pillar 1 — 100% Curated, Maintainer-Reviewed Registry (`CODEOWNERS` Gate) +- **No Unverified Remote Fetching:** `skillops-cli` never downloads arbitrary third-party URLs or unreviewed Git repositories at runtime. It installs exclusively from the curated, version-pinned `catalog/` bundled inside the audited release. +- **Mandatory Code Owner Approval:** Every Pull Request targeting `main` is governed by GitHub Ruleset protection (`require_code_owner_review: true` via [`.github/CODEOWNERS`](./CODEOWNERS)). No community PR can be merged without explicit manual line-by-line review from `@OdevMatheus`. +- **Automatic Stale Review Dismissal:** Pushing any new commit to an open PR automatically invalidates prior approvals (`dismiss_stale_reviews_on_push: true`), preventing post-approval commit tampering. + +### Pillar 2 — Deterministic AST Security Scanner & CodeQL SAST (`INV-SKILL-06`) +Every catalog Skill and script is audited on every PR and push by [`src/auditor/security.ts`](../src/auditor/security.ts), [`.github/workflows/ai-ci.yml`](./workflows/ai-ci.yml), and **GitHub CodeQL SAST** ([`.github/workflows/codeql.yml`](./workflows/codeql.yml)): +- **Zero Outbound Network Exfiltration (`forbidden-network-import`):** Blocks outbound network clients (`urllib.request`, `urllib2`, `urllib3`, `http.client`, `httplib`, `socket`, `socketserver`, `requests`, `httpx`, `aiohttp`, `ftplib`, `smtplib`, `telnetlib`, `xmlrpc.client`, `paramiko`, `websocket`, `websockets`) and remote shell pipes (`curl | sh`, `wget | bash`, `Invoke-WebRequest | iex`). Safe offline URL parsers (`urllib.parse`) and local preview servers (`http.server`, `webbrowser`) remain allowed. +- **Zero Dynamic Code Execution & Deserialization (`forbidden-dynamic-exec`):** Blocks `eval()`, `exec()`, `__import__()`, `Function()`, `pickle`, `cPickle`, `marshal`, `shelve`, `ctypes`, `cffi`, and base64-decoded shell execution (`base64 -d | sh`). +- **Zero Unsafe Shell Execution (`forbidden-shell-execution`):** Blocks `os.system()`, `os.popen()`, `os.spawn*()`, `os.exec*()`, `pty`, reverse-shell primitives (`/dev/tcp/`, `nc -e`), and `subprocess` calls with `shell=True`. + +### Pillar 3 — Anti-Trojan Unicode, Symlink & Boundary Containment Guards +- **Anti-Trojan Source & Invisible Prompt Injection (`forbidden-trojan-unicode`):** Blocks CVE-2021-42574 bidirectional Unicode control characters (`U+202A..U+202E`, `U+2066..U+2069`, `U+200E`, `U+200F`, `U+061C`), LLM invisible Unicode Tag smuggling (`U+E0000..U+E007F`), and zero-width script identifier spoofing (`U+200B`, `U+200C`, `U+2060..U+2064`). +- **Zero Symlinks & Opaque Binaries (`forbidden-symlink`, `forbidden-binary-file`):** Rejects symbolic links and compiled binary/archive payloads (`.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.wasm`, `.pyc`, `.zip`, `.tar.gz`, `.7z`, `.jar`) that cannot be inspected in GitHub PR diffs. +- **Strict Repository Boundary Containment (`resolveSafeRepoTargetPath`):** Every planned file write or removal is verified via `path.resolve` containment in [`src/sync/adapters.ts`](../src/sync/adapters.ts) so no path can escape the target repository or overwrite a symbolic link. + +### Pillar 4 — Cryptographic NPM Provenance (`--provenance`) +- Every official release of `skillops-cli` is built and published on GitHub-hosted runners via [`.github/workflows/release-publish.yml`](./workflows/release-publish.yml) using `npm publish --provenance`, generating a verifiable Sigstore attestation linking the npm tarball to the exact commit and workflow run. + +### Pillar 5 — Local Inspection (`--dry-run`) & SHA-256 Lockfile (`.skillops-lock.json`) +- **Pre-Install Inspection:** Run `npx skillops-cli add --dry-run` to inspect every target path before a single byte is written to disk. +- **Cryptographic Drift Protection:** `.skillops-lock.json` stores the SHA-256 hash of every installed file. `skillops add` and `skillops remove` refuse to overwrite or delete locally modified files unless `--force` is explicitly provided. + +--- + +## How Users Can Verify Package & Catalog Integrity Locally + +```bash +# 1. Verify npm package Sigstore provenance signatures +npm audit signatures + +# 2. Preview planned file paths without writing to disk +npx skillops-cli@latest add mcp-architect --dry-run + +# 3. Run the deterministic catalog security scanner on a local clone +node --input-type=module -e 'import { auditCatalogSecurity } from "./dist/index.js"; console.log(auditCatalogSecurity("./catalog"));' +``` + +--- + ## Reporting a Vulnerability **Please do NOT open a public GitHub issue for security vulnerabilities.** @@ -24,12 +68,3 @@ If you discover a security vulnerability in **SkillOps**, please report it priva 4. Suggested mitigation or fix (if available). **Response SLA:** Security reports are acknowledged within **48 hours** and triaged with a remediation plan or advisory within **7 days**. - ---- - -## Scope & Security Principles - -- **Privacy & Local Data Isolation:** Personal user data and local environment variables (`.env*`) must never be committed to the repository. -- **Deterministic & Safe Skill Execution:** All executable skill scripts (`catalog/**/scripts/*`) must operate strictly in read-only analysis mode unless explicitly documented, and must never execute untrusted shell strings (`shell=True`). -- **Prompt & Agent Safety:** AI agent instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `catalog/**/SKILL.md`, `catalog/subagents/**/SUBAGENT.md`) must never instruct agents to bypass security boundaries or expose credentials. -- **Supply Chain & Static Analysis Hygiene:** GitHub Actions, TypeScript (`src/`), and Python (`catalog/**/scripts/*.py`) are continuously audited via **GitHub CodeQL SAST** ([`.github/workflows/codeql.yml`](./workflows/codeql.yml)), Dependabot, and `CODEOWNERS`. diff --git a/CHANGELOG.md b/CHANGELOG.md index 25a88ac..dc862bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- **5-Pillar User Trust Model & Security Documentation (`#193`):** Documented the 5-Pillar Supply-Chain Security & User Trust Architecture (`CODEOWNERS` curated registry, `INV-SKILL-06` AST + CodeQL SAST script gate, Anti-Trojan Unicode/boundary guards, Sigstore NPM `--provenance`, and `--dry-run` + `.skillops-lock.json` SHA-256 verification) in [`README.md`](./README.md) and [`.github/SECURITY.md`](./.github/SECURITY.md). - **`INV-SKILL-06` Security Invariant & Mandatory PR Security Review Checklist (`#192`):** Codified `INV-SKILL-06` (*Zero-Network, Trojan-Free & Boundary-Safe Security Contract*) in [`SKILL_CONTRACT.md`](./SKILL_CONTRACT.md) and added a mandatory supply-chain security review checklist in [`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md). - **Anti-Trojan Unicode, Symlink, Binary & Path Containment Guards (`#191`):** Extended [`src/auditor/security.ts`](./src/auditor/security.ts), [`src/auditor/parser.ts`](./src/auditor/parser.ts), and [`src/sync/adapters.ts`](./src/sync/adapters.ts) (`resolveSafeRepoTargetPath`) to block Trojan-Source (CVE-2021-42574) bidirectional control characters, LLM invisible Unicode Tag smuggling (`U+E0000..U+E007F`), zero-width script identifier spoofing, symbolic links, opaque compiled binary/archive payloads (`.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.wasm`, `.pyc`, `.zip`, `.tar.gz`), and repository boundary path traversal. - **Catalog Script AST & Lexical Security Scanner (`#190`):** Added [`src/auditor/security.ts`](./src/auditor/security.ts) (`auditSkillSecurity`, `auditCatalogSecurity`) and a Python `ast` security gate in [`.github/workflows/ai-ci.yml`](./.github/workflows/ai-ci.yml) to block outbound network modules (`urllib.request`, `http.client`, `socket`, `requests`, `curl | sh`), dynamic execution/deserialization (`eval`, `exec`, `__import__`, `pickle`, `marshal`, `ctypes`), and unsafe shell execution (`os.system`, `os.popen`, `shell=True`) in catalog Skill scripts with zero false positives on legitimate large skills. diff --git a/README.md b/README.md index f160887..fedf703 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@

npm version - CI + CI + CodeQL SAST 28 AI IDEs & CLIs License: MIT

@@ -119,6 +120,20 @@ Every generated file is tracked in `.skillops-lock.json` with a cryptographic di --- +## Security & Trust Model (5-Pillar Defense-in-Depth) + +Installing AI Skills and executable helper scripts into your IDE requires strict supply-chain guarantees. **SkillOps** enforces a **5-Pillar Security Architecture** ([`.github/SECURITY.md`](./.github/SECURITY.md) & `INV-SKILL-06` in [`SKILL_CONTRACT.md`](./SKILL_CONTRACT.md)) so no unreviewed or malicious skill can enter the catalog: + +| Pillar | Guarantee | How It Is Enforced | +| :--- | :--- | :--- | +| **1. 100% Curated & Maintainer-Reviewed Catalog** | Zero arbitrary remote URL fetching; every Skill and Subagent is reviewed line-by-line by a human maintainer before merge. | Protected `main` ruleset + [`.github/CODEOWNERS`](./.github/CODEOWNERS) (`require_code_owner_review: true` & automatic stale-review dismissal on new commits). | +| **2. Deterministic AST & CodeQL Script Gate (`INV-SKILL-06`)** | Bundled scripts run offline using the standard library—never exfiltrating data or executing arbitrary shell strings. | [`src/auditor/security.ts`](./src/auditor/security.ts) + [`.github/workflows/ai-ci.yml`](./.github/workflows/ai-ci.yml) + **GitHub CodeQL SAST** block outbound network clients (`urllib.request`, `http.client`, `socket`, `requests`, `curl \| sh`), `eval()`/`exec()`/`pickle`, and `os.system()`/`shell=True`. | +| **3. Anti-Trojan Unicode & Boundary Guards** | Protects PR reviewers and LLMs from invisible prompt injection, binary droppers, and path traversal. | Blocks CVE-2021-42574 bidirectional Unicode (`U+202A..U+202E`), LLM invisible Unicode Tags (`U+E0000..U+E007F`), symlinks, opaque binaries/archives (`.exe`, `.dll`, `.so`, `.pyc`, `.zip`), and `..` path escapes (`resolveSafeRepoTargetPath`). | +| **4. Cryptographic NPM Provenance** | Every published `skillops-cli` release is cryptographically linked to its exact GitHub commit and CI build. | Published via GitHub Actions with `npm publish --provenance` (verifiable via `npm audit signatures`). | +| **5. Local `--dry-run` & SHA-256 Lockfile** | Preview every planned file before writing to disk and detect unauthorized local modifications. | `npx skillops-cli add --dry-run` + cryptographic SHA-256 digests in `.skillops-lock.json`. | + +--- + ## Contributing (Two-Track Open Source) SkillOps uses a two-track contribution workflow so the community can add new **Skills** and **Subagents** with zero friction: @@ -128,6 +143,7 @@ SkillOps uses a two-track contribution workflow so the community can add new **S | **Track A — Library (`catalog/`)** | New or improved **Skills (`SKILL.md`)** and **Subagents (`SUBAGENT.md`)** | **No — Direct PR** | Add your folder under `catalog///` or `catalog/subagents//` and open a PR directly | | **Track B — Core CLI (`src/`)** | CLI commands, TUI components, 28-IDE transpiler, or schemas | **Yes — Issue First** | Open an Issue to align scope before submitting a Pull Request | +- 🛡️ [**Security Policy & Trust Model (`.github/SECURITY.md`)**](./.github/SECURITY.md) - 📖 [**Contribution Guide (`CONTRIBUTING.md`)**](./CONTRIBUTING.md) - 📜 [**Skill & Subagent Contract (`SKILL_CONTRACT.md`)**](./SKILL_CONTRACT.md) - ⚖️ Licensed under the [**MIT License**](./LICENSE) — Built by [**@OdevMatheus**](https://github.com/OdevMatheus)