Skip to content

README.md

Latest commit

 

History

History
138 lines (107 loc) · 4.66 KB

README.md

File metadata and controls

138 lines (107 loc) · 4.66 KB

Injectra

Universal Windows DLL injector. Safety-first LoadLibraryW injection with PE validation, architecture checks, already-loaded detection, eject mode, and structured colorized logs.

Built for legitimate use: debugging, modding, instrumentation, plugin loading, and security research on systems you own or are authorized to test. Do not use to bypass anti-cheat, EULAs, or to target software or systems you do not have permission to instrument.

Features

  • PE validation — verifies the file is a real PE, is a DLL, and detects its architecture before doing anything to the target.
  • Architecture matching — refuses to inject an x86 DLL into an x64 process (or vice versa) unless --force is given. ARM64 supported.
  • Already-loaded detection — won't double-inject the same module by name.
  • Eject mode — --eject <module> calls FreeLibrary remotely to cleanly unload a previously injected DLL.
  • Wait-for-process — --wait polls until the target appears, with optional --timeout.
  • Process listing — --list [filter] enumerates running processes.
  • Dry run — --dry-run performs every check without touching the target.
  • Structured logs — millisecond timestamps, level tags, ANSI colors, optional --log file.txt.
  • Privilege upgrade — best-effort SeDebugPrivilege when run elevated.
  • No external dependencies — single executable, links only Windows SDK.
  • Both x86 and x64 builds — match the bitness of your target.

Build

Visual Studio 2022

Open Injectra.sln and build any of: Debug|Release × Win32|x64.

CMake

cmake -S . -B build
cmake --build build --config Release

Output: build/x64/Release/injectra.exe (msbuild) or build/Release/injectra.exe (cmake).

Usage

injectra --dll <path> [--proc <name> | --pid <id>] [options]
injectra --eject <module> [--proc <name> | --pid <id>] [options]
injectra --list [filter]

Common examples

# Inject by process name
injectra --dll C:\mods\my.dll --proc notepad.exe

# Wait for the process to start (max 60s), log to file
injectra --dll mod.dll --proc game.exe --wait --timeout 60 --log run.log

# Inject by PID
injectra --dll mod.dll --pid 12345

# Eject a previously-loaded DLL
injectra --eject mod.dll --pid 12345

# List Chrome processes
injectra --list chrome

# Validate without touching the target
injectra --dll mod.dll --proc notepad.exe --dry-run --verbose

All options

Flag Description
--dll <path> DLL to inject
--proc <name> Target process name
--pid <id> Target by PID
--eject <module> Free a module from the target
--list [filter] List processes (optional substring filter)
--wait Wait for the target to appear
--timeout <sec> Timeout for --wait (0 = infinite)
--dry-run Validate everything, don't inject
--force Skip safety checks (arch, already-loaded)
--verbose Debug-level logging
--quiet Errors only
--no-color Disable ANSI colors
--no-banner Hide startup banner
--log <file> Append logs to file
--pause Pause before exit (handy for double-click)
-h, --help Show help
-v, --version Show version

Exit codes

Code Meaning
0 Success
1 Injection / eject failed at runtime
2 Argument or pre-flight validation error

How it works

Standard CreateRemoteThread + LoadLibraryW injection, with extra checks:

  1. Parse and validate the DLL's PE headers from disk (DOS + NT signatures, machine type, IMAGE_FILE_DLL flag).
  2. OpenProcess with the minimum rights needed; bail if denied.
  3. IsWow64Process2 to determine the target's effective arch and refuse a mismatched DLL unless --force.
  4. EnumProcessModulesEx to detect an already-loaded module of the same base name.
  5. VirtualAllocEx a PAGE_READWRITE buffer, WriteProcessMemory the full wide-char path, then CreateRemoteThread on LoadLibraryW.
  6. Wait up to 15 seconds for the remote thread, free remote memory, report the returned HMODULE.

Eject mirrors this: locate the module in the target, then CreateRemoteThread on FreeLibrary with that handle.

Caveats

  • Some processes refuse OpenProcess even from Administrator (protected processes, anti-cheat, AV self-protection). Injectra surfaces the Win32 error code; it does not attempt evasion.
  • --force skips safety checks but cannot fix an actual arch mismatch — the remote LoadLibraryW will still fail.
  • Run from a console matching the target's bitness when in doubt (x64 injector for x64 targets).

License

MIT — see LICENSE.