219 lines
6.9 KiB
Markdown
219 lines
6.9 KiB
Markdown
---
|
|
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!
|