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

# API Reference — Implementing Link Sandboxing

## Agent Script

### Commands

| Command | Description |
|---|---|
| `node agent.js extract-urls --email <file>` | Extract and categorize URLs from email |
| `node agent.js expand-url --url <url>` | Expand shortened URL |
| `node agent.js batch-expand --url-file <file>` | Batch expand URLs from file |
| `node agent.js detonate --url <url> --sandbox <provider> --api-key <key>` | Submit URL for detonation |
| `node agent.js verdict --scan-id <id> --sandbox <provider>` | Retrieve detonation verdict |
| `node agent.js generate-policy --provider <m365>` | Generate Safe Links policy |
| `node agent.js audit-coverage --mail-log <csv>` | Audit URL rewriting coverage |
| `node agent.js generate-alert --verdict <val> --url <url> --recipient <email>` | Generate SIEM alert |

### Examples

```bash
# Extract URLs from suspicious email
node agent.js extract-urls --email /tmp/suspect.eml

# Detonate URL in urlscan.io sandbox
node agent.js detonate --url "https://suspicious.com/login" \
  --sandbox urlscan --api-key "${URLSCAN_API_KEY}"

# Check verdict
node agent.js verdict --scan-id "abc123" --sandbox urlscan

# Generate M365 Safe Links policy
node agent.js generate-policy --provider m365 --track-clicks true
```

## Sandbox API Reference

| Provider | Submit Endpoint | Verdict Endpoint |
|---|---|---|
| urlscan.io | `POST https://urlscan.io/api/v1/scan/` | `GET https://urlscan.io/api/v1/result/{id}/` |
| VirusTotal | `POST https://www.virustotal.com/api/v3/urls` | `GET https://www.virustotal.com/api/v3/analyses/{id}` |
