<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Detecting Spear-Phishing Campaigns

## Agent Script

### Commands

| Command | Description |
|---|---|
| `node agent.js build-baseline --mail-log <csv> --days <n> --output <path>` | Build sender frequency baseline |
| `node agent.js score-message --headers <file> --baseline <file>` | Score message for spear-phishing risk |
| `node agent.js detect-impersonation --message <file> --executive-list <file>` | Detect VIP display name impersonation |
| `node agent.js detect-bec --message <file>` | Detect BEC financial request patterns |
| `node agent.js cluster-campaign --ioc-file <json> --window <days>d` | Cluster IOCs into campaigns |
| `node agent.js generate-sigma --detection-type <impersonation\|bec>` | Generate Sigma detection rule |

### Examples

```bash
# Build 90-day sender baseline
node agent.js build-baseline --mail-log /var/log/mail/flow.csv \
  --days 90 --output /tmp/sender_baseline.json

# Score a suspicious message
node agent.js score-message --headers /tmp/suspect.txt \
  --baseline /tmp/sender_baseline.json

# Check for executive impersonation
node agent.js detect-impersonation --message /tmp/suspect.txt \
  --executive-list /tmp/vip_names.txt

# Detect BEC patterns
node agent.js detect-bec --message /tmp/suspect.txt
```

## SIEM Detection Queries

| Platform | Query Purpose |
|---|---|
| Splunk | First-time sender to executives |
| KQL (Sentinel) | Display name impersonation |
| Elastic | Reply-to domain mismatch |
