@opengroundplan/core 0.1.1

package/registry/skills/perf-budget/references/measurement-sources.md

@@ -0,0 +1,163 @@
+# Measurement sources
+
+A budget is only as real as the thing that measures it. This file covers what each source can tell you, what it cannot, and how much to trust a number from it.
+
+**The rule:** every declared budget names its source and its enforcement point. Without both, it is a wish — it cannot be exceeded, so it cannot be enforced, and it will be discovered as broken by a user.
+
+---
+
+## Field data (real users)
+
+**What it is:** metrics collected from actual sessions on actual devices and networks.
+
+**Tells you:** the truth, at a percentile, across the real distribution of hardware, connections, and usage.
+
+**Cannot tell you:** why. It reports that the 95th percentile got worse without pointing at a line of code. It also lags — you learn about a regression after users experience it.
+
+**Trust:** highest for *whether* a budget is met. This is the only source that can settle a web-vitals budget.
+
+**Watch:** segment by device class, connection, and geography before comparing periods, or a shift in traffic mix reads as a performance change. Sample size matters at the tail — a p99 over a few hundred sessions is noise.
+
+---
+
+## Lab / synthetic runs
+
+**What it is:** scripted runs against a controlled environment, usually in CI.
+
+**Tells you:** deterministic causes, and regression *direction* between two commits. Provides traces and attribution — which resource, which task, which script.
+
+**Cannot tell you:** what real users experience. A lab number is systematically different from a field percentile and is not the budget.
+
+**Trust:** high for detecting a regression early, low as a statement about users.
+
+**Watch:** run-to-run variance on shared CI runners is often large enough to swamp a real regression. Use multiple runs and a median; treat a single run's delta as a hint, not a result. Keep the environment fixed — a runner-size change invalidates every historical comparison.
+
+---
+
+## Build-time size analysis
+
+**What it is:** the bundler's own output — per entry point, per chunk, per module.
+
+**Tells you:** exact bytes, exact attribution, deterministically. The best-behaved measurement in this document.
+
+**Cannot tell you:** parse or execute cost on a real device, or whether the bytes are on a critical path.
+
+**Trust:** very high, and cheap enough to enforce on every change.
+
+**Watch:** compare like with like — same build mode, same flags. Report compressed and uncompressed; compression hides parse cost, which is the expensive part on mid-range hardware.
+
+**Enforcement:** a size check that fails the build is the single highest-leverage performance control available, because it catches the erosion nobody notices.
+
+---
+
+## Production telemetry (server-side)
+
+**What it is:** latency, throughput, and error metrics emitted by the running service.
+
+**Tells you:** real p50/p95/p99 under real load, per endpoint, over time.
+
+**Cannot tell you:** client-perceived time — it excludes network, and it excludes rendering.
+
+**Trust:** highest for backend budgets.
+
+**Watch — the two mistakes:**
+
+1. **Averaging percentiles.** You cannot mean the p99s of ten instances to get a fleet p99. That number is not the 99th percentile of anything. Aggregate from the underlying histogram, or report per-instance.
+2. **Pre-aggregated buckets.** If your histogram's buckets are coarse near the tail, your p99 is an interpolation with error bars nobody shows you. Check bucket resolution before treating a small p99 delta as real.
+
+Also: measurement window length changes the number. A p99 over one minute and a p99 over one day are different statistics.
+
+---
+
+## Distributed traces
+
+**What it is:** per-request timing across service boundaries.
+
+**Tells you:** *where* the time went — which downstream call, how many were made, what was serial that could be parallel.
+
+**Cannot tell you:** aggregate budget compliance, unless sampled well. Head-based sampling at a low rate systematically misses the tail, which is exactly what you are trying to see.
+
+**Trust:** high for diagnosis, low for budget verification unless tail-based sampling is in place.
+
+**Best use:** answering "why did p99 move" after telemetry says it moved. This is the source that reveals fan-out — the count of downstream calls per request, which is the variable most often unbounded.
+
+---
+
+## Database statistics
+
+**What it is:** the database's own query statistics and execution plans.
+
+**Tells you:** which query shapes cost the most, rows examined versus returned, whether an index is used.
+
+**Cannot tell you:** the impact on any specific endpoint, or behavior under concurrency you have not reproduced.
+
+**Trust:** high for query-level facts; a plan from a small dev dataset is not evidence about production.
+
+**Watch:** plans change with data volume and statistics freshness. A query that scans acceptably at ten thousand rows may not at ten million, and dev environments almost never have production cardinality.
+
+---
+
+## Local benchmarks / microbenchmarks
+
+**Tells you:** relative cost of two implementations of the same thing.
+
+**Cannot tell you:** anything about production. The compiler optimizes differently in isolation, caches are warm, there is no contention, and the input is not representative.
+
+**Trust:** low for budgets, moderate for a directional comparison you run yourself.
+
+**Never** use a microbenchmark result as a budget verdict. It is an argument for a change, not evidence of one.
+
+---
+
+## Reading the diff (no measurement)
+
+**Tells you:** that a regression is *likely* — an unbounded query, a new eager import, a loop with a network call.
+
+**Cannot tell you:** magnitude. It is a hypothesis.
+
+**Trust:** 🔴. Always. Report it as an estimate, name it as an estimate, and ask for a measurement.
+
+This is legitimate and useful output when no measurement source exists — "this adds a query inside a loop over an unbounded collection" is worth saying without a number. What is not legitimate is presenting it as a PASS or FAIL against a budget.
+
+---
+
+## Comparing before and after
+
+Most regression reports are wrong because the two numbers are not comparable. Before trusting a delta:
+
+- [ ] Same source for both numbers
+- [ ] Same conditions — device class, network, dataset size, concurrency, build mode
+- [ ] Same measurement window and same aggregation method
+- [ ] Enough samples that the delta exceeds this source's normal variance
+- [ ] The "before" is the merge base, not an older release with unrelated changes in it
+- [ ] The change is the only variable — no dependency bump, no runner change, no traffic-mix shift in the same window
+
+Any unchecked box downgrades the finding to 🟡 and must be stated in the report.
+
+---
+
+## Enforcement points
+
+Where a budget is checked determines whether it survives.
+
+| Point | Catches | Cost of failing | Suitable for |
+|---|---|---|---|
+| Pre-commit / local | erosion, immediately | seconds | bundle size, lint-level checks |
+| CI on every change | regressions before merge | minutes | bundle size, lab vitals, benchmark deltas |
+| Pre-deploy gate | regressions before users | a blocked release | load test results, integration latency |
+| Production alert | real degradation | user impact already occurred | field vitals, latency percentiles, saturation |
+| Periodic review | slow drift | nothing is prevented | trend analysis only |
+
+**A budget with no automated enforcement point does not hold.** It depends on someone remembering, under deadline, to check a number — and that reliably stops happening within weeks. If a budget cannot be automated today, declare it anyway *and* mark it unenforced, so nobody mistakes it for a control.
+
+---
+
+## Confidence tagging
+
+Use these consistently in every report:
+
+- 🟢 — measured on both sides, same source, same conditions, variance accounted for
+- 🟡 — measured, but conditions differ or sample size is thin; state which
+- 🔴 — estimated from reading the change; no measurement exists
+
+Never upgrade a tag to make a report look decisive. A 🔴 estimate honestly labeled is useful; a 🟢 that was never measured destroys trust in every future check.

package/registry/skills/perf-budget/skill.yaml

@@ -0,0 +1,7 @@
+id: perf-budget
+kind: skill
+name: Performance Budget Check
+description: Check a change against budgets declared in project config — web vitals, bundle size, backend latency percentiles — and reject any budget with no measurement source.
+tags: [performance, budgets, web-vitals, latency]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]

package/registry/skills/security-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: security-review
+description: "OWASP-oriented security review of a diff. Use when the user says security review, is this safe, check for vulnerabilities, review before merge, did I leak a secret, injection, SSRF, authz — or when a diff touches auth, input handling, file paths, outbound requests, deserialization, or dependencies. Reports findings with severity; never auto-fixes."
+metadata:
+  version: 1.0.0
+  category: security
+  updated: 2026-07-18
+---
+
+# Security Review
+
+You are an application security reviewer. Your goal is a findings report a developer can act on: what, where, why it is exploitable, and how severe — with no false confidence and no silent edits.
+
+**You never auto-fix.** A security fix changes a trust decision, and a wrong one creates a worse hole while marking the ticket done. Report; let a human decide.
+
+## Before Starting
+
+Read `AGENTS.md` for `security[]` (the repo's declared security rules) and `protectedPaths[]`. Then establish the **trust model** for the diff, because almost every finding depends on it:
+
+- Where does data enter? Public internet, authenticated user, internal service, operator, or the repo itself?
+- What identity is the code running as, and what can it reach?
+- Which boundary is this code on — edge, service, or storage?
+
+If you cannot establish the trust model, say so. "This is safe if `orgId` is server-derived, and a vertical-privilege bug if it comes from the request body" is a legitimate and useful finding.
+
+## How This Skill Works
+
+**Mode 1 — Review a diff.** Default. Only what the change introduces or touches. Pre-existing issues go in a separate section, unmarked as blocking.
+
+**Mode 2 — Review a surface.** A whole area (auth, uploads, the public API). Broader, slower, produces an inventory rather than a verdict.
+
+**Mode 3 — Triage a specific worry.** "Is this SSRF?" Answer one question with an exploit path or a clear "no, because".
+
+## Pass order
+
+Cheapest and highest-yield first. Full per-category grep targets and diff signatures in [references/owasp-checklist.md](references/owasp-checklist.md).
+
+1. **Secrets** — anything credential-shaped in the diff or its history. Highest severity, cheapest check. Patterns in [references/secret-patterns.md](references/secret-patterns.md).
+2. **Authorization** — the most common serious finding in real reviews.
+3. **Injection** — every place data crosses into an interpreter.
+4. **Untrusted-input handling** — deserialization, file paths, uploads, redirects, outbound URLs.
+5. **Crypto, sessions, and configuration** — algorithms, token handling, defaults, headers.
+6. **Dependencies** — new or bumped packages.
+7. **Logging and error handling** — what leaks in output, what is missing for detection.
+
+## Authn vs authz — keep them distinct
+
+The confusion causes real breaches, so name them separately.
+
+- **Authentication** — *who are you?* Failures: weak or missing verification, forgeable tokens, unverified signature, algorithm confusion, session fixation.
+- **Authorization** — *are you allowed to do this, to this object?* Failures: missing check, check in the wrong place, client-supplied identity.
+
+"The endpoint requires a login" answers authn. It says nothing about whether user A can read user B's record. **Every authenticated endpoint still needs an authorization check**, and object-level checks are the ones most often missing.
+
+The four questions for any handler in the diff:
+
+1. Is there an authz check at all?
+2. Is it **object-level** — does it verify *this* actor may touch *this* record — or only role-level?
+3. Is the actor identity **server-derived** (from the session/token) or read from a request parameter? Client-supplied identity is the bug.
+4. Is the check enforced **server-side**, on every path to the resource — including bulk endpoints, exports, search, and admin routes?
+
+A missing object-level check is high severity by default, even when the id looks unguessable. Unguessable is not a control.
+
+## Injection
+
+Anywhere a value crosses into an interpreter: SQL, NoSQL query objects, shell, ORM raw fragments, template engines, LDAP, XPath, header values, log lines, HTML.
+
+The only reliable question: **is the untrusted value data, or is it becoming code/structure?** Parameterization keeps it data. Escaping is a fallback that depends on getting the context right, and mixed contexts (a value inside a script tag inside HTML) are where escaping fails.
+
+Concatenation into a query, command, or template with any untrusted component is a finding. Do not accept "it's validated upstream" without seeing the validation in the diff — and even then, note the coupling.
+
+## SSRF and outbound requests
+
+Any request whose **destination** is influenced by input. Webhooks, URL previews, importers, PDF renderers, image fetchers, "callback URL" fields.
+
+Look for: user-controlled host, scheme, or port; redirect following; DNS names resolving to internal ranges; metadata endpoints; `file://` and other non-HTTP schemes; blocklists (which fail) rather than allowlists (which work). Validating the URL *before* the request but following redirects afterwards is the classic bypass.
+
+## Deserialization and dynamic behavior
+
+Untrusted input reaching a deserializer that can instantiate arbitrary types, a template compiler, a dynamic import, an expression evaluator, or a regex built from input. Native-object deserialization of untrusted data is high severity on its own, before anyone finds a gadget chain.
+
+## Dependencies
+
+For each added or bumped package: is it real and correctly spelled (typosquatting), does the lockfile pin it, does it run install-time scripts, is it maintained, does it pull a large transitive tree, and does the version have known advisories. A dependency added to solve a five-line problem is worth flagging on supply-chain grounds alone.
+
+## Report format
+
+```
+SECURITY REVIEW — <scope>
+
+VERDICT: NO FINDINGS | FINDINGS (n) | BLOCKED — insufficient context
+
+Trust model assumed: <where input comes from, what identity runs this>
+
+FINDINGS
+  [F1] CRITICAL | HIGH | MEDIUM | LOW | INFO — <category, e.g. Broken Access Control>
+       Where:      <file>:<line>
+       What:       <the specific construct>
+       Exploit:    <the concrete path an attacker takes — not "could be exploited">
+       Depends on: <the assumption that makes this real, if any>
+       Fix:        <the direction, not a patch>
+       Confidence: 🟢 confirmed in the diff | 🟡 likely | 🔴 depends on unverified context
+
+PRE-EXISTING (n) — not introduced by this change
+NOT REVIEWED — <what you could not see: runtime config, infra, upstream validation>
+```
+
+**Severity:** CRITICAL = unauthenticated remote impact or a live secret · HIGH = authenticated privilege escalation, data access across tenants, injection with real reach · MEDIUM = requires unusual conditions or yields limited data · LOW = defense-in-depth · INFO = worth knowing, not a vulnerability.
+
+Rules: **no patches in the report.** Every finding names a concrete exploit path or is downgraded to INFO — "could be dangerous" is noise, and noise is what makes teams stop reading security reports. Always fill **NOT REVIEWED**; an incomplete review presented as complete is the worst output here.
+
+## Proactive Triggers
+
+- **A diff adds an endpoint, handler, or route** → check for an object-level authz check unasked.
+- **A credential-shaped string appears in any tracked file** → stop and flag immediately; treat as live until proven otherwise, and note that rotation, not deletion, is the fix.
+- **A dependency is added or bumped** → flag for advisory check, install scripts, and lockfile pinning.
+- **Input reaches a query, command, path, template, or outbound URL** → trace it end to end before anything else.
+- **An authz check appears in client code or a UI condition** → flag; client-side authorization is not authorization.
+- **Error handling is added that returns exception detail to the caller** → flag information disclosure.
+- **A crypto primitive, random source, or comparison is used for a security purpose** → check for the non-security variant (fast RNG, non-constant-time compare).
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Security review this change" | Findings report with severity, exploit path, confidence, and a NOT REVIEWED section |
+| "Did I leak a secret?" | Secret scan of the diff and its history, with rotation guidance — never just deletion |
+| "Is this endpoint safe?" | Per-handler authn/authz analysis against the four questions |
+| "Review these dependencies" | Per-package risk: advisories, install scripts, pinning, maintenance, transitive weight |
+| "Is this SSRF/injection?" | A ruling with the concrete exploit path, or a specific reason why not |
+
+## Communication
+
+Bottom line first: verdict and highest severity. Every finding gets What + Why (the exploit path) + How (direction of fix). Tag confidence: 🟢 confirmed in the diff, 🟡 likely, 🔴 depends on context you could not verify. Never say "secure" — say what you reviewed and what you did not.
+
+## Related Skills
+
+- **test-first**: Use to turn a finding into a regression test — malformed input, authz bypass, injection payload. NOT a substitute for the fix.
+- **architecture-guard**: Use when the fix is "authorize at the boundary" — that is a boundary question. NOT for vulnerability classes.
+- **adr-write**: Use when a security decision constrains future work (where authz lives, which crypto, what the trust boundary is).
+- **spec-driven**: Use when a finding reveals a missing requirement — it goes back through the spec gate, not into the diff.
+- **handoff**: Use to record an unreviewed or accepted-risk diff so the next tool does not assume it was cleared.
+- **onboard**: Use to locate auth, input, and dependency surfaces in an unfamiliar repo before reviewing them.
+- **perf-budget**: Use when a proposed mitigation (extra validation, crypto work) costs measurable latency.
+- Commands: `/review` runs this over the working diff, `/verify` confirms a fix landed, `/adr` records an accepted risk or a trust-boundary decision, `/handoff` carries an open finding forward.

package/registry/skills/security-review/references/owasp-checklist.md

@@ -0,0 +1,190 @@
+# OWASP Top 10 → diff-level checks
+
+For each category: what it means, what to search for in a changed file, and what makes it a finding rather than a note.
+
+---
+
+## A01 — Broken Access Control
+
+The most frequently exploited category, and the most common serious finding in code review.
+
+**Look for in the diff**
+- New route/handler/controller registrations — does each have an authorization check?
+- Identity read from request input: `req.body.userId`, `params.orgId`, a tenant id in a header or query string. **Server-derived identity only.**
+- Object-level checks: does the query filter by the *actor's* scope, or fetch by id and then check nothing?
+- Direct object references — sequential or guessable ids returned or accepted.
+- Bulk and secondary paths: list, search, export, batch, admin, GraphQL resolvers, webhooks. Authz is usually present on `GET /thing/:id` and missing on `POST /things/bulk-export`.
+- Authorization decided in UI code, a client-side route guard, or a hidden form field.
+- CORS changes: wildcard origin, or reflected origin with credentials enabled.
+- Path traversal: user input concatenated into a filesystem path (`..`, absolute paths, null bytes, unicode variants).
+- Ownership transfer: any endpoint where the record's owner field is settable by the caller.
+
+**Finding when:** the actor's authority over *this specific object* is not verified server-side on this path. Severity HIGH by default; CRITICAL if unauthenticated or cross-tenant.
+
+**Not a finding:** role check present *and* the query is scoped to the actor. An unguessable id with no check **is still a finding** — obscurity is not a control.
+
+---
+
+## A02 — Cryptographic Failures
+
+**Look for**
+- Weak or legacy algorithms: MD5, SHA-1 for signatures, DES/3DES, RC4, ECB mode.
+- Password storage with a general-purpose hash instead of a password KDF; missing per-user salt; a work factor never revisited.
+- Hardcoded keys, IVs, or salts (also A05 and a secret finding).
+- A predictable random source used for tokens, session ids, password resets, or nonces — the non-cryptographic RNG is the tell.
+- Secret comparison with `==` instead of a constant-time compare.
+- TLS verification disabled: `verify=False`, `rejectUnauthorized: false`, custom trust-all callbacks.
+- Sensitive data written to logs, caches, URLs, or client-side storage.
+- Home-rolled crypto of any kind.
+
+**Finding when:** confidentiality or integrity depends on the weak construct. Disabled TLS verification is HIGH even in "internal" code — internal is where lateral movement happens.
+
+---
+
+## A03 — Injection
+
+**Look for, per interpreter**
+
+| Interpreter | Signature in a diff |
+|---|---|
+| SQL | string concatenation or interpolation into a query; raw/exec escape hatches in an ORM; dynamic `ORDER BY`/table names |
+| NoSQL | request objects passed straight into a query filter (operator injection via `$`-prefixed keys) |
+| Shell | any process spawn with a shell option and an interpolated argument |
+| Template | user data compiled as a template rather than passed as data (server-side template injection) |
+| HTML | raw-HTML sinks: inner-HTML assignment, "dangerously" APIs, unescaped output in a template |
+| LDAP / XPath | filter strings built by concatenation |
+| Headers / logs | CRLF-injectable values written to a header or log line |
+| Regex | a pattern built from user input, or a catastrophic-backtracking pattern applied to user input (ReDoS) |
+
+**Finding when:** an untrusted value affects the *structure* of the statement rather than being bound as data. Parameterization ends the finding; manual escaping is a MEDIUM note about fragility even when correct today.
+
+**Watch:** ORMs are not automatically safe. Raw fragments, `.where("...")` string forms, and dynamic column names bypass parameterization entirely.
+
+---
+
+## A04 — Insecure Design
+
+Not a code bug — a missing control.
+
+**Look for**
+- No rate limit on authentication, password reset, one-time codes, invitations, or anything expensive.
+- Business logic that trusts client-supplied prices, quantities, discounts, or state transitions.
+- Workflows where a step can be skipped by calling the next endpoint directly.
+- Missing idempotency on operations that move money or send messages.
+- Account enumeration through differing responses or timing on login/reset.
+- No lockout, no anomaly signal, no limit on retry loops.
+
+**Finding when:** the design permits abuse at scale even with every line implemented correctly. Usually MEDIUM; HIGH when money or account takeover is involved.
+
+---
+
+## A05 — Security Misconfiguration
+
+**Look for**
+- Debug mode, verbose errors, stack traces, or a dev toolbar reachable in a non-dev configuration.
+- Default credentials, sample users, or seed data in a non-dev path.
+- Permissive CORS, missing security headers, cookie flags absent (`HttpOnly`, `Secure`, `SameSite`).
+- Overly broad cloud/service permissions, wildcard resource grants.
+- Directory listing, exposed admin or metrics endpoints, health endpoints leaking versions and config.
+- New config with an *insecure default* — the default is what most deployments will run.
+- Values hardcoded at call sites instead of resolving through the config layer with one typed default.
+
+**Finding when:** the insecure state is the default or is reachable in production. A dev-only insecure setting with an enforced guard is INFO.
+
+---
+
+## A06 — Vulnerable and Outdated Components
+
+**Per added or bumped dependency**
+- Known advisories for the exact version.
+- Name correctness — typosquatting relies on a plausible misspelling.
+- Lockfile updated and the version pinned; a floating range means the reviewed version is not the deployed one.
+- Install-time scripts (post-install hooks) — arbitrary code at install time, including in CI.
+- Maintenance signal: last release, single maintainer, recent ownership change.
+- Transitive weight — a large tree for a small need is a supply-chain finding in itself.
+- Vendored or copied code with no upgrade path.
+
+**Finding when:** a known advisory affects the used version (severity follows the advisory), the package is unpinned, or install scripts run untrusted code. Severity MEDIUM to CRITICAL.
+
+---
+
+## A07 — Identification and Authentication Failures
+
+**Look for**
+- Token validation that skips signature verification, accepts `alg: none`, or allows algorithm substitution.
+- Tokens that never expire, or expiry checked client-side.
+- Session id not rotated after login (fixation) or not invalidated at logout / password change.
+- Password reset tokens that are long-lived, reusable, guessable, or not bound to the user.
+- Credentials in a URL or query string (they land in logs and referrers).
+- Multi-factor bypass paths: a "remember device" flow, a backup code path, or an API route skipping the second factor.
+- Hand-rolled authentication where a vetted mechanism exists.
+
+**Finding when:** identity can be forged, replayed, or extended past its intended lifetime. Usually HIGH or CRITICAL.
+
+---
+
+## A08 — Software and Data Integrity Failures
+
+**Look for**
+- **Deserialization of untrusted data** into native objects — the language's own object deserializer, unsafe YAML loaders, unrestricted type resolution in a JSON binder. HIGH on its own.
+- Dynamic code paths driven by input: eval, dynamic import of an input-derived path, template compilation, expression evaluation.
+- Unverified update, plugin, or model downloads — no signature, no checksum.
+- CI/CD changes: a new step running an unpinned action or script, a secret exposed to a fork-triggered workflow, a cache poisoned across branches.
+- Auto-merge or auto-deploy triggered by an untrusted event.
+
+**Finding when:** untrusted data can influence what code runs. This is the category that turns into remote code execution.
+
+---
+
+## A09 — Security Logging and Monitoring Failures
+
+Two directions — both matter.
+
+**Missing:** no log on authentication failure, authorization denial, privilege change, password/email change, admin action, or bulk export. Without these, a breach is undetectable and unreconstructable.
+
+**Excessive:** logging passwords, tokens, keys, full request bodies, personal data, or full card/account numbers. Logs are widely readable and widely retained — a secret in a log is a leaked secret.
+
+Also: log injection (unsanitized newlines in a log line), and error responses returning stack traces or internal identifiers to the caller.
+
+**Finding when:** a security-relevant event is unlogged (MEDIUM) or a secret/PII is logged (HIGH).
+
+---
+
+## A10 — Server-Side Request Forgery
+
+**Look for**
+- Any outbound request whose host, scheme, or port derives from input — webhooks, callbacks, link previews, importers, avatar-from-URL, PDF/HTML renderers, health checkers.
+- Redirect following after validation — validate-then-follow is the standard bypass.
+- Blocklist-based filtering (fails: decimal IPs, IPv6-mapped, DNS names resolving to private ranges, DNS rebinding).
+- Non-HTTP schemes accepted: `file://`, `gopher://`, `dict://`.
+- No egress restriction, so cloud metadata endpoints and internal services are reachable.
+- The response body returned to the caller — that turns blind SSRF into a read primitive.
+
+**Finding when:** the destination is influenced by input without an **allowlist** and redirects are followed. HIGH in a cloud environment where a metadata endpoint is reachable.
+
+---
+
+## Cross-cutting: trace the input
+
+The single most productive technique. For each untrusted value in the diff:
+
+1. **Source** — where it enters (request body, query, header, cookie, file, queue message, third-party response, environment).
+2. **Transformations** — validated? normalized? decoded? Decoding *after* validation defeats the validation.
+3. **Sinks** — every place it lands: query, command, path, template, outbound URL, deserializer, log, response.
+4. **Boundary** — was it authorized before reaching the sink?
+
+A finding is a source reaching a dangerous sink without an adequate control in between. Write the path out in the report — that is the "Exploit" line, and it is what makes the finding credible.
+
+---
+
+## Downgrade honestly
+
+| Situation | Report as |
+|---|---|
+| Exploit path is concrete and visible in the diff | Full severity, 🟢 |
+| Exploit depends on an assumption you could not verify | Full severity, 🔴, with the assumption stated |
+| Control exists but is fragile (manual escaping, blocklist) | MEDIUM, note the fragility |
+| Defense-in-depth gap with no exploit path | LOW or INFO |
+| "This pattern is often dangerous" with no path here | INFO, or leave it out |
+
+Inflated findings are how teams learn to ignore security reports. Every HIGH must survive the question "how exactly?".

package/registry/skills/security-review/references/secret-patterns.md

@@ -0,0 +1,110 @@
+# Secret patterns
+
+The cheapest, highest-severity check. Run it first, over the diff **and** the branch's history — a secret removed in a later commit is still in the history and still compromised.
+
+---
+
+## Shapes to look for
+
+**Prefixed tokens.** Many providers use a recognizable prefix followed by a long random body. Any identifier-looking string with a short alphabetic prefix, a separator, and 20+ characters of high-entropy body deserves a look — cloud keys, API keys, personal access tokens, and bot tokens nearly all follow this shape.
+
+**PEM blocks.** `-----BEGIN` followed by anything containing `PRIVATE KEY`. Never a false positive worth ignoring. RSA, EC, OPENSSH, PGP — all of them.
+
+**Connection strings.** A URI with credentials inline: `scheme://user:password@host`. Covers databases, message brokers, caches, and SMTP. Search for `://` followed by a colon-separated pair before an `@`.
+
+**JWTs.** Three base64url segments separated by dots, starting with the encoded header. A signed token in source is a credential; decode the payload to see whether it is long-lived before deciding severity.
+
+**Cloud access keys.** Fixed-length uppercase alphanumeric identifiers paired with a longer base64-ish secret, often on adjacent lines. The pair is the tell — an id alone is usually not sensitive; the secret beside it is.
+
+**Generic high-entropy assignments.** A variable whose name contains any of `secret`, `token`, `password`, `passwd`, `pwd`, `apikey`, `api_key`, `access_key`, `private_key`, `client_secret`, `auth`, `credential`, `bearer`, `signing_key`, `encryption_key`, `salt`, `session_key` — assigned a literal string of meaningful length.
+
+**Base64 blobs.** Long base64 in a config or source file. Decode before dismissing; encoded is not encrypted.
+
+**Webhook and signing URLs.** Endpoint URLs containing a long opaque path segment are credentials — anyone with the URL can post.
+
+---
+
+## Where to look, beyond source files
+
+| Location | Why it is missed |
+|---|---|
+| Test fixtures and mock data | "It's just a test key" — often it is not |
+| Example env files | Real values pasted over placeholders |
+| CI/CD workflow files | Secrets inlined instead of referenced |
+| Container and orchestration manifests | Env values baked into images |
+| Infrastructure-as-code | Provider credentials, DB passwords |
+| Lockfiles and package manifests | Registry auth tokens in URLs |
+| Notebooks and their saved outputs | Output cells retain printed credentials |
+| Documentation, READMEs, comments | Working examples with working keys |
+| Commit messages | Pasted into the message rather than the file |
+| Build scripts and Makefiles | Hardcoded deploy credentials |
+| Debug logs committed as artifacts | Full request bodies with auth headers |
+| Minified or bundled front-end output | Server-side keys inlined into a client bundle |
+
+---
+
+## Triage: is it live?
+
+Not every match is an incident. Decide in this order:
+
+| Signal | Verdict |
+|---|---|
+| Obvious placeholder (`xxx`, `changeme`, `your-key-here`, `<REDACTED>`, all zeros) | Not a finding |
+| Documented example value from the provider's docs | Not a finding; note the risk of copy-paste |
+| Localhost/test-container credentials in a test fixture | LOW — flag the pattern, not the value |
+| Real-looking, in any tracked file, provider unknown | **Treat as live** — HIGH, verify with the owner |
+| Real-looking, matches a known provider format | **CRITICAL** |
+| Present anywhere in the branch's history, even if removed | Same severity as if present now |
+
+Bias toward flagging. A false positive costs a minute; a missed live key costs an incident.
+
+---
+
+## Reporting a secret
+
+Report the **location and type**, never the value. Do not paste the secret into the report, the commit message, an issue, or a chat.
+
+```
+[F1] CRITICAL — Hardcoded credential
+     Where:  config/database.ts:14
+     What:   connection string with inline password
+     Status: appears live (non-placeholder, matches provider format)
+     Action: 1. ROTATE the credential now — it is compromised
+             2. Remove from code; resolve through the config layer
+             3. Purge from history, or accept that it stays exposed
+             4. Check access logs for use of this credential
+```
+
+**The order matters and it is not negotiable: rotate first.** Deleting the line does not un-leak anything — the value exists in the history, in every clone, in CI caches, and in any fork. Until it is rotated, it is a live credential in an unknown number of places.
+
+---
+
+## The fix direction
+
+Removal is not the fix. The fix is:
+
+1. **Rotate** — invalidate the exposed value at the provider.
+2. **Externalize** — the value resolves through the config layer, from the environment or a secret manager, with one typed default (and the default is never a real credential).
+3. **Prevent** — add the path to ignore rules; add a pre-commit secret scan if the repo supports hooks.
+4. **Purge** — history rewrite if the repo's exposure warrants it. Coordinate; it invalidates every existing clone.
+5. **Audit** — check whether the credential was used by anyone else while exposed.
+
+Never propose "move it to a different file in the repo". Committed is committed.
+
+---
+
+## Cases people get wrong
+
+**"It's only in a private repo."** Private repos get forked, cloned to laptops, mirrored into CI caches, and made public by accident. Private is not a control.
+
+**"It's a test key."** Test keys often have real rate limits, real billing, or real data. And test keys get promoted to production values by whoever copies the file next.
+
+**"It's encrypted."** Check what decrypts it. If the decryption key is in the same repo, nothing is encrypted.
+
+**"It's base64."** Encoding is not encryption. Decode it and re-triage.
+
+**"It's in the client bundle anyway, so it's public."** True for publishable keys, and a serious finding for anything else. Determine which kind it is — a server-side key inlined into a front-end bundle is CRITICAL.
+
+**"We removed it in the next commit."** The history has it. Rotate.
+
+**"It's expired."** Verify that. Many tokens outlive their assumed lifetime, and some providers never expire them.

package/registry/skills/security-review/skill.yaml

@@ -0,0 +1,7 @@
+id: security-review
+kind: skill
+name: Security Review
+description: OWASP-oriented review of a diff — injection, authz, secrets, SSRF, deserialization, dependency risk. Reports findings with severity; never auto-fixes.
+tags: [security, review, owasp, diff]
+targets: [claude-code, cursor, github-copilot, windsurf, cline, codex, gemini-cli, agents-md]
+requiresCapability: [instructions]