# ticarpi/jwt_tool architecture

> Architecture diagram of the GitHub repository ticarpi/jwt_tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ticarpi/jwt_tool
- Repository: https://github.com/ticarpi/jwt_tool

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U("User Input (JWT+Options)"):::user

    %% Application Core Subgraph
    subgraph "Application Core"
        CLI("CLI Interface (jwt_tool.py)"):::cli
        subgraph "Processing Modules"
            VAL("Token Parsing & Validation Module"):::module
            EXP("Exploit & Tampering Module"):::module
            SCN("Scanning & Fuzzing Module"):::module
        end
        EXTC("External Communication Module (HTTP/DNS interactions)"):::external
    end

    %% Configuration & Resource Files Subgraph
    subgraph "Configuration & Resource Files"
        CH("Common Headers"):::config
        CP("Common Payloads"):::config
        JWK("JWKS Resource"):::config
        JWT("JWT Default Config"):::config
    end

    %% Deployment & Automation Subgraph
    subgraph "Deployment & Automation"
        DOCK("Docker Container"):::deployment
        CICD("GitHub Actions"):::deployment
    end

    %% Connections
    U -->|"provides input"| CLI
    CLI -->|"initiates"| VAL
    CLI -->|"initiates"| EXP
    CLI -->|"initiates"| SCN

    %% Connections from configuration to processing modules
    CH ---|"supplies data"| VAL
    CP ---|"supplies data"| EXP
    JWK ---|"supplies keys"| VAL
    JWT ---|"supplies defaults"| SCN

    %% Processing modules to external communications
    VAL -->|"sends requests"| EXTC
    EXP -->|"sends requests"| EXTC
    SCN -->|"sends requests"| EXTC

    %% Deployment connections
    DOCK ---|"runs in"| CLI
    CICD ---|"builds and deploys"| DOCK

    %% Click Events for Component Mappings
    click CLI "https://github.com/ticarpi/jwt_tool/blob/master/jwt_tool.py"
    click CH "https://github.com/ticarpi/jwt_tool/blob/master/common-headers.txt"
    click CP "https://github.com/ticarpi/jwt_tool/blob/master/common-payloads.txt"
    click JWK "https://github.com/ticarpi/jwt_tool/blob/master/jwks-common.txt"
    click JWT "https://github.com/ticarpi/jwt_tool/blob/master/jwt-common.txt"
    click DOCK "https://github.com/ticarpi/jwt_tool/tree/master/Dockerfile"
    click CICD "https://github.com/ticarpi/jwt_tool/blob/master/.github/workflows/builddocker.yml"

    %% Styles
    classDef user fill:#F7C8E0,stroke:#AD1457,stroke-width:2px;
    classDef cli fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef module fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef external fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef deployment fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
```
