vanara 0.1.0 → 0.3.0

package/catalog/skills/error-handling-patterns/scripts/lint-empty-catch.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Runnable linter: scans source code for SWALLOWED errors — the #1 error-handling
+// defect. Flags empty catch blocks, bare `except: pass`, no-op promise .catch
+// handlers, and ignored Go errors. Use it in CI to fail builds that hide failures.
+//
+// Usage:
+//   node lint-empty-catch.mjs <file> [<file>...]   # lint files, exit 1 if any findings
+//   echo '<code>' | node lint-empty-catch.mjs       # lint code from stdin
+//   node lint-empty-catch.mjs --selftest            # run built-in test cases
+//
+// Exit code: 0 = clean, 1 = swallowed errors found (or a selftest case failed).
+
+import { readFileSync } from 'node:fs';
+
+// Each rule: a label and a regex matching a swallow anti-pattern.
+// Patterns are intentionally conservative to limit false positives.
+const RULES = [
+  // JS/TS/Java/C#: catch with an empty or whitespace/comment-only body.
+  ['empty catch block', /catch\s*(\([^)]*\))?\s*\{\s*(\/\/[^\n]*\s*|\/\*[\s\S]*?\*\/\s*)*\}/g],
+  // JS/TS: a promise .catch that does nothing.
+  ['no-op .catch handler', /\.catch\s*\(\s*\(?\s*[\w$]*\s*\)?\s*=>\s*\{\s*\}\s*\)/g],
+  // JS/TS: .catch(() => undefined) style swallow.
+  ['no-op .catch (returns nothing)', /\.catch\s*\(\s*\(?\s*[\w$]*\s*\)?\s*=>\s*(undefined|null|void 0)\s*\)/g],
+  // Python: bare except (optionally typed) whose only statement is pass.
+  ['python except: pass', /except\b[^\n:]*:\s*(\n\s*)?pass\b/g],
+  // Python: except whose only statement is `...` (ellipsis stub left in prod).
+  ['python except: ...', /except\b[^\n:]*:\s*(\n\s*)?\.\.\.\s*/g],
+  // Go: an `if err != nil` block that is empty.
+  ['go empty err check', /if\s+err\s*!=\s*nil\s*\{\s*\}/g],
+];
+
+export function lint(source) {
+  const findings = [];
+  for (const [label, re] of RULES) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+      const line = source.slice(0, m.index).split('\n').length;
+      findings.push({ label, line });
+      if (m.index === re.lastIndex) re.lastIndex++; // guard against zero-width loops
+    }
+  }
+  findings.sort((a, b) => a.line - b.line);
+  return findings;
+}
+
+function lintLabeled(label, source) {
+  const findings = lint(source);
+  if (findings.length === 0) {
+    console.log(`✓ ${label}: no swallowed errors`);
+    return true;
+  }
+  console.error(`✗ ${label}: ${findings.length} swallowed error(s)`);
+  for (const f of findings) console.error(`    line ${f.line}: ${f.label}`);
+  return false;
+}
+
+function selftest() {
+  // name starts with "clean" => expect 0 findings; otherwise expect >=1 finding.
+  const cases = {
+    bad_empty_catch: 'try { risky(); } catch (e) {}',
+    bad_catch_comment_only: 'try { risky(); } catch (e) {\n  // ignore\n}',
+    bad_noop_promise_catch: 'doThing().catch(() => {});',
+    bad_noop_catch_undefined: 'doThing().catch(e => undefined);',
+    bad_python_except_pass: 'try:\n    risky()\nexcept Exception:\n    pass',
+    bad_python_except_ellipsis: 'try:\n    risky()\nexcept ValueError:\n    ...',
+    bad_go_empty_err: 'v, err := load()\nif err != nil {}\nuse(v)',
+    clean_handled_catch: 'try { risky(); } catch (e) {\n  logger.error(e);\n  throw e;\n}',
+    clean_handled_promise: 'doThing().catch(e => logger.error(e));',
+    clean_python_handled: 'try:\n    risky()\nexcept Exception as e:\n    log.error(e)\n    raise',
+    clean_go_handled: 'v, err := load()\nif err != nil {\n  return err\n}\nuse(v)',
+  };
+
+  let allExpected = true;
+  for (const [name, code] of Object.entries(cases)) {
+    const found = lint(code).length;
+    const shouldBeClean = name.startsWith('clean');
+    const isClean = found === 0;
+    const correct = isClean === shouldBeClean;
+    allExpected &&= correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ${found} finding(s) ` +
+        `(expected ${shouldBeClean ? 'clean' : 'swallow'})`,
+    );
+  }
+  console.log(allExpected ? '\nAll selftest cases passed.' : '\nSelftest FAILED.');
+  process.exit(allExpected ? 0 : 1);
+}
+
+// --- CLI -------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+if (args[0] === '--selftest') {
+  selftest();
+} else if (args.length > 0) {
+  let clean = true;
+  for (const file of args) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf8');
+    } catch {
+      console.error(`✗ ${file}: cannot read file`);
+      clean = false;
+      continue;
+    }
+    clean = lintLabeled(file, src) && clean;
+  }
+  process.exit(clean ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(lintLabeled('stdin', buf) ? 0 : 1));
+}

package/catalog/skills/git-collaboration-workflows/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: git-collaboration-workflows
+description: Run git collaboration that scales — trunk-based vs git-flow decided by deploy cadence, branch protection and required checks, PR sizing and review etiquette, monorepo vs polyrepo trade-offs, release branches and hotfixes, and history hygiene with disciplined merges.
+type: skill
+version: 1.0.0
+updated: 2026-07-10
+---
+# Git Collaboration Workflows
+
+Git workflow debates are proxy wars over one variable: **how often you ship**. Choose the
+branching model from your deploy cadence, enforce it with branch protection instead of
+vigilance, and keep PRs small enough to review honestly. Deep detail in `references/`;
+protection settings and a PR-review playbook in `examples/`; `scripts/check-branch-hygiene.mjs`
+audits a repo's local hygiene.
+
+## Choosing the branching model
+
+| You deploy… | Model | Shape |
+|---|---|---|
+| Continuously (SaaS default) | **Trunk-based** | Short-lived branches (<2 days) → main; release = deploy main; flags hide unfinished work |
+| On a cadence (mobile, desktop) | Trunk + **release branches** | Cut `release/1.24` from main; only cherry-picked fixes land on it; tag ships |
+| Multiple supported majors (enterprise, on-prem) | Trunk + long-lived release lines | Fix on main first, cherry-pick back (never the reverse) |
+
+Full git-flow (develop + feature + release + hotfix branches) earns its complexity only in
+the third row — adopted by SaaS teams it mostly adds merge ceremony and delays integration.
+The deciding question is never taste; it's "what do we support in production simultaneously?"
+
+```text
+trunk-based:   main ──●──●──●──●──►            release = deploy latest green main
+cadence:       main ──●──●──●──►               release/1.24 ──●(cp)──tag 1.24.1
+hotfix:        branch from the SHIPPED TAG, fix, tag — then forward-port to main SAME DAY
+```
+
+Mechanics of each and the hotfix path: `references/branching-models.md`.
+
+## Short-lived branches or bust
+
+Integration pain grows superlinearly with branch age — two weeks of divergence is a merge
+project. Working rules:
+
+```text
+branch age    < 2 days   (rebase on main daily if longer is unavoidable)
+PR size       ≤ ~400 changed lines — review quality collapses beyond that
+one PR        one logical change (refactor ≠ behavior change ≠ formatting)
+big features  land dark in slices behind a flag (feature-flags-experimentation),
+              never in a long-lived feature branch
+```
+
+Stacked PRs (chain of small dependent PRs) are the escape hatch when a change is genuinely
+large: reviewable slices, one logical narrative — etiquette and mechanics in
+`examples/pr-review-playbook.md`.
+
+## Protection is policy-as-config
+
+Trust the settings, not the culture doc — `examples/branch-protection.md` has the full
+recommended set. The load-bearing ones: required status checks (build + tests + lint, the
+same gate for everyone including admins), required review (1 for most teams, 2 for
+money/security paths via CODEOWNERS), **stale-review dismissal** (a re-push invalidates old
+approvals), and linear history or squash-only merges so `main` reads as a changelog.
+Conventional commit messages (`conventional-commits`) make that changelog machine-readable.
+
+## Merge strategy: pick one, encode it
+
+- **Squash-merge** (default recommendation): PR = one commit on main; messy WIP commits
+  vanish; revert = one commit. Cost: intra-PR history lost — fine when PRs are small (rule
+  above).
+- **Rebase-merge**: preserves commit series linearly — only worth it if authors curate
+  commits (interactive rebase discipline); otherwise you're preserving noise.
+- **Merge commits**: keeps true topology; `main` becomes unreadable at scale. Reserve for
+  release-branch merges where the merge point *is* the information.
+- Never mix by whim — one strategy per repo, enforced in settings. And **never rewrite
+  pushed shared history**; `revert` forward instead (`references/history-hygiene.md` covers
+  recovery, bisect, and blame-friendly practices).
+
+## Monorepo vs polyrepo (an ownership decision)
+
+Monorepo buys atomic cross-cutting changes, one dependency graph, and universal refactors —
+at the price of tooling (selective CI via path filters/affected-graphs, CODEOWNERS, merge
+queues at scale). Polyrepo buys independent pace and clear boundaries — at the price of
+version-matrix coordination (`release-coordination` in `deployment-strategies`) and
+cross-repo changes becoming N-PR projects. Rule of thumb: one product surface + one deploy
+train → monorepo; genuinely independent products/teams → polyrepo. The failure mode is the
+*unmanaged* middle: 40 repos with hand-maintained version matrices and no contract tests.
+
+## Pitfalls
+
+- Long-lived feature branches "to keep main stable" — main stays stable via checks and
+  flags; the branch just batches risk into one giant merge.
+- `main` broken and normalized ("just skip that test") — a red main blocks everyone's
+  integration; fixing it outranks all feature work, and a merge queue prevents most of it.
+- Force-push to shared branches — reflog archaeology for the whole team; protect against it
+  in settings.
+- Review theater: 2,000-line PRs approved in 4 minutes — the size rule exists because
+  reviewers are human.
+- Cherry-picking main→release without fixing main first — the fix vanishes in the next
+  release cut.
+
+## Verification
+
+Run `node scripts/check-branch-hygiene.mjs` inside any repo: it reports stale branches,
+oversized undelivered work, and non-linear history segments. Then diff your repo settings
+against `examples/branch-protection.md`. Pairs with `conventional-commits`,
+`ci-pipeline-design`, `code-review` practices in `deployment-strategies`, and
+`feature-flags-experimentation`.

package/catalog/skills/git-collaboration-workflows/examples/branch-protection.md

@@ -0,0 +1,48 @@
+# Branch Protection — recommended settings
+
+GitHub terminology; GitLab/Bitbucket equivalents in parentheses. Apply to `main` and all
+`release/*` patterns.
+
+## Required (the load-bearing set)
+
+| Setting | Value | Why |
+|---|---|---|
+| Require a pull request before merging | on | No direct pushes, no exceptions |
+| Required approvals | 1 (2 via CODEOWNERS for `/payments`, `/auth`, `/infra`) | Match rigor to blast radius |
+| Dismiss stale approvals on new commits | **on** | Re-push invalidates what was reviewed |
+| Require review from Code Owners | on where CODEOWNERS exists | Routing, not gatekeeping |
+| Require status checks to pass | build, test, lint, typecheck | The same bar for everyone |
+| Require branches to be up to date / merge queue | merge queue when >10 merges/day | Kills "two green PRs, red main" |
+| Require linear history (or squash-only) | on | main reads as changelog; bisect stays fast |
+| Include administrators (no bypass) | **on** | The bypass you allow is the one used at the worst moment |
+| Allow force pushes / deletions | **off** | Non-negotiable on shared branches |
+
+## Recommended
+
+- **Require signed commits** on release branches (supply-chain posture; pairs with
+  provenance in `OPEN-CORE`-style distribution).
+- **Conversation resolution required** — threads don't vanish on merge.
+- Auto-delete head branches after merge — stale-branch hygiene by default.
+- `CODEOWNERS` kept small and real: teams, not individuals (vacation-proof); every entry
+  answers "who must know about changes here", not "who wrote it once".
+
+## The escape hatch, designed
+
+Emergencies happen; design the fast path so nobody disables protection:
+
+- A `hotfix` label + on-call approver satisfies the review requirement (a second human, fast).
+- Checks stay required — a hotfix that doesn't build isn't fast, it's twice.
+- Break-glass audit: any settings change to protection pages an owner (settings drift is
+  how "temporary" bypasses become permanent).
+
+## CODEOWNERS sketch
+
+```
+# Default: any senior reviewer team
+*                    @org/reviewers
+# Blast-radius paths: two approvals via team + specialist
+/services/payments/  @org/payments @org/security
+/auth/               @org/security
+/infra/              @org/platform
+/.github/            @org/platform   # CI is code; protect the protector
+```

package/catalog/skills/git-collaboration-workflows/examples/pr-review-playbook.md

@@ -0,0 +1,48 @@
+# PR & Review Playbook
+
+## Author side
+
+- **Size**: ≤ ~400 changed lines. Bigger? Split: mechanical prep PRs (rename, extract,
+  format — trivially approvable) first, the behavior change last and small.
+- **Stacked PRs** for large features: each PR one reviewable slice, description links the
+  stack ("2/5, builds on #341"). Land bottom-up; rebase the stack on each merge (tooling
+  helps; discipline suffices).
+- **Description contract**: what + why + how-verified (test evidence, screenshots for UI),
+  plus rollback note if non-trivial ("revert cleanly" or the flag to flip). A reviewer
+  should know the intent before reading the diff.
+- **Self-review first**: your own pass catches the debug prints and stray files; respect
+  reviewers' attention as the scarce resource it is.
+- Draft PRs early for direction checks ("is this approach sane?") — cheaper than polished
+  wrongness.
+
+## Reviewer side
+
+- **First response < 4 working hours; small PRs same-day.** Review latency sets integration
+  speed for the whole team — it IS the constraint, treat it like on-call.
+- Review for: correctness, tests actually asserting behavior, security on tainted paths,
+  and "will the next reader understand this" — not personal style (the linter owns style;
+  what the linter doesn't own isn't blocking).
+- **Prefix comments by weight**: `blocking:` (must fix), `q:` (genuine question),
+  `nit:` (author's call, never blocks). Unprefixed comments read as blocking — inflation
+  by default.
+- Approve with nits rather than round-tripping for trivia; re-request only when something
+  `blocking:` changed.
+- Big PR arrives anyway? First comment: "split suggestion", not 45 line-notes on code
+  that'll be rewritten.
+
+## Team mechanics
+
+- **Review SLO on the dashboard** (median time-to-first-review) — what's measured gets
+  staffed.
+- Rotate a daily "review goalie" who owns unblocking the queue before their own work.
+- Disagreements past two round-trips move to a 10-minute call; write the resolution back
+  into the PR (the thread is the record).
+- Merge is the author's job once approved (or auto-merge/queue) — approved-but-unmerged PRs
+  rot against main.
+
+## Anti-patterns, named
+
+LGTM-stamping (approval without evidence of reading — ask one substantive question per
+review as a personal rule) · drive-by rewrites in review comments (open your own follow-up
+PR) · review as status hierarchy (junior reviews senior code; fresh eyes are the point) ·
+the 47-comment style war (fix the linter config, apologize, move on).

package/catalog/skills/git-collaboration-workflows/references/branching-models.md

@@ -0,0 +1,52 @@
+# Branching Models in Detail
+
+## Trunk-based (continuous deploy)
+
+```
+main ──●──●──●──●──●──●──►  every merge deployable; deploy = promote latest green main
+        \feat-a (hours)
+         ●──● → PR → squash → main
+```
+
+- Unfinished work ships **dark** behind flags — integration happens daily even when release
+  doesn't.
+- A **merge queue** (GitHub merge queue / Bors-style) serializes merges and tests each
+  against the true post-merge state — eliminates "two green PRs, red main" races; adopt it
+  once merges/day > ~10.
+- Broken main = full stop: auto-revert the offending merge (bot or on-call) rather than
+  fix-forward under pressure; the author re-lands calmly.
+
+## Release-branch overlay (cadence shipping)
+
+```
+main ──●──●──●──●──●──●──►
+              \release/1.24 ──●(cp)──●(cp)──tag 1.24.0──tag 1.24.1
+```
+
+- Cut from main at code-freeze; the branch only receives **cherry-picks** of fixes that
+  landed on main first (main-first is the invariant that prevents regressions in 1.25).
+- Tag builds from the release branch; the tag, not the branch tip, is what shipped.
+- Delete the branch when the version leaves support; tags are permanent.
+
+## Hotfix path (works in both models)
+
+1. Branch from the **shipped tag** (not main — main has moved).
+2. Fix, PR, tag `1.24.2` from the hotfix branch, ship.
+3. **Forward-port to main immediately** — the #1 hotfix failure is the fix missing from the
+   next regular release. A required "forward-ported? link" field in the hotfix PR template
+   is cheap insurance.
+
+## Multi-major support (enterprise/on-prem)
+
+Long-lived `release/2.x`, `release/3.x` lines. Every fix: main first, then cherry-pick down
+each supported line it applies to (automate with a cherry-pick bot + per-line labels).
+Support-matrix discipline: each line has an EOL date published; EOL means the branch goes
+read-only. The cost of each supported line is roughly a part-time engineer — price support
+contracts accordingly.
+
+## Migration notes (git-flow → trunk-based)
+
+Teams rarely regret the direction; the sequence that works: (1) merge queue + required
+checks on main, (2) flags for the two in-flight epics, (3) shrink PR-size norms via review
+culture, (4) delete `develop` — it's by then a stale mirror. Do (4) last; deleting develop
+first just moves the long-lived-branch problem to feature branches.

package/catalog/skills/git-collaboration-workflows/references/history-hygiene.md

@@ -0,0 +1,44 @@
+# History Hygiene
+
+History is a debugging tool and an audit trail; hygiene is what keeps `bisect`, `blame`, and
+`revert` usable at 3 a.m.
+
+## The rules
+
+- **Never rewrite pushed shared history.** `push --force` on main/release erases teammates'
+  reference points and CI provenance. Personal branches: force-push freely *before* review
+  starts; after review begins, prefer `--force-with-lease` (refuses if someone else pushed)
+  and only to your own branch.
+- **Revert forward.** A bad merge on main gets `git revert -m 1 <merge>` (or revert of the
+  squash commit) — a new commit that undoes it. History stays true: the mistake happened,
+  the fix happened.
+- **Atomic commits with why-messages.** Each commit builds and tests green (keeps bisect
+  honest); message body explains *why*, the diff already shows *what*
+  (`conventional-commits` for the format).
+- Separate **mechanical churn from logic**: formatting/rename-only commits isolated (and
+  listed in `.git-blame-ignore-revs` so blame skips them — one config line saves years of
+  "blame says the formatter wrote everything").
+
+## Bisect discipline
+
+`git bisect run ./test.sh` finds the breaking commit in log₂(n) steps — but only if commits
+build independently (atomic rule above) and main is linear-ish (squash/rebase merges). A
+history of "wip", "fix", "fix2" turns bisect from minutes into an afternoon of manual
+skipping. This is the practical argument that wins the squash-merge debate.
+
+## Recovering from disasters
+
+- Deleted branch / botched rebase: `git reflog` — every HEAD position for ~90 days; branch
+  from the lost SHA. Nothing pushed is ever really lost within the window.
+- Committed secret: rotate the secret FIRST (history cleaning is not containment — clones
+  and CI logs exist), then scrub with `git filter-repo` and force-push with the whole
+  team coordinated. Treat as an incident (`secrets-management`), not a git trick.
+- Wrong-branch commit: `git cherry-pick` it where it belongs, `git reset --keep` where it
+  doesn't (before push) or revert (after).
+
+## Large repos / large files
+
+Binary assets and datasets: LFS from day one — retrofitting LFS after 2GB of PSDs are in
+history requires a full rewrite event. Generated artifacts never get committed (CI rebuilds
+them); a `check-branch-hygiene` finding of build outputs in git is a config bug in
+`.gitignore`, fix at the root.

package/catalog/skills/git-collaboration-workflows/scripts/check-branch-hygiene.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Repo hygiene audit: stale branches, oversized in-flight work, non-linear
+// history, and tracked build artifacts. Read-only. Run inside any git repo:
+//   node scripts/check-branch-hygiene.mjs [repo-path]
+import { execFileSync } from 'node:child_process';
+
+const repo = process.argv[2] ?? process.cwd();
+const git = (...args) => {
+  try { return execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' }).trim(); }
+  catch { return ''; }
+};
+
+if (!git('rev-parse', '--is-inside-work-tree')) {
+  console.error(`Not a git repo: ${repo}`);
+  process.exit(1);
+}
+
+const findings = [];
+const DAY = 86_400_000;
+const main = git('symbolic-ref', 'refs/remotes/origin/HEAD').split('/').pop() ||
+             (git('rev-parse', '--verify', 'main') ? 'main' : 'master');
+
+// 1. Stale local branches (> 14 days since last commit, not merged into main)
+const branches = git('for-each-ref', 'refs/heads', '--format=%(refname:short)|%(committerdate:iso8601)')
+  .split('\n').filter(Boolean).map((l) => { const [name, date] = l.split('|'); return { name, date: new Date(date) }; });
+for (const b of branches) {
+  if (b.name === main) continue;
+  const ageDays = Math.floor((Date.now() - b.date) / DAY);
+  const merged = git('branch', '--merged', main).includes(b.name);
+  if (merged && b.name !== main) findings.push(`merged-but-undeleted branch: ${b.name} — delete it`);
+  else if (ageDays > 14) findings.push(`stale branch: ${b.name} (${ageDays}d old) — rebase & land in slices, or delete`);
+  else if (ageDays > 2) findings.push(`aging branch: ${b.name} (${ageDays}d) — branch-age rule is <2 days`);
+}
+
+// 2. Oversized undelivered work on current branch vs main
+const current = git('rev-parse', '--abbrev-ref', 'HEAD');
+if (current && current !== main) {
+  const stat = git('diff', '--shortstat', `${main}...HEAD`);
+  const changed = [...stat.matchAll(/(\d+) (insertion|deletion)/g)].reduce((s, m) => s + Number(m[1]), 0);
+  if (changed > 400) findings.push(`current branch carries ${changed} changed lines vs ${main} — split (≤400/PR)`);
+}
+
+// 3. Non-linear history in recent main (merge commits other than PR merges pattern)
+const merges = git('log', main, '--merges', '--oneline', '-n', '200').split('\n').filter(Boolean);
+if (merges.length > 50) findings.push(`${merges.length}/200 recent ${main} commits are merge commits — consider squash/linear policy`);
+
+// 4. Tracked files that look like build artifacts or secrets-adjacent
+const tracked = git('ls-files').split('\n');
+const artifactRe = /^(dist|build|out|node_modules)\/|\.(log|tmp)$/;
+const secretRe = /(^|\/)\.env(\.|$)|id_rsa|\.pem$/;
+const artifacts = tracked.filter((f) => artifactRe.test(f)).slice(0, 5);
+const secretish = tracked.filter((f) => secretRe.test(f) && !f.endsWith('.example')).slice(0, 5);
+if (artifacts.length) findings.push(`build artifacts tracked: ${artifacts.join(', ')} — .gitignore + git rm --cached`);
+if (secretish.length) findings.push(`SECRET-SHAPED tracked files: ${secretish.join(', ')} — rotate + scrub (see history-hygiene.md)`);
+
+// Report
+if (findings.length === 0) {
+  console.log(`Hygiene clean: ${branches.length} branches, ${main} linear-enough, no artifacts tracked.`);
+} else {
+  console.log(`Hygiene findings (${findings.length}):\n` + findings.map((f) => `  - ${f}`).join('\n'));
+}
+process.exit(secretish.length ? 1 : 0); // only secret-shaped files fail the check hard

package/catalog/skills/owasp-top10/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: owasp-top10
+description: A deep prevention reference for the OWASP Top 10 web risks — broken access control, injection, crypto failures, insecure design, SSRF and more — with vulnerable-vs-fixed code, edge cases, and a runnable naive-vulnerability scanner.
+type: skill
+version: 2.0.0
+updated: 2026-06-28
+---
+# OWASP Top 10 Prevention
+
+Most real-world breaches exploit a short, well-known list of weaknesses. This package is the deep
+reference: each category gets its root cause, the default defense, and a vulnerable-vs-fixed example.
+Category deep-dives live in `references/`, side-by-side fixes in `examples/`, and a runnable heuristic
+scanner in `scripts/`.
+
+> Based on the OWASP Top 10 (2021). The list shifts over time, but the underlying defenses are durable.
+
+## The list (and the one-line defense for each)
+
+| # | Category | Default defense |
+|---|---|---|
+| A01 | **Broken Access Control** | Enforce authorization server-side on every action; deny by default; check ownership (stop IDOR). |
+| A02 | **Cryptographic Failures** | TLS in transit; encrypt sensitive data at rest; hash passwords with argon2/bcrypt; never roll your own crypto. |
+| A03 | **Injection** (SQL/cmd/XSS) | Parameterize queries; context-aware output encoding; never concatenate untrusted input. |
+| A04 | **Insecure Design** | Threat-model before building; secure-by-design defaults; abuse-case thinking. |
+| A05 | **Security Misconfiguration** | Harden defaults; disable debug in prod; least-privilege; remove unused features. |
+| A06 | **Vulnerable Components** | Inventory dependencies; patch on a schedule; scan for CVEs (see `vuln-scanner` agent). |
+| A07 | **Auth Failures** | Strong session handling, MFA, rate-limit logins, no credential stuffing surface (see `secure-auth`). |
+| A08 | **Software & Data Integrity** | Verify signatures; secure CI/CD; don't deserialize untrusted data. |
+| A09 | **Logging & Monitoring Failures** | Log security events, alert on them, don't log secrets (see `audit-logging`). |
+| A10 | **SSRF** | Allow-list outbound destinations; validate/resolve URLs; block internal ranges. |
+
+## The two that cause the most damage
+
+### A01 — Broken Access Control (the #1 risk)
+The bug: the server checks *authentication* (who you are) but not *authorization* (whether you may do
+this specific thing). Classic IDOR — changing an ID in the URL to read someone else's data.
+
+```js
+// VULNERABLE: any logged-in user can read any invoice by guessing an id
+app.get('/invoices/:id', auth, async (req, res) => {
+  const invoice = await db.getInvoice(req.params.id);
+  res.json(invoice);
+});
+
+// FIXED: authorize against ownership, deny by default
+app.get('/invoices/:id', auth, async (req, res) => {
+  const invoice = await db.getInvoice(req.params.id);
+  if (!invoice || invoice.ownerId !== req.user.id) return res.status(404).end(); // 404 hides existence
+  res.json(invoice);
+});
+```
+Deep-dive: `references/access-control.md`.
+
+### A03 — Injection
+The bug: untrusted input is interpreted as code/query/markup. Defense is structural separation of code
+from data.
+
+```js
+// VULNERABLE: SQL injection
+db.query(`SELECT * FROM users WHERE email = '${input}'`);
+
+// FIXED: parameterized query — driver treats input strictly as data
+db.query('SELECT * FROM users WHERE email = $1', [input]);
+```
+SQL, command, and XSS variants with fixes: `references/injection.md` and `examples/sql-injection-fix.md`,
+`examples/xss-fix.md`.
+
+## A worked SSRF case (A10)
+
+```js
+// VULNERABLE: fetches any URL the user supplies -> attacker hits internal metadata service
+const data = await fetch(req.query.url);
+
+// FIXED: allow-list hosts and block internal ranges
+const url = new URL(req.query.url);
+if (!ALLOWED_HOSTS.has(url.hostname)) return res.status(400).json({ error: 'host not allowed' });
+// ...plus resolve DNS and reject private IP ranges (169.254/16, 10/8, 127/8) to stop rebinding
+```
+Detail and the private-range checks: `references/ssrf-and-design.md`.
+
+## Edge cases & gotchas
+
+- **Blocklists fail; allow-lists work.** Trying to block "bad" input (e.g. stripping `<script>`) is
+  whack-a-mole — encode for the output context instead, and allow-list what's permitted.
+- **404 vs 403 to avoid existence leakage.** For unauthorized access to a resource whose very existence
+  is sensitive, return `404`, not `403`, so attackers can't enumerate.
+- **Mass assignment.** Binding request bodies straight to models lets attackers set fields like
+  `isAdmin`. Allow-list bindable fields.
+- **Second-order injection.** Stored input that's safe on the way in can be unsafe when later used in a
+  different context (e.g. a stored value concatenated into a query). Defend at every sink.
+- **Defense in depth.** No single control is enough — combine input validation, parameterization,
+  output encoding, authz checks, and monitoring.
+
+## When the "fix" isn't enough
+
+Input sanitization alone is not a substitute for parameterization/encoding — it's a fragile add-on.
+And security review (this skill + the `security-auditor` agent) catches code-level bugs, but design-level
+flaws (A04) need **threat modeling up front** (see the `threat-modeler` agent) — you can't audit your
+way out of an insecure design.
+
+## Files in this package
+
+- `references/access-control.md` — A01 in depth: authz patterns, IDOR, mass assignment
+- `references/injection.md` — A03: SQL/command/XSS with defenses per context
+- `references/crypto-failures.md` — A02: hashing, encryption, key handling
+- `references/ssrf-and-design.md` — A10 + A04: SSRF defense and secure design
+- `examples/sql-injection-fix.md` — vulnerable vs parameterized, with edge cases
+- `examples/xss-fix.md` — output encoding and safe rendering
+- `scripts/scan-injection.mjs` — runnable heuristic scanner for naive injection patterns (selftest passes)
+
+Pairs with the `security-auditor` agent, the `threat-modeler` agent, and the `secure-auth` and
+`secrets-management` skills.

package/catalog/skills/owasp-top10/examples/sql-injection-fix.md

@@ -0,0 +1,33 @@
+# Example: SQL Injection — Vulnerable vs Fixed
+
+## Vulnerable
+```js
+// User-controlled `email` concatenated directly into SQL
+app.post('/login', (req, res) => {
+  const { email, password } = req.body;
+  const row = db.query(
+    `SELECT * FROM users WHERE email = '${email}' AND password = '${password}'`
+  );
+  // input  email = "' OR '1'='1' --"  ->  returns the first user, bypassing auth
+});
+```
+
+## Fixed
+```js
+app.post('/login', async (req, res) => {
+  const { email, password } = req.body;
+  const row = await db.query(
+    'SELECT id, password_hash FROM users WHERE email = $1',
+    [email]                        // bound parameter — treated strictly as data
+  );
+  if (!row || !(await argon2.verify(row.password_hash, password))) {
+    return res.status(401).json({ error: { code: 'unauthorized', message: 'Invalid credentials' } });
+  }
+});
+```
+
+## What changed & edge cases
+- **Parameterized query** — the driver sends the SQL and the data separately, so injected SQL can't execute.
+- **No password in SQL** — verify a hash, never compare plaintext passwords in the query.
+- **Generic error** — don't reveal whether the email or the password was wrong (avoids user enumeration).
+- **Second-order:** even values you stored earlier must be parameterized when reused in a query.

package/catalog/skills/owasp-top10/examples/xss-fix.md

@@ -0,0 +1,27 @@
+# Example: XSS — Vulnerable vs Fixed
+
+## Vulnerable (DOM XSS)
+```js
+// Renders untrusted comment as HTML -> <img src=x onerror=stealCookies()> executes
+commentEl.innerHTML = comment.text;
+```
+
+## Fixed
+```js
+// Assign as text — the browser never parses it as HTML
+commentEl.textContent = comment.text;
+```
+
+## Fixed (when you must render rich HTML)
+```js
+import DOMPurify from 'dompurify';
+commentEl.innerHTML = DOMPurify.sanitize(comment.html); // vetted sanitizer, allow-list of tags
+```
+
+## Framework note & edge cases
+- React/Vue auto-escape by default — the risk is the escape hatch (`dangerouslySetInnerHTML`, `v-html`).
+- **Encode for the context:** HTML body vs attribute vs URL vs inline JS each need different encoding.
+  `textContent` handles the body case; a value placed into an `href` needs URL validation
+  (`javascript:` URLs are an XSS vector).
+- **Don't regex-strip tags** — it's bypassable. Use a maintained sanitizer or encode for output.
+- Pair with a **Content-Security-Policy** as defense-in-depth so injected scripts won't run.