@elizaos/skills 2.0.0-alpha.3

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

@@ -0,0 +1,218 @@
+---
+name: code-maturity-assessor
+description: Systematic code maturity assessment using Trail of Bits' 9-category framework. Analyzes codebase for arithmetic safety, auditing practices, access controls, complexity, decentralization, documentation, MEV risks, low-level code, and testing. Produces professional scorecard with evidence-based ratings and actionable recommendations.
+---
+
+# Code Maturity Assessor
+
+## Purpose
+
+Systematically assesses codebase maturity using Trail of Bits' 9-category framework. Provides evidence-based ratings and actionable recommendations.
+
+**Framework**: Building Secure Contracts - Code Maturity Evaluation v0.1.0
+
+---
+
+## How This Works
+
+### Phase 1: Discovery
+Explores the codebase to understand:
+- Project structure and platform
+- Contract/module files
+- Test coverage
+- Documentation availability
+
+### Phase 2: Analysis
+For each of 9 categories, I'll:
+- **Search the code** for relevant patterns
+- **Read key files** to assess implementation
+- **Present findings** with file references
+- **Ask clarifying questions** about processes I can't see in code
+- **Determine rating** based on criteria
+
+### Phase 3: Report
+Generates:
+- Executive summary
+- Maturity scorecard (ratings for all 9 categories)
+- Detailed analysis with evidence
+- Priority-ordered improvement roadmap
+
+---
+
+## Rating System
+
+- **Missing (0)**: Not present/not implemented
+- **Weak (1)**: Several significant improvements needed
+- **Moderate (2)**: Adequate, can be improved
+- **Satisfactory (3)**: Above average, minor improvements
+- **Strong (4)**: Exceptional, only small improvements possible
+
+**Rating Logic**:
+- ANY "Weak" criteria → **Weak**
+- NO "Weak" + SOME "Moderate" unmet → **Moderate**
+- ALL "Moderate" + SOME "Satisfactory" met → **Satisfactory**
+- ALL "Satisfactory" + exceptional practices → **Strong**
+
+---
+
+## The 9 Categories
+
+I assess 9 comprehensive categories covering all aspects of code maturity. For detailed criteria, analysis approaches, and rating thresholds, see [ASSESSMENT_CRITERIA.md](resources/ASSESSMENT_CRITERIA.md).
+
+### Quick Reference:
+
+**1. ARITHMETIC**
+- Overflow protection mechanisms
+- Precision handling and rounding
+- Formula specifications
+- Edge case testing
+
+**2. AUDITING**
+- Event definitions and coverage
+- Monitoring infrastructure
+- Incident response planning
+
+**3. AUTHENTICATION / ACCESS CONTROLS**
+- Privilege management
+- Role separation
+- Access control testing
+- Key compromise scenarios
+
+**4. COMPLEXITY MANAGEMENT**
+- Function scope and clarity
+- Cyclomatic complexity
+- Inheritance hierarchies
+- Code duplication
+
+**5. DECENTRALIZATION**
+- Centralization risks
+- Upgrade control mechanisms
+- User opt-out paths
+- Timelock/multisig patterns
+
+**6. DOCUMENTATION**
+- Specifications and architecture
+- Inline code documentation
+- User stories
+- Domain glossaries
+
+**7. TRANSACTION ORDERING RISKS**
+- MEV vulnerabilities
+- Front-running protections
+- Slippage controls
+- Oracle security
+
+**8. LOW-LEVEL MANIPULATION**
+- Assembly usage
+- Unsafe code sections
+- Low-level calls
+- Justification and testing
+
+**9. TESTING & VERIFICATION**
+- Test coverage
+- Fuzzing and formal verification
+- CI/CD integration
+- Test quality
+
+For complete assessment criteria including what I'll analyze, what I'll ask you, and detailed rating thresholds (WEAK/MODERATE/SATISFACTORY/STRONG), see [ASSESSMENT_CRITERIA.md](resources/ASSESSMENT_CRITERIA.md).
+
+---
+
+## Example Output
+
+When the assessment is complete, you'll receive a comprehensive maturity report including:
+
+- **Executive Summary**: Overall score, top 3 strengths, top 3 gaps, priority recommendations
+- **Maturity Scorecard**: Table with all 9 categories rated with scores and notes
+- **Detailed Analysis**: Category-by-category breakdown with evidence (file:line references)
+- **Improvement Roadmap**: Priority-ordered recommendations (CRITICAL/HIGH/MEDIUM) with effort estimates
+
+For a complete example assessment report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).
+
+---
+
+## Assessment Process
+
+When invoked, I will:
+
+1. **Explore codebase**
+   - Find contract/module files
+   - Identify test files
+   - Locate documentation
+
+2. **Analyze each category**
+   - Search for relevant code patterns
+   - Read key implementations
+   - Assess against criteria
+   - Collect evidence
+
+3. **Interactive assessment**
+   - Present my findings with file references
+   - Ask about processes I can't see in code
+   - Discuss borderline cases
+   - Determine ratings together
+
+4. **Generate report**
+   - Executive summary
+   - Maturity scorecard table
+   - Detailed category analysis with evidence
+   - Priority-ordered improvement roadmap
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "Found some findings, assessment complete" | Assessment requires evaluating ALL 9 categories | Complete assessment of all 9 categories with evidence for each |
+| "I see events, auditing category looks good" | Events alone don't equal auditing maturity | Check logging comprehensiveness, testing, incident response processes |
+| "Code looks simple, complexity is low" | Visual simplicity masks composition complexity | Analyze cyclomatic complexity, dependency depth, state machine transitions |
+| "Not a DeFi protocol, MEV category doesn't apply" | MEV extends beyond DeFi (governance, NFTs, games) | Verify with transaction ordering analysis before declaring N/A |
+| "No assembly found, low-level category is N/A" | Low-level risks include external calls, delegatecall, inline assembly | Search for all low-level patterns before skipping category |
+| "This is taking too long" | Thorough assessment requires time per category | Complete all 9 categories, ask clarifying questions about off-chain processes |
+| "I can rate this without evidence" | Ratings without file:line references = unsubstantiated claims | Collect concrete code evidence for every category assessment |
+| "User will know what to improve" | Vague guidance = no action | Provide priority-ordered roadmap with specific improvements and effort estimates |
+
+---
+
+## Report Format
+
+For detailed report structure and templates, see [REPORT_FORMAT.md](resources/REPORT_FORMAT.md).
+
+### Structure:
+
+1. **Executive Summary**
+   - Project name and platform
+   - Overall maturity (average rating)
+   - Top 3 strengths
+   - Top 3 critical gaps
+   - Priority recommendations
+
+2. **Maturity Scorecard**
+   - Table with all 9 categories
+   - Ratings and scores
+   - Key findings notes
+
+3. **Detailed Analysis**
+   - Per-category breakdown
+   - Evidence with file:line references
+   - Gaps and improvement actions
+
+4. **Improvement Roadmap**
+   - CRITICAL (immediate)
+   - HIGH (1-2 months)
+   - MEDIUM (2-4 months)
+   - Effort estimates and impact
+
+---
+
+## Ready to Begin
+
+**Estimated Time**: 30-40 minutes
+
+**I'll need**:
+- Access to full codebase
+- Your knowledge of processes (monitoring, incident response, team practices)
+- Context about the project (DeFi, NFT, infrastructure, etc.)
+
+Let's assess this codebase!

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

@@ -0,0 +1,355 @@
+## The 9 Categories
+
+### 1. ARITHMETIC
+**Focus**: Overflow protection, precision handling, formula specification, edge case testing
+
+**I'll analyze**:
+- Overflow protection mechanisms (Solidity 0.8, SafeMath, checked_*, saturating_*)
+- Unchecked arithmetic blocks and documentation
+- Division/rounding operations
+- Arithmetic in critical functions (balances, rewards, fees)
+- Test coverage for arithmetic edge cases
+- Arithmetic specification documents
+
+**WEAK if**:
+- No overflow protection without justification
+- Unchecked arithmetic not documented
+- No arithmetic specification OR spec doesn't match code
+- No testing strategy for arithmetic
+- Critical edge cases not tested
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Unchecked arithmetic minimal, justified, documented
+- Overflow/underflow risks documented and tested
+- Explicit rounding for precision loss
+- Automated testing (fuzzing/formal methods)
+- Stateless arithmetic functions
+- Bounded parameters with explained ranges
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- Precision loss analyzed vs ground-truth
+- All trapping operations identified
+- Arithmetic spec matches code one-to-one
+- Automated testing covers all operations in CI
+
+---
+
+### 2. AUDITING
+**Focus**: Events, monitoring systems, incident response
+
+**I'll analyze**:
+- Event definitions and emission patterns
+- Events for critical operations (transfers, access changes, parameter updates)
+- Event naming consistency
+- Critical functions without events
+
+**I'll ask you**:
+- Off-chain monitoring infrastructure?
+- Monitoring plan documented?
+- Incident response plan exists and tested?
+
+**WEAK if**:
+- No event strategy
+- Events missing for critical updates
+- No consistent event guidelines
+- Same events reused for different purposes
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Events for all critical functions
+- Off-chain monitoring logs events
+- Monitoring plan documented
+- Event documentation (purpose, usage, assumptions)
+- Log review process documented
+- Incident response plan exists
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- Monitoring triggers alerts on unexpected behavior
+- Defined roles for incident detection
+- Incident response plan regularly tested
+
+---
+
+### 3. AUTHENTICATION / ACCESS CONTROLS
+**Focus**: Privilege management, role separation, access patterns
+
+**I'll analyze**:
+- Access control modifiers/functions
+- Role definitions and separation
+- Admin/owner patterns
+- Privileged function implementations
+- Test coverage for access controls
+
+**I'll ask you**:
+- Who are privileged actors? (EOA, multisig, DAO?)
+- Documentation of roles and privileges?
+- Key compromise scenarios?
+
+**WEAK if**:
+- Access controls unclear or inconsistent
+- Single address controls system without safeguards
+- Missing access controls on privileged functions
+- No role differentiation
+- All privileges on one address
+
+**MODERATE requires**:
+- All weak criteria resolved
+- All privileged functions have access control
+- Least privilege principle followed
+- Non-overlapping role privileges
+- Clear actor/privilege documentation
+- Tests cover all privileges
+- Roles can be revoked
+- Two-step processes for EOA operations
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- All actors well documented
+- Implementation matches specification
+- Privileged actors not EOAs
+- Key leakage doesn't compromise system
+- Tested against known attack vectors
+
+---
+
+### 4. COMPLEXITY MANAGEMENT
+**Focus**: Code clarity, function scope, avoiding unnecessary complexity
+
+**I'll analyze**:
+- Function length and nesting depth
+- Cyclomatic complexity
+- Code duplication
+- Inheritance hierarchies
+- Naming conventions
+- Function clarity
+
+**I'll ask you**:
+- Complex parts documented?
+- Naming convention documented?
+- Complexity measurements?
+
+**WEAK if**:
+- Unnecessary complexity hinders review
+- Functions overuse nested operations
+- Functions have unclear scope
+- Unnecessary code duplication
+- Complex inheritance tree
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Complex parts identified, minimized
+- High complexity (≥11) justified
+- Critical functions well-scoped
+- Minimal, justified redundancy
+- Clear inputs with validation
+- Documented naming convention
+- Types not misused
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- Minimal unnecessary complexity
+- Necessary complexity documented
+- Clear function purposes
+- Straightforward to test
+- No redundant behavior
+
+---
+
+### 5. DECENTRALIZATION
+**Focus**: Centralization risks, upgrade control, user opt-out
+
+**I'll analyze**:
+- Upgrade mechanisms (proxies, governance)
+- Owner/admin control scope
+- Timelock/multisig patterns
+- User opt-out mechanisms
+
+**I'll ask you**:
+- Upgrade mechanism and control?
+- User opt-out/exit paths?
+- Centralization risk documentation?
+
+**WEAK if**:
+- Centralization points not visible to users
+- Critical functions upgradable by single entity without opt-out
+- Single entity controls user funds
+- All decisions by single entity
+- Parameters changeable anytime by single entity
+- Centralized permission required
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Centralization risks identified, justified, documented
+- User opt-out/exit path documented
+- Upgradeability only for non-critical features
+- Privileged actors can't unilaterally move/trap funds
+- All privileges documented
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- Clear decentralization path justified
+- On-chain voting risks addressed OR no centralization
+- Deployment risks documented
+- External interaction risks documented
+- Critical parameters immutable OR users can exit
+
+---
+
+### 6. DOCUMENTATION
+**Focus**: Specifications, architecture, user stories, inline comments
+
+**I'll analyze**:
+- README, specification, architecture docs
+- Inline code comments (NatSpec, rustdoc, etc.)
+- User stories
+- Glossaries
+- Documentation completeness and accuracy
+
+**I'll ask you**:
+- User stories documented?
+- Architecture diagrams exist?
+- Glossary for domain terms?
+
+**WEAK if**:
+- Minimal or incomplete/outdated documentation
+- Only high-level description
+- Code comments don't match docs
+- Not publicly available (for public codebases)
+- Unexplained artificial terms
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Clear, unambiguous writing
+- Glossary for business terms
+- Architecture diagrams
+- User stories included
+- Core/critical components identified
+- Docs sufficient to understand behavior
+- All critical functions/blocks documented
+- Known risks/limitations documented
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- User stories cover all operations
+- Detailed behavior descriptions
+- Implementation matches spec (deviations justified)
+- Invariants clearly defined
+- Consistent naming conventions
+- Documentation for end-users AND developers
+
+---
+
+### 7. TRANSACTION ORDERING RISKS
+**Focus**: MEV, front-running, sandwich attacks
+
+**I'll analyze**:
+- MEV-vulnerable patterns (AMM swaps, arbitrage, large trades)
+- Front-running protections
+- Slippage/deadline checks
+- Oracle implementations
+
+**I'll ask you**:
+- Transaction ordering risks identified/documented?
+- Known MEV opportunities?
+- Mitigation strategies?
+- Testing for ordering attacks?
+
+**WEAK if**:
+- Ordering risks not identified/documented
+- Protocols/assets at risk from unexpected ordering
+- Relies on unjustified MEV prevention constraints
+- Unproven assumptions about MEV extractors
+
+**MODERATE requires**:
+- All weak criteria resolved
+- User operation ordering risks limited, justified, documented
+- MEV mitigations in place (delays, slippage checks)
+- Testing emphasizes ordering risks
+- Tamper-resistant oracles used
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- All ordering risks documented and justified
+- Known risks highlighted in docs/tests, visible to users
+- Documentation centralizes MEV opportunities
+- Privileged operation ordering risks limited, justified
+- Tests highlight ordering risks
+
+---
+
+### 8. LOW-LEVEL MANIPULATION
+**Focus**: Assembly, unsafe code, low-level operations
+
+**I'll analyze**:
+- Assembly blocks
+- Unsafe code sections
+- Low-level calls
+- Bitwise operations
+- Justification and documentation
+
+**I'll ask you**:
+- Why use assembly/unsafe here?
+- High-level reference implementation?
+- How is this tested?
+
+**WEAK if**:
+- Unjustified low-level manipulations
+- Assembly/low-level not justified, could be high-level
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Assembly use limited and justified
+- Inline comments for each operation
+- No re-implementation of established libraries without justification
+- High-level reference for complex assembly
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- Thorough documentation/justification/testing
+- Validated with automated testing vs reference
+- Differential fuzzing compares implementations
+- Compiler optimization risks identified
+
+---
+
+### 9. TESTING AND VERIFICATION
+**Focus**: Coverage, testing techniques, CI/CD
+
+**I'll analyze**:
+- Test file count and organization
+- Test coverage reports
+- CI/CD configuration
+- Advanced testing (fuzzing, formal verification)
+- Test quality and isolation
+
+**I'll ask you**:
+- Test coverage percentage?
+- Do all tests pass?
+- Testing techniques used?
+- Easy to run tests?
+
+**WEAK if**:
+- Limited testing, only happy paths
+- Common use cases not tested
+- Tests fail
+- Can't run tests "out of the box"
+
+**MODERATE requires**:
+- All weak criteria resolved
+- Most functions/use cases tested
+- All tests pass
+- Coverage reports available
+- Automated testing for critical components
+- Tests in CI/CD
+- Integration tests (if applicable)
+- Test code follows best practices
+
+**SATISFACTORY requires**:
+- All moderate criteria met
+- 100% reachable branch/statement coverage
+- End-to-end testing covers all entry points
+- Isolated test cases (no dependencies)
+- Mutation testing used