# अपनी पहली Smart Contract Audit Report कैसे लिखें — Step-by-Step Guide
Smart contract auditing एक lucrative career है, लेकिन finding को professional report में document करना उतना ही important है जितना bugs ढूंढना। इस guide में हम step-by-step सीखेंगे कि industry-standard audit report कैसे लिखें।
Report Structure Overview
Professional audit report में typically ये sections होते हैं:
1. Executive Summary
यह section non-technical stakeholders (executives, investors) के लिए है।
Template
# Executive Summary
Project: [Protocol Name]
Audit Date: March 20-25, 2026
Auditor: [Your Name/Company]
Scope: [Brief description]
Overview
[Protocol Name] engaged [Auditor] to review the security of their smart contracts.
The audit covered [X] contracts totaling [Y] lines of code.
Key Statistics
- Critical Issues: 0
- High Severity: 2
- Medium Severity: 5
- Low Severity: 8
- Informational: 12
- Gas Optimizations: 7
Summary
The codebase demonstrates [good/moderate/poor] security practices. Critical issues
were identified in [area] that require immediate attention before deployment.
[1-2 paragraphs summarizing main concerns and overall assessment]
Real Example
# Executive Summary
Project: DeFi Vault Protocol
Audit Date: March 20-25, 2026
Auditor: Cyfrin Security
Scope: Core vault contracts, reward distribution, and governance
Overview
DeFi Vault Protocol engaged Cyfrin Security to review their lending protocol
consisting of 8 smart contracts (2,450 lines of Solidity).
Key Statistics
- Critical Issues: 1
- High Severity: 2
- Medium Severity: 3
- Low Severity: 5
- Informational: 8
- Gas Optimizations: 4
Summary
The protocol demonstrates solid architecture with well-structured access controls
and comprehensive error handling. However, one critical reentrancy vulnerability
was discovered in the withdrawal mechanism that could allow attackers to drain
funds. Two high-severity issues related to oracle manipulation and precision loss
were also identified. All findings have been discussed with the team, and fixes
are being implemented.
2. Scope Definition
Clearly define क्या audit में included था और क्या नहीं।
Template
## Scope
In Scope
The following contracts were reviewed:
| Contract | Lines of Code | Purpose |
|----------|---------------|---------|
| Vault.sol | 450 | Main vault logic |
| RewardDistributor.sol | 320 | Reward calculations |
| Governance.sol | 280 | Voting mechanism |
Commit Hash: abc123def456...
Repository: https://github.com/project/repo
Out of Scope
- Frontend code
- Third-party dependencies (OpenZeppelin, Chainlink)
- Economic/game-theoretic analysis
- Formal verification
3. Methodology
Explain आपने audit कैसे किया।
Template
## Methodology
This audit employed a combination of manual review and automated analysis:
Manual Review
Architecture Analysis: System design and interaction flows
Code Review: Line-by-line examination for vulnerabilities
Access Control: Permission and privilege verification
Business Logic: Correctness of protocol economics
Automated Tools
- Slither: Static analysis for common patterns
- Aderyn: Rust-based vulnerability detection
- Echidna: Property-based fuzzing
- Mythril: Symbolic execution
Testing
- Reviewed existing test suite (coverage: 85%)
- Wrote additional Foundry tests for edge cases
- Fork testing against mainnet state
4. Severity Classification
Clear severity definitions बहुत जरूरी हैं।
Industry Standard Template
## Severity Classification
Critical
- Impact: Direct loss of funds, protocol insolvency
- Likelihood: Highly likely or easily exploitable
- Example: Reentrancy allowing unlimited withdrawals
High
- Impact: Significant fund loss or protocol disruption
- Likelihood: Moderate to high
- Example: Oracle manipulation enabling profitable exploits
Medium
- Impact: Moderate fund loss or temporary disruption
- Likelihood: Low to moderate
- Example: Incorrect slippage calculation causing user losses
Low
- Impact: Minimal fund loss, minor inconvenience
- Likelihood: Low
- Example: Missing event emissions
Informational
- Impact: No direct security impact
- Purpose: Code quality, best practices
- Example: Unused variables, unclear naming
Gas Optimization
- Impact: Cost savings for users
- Purpose: Efficiency improvements
5. Writing Findings
यह section सबसे important है। हर finding को detailed और actionable होना चाहिए।
Finding Template
## [Severity]-[Number]: [Concise Title]
Severity
[Critical/High/Medium/Low/Informational]
Description
[2-3 paragraphs explaining:
- What the vulnerability is
- Why it exists
- What the impact is]
Location
File: contracts/Vault.sol
Lines: 145-152
Vulnerable Code
function withdraw(uint256 amount) public {
require(balances[msg.sender] >= amount, "Insufficient balance");
// VULNERABLE: External call before state update
(bool success, ) = msg.sender.call{value: amount}("");
require(success, "Transfer failed");
balances[msg.sender] -= amount;
}
### Impact
[Specific consequences, with examples if possible]
Proof of Concept
// Attacker contract
contract Exploiter {
Vault public vault;
constructor(address _vault) {
vault = Vault(_vault);
}
receive() external payable {
if (address(vault).balance > 0) {
vault.withdraw(1 ether);
}
}
function attack() external payable {
vault.deposit{value: 1 ether}();
vault.withdraw(1 ether);
// Reenters, drains vault
}
}
### Recommendation
Solution: Apply Checks-Effects-Interactions pattern
function withdraw(uint256 amount) public {
require(balances[msg.sender] >= amount, "Insufficient balance");
// UPDATE STATE FIRST
balances[msg.sender] -= amount;
// Then external call
(bool success, ) = msg.sender.call{value: amount}("");
require(success, "Transfer failed");
}
### Team Response
[To be filled by protocol team]
- [ ] Acknowledged
- [ ] Fix committed: [commit hash]
- [ ] Verified by auditor
---
Real-World Example
## HIGH-01: Oracle Price Manipulation via Flash Loan
Severity
High
Description
The RewardDistributor contract uses spot price from a Uniswap V2 pool to calculate
reward values without any price manipulation protection. An attacker can use a flash
loan to manipulate the pool price within a single transaction, inflating reward values
and stealing funds from the protocol.
The vulnerability exists because the contract queries IUniswapV2Pair.getReserves()
directly without considering time-weighted average price (TWAP) or other manipulation
resistance mechanisms.
Location
File: contracts/RewardDistributor.sol
Lines: 89-95
Vulnerable Code
function calculateReward(address user) public view returns (uint256) {
(uint112 reserve0, uint112 reserve1, ) = pair.getReserves();
// VULNERABLE: Spot price can be manipulated
uint256 price = (reserve1 * 1e18) / reserve0;
return userStake[user] * price / 1e18;
}
### Impact
Estimated Loss: Up to entire reward pool (~$500K at current TVL)
Attack Scenario:
Attacker takes flash loan of 10,000 ETH
Swaps ETH → Token in Uniswap pool, inflating token price
Calls claimReward() with inflated price
Receives outsized reward payout
Swaps back Token → ETH
Repays flash loan
Profit from manipulated rewards
Proof of Concept
contract OracleExploit {
IRewardDistributor distributor;
IUniswapV2Pair pair;
IERC20 token;
function attack() external {
// 1. Flash loan 10000 ETH
uint256 loanAmount = 10000 ether;
flashLoan(loanAmount);
}
function onFlashLoan(uint256 amount) external {
// 2. Manipulate price
token.approve(address(pair), type(uint256).max);
pair.swap(amount, 0, address(this), "");
// 3. Claim inflated rewards
uint256 reward = distributor.claimReward();
// 4. Swap back
pair.swap(0, amount, address(this), "");
// 5. Repay loan + profit
}
}
### Recommendation
Primary Solution: Implement Chainlink price oracle
import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";
contract RewardDistributor {
AggregatorV3Interface priceFeed;
constructor(address _priceFeed) {
priceFeed = AggregatorV3Interface(_priceFeed);
}
function calculateReward(address user) public view returns (uint256) {
(, int256 price, , uint256 updatedAt, ) = priceFeed.latestRoundData();
require(block.timestamp - updatedAt < 1 hours, "Stale price");
require(price > 0, "Invalid price");
return userStake[user] * uint256(price) / 1e18;
}
}
Alternative: TWAP implementation// Use UniswapV3 TWAP oracle
import "@uniswap/v3-periphery/contracts/libraries/OracleLibrary.sol";
uint32 twapInterval = 1800; // 30 minutes
(int24 tick, ) = OracleLibrary.consult(pool, twapInterval);
uint256 price = OracleLibrary.getQuoteAtTick(tick, 1e18, token0, token1);
### Team Response
Status: Fix implemented
Commit: def789abc123...
Solution: Integrated Chainlink ETH/USD oracle with 1-hour staleness check
Verified: ✅ March 24, 2026
---
6. Gas Optimization Findings
Gas optimizations को separately document करें।
Template
## GAS-01: Cache Array Length in Loops
Current Code
function processUsers(address[] memory users) public {
for (uint256 i = 0; i < users.length; i++) {
// SLOAD on every iteration
process(users[i]);
}
}
### Optimized Codefunction processUsers(address[] memory users) public {
uint256 length = users.length; // Cache
for (uint256 i = 0; i < length; i++) {
process(users[i]);
}
}
### Gas Savings
Per iteration: ~3 gas
For 100 users: ~300 gas saved
---
7. Tools और Resources
Automated Analysis Tools
# Slither
slither . --json slither-report.json
# Aderyn
aderyn . -o aderyn-report.md
# Mythril
myth analyze contracts/Vault.sol
# Echidna fuzzing
echidna-test contracts/Vault.sol --contract VaultTest
Report Writing Tools
- Markdown editors: Obsidian, Typora
- Diagrams: draw.io, Mermaid
- Code highlighting: GitHub gists, Carbon
- PDF generation: Pandoc, LaTeX
8. Final Report Assembly
Complete Example Structure
# Smart Contract Audit Report
[Protocol Name]
Date: March 25, 2026
Auditor: [Name]
---
Table of Contents
Executive Summary
Scope
Methodology
Severity Classification
Findings
- Critical Severity
- High Severity
- Medium Severity
- Low Severity
- Informational
- Gas Optimizations
Recommendations
Conclusion
Appendix
---
[Insert all sections here]
---
Recommendations
Beyond specific findings, we recommend:
Increase test coverage from 85% to >95%
Implement formal verification for critical functions
Add monitoring for unusual transactions
Bug bounty program for ongoing security
Regular audits (every 6 months)
---
Conclusion
The [Protocol] codebase shows [assessment]. While [positive aspects],
several critical issues require immediate attention, particularly [main concern].
We recommend addressing all High and Critical findings before mainnet deployment.
---
Appendix
A. Audit Methodology Details
B. Tool Configurations
C. Test Coverage Report
D. References
Best Practices Checklist
- [ ] Clear, concise titles for each finding
- [ ] Severity justified with impact + likelihood
- [ ] Vulnerable code snippets included
- [ ] Proof of Concept provided for High/Critical
- [ ] Recommended fix with code example
- [ ] Line numbers and file paths accurate
- [ ] Grammar and spelling checked
- [ ] Technical accuracy verified
- [ ] Non-technical summary included
- [ ] Professional tone maintained
Common Mistakes to Avoid
- ✅ Better: "Reentrancy in transfer() allows unlimited withdrawals"
- ✅ Include working exploit code
- ✅ Use objective severity criteria
- ✅ Always provide solution
- ✅ Verify against final commit hash
Conclusion
Professional audit report writing एक skill है जो practice से improve होती है। Key points:
- Structure matters: Clear sections, logical flow
- Details critical हैं: Code snippets, PoCs, fixes
- Severity objective होना चाहिए: Impact × Likelihood
- Actionable recommendations: हर finding fixable होना चाहिए
अपनी first report लिखते समय existing public audit reports (Trail of Bits, Consensys, Cyfrin) reference करें।
Professional audit reports आपकी credibility build करती हैं और clients को trust दिलाती हैं। Quality reports = repeat business!