@rafter-security/cli 0.6.6 → 0.7.1

package/resources/skills/rafter-secure-design/docs/standards-pointers.md

@@ -0,0 +1,102 @@
+# Standards & Frameworks — Pointers
+
+This skill won't re-derive a compliance checklist. Pick the right baseline for your context, read the small number of sections that actually apply, and point your design doc at them. The goal is *known-adequate*, not *comprehensive*.
+
+## How to choose a baseline
+
+Answer these three before picking a framework:
+
+1. **Regulatory scope**: GDPR / CCPA (personal data)? HIPAA (health)? PCI-DSS (payment cards)? SOX (financial reporting)? Each forces specific controls; skipping the wrong one is non-negotiable risk.
+2. **Maturity goal**: "We need something defensible in review" (ASVS L1), "We handle meaningful PII" (ASVS L2 + SAMM intermediate), "We're a high-value target or regulated" (ASVS L3 + NIST SSDF + SOC 2).
+3. **Audit horizon**: will anyone external look at this? If yes, align with their expected framework early; retrofitting evidence is expensive.
+
+## App security baseline — OWASP ASVS
+
+[OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/).
+
+- **L1 — opportunistic**: external-facing apps without sensitive data. Covers basic auth, input validation, encoding, config. This is the floor; below L1 is "indefensible."
+- **L2 — standard**: apps handling PII, business-critical data, or B2B integrations. Adds cryptography requirements, session depth, access-control rigor.
+- **L3 — advanced**: high-value targets, regulated industries, critical infrastructure. Adds deep crypto requirements, defense-in-depth, hostile-environment assumptions.
+
+**Design-time use**: pick your level, scan the chapter for your domain (auth → V2, session → V3, access control → V4, validation → V5, crypto → V6, etc.), lift the requirements that match your design. Don't copy all 280+ requirements — that's audit prep, not design.
+
+`rafter-code-review/docs/asvs.md` has a deeper walk for review time.
+
+## Secure development lifecycle — NIST SSDF / SP 800-218
+
+[NIST Secure Software Development Framework](https://csrc.nist.gov/projects/ssdf).
+
+Four practice areas — *PO* (prepare the org), *PS* (protect the software), *PW* (produce well-secured software), *RV* (respond to vulnerabilities). Most relevant at design time:
+
+- **PW.1**: design software to meet security requirements and mitigate risks — the "why are we doing this skill" requirement.
+- **PW.4**: reuse existing well-secured software — dependency selection (see `docs/dependencies.md`).
+- **PW.6**: configure compilation/build/runtime for security — deployment posture.
+- **RV.1**: identify vulnerabilities on ongoing basis — SCA + scanning.
+
+Use SSDF as the program-level framework; ASVS fills in the per-app details.
+
+## Cloud & infra — CSA CCM / CIS Benchmarks / AWS Well-Architected
+
+- **[CSA Cloud Controls Matrix](https://cloudsecurityalliance.org/research/cloud-controls-matrix/)**: cloud-native control framework, maps to ISO 27001 / SOC 2 / NIST / etc. Good for answering "are we doing the cloud thing right?"
+- **[CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks)** per cloud / OS / Kubernetes: concrete configuration checklists. Use for hardening specific components.
+- **[AWS Well-Architected — Security Pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html)** (or GCP/Azure equivalents): opinionated cloud-architecture guidance. Start here before CCM for most AWS-native designs.
+
+Pick one per component. Don't adopt all three to "maximize coverage" — they overlap and you'll drown.
+
+## Threat modeling reference
+
+- **[Microsoft STRIDE](https://learn.microsoft.com/en-us/security/securing-devops/threat-modeling)** — the classic, used in `docs/threat-modeling.md`.
+- **[MITRE ATT&CK](https://attack.mitre.org/)** — tactics/techniques for *real-world* attacker behavior. Use to sanity-check "what would an attacker actually do?"
+- **[OWASP ASVS-companion ATM process](https://owasp.org/www-project-threat-modeling/)** — OWASP-flavored threat modeling methodology.
+- **[LINDDUN](https://linddun.org/)** — privacy-focused threat modeling (complement to STRIDE for PII-heavy designs).
+
+## Privacy & compliance
+
+- **GDPR**: data minimization, purpose limitation, user rights (access, deletion, portability), data transfer restrictions. Design-time decisions: what you collect, why, how long, where it lives.
+- **CCPA / CPRA**: similar shape, California-specific. Know-your-rights, opt-out of sale.
+- **HIPAA** (US health): PHI definition, covered entity / BA relationships. Requires BAAs with sub-processors.
+- **PCI-DSS** (cards): scope reduction is the name of the game — tokenize early, keep cardholder data out of your systems.
+- **SOC 2**: not a regulation, a report. Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy). Design maps to controls; audit reads evidence.
+- **ISO 27001**: information security management system. Certification is program-level, not design-level, but many controls live in design decisions.
+
+At design time, the answer is usually "we're in scope for X, Y; Z doesn't apply; here's the mapping." Not a full compliance plan — just a pointer.
+
+## AI / LLM-specific
+
+- **[OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/)** (2025): prompt injection, data disclosure, supply chain, poisoning, improper output handling, excessive agency, prompt leakage, vector/embedding weaknesses, misinformation, unbounded consumption.
+- **[MITRE ATLAS](https://atlas.mitre.org/)**: ATT&CK for AI/ML systems.
+- **[NIST AI RMF](https://www.nist.gov/itl/ai-risk-management-framework)**: risk management framework for AI (govern, map, measure, manage).
+- **EU AI Act** (if you ship in EU): risk categories + obligations. High-risk systems have heavy requirements; general-purpose AI has lighter.
+
+`rafter-code-review/docs/llm.md` walks LLM top 10 for review time.
+
+## Cheap-and-fast subset to start with
+
+If you have 30 minutes and need a defensible baseline for a new feature:
+
+1. Pick ASVS L1 or L2 (L2 if any PII).
+2. Read the chapter that matches your design's top risk (auth / input / access control / crypto — whichever is most novel).
+3. Check CIS Benchmark for your cloud + one container-level CIS (if containerized).
+4. Write the applicable compliance scope (GDPR? HIPAA? none?).
+5. Document the threat-model pass result (from `docs/threat-modeling.md`).
+
+This is less than a full compliance program and more than "we winged it." Most features don't need more at kickoff.
+
+## When to hire the specialist
+
+The pointers above get you to "informed designer." They do not replace:
+
+- A pentester on a high-risk launch.
+- A compliance counsel for novel regulatory scope (PCI-DSS 4.0, GDPR cross-border, HIPAA BAs).
+- A third-party audit for SOC 2 / ISO 27001 / FedRAMP.
+
+Budget for these where the risk warrants. Skipping them is a risk transfer to the future, usually at a higher cost.
+
+---
+
+## Exit criteria
+
+- The applicable regulatory scope is named (or "none, B2B internal only, accepted").
+- The baseline framework is picked (ASVS L?, SSDF yes/no).
+- The specific sections of the framework that match this design's novel risks are cited in the design doc.
+- Compliance obligations (if any) are routed to a human owner, not left as "TBD".

package/resources/skills/rafter-secure-design/docs/threat-modeling.md

@@ -0,0 +1,128 @@
+# Threat Modeling — STRIDE on the Specific Design
+
+This is the capstone. Walk after the individual decisions (auth, data, API, ingestion, deployment) are drafted. The goal: stress-test the design by asking "how would an attacker break *this specific thing*?"
+
+## Setup — the diagram you actually need
+
+Before STRIDE, draw two things. Prose is fine; ASCII is fine. Drawings get handwaved.
+
+1. **Data-flow diagram**: boxes for processes, cylinders for stores, arrows for flows. Label each arrow with what crosses it (request type, data fields).
+2. **Trust boundaries**: dotted lines *across* the arrows — every arrow that crosses a boundary is a security control point.
+
+Minimum sketch:
+```
+[Browser] → [CDN/WAF] ┆→ [API Gateway] → [App Service] ┆→ [DB]
+                                           ↓
+                                     [Third-Party API]
+```
+Boundaries: browser↔edge, edge↔app, app↔DB, app↔third-party.
+
+Each boundary is where STRIDE is most productive.
+
+## STRIDE — one per category, per boundary
+
+The trick is not to apply STRIDE globally; apply it to each trust-boundary crossing and each data-store.
+
+### S — Spoofing (identity)
+
+Applied per boundary: can the entity on the other side be impersonated?
+
+- Browser → edge: can an attacker present a valid-looking session cookie / token they didn't earn? (Authn strength, token theft, XSS → cookie steal.)
+- App → DB: is the DB credential stealable? Replayable? Scoped to the app's workload identity, or shared?
+- App → third-party: does the third-party authenticate the calling app? (Mutual TLS? Signed request?) If not, anyone on their egress path can spoof.
+- Human → admin console: how is admin access authenticated, and is that *separate* from user authN?
+
+### T — Tampering (data integrity)
+
+Per boundary + per store:
+
+- Data in transit: TLS version, cert validation, downgrade defenses. "We assume the internal network is safe" is where tampering happens.
+- Data at rest: can a DB compromise *modify* records undetectably? Append-only audit stores + signed rows are the high-assurance pattern.
+- Data in cache / queue: is message integrity validated? (HMAC on queue payloads, especially if they cross services with different trust levels.)
+- Build artifacts: tampering between build and deploy. Signed provenance catches it.
+
+### R — Repudiation
+
+- Is there an audit log that names the actor, the action, the resource, the time, and a request id?
+- Are the actor's identity and the action tamper-evident in the log? A log the app writes to a DB the app can also update is repudiable.
+- For high-value actions (payments, data exports, admin changes), is the log shipped to an append-only store? Separately from app storage?
+- Agents acting on behalf of users: does the log name both? "User X, via agent Y, did Z at T."
+
+### I — Information disclosure
+
+Per boundary + per store:
+
+- Errors: what do error responses reveal? (See `docs/api-design.md` error taxonomy.)
+- Side-channels: timing of login responses (does valid vs invalid username take different time?), response size, cache-hit timing.
+- Logs: what fields are logged? Do they contain credentials / PII / secrets?
+- Backups: who can read them? Are they encrypted separately from live?
+- Debug endpoints: `/debug`, `/metrics`, `/health` — what do they expose? `/metrics` with unauthenticated Prometheus is fine for latency, not for business counters that hint at usage.
+- URL leakage: does the URL contain sensitive data (tokens, email in query string)? URLs end up in logs, browser history, referer headers.
+- Third-party telemetry: does Datadog / Sentry / LogRocket see data it shouldn't? (Session replay tools are notorious for capturing PII.)
+
+### D — Denial of service
+
+- Rate limits exist per endpoint, per user, per IP (see `docs/api-design.md`).
+- Resource exhaustion: big uploads, deep JSON, big arrays, catastrophic regex, zip bombs (see `docs/ingestion.md`).
+- Downstream dep failures: what happens if the third-party API is down? Timeout, circuit-break, fallback? Synchronous calls with no timeout = cascading outage.
+- Queue / cache exhaustion: can a user enqueue infinite work? Background jobs that fan out per user need per-user caps.
+- Expensive operations (LLM calls, ML inference, PDF rendering): per-user and per-tenant quotas. Cost DoS is real.
+
+### E — Elevation of privilege
+
+- AuthZ gaps: user role → admin role escalation. Mass assignment of `role` / `is_admin`. Server-side role check on every sensitive endpoint.
+- Tenant escalation: cross-tenant data access. Row-level isolation enforced by policy engine, not by convention.
+- Horizontal privilege (same role, other user's data): the IDOR / BOLA surface. Resource-scoped authZ.
+- Agent / service escalation: a compromised less-privileged service calling a more-privileged one. Per-caller authZ at the callee.
+- Infra-level: a compromised container breaking out to the host, or to other containers. Non-root, read-only FS, seccomp, network policy.
+
+## Negative-space questions
+
+STRIDE catches the known categories. These catch what STRIDE misses:
+
+- **What did we assume is safe?** List the implicit trust assumptions. "We trust the CDN", "we trust that service X has done authN", "we trust the user to provide their own tenant_id". Each is a fragile assumption to revisit.
+- **What's the worst-case single compromise?** Pick one component — the web server, the DB, the build runner, a maintainer's laptop. How far does compromise spread? Is that acceptable, or does the design need more segmentation?
+- **What's the attacker's goal?** Data theft (who pays for it?), financial fraud (how does it monetize?), denial (who benefits from us being offline?), reputational (activist / extortion). The feasible attacks depend on who'd try.
+- **What changes in an incident?** Under compromise, can you freeze sessions, rotate secrets, disable endpoints? If the runbook starts with "we'll figure it out", design in the controls now.
+
+## Abuse cases — the flipside of use cases
+
+For each primary use case, write the abuse twin:
+
+- "User invites a friend" → "Attacker invites 10,000 friends to spam; legitimate invitee sees their address used as spam source."
+- "User uploads a profile picture" → "Attacker uploads a polyglot SVG to execute script in another user's browser."
+- "User requests a password reset" → "Attacker bulk-enumerates emails or sends reset-spam."
+- "User exports their data" → "Attacker exfiltrates via unthrottled export endpoint."
+
+One abuse twin per use case is enough at kickoff. Each surfaces a control that *should* be in the design but often isn't.
+
+## Agentic / LLM-specific threats (if in scope)
+
+If the design includes LLM or agent components, add these to the walk:
+
+- Prompt injection: untrusted content reaches the model. Can it alter behavior of subsequent tool calls?
+- Excessive agency: what tools does the agent have access to? Tools that write (email, file, DB, shell) are the blast-radius questions. Read-only tools are low-stakes.
+- Data poisoning: RAG indexes over user content — can a user plant content that affects another user's retrieval?
+- Model theft / extraction: API designs that let attackers reconstruct model behavior.
+- Cross-tenant context bleed: if the model sees data from tenant A during a tenant B session, even as a system prompt leak, it's a disclosure bug.
+
+## Output
+
+A threat-modeling pass should produce:
+
+- The DFD / trust-boundary sketch (prose or image).
+- For each boundary / store: the STRIDE findings and the proposed mitigations.
+- The refuse-list items that surfaced (if any).
+- A short list of residual risks the team is knowingly accepting, with a reason.
+- Follow-up items to file as issues (new controls, instrumentation, tests).
+
+---
+
+## Exit criteria
+
+- DFD + boundaries are drawn.
+- STRIDE is applied per boundary (not globally).
+- Negative-space questions are answered.
+- At least one abuse twin is written per primary use case.
+- Residual risks are explicit and accepted in writing, not implicit.
+- Design is ready for implementation — `rafter-code-review` will walk the PR when it lands.

package/resources/skills/rafter-skill-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rafter-skill-review
+description: "Security review of a skill, plugin, or agent extension before you install it. Router skill: pick (a) installing a brand-new skill, (b) updating an already-installed skill, or (c) investigating one that looks suspicious, and Read the matching sub-doc. Pairs with `rafter skill review <path-or-url>` which emits a deterministic JSON report (secrets, URLs, high-risk shell, obfuscation signals). Run this BEFORE copying any third-party SKILL.md, MCP server manifest, Cursor rule, or agent config into your machine. No installation is safe until it has passed."
+version: 0.1.0
+allowed-tools: [Bash, Read, Grep, Glob, WebFetch]
+---
+
+# Rafter Skill Review — Vet Before You Install
+
+Skills are executable context. Installing one gives it Read, sometimes Bash, sometimes network — with your identity and your files. Treat installation the way you treat `curl | sh`: don't.
+
+Before you copy any third-party `SKILL.md`, MCP manifest, Cursor rule, or agent extension into your machine, run this skill.
+
+> This skill replaces `rafter agent audit-skill` (still usable but deprecated — emits a stderr warning and aliases to `rafter skill review`).
+
+---
+
+## Step 0: Always run the deterministic pass first
+
+```bash
+rafter skill review <path-or-git-url>            # emits JSON to stdout
+rafter skill review <path> --format text         # human-readable summary
+```
+
+The command:
+- pulls the skill (if a URL, does a shallow clone into a temp dir),
+- runs `rafter scan local` over the tree,
+- extracts URLs, high-risk shell patterns, obfuscation signals,
+- reads `SKILL.md` frontmatter (`allowed-tools`, `version`, etc.),
+- prints a structured JSON report — see `shared-docs/CLI_SPEC.md` §`rafter skill review`.
+
+Exit code `0` means the deterministic pass found nothing. **That does NOT mean the skill is safe.** LLM prompt injection, sneaky data practices, and authorship fraud are invisible to regex. Always follow up with the Choose-Your-Adventure branch below.
+
+---
+
+## Choose Your Adventure
+
+Pick exactly one branch. Read only that sub-doc — do not flood your context with all six.
+
+### (a) I am installing a brand-new skill
+
+Use this when: you've never had this skill on this machine, and you want to know if it's safe to install for the first time.
+
+**Walk in order:**
+
+1. **`Read docs/authorship-provenance.md`** — who wrote it, how old, how signed, how widely installed. Stop early if provenance is weak.
+2. **`Read docs/malware-indicators.md`** — grep for obfuscation, binary blobs, postinstall scripts, known-bad URL patterns.
+3. **`Read docs/prompt-injection.md`** — scan prose for hidden instructions, zero-width characters, conflicting directives in long files.
+4. **`Read docs/data-practices.md`** — which files/paths does it read and write, what network calls, does it silently escalate via `allowed-tools`.
+5. **`Read docs/telemetry.md`** — phone-home URLs, analytics SDKs, anonymous-but-trackable IDs.
+
+Sign off only when every branch has a file:line answer. Partial confidence = don't install.
+
+### (b) I am updating a skill I already have installed
+
+Use this when: a new version of a skill you already trust is out and you're about to overwrite the installed copy.
+
+- **`Read docs/changelog-review.md`** — focuses on *what changed*: diff between old and new SKILL.md + sub-docs, new URLs, new shell, new tool grants, version-bump semantics. Provenance shifts (new maintainer, transferred repo, republished package) get their own checklist here.
+- If the diff touches prompts, tools, or network → also walk `docs/prompt-injection.md` and `docs/data-practices.md` on the changed sections only.
+
+### (c) I am investigating a skill that already looks suspicious
+
+Use this when: something smells wrong (someone reported it, the name is a typo-squat, it showed up uninstalled, a finding from step 0 alarmed you).
+
+- **`Read docs/malware-indicators.md`** first — prioritize obfuscation and binary-blob checks.
+- **`Read docs/prompt-injection.md`** — the skill may be weaponized against the installer, not the end user.
+- **`Read docs/authorship-provenance.md`** — map the real author (not the claimed one), check other artifacts from the same account.
+- **`Read docs/telemetry.md`** and **`docs/data-practices.md`** in parallel — data exfil is often what the attacker wants.
+
+If any branch yields a concrete indicator: do not install. File the finding with `rafter issues create from-text`, or attach to an existing PR / ticket with file:line evidence.
+
+---
+
+## What this skill will NOT do
+
+- It will not tell you a skill is "safe". There is no global safe list. Trust is per-install, per-machine, per-version.
+- It will not replace `rafter scan`. The JSON report from step 0 is the evidence floor, not the ceiling.
+- It will not evaluate skills you've already installed and run — by that point the exfil already happened. This is pre-install gating only.
+
+---
+
+## Fast path — copy-paste
+
+```bash
+# Local path
+rafter skill review ./third-party-skill/ --json > report.json
+
+# Git URL (shallow-cloned into temp dir; removed after review)
+rafter skill review https://github.com/acme/their-skill.git --json > report.json
+
+# Human-readable
+rafter skill review ./third-party-skill/
+```
+
+If the command exits 1 → findings present → walk branch (a) or (c) above.
+If exit 0 → deterministic pass clean → still walk branch (a) for a new install.
+
+## Decision rule
+
+Install only if **all three** are true:
+
+1. `rafter skill review` exit 0 (or every finding is explained and accepted).
+2. The branch you walked has no unanswered questions.
+3. `allowed-tools` is narrower than or equal to what the skill's stated purpose requires.
+
+If in doubt, don't install. Re-evaluating later is cheap; removing a backdoor is not.

package/resources/skills/rafter-skill-review/docs/authorship-provenance.md

@@ -0,0 +1,82 @@
+# Authorship & Provenance
+
+Who wrote the skill, how can you verify it, how long has it existed, and how widely is it already installed. A skill with perfect code and a brand-new pseudonymous author is still risky — provenance is the first filter, before reading a single line.
+
+## 1. Identify the claimed author
+
+Check all of:
+- `SKILL.md` frontmatter (`author`, `maintainer`, `url` fields if present).
+- `package.json` / `pyproject.toml` `author`, `maintainers`, `repository`.
+- Git history: `git log --format='%an <%ae>' | sort -u | head`.
+- README "Author" section.
+
+Mismatch between any of these = investigate before trusting any single source.
+
+## 2. Age and activity
+
+- **Repo age**: `git log --reverse --format='%ai' | head -1`. A repo created last week, publishing a complex security skill, is not automatically malicious — but it deserves more scrutiny.
+- **Number of independent contributors**: `git shortlog -sne`. One-author repos are common; zero-external-contributor repos that claim many users are suspicious.
+- **Commit cadence**: bursts right before a release with no prior activity suggest a hijacked or squatted name.
+
+## 3. Signing and verification
+
+- `git log --show-signature <ref>` — does the claimed maintainer actually sign?
+- `gh release view <tag>` — are release artifacts signed / checksummed?
+- For npm: `npm view <pkg> dist.integrity` and `npm audit signatures`.
+- For PyPI: look for Sigstore `.sigstore` files on the release page, or check `pip install --require-hashes`.
+
+Unsigned does not automatically mean bad. **Changed signatures** (used to sign, now doesn't) or **signature mismatch with claimed maintainer** is a hard reject.
+
+## 4. Distribution provenance
+
+- **Registry page**: `npm view <pkg>`, `pip show <pkg>`, plugin marketplace page.
+- **Download count / star count**: high numbers don't prove safety, but sudden spikes after a rename / transfer can indicate squatting.
+- **Transferred ownership**: `npm view <pkg> maintainers` history, `pypi` project audit log, GitHub transfer events. A skill that changed hands recently is a classic supply-chain pattern — the new owner publishes a trojaned version to existing users.
+- **Typo-squat check**: compare name to popular legitimate skills. Levenshtein distance of 1–2 from a well-known name, combined with recent registration, is a strong signal.
+
+## 5. Parallel artifacts from the same author
+
+Look at the author's other repos / packages:
+
+- Similar skills with credentials-adjacent behaviour? Pattern.
+- Aggressive telemetry in every project? Pattern.
+- Consistent style, history, maintainer responsiveness? Good signal.
+- Prior CVEs, prior account bans? Hard signal against.
+
+```bash
+gh api users/<login>/repos --jq '.[].full_name' | head -40
+```
+
+Skim a few for the same malware-indicator red flags — if two of them trip, treat this one as untrusted regardless of its own code.
+
+## 6. Independent endorsement
+
+A skill on its own repo's README can claim anything. Look for external signals:
+
+- Referenced in a blog post, conference talk, or mainstream doc.
+- Shipped as a recommended default by a tool's maintainers (not the skill author).
+- Reviewed by a known security practitioner with evidence (post + date + sample output).
+
+Absence of endorsement doesn't mean rejection, but presence of strong endorsement can lower the scrutiny level.
+
+## 7. Revocation readiness
+
+Even trusted skills fail. Before you install:
+
+- Know where the skill lives on disk (`rafter skill list --installed --json`).
+- Know how to remove it (`rafter skill uninstall <name>` if rafter-authored, otherwise manual delete).
+- Know what config files it might have written (walk `docs/data-practices.md` §2).
+- Keep a fresh shell open to re-verify the install path after install.
+
+## 8. Checklist summary
+
+Before proceeding to code-level review:
+
+- [ ] Claimed author matches git history and registry metadata.
+- [ ] Repo is at least a few releases old, OR endorsed by a trusted source.
+- [ ] Commits are signed by the claimed maintainer (or signing is consistently absent).
+- [ ] Ownership hasn't transferred recently without documented reason.
+- [ ] Name is not a typo-squat of a well-known skill.
+- [ ] Author's other artifacts don't trip the malware-indicator checklist.
+
+Two or more gaps = rescope to "only install in a sandbox after deep code review", or reject.

package/resources/skills/rafter-skill-review/docs/changelog-review.md

@@ -0,0 +1,99 @@
+# Changelog / Update Review
+
+You trusted v1.2 last month. v1.3 came out. Most of your past trust is stale — you need to re-verify what changed, not re-verify everything. This doc is the diff-focused companion to the other sub-docs.
+
+## 1. Produce the diff
+
+For a local copy:
+```bash
+# If you have the old version installed and the new version in a directory:
+diff -ru ~/.claude/skills/<name>/ /path/to/new-version/ > /tmp/skill.diff
+```
+
+For a git-published skill:
+```bash
+git -C /tmp/<skill>-old log --oneline
+git -C /tmp/<skill>-old diff <old-tag>..<new-tag> > /tmp/skill.diff
+```
+
+Skim top-to-bottom once. Then walk the sections below.
+
+## 2. What must be re-reviewed on every update
+
+These categories always need a fresh walk on the new version:
+
+1. **`allowed-tools` changes** — widening by even one tool resets trust. Narrowing is fine.
+2. **New outbound URLs** — each one demands §3 of `docs/data-practices.md`.
+3. **New shell invocations** — walk `docs/malware-indicators.md` §2.
+4. **New filesystem writes or reads outside the previous set**.
+5. **New `WebFetch` / live-remote dependencies**.
+6. **New env vars read**.
+
+Use:
+```bash
+grep -E '^\+' /tmp/skill.diff | grep -E 'allowed-tools|https?://|curl|wget|Bash|WebFetch|writeFile|process\.env|os\.environ'
+```
+
+## 3. Version semantics
+
+- **Patch bumps (x.y.Z)**: should be bugfixes + docs. A patch bump with new tools / URLs is a provenance red flag — the maintainer is either careless or pretending.
+- **Minor bumps (x.Y.z)**: new feature work. Expect new code surface; re-walk the relevant sub-doc.
+- **Major bumps (X.y.z)**: re-evaluate from scratch — treat the new version as a new skill. Walk branch (a) of the main SKILL.md.
+
+If the skill has no versioning or a single rolling `latest` tag, it's effectively a major bump every time. Do not auto-update.
+
+## 4. Maintainer transfer / republish
+
+The single highest-risk update pattern:
+
+- Original maintainer transfers ownership (`npm owner add/rm`, GitHub transfer, PyPI project transfer).
+- A dormant package springs back to life with a large version bump.
+- Package is unpublished then republished (sometimes with a version hole filled in).
+
+On any of these: treat as a new install. Re-walk `docs/authorship-provenance.md` from scratch. Do NOT reuse old trust.
+
+## 5. Silent changes to trust-adjacent files
+
+A changelog may claim "docs only" while the actual diff includes:
+- New entries in `scripts.postinstall` / `setup.py` install hook.
+- New entries in `.claude/settings.json` if the skill distributes one.
+- New entries in `.rafter.yml` defaults.
+- Changes to bundled fixtures that become runtime data.
+
+Grep the diff for changes to any file outside `*.md` and the skill's explicitly declared source paths.
+
+## 6. Dependency drift
+
+If the skill ships deps:
+- `package.json` / `package-lock.json` / `pyproject.toml` / `poetry.lock` / `requirements.txt`.
+- Any new dep at a new major version = walk that dep's own provenance briefly.
+- Any replaced dep (A → B) = check B's provenance.
+- Any dep that resolves to a different registry (e.g. `--index-url` change) = reject-or-investigate.
+
+Tools:
+```bash
+npm diff <pkg>@<old> <pkg>@<new>              # raw file-level diff
+npm view <new-dep>                            # provenance of any newcomer
+pip-audit                                     # known CVEs in the new lockfile
+```
+
+## 7. Prompt / SKILL.md diffs
+
+Even a "prose-only" diff can install a prompt-injection vector:
+- Any newly inserted `Bash:` heredoc.
+- New `<details>` sections.
+- New `WebFetch` references.
+- New "also run …", "after each step, …", "silently …" phrasing.
+
+If the SKILL.md diff is non-trivial, walk `docs/prompt-injection.md` on the changed sections.
+
+## 8. Decision rule
+
+Accept the update if **all** are true:
+
+- The diff is small enough to read end-to-end without skipping.
+- Every new capability (tool, URL, shell, write) is justified in the changelog and in the code.
+- The maintainer identity is unchanged from the last trusted version.
+- No trust-adjacent file silently changed.
+
+Otherwise: pin to the previous version and file the concerns upstream. A pinned-old version that still works beats a new version that might exfil — every time.

package/resources/skills/rafter-skill-review/docs/data-practices.md

@@ -0,0 +1,88 @@
+# Data Practices
+
+What the skill reads, what it writes, where it sends bytes. The goal: a complete map of the skill's I/O before installation.
+
+> The JSON report from `rafter skill review` gives you URLs and some command patterns. This doc is the structured follow-up: enumerate surface, then decide.
+
+## 1. Filesystem reads
+
+For every Read / Glob / Grep / `cat` the skill performs, answer:
+
+| Question | Expected answer |
+|----------|----------------|
+| Is the path derived from user input? | Yes, and validated — or no, it's a fixed project path. |
+| Does it glob `~/` or `/` roots? | Only with explicit exclusions of credential dirs. |
+| Does it follow symlinks? | Only if documented and scoped. |
+| Does it touch `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config/gh`, `~/.netrc`, `~/.git-credentials`, browser profiles, password managers? | No. Any yes = reject. |
+
+Flag: `fs.readFileSync`, `open(...)`, `readFile`, `fs.readdir`, `glob(...)` with patterns broader than the stated purpose requires.
+
+## 2. Filesystem writes
+
+Every Write / `mv` / `cp` / `mkdir` needs justification:
+
+- **In-repo writes**: fine, if the file is one the user expects the skill to produce.
+- **Home-dir writes**: must be `~/.<skill-name>/` or equivalent scoped dir. Writes to `~/.bashrc`, shell rc files, `~/.config/systemd`, crontab, launchd plists are persistence = reject.
+- **System-wide writes** (`/etc`, `/usr/local`): reject unless the skill is documented as a sysadmin tool AND requires explicit sudo with prompt.
+
+Search the tree:
+```bash
+rg -n 'writeFileSync|fs\.write|open\([^)]*"[wa]"|createWriteStream|\.mkdirSync' <skill>
+rg -n '\.bashrc|\.zshrc|\.profile|crontab|systemctl|launchctl' <skill>
+```
+
+## 3. Network calls
+
+List every outbound URL the skill touches. For each, answer:
+
+1. Is the domain owned by the claimed maintainer? (Check WHOIS / org owner.)
+2. Is it HTTPS? Pinned to a specific path and version?
+3. Is it called at install time, at run time, or both?
+4. Does it include any data from the user's repo or machine as query/body?
+5. Is failure handled by **stopping**, not by falling back to a plain-text alternative?
+
+Red flags:
+- Outbound POSTs whose body includes file contents, env vars, or user prompts.
+- `User-Agent` strings that encode a machine ID or repo name.
+- Fallback chains: "try HTTPS, else HTTP, else cache" — the else branches are a downgrade attack.
+
+## 4. Environment variable access
+
+Every `process.env.FOO` / `os.environ["FOO"]` is a potential credential sink. Enumerate them and split:
+
+- **Expected**: `RAFTER_API_KEY` in a rafter-adjacent skill, `OPENAI_API_KEY` in an AI tooling skill.
+- **Unexpected**: `AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, `NPM_TOKEN`, `ANTHROPIC_API_KEY`, `DATABASE_URL`. These should never be read by a skill unless that's the skill's stated purpose.
+- **Leaky**: any env var that's then passed into a network call (step 3) or into a shell invocation (step 5).
+
+## 5. Shell / tool invocation
+
+Skills declare `allowed-tools` in frontmatter. Reconcile:
+
+- **Stated purpose vs. allowed-tools**: a "code review" skill that declares `allowed-tools: [Bash, Write, WebFetch]` is asking for more than the purpose justifies.
+- **Minimal grant**: `Read, Glob, Grep` is usually enough for analysis skills. Each extra tool (`Bash`, `Write`, `WebFetch`, `Edit`) needs a sentence of justification in SKILL.md.
+- **Shell calls in `Bash`**: for every shell command the skill invokes, re-run `rafter skill review` worth of checks against that command specifically.
+
+## 6. Silent escalation
+
+Patterns where the skill widens its own surface at run time:
+
+- Adds new tools via MCP server registration.
+- Writes to `settings.json` / `.claude/settings.json` to grant permissions.
+- Modifies `.rafter.yml` or other policy files.
+- Changes shell rc files to export new env vars / aliases.
+
+Any of these = reject unless they are the skill's stated, headline feature (e.g., a skill whose whole job is installing MCP servers).
+
+## 7. Data classification of outputs
+
+For any data the skill emits to stdout / files / network, classify:
+
+- **Public**: analysis results, counts, categories. Safe.
+- **Repo-private**: code snippets, file names, diffs. Only OK on HTTPS to a maintainer-owned URL the user has already trusted.
+- **Credential-adjacent**: .env files, `~/.aws/config`, keychain excerpts. Should never leave the machine via a skill.
+
+---
+
+## Decision rule
+
+Write out, in one paragraph, the skill's total I/O surface: read-set, write-set, outbound URLs, env vars. If that paragraph has any surprises relative to the skill's stated purpose, reject. If every item is expected and scoped, proceed to `docs/telemetry.md`.