guardskills 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guardskills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRODUCTION_READINESS.md

@@ -0,0 +1,89 @@
+# PRODUCTION_READINESS
+
+This checklist tracks readiness for a production-grade `guardskills` release.
+
+## Readiness Scale
+
+- `Done`: implemented and verified in this repository
+- `In Progress`: partially implemented
+- `Pending`: not yet implemented
+
+## P0 Critical (Must-have before production)
+
+1. Deterministic CI gating (`--ci`)  
+Status: `Done`
+
+2. Hard safety limits for resolver (timeouts, max file size/count)  
+Status: `Done`
+
+3. Stable, documented exit codes  
+Status: `Done`
+
+4. Scanner rule coverage for core malware classes  
+Status: `In Progress`
+
+5. False-positive controls with fixture regression tests  
+Status: `Done`
+
+6. End-to-end integration tests for install handoff paths  
+Status: `Done` (command-level integration tests in `tests/add-handoff.test.ts`)
+
+7. Security review of scanner bypass/evasion paths  
+Status: `Pending`
+
+## P1 High (Required for broad adoption)
+
+1. Versioned policy/config file (`guardskills.config.json`)  
+Status: `Done` (supports defaults, resolver limits, and source/override policy)
+
+2. Rule versioning + changelog + compatibility guarantees  
+Status: `Pending`
+
+3. Structured error taxonomy (network/auth/not-found/rate-limit)  
+Status: `Done`
+
+4. Robust retry/backoff for transient GitHub API failures  
+Status: `Done`
+
+5. Performance and memory profiling on large repositories  
+Status: `Pending`
+
+6. Signed release artifacts and provenance (supply chain hardening)  
+Status: `Done` (GitHub release workflow publishes with npm provenance)
+
+## P2 Medium (Operational maturity)
+
+1. Telemetry/metrics (opt-in) for false positive and miss rates  
+Status: `Pending`
+
+2. Policy presets by risk posture (balanced/strict/paranoid)  
+Status: `Pending`
+
+3. Rule documentation auto-generation from source metadata  
+Status: `Pending`
+
+4. Security benchmark corpus with periodic calibration  
+Status: `In Progress`
+
+## Implemented in this sprint
+
+- `--ci` mode: scan + gate only, no install handoff
+- Resolver controls:
+  - `--github-timeout-ms`
+  - `--github-retries`
+  - `--github-retry-base-ms`
+  - `--max-file-bytes`
+  - `--max-aux-files`
+  - `--max-total-files`
+- Expanded scanner rules and markdown executable-content filtering
+- Fixture tests for safe/warning/malicious/prose-only cases
+- Command integration tests for installer handoff and gate behavior
+- Structured resolver errors with retry/backoff strategy
+- CI + release workflows and SECURITY policy
+- Rulebook in `RULES.md`
+
+## Next 3 priorities
+
+1. Add repository integration tests with HTTP fixtures for resolver retries and error classes.
+2. Add scanner benchmark corpus and threshold calibration automation.
+3. Add policy versioning/migration semantics for long-term compatibility.

package/README.md

@@ -0,0 +1,211 @@
+# guardskills
+
+`guardskills` is a security wrapper around `skills` installation.
+
+Instead of:
+
+```bash
+npx skills add https://github.com/vercel-labs/skills --skill find-skills
+```
+
+use:
+
+```bash
+npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
+```
+
+## What It Does
+
+1. Resolves a skill from GitHub.
+2. Scans resolved files for malicious patterns.
+3. Computes a risk decision (`SAFE`, `WARNING`, `UNSAFE`, `CRITICAL`, `UNVERIFIABLE`).
+4. Proceeds to `npx skills add ...` only if gate policy allows.
+
+## Current Readiness
+
+- Current stage: **beta-quality**.
+- Good for internal use and early adopters.
+- Not final production-grade yet; see `PRODUCTION_READINESS.md`.
+
+## Implemented Features
+
+- `guardskills add <repo> --skill <name>`
+- GitHub resolver (`owner/repo` and `https://github.com/...`)
+- Deterministic static scanner with rule matrix in `RULES.md`
+- Score-based decision engine with hard-block guardrails
+- Gate controls:
+  - `--yes` (accept warning)
+  - `--force` (accept unsafe)
+  - `--allow-unverifiable`
+- Modes:
+  - `--dry-run` (scan + decision only)
+  - `--ci` (deterministic gate mode, no install handoff)
+- Config file support:
+  - auto-load `guardskills.config.json` from current directory
+  - or specify explicit path with `--config <path>`
+- Resolver safety controls:
+  - `--github-timeout-ms`
+  - `--github-retries`
+  - `--github-retry-base-ms`
+  - `--max-file-bytes`
+  - `--max-aux-files`
+  - `--max-total-files`
+- Installer handoff to `npx skills add ...` when allowed
+- Structured resolver error taxonomy + retry/backoff
+- Tests:
+  - fixture scanner tests (`safe`, `warning`, `malicious`, `prose-only`)
+  - gate behavior tests
+  - command install-handoff integration tests
+- Release hardening baseline:
+  - `.github/workflows/ci.yml`
+  - `.github/workflows/release.yml` (npm provenance publish)
+  - `SECURITY.md`
+
+## False-Positive Controls
+
+- Markdown is scanned as executable content only:
+  - fenced code blocks
+  - command-like inline snippets
+  - command-style lines
+- Prose-only markdown is ignored for high-risk matching.
+
+## Quick Start
+
+Install dependencies and validate:
+
+```bash
+npm install
+npm run ci
+npm run audit:prod
+```
+
+Local dry-run:
+
+```bash
+guardskills add https://github.com/vercel-labs/skills --skill find-skills --dry-run
+```
+
+Deterministic CI gate:
+
+```bash
+guardskills add https://github.com/vercel-labs/skills --skill find-skills --ci --json
+```
+
+With resolver reliability controls:
+
+```bash
+guardskills add owner/repo --skill name \
+  --github-timeout-ms 15000 \
+  --github-retries 2 \
+  --github-retry-base-ms 300 \
+  --max-file-bytes 250000 \
+  --max-aux-files 40 \
+  --max-total-files 120
+```
+
+## Configuration File
+
+`guardskills` supports repository-local policy and default settings via `guardskills.config.json`.
+
+- Default lookup: `./guardskills.config.json`
+- Explicit path: `--config <path>`
+- CLI flags always override config values.
+
+Starter template:
+
+```json
+{
+  "defaults": {
+    "strict": false,
+    "ci": false,
+    "json": false,
+    "yes": false,
+    "dryRun": false,
+    "force": false,
+    "allowUnverifiable": false
+  },
+  "resolver": {
+    "githubTimeoutMs": 15000,
+    "githubRetries": 2,
+    "githubRetryBaseMs": 300,
+    "maxFileBytes": 250000,
+    "maxAuxFiles": 40,
+    "maxTotalFiles": 120
+  },
+  "policy": {
+    "allowForce": true,
+    "allowUnverifiableOverride": true,
+    "allowedOwners": [],
+    "blockedOwners": [],
+    "allowedRepos": [],
+    "blockedRepos": []
+  }
+}
+```
+
+Template files are included as:
+
+- `guardskills.config.json` (baseline default)
+- `guardskills.config.example.json` (copy/reference template)
+
+## Exit Codes
+
+- `0`: allowed/success
+- `10`: warning not confirmed
+- `20`: blocked (`UNSAFE`, `CRITICAL`, or `UNVERIFIABLE` without override)
+- `30`: runtime/internal error
+
+## Scoring Logic (v3)
+
+Two-layer model:
+
+1. Hard-block guardrails
+2. Weighted risk score (`0-100`)
+
+Formula:
+
+```text
+risk_score = clamp(
+  sum(base_points * confidence_multiplier)
+  + chain_bonuses
+  - trust_credits,
+  0, 100
+)
+```
+
+Severity base points:
+
+- `CRITICAL = 50`
+- `HIGH = 25`
+- `MEDIUM = 12`
+- `LOW = 5`
+- `INFO = 0`
+
+Confidence multipliers:
+
+- `high = 1.0`
+- `medium = 0.7`
+- `low = 0.4`
+
+Standard thresholds:
+
+- `0-29 SAFE`
+- `30-59 WARNING`
+- `60-79 UNSAFE`
+- `80-100 CRITICAL`
+
+Strict thresholds (`--strict`):
+
+- `0-19 SAFE`
+- `20-39 WARNING`
+- `40-59 UNSAFE`
+- `60-100 CRITICAL`
+
+`UNVERIFIABLE` is non-scored and blocked by default unless `--allow-unverifiable`.
+
+## References
+
+- `RULES.md` (scanner matrix, chain bonuses, tuning workflow)
+- `PROJECT_PLAN.md` (project roadmap)
+- `PRODUCTION_READINESS.md` (production checklist/status)
+- `SECURITY.md` (vulnerability reporting policy)

package/RULES.md

@@ -0,0 +1,105 @@
+# RULES
+
+This document is the tuning reference for scanner behavior and scoring.
+
+## Scoring Map
+
+- Severity points:
+  - `CRITICAL = 50`
+  - `HIGH = 25`
+  - `MEDIUM = 12`
+  - `LOW = 5`
+  - `INFO = 0`
+- Confidence multipliers:
+  - `high = 1.0`
+  - `medium = 0.7`
+  - `low = 0.4`
+- Risk formula:
+  - `risk = clamp(sum(base_points * confidence) + chain_bonus - trust_credits, 0, 100)`
+- Trust credits:
+  - allowed only when no `HIGH`/`CRITICAL`
+  - capped at `20`
+
+## Decision Levels
+
+- Standard mode:
+  - `0-29 SAFE`
+  - `30-59 WARNING`
+  - `60-79 UNSAFE`
+  - `80-100 CRITICAL`
+- Strict mode:
+  - `0-19 SAFE`
+  - `20-39 WARNING`
+  - `40-59 UNSAFE`
+  - `60-100 CRITICAL`
+- `UNVERIFIABLE` is separate (not scored), default block unless `--allow-unverifiable`.
+
+## Hard-Block Policy
+
+A finding triggers hard block only when all are true:
+
+- severity is `CRITICAL`
+- confidence is `high`
+- type is one of:
+  - `CREDENTIAL_EXFIL`
+  - `DESTRUCTIVE_OP`
+  - `REMOTE_CODE_EXEC`
+  - `PRIV_ESCALATION`
+
+## Scanner Rule Matrix
+
+| Rule ID | Type | Severity | Confidence | Primary intent | False-positive notes |
+|---|---|---:|---:|---|---|
+| `R001_CREDENTIAL_EXFIL` | `CREDENTIAL_EXFIL` | `CRITICAL` | `high` | Detect credential read followed by outbound transfer | Requires read + network sequence, not standalone mention |
+| `R002_RCE_PIPE` | `REMOTE_CODE_EXEC` | `CRITICAL` | `high` | Detect `download | interpreter` patterns | Anchored to shell-style pipeline |
+| `R003_DESTRUCTIVE_FS` | `DESTRUCTIVE_OP` | `CRITICAL` | `high` | Detect destructive wipe/delete commands | Looks for dangerous targets (`/`, home, root-like paths) |
+| `R004_PRIV_ESC` | `PRIV_ESCALATION` | `CRITICAL` | `high` | Detect risky `sudo` command execution | Focuses on high-risk command verbs |
+| `R005_SECRET_READ` | `SECRET_READ` | `HIGH` | `medium` | Detect secret/token source access | Alone does not hard-block |
+| `R006_NETWORK_POST` | `NETWORK_POST` | `MEDIUM` | `medium` | Detect outbound requests with explicit payload/body | Requires payload/body indicators |
+| `R007_DECODE_EXEC` | `DECODE_EXEC` | `HIGH` | `medium` | Detect decode/deobfuscation with execution sink | Requires both decode and sink |
+| `R008_ENV_ACCESS` | `ENV_ACCESS` | `LOW` | `low` | Detect env reads | Low weight by design |
+| `R009_FILE_STAGE` | `FILE_STAGE` | `LOW` | `low` | Detect temp/staging writes | Low weight by design |
+| `R010_DYNAMIC_EXEC` | `REMOTE_CODE_EXEC` | `HIGH` | `medium` | Detect dynamic execution primitives | Not hard-block unless promoted to critical/high-confidence |
+| `R011_IEX_DOWNLOAD` | `REMOTE_CODE_EXEC` | `CRITICAL` | `high` | Detect PowerShell download-and-execute | Strong signature for malicious behavior |
+| `R012_DOWNLOAD_THEN_EXEC` | `REMOTE_CODE_EXEC` | `HIGH` | `medium` | Detect downloaded artifact executed without verification | Medium confidence because some installers are legitimate |
+| `R013_ENCODED_EXFIL` | `NETWORK_POST` | `HIGH` | `medium` | Detect encoded data sent externally | Requires encoded transform + network |
+| `R014_ARCHIVE_FETCH_EXEC` | `REMOTE_CODE_EXEC` | `HIGH` | `medium` | Detect archive download/extract then execute flow | Can match legitimate bootstrap scripts; not hard-block by itself |
+| `R015_CHMOD_THEN_EXEC` | `REMOTE_CODE_EXEC` | `HIGH` | `medium` | Detect chmod +x followed by execution | Requires local execution sequence, still may appear in installers |
+| `R016_SPLIT_TOKEN_RCE` | `REMOTE_CODE_EXEC` | `CRITICAL` | `high` | Detect obfuscated split-token download-exec signatures | Targets evasion via token splitting/non-word separators |
+
+## Attack Chain Matrix
+
+| Chain ID | Required finding types | Bonus | Intent |
+|---|---|---:|---|
+| `CHAIN_SECRET_EXFIL` | `SECRET_READ` + `NETWORK_POST` | `+25` | Credential/data exfil flow |
+| `CHAIN_DECODE_EXEC` | `DECODE_EXEC` + `REMOTE_CODE_EXEC` | `+30` | Obfuscated payload execution |
+| `CHAIN_ENV_STAGE_EXFIL` | `ENV_ACCESS` + `FILE_STAGE` + `NETWORK_POST` | `+20` | Staged environment exfiltration |
+
+## False-Positive Controls
+
+- Markdown is scanned as executable content only:
+  - fenced code blocks
+  - inline code snippets that look command-like
+  - command-style lines (`$`, `PS>`, `>`, list-item command lines)
+- Prose-only markdown text is ignored for high-risk matching.
+
+## Test Fixtures
+
+Current fixture suite in `tests/scanner-scoring.test.ts`:
+
+- `tests/fixtures/safe`: expected `SAFE`
+- `tests/fixtures/prose-only`: expected `SAFE` (FP guard)
+- `tests/fixtures/warning`: expected `WARNING` with secret+network chain
+- `tests/fixtures/malicious`: expected `CRITICAL` hard block
+
+## Tuning Workflow
+
+1. Add/update a rule in `src/scanner/scan.ts`.
+2. Add fixture content that should trigger (and one that should not).
+3. Assert expected level and chain behavior in `tests/scanner-scoring.test.ts`.
+4. Run:
+   - `npm run typecheck`
+   - `npm test`
+   - `npm run build`
+   - `npm run audit:prod`
+5. If false positives increase, narrow pattern context or lower confidence/severity.

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the latest pre-release and latest stable tag.
+
+## Reporting a Vulnerability
+
+- Do not open public issues for suspected vulnerabilities.
+- Report privately to: `security@guardskills.sh` (placeholder; replace with your real address before public launch).
+- Include:
+  - affected version
+  - reproduction steps
+  - expected vs actual behavior
+  - potential impact
+
+## Response Targets
+
+- Initial acknowledgment: within 72 hours
+- Triage decision: within 7 days
+- Fix and disclosure timeline: risk-based; critical issues prioritized
+
+## Scope
+
+In scope:
+
+- scanner bypasses that cause false negatives for malicious skills
+- install-gate bypasses
+- supply-chain integrity and release artifacts
+
+Out of scope:
+
+- vulnerabilities in third-party skill repositories themselves
+- social engineering reports without technical exploit details

package/bin/guardskills.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/cli.cjs");