How I Built CTF Write-up Builder: Solving My Own Documentation Nightmare with Next.js + AI

ilana aminoff — Fri, 30 May 2025 19:43:00 +0000

From frustrated pentester to productive developer - the story of automating what I hated most about cybersecurity work.

The Problem That Drove Me Crazy

Picture this: You've just spent 6 hours pwning a challenging CTF machine on HackTheBox. You found the initial foothold, escalated privileges, grabbed both flags, and learned some cool new techniques. You're feeling great!

Then comes the part I absolutely dreaded: documentation.

Opening Google Docs (again)
Copy-pasting command outputs with broken formatting
Manually organizing screenshots from 3 different folders
Fighting with tables and bullet points
Spending 2+ hours on documentation for 6 hours of actual hacking

After years of this cycle, I realized I was spending 30% of my CTF time on documentation. That's when I decided to build my way out of this problem.

Enter CTF Write-up Builder

What I built: A specialized web application that turns CTF documentation from a chore into a streamlined workflow.

Tech stack:

Next.js 14 (App Router)
TypeScript
Tailwind CSS
AI Integration (Gemini/ChatGPT APIs)
Local storage for privacy

Live demo: ctf-writeup-builder.vercel.app
GitHub: github.com/ilanami/ctf_writeup_builder

The Technical Journey

Architecture Decisions

Why Next.js? I needed a framework that could handle:

Client-side AI API calls (keeping everything private)
File handling for screenshots and exports
Responsive design for mobile documentation
Easy deployment and fast performance

Privacy-First Approach:
Everything processes locally. No servers storing your write-ups, no data collection. The only external calls are to AI APIs (optional) and they're made directly from your browser.

Key Features That Solved Real Pain Points

🤖 AI-Powered Content Generation
Instead of staring at a blank page, I describe what I found: "nmap showed SSH and HTTP, found admin panel" and the AI suggests structured content, common enumeration commands, and next steps.

📝 Structured Templates
Pre-built sections that mirror real pentesting methodology:

Initial Reconnaissance
Service Enumeration
Web Application Analysis
Exploitation
Privilege Escalation
Lessons Learned

📸 Drag & Drop Screenshot Management
Screenshots automatically organize by section. No more desktop chaos.

📄 Professional PDF Export
Generates clean, professional PDFs perfect for job interview portfolios, client deliverables, and personal documentation archives.

The Development Process

Challenges I Faced

1. AI Integration Complexity
Initially tried server-side AI calls, but realized this broke my privacy-first promise. Refactored to client-side calls while handling API key management securely.

2. File Handling
Browser file APIs are tricky. Had to implement custom drag-and-drop with proper validation and preview generation.

3. PDF Generation
Finding the right balance between file size and quality took several iterations. Ended up with a custom solution using jsPDF with optimized image compression.

Code Architecture

Component Structure:

Editor: Markdown editor with live preview
Templates: CTF section templates
AI Integration: Smart content generation
Export: PDF/Markdown export functionality

State Management:
Used React's built-in state with custom hooks for persistence. Kept it simple - no Redux needed for this use case.

Real-World Impact

Documentation time: 2+ hours → 30 minutes
Consistency: Every write-up follows the same professional structure
Quality: AI suggestions help me remember methodology steps I might skip

Technical Lessons Learned

1. Privacy-First Development

Building everything client-side taught me a lot about browser APIs and local data management. It's more complex but worth it for user trust.

2. AI Integration Best Practices

Always make AI optional, never required
Provide fallbacks when APIs are down
Let users bring their own API keys
Design prompts for consistency across different AI models

3. User Experience in Specialized Tools

CTF practitioners have very specific workflows. Generic documentation tools fail because they don't understand the domain. Building for a niche allows for better UX decisions.

What's Next

Templates by CTF type: Web, PWN, Crypto, etc.
Integration APIs: Direct connection to HackTheBox, TryHackMe
Team collaboration: Shared write-ups for red team exercises

For the Developer Community

The entire codebase is open source. I'd love contributions for additional export formats, new AI provider integrations, and performance optimizations.

Try It Yourself

Demo: ctf-writeup-builder.vercel.app

No registration required
Works entirely in your browser
Try the AI features with your own API key

Questions for the Dev Community:

What documentation pain points do you face in your work?
How do you handle local-first applications with external APIs?
What features would make this useful for your field?

Building tools that solve your own problems is incredibly rewarding. This project turned my biggest workflow frustration into something I actually enjoy. What problems are you building your way out of?

Tags: #cybersecurity #nextjs #typescript #ai #productivity #opensource #ctf #pentesting

DEV Community: ilana aminoff