Merge pull request #128 from wrhalpin/claude/create-gnat-admin-guide-BOSrp

Add Cuckoo Sandbox / CAPEv2 connector with dual API support

Author: wrhalpin

CHANGELOG.md

@@ -19,6 +19,33 @@ all v1.4+ modules.
 → Full feature breakdown is in `## [1.4.0]` below; this entry marks the version cut.
 ## [Unreleased]
 
+### Added — Cuckoo Sandbox / CAPEv2 connector
+
+New `gnat/connectors/cuckoo/` connector for dynamic malware analysis.
+Supports both the legacy Cuckoo 2.x API (`/api/`) and CAPEv2/3.x
+(`/apiv2/`) with auto-detection at `authenticate()` time. Platform
+count: 158 → 159.
+
+- `CuckooClient` — Bearer token auth. STIX type map: observed-data,
+  malware, indicator. Version-specific endpoint routing via
+  `self._prefix`. Auto-detection probes `/apiv2/cuckoo/status/` first
+  (CAPEv2 is more common); falls back to v2 on failure. Optional
+  `api_version` constructor override skips detection.
+- Domain helpers: `submit_file()`, `submit_url()`, `get_report()`,
+  `get_task_view()`, `get_iocs()`, `iocs_to_indicators()`,
+  `list_machines()`, `get_pcap()`.
+- IOC extraction: walks `network.hosts` (IPs), `network.domains`
+  (domains), `network.http` (URLs), `dropped` (SHA-256 hashes),
+  `network.dns.answers` (resolved IPs), and CAPEv2
+  `signatures[*].marks[*].ioc` (signature-extracted IOCs).
+  Deduplicates by type+value.
+- STIX mapping: `sandbox_report_envelope()` for observed-data with
+  processes, contacted IPs/domains/URLs, verdict from score mapping
+  (0-3→clean, 4-6→suspicious, 7+→malicious). Malware SDO from
+  `malfamily`/`detections` fields. Indicator SDOs via
+  `make_indicator_pattern()`.
+- 22 new tests in `TestCuckooClient`.
+
 ### Added — Sensor/telemetry ingestion module (`gnat[telemetry]`)
 
 New `gnat/ingest/telemetry/` package for high-volume honeypot, netflow,

CLAUDE.md

@@ -31,7 +31,7 @@ gnat/                        # Main Python package
 ├── orm/                     # STIX 2.1 ORM (STIXBase + 8 object types)
 ├── stix/                    # STIX pattern validation (stix2-patterns integration)
 ├── clients/                 # HTTP client layer (urllib3 BaseClient + CLIENT_REGISTRY)
-├── connectors/              # 158 platform connectors (ThreatQ, CrowdStrike, Splunk, etc.)
+├── connectors/              # 159 platform connectors (ThreatQ, CrowdStrike, Splunk, etc.)
 ├── ingest/                  # Multi-source ingestion pipeline (14 readers, 12 mappers)
 │   └── telemetry/           # High-volume sensor ingestion (Kafka reader, Redis dedup, campaign auto-link)
 ├── export/                  # Export pipeline (EDL, Netskope CE delivery targets)
@@ -352,6 +352,7 @@ Prefer mocking at the HTTP layer (`mock_pool_manager`) rather than patching indi
 | Hybrid Analysis / Falcon Sandbox | `gnat/connectors/hybrid_analysis/` | API key + User-Agent header |
 | VMRay (hypervisor-level analysis) | `gnat/connectors/vmray/` | API key (`api_key` header) |
 | Intezer Analyze (binary DNA attribution) | `gnat/connectors/intezer/` | API key → JWT Bearer |
+| Cuckoo Sandbox / CAPEv2 (dynamic malware analysis) | `gnat/connectors/cuckoo/` | Bearer token |
 | Huntress Managed EDR / ITDR | `gnat/connectors/huntress/` | HTTP Basic (key id + secret) |
 | Arctic Wolf MDR | `gnat/connectors/arctic_wolf/` | Bearer token (+ optional customer id) |
 | Red Canary MDR | `gnat/connectors/red_canary/` | API key (`X-Api-Key` header) |

README.md

@@ -52,7 +52,7 @@ GNAT provides a single, consistent abstraction layer over 158 platforms — thre
 
 | Layer | What it does |
 |-------|-------------|
-| **158 Connectors** | Uniform CRUD + bidirectional STIX 2.1 translation for every supported platform |
+| **159 Connectors** | Uniform CRUD + bidirectional STIX 2.1 translation for every supported platform |
 | **STIX 2.1 ORM** | Indicator, ThreatActor, Vulnerability, Malware, AttackPattern, Relationship, Observables |
 | **Ingest Pipelines** | 15 source readers × 13 mappers; pull from any platform, file, feed, database, or Kafka topic |
 | **Export Pipelines** | EDL files, Netskope CE, STIX bundles, CSV; configurable filters + transforms + delivery |
@@ -245,6 +245,7 @@ GNAT provides a single, consistent abstraction layer over 158 platforms — thre
 | `hybrid_analysis` | Hybrid Analysis / Falcon Sandbox | API key + User-Agent header |
 | `vmray` | VMRay (hypervisor-level analysis) | API key (`api_key` header) |
 | `intezer` | Intezer Analyze (binary DNA attribution) | API key → JWT Bearer |
+| `cuckoo` | Cuckoo Sandbox / CAPEv2 (dynamic malware analysis) | Bearer token |
 
 ### Managed Detection & Response (MDR)
 

config/config.ini.example

@@ -1232,6 +1232,13 @@ api_key = YOUR_HTTPBL_ACCESS_KEY
 [crtsh]
 host = https://crt.sh
 
+# --- Cuckoo Sandbox / CAPEv2 (dynamic malware analysis) --------------------
+# Supports both Cuckoo 2.x and CAPEv2/3.x APIs (auto-detected).
+[cuckoo]
+host        = https://cuckoo.lab.internal
+api_key     = <your-cuckoo-api-key>
+# api_version = 3     ; optional — auto-detected if omitted
+
 # --- Google Certificate Transparency log API -------------------------------
 # No authentication required. ``log`` is the path to a specific CT log
 # operated by Google (Argon, Xenon, etc.).

gnat/clients/__init__.py

@@ -42,6 +42,7 @@
 from gnat.connectors.cribl.client import CriblClient
 from gnat.connectors.crowdstrike.client import CrowdStrikeClient
 from gnat.connectors.crtsh.client import CrtShClient
+from gnat.connectors.cuckoo.client import CuckooClient
 from gnat.connectors.cyble_vision.client import CybleVisionClient
 from gnat.connectors.cycognito.client import CyCognitoClient
 from gnat.connectors.cymulate.client import CymulateClient
@@ -339,6 +340,7 @@
     "project_honey_pot": ProjectHoneyPotClient,
     # Phase 2 Wave 9 — Cert transparency + DFIR + bug bounty
     "crtsh": CrtShClient,
+    "cuckoo": CuckooClient,
     "google_ct": GoogleCTClient,
     "velociraptor": VelociraptorClient,
     "magnet_axiom": MagnetAxiomClient,

gnat/connectors/cuckoo/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Bill Halpin
+"""
+gnat.connectors.cuckoo
+=========================
+
+Cuckoo Sandbox / CAPEv2 connector — automated malware analysis with
+behavioral reports, IOC extraction, and STIX indicator generation.
+Supports both Cuckoo 2.x and CAPEv2/3.x APIs with auto-detection.
+"""
+
+from .client import CuckooClient
+
+__all__ = ["CuckooClient"]