# jailctf/how2python architecture

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

- Interactive diagram: https://gitdiagram.com/jailctf/how2python
- Repository: https://github.com/jailctf/how2python

## Overview

##### Project type and purpose
- This is an open-source research tool / exploit PoC repository for tracking and demonstrating Python memory-corruption bugs.
- There is no “frontend” or “backend” in the traditional sense—rather a collection of standalone Python scripts under a single `bugs/` directory, each targeting a specific bug in CPython.

##### File structure
- Top level:
- `.gitignore`
- `README.md` (project description, Python version notes, bug table)
- `bugs/` directory containing one `.py` per bug pattern
- No build scripts, no external services, no configuration files beyond standard Git and Python.
- Each script is a minimal PoC: import one or more stdlib modules, trigger a bug, demonstrate arbitrary write.

##### README for additional insights
- The README defines:
- Supported platforms (Windows, Linux, 64-bit)
- Target Python versions (>=3.13.0, notes on 3.14 compatibility)
- A table listing bugs, their introduction version, patch status, and whether a PoC exists

a. Main components
- Developer / Security researcher (user of the repo)
- GitHub repository (version control)
- Local filesystem containing:
– `README.md` & metadata
– `bugs/` folder with PoC scripts
- Python interpreter (CPython runtime)
- Operating system (Windows/Linux, 64-bit)
- Standard library modules under test (e.g., `bytearray`, `itertools`, `decimal`)

b. Relationships & interactions
- User ↔ GitHub repo: clone / pull / push
- User → local `bugs/*.py`: selects and runs a PoC via `python bug_x.py`
- PoC script → CPython runtime: imports stdlib module(s), triggers bug in C code
- CPython runtime → OS memory subsystem: corrupts memory, prints results
- Feedback loop: developer examines output, crafts new PoCs

c. Architectural patterns / design principles
- Modular: one script per bug, easy to add new exploits
- Declarative metadata in README: versioning, patch status, links
- Git‐centric workflow: track issues via GitHub Issues / PRs

d. Key technologies & libraries
- Python 3.13.x (and 3.14 preview)
- Standard library modules under test
- Git / GitHub for collaboration

##### Detailed capture of architectural elements
- README.md as the project’s metadata hub

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Repo
    User["Developer / Security Researcher"]:::user
    Repo["GitHub Repository"]:::code

    %% Local Filesystem
    subgraph "Local Filesystem"
        README["README.md"]:::code
        Gitignore[".gitignore"]:::code
        subgraph "bugs/" 
            Accumulate["accumulate_bug.py"]:::code
            Bytearray["bytearray_bug.py"]:::code
            BytesIO["bytesio_bug.py"]:::code
            ClassDict["classdict_bug.py"]:::code
            DecimalCtx["decimal_context_bug.py"]:::code
            Memview["memoryview_cmp_bug.py"]:::code
            Namespace["namespace_bug.py"]:::code
            TryExcept["try_except_star_bug.py"]:::code
        end
    end

    %% Runtime and OS
    Interpreter["Python Interpreter"]:::runtime
    CAPI["Python C API"]:::runtime
    OS["Operating System (Memory Subsystem)"]:::os

    %% Flows
    User -->|"git clone / pull"| Repo
    Repo -.->|"local clone"| README
    Repo -.-> Gitignore
    Repo -.-> Accumulate
    Repo -.-> Bytearray
    Repo -.-> BytesIO
    Repo -.-> ClassDict
    Repo -.-> DecimalCtx
    Repo -.-> Memview
    Repo -.-> Namespace
    Repo -.-> TryExcept

    User -->|"select & run script"| Accumulate
    User -->|"select & run script"| Bytearray
    User -->|"select & run script"| BytesIO
    User -->|"select & run script"| ClassDict
    User -->|"select & run script"| DecimalCtx
    User -->|"select & run script"| Memview
    User -->|"select & run script"| Namespace
    User -->|"select & run script"| TryExcept

    Accumulate -->|"import & execute"| Interpreter
    Bytearray -->|"import & execute"| Interpreter
    BytesIO -->|"import & execute"| Interpreter
    ClassDict -->|"import & execute"| Interpreter
    DecimalCtx -->|"import & execute"| Interpreter
    Memview -->|"import & execute"| Interpreter
    Namespace -->|"import & execute"| Interpreter
    TryExcept -->|"import & execute"| Interpreter

    Interpreter -->|"C API calls"| CAPI
    CAPI -->|"memory corruption"| OS
    OS -->|"memory effects"| CAPI
    CAPI -->|"return to interpreter"| Interpreter

    Interpreter -->|"stdout / log results"| User

    %% Click Events
    click Repo "https://github.com/jailctf/how2python/blob/main/."
    click README "https://github.com/jailctf/how2python/blob/main/README.md"
    click Gitignore "https://github.com/jailctf/how2python/blob/main/.gitignore"
    click Accumulate "https://github.com/jailctf/how2python/blob/main/bugs/accumulate_bug.py"
    click Bytearray "https://github.com/jailctf/how2python/blob/main/bugs/bytearray_bug.py"
    click BytesIO "https://github.com/jailctf/how2python/blob/main/bugs/bytesio_bug.py"
    click ClassDict "https://github.com/jailctf/how2python/blob/main/bugs/classdict_bug.py"
    click DecimalCtx "https://github.com/jailctf/how2python/blob/main/bugs/decimal_context_bug.py"
    click Memview "https://github.com/jailctf/how2python/blob/main/bugs/memoryview_cmp_bug.py"
    click Namespace "https://github.com/jailctf/how2python/blob/main/bugs/namespace_bug.py"
    click TryExcept "https://github.com/jailctf/how2python/blob/main/bugs/try_except_star_bug.py"

    %% Styles
    classDef code fill:#cce5ff,stroke:#2b6cb0,color:#1a202c
    classDef runtime fill:#d4edda,stroke:#276749,color:#1a202c
    classDef os fill:#e2e3e5,stroke:#4a5568,color:#1a202c
    classDef user fill:#f8d7da,stroke:#742a2a,color:#1a202c
```
