# gaffe23/linux-inject architecture

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

- Interactive diagram: https://gitdiagram.com/gaffe23/linux-inject
- Repository: https://github.com/gaffe23/linux-inject

## Overview

##### Project type and purpose
- This is a native command-line injection tool (“linux-inject”) for Linux that uses ptrace() to inject a shared object into an already-running process.
- It is neither a full-stack web app nor a microservice; it’s a single binary tool with architecture-specific modules (x86, x86_64, ARM) and supporting C libraries.

##### File structure
- Top-level C source files:
- inject-arm.c, inject-x86.c, inject-x86_64.c – each contains the architecture-specific entry point and injection logic
- ptrace.c / ptrace.h – abstraction over ptrace syscalls and memory operations
- utils.c / utils.h – shared utilities (error handling, lookup functions)
- sample-library.c / sample-target.c – demonstration library and target process
- Makefile – build orchestration
- There are no separate frontend/backend folders; everything lives at the root.

##### Key insights from the README
- The tool:
- Locates or attaches to a target by name or PID
- Allocates memory in the target via ptrace
- Writes code into the target process address space
- Invokes __libc_dlopen_mode in the target to load the shared object
- Supports three CPU architectures via separate source files.
- Relies on the Linux kernel’s ptrace interface and on libc internals, not libdl.

##### Main components
a. Injector CLI (linux-inject)
- Architecture-agnostic orchestrator
- Delegates to one of the arch-specific modules (x86, x86_64, ARM)
b. Arch-specific module
- Implements injection steps for each ISA (register setup, syscall conventions)
c. ptrace abstraction layer
- Wraps ptrace() syscalls to read/write memory, set registers, single-step
d. Utility functions
- Error handling, symbol resolution, process lookup
e. Target process
- Any running Linux process (sample-target for demo)
f. Shared object to inject
- sample-library or any .so specified on the command line
g. Linux kernel and glibc
- Kernel provides the ptrace syscalls
- glibc in the target exports __libc_dlopen_mode
h. Environment
- Execution shell, Makefile build

##### Relationships and interactions
- The user invokes “./inject” in a shell
- Injector CLI loads the appropriate arch module
- Injector → ptrace abstraction → Kernel (ptrace ATTACH)
- Injector uses ptrace abstraction to:
1) Allocate memory in target (via mmap syscall in the target)
2) Write the path of the .so and stub code into target memory
3) Hijack target’s instruction pointer to call __libc_dlopen_mode
4) Wait for the call to finish, then restore registers
5) Detach (ptrace DETACH)
- Target process resumes execution with the new shared object loaded
- Optionally, target’s own .init routines run and produce output

##### Architectural patterns and design principles
- Plugin-like separation: arch-specific code is isolated in separate C files
- Abstraction layer (ptrace.c/h) encapsulates low-level syscalls
- Utility layer for common tasks (CLI parsing, symbol lookups)
- Single-responsibility: each module has a clear role in the injection pipeline

##### Diagramming recommendations
- Rectangles for code modules (inject CLI, arch modules, ptrace layer, utils)
- Blue for injector components
- Green for ptrace abstraction
- Yellow for external dependencies (Kernel, glibc)
- Orange for target and injected library
- From “User CLI” → “inject CLI”
- “inject CLI” → “arch module” → “ptrace layer” → “Kernel”
- “ptrace layer” ↔ “Target process memory”
- “arch module” → “Injected library in target”
- Syscalls where they occur (ptrace, mmap, write, single-step)

##### Essential elements to capture
- Separation of modules by responsibility
- Flow of control/data from injector to kernel to target
- Where architecture-specific logic is plugged in
- Use of libc internals in the target
- Entry and exit points of the process injection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and components
    User["User Shell"]:::user
    Injector["Injector CLI\n(linux-inject)"]:::injector
    subgraph "Injector Components"
        ArchArm["ARM Module"]:::arch
        Archx86["x86 Module"]:::arch
        Archx8664["x86_64 Module"]:::arch
        PtrLayer["ptrace Abstraction"]:::ptrace
        Utils["Utility Layer"]:::utils
    end
    Kernel["Linux Kernel\n(ptrace syscalls)"]:::kernel
    Glibc["glibc in Target\n(__libc_dlopen_mode)"]:::glibc
    Target["Target Process"]:::target
    Library["Injected Shared Library"]:::library
    Makefile["Makefile"]:::env
    README["README.md"]:::env

    %% Control flow
    User -->|"invokes ./inject"| Injector
    Injector -->|"loads architecture module"| ArchArm
    Injector -->|"loads architecture module"| Archx86
    Injector -->|"loads architecture module"| Archx86_64
    Injector -->|"uses utilities"| Utils

    ArchArm -->|"uses ptrace API"| PtrLayer
    Archx86 -->|"uses ptrace API"| PtrLayer
    Archx86_64 -->|"uses ptrace API"| PtrLayer

    PtrLayer -->|"ptrace ATTACH/DETACH"| Kernel
    PtrLayer -->|"ALLOCATE (mmap) WRITE CODE"| Target
    PtrLayer -->|"READ/WRITE MEMORY, SET REGISTERS"| Target

    ArchArm -->|"CALL __libc_dlopen_mode"| Target
    Archx86 -->|"CALL __libc_dlopen_mode"| Target
    Archx86_64 -->|"CALL __libc_dlopen_mode"| Target

    Target -->|"invokes symbol"| Glibc
    Target -->|"loads library"| Library

    Makefile --> Injector
    README --> Injector
    README --> Utils
    README --> PtrLayer
    README --> ArchArm
    README --> Archx86
    README --> Archx86_64

    %% Click events
    click ArchArm "https://github.com/gaffe23/linux-inject/blob/master/inject-arm.c"
    click Archx86 "https://github.com/gaffe23/linux-inject/blob/master/inject-x86.c"
    click Archx8664 "https://github.com/gaffe23/linux-inject/blob/master/inject-x86_64.c"
    click PtrLayer "https://github.com/gaffe23/linux-inject/blob/master/ptrace.c"
    click PtrLayer "https://github.com/gaffe23/linux-inject/blob/master/ptrace.h"
    click Utils "https://github.com/gaffe23/linux-inject/blob/master/utils.c"
    click Utils "https://github.com/gaffe23/linux-inject/blob/master/utils.h"
    click Target "https://github.com/gaffe23/linux-inject/blob/master/sample-target.c"
    click Library "https://github.com/gaffe23/linux-inject/blob/master/sample-library.c"
    click Makefile "https://github.com/gaffe23/linux-inject/tree/master/Makefile"
    click README "https://github.com/gaffe23/linux-inject/blob/master/README.md"

    %% Styles
    classDef user fill:#AED6F1,stroke:#1B4F72,color:#1B4F72;
    classDef injector fill:#5DADE2,stroke:#1A5276,color:#ffffff;
    classDef arch fill:#85C1E9,stroke:#1B4F72,color:#1B4F72;
    classDef ptrace fill:#ABEBC6,stroke:#196F3D,color:#1B4F3D;
    classDef utils fill:#A9DFBF,stroke:#1E8449,color:#ffffff;
    classDef kernel fill:#F9E79F,stroke:#7D6608,color:#7D6608;
    classDef glibc fill:#F7DC6F,stroke:#7D6608,color:#000000;
    classDef target fill:#F5B7B1,stroke:#641E16,color:#641E16;
    classDef library fill:#F1948A,stroke:#922B21,color:#000000;
    classDef env fill:#D5DBDB,stroke:#424949,color:#424949;
```
