<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Performing Phishing IR — API Reference

## Email Header Analysis

### Key Headers to Check

| Header | Purpose | Spoofing Indicator |
|--------|---------|-------------------|
| `From` | Displayed sender | Compare with Return-Path |
| `Return-Path` | Actual envelope sender | Domain mismatch = spoofing |
| `Reply-To` | Reply destination | Different domain = suspicious |
| `Received` | Mail hop chain | Read bottom-to-top |
| `Authentication-Results` | SPF/DKIM/DMARC | fail = not authenticated |
| `X-Originating-IP` | Sender IP | Geolocation mismatch |
| `Message-ID` | Unique identifier | For mailbox searches |

### SPF/DKIM/DMARC Check

```bash
# Check SPF record
dig TXT sender-domain.com | grep spf

# Check DKIM record
dig TXT selector._domainkey.sender-domain.com

# Check DMARC record
dig TXT _dmarc.sender-domain.com
```

## URL Analysis APIs

### URLScan.io

```bash
# Submit URL for scan
curl -X POST "https://urlscan.io/api/v1/scan/" \
  -H "API-Key: $URLSCAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://suspicious.com","visibility":"unlisted"}'

# Get scan results
curl -s "https://urlscan.io/api/v1/result/$SCAN_UUID/" | jq '{verdict: .verdicts.overall, page: .page}'
```

### VirusTotal — URL Check

```bash
# Encode URL to base64 (no padding)
URL_ID=$(echo -n "https://suspicious.com" | base64 -w0 | tr '+/' '-_' | tr -d '=')
curl -s "https://www.virustotal.com/api/v3/urls/$URL_ID" -H "x-apikey: $VT_KEY" | jq '.data.attributes.last_analysis_stats'
```

### WHOIS Domain Check

```bash
whois suspicious-domain.com | grep -iE "creation|registrar|registrant|updated"
```

## Attachment Analysis

### oletools (Office Macros)

```bash
# Analyze VBA macros
olevba suspicious.docx

# Check for auto-exec macros
mraptor suspicious.docx

# Extract embedded objects
oleobj suspicious.docx

# Decompress VBA streams
oledump.py suspicious.docx -s 7 -v
```

### File Hash Check

```bash
sha256sum attachment.docx
curl -s "https://www.virustotal.com/api/v3/files/$HASH" -H "x-apikey: $VT_KEY"
```

## M365 Email Management

### Message Trace

```powershell
# Trace phishing email delivery
Get-MessageTrace -SenderAddress "attacker@phishing.com" -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date)

# Search by subject
Get-MessageTrace -StartDate (Get-Date).AddDays(-7) | Where-Object {$_.Subject -like "*pattern*"}
```

### Compliance Search and Purge

```powershell
# Create search
New-ComplianceSearch -Name "PhishPurge" -ExchangeLocation All -ContentMatchQuery 'from:attacker@phish.com AND subject:"Invoice"'
Start-ComplianceSearch -Identity "PhishPurge"

# Preview results
Get-ComplianceSearch -Identity "PhishPurge" | Format-List

# Purge (soft delete)
New-ComplianceSearchAction -SearchName "PhishPurge" -Purge -PurgeType SoftDelete
```

## Common Patterns

### Phishing IR Workflow

```
1. Receive phishing report
2. Analyze email headers (SPF/DKIM/DMARC)
3. Extract and analyze URLs (URLScan, VT)
4. Extract and analyze attachments (oletools, sandbox)
5. Determine recipient scope (message trace)
6. Categorize: received / opened / clicked / submitted credentials
7. Block sender and URLs
8. Purge from all mailboxes
9. Reset compromised credentials
10. Notify affected users
```

### Key Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `sender_address` | Phishing sender email | `attacker@phish.com` |
| `subject_pattern` | Subject line pattern | `*Urgent Invoice*` |
| `url` | Phishing URL | `https://fake-login.com` |
| `attachment_hash` | SHA-256 of attachment | `abc123...` |
