AI-Powered Malware Triage — Static Analysis Only
HexTriage is a production-ready CLI tool for static malware triage. It combines PE parsing, string/YARA analysis, a weighted heuristics engine, and ML-based risk scoring using EMBER2024 pretrained LightGBM models — without executing samples.
- Primary CLI:
hextriage - Backward-compatible alias:
triage
SOC analysts often need fast answers: Is this file likely malicious? What evidence supports that? Is it a legitimate dual-use tool (LOLBin)?
HexTriage accelerates triage by combining static evidence + ML probability, while explicitly separating dual-use risk from maliciousness to reduce noisy false positives.
- PE Analysis: headers, sections, imports/exports, entropy, suspicious anomalies (e.g., RWX, abnormal sections)
- Strings Analysis: ASCII/UTF-16LE extraction with suspicious indicator matching (URLs, IPs, PowerShell patterns)
- YARA Scanning: rule-based matches with timeouts + safe error handling
- Heuristics Engine: weighted rules that combine analyzer signals into an interpretable score
- Optional Integrations: FLOSS (decoded strings) and capa (ATT&CK capabilities)
- EMBER2024 v3 features: 2568-dimensional vectors via
thrember - LightGBM models: supports pretrained
.modelfiles and artifact models - Safe usage: inference on static features only; no sample execution
- LOLBin awareness: identifies legitimate system tools with abuse potential (PowerShell, certutil, rundll32, regsvr32, etc.)
- Separates “abuse potential” from “malicious probability” to reduce false positives
- JSON reports (structured, versioned)
- HTML reports (collapsible sections, evidence-first layout)
ml list-models— finds pretrained thrember models and artifact modelsml validate-model— checks compatibility (feature dimension, required files)ml benchmark— evaluates a LightGBM model on vectorized EMBER2024 features (no binaries required)
- Static-only analysis (no execution, no emulation)
- File size limits and timeouts
- Defensive output (no offensive instructions)
┌─────────────┐
│ CLI (Typer)│
└──────┬──────┘
│
┌──────▼──────────────────┐
│ Orchestrator │
│ - Intake + limits │
│ - Analyzer coordination│
│ - ML inference │
└──────┬──────────────────┘
│
┌───┴────────────────────────┬──────────────────┐
│ │ │
┌──▼────────┐ ┌───────▼─────────┐ ┌────▼──────────┐
│ PE │ │ Strings + YARA │ │ Heuristics │
│ Analyzer │ │ FLOSS/capa (opt) │ │ Scoring │
└───────────┘ └──────────────────┘ └────┬──────────┘
│
┌──────▼───────┐
│ ML (EMBER2024)│
└──────┬───────┘
│
┌──────▼───────┐
│ Reports │
│ JSON + HTML │
└───────────────┘
python -m venv .venv
.venv\Scripts\activate
# Core install
pip install -e .
# ML dependencies (EMBER2024 / thrember)
pip install -e ".[ml]"mkdir ml\artifacts\ember2024 -Force | Out-Null
python -c "import thrember; thrember.download_models('ml/artifacts/ember2024')"Models are not committed to the repo. Download locally to
ml/artifacts/ember2024/.
pip install -e ".[ml]"
python -c "import thrember; thrember.download_models('ml/artifacts/ember2024')"
hextriage ml validate-model --model-path "ml/artifacts/ember2024"Enable in config.yaml:
ml:
enabled: true
model_path: "ml/artifacts/ember2024"
model_name: "EMBER2024_PE.model" # optional (auto for PE)Create config.yaml:
limits:
max_file_size_mb: 50
timeout_seconds: 300
yara_timeout_seconds: 60
subprocess_timeout_seconds: 120
yara:
rules_directory: "rules/"
ml:
enabled: true
model_path: "ml/artifacts/ember2024"
model_name: "EMBER2024_PE.model"
thresholds:
benign: 0.30
suspicious: 0.70
calibration: "none"
reporting:
include_safe_recommendations: truehextriage scan "C:\Windows\System32\notepad.exe" --out reports\notepad.json --html reports\notepad.htmlhextriage scan "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" --out reports\powershell.json --html reports\powershell.htmlExpected style of output:
- Verdict:
BENIGN - Dual-use:
YES (HIGH) - Malicious Probability: small % (model-based)
This benchmark evaluates the pretrained LightGBM model on vectorized EMBER2024 challenge features (no binaries are executed).
Command used:
hextriage ml benchmark -d data\ember2024_eval -s challenge -m ml\artifacts\ember2024\EMBER2024_all.model -o reports\benchmarks\benchmark_challenge.jsonOutput:
Benchmark Results
Dataset: data\ember2024_eval
Subset: challenge
Model: ml\artifacts\ember2024\EMBER2024_all.model
Dataset Statistics:
Samples: 6,315
Features: 2568
Label distribution: {1: 6315}
Prediction Statistics:
Mean: 0.6264
Median: 0.6888
Std: 0.3554
Min: 0.0003
Max: 0.9999
Fraction Above Thresholds:
>= 0.3: 0.7528 (75.28%)
>= 0.5: 0.6654 (66.54%)
>= 0.7: 0.4918 (49.18%)
>= 0.9: 0.3629 (36.29%)
Why this is credible and safe:
- Uses vectorized features only (no malware binaries needed for benchmarking).
- HexTriage performs static-only analysis and never executes samples.
- Results provide measurable evidence that the ML scoring flags a large fraction of challenge samples at practical thresholds.
verdict:BENIGN/SUSPICIOUS/MALICIOUSdecision_confidence:HIGH/MODERATE/LOWdual_useandabuse_potential: dual-use detection signalmalicious_probability: model probability (0.0–1.0)heuristics: triggered rules + weighted scoring evidence
pytest -q
ruff check src tests
black src tests- Add ROC-AUC / PR-AUC / confusion matrix to
ml benchmarkwhen labels include both 0 and 1 - Improve “explanation” layer: top evidence contributors (rules + indicators)
MIT License.
STATIC TRIAGE ONLY: HexTriage performs static analysis only and never executes, emulates, or runs samples. Use for defensive security purposes only and comply with applicable laws and policies.