Document machine-readable output fields for scripting (to_json, to_ioc_format, suspicious_connections, iocs)

API_REFERENCE.md

@@ -306,6 +306,73 @@ Dataclass containing analysis results.
 | `service_type` | str | Detected service type |
 | `recommendations` | List[str] | Suggested follow-up actions |
 | `features` | List[float] | Raw 40-dimensional feature vector |
+| `connections_analyzed` | int | Number of connections processed |
+| `suspicious_connections` | List[Dict] | All connections with individual scores (if C2 detected) |
+| `iocs` | Dict | Extracted IOCs for threat intel (if C2 detected) |
+| `time_range` | Dict | Start, end, and duration of analyzed traffic |
+| `destination_summary` | Dict | Destination IPs, ports, and byte totals |
+
+### Machine-Readable Output Fields
+
+When C2 is detected, these fields are populated for scripting and automation:
+
+**suspicious_connections** - List of all connections with scores:
+```python
+[
+    {
+        'index': 0,
+        'timestamp': 1705600000,
+        'src_ip': '192.168.1.100',
+        'src_port': 52341,
+        'dst_ip': '45.33.32.156',
+        'dst_port': 443,
+        'bytes_sent': 200,
+        'bytes_recv': 500,
+        'score': 0.92
+    },
+    ...
+]
+```
+
+**iocs** - Indicators of Compromise for threat intel:
+```python
+{
+    'ip_addresses': ['45.33.32.156'],
+    'ports': [443],
+    'c2_type': 'cobalt_strike',
+    'timing_signature': {
+        'mean_interval': 60.0,
+        'interval_cv': 0.05
+    },
+    'size_signature': {
+        'mean_bytes_sent': 200.0,
+        'mean_bytes_recv': 500.0,
+        'sent_cv': 0.02,
+        'recv_cv': 0.03
+    },
+    'behavioral_indicators': ['Regular timing with consistent sizes', ...]
+}
+```
+
+**time_range** - Temporal bounds of analyzed traffic:
+```python
+{
+    'start': 1705600000.0,
+    'end': 1705600420.0,
+    'duration': 420.0
+}
+```
+
+**destination_summary** - Traffic summary:
+```python
+{
+    'unique_ips': ['45.33.32.156'],
+    'unique_ports': [443],
+    'destinations': {'45.33.32.156:443': 8},
+    'total_bytes_sent': 1600,
+    'total_bytes_recv': 4000
+}
+```
 
 ### Methods
 
@@ -321,6 +388,68 @@ Convert result to dictionary.
 
 ---
 
+#### to_json
+
+```python
+def to_json(self, indent: int = 2) -> str
+```
+
+Convert result to JSON string for scripting.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `indent` | int | 2 | JSON indentation level |
+
+**Returns:** JSON string of all attributes
+
+**Example:**
+```python
+result = sentinel.analyze(connections)
+json_output = result.to_json()
+
+# Write to file
+with open('detection_result.json', 'w') as f:
+    f.write(result.to_json())
+
+# Parse in pipeline
+import json
+data = json.loads(result.to_json())
+```
+
+---
+
+#### to_ioc_format
+
+```python
+def to_ioc_format(self) -> Dict[str, Any]
+```
+
+Convert result to STIX-like format for threat intelligence platforms.
+
+**Returns:**
+```python
+{
+    'type': 'indicator',
+    'spec_version': '2.1',
+    'pattern_type': 'c2-beacon',
+    'valid_from': timestamp,
+    'labels': ['malicious-activity', 'c2'],
+    'confidence': 92,
+    'indicators': { ... }  # Same as iocs field
+}
+```
+
+**Example:**
+```python
+result = sentinel.analyze(connections)
+if result.is_c2:
+    stix_indicator = result.to_ioc_format()
+    # Send to threat intel platform
+    send_to_misp(stix_indicator)
+```
+
+---
+
 ## ConnectionContext Class
 
 Dataclass for providing additional context to improve detection accuracy.