How ticarpi/jwt_tool works
Based on our analysis of the file structure and README contents, this project is a specialized security testing toolkit for JSON Web Tokens. Its primary purpose is to validate, forge, scan, and modify JWTs in order to find vulnerabilities during pentesting and CTF challenges. Although the code is packaged as a single Python script (jwt_tool.py) along with a few helper files (e.g., common-headers.txt, common-payloads.txt, jwks-common.txt, jwt-common.txt), there are several supporting components (Dockerfile, GitHub workflows, setup/requirements files) that indicate the project’s deployment, testing, and distribution setup.
Main Components
• Command-Line Interface (CLI) Application: The jwt_tool.py serves as the entry point. It handles argument parsing, directs which functionality (validation, scanning, exploitation, fuzzing) to use, and displays output.
• JWT Processing Modules: Even if not explicitly separated into multiple files, conceptually there is a parsing and validation component, a tampering/forgery component, and various exploit-specific routines.
• Configuration & Resource Files: Files like common-headers.txt, common-payloads.txt, jwks-common.txt, and jwt-common.txt provide common data patterns and default values. These support the tool’s modular attack capabilities.
• External Service Interactions: The tool can send tokens to web applications (via HTTP requests) and log responses. There is integration with external services such as DNS, HTTP requests, and even external SSH or Docker environments.
• Docker & CI/CD Integration: The Dockerfile facilitates containerization for easier deployment, and the .github/workflows directory shows that automated building/testing is in place.
Relationships and Interactions
• Within the tool, demonstrate separate flows for:
• Validation: Parsing and verifying JWT structure and signature.
• Exploitation: Engaging modules or routines that attempt known JWT vulnerabilities (e.g., alg=none, RS/HS256 mismatch).
• Scanning/Fuzzing: Passing the JWT (or modified versions) to target URLs with user-supplied headers/cookies.
Architectural Patterns and Design Principles
• Modular Mono-Script: Although everything is bundled in jwt_tool.py, the design is conceptually modular, with each functionality (e.g., token tampering, vulnerability scanning) self-contained. Emphasize that the architecture follows a “single-entry CLI” pattern with logical separation of concerns.
• Extensibility: The use of configuration files and external key files (like JWKS and PEM files) alongside command-line options allows users to extend or change behaviors. Note the design awareness for remote configuration and output logging.
• Containerization & Automation: Include a separate module or node for cloud/CI-CD processes, showing how the Dockerfile and GitHub workflows automate build and deployment, ensuring consistent environments.
Relevant Technologies and Frameworks
• Programming Language: Python 3 (3.6+)
• Containerization: Docker is used for easy execution and deployment.
• (CI/CD Tools): GitHub Actions as indicated by the workflows