@tamsensedev/runner 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,115 @@
+# Adversarial analysis (phase 5)
+
+Read after phase 4 for every HIGH risk change. The rule: concrete impact only, never "could cause issues". Every finding names the data exposed, the privilege gained, the money at risk or the invariant broken.
+
+Everything here is analysis on paper and reading code. Do not send requests to live services, and do not write files into the repository under review.
+
+## 1. Define a specific attacker model
+
+**Who is the attacker?**
+- Unauthenticated visitor
+- Authenticated regular user
+- User of another tenant or organisation
+- Malicious or compromised administrator
+- Compromised upstream service, webhook sender or dependency
+
+**What access do they have?**
+- Public API only
+- An authenticated role
+- Specific permissions or tokens
+- Ability to send webhooks, queue messages or files
+
+**Where do they interact with the system?**
+- Specific HTTP endpoints, pages or forms
+- RPC, GraphQL or WebSocket interfaces
+- Jobs triggered by their input
+- External APIs the system calls on their behalf
+
+## 2. Identify concrete attack vectors
+
+```
+ENTRY POINT: <exact endpoint or function the attacker can reach>
+
+ATTACK SEQUENCE:
+1. <specific request with parameters>
+2. <how it reaches the vulnerable code, file:line>
+3. <what happens in the vulnerable code>
+4. <impact achieved>
+
+PROOF OF ACCESSIBILITY:
+- The entry point is exposed (route registered, no guard in front)
+- The attacker has the required permissions
+- The path exists through real interfaces, not only internal calls
+```
+
+## 3. Rate realistic exploitability
+
+**EASY:** through public or ordinary user APIs, no special privileges, a single request, no special conditions.
+
+**MEDIUM:** needs specific conditions or elevated but obtainable privileges: several steps, timing, a particular system state.
+
+**HARD:** needs admin privileges, rare conditions or significant resources.
+
+## 4. Build the complete exploit scenario
+
+```
+ATTACKER STARTING POSITION:
+<what the attacker has at the beginning>
+
+STEP-BY-STEP EXPLOITATION:
+Step 1: <concrete action through an accessible interface>
+  - Request: <exact call>
+  - Parameters: <specific values>
+  - Result: <what happens>
+Step 2: <next action>
+  - Why this works: <reference to the code change>
+  - State change: <what changed>
+Step 3: <final impact>
+  - Result: <concrete harm>
+  - Evidence: <how to verify it from the code or a test>
+
+CONCRETE IMPACT:
+<specific and measurable: which records exposed, which privilege gained, how much money>
+```
+
+## 5. Cross-reference with the baseline
+
+From the baseline context in [methodology.md](methodology.md):
+
+- Does this violate a system-wide invariant?
+- Does it break a trust boundary?
+- Does it bypass a validation pattern used elsewhere?
+- Is it a regression of an earlier fix?
+
+## Finding template
+
+```
+[SEVERITY] <title>
+
+Attacker model:
+- WHO: <attacker type>
+- ACCESS: <privileges>
+- INTERFACE: <entry point>
+
+Attack vector: <step-by-step through accessible interfaces>
+Exploitability: EASY | MEDIUM | HARD, because <reason>
+Concrete impact: <specific harm>
+Proof of concept: <pseudocode or request sequence>
+Root cause: <file:line, commit>
+Blast radius: <N callers>
+Baseline violation: <invariant or pattern broken>
+```
+
+## Example
+
+**Change:** a refactor of the invoice routes moved handlers into a new router file. The old router applied `requireAccountMember` to the whole `/accounts/:accountId/*` group; the new file registers `GET /invoices/:id` without it and loads the invoice by id alone.
+
+1. **Attacker model.** WHO: any authenticated user. ACCESS: an ordinary account. INTERFACE: `GET /invoices/:id`.
+2. **Attack vector.** ENTRY POINT: `GET /invoices/:id`. SEQUENCE: log in with any account; request `/invoices/1001`, `/invoices/1002`, and so on; the handler calls `invoiceRepo.findById(id)` (src/invoices/routes.ts:24) with no account filter; the full invoice is returned. PROOF: the route is registered in src/app.ts:40 behind `requireLogin` only.
+3. **Exploitability.** EASY: one request per invoice, ordinary user, ids are sequential integers.
+4. **Impact.** Every invoice of every customer can be read: names, addresses, amounts, tax ids.
+5. **Baseline violation.** Breaks the invariant "a user only sees data of accounts they belong to". `requireAccountMember` guards every other account resource (12 routes). Git history: the guard was added in commit 4f2a9c1, "Fix: invoices readable across accounts". This is a regression.
+
+Recommendation: register the route inside the account-scoped router, or add the guard and filter the query by account id; add a test that a member of account A gets 404 for an invoice of account B.
+
+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: attacker types and example rewritten for web applications, no live testing, no separate agent.

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

@@ -0,0 +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.

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

@@ -0,0 +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.