<!-- 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 — Malware Hash Enrichment

## VirusTotal API v3

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

### File Behavior Summary
```bash
curl -H "x-apikey: $VT_KEY" \
  "https://www.virustotal.com/api/v3/files/SHA256_HASH/behaviour_summary"
```

### Submit File for Scanning
```bash
curl -X POST "https://www.virustotal.com/api/v3/files" \
  -H "x-apikey: $VT_KEY" \
  --form file=@suspicious.exe
```

### Search by Imphash
```bash
curl -H "x-apikey: $VT_KEY" \
  "https://www.virustotal.com/api/v3/search?query=imphash:HASH"
```

**Rate Limits:** Free: 4 req/min, 500/day. Premium: 1000 req/min.

## MalwareBazaar API

**Base URL:** `https://mb-api.abuse.ch/api/v1/`

### Get Sample Info
```bash
curl -X POST "https://mb-api.abuse.ch/api/v1/" \
  -d "query=get_info&hash=SHA256_HASH"
```

### Query by Tag
```bash
curl -X POST "https://mb-api.abuse.ch/api/v1/" \
  -d "query=get_taginfo&tag=Emotet&limit=50"
```

### Query by Signature
```bash
curl -X POST "https://mb-api.abuse.ch/api/v1/" \
  -d "query=get_siginfo&signature=Cobalt Strike&limit=50"
```

### Download Sample
```bash
curl -X POST "https://mb-api.abuse.ch/api/v1/" \
  -d "query=get_file&sha256_hash=HASH" --output sample.zip
# Password: infected
```

## ThreatFox API

**Base URL:** `https://threatfox-api.abuse.ch/api/v1/`

### Search by Hash
```bash
curl -X POST "https://threatfox-api.abuse.ch/api/v1/" \
  -H "Content-Type: application/json" \
  -d '{"query":"search_hash","hash":"SHA256_HASH"}'
```

### Search by IOC
```bash
curl -X POST "https://threatfox-api.abuse.ch/api/v1/" \
  -d '{"query":"search_ioc","search_term":"evil.com"}'
```

## Hybrid Analysis API

### Quick Scan
```bash
curl -X POST "https://www.hybrid-analysis.com/api/v2/quick-scan/file" \
  -H "api-key: $HA_KEY" \
  -F "scan_type=all" -F "file=@sample.exe"
```

### Hash Summary
```bash
curl "https://www.hybrid-analysis.com/api/v2/overview/SHA256_HASH/summary" \
  -H "api-key: $HA_KEY"
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `VT_API_KEY` | VirusTotal API key |
| `HA_API_KEY` | Hybrid Analysis API key |
| `ANYRUN_API_KEY` | Any.Run API key |
