Documentation — Install, Usage & CLI | Hacksguard

Documentation

Everything you need to build, run, and integrate Hacksguard v0.3.0.

§ Installation

Requires Rust (stable) and Cargo. Clone with submodules to pull the YARA rulesets:

$ git clone --recursive https://github.com/Rhacknarok/hacksguard.git
$ cd hacksguard
$ cargo build --release

Already cloned without submodules?

$ git submodule update --init --recursive

The binary lands at target/release/hacksguard.

❄ Nix / NixOS

A package is available in Nixpkgs. Latest releases may only be in the unstable channel.

$ nix-env -iA nixos.hacksguard

§ Usage

Point Hacksguard at the binary you want to triage:

$ hacksguard path/to/binary.exe
$ cargo run --release -- path/to/binary.exe # from source

A progress gauge shows while the background threads work; the dashboard opens as soon as basic analysis completes. YARA streams its verdict in live, updating the global risk score with an animated spinner.

§ Keyboard shortcuts

{{ k.combo }}
{{ k.action }}

§ The nine tabs

{{ t.n }} {{ t.name }}
{{ t.desc }}

When an embedded PE is extracted from an overlay, press e to toggle the dynamic tabs (Headers, Sections, Imports, Disasm) between the parent and the embedded payload.

§ Analysis pipeline

The file is memory-mapped once (memmap2, zero-copy) and analyzed by independent threads. Nothing blocks the UI.

mmap
zero-copy buffer
─▶
{{ p.name }} {{ p.desc }}
─▶
Risk Engine
0–100 verdict → TUI / JSON

Within basic analysis, rayon parallelizes MD5 / SHA-1 / SHA-256 / byte distribution / string extraction on the same buffer. On Linux, jemalloc is the global allocator for faster YARA heap churn.

§ YARA rules

Signatures load recursively from rules/, tracked as git submodules:

elastic/protections-artifacts — production rules from Elastic Security, incl. the Adaptix trojan family
Neo23x0/signature-base — Florian Roth's signature base for THOR/LOKI scanners
  • Compiled rules are cached to .yara_cache with SHA-256 fingerprinting — subsequent launches skip recompilation.
  • Cache validation uses file metadata (size, mtime) for instant startup on large rulesets.
  • Any YARA match overrides the risk score to 100 / Critical.

§ CLI / JSON mode

For CI/CD gates and SIEM/SOAR ingestion, skip the TUI entirely:

$ hacksguard --json sample.exe > report.json
{
  "file": { "name": "sf.exe", "size": 94208, "type": "PE32+ EXE (x86-64)" },
  "hashes": { "md5": "9690468b…", "sha256": "aa3516dd…" },
  "risk": { "score": 100, "level": "Critical" },
  "yara_matches": [ "Windows_Trojan_Adaptix_b2cda978" ],
  "detections": [ "indirect_syscalls", "hidden_iat", "peb_walking" ],
  "entropy": { "global": 5.4801, "peak": 5.55 }
}

§ Dependencies

{{ d.name }}
{{ d.role }}
Next: Analyst Guide → Edit on GitHub