GNAT-o-sphere / malware sandbox
SandGNAT
Automated malware runtime-analysis environment: detonate suspicious binaries in isolated Windows VMs on Proxmox, cluster samples against the existing corpus via byte/opcode trigram MinHash, and emit STIX 2.1 objects into PostgreSQL.
Source: github.com/wrhalpin/SandGNAT.
Documentation
Organised with the Diátaxis framework. Four quadrants for four kinds of reader-intent:
| Action (doing) | Study (reading) | |
|---|---|---|
| Learning | Tutorials | Explanation |
| Working | How-to guides | Reference |
Start here if you’re…
- New to SandGNAT → tutorials/01 — Your first sample
- Standing up a dev stack → tutorials/02 — Local dev stack
- Curious about the architecture → explanation/architecture
- Integrating the export API → reference/http-api
What SandGNAT does, end to end
- Intake (
POST /submit) — validate, hash, dedupe against the existing corpus, VT hash pre-check, YARA scan, stage to SMB. - Static analysis (Linux VM, optional pre-stage) — PE/ELF parsing, ssdeep + TLSH fuzzy hashes, deep YARA, CAPA capability detection, strings + entropy, byte + opcode trigram MinHash.
- LSH similarity lookup — banded-candidate fetch then exact Jaccard. If the best hit clears the threshold (default 0.85), skip detonation.
- Windows detonation — ProcMon, tshark, RegShot, dropped-file collection.
- Artifact parsing → STIX 2.1 — deterministic UUIDv5 IDs, PostgreSQL JSONB storage.
- Export —
GET /analyses/<uuid>/bundleserves the STIX bundle to external consumers (the GNAT connector, analyst scripts, etc.).
Full architecture diagrams live in explanation/architecture — topology, pipeline flow, sequence, and component diagrams rendered via Mermaid.
Key design choices
- Isolation by default. Analysis bridge has no host IP. OPNsense default-denies egress; only INetSim and staging SMB are allowed. See explanation/isolation-model.
- STIX 2.1 as the output contract. Survives schema churn, plays nicely with every modern TIP. Rationale: explanation/why-stix.
- Byte + opcode trigram MinHash + LSH bands. Sub-linear similarity lookup over a growing corpus. Theory: explanation/similarity.
-
Near-duplicate short-circuit. Skip detonation when a submission is obviously a repacked variant of something we already analysed. Details: explanation/near-duplicate-short-circuit.
- Anti-analysis evasion posture. Catalogue of how modern malware detects sandboxes plus the phased mitigation plan for SandGNAT: explanation/anti-analysis-evasion.
Status
Phases 1–6 shipped: scaffold, host↔guest detonation protocol, intake, VM pool manager, Linux static-analysis + trigram similarity, the read-only export API, and the anti-analysis evasion mitigations (phases A–G). See explanation/anti-analysis-evasion for the full implementation record.
The GNAT-o-sphere
SandGNAT is one of three add-ons that plug into GNAT, the core threat-intel platform. Every sibling emits STIX 2.1 objects and is pulled by GNAT through a documented connector rather than writing into its database directly.
GNAT
The hub TIP. Connector abstraction, STIX 2.1 modelling, investigations, reports, and workflow automation across a large integration surface.
Learn moreGNAT-gui
Analyst workbench for GNAT — React SPA + FastAPI backend covering investigations, detection rules, evidence graphs, and live SSE streaming.
Learn moreRedGNAT
Continuous automated readiness testing — ingests threat intel, constructs adversary emulation scenarios, executes them with safety controls.
Learn moreSenseGNAT
NNetwork profiling and behavior analysis that surfaces anomalies and enriches GNAT investigations with traffic-layer context using network sensor and honeypot telemetry — high-volume ingestion from Kafka topics, Redis dedup, automatic campaign linking.
Learn moreCanonical Workflow
Licensed under Apache 2.0.