How gaffe23/linux-inject works
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