How puckk/ctfd-plugin-unique-token works
Project Type and Purpose
• This is a CTFd plugin (i.e. an extension module) whose job is to generate and persist a unique token per user, inject client-side code to replace placeholders in challenge descriptions, and expose HTTP endpoints for retrieving or using those tokens (e.g. auto-solving challenges via an admin endpoint).
Main Components
a. CTFd Core Application
• The primary Flask app that hosts user management, challenges, submissions, etc.
• Loads plugins via its plugin API.
b. Unique Token Plugin Module
• __init__.py: Python code that hooks into CTFd plugin lifecycle, defines database model for the token, registers two Flask blueprints:
– GET /get_user_token
– GET /admin-solve/<token>/<challenge_name>
• unique_token.js: Client-side script that replaces any ##unique_token## placeholder in a challenge page with the logged‐in user’s token (fetched from the GET /get_user_token route).
c. Database
• A new table or model introduced by the plugin to store (user_id, token) records, using CTFd’s existing SQLAlchemy setup.
d. Browser (User)
• Renders challenge pages, executes unique_token.js to do string replacement.
• May call GET /get_user_token via AJAX.
e. Admin Client or Script
• Any HTTP client (curl, Python requests) that calls GET /admin-solve/<token>/<challenge_name> with a valid admin authorization token to auto-solve on a user’s behalf.
Interactions and Data Flow
1. User logs in to CTFd → Plugin login hook fires → Plugin generates a cryptographically secure token (using env vars: UNIQUE_TOKEN_SECRETKEY, UNIQUE_TOKEN_SALT) → Token is saved to the plugin’s DB table.
2. User views a challenge page → CTFd renders HTML → unique_token.js (injected by the plugin) executes in browser → It requests /get_user_token → Receives the token → Replaces all ##unique_token## placeholders in the page.
3. Admin wants to solve a user’s challenge → Admin script calls /admin-solve/<user_token>/<challenge_name> with an Admin API token → Plugin verifies both tokens, finds the matching user, and uses CTFd’s internal API to mark the challenge as solved for that user.
Architectural Patterns & Principles
• Plugin architecture / modular extension of a monolithic Flask app
• MVC‐style separation within the plugin:
• Model: SQLAlchemy token table
• View/Controller: Flask blueprints for the two endpoints
• Client View: JS script executed in the browser
• Security by design: using environment variables for secrets, token hashing/salting
Technologies & Frameworks
• Python 3.9, Flask (via CTFd core)
• SQLAlchemy (through CTFd)
• JavaScript for client-side placeholder replacement
• RESTful endpoints for both front-end AJAX and admin scripts
• Components: Browser (User), CTFd Core, Unique Token Plugin (Python), unique_token.js (Client), Database, Admin Script.
• Notes on security: secret key & salt, admin token header.