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

## VirusTotal API v3

**Base URL:** `https://www.virustotal.com/api/v3`

### IP Address Report
```bash
curl -H "x-apikey: $VT_API_KEY" \
  "https://www.virustotal.com/api/v3/ip_addresses/1.2.3.4"
```

### Domain Report
```bash
curl -H "x-apikey: $VT_API_KEY" \
  "https://www.virustotal.com/api/v3/domains/evil.com"
```

### File Hash Report
```bash
curl -H "x-apikey: $VT_API_KEY" \
  "https://www.virustotal.com/api/v3/files/SHA256_HASH"
```

### Rate Limits
- Free: 4 requests/min, 500/day
- Premium: 1000 requests/min

## Shodan API

**Base URL:** `https://api.shodan.io`

### Host Lookup
```bash
curl "https://api.shodan.io/shodan/host/1.2.3.4?key=$SHODAN_KEY"
```

### Search
```bash
curl "https://api.shodan.io/shodan/host/search?key=$SHODAN_KEY&query=product:nginx+country:RU"
```

### DNS Resolve
```bash
curl "https://api.shodan.io/dns/resolve?hostnames=evil.com&key=$SHODAN_KEY"
```

## GreyNoise API

**Base URL:** `https://api.greynoise.io/v3`

### Community IP Lookup (Free)
```bash
curl -H "key: $GREYNOISE_KEY" \
  "https://api.greynoise.io/v3/community/1.2.3.4"
```

**Response fields:**
- `noise`: true if seen scanning the internet
- `riot`: true if known benign service (Google, Cloudflare)
- `classification`: benign | malicious | unknown

## AbuseIPDB API

**Base URL:** `https://api.abuseipdb.com/api/v2`

### Check IP
```bash
curl -G "https://api.abuseipdb.com/api/v2/check" \
  -d "ipAddress=1.2.3.4" -d "maxAgeInDays=90" \
  -H "Key: $ABUSEIPDB_KEY" -H "Accept: application/json"
```

### Report IP
```bash
curl "https://api.abuseipdb.com/api/v2/report" \
  -H "Key: $ABUSEIPDB_KEY" \
  --data-urlencode "ip=1.2.3.4" \
  --data-urlencode "categories=18,22" \
  --data-urlencode "comment=C2 callback observed"
```

## MISP REST API

### Add Attribute
```bash
curl -X POST "$MISP_URL/attributes/add/0" \
  -H "Authorization: $MISP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"1.2.3.4","type":"ip-dst","to_ids":true,"comment":"Enriched IOC"}'
```

### Search Attributes
```bash
curl -X POST "$MISP_URL/attributes/restSearch" \
  -H "Authorization: $MISP_KEY" \
  -d '{"value":"evil.com","type":"domain"}'
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `VT_API_KEY` | VirusTotal API key |
| `SHODAN_API_KEY` | Shodan API key |
| `GREYNOISE_API_KEY` | GreyNoise API key |
| `ABUSEIPDB_KEY` | AbuseIPDB API key |
| `MISP_URL` | MISP instance URL |
| `MISP_KEY` | MISP automation key |
