nexakit 0.0.0-stage → 0.2.0

package/skills/differential-review/adversarial.md

@@ -0,0 +1,203 @@
+# Adversarial Vulnerability Analysis (Phase 5)
+
+Structured methodology for finding vulnerabilities through attacker modeling.
+
+**When to use:** After completing deep context analysis (Phase 4), apply this to all HIGH RISK changes.
+
+---
+
+## 1. Define Specific Attacker Model
+
+**WHO is the attacker?**
+- Unauthenticated external user
+- Authenticated regular user
+- Malicious administrator
+- Compromised contract/service
+- Front-runner/MEV bot
+
+**WHAT access/privileges do they have?**
+- Public API access only
+- Authenticated user role
+- Specific permissions/tokens
+- Contract call capabilities
+
+**WHERE do they interact with the system?**
+- Specific HTTP endpoints
+- Smart contract functions
+- RPC interfaces
+- External APIs
+
+---
+
+## 2. Identify Concrete Attack Vectors
+
+```
+ENTRY POINT: [Exact function/endpoint attacker can access]
+
+ATTACK SEQUENCE:
+1. [Specific API call/transaction with parameters]
+2. [How this reaches the vulnerable code]
+3. [What happens in the vulnerable code]
+4. [Impact achieved]
+
+PROOF OF ACCESSIBILITY:
+- Show the function is public/external
+- Demonstrate attacker has required permissions
+- Prove attack path exists through actual interfaces
+```
+
+---
+
+## 3. Rate Realistic Exploitability
+
+**EASY:** Exploitable via public APIs with no special privileges
+- Single transaction/call
+- Common user access level
+- No complex conditions required
+
+**MEDIUM:** Requires specific conditions or elevated privileges
+- Multiple steps or timing requirements
+- Elevated but obtainable privileges
+- Specific system state needed
+
+**HARD:** Requires privileged access or rare conditions
+- Admin/owner privileges needed
+- Rare edge case conditions
+- Significant resources required
+
+---
+
+## 4. Build Complete Exploit Scenario
+
+```
+ATTACKER STARTING POSITION:
+[What the attacker has at the beginning]
+
+STEP-BY-STEP EXPLOITATION:
+Step 1: [Concrete action through accessible interface]
+  - Command: [Exact call/request]
+  - Parameters: [Specific values]
+  - Expected result: [What happens]
+
+Step 2: [Next action]
+  - Command: [Exact call/request]
+  - Why this works: [Reference to code change]
+  - System state change: [What changed]
+
+Step 3: [Final impact]
+  - Result: [Concrete harm achieved]
+  - Evidence: [How to verify impact]
+
+CONCRETE IMPACT:
+[Specific, measurable impact - not "could cause issues"]
+- Exact amount of funds drained
+- Specific privileges escalated
+- Particular data exposed
+```
+
+---
+
+## 5. Cross-Reference with Baseline Context
+
+From baseline analysis (see [methodology.md](methodology.md#pre-analysis-baseline-context-building)), check:
+- Does this violate a system-wide invariant?
+- Does this break a trust boundary?
+- Does this bypass a validation pattern?
+- Is this a regression of a previous fix?
+
+---
+
+## Vulnerability Report Template
+
+Generate this for each finding:
+
+```markdown
+## [SEVERITY] Vulnerability Title
+
+**Attacker Model:**
+- WHO: [Specific attacker type]
+- ACCESS: [Exact privileges]
+- INTERFACE: [Specific entry point]
+
+**Attack Vector:**
+[Step-by-step exploit through accessible interfaces]
+
+**Exploitability:** EASY/MEDIUM/HARD
+**Justification:** [Why this rating]
+
+**Concrete Impact:**
+[Specific, measurable harm - not theoretical]
+
+**Proof of Concept:**
+```code
+// Exact code to reproduce
+```
+
+**Root Cause:**
+[Reference specific code change at file.sol:L123]
+
+**Blast Radius:** [N callers affected]
+**Baseline Violation:** [Which invariant/pattern broken]
+```
+
+---
+
+## Example: Complete Adversarial Analysis
+
+**Change:** Removed `require(amount > 0)` check from `withdraw()` function
+
+### 1. Attacker Model
+- **WHO:** Unauthenticated external user
+- **ACCESS:** Can call public contract functions
+- **INTERFACE:** `withdraw(uint256 amount)` at 0x1234...
+
+### 2. Attack Vector
+**ENTRY POINT:** `withdraw(0)`
+
+**ATTACK SEQUENCE:**
+1. Call `withdraw(0)` from attacker address
+2. Code bypasses amount check (removed)
+3. Withdraw event emitted with 0 amount
+4. Accounting updated incorrectly
+
+**PROOF:** Function is `external`, no auth required
+
+### 3. Exploitability
+**RATING:** EASY
+- Single transaction
+- Public function
+- No special state required
+
+### 4. Exploit Scenario
+**ATTACKER POSITION:** Has user account with 0 balance
+
+**EXPLOITATION:**
+```solidity
+Step 1: attacker.withdraw(0)
+  - Passes removed validation
+  - Emits Withdraw(user, 0)
+  - Updates withdrawnAmount[user] += 0
+
+Step 2: Off-chain indexer sees Withdraw event
+  - Credits attacker for 0 withdrawal
+  - But accounting thinks withdrawal happened
+
+Step 3: Accounting mismatch exploited
+  - Total supply decremented
+  - User balance not changed
+  - System invariants broken
+```
+
+**IMPACT:**
+- Protocol accounting corrupted
+- Can be used to manipulate LP calculations
+- Estimated $50K impact on pool prices
+
+### 5. Baseline Violation
+- Violates invariant: "All withdrawals must transfer non-zero value"
+- Breaks validation pattern: Amount checks present in all other value transfers
+- Regression: Check added in commit abc123 "Fix zero-amount exploit"
+
+---
+
+**Next:** Document all findings in final report (see [reporting.md](reporting.md))

package/skills/differential-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Differential Review"
+  short_description: "Review code changes for security regressions and impact"
+  icon_small: "assets/trail-of-bits-mark.svg"
+  icon_large: "assets/trail-of-bits-mark.svg"
+  brand_color: "#D83A34"

package/skills/differential-review/assets/trail-of-bits-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="94" height="56" fill="none" viewBox="0 0 94 56"><path fill="#F0F4F7" d="m34.04 54.662-7.61-4.147L24.593 56l9.433-1.335c-.029 0-.043 0 .014-.003"/><path fill="#F0F4F7" d="m34.039 54.662-.014.003c.035 0 .096-.003.014-.003m26.191-2.67 6.124-1.804 2.301-7.26-5.655.387zM74.805 5.478l-4.68-3.035-2.62 8.332 5.15 1.548zM43.224 3.532s3.172.973 4.423 1.328l4.508 1.335L52.234 0l-7.928 1.576zm-31.473 23.14 5.566.014 1.982-6.216-5.06-1.342c-.538 1.708-1.94 5.837-2.488 7.544M1.394 20.896l4.164 4.338 2.398-7.696-5.11-1.357zm88.205 24.841c-.086-2.18-.692-2.894-1.978-4.232l-6.71.447c1.871 1.175 3.018 2.63 3.255 4.583.261 2.145-2.068 4.623-4.322 4.623-1.258 0-1.885-.987-1.885-2.12.035-.845.333-1.942.777-2.673h-5.691c-.444 1.136-.813 2.418-.813 3.625 0 4.136 3.659 5.197 7.131 5.197 3.62 0 6.616-.696 8.501-4.03.85-1.505 1.806-3.663 1.735-5.42M18.804.56 1.362.576 0 4.86l6.394-.007-3.161 9.962 5.114 1.356 3.551-11.322 5.544-.007z"/><path fill="#F0F4F7" d="M20.707 15.898c.628-.04 1.258-.04 1.886-.04 1.035-.003 2.587.072 2.587 1.499.004.987-.366 2.233-.66 3.184-.551 1.942-1.214 3.88-1.325 5.858l5.727-.007c-.151-3.185 1.842-5.968 1.838-9.117 0-2.123-1.627-2.964-3.512-3.294l.552-.075c4.103-.554 6.39-3.738 6.386-7.729-.004-4.423-3.738-5.666-7.544-5.662l-6.576.007c-1.87 5.751-3.645 11.534-5.462 17.31l5.057 1.339zM24.245 4.58l1.849-.004c1.369 0 2.734.327 2.738 1.939.003 1.977-1.437 5.31-3.803 5.31l-3.031.004zm11.959 21.883 2.949-5.531 7.06-.008-.215 5.564 5.544-.004.441-18.94-4.763-1.43a89 89 0 0 0-.677 10.71h-.036l-5.322.004c1.914-3.586 3.749-7.2 5.4-10.906L42.77 4.775 30.437 26.466zm39.249-.036 1.402-4.214-7.43.01 2.753-8.612-5.15-1.548-4.584 14.375zm-34.411 1.658h-7.28l-6.834 21.18 8.698 4.694c5.208-.196 8.856-4.012 8.856-9.252 0-2.013-1.258-3.586-3.215-4.136 3.846-.877 6.319-3.33 6.319-7.356-.004-3.923-3.072-5.13-6.544-5.13m-2.993 20.318c-1.036 1.537-2.143 1.647-3.881 1.647h-2.254l2.476-7.611c1.81.07 5.024-.366 5.024 2.268 0 1.168-.698 2.744-1.365 3.696m-.444-9.667h-2.072l2.18-6.7c1.626.075 4.694-.436 4.694 2.053.04 2.928-1.846 4.647-4.802 4.647M58.67 9.582l-5.522 18.29-4.878 14.836 5.856-.447 4.23-13.2h.006l5.713-17.878c-.796-.22-3.964-1.228-5.404-1.601m2.738 18.542-1.37 4.278h6.398l-2.993 9.525 5.584-.38 2.913-9.145h5.541l1.37-4.278zm25.351-.259c-5.726 0-9.127 3.951-9.127 9.444.007.798.727 2.765 2.2 3.422l6.888-.462c-1.172-.98-3.243-3.29-3.243-4.519 0-1.686.95-3.891 2.91-3.891 1.33 0 2.143.366 2.143 1.793 0 .916-.444 1.757-.702 2.638h5.322c.333-.77.849-2.528.849-3.334.004-3.994-3.913-5.09-7.24-5.09m-63.15.372c-2.605 0-2.978 1.906-3.623 3.93-.215.728-.623 1.615-.623 2.379 0 1.47 1.315 1.75 2.537 1.75 1.494.01 2.29-.487 2.82-1.878.362-.952 1.305-3.568 1.305-4.488 0-1.303-1.326-1.693-2.416-1.693m.728 1.87c0 .328-.373 1.392-.498 1.765l-.577 1.782c-.226.675-.498 1.449-1.359 1.449-.487 0-.802-.28-.802-.785 0-.653.509-1.864.724-2.538.215-.671.498-2.01 1.247-2.269.168-.056.351-.078.534-.078.34 0 .749.302.749.664zm5.902 2.674.394-1.292H28.37l.613-1.928h2.38l.42-1.292h-4.126l-2.48 7.924h1.735l1.075-3.412z"/></svg>

package/skills/differential-review/methodology.md

@@ -0,0 +1,234 @@
+# Differential Review Methodology
+
+Detailed phase-by-phase workflow for security-focused code review.
+
+## Pre-Analysis: Baseline Context Building
+
+**FIRST ACTION - Build complete baseline understanding:**
+
+If `audit-context-building` skill is available:
+
+```bash
+# Checkout baseline commit
+git checkout <baseline_commit>
+
+# Invoke audit-context-building skill on baseline codebase
+# Scope = entire relevant project (e.g., packages/contracts/contracts/ for Solidity, src/ for Rust, etc.)
+audit-context-building --scope [entire project or main contract directory] --focus invariants,trust-boundaries,validation-patterns,call-graphs,state-flows
+
+# Examples:
+# For Solidity: audit-context-building --scope packages/contracts/contracts
+# For Rust: audit-context-building --scope src
+# For full repo: audit-context-building --scope .
+```
+
+**Capture from baseline analysis:**
+- System-wide invariants (what must ALWAYS be true across all code)
+- Trust boundaries and privilege levels (who can do what)
+- Validation patterns (what gets checked where - defense-in-depth)
+- Complete call graphs for critical functions (who calls what)
+- State flow diagrams (how state changes)
+- External dependencies and trust assumptions
+
+**Why this matters:**
+- Understand what the code was SUPPOSED to do before changes
+- Identify implicit security assumptions in baseline
+- Detect when changes violate baseline invariants
+- Know which patterns are system-wide vs local
+- Catch when changes break defense-in-depth
+
+**Store baseline context for reference during differential analysis.**
+
+After baseline analysis, checkout back to head commit to analyze changes.
+
+---
+
+## Phase 0: Intake & Triage
+
+**Extract changes:**
+```bash
+# For commit range
+git diff <base>..<head> --stat
+git log <base>..<head> --oneline
+
+# For PR
+gh pr view <number> --json files,additions,deletions
+
+# Get all changed files
+git diff <base>..<head> --name-only
+```
+
+**Assess codebase size:**
+```bash
+find . -name "*.sol" -o -name "*.rs" -o -name "*.go" -o -name "*.ts" | wc -l
+```
+
+**Classify complexity:**
+- **SMALL**: <20 files → Deep analysis (read all deps)
+- **MEDIUM**: 20-200 files → Focused analysis (1-hop deps)
+- **LARGE**: 200+ files → Surgical (critical paths only)
+
+**Risk score each file:**
+- **HIGH**: Auth, crypto, external calls, value transfer, validation removal
+- **MEDIUM**: Business logic, state changes, new public APIs
+- **LOW**: Comments, tests, UI, logging
+
+---
+
+## Phase 1: Changed Code Analysis
+
+For each changed file:
+
+1. **Read both versions** (baseline and changed)
+
+2. **Analyze each diff region:**
+   ```
+   BEFORE: [exact code]
+   AFTER: [exact code]
+   CHANGE: [behavioral impact]
+   SECURITY: [implications]
+   ```
+
+3. **Git blame removed code:**
+   ```bash
+   # When was it added? Why?
+   git log -S "removed_code" --all --oneline
+   git blame <baseline> -- file.sol | grep "pattern"
+   ```
+
+   **Red flags:**
+   - Removed code from "fix", "security", "CVE" commits → CRITICAL
+   - Recently added (<1 month) then removed → HIGH
+
+4. **Check for regressions (re-added code):**
+   ```bash
+   git log -S "added_code" --all -p
+   ```
+
+   Pattern: Code added → removed for security → re-added now = REGRESSION
+
+5. **Micro-adversarial analysis** for each change:
+   - What attack did removed code prevent?
+   - What new surface does new code expose?
+   - Can modified logic be bypassed?
+   - Are checks weaker? Edge cases covered?
+
+6. **Generate concrete attack scenarios:**
+   ```
+   SCENARIO: [attack goal]
+   PRECONDITIONS: [required state]
+   STEPS:
+     1. [specific action]
+     2. [expected outcome]
+     3. [exploitation]
+   WHY IT WORKS: [reference code change]
+   IMPACT: [severity + scope]
+   ```
+
+---
+
+## Phase 2: Test Coverage Analysis
+
+**Identify coverage gaps:**
+```bash
+# Production code changes (exclude tests)
+git diff <range> --name-only | grep -v "test"
+
+# Test changes
+git diff <range> --name-only | grep "test"
+
+# For each changed function, search for tests
+grep -r "test.*functionName" test/ --include="*.sol" --include="*.js"
+```
+
+**Risk elevation rules:**
+- NEW function + NO tests → Elevate risk MEDIUM→HIGH
+- MODIFIED validation + UNCHANGED tests → HIGH RISK
+- Complex logic (>20 lines) + NO tests → HIGH RISK
+
+---
+
+## Phase 3: Blast Radius Analysis
+
+**Calculate impact:**
+```bash
+# Count callers for each modified function
+grep -r "functionName(" --include="*.sol" . | wc -l
+```
+
+**Classify blast radius:**
+- 1-5 calls: LOW
+- 6-20 calls: MEDIUM
+- 21-50 calls: HIGH
+- 50+ calls: CRITICAL
+
+**Priority matrix:**
+
+| Change Risk | Blast Radius | Priority | Analysis Depth |
+|-------------|--------------|----------|----------------|
+| HIGH | CRITICAL | P0 | Deep + all deps |
+| HIGH | HIGH/MEDIUM | P1 | Deep |
+| HIGH | LOW | P2 | Standard |
+| MEDIUM | CRITICAL/HIGH | P1 | Standard + callers |
+
+---
+
+## Phase 4: Deep Context Analysis
+
+**If `audit-context-building` skill is available**, invoke it to help answer all the questions below for each HIGH RISK changed function:
+
+```bash
+# Run audit-context-building on the changed function and its dependencies
+audit-context-building --scope [file containing changed function] --focus flow-analysis,call-graphs,invariants,root-cause
+```
+
+**The audit-context-building skill will help you answer:**
+
+1. **Map complete function flow:**
+   - Entry conditions (preconditions, requires, modifiers)
+   - State reads (which variables accessed)
+   - State writes (which variables modified)
+   - External calls (to contracts, APIs, system)
+   - Return values and side effects
+
+2. **Trace internal calls:**
+   - List all functions called
+   - Recursively map their flows
+   - Build complete call graph
+
+3. **Trace external calls:**
+   - Identify trust boundaries crossed
+   - List assumptions about external behavior
+   - Check for reentrancy risks
+
+4. **Identify invariants:**
+   - What must ALWAYS be true?
+   - What must NEVER happen?
+   - Are invariants maintained after changes?
+
+5. **Five Whys root cause:**
+   - WHY was this code changed?
+   - WHY did the original code exist?
+   - WHY might this break?
+   - WHY is this approach chosen?
+   - WHY could this fail in production?
+
+**If `audit-context-building` skill is NOT available**, manually perform the line-by-line analysis above using Read, Grep, and code tracing.
+
+**Cross-cutting pattern detection:**
+```bash
+# Find repeated validation patterns
+grep -r "require.*amount > 0" --include="*.sol" .
+grep -r "onlyOwner" --include="*.sol" .
+
+# Check if any removed in diff
+git diff <range> | grep "^-.*require.*amount > 0"
+```
+
+**Flag if removal breaks defense-in-depth.**
+
+---
+
+**Next steps:**
+- For HIGH RISK changes, proceed to [adversarial.md](adversarial.md)
+- For report generation, see [reporting.md](reporting.md)