GNAT-o-sphere / behavior analytics

SenseGNAT

Behavior analytics companion to GNAT. Builds per-entity baselines from normalized network telemetry, runs explainable detectors against those baselines, and emits STIX 2.1 findings back into GNAT via TAXII 2.1.

Behavior is the signal.

Source: github.com/wrhalpin/SenseGNAT.

---

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 SenseGNAT → tutorials/01 — Getting started
• Writing a custom adapter → tutorials/02 — Write a custom adapter
• Adding a new detector → how-to/add-a-detector
• Pushing findings into GNAT → how-to/integrate-with-gnat
• Understanding the architecture → explanation/architecture
• Looking up a data type → reference/data-model

---

What SenseGNAT does, end to end

1. Ingest — an EventAdapter reads telemetry from any source (Zeek conn.log, Suricata EVE JSON, CSV, Splunk REST API, GNAT’s live Kafka telemetry topic, or custom) and yields NormalizedNetworkEvent objects with a consistent five-tuple schema.

2. Profile — ProfileBuilder aggregates events into per-entity BehaviorProfile objects. Profiles are seeded from YAML policy rules before telemetry arrives, so day-one traffic to approved destinations is never flagged as anomalous.

3. Detect — four stateless, explainable detectors run against each event and its profile:
   • RareDestinationDetector — flags destinations absent from the entity’s baseline.
   • PeerDeviationDetector — flags destinations unique to one entity within its peer group.
   • PolicyViolationDetector — flags traffic that violates an explicit allow-list rule.
   • TimeWindowDriftDetector — flags a burst of new destinations in the current batch relative to the established baseline size.

4. Narrate — NarrativeBuilder rolls per-entity findings into a Narrative with severity rollup, type frequency, and a human-readable summary.

5. Publish — GNATConnector converts findings to STIX 2.1 Indicator objects and narratives to STIX 2.1 Note objects, then POSTs them as STIX bundles to the GNAT TAXII 2.1 collection endpoint.

---

Key design choices

• Explainability first. Every Finding carries a summary (human-readable sentence) and an evidence dict (the specific data that triggered it). Analysts know exactly what to look at. Rationale: explanation/explainability-first.

• Policy-guided baselining. Policy seeds the baseline with known-good patterns before telemetry arrives, solving the cold-start problem. Telemetry then refines the baseline over time. Rationale: explanation/policy-guided-baselining.

• Profile accumulation across runs. BehaviorProfile.merge() unions observation sets on every write, so baselines grow without losing history.

• STIX 2.1 as the output contract. Findings surface in GNAT as standard Indicator and Note objects with x_gnat_* telemetry properties and x_sensegnat_* behavioral metadata. See: reference/gnat-connector.

• Standalone by design. SenseGNAT integrates with GNAT via connector contract — it does not modify GNAT core. Independent release cadence, independent storage, independent scheduling.

---

What’s implemented

Area	Component
Adapters	SampleEventAdapter, CsvEventAdapter, ZeekConnLogAdapter, SuricataEveAdapter, GNATTelemetryAdapter, SplunkEventAdapter
Detectors	RareDestinationDetector, PeerDeviationDetector, PolicyViolationDetector, TimeWindowDriftDetector
Storage	InMemoryProfileStore, InMemoryFindingStore, JsonProfileStore, JsonFindingStore
Policy	PolicyEngine — YAML-driven group/subject allow-lists with peer-group assignment
Narrative	NarrativeBuilder — per-entity severity rollup and type-frequency summary
Connector	GNATConnector — STIX 2.1 Indicator + Note, TAXII 2.1 POST with Bearer auth
Config	SenseGNATSettings — Pydantic model, YAML loader
Tests	322 passing tests

---

Status

All three phases are complete. Six source adapters, four explainable detectors, a fully-wired GNAT connector, a live Kafka telemetry adapter, and a Splunk REST API adapter are shipped. Profile accumulation, policy-guided baselining, and narrative building are complete. SenseGNAT now operates as a bidirectional partner to GNAT: consuming raw sensor telemetry from GNAT’s Kafka topic and publishing behavioral findings back into GNAT via TAXII 2.1.

---

The GNAT-o-sphere

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

Core Platform

GNAT

The hub platform for threat intelligence. Connector abstraction, STIX 2.1 modeling, reports, investigations, and workflow automation.

Learn more

Addon

SandGNAT

Automated malware sandbox analysis — detonate binaries in isolated VMs, capture behavioral artifacts, emit STIX 2.1 objects.

Learn more

Addon

RedGNAT

Continuous automated readiness testing — ingest threat intel, construct adversary emulation scenarios, execute with safety controls.

Learn more

Interface

GNAT-gui

The visual interface for the GNAT ecosystem — investigation timelines, threat graphs, connector dashboards, and workflow management in a unified web UI.

Learn more

Canonical Workflow

Collect Telemetry & Sources

External indicators and raw network telemetry enter the ecosystem

→

Process GNAT

Ingest, normalize, convert to STIX, and route to addons

→

SenseGNAT

Behavioral profiling & anomaly detection

SandGNAT

Malware detonation & artifact enrichment

RedGNAT

Adversary emulation & validation

→

Report Investigate & Act

Unified investigation graph, reporting, and operator action

View full diagram → Read the workflow doc →

Licensed under Apache 2.0.