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

# API Reference — Analyzing Phishing Email Headers

## Agent Script

### Commands

| Command | Description |
|---|---|
| `node agent.js parse <file>` | Parse raw headers and extract key fields |
| `node agent.js extract-iocs <file>` | Extract IPs, domains, emails from headers |
| `node agent.js timeline <file>` | Build delivery timeline from Received headers |
| `node agent.js check-spoofing <file>` | Detect spoofing indicators |

### Examples

```bash
# Parse headers and show authentication results
node agent.js parse /tmp/phish_headers.txt

# Extract all IOCs for threat intel lookup
node agent.js extract-iocs /tmp/phish_headers.txt

# Build hop-by-hop delivery timeline
node agent.js timeline /tmp/phish_headers.txt

# Check for From/Reply-To/Return-Path mismatches
node agent.js check-spoofing /tmp/phish_headers.txt
```

## DNS Verification Commands

| Command | Purpose |
|---|---|
| `dig TXT domain.com \| grep spf` | Check SPF record |
| `dig TXT selector._domainkey.domain.com` | Check DKIM record |
| `dig TXT _dmarc.domain.com` | Check DMARC policy |
| `dig -x <ip>` | Reverse DNS lookup |
| `whois <ip>` | IP ownership and ASN |

## Key Header Fields

| Header | Analysis Purpose |
|---|---|
| `From` | Claimed sender identity |
| `Reply-To` | Actual reply destination (BEC indicator) |
| `Return-Path` | Envelope sender for bounces |
| `Received` | Relay chain — read bottom-to-top |
| `Authentication-Results` | SPF/DKIM/DMARC verdicts |
| `X-Originating-IP` | Source IP of submission |
| `Message-ID` | Domain consistency check |
| `X-Mailer` | Sending client fingerprint |
