Aegis-3

Adversarial smart contract auditor

Comment

Inspiration

Smart contract security is a $2B+ problem. Traditional static analyzers like Slither and Mythril find surface-level issues, but they miss the context—they can't recognize when a pattern that looks safe in isolation becomes critical when combined with specific protocol mechanics.

I wanted to build a semantic context auditor that thinks like a security researcher.

The inspiration came from two realizations:

  1. Historical vulnerability patterns repeat across protocols — Solodit has documented over 69,000 real-world findings. What if an AI could learn from every past audit?

  2. LLMs + RAG = Adversarial reasoning — Gemini 3 can trace complex execution paths and reason about edge cases when given the right context. Static analyzers check for known patterns; AI can discover novel attack vectors.

What it does

Aegis-3 analyzes smart contract repositories in minutes through a five-stage pipeline:

  1. GitHub Ingestion - Fetches and flattens all Solidity files from any public repository
  2. Architecture Mapping - Gemini 3 Flash generates a system map identifying contracts, key functions, and risk areas
  3. RAG Context Retrieval - Searches 69,000+ indexed historical vulnerabilities to find relevant patterns
  4. Adversarial Audit - Gemini 3 Pro performs deep security analysis with historical context
  5. Visualization - Displays findings in Monaco Editor

Key Features:

  • Analyzes protocols (Aave, Uniswap, etc.) in under 5 minutes
  • Two-phase AI reasoning mimics human auditor workflow
  • RAG-lite system retrieves relevant patterns from 69,641 real-world findings
  • Severity rating tags
  • Generates Foundry-style PoC scaffolds for each finding
  • Live progress updates during analysis
  • Responsive design for desktop, tablet, and mobile

How we built it

Two-Phase AI Reasoning Pipeline

[1] GitHub Ingestion (Octokit REST API)
      ↓
[2] Architecture Mapping (Gemini 3 Flash - 1st Pass)
      ↓
[3] RAG Context Retrieval (69,000+ indexed findings)
      ↓
[4] Adversarial Audit (Gemini 3 Pro - 2nd Pass)
      ↓
[5] Visualization (Monaco Editor + Findings Panel)

This mimics how human auditors work: first understand the architecture, then hunt for vulnerabilities.

Tech Stack

  • Frontend: Next.js 16 + React 19 + Tailwind CSS
  • AI Engine: Google Gemini 3 Pro/Flash (2M token context)
  • Code Editor: Monaco Editor (VSCode engine)
  • GitHub API: Octokit (serverless-compatible)
  • Storage: Redis (Upstash) + Filesystem fallback
  • Security Data: 69,000+ Solodit reports across 50+ JSON files

RAG System

Built a lightweight semantic search system using keyword matching, pattern similarity, and impact weighting—no vector databases required. It retrieves the top 15 most relevant findings from 69,641 reports in under 2 seconds.

Challenges we ran into

Challenge 1: Serverless Architecture Constraints

Problem: Vercel's serverless environment has no git binary, 10s timeout limit, and ephemeral storage.

Solutions:

  1. No git binary → Built GitHub REST API ingestion with Octokit
  2. Storage persistence → Implemented dual-mode: Redis (Vercel) + filesystem (local)
  3. 10s timeout → Added frontend timeout detection + clear "run locally" guidance

Challenge 2: React Stale Closure Bug

Problem: Polling interval saw stale audit state → UI stuck on "Analyzing..."

Solution: Used useRef for interval handle + separate useEffect watching audit.status to clear on completion.

Challenge 3: Gemini API Rate Limits

Problem: Hit 429 errors during development testing.

Solution: Implemented automatic fallback, then upgraded to paid plan for production reliability.

Challenge 4: Monaco Editor TypeScript Integration

Problem: window.monaco type errors blocking builds.

Solution: Created type definitions (types/monaco.d.ts) declaring Monaco global.

Accomplishments that we're proud of

  • Successfully audited real protocols - Tested on Aave v2, and other contracts including one I wrote personally.
  • Two-phase AI reasoning - Architecture mapping → adversarial audit (mimics human workflow)
  • RAG at scale without vector DBs - Semantic search across 69,000+ findings
  • Tactical minimalist UI - High-information-density interface with live progress updates
  • Sub-5-minute analysis - Complete audit from GitHub URL to visual findings

What we learned

1. LLMs Can Perform Sophisticated Security Analysis

After testing on real protocols (Aave v2), I discovered Gemini 3 can:

  • Trace multi-step attack paths
  • Systematically explore boundary conditions without explicit instructions
  • Match new code against similar past vulnerabilities

The key was prompt engineering + structured context.

2. RAG Without Vector Databases is Viable

Text-based semantic search using keyword matching, pattern extraction, and impact scoring can retrieve highly relevant context from 69,000+ documents. Vector embeddings aren't always necessary for effective RAG.

3. Serverless Has Hard Constraints

Vercel's free plan has 10s function timeout, read-only filesystem, and ephemeral storage. Building for serverless requires architectural decisions from day one: API-based ingestion (not git clone), persistent storage (Redis not filesystem), and clear user guidance on limitations.

4. React Closures + Intervals = Danger

setInterval inside useEffect captures stale state. Always use useRef for interval handles and separate effects to react to state changes.

What's next for Aegis-3

  • Upgrade Vercel plan - Hope to unlock full serverless functionality
  • Executable PoC generation - Generate full Foundry test files, not just scaffolds
  • Audit competitions test-run - Take this for a test run in an active audit competition
  • Feedback and Iteration - I will continue to improve this until it is one of the best Auditing tools in the space.

Current Status: Production-ready only for localhost audits as Vercel has limitations.

Built With

Share this project:

Updates