# fadi002/unshackle architecture

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

- Interactive diagram: https://gitdiagram.com/fadi002/unshackle
- Repository: https://github.com/fadi002/unshackle

## Overview

##### Project Type and Purpose
- Unshackle is an open-source, Linux-based, bootable USB tool designed to bypass Windows and Linux user passwords by injecting payloads and replacing system binaries (e.g., sethc.exe).
- The end goal is a self-contained ISO/USB image that, once booted, presents a simple CLI/GUI menu, lets the user pick the target OS, and executes the necessary removal or injection routines.

##### File Structure Analysis
- Top-Level Build & Config:
- build.sh        → orchestrates ISO creation
- inittab         → defines init process (menu loader)
- payload.sh      → root-level payload launcher
- version         → ISO version tag
- Scripts Directory:
- scripts/common          → shared helper functions
- scripts/unshackle_menu  → launch menu UI
- scripts/unshackle_options → handle user selections
- Source Directory (src):
- unshackle.py     → main Python orchestrator
- removal_util.cpp → C++ binary for Windows file operations
- payload.sh       → secondary shell payload (Linux support)
- Other Files:
- sethc.exe        → Windows sticky-keys binary to be replaced
- unshackle        → built executable or linker script

##### README Insights
- Confirms Linux and Windows support, simple CLI, plans for GUI, and ISO-based deployment.
- Outlines user flow: burn ISO to USB → boot → choose OS → automatic bypass → reboot → trigger sticky-keys hack (Windows).

a. Main Components
1. Build Pipeline
- build.sh
- Packaging scripts
- ISO/USB artifact
2. Boot Environment
- Syslinux/isolinux loader (configured via inittab)
- Linux kernel + initramfs
3. Runtime Control
- unshackle.py (Python orchestrator)
- scripts/unshackle_menu & unshackle_options (menu UI)
4. Payload Execution
- payload.sh (shell script for Linux target)
- removal_util (compiled C++ for Windows FS operations)
- sethc.exe replacement
5. Target File Systems
- Windows partition (NTFS)
- Linux partition (EXT4, etc.)
6. External Interfaces
- USB device (boot medium)
- Host BIOS/UEFI (boots ISO)

b. Relationships & Data Flow
1. User boots from USB → BIOS/UEFI hands off to isolinux
2. inittab → launches unshackle.py
3. unshackle.py → invokes menu scripts → user picks target OS
4. Based on selection:
- Invoke payload.sh (Linux) or removal_util.exe + payload.sh (Windows)
- Scripts mount target partition, backup & replace binaries
5. On success → unmount → reboot

c. Architectural Patterns & Principles
- Modular scripting: separates menu, options, common logic
- Polyglot orchestrator: Python for high-level logic, shell for file ops, C++ for low-level FS manipulation
- Single responsibility: each component (build, menu, payload, removal) has a distinct role

d. Key Technologies & Libraries
- Python 3 (unshackle.py)
- POSIX shell (bash)
- C++ (removal_util.cpp, compiled with g++)
- Syslinux/isolinux (bootloader)
- GNU coreutils (mount, dd, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        buildScript["build.sh"]:::buildComp
        versionTag["version"]:::buildComp
        isoArtifact["ISO/USB Artifact"]:::storage
        buildScript -->|generates| isoArtifact
        versionTag -->|tags| isoArtifact
    end

    %% Boot Environment
    subgraph "Boot Environment"
        direction TB
        bootloader["Syslinux/isolinux Loader"]:::runtime
        inittabCfg["inittab"]:::buildComp
        kernelInitramfs["Linux Kernel + initramfs"]:::runtime
        bootloader -->|configured by| inittabCfg
        bootloader -->|loads| kernelInitramfs
    end

    %% Runtime Control
    subgraph "Runtime Control"
        direction TB
        orchestrator["unshackle.py"]:::runtime
        menuUI["scripts/unshackle_menu"]:::runtime
        menuOpts["scripts/unshackle_options"]:::runtime
        commonFuncs["scripts/common"]:::runtime
        kernelInitramfs -->|executes| orchestrator
        orchestrator -->|calls| commonFuncs
        orchestrator -->|invokes| menuUI
        menuUI -->|uses| menuOpts
    end

    %% Payload Execution
    subgraph "Payload Execution"
        direction TB
        primaryPayload["payload.sh (root)"]:::runtime
        secondaryPayload["src/payload.sh"]:::runtime
        removalUtil["removal_util.cpp"]:::runtime
        stickyExe["sethc.exe"]:::target
        orchestrator -->|on Linux selection| primaryPayload
        orchestrator -->|on Windows selection| removalUtil
        orchestrator -->|on Windows selection| secondaryPayload
        removalUtil -->|replaces| stickyExe
        primaryPayload -->|mounts/unmounts| targetFS
        secondaryPayload -->|mounts/unmounts| targetFS
    end

    %% Target File Systems
    subgraph "Target File Systems"
        direction TB
        targetFS["Windows (NTFS) / Linux (EXT4) Partition"]:::target
    end

    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        usbDevice["USB Device"]:::external
        bios["Host BIOS/UEFI"]:::external
        usbDevice -->|boot medium| bios
        bios -->|hands off| bootloader
    end

    %% Connections
    isoArtifact -->|burn to USB| usbDevice
    orchestrator -->|triggers| removalUtil

    %% Click Events
    click buildScript "https://github.com/fadi002/unshackle/blob/main/build.sh"
    click versionTag "https://github.com/fadi002/unshackle/tree/main/version"
    click inittabCfg "https://github.com/fadi002/unshackle/tree/main/inittab"
    click orchestrator "https://github.com/fadi002/unshackle/blob/main/src/unshackle.py"
    click menuUI "https://github.com/fadi002/unshackle/tree/main/scripts/unshackle_menu"
    click menuOpts "https://github.com/fadi002/unshackle/tree/main/scripts/unshackle_options"
    click commonFuncs "https://github.com/fadi002/unshackle/tree/main/scripts/common"
    click primaryPayload "https://github.com/fadi002/unshackle/blob/main/payload.sh"
    click secondaryPayload "https://github.com/fadi002/unshackle/blob/main/src/payload.sh"
    click removalUtil "https://github.com/fadi002/unshackle/blob/main/src/removal_util.cpp"
    click stickyExe "https://github.com/fadi002/unshackle/blob/main/sethc.exe"
    click unshackle "https://github.com/fadi002/unshackle/tree/main/unshackle"

    %% Styles
    classDef buildComp fill:#d4f4dd,stroke:#2d6a4f,color:#1b4332
    classDef runtime fill:#d0ebff,stroke:#1c7ed6,color:#1864ab
    classDef target fill:#fff3bf,stroke:#f59f00,color:#d9480f
    classDef external fill:#ffe3e3,stroke:#c92a2a,color:#b7094c
    classDef storage fill:#e7f5ff,stroke:#339af0,color:#1864ab
    classDef default stroke:#333,fill:#fff,color:#000
```
