English · 简体中文
Heroinn is a cross-platform C2 post-exploitation framework written in Rust for authorized security research, red-team testing, and educational use.
Authorized use only. Use Heroinn exclusively on systems you own or have explicit permission to test. You are responsible for complying with all applicable laws and authorization requirements.
- Desktop GUI.
- Interactive PTY shell with a dedicated terminal window per session.
- File manager with resumable transfers and large-file support.
- Agents can be configured to connect to the server through a SOCKS5 proxy, including a proxy chain with the system proxy.
- Limit the total transfer rate per agent (default 1 MB/s).
- SOCKS5 reverse proxy support through proxy chains.
- TCP, HTTP, and reliable UDP transports.
- When using TCP or HTTP, agents automatically connect through the system proxy (HTTP/HTTPS/SOCKS5).
- End-to-end encrypted transport (Noise_NN_25519_ChaChaPoly_BLAKE2s)
- Windows 10+ (Windows Server 2019+), Linux, and FreeBSD support.
- Rust 1.95 or newer with Cargo.
- Linux build dependencies:
sudo apt-get install -y \
build-essential pkg-config cmake libssl-dev \
libfontconfig1-dev libfreetype6-dev libexpat1-dev \
libx11-dev libx11-xcb-dev libxcb1-dev libxrandr-dev \
libxi-dev libxcursor-dev libxinerama-dev \
libxkbcommon-dev libxkbcommon-x11-dev libwayland-dev \
libegl1-mesa-dev libvulkan-dev- Windows: a normal Rust MSVC toolchain is recommended. Heroinn uses Schannel for TLS and does not require OpenSSL development packages.
- At runtime on Linux, the terminal component needs libX11, libxcb, libEGL, libwayland-client, libxkbcommon, and libvulkan.
- FreeBSD: Rust 1.100.0, Python 3.11, bash, perl5, gmake, pkgconf, OpenSSL and the
X11/Wayland/font/EGL/Vulkan desktop development libraries are required for the
default workspace. See
.github/scripts/freebsd-prepare.shfor the CI package list. FreeBSD 14.1 amd64 is the native compatibility test environment; default CI separately builds and tests 15.1. 14.1 is EOL:
git clone https://github.com/b23r0/Heroinn.git
cd Heroinn
cargo build --release --lockedThe build produces five executables:
heroinn— server GUIheroinn_client— agentheroinn_ftp— file managerheroinn_shell— terminal window used by interactive shell sessionsheroinn_socks5proxy— reverse SOCKS5 proxy GUI used by online agents
heroinn_shell, heroinn_ftp, and heroinn_socks5proxy must be placed next to
the heroinn executable. Reverse SOCKS5 locates its sidecar there first, with
the current working directory as a fallback, and requires agent capability.
Qualified single-file client templates use a separate client-only profile:
# Linux x86_64 (musl toolchain required)
bash scripts/build-static-client.sh
# Native FreeBSD amd64
bash scripts/build-native-static-client.sh
# Windows MSVC: powershell -File scripts/build-static-client.ps1Templates are written to $CARGO_TARGET_DIR/client-templates (or
target/client-templates). FreeBSD uses static ET_EXEC, vendored OpenSSL, and
the native static libkvm/libelf closure: no ELF interpreter, DT_NEEDED or extra
shared-library mappings are allowed. This is not a static-PIE/ASLR guarantee.
Kernel, trust/resolver data and /bin/sh remain runtime system facilities;
arbitrary third-party NSS/OpenSSL providers and cross-major ABI compatibility
are not promised.
The server's Generator tab does not compile an agent. It copies a prebuilt
heroinn_client and rewrites its embedded connection stamp in place.
For TCP and HTTP agents, the Generator can also embed an optional SOCKS5 proxy. If the generated agent discovers a system proxy, it connects through the system proxy to the configured SOCKS5 proxy and then to the server, forming a proxy chain. SOCKS5 settings are not available for UDP agents. Any SOCKS5 credentials are embedded in the generated client binary and may be extractable.
Templates are searched next to the running heroinn executable first, then in
the current working directory. The GUI label is exactly FreeBSD_x86_64 for
FreeBSD. Copy the audited template explicitly into either search directory:
| Platform | Template names |
|---|---|
| Windows x86_64 | heroinn_client_windows_static.exe (preferred), heroinn_client_windows.exe, heroinn_client.exe |
| Linux x86_64 | heroinn_client_linux_static (preferred), heroinn_client_linux, heroinn_client |
| FreeBSD x86_64 | heroinn_client_freebsd_static (preferred), heroinn_client_bsd, heroinn_client |
All names, including legacy aliases, require the matching unique HRNNSTC1
qualification, unique connection record and required SOCKS capabilities. A normal
dynamic cargo build --release client, wrong-platform image or multiple-stamp
template is rejected, even if renamed. Generator copies a native audited image;
it does not cross-compile.
The generated executable inherits the template's permissions, including the Unix executable bit. Connection information is limited to 1024 bytes of JSON, and the generator rejects templates containing more than one valid stamp.
| Path | Purpose |
|---|---|
heroinn |
Server GUI and controller |
heroinn_client |
Cross-platform agent |
heroinn_core |
Shared application-core logic |
heroinn_util |
Protocol, transport, packet, and utility layers |
th3rd/heroinn_ftp |
File manager |
th3rd/heroinn_socks5proxy |
Reverse SOCKS5 proxy GUI and sidecar |
th3rd/heroinn_shell |
Terminal implementation used by heroinn_shell |
First-party crates use edition 2024 and share dependency versions pinned at the
workspace root in [workspace.dependencies]. Vendored terminal crates retain
their upstream editions.
Bug reports, feature suggestions, pull requests, and documentation improvements are welcome. Before opening a pull request, run the same checks used by CI:
cargo fmt -p heroinn_ftp -- --check
cargo metadata --format-version 1 --locked --no-deps
cargo check --workspace --lib --bins --locked
cargo clippy -p heroinn -p heroinn_client -p heroinn_core -p heroinn_util -p heroinn_ftp -p heroinn_socks5proxy --all-targets --locked -- -D warnings
cargo test --workspace --exclude heroinn_shell_terminal --locked
cargo test -p heroinn_shell_terminal --lib --locked
cargo test -p heroinn_shell_config_derive --test config --locked
cargo build --workspace --release --locked
HEROINN_CLIENT_TEMPLATE=target/release/heroinn_client \
cargo test -p heroinn_util --test real_client_template --locked -- --ignored --exact patches_a_real_client_templateOn Windows PowerShell, set
$env:HEROINN_CLIENT_TEMPLATE = "target/release/heroinn_client.exe" before running
the same test command.
Default CI includes the original five Linux/Windows jobs and FreeBSD 15.1 Test and Release build. The latter also builds/audits the static client, runs its actual template test and exercises generated TCP/HTTP/UDP clients with live-load auditing. Native FreeBSD compatibility entry points (shared Cargo target) are:
python3.11 .github/scripts/freebsd-ci.py test --expected-release 14.1 --offline
python3.11 .github/scripts/freebsd-ci.py release --expected-release 14.1 --offlineJoin the community on Discord.
Heroinn is distributed under the GNU General Public License v3.0. The project logo is an original asset distributed with the project under the same license.
