Smart Contract Security Audit Portfolio

A collection of smart contract security audits, audit tooling, and vulnerability research. Each project folder contains the audit script, static analysis output, test results, and a final audit report.

The goal is to build auditing skills systematically — from understanding the protocol and mapping attack surfaces, through static analysis and testing, to writing clear vulnerability reports — both as a learning practice and toward competitive bug bounty participation.

---

Audited Projects

All audits below are CodeHawks First Flights (closed competitions). Each project folder contains the customised audit.sh, overview.md (protocol notes), the audit_output_*/ artifacts produced by the script, and the written findings.

Project	Type	Period	Report
PasswordStore	Cyfrin training walkthrough	Oct 2025	Working notes
Snowman Merkle Airdrop	ERC20/ERC721 Merkle Airdrop	Jan 2026	Submissions · Notes
Stratax Contracts	DeFi Leveraged Positions (Aave + 1inch + Chainlink)	Feb 12–19 2026	Audit Report
MyCut	Contest Rewards Distribution	Feb 25 – Mar 4 2026	Audit Report Draft
ThunderLoan	Flash Loan + LP Yield (UUPS Upgradeable)	Feb 26 – Mar 5 2026	Audit Report Draft
Puppy Raffle	NFT Raffle	Mar 4 2026	Audit Report Draft
Santa's List	NFT Allowlist + ERC20	Mar 12 2026	Audit Report Draft
NFT Dealers	NFT Marketplace + Progressive Fee	Mar 12–26 2026	Audit Report
SNARKeling Treasure Hunt	ZK Proofs (Noir + Honk verifier)	Apr 16–23 2026	Findings
Beatland Festival	ERC1155 Passes + ERC20 BEAT	Jul 17–24 2025	Findings

---

Workflow: from overview.md to findings

Each audit follows the same pipeline. The protocol description drives the script config, the script produces artifacts, and the artifacts feed the manual review that produces written findings.

contest README / docs
        │
        ▼
   overview.md          ← protocol description, actors, scope, setup
        │                  (used to fill in audit.sh PROJECT CONFIG below,
        ▼                   and to seed the report's protocol section)
   audit.sh
   (PROJECT CONFIG       ← edit per project: name, scope files, repo URL,
    block edited)           src/test dirs, compiler, external protocols
        │
        ▼
   ./audit.sh
   (Setup → Recon → Static Analysis → Tests → Draft Report)
        │
        ▼
   audit_output_<name>/
     recon/   static/   tests/   report/AUDIT_REPORT_DRAFT.md
        │
        ▼
   Manual review (read every in-scope contract, threat model, write PoCs)
        │
        ▼
   findings.md / audit-report.md / SUBMISSIONS.md
   (titled findings with severity, root cause, impact, PoC, fix)

In short: overview.md is the input, audit.sh is the engine, audit_output_*/ is the scaffolding, the findings file is the deliverable.

---

Audit Script (audit.sh)

Each project contains an audit.sh script that automates the setup, recon, static analysis, and testing phases of a Foundry-based smart contract audit. The script evolves with each engagement — new recon patterns and analysis checks are added as the protocol type demands.

What it does

Phase 1 — Setup
  • Checks tool versions (forge, slither, aderyn, jq)
  • Installs Foundry dependencies (forge install)
  • Builds the project and logs any compilation warnings

Phase 2 — Recon
  • Generates storage layouts, ABIs, and function selectors for each in-scope contract
  • Extracts import graphs and dependency trees
  • Counts lines of code per contract
  • Flags public/external functions, access control patterns, external calls
  • Protocol-specific checks (e.g. oracle manipulation patterns, flash loan callbacks,
    upgradeable storage slots, unbounded loops, missing events)

Phase 3 — Static Analysis
  • Slither  → full JSON + human-readable output
  • Aderyn   → Markdown report

Phase 4 — Tests
  • forge test (unit)
  • forge test (fork / integration, if configured)
  • forge coverage → lcov.info + summary

Phase 5 — Report Generation
  • Writes a pre-filled AUDIT_REPORT_DRAFT.md with protocol overview,
    architecture diagram, actor table, and placeholder finding sections

Output structure

audit_output_<project>/
  recon/    — storage layouts, ABIs, selectors, import graph, line counts,
              access control, external calls, protocol-specific pattern files
  static/   — slither_output.{txt,json}, aderyn_report.md
  tests/    — unit_tests.log, coverage_summary.txt, lcov.info
  report/   — AUDIT_REPORT_DRAFT.md

Adapting for a new project

Start by writing overview.md for the new project — pull the protocol description, actors, scope, and setup steps from the contest README. The values you need for audit.sh are all there: scope filenames, repo URL, source/test directory layout, compiler version, external integrations.

Then edit only the PROJECT CONFIG block at the top of audit.sh:

PROJECT_NAME="MyProtocol"
AUDITOR="jebitok"
AUDIT_START="YYYY-MM-DD"
AUDIT_END="YYYY-MM-DD"

CONTRACTS_IN_SCOPE=("Token.sol" "Vault.sol")

SRC_DIR="src"
TEST_DIR="test"
TEST_UNIT_DIR="test/unit"
TEST_FORK_DIR="test/integration"   # leave empty if no fork tests

FUZZ_RUNS=5000

RPC_ENV_VAR="ETH_RPC_URL"
FORK_BLOCK=""   # pin to a block for deterministic replays

EXTERNAL_PROTOCOLS=("OpenZeppelin" "Chainlink")
BLOCKCHAIN="Ethereum Mainnet"
COMPILER="^0.8.20"

Then run:

cd path/to/cloned/protocol
cp /path/to/audit.sh .
chmod +x audit.sh
./audit.sh                        # all phases
./audit.sh --skip-static          # skip Slither / Aderyn
./audit.sh --skip-fork            # skip fork tests
./audit.sh --skip-static --skip-fork

---

Audit Methodology

1. Setup & Scope
   Read the README, docs, and contest brief. Pin the commit hash.
   Identify contracts in scope, compiler version, external integrations.

2. Recon (automated + manual)
   Run audit.sh to generate storage layouts, ABIs, import graphs.
   Read every in-scope contract top-to-bottom. Understand state variables,
   roles, and invariants before looking for bugs.

3. Attack Surface Mapping
   List all external/public entry points and their trust assumptions.
   Map privilege levels and access control. Identify assets at risk
   (tokens, NFTs, protocol fees, governance power).

4. Threat Modelling
   For each actor (owner, user, attacker), ask: what can they do that
   they shouldn't be able to? What invariant breaks if X is true?
   Common categories: reentrancy, price oracle manipulation, access control,
   arithmetic, flash loan attack vectors, upgrade storage collisions.

5. Static Analysis
   Review Slither and Aderyn output. Triage findings — distinguish true
   positives from noise. Cross-reference with manual notes.

6. Dynamic Testing
   Run existing tests, check coverage gaps. Write PoC tests for suspected
   vulnerabilities. Use forge fuzz to stress invariants.

7. Reporting
   Write findings with: Title, Severity, Root Cause, Impact, PoC, Fix.
   Severity follows standard: Critical / High / Medium / Low / Informational.

---

Tools

Tool	Purpose
Foundry	Build, test, fuzz, fork
Slither	Static analysis (Python)
Aderyn	Static analysis (Rust, Markdown output)
jq	JSON processing for ABI/selector extraction

---

Platforms

• CodeHawks — competitive audits and first flights
• Sherlock — competitive audits
• Code4rena — competitive audits