@elizaos/skills 2.0.0-alpha.10

package/skills/security-differential-review/skills/differential-review/reporting.md

@@ -0,0 +1,369 @@
+# Report Generation (Phase 6)
+
+Comprehensive markdown report structure and formatting guidelines.
+
+---
+
+## Report Structure
+
+Generate markdown report with these mandatory sections:
+
+### 1. Executive Summary
+
+- Severity distribution table
+- Risk assessment (CRITICAL/HIGH/MEDIUM/LOW)
+- Final recommendation (APPROVE/REJECT/CONDITIONAL)
+- Key metrics (test gaps, blast radius, red flags)
+
+**Template:**
+```markdown
+# Executive Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 CRITICAL | X |
+| 🟠 HIGH | Y |
+| 🟡 MEDIUM | Z |
+| 🟢 LOW | W |
+
+**Overall Risk:** CRITICAL/HIGH/MEDIUM/LOW
+**Recommendation:** APPROVE/REJECT/CONDITIONAL
+
+**Key Metrics:**
+- Files analyzed: X/Y (Z%)
+- Test coverage gaps: N functions
+- High blast radius changes: M functions
+- Security regressions detected: P
+```
+
+---
+
+### 2. What Changed
+
+- Commit timeline with visual
+- File summary table
+- Lines changed stats
+
+**Template:**
+```markdown
+## What Changed
+
+**Commit Range:** `base..head`
+**Commits:** X
+**Timeline:** YYYY-MM-DD to YYYY-MM-DD
+
+| File | +Lines | -Lines | Risk | Blast Radius |
+|------|--------|--------|------|--------------|
+| file1.sol | +50 | -20 | HIGH | CRITICAL |
+| file2.sol | +10 | -5 | MEDIUM | LOW |
+
+**Total:** +N, -M lines across K files
+```
+
+---
+
+### 3. Critical Findings
+
+For each HIGH/CRITICAL issue:
+
+```markdown
+### [SEVERITY] Title
+
+**File**: path/to/file.ext:lineNumber
+**Commit**: hash
+**Blast Radius**: N callers (HIGH/MEDIUM/LOW)
+**Test Coverage**: YES/NO/PARTIAL
+
+**Description**: [clear explanation]
+
+**Historical Context**:
+- Git blame: Added in commit X (date)
+- Message: "[original commit message]"
+- [Why this code existed]
+
+**Attack Scenario**:
+[Concrete exploitation steps from adversarial.md]
+
+**Proof of Concept**:
+```code demonstrating issue```
+
+**Recommendation**:
+[Specific fix with code]
+```
+
+**Example:**
+```markdown
+### 🔴 CRITICAL: Authorization Bypass in Withdraw
+
+**File**: TokenVault.sol:156
+**Commit**: abc123def
+**Blast Radius**: 23 callers (HIGH)
+**Test Coverage**: NO
+
+**Description**:
+Removed `require(msg.sender == owner)` check allows any user to withdraw funds.
+
+**Historical Context**:
+- Git blame: Added 2024-06-15 (commit def456)
+- Message: "Add owner check per audit finding #45"
+- Code existed to prevent unauthorized withdrawals
+
+**Attack Scenario**:
+1. Attacker calls `withdraw(1000 ether)`
+2. No authorization check (removed)
+3. 1000 ETH transferred to attacker
+4. Protocol funds drained
+
+**Proof of Concept**:
+```solidity
+// As any address
+vault.withdraw(vault.balance());
+// Success - funds stolen
+```
+
+**Recommendation**:
+```solidity
+function withdraw(uint256 amount) external {
++   require(msg.sender == owner, "Unauthorized");
+    // ... rest of function
+}
+```
+```
+
+---
+
+### 4. Test Coverage Analysis
+
+- Coverage statistics
+- Untested changes list
+- Risk assessment
+
+**Template:**
+```markdown
+## Test Coverage Analysis
+
+**Coverage:** X% of changed code
+
+**Untested Changes:**
+| Function | Risk | Impact |
+|----------|------|--------|
+| functionA() | HIGH | No validation tests |
+| functionB() | MEDIUM | Logic untested |
+
+**Risk Assessment:**
+N HIGH-risk functions without tests → Recommend blocking merge
+```
+
+---
+
+### 5. Blast Radius Analysis
+
+- High-impact functions table
+- Dependency graph
+- Impact quantification
+
+**Template:**
+```markdown
+## Blast Radius Analysis
+
+**High-Impact Changes:**
+| Function | Callers | Risk | Priority |
+|----------|---------|------|----------|
+| transfer() | 89 | HIGH | P0 |
+| validate() | 45 | MEDIUM | P1 |
+```
+
+---
+
+### 6. Historical Context
+
+- Security-related removals
+- Regression risks
+- Commit message red flags
+
+**Template:**
+```markdown
+## Historical Context
+
+**Security-Related Removals:**
+- Line 45: `require` removed (added 2024-03 for CVE-2024-1234)
+- Line 78: Validation removed (added 2023-12 "security hardening")
+
+**Regression Risks:**
+- Code pattern removed in commit X, re-added in commit Y
+```
+
+---
+
+### 7. Recommendations
+
+- Immediate actions (blocking)
+- Before production (tracking)
+- Technical debt (future)
+
+**Template:**
+```markdown
+## Recommendations
+
+### Immediate (Blocking)
+- [ ] Fix CRITICAL issue in TokenVault.sol:156
+- [ ] Add tests for withdraw() function
+
+### Before Production
+- [ ] Security audit of auth changes
+- [ ] Load test blast radius functions
+
+### Technical Debt
+- [ ] Refactor validation pattern consistency
+```
+
+---
+
+### 8. Analysis Methodology
+
+- Strategy used (DEEP/FOCUSED/SURGICAL)
+- Files analyzed
+- Coverage estimate
+- Techniques applied
+- Limitations
+- Confidence level
+
+**Template:**
+```markdown
+## Analysis Methodology
+
+**Strategy:** FOCUSED (80 files, medium codebase)
+
+**Analysis Scope:**
+- Files reviewed: 45/80 (56%)
+- HIGH RISK: 100% coverage
+- MEDIUM RISK: 60% coverage
+- LOW RISK: Excluded
+
+**Techniques:**
+- Git blame on all removals
+- Blast radius calculation
+- Test coverage analysis
+- Adversarial modeling for HIGH RISK
+
+**Limitations:**
+- Did not analyze external dependencies
+- Limited to 1-hop caller analysis
+
+**Confidence:** HIGH for analyzed scope, MEDIUM overall
+```
+
+---
+
+### 9. Appendices
+
+- Commit reference table
+- Key definitions
+- Contact info
+
+---
+
+## Formatting Guidelines
+
+**Tables:** Use markdown tables for structured data
+
+**Code blocks:** Always include syntax highlighting
+```solidity
+// Solidity code
+```
+```rust
+// Rust code
+```
+
+**Status indicators:**
+- ✅ Complete
+- ⚠️ Warning
+- ❌ Failed/Blocked
+
+**Severity:**
+- 🔴 CRITICAL
+- 🟠 HIGH
+- 🟡 MEDIUM
+- 🟢 LOW
+
+**Before/After comparisons:**
+```markdown
+**BEFORE:**
+```code
+old code
+```
+
+**AFTER:**
+```code
+new code
+```
+```
+
+**Line number references:** Always include
+- Format: `file.sol:L123`
+- Link to commit: `file.sol:L123 (commit abc123)`
+
+---
+
+## File Naming and Location
+
+**Priority order for output:**
+1. Current working directory (if project repo)
+2. User's Desktop
+3. `~/.claude/skills/differential-review/output/`
+
+**Filename format:**
+```
+<PROJECT>_DIFFERENTIAL_REVIEW_<DATE>.md
+
+Example: VeChain_Stargate_DIFFERENTIAL_REVIEW_2025-12-26.md
+```
+
+---
+
+## User Notification Template
+
+After generating report:
+
+```markdown
+Report generated successfully!
+
+📄 File: [filename]
+📁 Location: [path]
+📏 Size: XX KB
+⏱️ Review Time: ~X hours
+
+Summary:
+- X findings (Y critical, Z high)
+- Final recommendation: APPROVE/REJECT/CONDITIONAL
+- Confidence: HIGH/MEDIUM/LOW
+
+Next steps:
+- Review findings in detail
+- Address CRITICAL/HIGH issues before merge
+- Consider chaining with issue-writer for stakeholder report
+```
+
+---
+
+## Integration with issue-writer
+
+After generating differential review, transform into audit report:
+
+```bash
+issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report
+```
+
+This creates polished documentation for non-technical stakeholders.
+
+---
+
+## Error Handling
+
+If file write fails:
+1. Try Desktop location
+2. Try temp directory
+3. As last resort, output full report to chat
+4. Notify user to save manually
+
+**Always prioritize persistent artifact generation over ephemeral chat output.**

package/skills/security-entry-point-analyzer/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "entry-point-analyzer",
+  "version": "1.0.0",
+  "description": "Analyzes smart contract codebases to identify state-changing entry points for security auditing. Detects externally callable functions that modify state, categorizes them by access level, and generates structured audit reports.",
+  "author": {
+    "name": "Nicolas Donboly",
+    "email": "opensource@trailofbits.com",
+    "url": "https://github.com/trailofbits"
+  }
+}

package/skills/security-entry-point-analyzer/README.md

@@ -0,0 +1,74 @@
+# Entry Point Analyzer
+
+A Claude skill for systematically identifying **state-changing** entry points in smart contract codebases to guide security audits.
+
+## Purpose
+
+When auditing smart contracts, examining each file or function individually is inefficient. What auditors need is to start from **entry points**—the externally callable functions that represent the attack surface. This skill automates the identification and classification of state-changing entry points, excluding view/pure/read-only functions that cannot directly cause loss of funds or state corruption.
+
+## Supported Languages
+
+| Language | File Extensions | Framework Support |
+|----------|-----------------|-------------------|
+| Solidity | `.sol` | OpenZeppelin, custom modifiers |
+| Vyper | `.vy` | Native patterns |
+| Solana | `.rs` | Anchor, Native |
+| Move | `.move` | Aptos, Sui |
+| TON | `.fc`, `.func`, `.tact` | FunC, Tact |
+| CosmWasm | `.rs` | cw-ownable, cw-controllers |
+
+## Access Classifications
+
+The skill categorizes entry points into four levels:
+
+1. **Public (Unrestricted)** — Callable by anyone; highest audit priority
+2. **Role-Restricted** — Limited to specific roles (admin, governance, guardian, etc.)
+3. **Review Required** — Ambiguous access patterns needing manual verification
+4. **Contract-Only** — Internal integration points (callbacks, hooks)
+
+## Output
+
+Generates a structured markdown report with:
+- Summary table of entry point counts by category
+- Detailed tables for each access level
+- Function signatures with file:line references
+- Restriction patterns and role assignments
+- List of analyzed files
+
+## Usage
+
+Trigger the skill with requests like:
+- "Analyze the entry points in this codebase"
+- "Find all external functions and access levels"
+- "List audit flows for src/core/"
+- "What privileged operations exist in this project?"
+
+## Directory Filtering
+
+Specify a subdirectory to limit scope:
+- "Analyze only `src/core/`"
+- "Find entry points in `contracts/protocol/`"
+
+## Role Detection
+
+The skill infers roles from common patterns:
+
+| Pattern | Detected Role |
+|---------|---------------|
+| `onlyOwner`, `msg.sender == owner` | Owner |
+| `onlyAdmin`, `ADMIN_ROLE` | Admin |
+| `onlyGovernance`, `governance` | Governance |
+| `onlyGuardian`, `onlyPauser` | Guardian |
+| `onlyKeeper`, `onlyRelayer` | Keeper/Relayer |
+| `onlyStrategy`, `strategist` | Strategist |
+| Dynamic checks (`authorized[msg.sender]`) | Review Required |
+
+## Installation
+
+```
+/plugin install trailofbits/skills/plugins/entry-point-analyzer
+```
+
+## License
+
+See LICENSE.txt for terms.

package/skills/security-entry-point-analyzer/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: security-entry-point-analyzer
+description: Analyzes smart contract codebases to identify state-changing entry points for security auditing. Detects externally callable functions that modify state, categorizes them by access level (public, admin, role-restricted, contract-only), and generates structured audit reports. Excludes view/pure/read-only functions. Use when auditing smart contracts (Solidity, Vyper, Solana/Rust, Move, TON, CosmWasm) or when asked to find entry points, audit flows, external functions, access control patterns, or privileged operations.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Entry Point Analyzer
+
+Systematically identify all **state-changing** entry points in a smart contract codebase to guide security audits.
+
+## When to Use
+
+Use this skill when:
+- Starting a smart contract security audit to map the attack surface
+- Asked to find entry points, external functions, or audit flows
+- Analyzing access control patterns across a codebase
+- Identifying privileged operations and role-restricted functions
+- Building an understanding of which functions can modify contract state
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Vulnerability detection (use audit-context-building or domain-specific-audits)
+- Writing exploit POCs (use solidity-poc-builder)
+- Code quality or gas optimization analysis
+- Non-smart-contract codebases
+- Analyzing read-only functions (this skill excludes them)
+
+## Scope: State-Changing Functions Only
+
+This skill focuses exclusively on functions that can modify state. **Excluded:**
+
+| Language | Excluded Patterns |
+|----------|-------------------|
+| Solidity | `view`, `pure` functions |
+| Vyper | `@view`, `@pure` functions |
+| Solana | Functions without `mut` account references |
+| Move | Non-entry `public fun` (module-callable only) |
+| TON | `get` methods (FunC), read-only receivers (Tact) |
+| CosmWasm | `query` entry point and its handlers |
+
+**Why exclude read-only functions?** They cannot directly cause loss of funds or state corruption. While they may leak information, the primary audit focus is on functions that can change state.
+
+## Workflow
+
+1. **Detect Language** - Identify contract language(s) from file extensions and syntax
+2. **Use Tooling (if available)** - For Solidity, check if Slither is available and use it
+3. **Locate Contracts** - Find all contract/module files (apply directory filter if specified)
+4. **Extract Entry Points** - Parse each file for externally callable, state-changing functions
+5. **Classify Access** - Categorize each function by access level
+6. **Generate Report** - Output structured markdown report
+
+## Slither Integration (Solidity)
+
+For Solidity codebases, Slither can automatically extract entry points. Before manual analysis:
+
+### 1. Check if Slither is Available
+
+```bash
+which slither
+```
+
+### 2. If Slither is Detected, Run Entry Points Printer
+
+```bash
+slither . --print entry-points
+```
+
+This outputs a table of all state-changing entry points with:
+- Contract name
+- Function name
+- Visibility
+- Modifiers applied
+
+### 3. Use Slither Output as Foundation
+
+- Parse the Slither output table to populate your analysis
+- Cross-reference with manual inspection for access control classification
+- Slither may miss some patterns (callbacks, dynamic access control)—supplement with manual review
+- If Slither fails (compilation errors, unsupported features), fall back to manual analysis
+
+### 4. When Slither is NOT Available
+
+If `which slither` returns nothing, proceed with manual analysis using the language-specific reference files.
+
+## Language Detection
+
+| Extension | Language | Reference |
+|-----------|----------|-----------|
+| `.sol` | Solidity | [skills/entry-point-analyzer/references/solidity.md](skills/entry-point-analyzer/references/solidity.md) |
+| `.vy` | Vyper | [skills/entry-point-analyzer/references/vyper.md](skills/entry-point-analyzer/references/vyper.md) |
+| `.rs` + `Cargo.toml` with `solana-program` | Solana (Rust) | [skills/entry-point-analyzer/references/solana.md](skills/entry-point-analyzer/references/solana.md) |
+| `.move` + `Move.toml` with `edition` | [skills/entry-point-analyzer/references/move-sui.md](skills/entry-point-analyzer/references/move-sui.md) |
+| `.move` + `Move.toml` with `Aptos` | [skills/entry-point-analyzer/references/move-aptos.md](skills/entry-point-analyzer/references/move-aptos.md) |
+| `.fc`, `.func`, `.tact` | TON (FunC/Tact) | [skills/entry-point-analyzer/references/ton.md](skills/entry-point-analyzer/references/ton.md) |
+| `.rs` + `Cargo.toml` with `cosmwasm-std` | CosmWasm | [skills/entry-point-analyzer/references/cosmwasm.md](skills/entry-point-analyzer/references/cosmwasm.md) |
+
+Load the appropriate reference file(s) based on detected language before analysis.
+
+## Access Classification
+
+Classify each state-changing entry point into one of these categories:
+
+### 1. Public (Unrestricted)
+Functions callable by anyone without restrictions.
+
+### 2. Role-Restricted
+Functions limited to specific roles. Common patterns to detect:
+- Explicit role names: `admin`, `owner`, `governance`, `guardian`, `operator`, `manager`, `minter`, `pauser`, `keeper`, `relayer`, `lender`, `borrower`
+- Role-checking patterns: `onlyRole`, `hasRole`, `require(msg.sender == X)`, `assert_owner`, `#[access_control]`
+- When role is ambiguous, flag as **"Restricted (review required)"** with the restriction pattern noted
+
+### 3. Contract-Only (Internal Integration Points)
+Functions callable only by other contracts, not by EOAs. Indicators:
+- Callbacks: `onERC721Received`, `uniswapV3SwapCallback`, `flashLoanCallback`
+- Interface implementations with contract-caller checks
+- Functions that revert if `tx.origin == msg.sender`
+- Cross-contract hooks
+
+## Output Format
+
+Generate a markdown report with this structure:
+
+```markdown
+# Entry Point Analysis: [Project Name]
+
+**Analyzed**: [timestamp]
+**Scope**: [directories analyzed or "full codebase"]
+**Languages**: [detected languages]
+**Focus**: State-changing functions only (view/pure excluded)
+
+## Summary
+
+| Category | Count |
+|----------|-------|
+| Public (Unrestricted) | X |
+| Role-Restricted | X |
+| Restricted (Review Required) | X |
+| Contract-Only | X |
+| **Total** | **X** |
+
+---
+
+## Public Entry Points (Unrestricted)
+
+State-changing functions callable by anyone—prioritize for attack surface analysis.
+
+| Function | File | Notes |
+|----------|------|-------|
+| `functionName(params)` | `path/to/file.sol:L42` | Brief note if relevant |
+
+---
+
+## Role-Restricted Entry Points
+
+### Admin / Owner
+| Function | File | Restriction |
+|----------|------|-------------|
+| `setFee(uint256)` | `Config.sol:L15` | `onlyOwner` |
+
+### Governance
+| Function | File | Restriction |
+|----------|------|-------------|
+
+### Guardian / Pauser
+| Function | File | Restriction |
+|----------|------|-------------|
+
+### Other Roles
+| Function | File | Restriction | Role |
+|----------|------|-------------|------|
+
+---
+
+## Restricted (Review Required)
+
+Functions with access control patterns that need manual verification.
+
+| Function | File | Pattern | Why Review |
+|----------|------|---------|------------|
+| `execute(bytes)` | `Executor.sol:L88` | `require(trusted[msg.sender])` | Dynamic trust list |
+
+---
+
+## Contract-Only (Internal Integration Points)
+
+Functions only callable by other contracts—useful for understanding trust boundaries.
+
+| Function | File | Expected Caller |
+|----------|------|-----------------|
+| `onFlashLoan(...)` | `Vault.sol:L200` | Flash loan provider |
+
+---
+
+## Files Analyzed
+
+- `path/to/file1.sol` (X state-changing entry points)
+- `path/to/file2.sol` (X state-changing entry points)
+```
+
+## Filtering
+
+When user specifies a directory filter:
+- Only analyze files within that path
+- Note the filter in the report header
+- Example: "Analyze only `src/core/`" → scope = `src/core/`
+
+## Analysis Guidelines
+
+1. **Be thorough**: Don't skip files. Every state-changing externally callable function matters.
+2. **Be conservative**: When uncertain about access level, flag for review rather than miscategorize.
+3. **Skip read-only**: Exclude `view`, `pure`, and equivalent read-only functions.
+4. **Note inheritance**: If a function's access control comes from a parent contract, note this.
+5. **Track modifiers**: List all access-related modifiers/decorators applied to each function.
+6. **Identify patterns**: Look for common patterns like:
+   - Initializer functions (often unrestricted on first call)
+   - Upgrade functions (high-privilege)
+   - Emergency/pause functions (guardian-level)
+   - Fee/parameter setters (admin-level)
+   - Token transfers and approvals (often public)
+
+## Common Role Patterns by Protocol Type
+
+| Protocol Type | Common Roles |
+|---------------|--------------|
+| DEX | `owner`, `feeManager`, `pairCreator` |
+| Lending | `admin`, `guardian`, `liquidator`, `oracle` |
+| Governance | `proposer`, `executor`, `canceller`, `timelock` |
+| NFT | `minter`, `admin`, `royaltyReceiver` |
+| Bridge | `relayer`, `guardian`, `validator`, `operator` |
+| Vault/Yield | `strategist`, `keeper`, `harvester`, `manager` |
+
+## Rationalizations to Reject
+
+When analyzing entry points, reject these shortcuts:
+- "This function looks standard" → Still classify it; standard functions can have non-standard access control
+- "The modifier name is clear" → Verify the modifier's actual implementation
+- "This is obviously admin-only" → Trace the actual restriction; "obvious" assumptions miss subtle bypasses
+- "I'll skip the callbacks" → Callbacks define trust boundaries; always include them
+- "It doesn't modify much state" → Any state change can be exploited; include all non-view functions
+
+## Error Handling
+
+If a file cannot be parsed:
+1. Note it in the report under "Analysis Warnings"
+2. Continue with remaining files
+3. Suggest manual review for unparsable files