AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

secure-workflow-guide

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. Use when securing a smart contract end to end rather than hunting one bug, checking a project on every check-in or before deployment, triaging a Slither report, or asking where to start on smart contract security.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--secure-workflow-guide at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

resources/EXAMPLE_REPORT.md

Example Output

When I complete the workflow, you'll get a comprehensive security report:

=== SECURE DEVELOPMENT WORKFLOW REPORT ===

Project: DeFi Staking Contract
Platform: Solidity 0.8.19
Workflow Date: March 15, 2024

---

## STEP 1: KNOWN SECURITY ISSUES

### Slither Security Scan

Command: slither . --exclude-dependencies
Status: ✓ CLEAN (after fixes)

**Issues Found & Resolved:**
✓ HIGH: Reentrancy in withdraw() - FIXED (added ReentrancyGuard)
✓ MEDIUM: Unprotected selfdestruct - FIXED (removed function)
✓ LOW: Missing zero-address checks - FIXED (added require statements)
✓ INFO: 5 optimization suggestions - DOCUMENTED

**Current Status:** All high/medium issues resolved. Ready for next steps.

---

## STEP 2: SPECIAL FEATURES

### Upgradeability Check

Pattern Detected: UUPS Proxy (ERC1967)

**slither-check-upgradeability Results:**
✓ Storage layout compatible
✓ No function collisions
✓ Initialize function protected
✓ _authorizeUpgrade restricted to owner
⚠ No timelock on upgrades

**Recommendation:** Add 48-hour timelock before Step 3 (Critical)

### ERC20 Conformance

**slither-check-erc Results:**
✓ All required functions present
✓ transfer/transferFrom return bool
✓ decimals returns uint8
✓ approve race condition mitigated (increaseAllowance/decreaseAllowance)
✓ No external calls in transfer functions

**Status:** FULLY COMPLIANT with ERC20 standard

---

## STEP 3: VISUAL SECURITY INSPECTION

### Inheritance Graph

File: inheritance-graph.png

**Analysis:**

StakingToken ├─ ERC20Upgradeable │ ├─ IERC20 │ └─ Context ├─ OwnableUpgradeable └─ UUPSUpgradeable


✓ Shallow hierarchy (depth: 3)
✓ No shadowing detected
✓ C3 linearization correct
✓ No diamond inheritance issues

### Function Summary

| Function           | Visibility | Modifiers          | Mutability  | Risk  |
|--------------------|------------|--------------------|-------------|-------|
| stake()            | external   | nonReentrant       | non-payable | Low   |
| withdraw()         | external   | nonReentrant       | non-payable | Low   |
| claimRewards()     | external   | nonReentrant       | non-payable | Low   |
| setRewardRate()    | external   | onlyOwner          | non-payable | Med   |
| pause()            | external   | onlyOwner          | non-payable | Med   |
| _authorizeUpgrade()| internal   | onlyOwner          | view        | High  |

✓ All privileged functions have access controls
✓ External functions have reentrancy protection
⚠ setRewardRate() allows owner to set arbitrary rate (no bounds)

**Recommendation:** Add min/max bounds to setRewardRate()

### Variables and Authorization

**State Variable Access:**

totalStaked (uint256)
├─ Written by: stake() [external, nonReentrant]
├─ Written by: withdraw() [external, nonReentrant]
└─ Read by: calculateRewards() [internal]

rewardRate (uint256)
├─ Written by: setRewardRate() [external, onlyOwner]
└─ Read by: calculateRewards() [internal]
⚠ No bounds checking - can be set to extreme values

userStakes (mapping)
├─ Written by: stake() [external, nonReentrant]
├─ Written by: withdraw() [external, nonReentrant]
└─ Protected by access controls ✓

**Critical Finding:** rewardRate modification needs validation

---

## STEP 4: SECURITY PROPERTIES DOCUMENTED

### Properties Defined

**State Machine Invariants:**
1. totalStaked == sum of all userStakes[user]
2. contract balance >= totalStaked + totalRewards
3. User cannot withdraw more than staked

**Access Control Properties:**
4. Only owner can modify rewardRate
5. Only owner can pause/unpause
6. Only owner can authorize upgrades

**Arithmetic Properties:**
7. calculateRewards() cannot overflow
8. Staking amount must be > 0
9. Reward calculation precision loss < 0.01%

### Testing Setup

**Echidna Configuration Created:**
File: echidna.yaml
```yaml
testMode: assertion
testLimit: 50000
deployer: "0x10000"
sender: ["0x10000", "0x20000", "0x30000"]

Invariants Implemented: File: test/echidna/StakingInvariants.sol

contract StakingInvariants {
    function echidna_total_staked_matches_sum() public returns (bool) {
        return staking.totalStaked() == calculateExpectedTotal();
    }

    function echidna_balance_sufficient() public returns (bool) {
        return address(staking).balance >= staking.totalStaked();
    }
}

Fuzzing Results: ✓ All 3 invariants hold after 50,000 runs ✓ No violations found ✓ Coverage: 94% of contract code

Next Step: Run Manticore for formal verification (optional, 2-3 days)


STEP 5: MANUAL REVIEW AREAS

Privacy Analysis

✓ No secrets stored on-chain ✓ All state variables appropriately public/internal ✓ No commit-reveal needed for current design ⚠ User staking amounts are publicly visible

Note: Public visibility of stakes is acceptable for this use case.

Front-Running Risks

Identified Risks: ⚠ setRewardRate() can be front-run by users to claim before rate decrease

Scenario:

  1. Owner submits tx to decrease rewardRate from 10% to 5%
  2. Users see pending tx in mempool
  3. Users front-run with claimRewards() at old 10% rate

Mitigation:

  • Add timelock to rewardRate changes (48-hour delay)
  • Implement gradual rate transitions

Cryptography Review

✓ No custom cryptography used ✓ No randomness requirements ✓ No signature verification N/A - Contract doesn't use cryptographic operations

DeFi Interaction Risks

External Dependencies:

  • None (self-contained staking contract)

✓ No oracle dependencies ✓ No flash loan risks (uses snapshots) ✓ No external protocol calls

Assessment: Low DeFi interaction risk


ACTION PLAN

Critical (Fix Before Deployment - Week 1)

  1. ✅ Add timelock to upgrades [COMPLETED]

    • Deployed TimelockController
    • 48-hour delay configured
    • Owner transferred to timelock
  2. ⚠ Add bounds to setRewardRate() [IN PROGRESS]

    • Add MIN_REWARD_RATE = 1%
    • Add MAX_REWARD_RATE = 50%
    • Estimated completion: 1 day
  3. ⚠ Add timelock to rewardRate changes [PENDING]

    • Use same timelock as upgrades
    • Estimated effort: 2 days

High Priority (Before Audit - Week 2)

  1. Document all security properties [80% COMPLETE]

    • 9/12 properties documented
    • Need to document upgrade invariants
    • Estimated completion: 2 days
  2. Increase test coverage to 95% [CURRENT: 89%]

    • Add pause state tests
    • Add edge case tests (zero amounts, etc.)
    • Estimated effort: 3 days

Medium Priority (Nice to Have)

  1. Add Manticore formal verification
    • Verify critical properties formally
    • Estimated effort: 1 week
    • Impact: High confidence

WORKFLOW CHECKLIST

✅ Step 1: Slither scan clean ✅ Step 2: Special features validated (upgradeability, ERC20) ✅ Step 3: Visual inspection complete (diagrams generated) ✅ Step 4: Properties documented, Echidna configured ✅ Step 5: Manual review complete

🎯 WORKFLOW STATUS: 95% COMPLETE

Remaining Tasks:

  • Add setRewardRate() bounds validation
  • Complete timelock integration
  • Document 3 remaining properties

Estimated Time to Full Completion: 3-4 days


Ready for external audit after critical tasks completed.

Trail of Bits Secure Development Workflow - v0.1.0