@elizaos/skills 2.0.0-alpha.3

package/skills/security-building-secure-contracts/skills/guidelines-advisor/resources/EXAMPLE_REPORT.md

@@ -0,0 +1,298 @@
+## Example Output
+
+When the analysis is complete, you'll receive comprehensive guidance like this:
+
+```
+=== DEVELOPMENT GUIDELINES ANALYSIS ===
+
+Project: NFT Marketplace
+Platform: Solidity (Ethereum)
+Analysis Date: March 15, 2024
+
+---
+
+## 1. DOCUMENTATION & SPECIFICATIONS
+
+### Generated System Description
+
+**Plain English Overview:**
+The NFT Marketplace allows users to list, buy, and auction ERC721 tokens.
+The system uses a decentralized orderbook where sellers create listings with
+price and duration. Buyers can purchase instantly or place bids for auctions.
+A 2.5% platform fee is collected on each sale.
+
+**Key Assumptions:**
+- All NFTs follow ERC721 standard
+- Prices denominated in ETH only
+- No token whitelisting (any ERC721 accepted)
+- Platform fee immutable after deployment
+
+### Architectural Diagrams Generated
+
+✓ contract-interactions.png - Shows Marketplace, OrderBook, FeeCollector flow
+✓ state-machine.png - Listing states (Created → Active → Sold/Cancelled/Expired)
+✓ auction-flow.png - Bid placement and finalization sequence
+
+### Documentation Gaps Identified
+
+⚠ Missing NatSpec:
+- OrderBook.cancelOrder() - No @notice or @param
+- FeeCollector.withdrawFees() - Missing @dev implementation notes
+
+⚠ Undocumented Assumptions:
+- What happens if NFT transfer fails during purchase?
+- Are listings automatically cleaned up after expiration?
+- Fee distribution mechanism not explained
+
+**Recommendation:** Add comprehensive NatSpec to all public functions
+and document error handling for external calls.
+
+---
+
+## 2. ARCHITECTURE ANALYSIS
+
+### On-Chain vs Off-Chain Components
+
+**Current Distribution:**
+- On-Chain: Listing creation, order execution, fee collection
+- Off-Chain: Order discovery, price indexing, user notifications
+
+**Optimization Opportunities:**
+✓ Order matching is efficient (on-chain orderbook)
+✗ Listing enumeration is gas-intensive
+
+**Recommendation:**
+Consider moving listing discovery off-chain using event indexing.
+Keep core execution on-chain. Estimated gas savings: 40% for browse operations.
+
+### Upgradeability Review
+
+**Current Pattern:** TransparentUpgradeableProxy (OpenZeppelin)
+
+**Assessment:**
+✓ Proxy and implementation use shared storage base
+✓ Initialization properly handled
+✓ No function shadowing detected
+✗ No timelock on upgrades (admin can upgrade immediately)
+
+**Critical Issue:**
+File: contracts/Marketplace.sol
+The marketplace uses delegatecall proxy but admin is EOA without timelock.
+
+**Recommendation:**
+- Deploy TimelockController (48-hour delay)
+- Transfer proxy admin to timelock
+- Add emergency pause for critical bugs
+
+### Proxy Pattern Security
+
+**Findings:**
+✓ Storage layout consistent (inherits MarketplaceStorage)
+✓ No constructors in implementation
+✓ Initialize function has initializer modifier
+⚠ Immutable variables in proxy (PLATFORM_FEE)
+
+**Issue:** PLATFORM_FEE defined as immutable in proxy will not update
+if implementation changes this value.
+
+**Fix:** Move PLATFORM_FEE to storage or accept it's immutable forever.
+
+---
+
+## 3. IMPLEMENTATION REVIEW
+
+### Function Composition
+
+**Complex Functions Identified:**
+⚠ executePurchase() - 45 lines, cyclomatic complexity: 12
+  - Handles payment, NFT transfer, fee calc, event emission
+  - Recommendation: Extract _validatePurchase(), _processPayment(), _transferNFT()
+
+⚠ finalizeAuction() - 38 lines, cyclomatic complexity: 10
+  - Multiple nested conditionals for winner determination
+  - Recommendation: Extract _determineWinner(), _refundLosers()
+
+✓ Other functions well-scoped (average 15 lines)
+
+### Inheritance
+
+**Hierarchy Analysis:**
+```
+Marketplace
+├─ Ownable
+├─ ReentrancyGuard
+├─ Pausable
+└─ MarketplaceStorage
+```
+
+✓ Shallow inheritance (depth: 2)
+✓ No diamond problem
+✓ Clear separation of concerns
+
+**Slither Inheritance Graph:** contracts/inheritance.png (generated)
+
+### Events
+
+**Event Coverage:**
+✓ 12 events defined
+✓ All state changes emit events
+✓ Consistent naming (ListingCreated, OrderFulfilled, BidPlaced)
+✓ Indexed parameters for filtering (tokenId, seller, buyer)
+
+⚠ Missing Events:
+- Platform fee updates (if ever made variable)
+- Pause/unpause operations
+
+**Recommendation:** Add PlatformPaused/Unpaused events for monitoring.
+
+### Common Pitfalls
+
+**Issues Found:**
+
+❌ CRITICAL: Reentrancy in executePurchase()
+File: contracts/Marketplace.sol:234
+```solidity
+function executePurchase(uint256 listingId) external payable {
+    Listing memory listing = listings[listingId];
+    IERC721(listing.nftContract).transferFrom(listing.seller, msg.sender, listing.tokenId);
+    // State update AFTER external call!
+    listing.status = Status.Sold;
+}
+```
+**Fix:** Follow checks-effects-interactions. Update state before external calls.
+
+⚠ HIGH: Unvalidated external call return
+File: contracts/Marketplace.sol:245
+```solidity
+payable(seller).transfer(amount);  // Can fail silently
+```
+**Fix:** Use call{value}() and check return value or use Address.sendValue().
+
+✓ No timestamp dependence
+✓ No tx.origin usage
+✓ Integer overflow protected (Solidity 0.8+)
+
+---
+
+## 4. DEPENDENCIES
+
+**Current Dependencies:**
+✓ @openzeppelin/contracts@4.9.0 - Well-tested, good choice
+✗ Custom ERC721 implementation (contracts/CustomERC721.sol)
+
+**Issues:**
+⚠ CustomERC721 reinvents OpenZeppelin's ERC721
+   - 234 lines of duplicate code
+   - No added functionality
+   - Increases audit surface
+
+**Recommendation:**
+Replace CustomERC721 with OpenZeppelin's implementation.
+Saves 234 lines, reduces risk, improves maintainability.
+
+**Dependency Management:**
+✓ Using npm for dependencies
+✓ Package versions pinned
+⚠ Dependencies not updated in 8 months
+
+**Action:** Update @openzeppelin/contracts to latest 5.x (breaking changes, test thoroughly)
+
+---
+
+## 5. TESTING EVALUATION
+
+**Current Test Suite:**
+- 45 unit tests (forge test)
+- 12 integration tests
+- Coverage: 78%
+
+**Gaps Identified:**
+✗ No fuzzing (Echidna/Foundry)
+✗ No formal verification
+✗ Edge cases not covered:
+  - Auction with zero bids
+  - Listing with expired timestamp
+  - Purchase during contract pause
+
+**Recommendations:**
+1. Add Foundry invariant tests:
+   - Total fees collected == sum of individual sales * 0.025
+   - Active listings count matches actual active listings
+   - No NFT can be in multiple active listings
+
+2. Increase coverage to 95%+ by testing:
+   - Pausable functions during pause state
+   - Reentrancy attack scenarios
+   - Failed NFT transfers
+
+3. Add integration tests:
+   - End-to-end auction flow with multiple bidders
+   - Platform fee collection and withdrawal
+   - Upgrade and data migration
+
+**Estimated Effort:** 1-2 weeks to reach 95% coverage with invariant testing
+
+---
+
+## PRIORITIZED RECOMMENDATIONS
+
+### CRITICAL (Fix Immediately)
+1. **Fix reentrancy in executePurchase()** [HIGH IMPACT]
+   - Risk: Funds can be drained
+   - Effort: 1 day
+   - File: contracts/Marketplace.sol:234
+
+2. **Validate external call returns** [HIGH IMPACT]
+   - Risk: Failed transfers not detected
+   - Effort: 1 day
+   - Files: Multiple payment operations
+
+3. **Add timelock to upgrades** [HIGH IMPACT]
+   - Risk: Instant malicious upgrade
+   - Effort: 2 days
+
+### HIGH (Before Mainnet)
+4. **Remove CustomERC721, use OpenZeppelin** [MEDIUM IMPACT]
+   - Benefit: Reduce code, increase security
+   - Effort: 3 days
+
+5. **Increase test coverage to 95%** [MEDIUM IMPACT]
+   - Benefit: Catch edge case bugs
+   - Effort: 1-2 weeks
+
+6. **Add comprehensive NatSpec** [LOW IMPACT]
+   - Benefit: Better documentation
+   - Effort: 2-3 days
+
+### MEDIUM (Post-Launch V2)
+7. **Optimize listing enumeration** [MEDIUM IMPACT]
+   - Benefit: 40% gas savings on reads
+   - Effort: 1 week
+
+8. **Add invariant fuzzing** [HIGH IMPACT]
+   - Benefit: Discover hidden bugs
+   - Effort: 1 week
+
+---
+
+## SUMMARY
+
+**Overall Assessment:** MODERATE MATURITY
+
+The codebase follows many best practices with good use of OpenZeppelin
+libraries and clear architecture. Critical issues are reentrancy vulnerability
+and lack of upgrade timelock. Testing needs improvement.
+
+**Path to Production:**
+1. Fix CRITICAL items (reentrancy, timelock) - Week 1
+2. Address HIGH items (dependencies, testing) - Week 2-3
+3. External audit - Week 4-5
+4. Mainnet deployment with documented limitations
+5. MEDIUM items in V2 - Month 2-3
+
+**Estimated Timeline:** 3-4 weeks to production-ready state.
+
+---
+
+Analysis completed using Trail of Bits Development Guidelines
+```

package/skills/security-building-secure-contracts/skills/secure-workflow-guide/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: secure-workflow-guide
+description: Guides through Trail of Bits' 5-step secure development workflow. Runs Slither scans, checks special features (upgradeability/ERC conformance/token integration), generates visual security diagrams, helps document security properties for fuzzing/verification, and reviews manual security areas.
+---
+
+# Secure Workflow Guide
+
+## Purpose
+
+Guides through Trail of Bits' secure development workflow - a 5-step process to enhance smart contract security throughout development.
+
+**Use this**: On every check-in, before deployment, or when you want a security review
+
+---
+
+## The 5-Step Workflow
+
+Covers a security workflow including:
+
+### Step 1: Check for Known Security Issues
+Run Slither with 70+ built-in detectors to find common vulnerabilities:
+- Parse findings by severity
+- Explain each issue with file references
+- Recommend fixes
+- Help triage false positives
+
+**Goal**: Clean Slither report or documented triages
+
+### Step 2: Check Special Features
+Detect and validate applicable features:
+- **Upgradeability**: slither-check-upgradeability (17 upgrade risks)
+- **ERC conformance**: slither-check-erc (6 common specs)
+- **Token integration**: Recommend token-integration-analyzer skill
+- **Security properties**: slither-prop for ERC20
+
+**Note**: Only runs checks that apply to your codebase
+
+### Step 3: Visual Security Inspection
+Generate 3 security diagrams:
+- **Inheritance graph**: Identify shadowing and C3 linearization issues
+- **Function summary**: Show visibility and access controls
+- **Variables and authorization**: Map who can write to state variables
+
+Review each diagram for security concerns
+
+### Step 4: Document Security Properties
+Help document critical security properties:
+- State machine transitions and invariants
+- Access control requirements
+- Arithmetic constraints and precision
+- External interaction safety
+- Standards conformance
+
+Then set up testing:
+- **Echidna**: Property-based fuzzing with invariants
+- **Manticore**: Formal verification with symbolic execution
+- **Custom Slither checks**: Project-specific business logic
+
+**Note**: Most important activity for security
+
+### Step 5: Manual Review Areas
+Analyze areas automated tools miss:
+- **Privacy**: On-chain secrets, commit-reveal needs
+- **Front-running**: Slippage protection, ordering risks, MEV
+- **Cryptography**: Weak randomness, signature issues, hash collisions
+- **DeFi interactions**: Oracle manipulation, flash loans, protocol assumptions
+
+Search codebase for these patterns and flag risks
+
+For detailed instructions, commands, and explanations for each step, see [WORKFLOW_STEPS.md](resources/WORKFLOW_STEPS.md).
+
+---
+
+## How I Work
+
+When invoked, I will:
+
+1. **Explore your codebase** to understand structure
+2. **Run Step 1**: Slither security scan
+3. **Detect and run Step 2**: Special feature checks (only what applies)
+4. **Generate Step 3**: Visual security diagrams
+5. **Guide Step 4**: Security property documentation
+6. **Analyze Step 5**: Manual review areas
+7. **Provide action plan**: Prioritized fixes and next steps
+
+Adapts based on:
+- What tools you have installed
+- What's applicable to your project
+- Where you are in development
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "Slither not available, I'll check manually" | Manual checking misses 70+ detector patterns | Install and run Slither, or document why it's blocked |
+| "Can't generate diagrams, I'll describe the architecture" | Descriptions aren't visual - diagrams reveal patterns text misses | Execute slither --print commands, generate actual visual outputs |
+| "No upgrades detected, skip upgradeability checks" | Proxies and upgrades are often implicit or planned | Verify with codebase search before skipping Step 2 checks |
+| "Not a token, skip ERC checks" | Tokens can be integrated without obvious ERC inheritance | Check for token interactions, transfers, balances before skipping |
+| "Can't set up Echidna now, suggesting it for later" | Property-based testing is Step 4, not optional | Document properties now, set up fuzzing infrastructure |
+| "No DeFi interactions, skip oracle/flash loan checks" | DeFi patterns appear in unexpected places (price feeds, external calls) | Complete Step 5 manual review, search codebase for patterns |
+| "This step doesn't apply to my project" | "Not applicable" without verification = missed vulnerabilities | Verify with explicit codebase search before declaring N/A |
+| "I'll provide generic security advice instead of running workflow" | Generic advice isn't actionable, workflow finds specific issues | Execute all 5 steps, generate project-specific findings with file:line references |
+
+---
+
+## Example Output
+
+When I complete the workflow, you'll get a comprehensive security report covering:
+
+- **Step 1**: Slither findings with severity, file references, and fix recommendations
+- **Step 2**: Special feature validation results (upgradeability, ERC conformance, etc.)
+- **Step 3**: Visual diagrams analyzing inheritance, functions, and state variable authorization
+- **Step 4**: Documented security properties and testing setup (Echidna/Manticore)
+- **Step 5**: Manual review findings (privacy, front-running, cryptography, DeFi risks)
+- **Action plan**: Critical/high/medium priority tasks with effort estimates
+- **Workflow checklist**: Progress on all 5 steps
+
+For a complete example workflow report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).
+
+---
+
+## What You'll Get
+
+**Security Report**:
+- Slither findings with severity and fixes
+- Special feature validation results
+- Visual diagrams (PNG/PDF)
+- Manual review findings
+
+**Action Plan**:
+- [ ] Critical issues to fix immediately
+- [ ] Security properties to document
+- [ ] Testing to set up (Echidna/Manticore)
+- [ ] Manual areas to review
+
+**Workflow Checklist**:
+- [ ] Clean Slither report
+- [ ] Special features validated
+- [ ] Visual inspection complete
+- [ ] Properties documented
+- [ ] Manual review done
+
+---
+
+## Getting Help
+
+**Trail of Bits Resources**:
+- Office Hours: Every Tuesday ([schedule](https://meetings.hubspot.com/trailofbits/office-hours))
+- Empire Hacking Slack: #crytic and #ethereum channels
+
+**Other Security**:
+- Remember: Security is about more than smart contracts
+- Off-chain security (owner keys, infrastructure) equally critical
+
+---
+
+## Ready to Start
+
+Let me know when you're ready and I'll run through the workflow with your codebase!