@elizaos/skills 2.0.0-alpha.3

package/skills/security-building-secure-contracts/skills/code-maturity-assessor/resources/EXAMPLE_REPORT.md

@@ -0,0 +1,248 @@
+## Example Output
+
+When the assessment is complete, you'll receive a comprehensive maturity report:
+
+```
+=== CODE MATURITY ASSESSMENT REPORT ===
+
+Project: DeFi DEX Protocol
+Platform: Solidity (Ethereum)
+Assessment Date: March 15, 2024
+Assessor: Trail of Bits Code Maturity Framework v0.1.0
+
+---
+
+## EXECUTIVE SUMMARY
+
+Overall Maturity Score: 2.7 / 4.0 (MODERATE-SATISFACTORY)
+
+Top 3 Strengths:
+✓ Comprehensive testing with 96% coverage and fuzzing
+✓ Well-documented access controls with multi-sig governance
+✓ Clear architectural documentation with diagrams
+
+Top 3 Critical Gaps:
+⚠ Arithmetic operations lack formal specification
+⚠ No event monitoring infrastructure deployed
+⚠ Centralized upgrade mechanism without timelock
+
+Priority Recommendation:
+Implement arithmetic specification document and add 48-hour timelock
+to all governance operations before mainnet launch.
+
+---
+
+## MATURITY SCORECARD
+
+| Category                    | Rating        | Score | Notes                           |
+|-----------------------------|---------------|-------|---------------------------------|
+| 1. Arithmetic               | WEAK          | 1/4   | Missing specification           |
+| 2. Auditing                 | MODERATE      | 2/4   | Events present, no monitoring   |
+| 3. Authentication/Access    | SATISFACTORY  | 3/4   | Multi-sig, well-documented      |
+| 4. Complexity Management    | MODERATE      | 2/4   | Some functions too complex      |
+| 5. Decentralization         | WEAK          | 1/4   | Centralized upgrades            |
+| 6. Documentation            | SATISFACTORY  | 3/4   | Comprehensive, minor gaps       |
+| 7. Transaction Ordering     | MODERATE      | 2/4   | Some MEV risks documented       |
+| 8. Low-Level Manipulation   | SATISFACTORY  | 3/4   | Minimal assembly, justified     |
+| 9. Testing & Verification   | STRONG        | 4/4   | Excellent coverage & techniques |
+
+**OVERALL: 2.7 / 4.0** (Moderate-Satisfactory)
+
+---
+
+## DETAILED ANALYSIS
+
+### 1. ARITHMETIC - WEAK (1/4)
+
+**Evidence:**
+✗ No arithmetic specification document found
+✗ AMM pricing formula not documented (src/SwapRouter.sol:89-156)
+✗ Slippage calculation lacks precision analysis
+✓ Using Solidity 0.8+ for overflow protection
+✓ Critical functions tested for edge cases
+
+**Critical Gap:**
+File: src/SwapRouter.sol:127
+```solidity
+uint256 amountOut = (reserveOut * amountIn * 997) / (reserveIn * 1000 + amountIn * 997);
+```
+No specification for:
+- Expected liquidity depth ranges
+- Precision loss analysis
+- Rounding direction justification
+
+**To Reach Moderate (2/4):**
+- Create arithmetic specification document
+- Document all formulas and their precision requirements
+- Add explicit rounding direction comments
+- Test arithmetic edge cases with fuzzing
+
+**Files Referenced:**
+- src/SwapRouter.sol:89-156
+- src/LiquidityPool.sol:234-267
+- src/PriceCalculator.sol:178-195
+
+---
+
+### 2. AUDITING - MODERATE (2/4)
+
+**Evidence:**
+✓ Events emitted for all critical operations
+✓ Consistent event naming (Action + noun)
+✓ Indexed parameters for filtering
+✗ No off-chain monitoring infrastructure
+✗ No monitoring plan documented
+✗ No incident response plan
+
+**Events Found:** 23 events across 8 contracts
+- Swap, AddLiquidity, RemoveLiquidity ✓
+- PairCreated, LiquidityProvided ✓
+- OwnershipTransferred, GovernanceProposed ✓
+
+**Critical Gap:**
+No monitoring alerts for:
+- Large swaps causing significant price impact
+- Oracle price deviations
+- Unusual liquidity withdrawal patterns
+
+**To Reach Satisfactory (3/4):**
+- Deploy off-chain monitoring (Tenderly/Defender)
+- Create monitoring playbook document
+- Set up alerts for critical events
+- Test incident response plan quarterly
+
+---
+
+### 3. AUTHENTICATION/ACCESS CONTROLS - SATISFACTORY (3/4)
+
+**Evidence:**
+✓ All privileged functions have access controls
+✓ Multi-sig (3/5) controls governance
+✓ Role separation (Admin, Operator, Pauser)
+✓ Roles documented in ROLES.md
+✓ Two-step ownership transfer
+✓ All access patterns tested
+✓ Emergency pause by separate role
+
+**Access Control Implementation:**
+- OpenZeppelin AccessControl used consistently
+- 4 roles defined with non-overlapping privileges
+- Emergency functions require multi-sig
+
+**Minor Gap:**
+Multi-sig is EOA-based (should upgrade to Governor contract)
+
+**To Reach Strong (4/4):**
+- Replace multi-sig EOAs with on-chain Governor
+- Add timelock to all parameter changes
+- Document key compromise scenarios
+- Test governor upgrade path
+
+**Files Referenced:**
+- All contracts use consistent access patterns
+- ROLES.md comprehensive
+- test/access/* covers all scenarios
+
+---
+
+### 9. TESTING & VERIFICATION - STRONG (4/4)
+
+**Evidence:**
+✓ 96% line coverage, 94% branch coverage
+✓ 287 unit tests, all passing
+✓ Echidna fuzzing for 12 invariants
+✓ Integration tests for all workflows
+✓ Mutation testing implemented
+✓ Tests run in CI/CD
+✓ Fork tests against mainnet state
+
+**Testing Breakdown:**
+- Unit: 287 tests (forge test)
+- Integration: 45 scenarios (end-to-end flows)
+- Fuzzing: 12 invariants (Echidna, 10k runs each)
+- Formal: 3 key properties (Certora)
+- Fork: Tested against live Uniswap/SushiSwap
+
+**Uncovered Code:**
+- Emergency migration (tested manually)
+- Governance upgrade path (one-time)
+
+**Why Strong:**
+Exceeds all satisfactory criteria with formal verification and
+extensive fuzzing. Test quality is exceptional.
+
+---
+
+## IMPROVEMENT ROADMAP
+
+### CRITICAL (Fix Before Mainnet - Week 1-2)
+
+**1. Create Arithmetic Specification [HIGH IMPACT]**
+- Effort: 3-5 days
+- Document all formulas with ground-truth models
+- Analyze precision loss for each operation
+- Justify rounding directions
+- Impact: Moves Arithmetic from WEAK → MODERATE
+
+**2. Add Governance Timelock [HIGH IMPACT]**
+- Effort: 2-3 days
+- Deploy TimelockController (48-hour delay)
+- Update all governance functions
+- Document emergency override procedure
+- Impact: Moves Decentralization from WEAK → MODERATE
+
+---
+
+### HIGH PRIORITY (Fix Before Launch - Week 3-4)
+
+**3. Deploy Monitoring Infrastructure [MEDIUM IMPACT]**
+- Effort: 3-4 days
+- Set up Tenderly/OpenZeppelin Defender
+- Create alert rules for critical events
+- Document monitoring playbook
+- Impact: Moves Auditing from MODERATE → SATISFACTORY
+
+**4. Simplify Complex Functions [MEDIUM IMPACT]**
+- Effort: 5-7 days
+- Split SwapRouter.getAmountOut() (cyclomatic complexity: 15)
+- Extract PriceCalculator._validateSlippage() logic
+- Impact: Moves Complexity from MODERATE → SATISFACTORY
+
+---
+
+### MEDIUM PRIORITY (Improve for V2 - Month 2-3)
+
+**5. Document MEV Risks**
+- Effort: 2-3 days
+- Create MEV analysis document
+- Add slippage protection where missing
+- Impact: Moves Transaction Ordering from MODERATE → SATISFACTORY
+
+**6. Upgrade to On-Chain Governance**
+- Effort: 1-2 weeks
+- Replace multi-sig with Governor contract
+- Add voting period and quorum
+- Impact: Moves Authentication from SATISFACTORY → STRONG
+
+---
+
+## CONCLUSION
+
+The codebase demonstrates **MODERATE-SATISFACTORY maturity** (2.7/4.0),
+with excellent testing practices and good documentation. Primary concerns
+are arithmetic specification gaps and centralized upgrade control.
+
+**Recommended Path to Mainnet:**
+1. Complete CRITICAL items (arithmetic spec, timelock)
+2. Address HIGH priority items (monitoring, complexity)
+3. Conduct external audit
+4. Launch with documented limitations
+5. Implement MEDIUM priority items in V2
+
+**Timeline:** 3-4 weeks to address critical/high items before audit.
+
+---
+
+Assessment completed using Trail of Bits Building Secure Contracts
+Code Maturity Evaluation Framework v0.1.0
+```

package/skills/security-building-secure-contracts/skills/code-maturity-assessor/resources/REPORT_FORMAT.md

@@ -0,0 +1,33 @@
+
+## Report Format
+
+### Executive Summary
+- Project name and platform
+- Overall maturity (average rating)
+- Top 3 strengths
+- Top 3 critical gaps
+- Priority recommendations
+
+### Maturity Scorecard
+| Category | Rating | Notes |
+|----------|--------|-------|
+| Arithmetic | [Rating] | [Key findings] |
+| Auditing | [Rating] | [Key findings] |
+| ... | ... | ... |
+
+**Overall**: [X.X / 4.0]
+
+### Detailed Analysis
+For each category:
+- Rating with justification
+- Evidence from codebase (file:line references)
+- Gaps identified
+- Actions to reach next level
+
+### Improvement Roadmap
+Priority-ordered recommendations:
+- **CRITICAL** (immediate)
+- **HIGH** (1-2 months)
+- **MEDIUM** (2-4 months)
+
+Each with effort estimate and impact

package/skills/security-building-secure-contracts/skills/cosmos-vulnerability-scanner/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: cosmos-vulnerability-scanner
+description: Scans Cosmos SDK blockchains for 9 consensus-critical vulnerabilities including non-determinism, incorrect signers, ABCI panics, and rounding errors. Use when auditing Cosmos chains or CosmWasm contracts.
+---
+
+# Cosmos Vulnerability Scanner
+
+## 1. Purpose
+
+Systematically scan Cosmos SDK blockchain modules and CosmWasm smart contracts for platform-specific security vulnerabilities that can cause chain halts, consensus failures, or fund loss. This skill encodes 9 critical vulnerability patterns unique to Cosmos-based chains.
+
+## 2. When to Use This Skill
+
+- Auditing Cosmos SDK modules (custom x/ modules)
+- Reviewing CosmWasm smart contracts (Rust)
+- Pre-launch security assessment of Cosmos chains
+- Investigating chain halt incidents
+- Validating consensus-critical code changes
+- Reviewing ABCI method implementations
+
+## 3. Platform Detection
+
+### File Extensions & Indicators
+- **Go files**: `.go`, `.proto`
+- **CosmWasm**: `.rs` (Rust with cosmwasm imports)
+
+### Language/Framework Markers
+```go
+// Cosmos SDK indicators
+import (
+    "github.com/cosmos/cosmos-sdk/types"
+    sdk "github.com/cosmos/cosmos-sdk/types"
+    "github.com/cosmos/cosmos-sdk/x/..."
+)
+
+// Common patterns
+keeper.Keeper
+sdk.Msg, GetSigners()
+BeginBlocker, EndBlocker
+CheckTx, DeliverTx
+protobuf service definitions
+```
+
+```rust
+// CosmWasm indicators
+use cosmwasm_std::*;
+#[entry_point]
+pub fn execute(deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg)
+```
+
+### Project Structure
+- `x/modulename/` - Custom modules
+- `keeper/keeper.go` - State management
+- `types/msgs.go` - Message definitions
+- `abci.go` - BeginBlocker/EndBlocker
+- `handler.go` - Message handlers (legacy)
+
+### Tool Support
+- **CodeQL**: Custom rules for non-determinism and panics
+- **go vet**, **golangci-lint**: Basic Go static analysis
+- **Manual review**: Critical for consensus issues
+
+---
+
+## 4. How This Skill Works
+
+When invoked, I will:
+
+1. **Search your codebase** for Cosmos SDK modules
+2. **Analyze each module** for the 9 vulnerability patterns
+3. **Report findings** with file references and severity
+4. **Provide fixes** for each identified issue
+5. **Check message handlers** for validation issues
+
+---
+
+## 5. Example Output
+
+When vulnerabilities are found, you'll get a report like this:
+
+```
+=== COSMOS SDK VULNERABILITY SCAN RESULTS ===
+
+Project: my-cosmos-chain
+Files Scanned: 6 (.go)
+Vulnerabilities Found: 2
+
+---
+
+[CRITICAL] Incorrect GetSigners()
+
+---
+
+## 5. Vulnerability Patterns (9 Patterns)
+
+I check for 9 critical vulnerability patterns unique to CosmWasm. For detailed detection patterns, code examples, mitigations, and testing strategies, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).
+
+### Pattern Summary:
+
+1. **Missing Denom Validation** ⚠️ CRITICAL - Accepting arbitrary token denoms
+2. **Insufficient Authorization** ⚠️ CRITICAL - Missing sender/admin validation
+3. **Missing Balance Check** ⚠️ HIGH - Not verifying sufficient balances
+4. **Improper Reply Handling** ⚠️ HIGH - Unsafe submessage reply processing
+5. **Missing Reply ID Check** ⚠️ MEDIUM - Not validating reply IDs
+6. **Improper IBC Packet Validation** ⚠️ CRITICAL - Unvalidated IBC packets
+7. **Unvalidated Execute Message** ⚠️ HIGH - Missing message validation
+8. **Integer Overflow** ⚠️ HIGH - Unchecked arithmetic operations
+9. **Reentrancy via Submessages** ⚠️ MEDIUM - State changes before submessages
+
+For complete vulnerability patterns with code examples, see [VULNERABILITY_PATTERNS.md](resources/VULNERABILITY_PATTERNS.md).
+## 5. Scanning Workflow
+
+### Step 1: Platform Identification
+1. Identify Cosmos SDK version (`go.mod`)
+2. Locate custom modules (`x/*/`)
+3. Find ABCI methods (`abci.go`, BeginBlocker, EndBlocker)
+4. Identify message types (`types/msgs.go`, `.proto`)
+
+### Step 2: Critical Path Analysis
+Focus on consensus-critical code:
+- BeginBlocker / EndBlocker implementations
+- Message handlers (execute, DeliverTx)
+- Keeper methods that modify state
+- CheckTx priority logic
+
+### Step 3: Non-Determinism Sweep
+**This is the highest priority check for Cosmos chains.**
+
+```bash
+# Search for non-deterministic patterns
+grep -r "range.*map\[" x/
+grep -r "\bint\b\|\buint\b" x/ | grep -v "int32\|int64\|uint32\|uint64"
+grep -r "float32\|float64" x/
+grep -r "go func\|go routine" x/
+grep -r "select {" x/
+grep -r "time.Now()" x/
+grep -r "rand\." x/
+```
+
+For each finding:
+1. Verify it's in consensus-critical path
+2. Confirm it causes non-determinism
+3. Assess severity (chain halt vs data inconsistency)
+
+### Step 4: ABCI Method Analysis
+Review BeginBlocker and EndBlocker:
+- [ ] Computational complexity bounded?
+- [ ] No unbounded iterations?
+- [ ] No nested loops over large collections?
+- [ ] Panic-prone operations validated?
+- [ ] Benchmarked with maximum state?
+
+### Step 5: Message Validation
+For each message type:
+- [ ] GetSigners() address matches handler usage?
+- [ ] All error returns checked?
+- [ ] Priority set in CheckTx if critical?
+- [ ] Handler registered (or using v0.47+ auto-registration)?
+
+### Step 6: Arithmetic & Bookkeeping
+- [ ] sdk.Dec operations use multiply-before-divide?
+- [ ] Rounding favors protocol over users?
+- [ ] Custom bookkeeping synchronized with x/bank?
+- [ ] Invariant checks in place?
+
+---
+
+## 6. Reporting Format
+
+### Finding Template
+```markdown
+## [CRITICAL] Non-Deterministic Map Iteration in EndBlocker
+
+**Location**: `x/dex/abci.go:45-52`
+
+**Description**:
+The EndBlocker iterates over an unordered map to distribute rewards, causing different validators to process users in different orders and produce different state roots. This will halt the chain when validators fail to reach consensus.
+
+**Vulnerable Code**:
+```go
+// abci.go, line 45
+func EndBlocker(ctx sdk.Context, k keeper.Keeper) {
+    rewards := k.GetPendingRewards(ctx)  // Returns map[string]sdk.Coins
+    for user, amount := range rewards {  // NON-DETERMINISTIC ORDER
+        k.bankKeeper.SendCoins(ctx, moduleAcc, user, amount)
+    }
+}
+```
+
+**Attack Scenario**:
+1. Multiple users have pending rewards
+2. Different validators iterate in different orders due to map randomization
+3. If any reward distribution fails mid-iteration, state diverges
+4. Validators produce different app hashes
+5. Chain halts - cannot reach consensus
+
+**Recommendation**:
+Sort map keys before iteration:
+```go
+func EndBlocker(ctx sdk.Context, k keeper.Keeper) {
+    rewards := k.GetPendingRewards(ctx)
+
+    // Collect and sort keys for deterministic iteration
+    users := make([]string, 0, len(rewards))
+    for user := range rewards {
+        users = append(users, user)
+    }
+    sort.Strings(users)  // Deterministic order
+
+    // Process in sorted order
+    for _, user := range users {
+        k.bankKeeper.SendCoins(ctx, moduleAcc, user, rewards[user])
+    }
+}
+```
+
+**References**:
+- building-secure-contracts/not-so-smart-contracts/cosmos/non_determinism
+- Cosmos SDK docs: Determinism
+```
+
+---
+
+## 7. Priority Guidelines
+
+### Critical - CHAIN HALT Risk
+- Non-determinism (any form)
+- ABCI method panics
+- Slow ABCI methods
+- Incorrect GetSigners (allows unauthorized actions)
+
+### High - Fund Loss Risk
+- Missing error handling (bankKeeper.SendCoins)
+- Broken bookkeeping (accounting mismatch)
+- Missing message priority (oracle/emergency messages)
+
+### Medium - Logic/DoS Risk
+- Rounding errors (protocol value leakage)
+- Unregistered message handlers (functionality broken)
+
+---
+
+## 8. Testing Recommendations
+
+### Non-Determinism Testing
+```bash
+# Build for different architectures
+GOARCH=amd64 go build
+GOARCH=arm64 go build
+
+# Run same operations, compare state roots
+# Must be identical across architectures
+
+# Fuzz test with concurrent operations
+go test -fuzz=FuzzEndBlocker -parallel=10
+```
+
+### ABCI Benchmarking
+```go
+func BenchmarkBeginBlocker(b *testing.B) {
+    ctx := setupMaximalState()  // Worst-case state
+    b.ResetTimer()
+
+    for i := 0; i < b.N; i++ {
+        BeginBlocker(ctx, keeper)
+    }
+
+    // Must complete in < 1 second
+    require.Less(b, b.Elapsed()/time.Duration(b.N), time.Second)
+}
+```
+
+### Invariant Testing
+```go
+// Run invariants in integration tests
+func TestInvariants(t *testing.T) {
+    app := setupApp()
+
+    // Execute operations
+    app.DeliverTx(...)
+
+    // Check invariants
+    _, broken := keeper.AllInvariants()(app.Ctx)
+    require.False(t, broken, "invariant violation detected")
+}
+```
+
+---
+
+## 9. Additional Resources
+
+- **Building Secure Contracts**: `building-secure-contracts/not-so-smart-contracts/cosmos/`
+- **Cosmos SDK Docs**: https://docs.cosmos.network/
+- **CodeQL for Go**: https://codeql.github.com/docs/codeql-language-guides/codeql-for-go/
+- **Cosmos Security Best Practices**: https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/learn/advanced/17-determinism.md
+
+---
+
+## 10. Quick Reference Checklist
+
+Before completing Cosmos chain audit:
+
+**Non-Determinism (CRITICAL)**:
+- [ ] No map iteration in consensus code
+- [ ] No platform-dependent types (int, uint, float)
+- [ ] No goroutines in message handlers/ABCI
+- [ ] No select statements with multiple channels
+- [ ] No rand, time.Now(), memory addresses
+- [ ] All serialization is deterministic
+
+**ABCI Methods (CRITICAL)**:
+- [ ] BeginBlocker/EndBlocker computationally bounded
+- [ ] No unbounded iterations
+- [ ] No nested loops over large collections
+- [ ] All panic-prone operations validated
+- [ ] Benchmarked with maximum state
+
+**Message Handling (HIGH)**:
+- [ ] GetSigners() matches handler address usage
+- [ ] All error returns checked
+- [ ] Critical messages prioritized in CheckTx
+- [ ] All message types registered
+
+**Arithmetic & Accounting (MEDIUM)**:
+- [ ] Multiply before divide pattern used
+- [ ] Rounding favors protocol
+- [ ] Custom bookkeeping synced with x/bank
+- [ ] Invariant checks implemented
+
+**Testing**:
+- [ ] Cross-architecture builds tested
+- [ ] ABCI methods benchmarked
+- [ ] Invariants checked in CI
+- [ ] Integration tests cover all messages