GNAT Architecture Decision Records

A single reference for every design decision made during development, including tradeoffs, alternatives considered, and implementation notes. Use this when testing, implementing new connectors, or extending existing subsystems.

Phase 4 — Control, Reasoning, Safety

Detection, Attribution & Telemetry

Cross-Tool Integration

GUI Foundation

Quick Reference: Adding a New Connector

# 1. Generate scaffold
gnat-codegen --spec platform-openapi.json --name myplatform --auth oauth2

# 2. Implement in gnat/connectors/myplatform/client.py
#    - authenticate()
#    - to_stix(native) → dict with type, id, created, modified
#    - from_stix(stix_dict) → platform-native payload
#    - health_check()
#    - get_object(), list_objects(), upsert_object(), delete_object()

# 3. Register sync connector
# gnat/clients/__init__.py:
CLIENT_REGISTRY["myplatform"] = MyplatformClient

# 4. Add async mirror
# gnat/async_client/connectors.py: add AsyncMyplatformClient
# gnat/async_client/client.py: add to _build_async_registry()

# 5. Add INI section to config/config.ini.example

# 6. Add [global.myplatform] block to ADR-0013 (0013-ADR-configuration.md)

# 7. Run tests
pytest tests/unit/connectors/ -v

Quick Reference: Adding a New Ingest Source

# SourceReader subclass
class MyReader(SourceReader):
    def _iter_records(self) -> Iterator[RawRecord]:
        # yield plain dicts

# RecordMapper subclass
class MyMapper(RecordMapper):
    def map(self, record: RawRecord) -> Iterator[STIXBase]:
        # yield STIXBase objects using self._client, self.tlp_marking, self.confidence

# Register in:
# gnat/ingest/sources/__init__.py
# gnat/ingest/mappers/__init__.py
# gnat/__init__.py (both __all__ and import)

Quick Reference: Workspace Investigation Workflow

from gnat import GNATClient
from gnat.context import WorkspaceManager, GlobalContextRegistry

# Setup (once per session)
tq = GNATClient().connect("threatq")
rf = GNATClient().connect("recordedfuture")  # read-only
cs = GNATClient().connect("crowdstrike")

manager = WorkspaceManager.from_clients(
    {"threatq": tq, "rf": rf, "crowdstrike": cs},
    default="threatq",
    read_only=["rf"],
)

# Investigation
ws = manager.get_or_create("campaign-name")
ws.load("indicator", filters={"tags": "apt28"})

ws.enrich(
    sources=["rf", "crowdstrike"],
    strategy="create_relationships",  # preserves provenance
    confidence_floor=60,
)

print(ws.diff())            # what changed
result = ws.commit()        # write back to ThreatQ
print(result)

# Visualize
from gnat.viz import TabularView, GraphView
TabularView(ws).show()
GraphView(ws).to_html("graph.html")  # auto-selects sigma.js at scale

Licensed under the Apache License, Version 2.0

GNAT Architecture Decision Records

GNAT's Not A TIP — unified Python library for cyber threat intelligence across 159 security platforms. STIX 2.1 ORM, investigations, reports, rule engine, campaign tracking. Documentation organised with the Diataxis framework.

GNAT Architecture Decision Records

Table of Contents

Phase 4 — Control, Reasoning, Safety

Detection, Attribution & Telemetry

Cross-Tool Integration

GUI Foundation

Quick Reference: Adding a New Connector

Quick Reference: Adding a New Ingest Source

Quick Reference: Workspace Investigation Workflow