@bgicli/bgicli 2.2.8 → 2.2.10

package/data/skills/trailofbits-audit-context-building/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: audit-context-building
+description: Enables ultra-granular, line-by-line code analysis to build deep architectural context before vulnerability or bug finding.
+---
+
+# Deep Context Builder Skill (Ultra-Granular Pure Context Mode)
+
+## 1. Purpose
+
+This skill governs **how Claude thinks** during the context-building phase of an audit.
+
+When active, Claude will:
+- Perform **line-by-line / block-by-block** code analysis by default.
+- Apply **First Principles**, **5 Whys**, and **5 Hows** at micro scale.
+- Continuously link insights → functions → modules → entire system.
+- Maintain a stable, explicit mental model that evolves with new evidence.
+- Identify invariants, assumptions, flows, and reasoning hazards.
+
+This skill defines a structured analysis format (see Example: Function Micro-Analysis below) and runs **before** the vulnerability-hunting phase.
+
+---
+
+## 2. When to Use This Skill
+
+Use when:
+- Deep comprehension is needed before bug or vulnerability discovery.
+- You want bottom-up understanding instead of high-level guessing.
+- Reducing hallucinations, contradictions, and context loss is critical.
+- Preparing for security auditing, architecture review, or threat modeling.
+
+Do **not** use for:
+- Vulnerability findings
+- Fix recommendations
+- Exploit reasoning
+- Severity/impact rating
+
+---
+
+## 3. How This Skill Behaves
+
+When active, Claude will:
+- Default to **ultra-granular analysis** of each block and line.
+- Apply micro-level First Principles, 5 Whys, and 5 Hows.
+- Build and refine a persistent global mental model.
+- Update earlier assumptions when contradicted ("Earlier I thought X; now Y.").
+- Periodically anchor summaries to maintain stable context.
+- Avoid speculation; express uncertainty explicitly when needed.
+
+Goal: **deep, accurate understanding**, not conclusions.
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "I get the gist" | Gist-level understanding misses edge cases | Line-by-line analysis required |
+| "This function is simple" | Simple functions compose into complex bugs | Apply 5 Whys anyway |
+| "I'll remember this invariant" | You won't. Context degrades. | Write it down explicitly |
+| "External call is probably fine" | External = adversarial until proven otherwise | Jump into code or model as hostile |
+| "I can skip this helper" | Helpers contain assumptions that propagate | Trace the full call chain |
+| "This is taking too long" | Rushed context = hallucinated vulnerabilities later | Slow is fast |
+
+---
+
+## 4. Phase 1 — Initial Orientation (Bottom-Up Scan)
+
+Before deep analysis, Claude performs a minimal mapping:
+
+1. Identify major modules/files/contracts.
+2. Note obvious public/external entrypoints.
+3. Identify likely actors (users, owners, relayers, oracles, other contracts).
+4. Identify important storage variables, dicts, state structs, or cells.
+5. Build a preliminary structure without assuming behavior.
+
+This establishes anchors for detailed analysis.
+
+---
+
+## 5. Phase 2 — Ultra-Granular Function Analysis (Default Mode)
+
+Every non-trivial function receives full micro analysis.
+
+### 5.1 Per-Function Microstructure Checklist
+
+For each function:
+
+1. **Purpose**
+   - Why the function exists and its role in the system.
+
+2. **Inputs & Assumptions**
+   - Parameters and implicit inputs (state, sender, env).
+   - Preconditions and constraints.
+
+3. **Outputs & Effects**
+   - Return values.
+   - State/storage writes.
+   - Events/messages.
+   - External interactions.
+
+4. **Block-by-Block / Line-by-Line Analysis**
+   For each logical block:
+   - What it does.
+   - Why it appears here (ordering logic).
+   - What assumptions it relies on.
+   - What invariants it establishes or maintains.
+   - What later logic depends on it.
+
+   Apply per-block:
+   - **First Principles**
+   - **5 Whys**
+   - **5 Hows**
+
+---
+
+### 5.2 Cross-Function & External Flow Analysis
+*(Full Integration of Jump-Into-External-Code Rule)*
+
+When encountering calls, **continue the same micro-first analysis across boundaries.**
+
+#### Internal Calls
+- Jump into the callee immediately.
+- Perform block-by-block analysis of relevant code.
+- Track flow of data, assumptions, and invariants:
+  caller → callee → return → caller.
+- Note if callee logic behaves differently in this specific call context.
+
+#### External Calls — Two Cases
+
+**Case A — External Call to a Contract Whose Code Exists in the Codebase**
+Treat as an internal call:
+- Jump into the target contract/function.
+- Continue block-by-block micro-analysis.
+- Propagate invariants and assumptions seamlessly.
+- Consider edge cases based on the *actual* code, not a black-box guess.
+
+**Case B — External Call Without Available Code (True External / Black Box)**
+Analyze as adversarial:
+- Describe payload/value/gas or parameters sent.
+- Identify assumptions about the target.
+- Consider all outcomes:
+  - revert
+  - incorrect/strange return values
+  - unexpected state changes
+  - misbehavior
+  - reentrancy (if applicable)
+
+#### Continuity Rule
+Treat the entire call chain as **one continuous execution flow**.
+Never reset context.
+All invariants, assumptions, and data dependencies must propagate across calls.
+
+---
+
+### 5.3 Complete Analysis Example
+
+See [FUNCTION_MICRO_ANALYSIS_EXAMPLE.md](resources/FUNCTION_MICRO_ANALYSIS_EXAMPLE.md) for a complete walkthrough demonstrating:
+- Full micro-analysis of a DEX swap function
+- Application of First Principles, 5 Whys, and 5 Hows
+- Block-by-block analysis with invariants and assumptions
+- Cross-function dependency mapping
+- Risk analysis for external interactions
+
+This example demonstrates the level of depth and structure required for all analyzed functions.
+
+---
+
+### 5.4 Output Requirements
+
+When performing ultra-granular analysis, Claude MUST structure output following the format defined in [OUTPUT_REQUIREMENTS.md](resources/OUTPUT_REQUIREMENTS.md).
+
+Key requirements:
+- **Purpose** (2-3 sentences minimum)
+- **Inputs & Assumptions** (all parameters, preconditions, trust assumptions)
+- **Outputs & Effects** (returns, state writes, external calls, events, postconditions)
+- **Block-by-Block Analysis** (What, Why here, Assumptions, First Principles/5 Whys/5 Hows)
+- **Cross-Function Dependencies** (internal calls, external calls with risk analysis, shared state)
+
+Quality thresholds:
+- Minimum 3 invariants per function
+- Minimum 5 assumptions documented
+- Minimum 3 risk considerations for external interactions
+- At least 1 First Principles application
+- At least 3 combined 5 Whys/5 Hows applications
+
+---
+
+### 5.5 Completeness Checklist
+
+Before concluding micro-analysis of a function, verify against the [COMPLETENESS_CHECKLIST.md](resources/COMPLETENESS_CHECKLIST.md):
+
+- **Structural Completeness**: All required sections present (Purpose, Inputs, Outputs, Block-by-Block, Dependencies)
+- **Content Depth**: Minimum thresholds met (invariants, assumptions, risk analysis, First Principles)
+- **Continuity & Integration**: Cross-references, propagated assumptions, invariant couplings
+- **Anti-Hallucination**: Line number citations, no vague statements, evidence-based claims
+
+Analysis is complete when all checklist items are satisfied and no unresolved "unclear" items remain.
+
+---
+
+## 6. Phase 3 — Global System Understanding
+
+After sufficient micro-analysis:
+
+1. **State & Invariant Reconstruction**
+   - Map reads/writes of each state variable.
+   - Derive multi-function and multi-module invariants.
+
+2. **Workflow Reconstruction**
+   - Identify end-to-end flows (deposit, withdraw, lifecycle, upgrades).
+   - Track how state transforms across these flows.
+   - Record assumptions that persist across steps.
+
+3. **Trust Boundary Mapping**
+   - Actor → entrypoint → behavior.
+   - Identify untrusted input paths.
+   - Privilege changes and implicit role expectations.
+
+4. **Complexity & Fragility Clustering**
+   - Functions with many assumptions.
+   - High branching logic.
+   - Multi-step dependencies.
+   - Coupled state changes across modules.
+
+These clusters help guide the vulnerability-hunting phase.
+
+---
+
+## 7. Stability & Consistency Rules
+*(Anti-Hallucination, Anti-Contradiction)*
+
+Claude must:
+
+- **Never reshape evidence to fit earlier assumptions.**
+  When contradicted:
+  - Update the model.
+  - State the correction explicitly.
+
+- **Periodically anchor key facts**
+  Summarize core:
+  - invariants
+  - state relationships
+  - actor roles
+  - workflows
+
+- **Avoid vague guesses**
+  Use:
+  - "Unclear; need to inspect X."
+  instead of:
+  - "It probably…"
+
+- **Cross-reference constantly**
+  Connect new insights to previous state, flows, and invariants to maintain global coherence.
+
+---
+
+## 8. Subagent Usage
+
+Claude may spawn subagents for:
+- Dense or complex functions.
+- Long data-flow or control-flow chains.
+- Cryptographic / mathematical logic.
+- Complex state machines.
+- Multi-module workflow reconstruction.
+
+Use the **`function-analyzer`** agent for per-function deep analysis.
+It follows the full microstructure checklist, cross-function flow
+rules, and quality thresholds defined in this skill, and enforces
+the pure-context-building constraint.
+
+Subagents must:
+- Follow the same micro-first rules.
+- Return summaries that Claude integrates into its global model.
+
+---
+
+## 9. Relationship to Other Phases
+
+This skill runs **before**:
+- Vulnerability discovery
+- Classification / triage
+- Report writing
+- Impact modeling
+- Exploit reasoning
+
+It exists solely to build:
+- Deep understanding
+- Stable context
+- System-level clarity
+
+---
+
+## 10. Non-Goals
+
+While active, Claude should NOT:
+- Identify vulnerabilities
+- Propose fixes
+- Generate proofs-of-concept
+- Model exploits
+- Assign severity or impact
+
+This is **pure context building** only.

package/data/skills/trailofbits-differential-review/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: differential-review
+description: >
+  Performs security-focused differential review of code changes (PRs, commits, diffs).
+  Adapts analysis depth to codebase size, uses git history for context, calculates
+  blast radius, checks test coverage, and generates comprehensive markdown reports.
+  Automatically detects and prevents security regressions.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Differential Security Review
+
+Security-focused code review for PRs, commits, and diffs.
+
+## Core Principles
+
+1. **Risk-First**: Focus on auth, crypto, value transfer, external calls
+2. **Evidence-Based**: Every finding backed by git history, line numbers, attack scenarios
+3. **Adaptive**: Scale to codebase size (SMALL/MEDIUM/LARGE)
+4. **Honest**: Explicitly state coverage limits and confidence level
+5. **Output-Driven**: Always generate comprehensive markdown report file
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "Small PR, quick review" | Heartbleed was 2 lines | Classify by RISK, not size |
+| "I know this codebase" | Familiarity breeds blind spots | Build explicit baseline context |
+| "Git history takes too long" | History reveals regressions | Never skip Phase 1 |
+| "Blast radius is obvious" | You'll miss transitive callers | Calculate quantitatively |
+| "No tests = not my problem" | Missing tests = elevated risk rating | Flag in report, elevate severity |
+| "Just a refactor, no security impact" | Refactors break invariants | Analyze as HIGH until proven LOW |
+| "I'll explain verbally" | No artifact = findings lost | Always write report |
+
+---
+
+## Quick Reference
+
+### Codebase Size Strategy
+
+| Codebase Size | Strategy | Approach |
+|---------------|----------|----------|
+| SMALL (<20 files) | DEEP | Read all deps, full git blame |
+| MEDIUM (20-200) | FOCUSED | 1-hop deps, priority files |
+| LARGE (200+) | SURGICAL | Critical paths only |
+
+### Risk Level Triggers
+
+| Risk Level | Triggers |
+|------------|----------|
+| HIGH | Auth, crypto, external calls, value transfer, validation removal |
+| MEDIUM | Business logic, state changes, new public APIs |
+| LOW | Comments, tests, UI, logging |
+
+---
+
+## Workflow Overview
+
+```
+Pre-Analysis → Phase 0: Triage → Phase 1: Code Analysis → Phase 2: Test Coverage
+    ↓              ↓                    ↓                        ↓
+Phase 3: Blast Radius → Phase 4: Deep Context → Phase 5: Adversarial → Phase 6: Report
+```
+
+---
+
+## Decision Tree
+
+**Starting a review?**
+
+```
+├─ Need detailed phase-by-phase methodology?
+│  └─ Read: methodology.md
+│     (Pre-Analysis + Phases 0-4: triage, code analysis, test coverage, blast radius)
+│
+├─ Analyzing HIGH RISK change?
+│  └─ Read: adversarial.md
+│     (Phase 5: Attacker modeling, exploit scenarios, exploitability rating)
+│
+├─ Writing the final report?
+│  └─ Read: reporting.md
+│     (Phase 6: Report structure, templates, formatting guidelines)
+│
+├─ Looking for specific vulnerability patterns?
+│  └─ Read: patterns.md
+│     (Regressions, reentrancy, access control, overflow, etc.)
+│
+└─ Quick triage only?
+   └─ Use Quick Reference above, skip detailed docs
+```
+
+---
+
+## Quality Checklist
+
+Before delivering:
+
+- [ ] All changed files analyzed
+- [ ] Git blame on removed security code
+- [ ] Blast radius calculated for HIGH risk
+- [ ] Attack scenarios are concrete (not generic)
+- [ ] Findings reference specific line numbers + commits
+- [ ] Report file generated
+- [ ] User notified with summary
+
+---
+
+## Integration
+
+**audit-context-building skill:**
+- Pre-Analysis: Build baseline context
+- Phase 4: Deep context on HIGH RISK changes
+
+**issue-writer skill:**
+- Transform findings into formal audit reports
+- Command: `issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report`
+
+---
+
+## Example Usage
+
+### Quick Triage (Small PR)
+```
+Input: 5 file PR, 2 HIGH RISK files
+Strategy: Use Quick Reference
+1. Classify risk level per file (2 HIGH, 3 LOW)
+2. Focus on 2 HIGH files only
+3. Git blame removed code
+4. Generate minimal report
+Time: ~30 minutes
+```
+
+### Standard Review (Medium Codebase)
+```
+Input: 80 files, 12 HIGH RISK changes
+Strategy: FOCUSED (see methodology.md)
+1. Full workflow on HIGH RISK files
+2. Surface scan on MEDIUM
+3. Skip LOW risk files
+4. Complete report with all sections
+Time: ~3-4 hours
+```
+
+### Deep Audit (Large, Critical Change)
+```
+Input: 450 files, auth system rewrite
+Strategy: SURGICAL + audit-context-building
+1. Baseline context with audit-context-building
+2. Deep analysis on auth changes only
+3. Blast radius analysis
+4. Adversarial modeling
+5. Comprehensive report
+Time: ~6-8 hours
+```
+
+---
+
+## When NOT to Use This Skill
+
+- **Greenfield code** (no baseline to compare)
+- **Documentation-only changes** (no security impact)
+- **Formatting/linting** (cosmetic changes)
+- **User explicitly requests quick summary only** (they accept risk)
+
+For these cases, use standard code review instead.
+
+---
+
+## Red Flags (Stop and Investigate)
+
+**Immediate escalation triggers:**
+- Removed code from "security", "CVE", or "fix" commits
+- Access control modifiers removed (onlyOwner, internal → external)
+- Validation removed without replacement
+- External calls added without checks
+- High blast radius (50+ callers) + HIGH risk change
+
+These patterns require adversarial analysis even in quick triage.
+
+---
+
+## Tips for Best Results
+
+**Do:**
+- Start with git blame for removed code
+- Calculate blast radius early to prioritize
+- Generate concrete attack scenarios
+- Reference specific line numbers and commits
+- Be honest about coverage limitations
+- Always generate the output file
+
+**Don't:**
+- Skip git history analysis
+- Make generic findings without evidence
+- Claim full analysis when time-limited
+- Forget to check test coverage
+- Miss high blast radius changes
+- Output report only to chat (file required)
+
+---
+
+## Supporting Documentation
+
+- **[methodology.md](methodology.md)** - Detailed phase-by-phase workflow (Phases 0-4)
+- **[adversarial.md](adversarial.md)** - Attacker modeling and exploit scenarios (Phase 5)
+- **[reporting.md](reporting.md)** - Report structure and formatting (Phase 6)
+- **[patterns.md](patterns.md)** - Common vulnerability patterns reference
+
+---
+
+**For first-time users:** Start with [methodology.md](methodology.md) to understand the complete workflow.
+
+**For experienced users:** Use this page's Quick Reference and Decision Tree to navigate directly to needed content.

package/data/skills/trailofbits-insecure-defaults/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: insecure-defaults
+description: "Detects fail-open insecure defaults (hardcoded secrets, weak auth, permissive security) that allow apps to run insecurely in production. Use when auditing security, reviewing config management, or analyzing environment variable handling."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Insecure Defaults Detection
+
+Finds **fail-open** vulnerabilities where apps run insecurely with missing configuration. Distinguishes exploitable defaults from fail-secure patterns that crash safely.
+
+- **Fail-open (CRITICAL):** `SECRET = env.get('KEY') or 'default'` → App runs with weak secret
+- **Fail-secure (SAFE):** `SECRET = env['KEY']` → App crashes if missing
+
+## When to Use
+
+- **Security audits** of production applications (auth, crypto, API security)
+- **Configuration review** of deployment files, IaC templates, Docker configs
+- **Code review** of environment variable handling and secrets management
+- **Pre-deployment checks** for hardcoded credentials or weak defaults
+
+## When NOT to Use
+
+Do not use this skill for:
+- **Test fixtures** explicitly scoped to test environments (files in `test/`, `spec/`, `__tests__/`)
+- **Example/template files** (`.example`, `.template`, `.sample` suffixes)
+- **Development-only tools** (local Docker Compose for dev, debug scripts)
+- **Documentation examples** in README.md or docs/ directories
+- **Build-time configuration** that gets replaced during deployment
+- **Crash-on-missing behavior** where app won't start without proper config (fail-secure)
+
+When in doubt: trace the code path to determine if the app runs with the default or crashes.
+
+## Rationalizations to Reject
+
+- **"It's just a development default"** → If it reaches production code, it's a finding
+- **"The production config overrides it"** → Verify prod config exists; code-level vulnerability remains if not
+- **"This would never run without proper config"** → Prove it with code trace; many apps fail silently
+- **"It's behind authentication"** → Defense in depth; compromised session still exploits weak defaults
+- **"We'll fix it before release"** → Document now; "later" rarely comes
+
+## Workflow
+
+Follow this workflow for every potential finding:
+
+### 1. SEARCH: Perform Project Discovery and Find Insecure Defaults
+
+Determine language, framework, and project conventions. Use this information to further discover things like secret storage locations, secret usage patterns, credentialed third-party integrations, cryptography, and any other relevant configuration. Further use information to analyze insecure default configurations.
+
+**Example**
+Search for patterns in `**/config/`, `**/auth/`, `**/database/`, and env files:
+- **Fallback secrets:** `getenv.*\) or ['"]`, `process\.env\.[A-Z_]+ \|\| ['"]`, `ENV\.fetch.*default:`
+- **Hardcoded credentials:** `password.*=.*['"][^'"]{8,}['"]`, `api[_-]?key.*=.*['"][^'"]+['"]`
+- **Weak defaults:** `DEBUG.*=.*true`, `AUTH.*=.*false`, `CORS.*=.*\*`
+- **Crypto algorithms:** `MD5|SHA1|DES|RC4|ECB` in security contexts
+
+Tailor search approach based on discovery results.
+
+Focus on production-reachable code, not test fixtures or example files.
+
+### 2. VERIFY: Actual Behavior
+For each match, trace the code path to understand runtime behavior.
+
+**Questions to answer:**
+- When is this code executed? (Startup vs. runtime)
+- What happens if a configuration variable is missing?
+- Is there validation that enforces secure configuration?
+
+### 3. CONFIRM: Production Impact
+Determine if this issue reaches production:
+
+If production config provides the variable → Lower severity (but still a code-level vulnerability)
+If production config missing or uses default → CRITICAL
+
+### 4. REPORT: with Evidence
+
+**Example report:**
+```
+Finding: Hardcoded JWT Secret Fallback
+Location: src/auth/jwt.ts:15
+Pattern: const secret = process.env.JWT_SECRET || 'default';
+
+Verification: App starts without JWT_SECRET; secret used in jwt.sign() at line 42
+Production Impact: Dockerfile missing JWT_SECRET
+Exploitation: Attacker forges JWTs using 'default', gains unauthorized access
+```
+
+## Quick Verification Checklist
+
+**Fallback Secrets:** `SECRET = env.get(X) or Y`
+→ Verify: App starts without env var? Secret used in crypto/auth?
+→ Skip: Test fixtures, example files
+
+**Default Credentials:** Hardcoded `username`/`password` pairs
+→ Verify: Active in deployed config? No runtime override?
+→ Skip: Disabled accounts, documentation examples
+
+**Fail-Open Security:** `AUTH_REQUIRED = env.get(X, 'false')`
+→ Verify: Default is insecure (false/disabled/permissive)?
+→ Safe: App crashes or default is secure (true/enabled/restricted)
+
+**Weak Crypto:** MD5/SHA1/DES/RC4/ECB in security contexts
+→ Verify: Used for passwords, encryption, or tokens?
+→ Skip: Checksums, non-security hashing
+
+**Permissive Access:** CORS `*`, permissions `0777`, public-by-default
+→ Verify: Default allows unauthorized access?
+→ Skip: Explicitly configured permissiveness with justification
+
+**Debug Features:** Stack traces, introspection, verbose errors
+→ Verify: Enabled by default? Exposed in responses?
+→ Skip: Logging-only, not user-facing
+
+For detailed examples and counter-examples, see [examples.md](references/examples.md).