Skip to content
b23r0Public

About

A cross platform C2/post-exploitation framework.

Topics

Resources

Stars

732 stars

Watchers

28 watching

Forks

Repository files navigation

Heroinn logo

English · 简体中文

CI License: GPL-3.0 Discord

Heroinn

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.

Heroinn server GUI

Features

  • 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.

Build

  • 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.sh for 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 --locked

The build produces five executables:

  • heroinn — server GUI
  • heroinn_client — agent
  • heroinn_ftp — file manager
  • heroinn_shell — terminal window used by interactive shell sessions
  • heroinn_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.ps1

Templates 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.

Client generation

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.

Workspace

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.

Contributing

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_template

On 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 --offline

Join the community on Discord.

License

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.

About

A cross platform C2/post-exploitation framework.

Topics

Resources

Stars

732 stars

Watchers

28 watching

Forks

Releases

Packages

Used by

Contributors

Languages