🚩 CTF Flag Generator

A web application that generates hilarious, sarcastic CTF (Capture The Flag) flags using Google's Gemini 2.5 Flash Lite AI API. Create witty flags that mock hackers and security fails!

✨ Features

• 🎉 3 Free Flags - Try the tool with 3 free flags before adding your API key!
• 🤖 AI-Powered Generation - Uses Gemini 2.5 Flash Lite for creative, context-aware flags
• 🔑 Easy API Key Setup - Add your free Gemini API key for unlimited flags
• ✅ API Key Validation - Tests API key before saving to ensure it works
• 💾 Local Storage - Saves generated flags in browser localStorage
• 📋 Copy to Clipboard - One-click flag copying
• 📥 Export to JSON - Export all flags with metadata
• ⚙️ Advanced Settings - Customize character types and attachments
• 🎛️ Character Options - Lowercase, uppercase, numbers, symbols
• 📎 Attachment Context - Image, text, binary, document options
• 🔄 Organization Persistence - Remembers your organization name
• 🎨 Modern UI - Clean design with Tailwind CSS and Font Awesome icons
• 🔒 Rate Limiting - 5 requests per minute per IP
• 🛡️ Security - Input sanitization and validation
• 📱 Responsive Design - Works on all devices
• 📎 Attachment Context - Image, text, binary, document options
• 🔄 Organization Persistence - Remembers your organization name
• 🎨 Modern UI - Clean design with Tailwind CSS and Font Awesome icons
• 🔒 Rate Limiting - 5 requests per minute per IP
• 🛡️ Security - Input sanitization and validation
• 📱 Responsive Design - Works on all devices

📋 Requirements

• PHP 7.0 or higher
• Web server (Apache/Nginx with PHP support)
• Modern web browser
• Internet connection for Gemini API calls
• Free Gemini API key from Google AI Studio

🚀 Setup

1. Clone or Download

   # Download the project files to your web server

2. File Structure

   CTF GEN/
   ├── index.html         # Main web interface
   ├── api.php            # Backend API endpoint
   ├── test_api.php       # API testing tool
   ├── list_models.php    # List available Gemini models
   ├── .env               # Default API key for first 3 flags
   ├── .gitignore         # Git ignore rules
   └── README.md          # This file
   

3. Configure Default API Key (Optional)

   • Open .env file
   • Replace your_gemini_api_key_here with your Gemini API key
   • This allows new users to try 3 free flags before adding their own key
   • If you skip this, users must add their own key immediately

4. Get Your API Key

   • Visit Google AI Studio
   • Sign in with your Google account
   • Click "Create API Key"
   • Copy your API key

5. Start Using the Tool

   • Open index.html in your browser
   • Option 1: Generate 3 free flags immediately (if .env is configured)
   • Option 2: Add your own API key in settings for unlimited flags

   To add your API key:

   • Click the settings icon (⚙️) in the top-right corner
   • Paste your API key
   • Click "Save API Key"
   • The tool will validate your key before saving

📖 Usage

First Time Experience

1. Open index.html in your web browser
2. You'll see a welcome notification: "🎉 Try 3 Free Flags!"
3. Start generating immediately - no setup required!
4. After 3 flags, you'll be prompted to add your own API key

Adding Your API Key

1. Click "Input API Key" button in the notification OR the settings icon (⚙️)
2. Enter your Gemini API key
3. Click "Save API Key" (automatically validated)
4. Enjoy unlimited flag generation! 🚀

Generating Flags

1. Fill in the required fields:

   • Organization Name: Used as flag prefix (e.g., CYBERX) - Saved automatically!
   • Challenge Name: The CTF challenge's name (e.g., SQL Warrior)
   • Challenge Description: What vulnerability or challenge type (e.g., SQL injection)

2. (Optional) Advanced Settings: Click to expand

   • Character Types: Choose lowercase, uppercase, numbers, symbols
   • Attachments: Select image, text, binary, or document context

3. Click "Generate Flag" to create your CTF flag

4. Manage your flags:

   • 📋 Copy - Click to copy flag to clipboard
   • 🗑️ Delete - Remove individual flags
   • 📥 Export - Download all flags as JSON
   • 🧹 Clear All - Remove all generated flags

🔧 How It Works

Frontend (index.html)

• Modern single-page application
• Collects user input and preferences
• Validates API key before saving
• Sends POST request to api.php with user's API key
• Displays generated flags with metadata
• Manages localStorage for:
  • Generated flags (ctfFlags)
  • User API key (customApiKey)
  • Organization name (ctfOrgName)

Backend (api.php)

• Requires user API key (no .env fallback)
• Validates and sanitizes all input
• Builds context-aware prompt with:
  • Challenge name and description
  • Character type requirements
  • Attachment context
• Calls Gemini 2.5 Flash Lite API via v1beta endpoint
• Returns generated flag in JSON format
• Rate limiting: 5 requests/minute per IP

Gemini API Integration

• Model: gemini-2.5-flash-lite via v1beta API
• Endpoint: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent
• Prompt: Context-aware with emphasis on sarcastic, funny flags
• Format: ORG_PREFIX{flag_text}
• Length: ~50-90 characters
• Style: Extremely sarcastic, witty, mocking security fails
• Speed: Ultra-fast responses with lightweight Flash Lite model

Advanced Features

• Character Customization: Specify which character types to include
• Attachment Context: Add context about challenge attachments
• API Key Validation: Tests key with sample request before saving
• Organization Persistence: Remembers your org name across sessions

🔒 Security Features

• ✅ Input Sanitization - htmlspecialchars, trim, stripslashes on all inputs
• ✅ XSS Prevention - Uses textContent instead of innerHTML for user data
• ✅ Rate Limiting - 5 requests per minute per IP address
• ✅ Server-Side Free Trial Tracking - 3 free flags tracked by IP (can't be bypassed by clearing cache)
• ✅ API Key Storage - Stored only in browser localStorage (not server-side)
• ✅ API Key Validation - Tests key before saving to prevent invalid keys
• ✅ CORS Headers - Properly configured for API calls
• ✅ Error Handling - Graceful error messages and fallback handling
• ✅ Persistent Tracking - Free usage stored in free_usage_*.json files per IP

📊 API Response Format

Success Response:

{
  "flag": "CYBERX{nice_try_but_sql_injection_is_so_2005}",
  "promptUsed": "Org: CYBERX, Challenge: SQL Warrior, Description: SQL injection in login form",
  "createdAt": "2025-10-10T12:34:56+00:00"
}

Error Response:

{
  "error": "API key is required. Please add your Gemini API key in the settings (top right corner)."
}

🛠️ Testing Tools

test_api.php

• Web-based API testing tool
• Input your API key to test connection
• Shows detailed request/response information
• Useful for debugging API issues

list_models.php

• Lists all available Gemini models
• Shows model capabilities
• Helps verify API access

🐛 Troubleshooting

Flag Generation Fails

1. No API Key: Add your API key in settings (⚙️ icon)
2. Invalid API Key:
   • Get a new key from Google AI Studio
   • Use test_api.php to verify your key works
3. Rate Limit: Wait 1 minute (5 requests per minute per IP)
4. Network Issues: Check your internet connection
5. Browser Issues: Clear browser cache and localStorage

API Key Won't Save

• Make sure the key starts with AIza...
• The tool validates the key before saving
• Check browser console for errors
• Try a different browser

Settings Not Persisting

• Enable localStorage in browser settings
• Check if cookies/storage is allowed
• Try clearing cache and re-entering settings

Need Help?

• Use test_api.php to debug API connection
• Check browser console (F12) for JavaScript errors
• Verify PHP error logs on server

Notes

⚠️ Security Warning: Never expose your .env file or commit it to version control. Add it to .gitignore:

.env
rate_*.json

License

This is a demonstration project for educational purposes.