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.
How I Work
When invoked, I will:
- Explore your codebase to understand structure
- Run Step 1: Slither security scan
- Detect and run Step 2: Special feature checks (only what applies)
- Generate Step 3: Visual security diagrams
- Guide Step 4: Security property documentation
- Analyze Step 5: Manual review areas
- 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.
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:
Workflow Checklist:
Getting Help
Trail of Bits Resources:
- Office Hours: Every Tuesday (schedule)
- 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!
1---2name: secure-workflow-guide3description: 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.4---5
6# Secure Workflow Guide
7
8## Purpose
9
10Guides through Trail of Bits' secure development workflow - a 5-step process to enhance smart contract security throughout development.
11
12**Use this**: On every check-in, before deployment, or when you want a security review
13
14---
15
16## The 5-Step Workflow
17
18Covers a security workflow including:
19
20### Step 1: Check for Known Security Issues
21Run Slither with 70+ built-in detectors to find common vulnerabilities:
22- Parse findings by severity
23- Explain each issue with file references
24- Recommend fixes
25- Help triage false positives
26
27**Goal**: Clean Slither report or documented triages
28
29### Step 2: Check Special Features
30Detect and validate applicable features:
31- **Upgradeability**: slither-check-upgradeability (17 upgrade risks)
32- **ERC conformance**: slither-check-erc (6 common specs)
33- **Token integration**: Recommend token-integration-analyzer skill
34- **Security properties**: slither-prop for ERC20
35
36**Note**: Only runs checks that apply to your codebase
37
38### Step 3: Visual Security Inspection
39Generate 3 security diagrams:
40- **Inheritance graph**: Identify shadowing and C3 linearization issues
41- **Function summary**: Show visibility and access controls
42- **Variables and authorization**: Map who can write to state variables
43
44Review each diagram for security concerns
45
46### Step 4: Document Security Properties
47Help document critical security properties:
48- State machine transitions and invariants
49- Access control requirements
50- Arithmetic constraints and precision
51- External interaction safety
52- Standards conformance
53
54Then set up testing:
55- **Echidna**: Property-based fuzzing with invariants
56- **Manticore**: Formal verification with symbolic execution
57- **Custom Slither checks**: Project-specific business logic
58
59**Note**: Most important activity for security
60
61### Step 5: Manual Review Areas
62Analyze areas automated tools miss:
63- **Privacy**: On-chain secrets, commit-reveal needs
64- **Front-running**: Slippage protection, ordering risks, MEV
65- **Cryptography**: Weak randomness, signature issues, hash collisions
66- **DeFi interactions**: Oracle manipulation, flash loans, protocol assumptions
67
68Search codebase for these patterns and flag risks
69
70For detailed instructions, commands, and explanations for each step, see [WORKFLOW_STEPS.md](resources/WORKFLOW_STEPS.md).
71
72---
73
74## How I Work
75
76When invoked, I will:
77
781. **Explore your codebase** to understand structure
792. **Run Step 1**: Slither security scan
803. **Detect and run Step 2**: Special feature checks (only what applies)
814. **Generate Step 3**: Visual security diagrams
825. **Guide Step 4**: Security property documentation
836. **Analyze Step 5**: Manual review areas
847. **Provide action plan**: Prioritized fixes and next steps
85
86Adapts based on:
87- What tools you have installed
88- What's applicable to your project
89- Where you are in development
90
91---
92
93## Rationalizations (Do Not Skip)
94
95| Rationalization | Why It's Wrong | Required Action |
96|-----------------|----------------|-----------------|
97| "Slither not available, I'll check manually" | Manual checking misses 70+ detector patterns | Install and run Slither, or document why it's blocked |
98| "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 |
99| "No upgrades detected, skip upgradeability checks" | Proxies and upgrades are often implicit or planned | Verify with codebase search before skipping Step 2 checks |
100| "Not a token, skip ERC checks" | Tokens can be integrated without obvious ERC inheritance | Check for token interactions, transfers, balances before skipping |
101| "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 |
102| "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 |
103| "This step doesn't apply to my project" | "Not applicable" without verification = missed vulnerabilities | Verify with explicit codebase search before declaring N/A |
104| "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 |
105
106---
107
108## Example Output
109
110When I complete the workflow, you'll get a comprehensive security report covering:
111
112- **Step 1**: Slither findings with severity, file references, and fix recommendations
113- **Step 2**: Special feature validation results (upgradeability, ERC conformance, etc.)
114- **Step 3**: Visual diagrams analyzing inheritance, functions, and state variable authorization
115- **Step 4**: Documented security properties and testing setup (Echidna/Manticore)
116- **Step 5**: Manual review findings (privacy, front-running, cryptography, DeFi risks)
117- **Action plan**: Critical/high/medium priority tasks with effort estimates
118- **Workflow checklist**: Progress on all 5 steps
119
120For a complete example workflow report, see [EXAMPLE_REPORT.md](resources/EXAMPLE_REPORT.md).
121
122---
123
124## What You'll Get
125
126**Security Report**:
127- Slither findings with severity and fixes
128- Special feature validation results
129- Visual diagrams (PNG/PDF)
130- Manual review findings
131
132**Action Plan**:
133- [ ] Critical issues to fix immediately
134- [ ] Security properties to document
135- [ ] Testing to set up (Echidna/Manticore)
136- [ ] Manual areas to review
137
138**Workflow Checklist**:
139- [ ] Clean Slither report
140- [ ] Special features validated
141- [ ] Visual inspection complete
142- [ ] Properties documented
143- [ ] Manual review done
144
145---
146
147## Getting Help
148
149**Trail of Bits Resources**:
150- Office Hours: Every Tuesday ([schedule](https://meetings.hubspot.com/trailofbits/office-hours))
151- Empire Hacking Slack: #crytic and #ethereum channels
152
153**Other Security**:
154- Remember: Security is about more than smart contracts
155- Off-chain security (owner keys, infrastructure) equally critical
156
157---
158
159## Ready to Start
160
161Let me know when you're ready and I'll run through the workflow with your codebase!
gabrielmoreira