@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/differential-security-review/references/methodology.md

@@ -1,145 +1,145 @@
-# Differential review methodology (phases 0 to 4)
-
-Read at the start of every differential security review. `<base>` is the base branch named in the task (for example `origin/main`); `<repo>` is the repository folder. Never check out another commit in the repository under review.
-
-## Before phase 0: baseline context
-
-Understand what the code was supposed to do before the change. From the base version (`git -C <repo> show <base>:<path>`, or a detached worktree in a temp directory outside the repository), capture:
-
-- System-wide invariants: what must always be true (a user only sees their own account's data; a balance never goes negative).
-- Trust boundaries and privilege levels: who can do what, and where that is enforced.
-- Validation patterns: what gets checked where, and which checks are layered as defense in depth.
-- Call graphs for the critical functions the change touches.
-- How state changes flow (status transitions, money movement).
-- External dependencies and the assumptions made about them.
-
-This lets you spot when the change violates an invariant, breaks a layer of defense, or deviates from a system-wide pattern.
-
-## Phase 0: intake and triage
-
-```bash
-git -C <repo> log --oneline <base>..HEAD
-git -C <repo> diff --stat <base>...HEAD
-git -C <repo> diff --name-only <base>...HEAD
-```
-
-Assess codebase size (count source files of the main languages, for example `git -C <repo> ls-files '*.ts' '*.py' '*.go' | wc -l`) and pick the strategy:
-
-- Small (under 20 files): deep analysis, read all dependencies.
-- Medium (20 to 200): focused analysis, one hop of dependencies.
-- Large (over 200): surgical, critical paths only.
-
-Give every changed file a risk level:
-
-- HIGH: auth, crypto, external calls, value transfer, validation removal, permission changes.
-- MEDIUM: business logic, state changes, new public APIs.
-- LOW: comments, tests, UI text, logging.
-
-## Phase 1: changed code analysis
-
-For each changed file, highest risk first:
-
-1. **Read both versions**, base and head.
-2. **Analyse each diff region:**
-   ```
-   BEFORE: <exact code>
-   AFTER: <exact code>
-   CHANGE: <behavioural impact>
-   SECURITY: <implications>
-   ```
-3. **Check the history of removed code.** When was it added, and why?
-   ```bash
-   git -C <repo> log -S "<removed code>" --oneline <base>
-   git -C <repo> blame <base> -- <file>
-   git -C <repo> show <commit>
-   ```
-   Red flags: removed code that came from a "fix", "security", "CVE" or "vulnerability" commit is CRITICAL until explained. Code added recently (under a month) and now removed is HIGH.
-4. **Check for regressions** (code being re-added):
-   ```bash
-   git -C <repo> log -S "<added code>" -p <base>
-   ```
-   Pattern: added, removed for security, re-added now means a regression.
-5. **Micro-adversarial questions** for each change:
-   - What attack did the removed code prevent?
-   - What new surface does the new code expose?
-   - Can the modified logic be bypassed?
-   - Are checks weaker? Are edge cases still covered?
-6. **Write concrete attack scenarios** for anything suspicious:
-   ```
-   SCENARIO: <attack goal>
-   PRECONDITIONS: <required state>
-   STEPS:
-     1. <specific action>
-     2. <expected outcome>
-     3. <exploitation>
-   WHY IT WORKS: <reference to the code change, file:line>
-   IMPACT: <severity and scope>
-   ```
-
-## Phase 2: test coverage of changed code
-
-```bash
-git -C <repo> diff --name-only <base>...HEAD | grep -v -i test
-git -C <repo> diff --name-only <base>...HEAD | grep -i test
-git -C <repo> grep -n "<functionName>" -- '*test*' '*spec*'
-```
-
-Adapt the test file patterns to the project's layout. Risk elevation rules:
-
-- New function and no tests: raise MEDIUM to HIGH.
-- Modified validation and unchanged tests: HIGH.
-- Complex logic (over 20 lines) and no tests: HIGH.
-
-## Phase 3: blast radius
-
-Count the callers of each modified function:
-
-```bash
-git -C <repo> grep -n "<functionName>(" | wc -l
-```
-
-Also check dynamic references (route tables, dependency injection, string-based lookups) where the language uses them.
-
-| Callers | Blast radius |
-|---|---|
-| 1 to 5 | LOW |
-| 6 to 20 | MEDIUM |
-| 21 to 50 | HIGH |
-| over 50 | CRITICAL |
-
-Priority matrix:
-
-| Change risk | Blast radius | Priority | Depth |
-|---|---|---|---|
-| HIGH | CRITICAL | P0 | Deep, all dependencies |
-| HIGH | HIGH or MEDIUM | P1 | Deep |
-| HIGH | LOW | P2 | Standard |
-| MEDIUM | CRITICAL or HIGH | P1 | Standard plus callers |
-
-## Phase 4: deep context for HIGH risk changes
-
-For each HIGH risk changed function, using Read, Grep and code tracing:
-
-1. **Map the function flow:** entry conditions (guards, middleware, decorators), state read, state written, external calls, return values and side effects.
-2. **Trace internal calls:** list every function called and map their flows in turn.
-3. **Trace external calls:** which trust boundaries are crossed, what is assumed about the other side's behaviour, whether a callback or re-entry is possible.
-4. **Identify invariants:** what must always be true, what must never happen, and whether the change keeps them.
-5. **Five whys:**
-   - Why was this code changed?
-   - Why did the original code exist?
-   - Why might this break?
-   - Why was this approach chosen?
-   - Why could this fail in production?
-
-**Cross-cutting patterns:** find the validation and permission patterns repeated across the codebase and check whether the diff removed any instance:
-
-```bash
-git -C <repo> grep -n "<repeated guard, e.g. requireRole(>"
-git -C <repo> diff <base>...HEAD | grep "^-.*<repeated guard>"
-```
-
-Flag a removal that breaks defense in depth.
-
-Next: for HIGH risk changes, continue with [adversarial.md](adversarial.md).
-
-Part of the `differential-security-review` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/differential-review (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: no checkouts, no external skills, commands made language-neutral and scoped to the repository folder.
+# Differential review methodology (phases 0 to 4)
+
+Read at the start of every differential security review. `<base>` is the base branch named in the task (for example `origin/main`); `<repo>` is the repository folder. Never check out another commit in the repository under review.
+
+## Before phase 0: baseline context
+
+Understand what the code was supposed to do before the change. From the base version (`git -C <repo> show <base>:<path>`, or a detached worktree in a temp directory outside the repository), capture:
+
+- System-wide invariants: what must always be true (a user only sees their own account's data; a balance never goes negative).
+- Trust boundaries and privilege levels: who can do what, and where that is enforced.
+- Validation patterns: what gets checked where, and which checks are layered as defense in depth.
+- Call graphs for the critical functions the change touches.
+- How state changes flow (status transitions, money movement).
+- External dependencies and the assumptions made about them.
+
+This lets you spot when the change violates an invariant, breaks a layer of defense, or deviates from a system-wide pattern.
+
+## Phase 0: intake and triage
+
+```bash
+git -C <repo> log --oneline <base>..HEAD
+git -C <repo> diff --stat <base>...HEAD
+git -C <repo> diff --name-only <base>...HEAD
+```
+
+Assess codebase size (count source files of the main languages, for example `git -C <repo> ls-files '*.ts' '*.py' '*.go' | wc -l`) and pick the strategy:
+
+- Small (under 20 files): deep analysis, read all dependencies.
+- Medium (20 to 200): focused analysis, one hop of dependencies.
+- Large (over 200): surgical, critical paths only.
+
+Give every changed file a risk level:
+
+- HIGH: auth, crypto, external calls, value transfer, validation removal, permission changes.
+- MEDIUM: business logic, state changes, new public APIs.
+- LOW: comments, tests, UI text, logging.
+
+## Phase 1: changed code analysis
+
+For each changed file, highest risk first:
+
+1. **Read both versions**, base and head.
+2. **Analyse each diff region:**
+   ```
+   BEFORE: <exact code>
+   AFTER: <exact code>
+   CHANGE: <behavioural impact>
+   SECURITY: <implications>
+   ```
+3. **Check the history of removed code.** When was it added, and why?
+   ```bash
+   git -C <repo> log -S "<removed code>" --oneline <base>
+   git -C <repo> blame <base> -- <file>
+   git -C <repo> show <commit>
+   ```
+   Red flags: removed code that came from a "fix", "security", "CVE" or "vulnerability" commit is CRITICAL until explained. Code added recently (under a month) and now removed is HIGH.
+4. **Check for regressions** (code being re-added):
+   ```bash
+   git -C <repo> log -S "<added code>" -p <base>
+   ```
+   Pattern: added, removed for security, re-added now means a regression.
+5. **Micro-adversarial questions** for each change:
+   - What attack did the removed code prevent?
+   - What new surface does the new code expose?
+   - Can the modified logic be bypassed?
+   - Are checks weaker? Are edge cases still covered?
+6. **Write concrete attack scenarios** for anything suspicious:
+   ```
+   SCENARIO: <attack goal>
+   PRECONDITIONS: <required state>
+   STEPS:
+     1. <specific action>
+     2. <expected outcome>
+     3. <exploitation>
+   WHY IT WORKS: <reference to the code change, file:line>
+   IMPACT: <severity and scope>
+   ```
+
+## Phase 2: test coverage of changed code
+
+```bash
+git -C <repo> diff --name-only <base>...HEAD | grep -v -i test
+git -C <repo> diff --name-only <base>...HEAD | grep -i test
+git -C <repo> grep -n "<functionName>" -- '*test*' '*spec*'
+```
+
+Adapt the test file patterns to the project's layout. Risk elevation rules:
+
+- New function and no tests: raise MEDIUM to HIGH.
+- Modified validation and unchanged tests: HIGH.
+- Complex logic (over 20 lines) and no tests: HIGH.
+
+## Phase 3: blast radius
+
+Count the callers of each modified function:
+
+```bash
+git -C <repo> grep -n "<functionName>(" | wc -l
+```
+
+Also check dynamic references (route tables, dependency injection, string-based lookups) where the language uses them.
+
+| Callers | Blast radius |
+|---|---|
+| 1 to 5 | LOW |
+| 6 to 20 | MEDIUM |
+| 21 to 50 | HIGH |
+| over 50 | CRITICAL |
+
+Priority matrix:
+
+| Change risk | Blast radius | Priority | Depth |
+|---|---|---|---|
+| HIGH | CRITICAL | P0 | Deep, all dependencies |
+| HIGH | HIGH or MEDIUM | P1 | Deep |
+| HIGH | LOW | P2 | Standard |
+| MEDIUM | CRITICAL or HIGH | P1 | Standard plus callers |
+
+## Phase 4: deep context for HIGH risk changes
+
+For each HIGH risk changed function, using Read, Grep and code tracing:
+
+1. **Map the function flow:** entry conditions (guards, middleware, decorators), state read, state written, external calls, return values and side effects.
+2. **Trace internal calls:** list every function called and map their flows in turn.
+3. **Trace external calls:** which trust boundaries are crossed, what is assumed about the other side's behaviour, whether a callback or re-entry is possible.
+4. **Identify invariants:** what must always be true, what must never happen, and whether the change keeps them.
+5. **Five whys:**
+   - Why was this code changed?
+   - Why did the original code exist?
+   - Why might this break?
+   - Why was this approach chosen?
+   - Why could this fail in production?
+
+**Cross-cutting patterns:** find the validation and permission patterns repeated across the codebase and check whether the diff removed any instance:
+
+```bash
+git -C <repo> grep -n "<repeated guard, e.g. requireRole(>"
+git -C <repo> diff <base>...HEAD | grep "^-.*<repeated guard>"
+```
+
+Flag a removal that breaks defense in depth.
+
+Next: for HIGH risk changes, continue with [adversarial.md](adversarial.md).
+
+Part of the `differential-security-review` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/differential-review (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: no checkouts, no external skills, commands made language-neutral and scoped to the repository folder.

package/library/skills/differential-security-review/references/patterns.md

@@ -1,108 +1,108 @@
-# Common vulnerability patterns in diffs
-
-Read during phase 1. Quick reference for detecting security problems in a change. Each `git diff` command assumes `git -C <repo> diff <base>...HEAD`, shortened below to `git diff <range>`.
-
-## Security regressions
-
-**Pattern:** code previously removed for security reasons is added again.
-
-```bash
-git log -S "<pattern>" --oneline -i --grep="security\|fix\|cve\|vuln" <base>
-```
-
-Red flags: the earlier commit message mentions security, fix, CVE or vulnerability; the removal was recent (under six months); the current change gives no reason for re-adding it.
-
-## Missing validation
-
-**Pattern:** a check, guard, assertion or schema rule removed without a replacement.
-
-```bash
-git diff <range> | grep -E "^-.*(throw|assert|require|validate|schema|guard|check|return .*40[0-4])"
-```
-
-Ask: was the validation moved elsewhere? Is it truly redundant? Does the removal expose something?
-
-```diff
- async function withdraw(userId, amount) {
--  if (amount <= 0) throw new BadRequest('amount must be positive')
--  if (amount > await balanceOf(userId)) throw new BadRequest('insufficient funds')
-   await ledger.debit(userId, amount)
- }
-```
-
-Risk: negative withdrawals credit the account; overdrafts are possible.
-
-## Access control bypass
-
-**Pattern:** a permission check removed or relaxed, or a route moved out of a protected group.
-
-```bash
-git diff <range> | grep -E "^-.*(auth|guard|policy|permission|role|can[A-Z]|isAdmin|owner|tenant|accountId)"
-```
-
-Ask: who can call this now? What is the new trust model? Was the check moved to the caller, and do all callers have it?
-
-```diff
-- router.post('/settings', requireRole('admin'), updateSettings)
-+ router.post('/settings', updateSettings)
-```
-
-Risk: any user can change global settings.
-
-## Double accounting
-
-**Pattern:** the same balance, stock or counter is changed twice for one logical event, often in two functions that each assume the other did not.
-
-```js
-// request a refund
-balance[user] += amount   // first credit
-// later, when the provider confirms
-balance[user] += amount   // second credit: bug
-```
-
-Impact: users are credited twice; the books do not balance.
-
-## Races and check-then-act
-
-**Pattern:** a value is checked and then used in separate steps without a transaction, lock or unique constraint: coupon redemption, stock reservation, "only one active subscription", balance checks.
-
-Ask: what happens when two requests arrive at the same moment? Is there a database constraint that makes the second one fail?
-
-## Unchecked results of external calls
-
-**Pattern:** the response of a payment provider, storage service, email API or child process is not checked, so a failure is treated as success.
-
-```bash
-git diff <range> | grep -E "^\+.*(fetch\(|axios|request\(|\.send\(|\.charge\(|\.upload\(|exec\()"
-```
-
-Risk: silent failures leave state inconsistent (order marked paid, charge failed).
-
-## New external calls and outbound URLs
-
-**Pattern:** the change adds calls to other services or fetches URLs. Check where the URL and the data come from (SSRF), whether TLS verification stays on, and whether the response is validated before use.
-
-## Denial of service
-
-**Pattern:** loops or queries over user-controlled sizes, unbounded batch endpoints, work that one request can multiply. Report as a note unless the task is about it; it does not block on its own.
-
-## Smart contracts
-
-If the repository is a smart-contract project, also check: external calls made before state updates (re-entrancy), arithmetic in `unchecked` blocks or old compiler versions (overflow), security logic depending on block timestamps, two-step approvals open to front-running, and return values of token transfers that are ignored.
-
-## Quick detection commands
-
-```bash
-# removed checks
-git diff <range> | grep "^-" | grep -E "throw|assert|require|validate|guard|policy"
-# added external calls
-git diff <range> | grep "^+" | grep -E "fetch\(|axios|http\.|request\(|exec\(|spawn\("
-# changed visibility or exposure
-git diff <range> | grep -E "export |public |private |internal |router\.|app\.(get|post|put|delete)"
-# raw queries and raw HTML
-git diff <range> | grep "^+" | grep -E "raw|Unsafe|innerHTML|v-html|dangerouslySetInnerHTML"
-```
-
-Next: methodology in [methodology.md](methodology.md), exploit scenarios in [adversarial.md](adversarial.md).
-
-Part of the `differential-security-review` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/differential-review (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: examples and detection commands rewritten for web stacks, smart-contract patterns condensed into one section, added races, double accounting and outbound-call patterns for web applications.
+# Common vulnerability patterns in diffs
+
+Read during phase 1. Quick reference for detecting security problems in a change. Each `git diff` command assumes `git -C <repo> diff <base>...HEAD`, shortened below to `git diff <range>`.
+
+## Security regressions
+
+**Pattern:** code previously removed for security reasons is added again.
+
+```bash
+git log -S "<pattern>" --oneline -i --grep="security\|fix\|cve\|vuln" <base>
+```
+
+Red flags: the earlier commit message mentions security, fix, CVE or vulnerability; the removal was recent (under six months); the current change gives no reason for re-adding it.
+
+## Missing validation
+
+**Pattern:** a check, guard, assertion or schema rule removed without a replacement.
+
+```bash
+git diff <range> | grep -E "^-.*(throw|assert|require|validate|schema|guard|check|return .*40[0-4])"
+```
+
+Ask: was the validation moved elsewhere? Is it truly redundant? Does the removal expose something?
+
+```diff
+ async function withdraw(userId, amount) {
+-  if (amount <= 0) throw new BadRequest('amount must be positive')
+-  if (amount > await balanceOf(userId)) throw new BadRequest('insufficient funds')
+   await ledger.debit(userId, amount)
+ }
+```
+
+Risk: negative withdrawals credit the account; overdrafts are possible.
+
+## Access control bypass
+
+**Pattern:** a permission check removed or relaxed, or a route moved out of a protected group.
+
+```bash
+git diff <range> | grep -E "^-.*(auth|guard|policy|permission|role|can[A-Z]|isAdmin|owner|tenant|accountId)"
+```
+
+Ask: who can call this now? What is the new trust model? Was the check moved to the caller, and do all callers have it?
+
+```diff
+- router.post('/settings', requireRole('admin'), updateSettings)
++ router.post('/settings', updateSettings)
+```
+
+Risk: any user can change global settings.
+
+## Double accounting
+
+**Pattern:** the same balance, stock or counter is changed twice for one logical event, often in two functions that each assume the other did not.
+
+```js
+// request a refund
+balance[user] += amount   // first credit
+// later, when the provider confirms
+balance[user] += amount   // second credit: bug
+```
+
+Impact: users are credited twice; the books do not balance.
+
+## Races and check-then-act
+
+**Pattern:** a value is checked and then used in separate steps without a transaction, lock or unique constraint: coupon redemption, stock reservation, "only one active subscription", balance checks.
+
+Ask: what happens when two requests arrive at the same moment? Is there a database constraint that makes the second one fail?
+
+## Unchecked results of external calls
+
+**Pattern:** the response of a payment provider, storage service, email API or child process is not checked, so a failure is treated as success.
+
+```bash
+git diff <range> | grep -E "^\+.*(fetch\(|axios|request\(|\.send\(|\.charge\(|\.upload\(|exec\()"
+```
+
+Risk: silent failures leave state inconsistent (order marked paid, charge failed).
+
+## New external calls and outbound URLs
+
+**Pattern:** the change adds calls to other services or fetches URLs. Check where the URL and the data come from (SSRF), whether TLS verification stays on, and whether the response is validated before use.
+
+## Denial of service
+
+**Pattern:** loops or queries over user-controlled sizes, unbounded batch endpoints, work that one request can multiply. Report as a note unless the task is about it; it does not block on its own.
+
+## Smart contracts
+
+If the repository is a smart-contract project, also check: external calls made before state updates (re-entrancy), arithmetic in `unchecked` blocks or old compiler versions (overflow), security logic depending on block timestamps, two-step approvals open to front-running, and return values of token transfers that are ignored.
+
+## Quick detection commands
+
+```bash
+# removed checks
+git diff <range> | grep "^-" | grep -E "throw|assert|require|validate|guard|policy"
+# added external calls
+git diff <range> | grep "^+" | grep -E "fetch\(|axios|http\.|request\(|exec\(|spawn\("
+# changed visibility or exposure
+git diff <range> | grep -E "export |public |private |internal |router\.|app\.(get|post|put|delete)"
+# raw queries and raw HTML
+git diff <range> | grep "^+" | grep -E "raw|Unsafe|innerHTML|v-html|dangerouslySetInnerHTML"
+```
+
+Next: methodology in [methodology.md](methodology.md), exploit scenarios in [adversarial.md](adversarial.md).
+
+Part of the `differential-security-review` skill, adapted from https://github.com/trailofbits/skills/tree/main/plugins/differential-review (commit 5c99c03fb8a9ea568432ecbcba5d86e9f4ac2bf0), CC BY-SA 4.0. Changed: examples and detection commands rewritten for web stacks, smart-contract patterns condensed into one section, added races, double accounting and outbound-call patterns for web applications.