psyc/docs/archive/waypoints.md

# API-Eligible Cyber Threat Reporting & Escalation Platforms

**Project purpose:** Build a white-hat defensive reporting workflow that can push credible pre-incident or incident intelligence to the right receivers through APIs or structured machine-to-machine channels.

**Scope:** This document focuses on platforms that support API-based reporting, submission, alert ingestion, or structured intelligence sharing. It excludes direct interaction with criminal forums and excludes sources that only provide manual web forms unless they are still operationally important as a fallback.

**Last reviewed:** 2026-05-13

---

## 1. Recommended Reporting Order

### 1.1 Normal credible threat against a named organization

1. **Victim security contact / VDP / security.txt**
2. **National CERT / CSIRT**
3. **Sector ISAC / ISAO**
4. **Law enforcement cyber unit**
5. **Infrastructure provider abuse API**
6. **Threat-intelligence sharing platform**
7. **Sanitized public advisory**

### 1.2 Imminent harm or critical infrastructure

1. **National CERT / CSIRT**
2. **Victim security team**
3. **Law enforcement cyber unit**
4. **Sector regulator / ISAC**
5. **Infrastructure provider abuse API**
6. **Trusted CTI community**
7. **Public advisory only after mitigation or authority clearance**

### 1.3 Malicious infrastructure, phishing, malware, or botnet indicators

1. **Platform-specific reporting API**  
   Examples: Cloudflare Abuse Reports API, Spamhaus Submission API, AbuseIPDB, URLhaus, MalwareBazaar, PhishTank, urlscan.io, Google Web Risk, VirusTotal.
2. **CERT / CSIRT**
3. **Affected victim**
4. **MISP / OpenCTI / trusted CTI sharing**
5. **Public sanitized report**

---

## 2. Tier-1 API Reporting Platforms

These are the strongest fits for automated defensive reporting because they accept machine-readable submissions or support structured threat sharing.

| Priority | Platform | Best for | API / submission capability | Use in workflow |
|---:|---|---|---|---|
| 1 | **CISA Automated Indicator Sharing (AIS)** | Sharing cyber threat indicators with U.S. government and AIS participants | STIX/TAXII bidirectional indicator sharing | High-confidence indicators, especially campaigns, exploited infrastructure, malware IOCs |
| 2 | **MISP** | Community and private threat-intelligence sharing | REST API, PyMISP, event and attribute creation | Share vetted IOCs, TTPs, victim-agnostic campaign intelligence |
| 3 | **OpenCTI** | Internal or consortium CTI knowledge base | GraphQL API and connectors | Normalize, enrich, and route intelligence before external disclosure |
| 4 | **Cloudflare Abuse Reports API** | Abuse hosted behind or involving Cloudflare | API supports submitting abuse reports, viewing report details, and listing reports | Phishing, malware, abusive hosting, malicious domains using Cloudflare services |
| 5 | **Spamhaus Submission Portal API** | Malicious IPs, domains, URLs, suspicious email content | REST API for suspicious IP/domain/URL/email reports | Reputation/blocklist contribution and takedown-support evidence |
| 6 | **AbuseIPDB** | Malicious IP reputation | API for reporting and checking abusive IP addresses | Scanner, brute-force, spam, probing, attack-source IP reporting |
| 7 | **URLhaus / abuse.ch** | Malware distribution URLs | Community API for downloading and submitting malware URLs | Active malware URL reporting and malware-distribution tracking |
| 8 | **MalwareBazaar / abuse.ch** | Malware sample exchange | Community API for sample upload/download and bulk queries | Malware sample submission and hash enrichment |
| 9 | **PhishTank** | Phishing URL verification | API for phishing URL status checks; community submission workflow | Phishing verification and enrichment |
| 10 | **urlscan.io** | URL detonation, phishing/malware page evidence | Submission API to scan URLs and retrieve results | Safe screenshot/evidence generation, IOC enrichment |
| 11 | **Google Web Risk Submission API** | Unsafe URL submission to Google Safe Browsing ecosystem | Submission API for suspected unsafe URLs; access requires sales/customer-engineer approval | High-scale malicious URL reporting |
| 12 | **VirusTotal API** | File, URL, domain, IP enrichment and submission | API for file upload, URL scan, reports, and comments | Enrichment and submission to multi-vendor analysis ecosystem |
| 13 | **Netcraft Report API** | Phishing, malware, suspicious URLs, emails, files | API for automated threat reporting | Brand abuse, phishing, takedown-support reporting |

---

## 3. Platform Notes

### 3.1 CISA Automated Indicator Sharing (AIS)

**Type:** Government-backed indicator sharing  
**Best for:** High-confidence cyber threat indicators and defensive measures  
**API style:** STIX/TAXII  
**Good submissions:** IPs, domains, URLs, hashes, malware indicators, campaign indicators  
**Avoid:** Victim-identifying details unless necessary and authorized  

**Operational fit:** Use for campaign-level and infrastructure-level reporting, especially when the intelligence may protect multiple organizations.

Source: https://www.cisa.gov/how-automated-indicator-sharing-ais-works

---

### 3.2 MISP

**Type:** Open-source threat-intelligence sharing platform  
**Best for:** Structured CTI sharing inside trusted communities  
**API style:** REST API; PyMISP client  
**Good submissions:** Events, attributes, galaxies, taxonomies, TLP-tagged indicators, sightings  
**Avoid:** Raw stolen data, credentials, or victim-sensitive artifacts without permission  

**Operational fit:** Use as the main trusted-community sharing layer.

Sources:
- https://www.misp-project.org/openapi/
- https://www.circl.lu/doc/misp/automation/

---

### 3.3 OpenCTI

**Type:** Threat-intelligence platform / knowledge graph  
**Best for:** Internal CTI normalization, enrichment, and case-to-intel routing  
**API style:** GraphQL API  
**Good submissions:** STIX-like entities, observables, reports, relationships, indicators, malware, threat actors  
**Avoid:** Treating OpenCTI itself as the final external reporting destination unless connected to a sharing community  

**Operational fit:** Use as your central intelligence brain before pushing to MISP, CERTs, providers, or reports.

Sources:
- https://docs.opencti.io/latest/
- https://docs.opencti.io/latest/reference/api/

---

### 3.4 Cloudflare Abuse Reports API

**Type:** Infrastructure provider abuse reporting  
**Best for:** Phishing, malware, abuse involving Cloudflare-protected assets  
**API style:** REST API  
**Good submissions:** URLs, domains, abuse category, evidence, contact details  
**Avoid:** Large stolen datasets; provide proof and context instead  

**Operational fit:** Use whenever malicious infrastructure resolves through or is protected by Cloudflare.

Sources:
- https://developers.cloudflare.com/api/resources/abuse_reports/
- https://developers.cloudflare.com/fundamentals/reference/report-abuse/submit-report/

---

### 3.5 Spamhaus Submission Portal API

**Type:** Reputation and abuse-intelligence reporting  
**Best for:** Malicious IPs, domains, URLs, suspicious email content  
**API style:** REST API  
**Good submissions:** IPs, domains, URLs, suspicious raw email/source evidence  
**Avoid:** Unverified mass submissions; maintain high-confidence standards  

**Operational fit:** Use for reliable contribution to reputation systems and anti-abuse communities.

Sources:
- https://submit.spamhaus.org/api/
- https://www.spamhaus.org/resource-hub/threat-intelligence/how-to-report-suspicious-activity-to-spamhaus/

---

### 3.6 AbuseIPDB

**Type:** IP reputation and abuse reporting  
**Best for:** Attack-source IP reporting  
**API style:** REST API  
**Good submissions:** Brute force, scanning, spam, exploitation attempts, abusive traffic categories  
**Avoid:** Reporting shared NAT/VPN/cloud IPs without strong evidence  

**Operational fit:** Use as an automated destination for source-IP abuse reports, especially from honeypots, firewalls, and SIEM detections.

Sources:
- https://docs.abuseipdb.com/
- https://www.abuseipdb.com/api.html

---

### 3.7 URLhaus / abuse.ch

**Type:** Malware URL exchange  
**Best for:** Active malware distribution URLs  
**API style:** Community API with Auth-Key  
**Good submissions:** URLs directly serving malware payloads  
**Avoid:** Generic phishing pages that do not distribute malware  

**Operational fit:** Use when you can verify a URL is actively distributing malware.

Source: https://urlhaus.abuse.ch/api/

---

### 3.8 MalwareBazaar / abuse.ch

**Type:** Malware sample exchange  
**Best for:** Malware samples, hashes, family tracking  
**API style:** Community API with Auth-Key  
**Good submissions:** Malware samples and related metadata  
**Avoid:** Benign files, sensitive internal documents, or samples that cannot be legally shared  

**Operational fit:** Use after malware handling review, with strict legal and operational controls.

Source: https://bazaar.abuse.ch/api/

---

### 3.9 PhishTank

**Type:** Community phishing clearing house  
**Best for:** Phishing URL verification and community validation  
**API style:** HTTP POST lookup API  
**Good submissions:** Suspected phishing URLs  
**Avoid:** URLs containing victim credentials, tokens, or private data in query strings  

**Operational fit:** Use for phishing intelligence enrichment and community verification.

Sources:
- https://phishtank.net/api_info.php
- https://www.phishtank.com/

---

### 3.10 urlscan.io

**Type:** URL scanning and investigation platform  
**Best for:** URL detonation, phishing evidence, page screenshots, redirects, IP/domain enrichment  
**API style:** Submission API and search API  
**Good submissions:** Suspicious URLs, phishing pages, malicious landing pages  
**Avoid:** Private internal URLs or sensitive tokens; set scan visibility carefully  

**Operational fit:** Use before provider reporting to create structured, shareable evidence.

Sources:
- https://urlscan.io/docs/api/
- https://docs.urlscan.io/pages/api-intro

---

### 3.11 Google Web Risk Submission API

**Type:** Unsafe URL submission into Google’s protection ecosystem  
**Best for:** High-scale phishing/malware URL submissions  
**API style:** Submission API; restricted access  
**Good submissions:** Suspected unsafe URLs that should be evaluated for Safe Browsing protection  
**Avoid:** Assuming access is automatic; Google says access requires contacting sales or a customer engineer  

**Operational fit:** Use when your group has enough volume and quality control to justify access.

Source: https://docs.cloud.google.com/web-risk/docs/submission-api

---

### 3.12 VirusTotal API

**Type:** Multi-vendor malware and URL analysis ecosystem  
**Best for:** URL/file submission, enrichment, analysis reports, community comments  
**API style:** REST API  
**Good submissions:** Suspicious files, URLs, domains, IPs, hashes  
**Avoid:** Uploading confidential files, customer data, private source code, or stolen materials  

**Operational fit:** Use for enrichment and multi-vendor visibility. Use private scanning options if available and appropriate.

Sources:
- https://docs.virustotal.com/docs/api-overview
- https://docs.virustotal.com/reference/overview
- https://docs.virustotal.com/reference/files-scan

---

### 3.13 Netcraft Report API

**Type:** Phishing, malware, suspicious URL/email/file reporting  
**Best for:** Phishing and takedown-support reporting  
**API style:** Report API  
**Good submissions:** Malicious URLs, suspicious emails, files, phishing evidence  
**Avoid:** Low-confidence or privacy-sensitive submissions  

**Operational fit:** Use for high-confidence phishing and brand-abuse reporting, especially where takedown support matters.

Sources:
- https://report.netcraft.com/api
- https://www.netcraft.com/company/news/netcraft-launches-new-real-time-threat-api-to-improve-and-accelerate-collaboration-with-infrastructure-providers

---

## 4. Internal Case / Incident Routing Platforms

These platforms are not external public reporting destinations, but they are useful for receiving your detections through APIs and routing them into a proper case workflow.

| Platform | Best for | API capability | Workflow role |
|---|---|---|---|
| **TheHive** | SOC alert-to-case management | TheHive 5 API supports alert creation | Convert signals into triaged investigations |
| **DFIR-IRIS** | Collaborative incident response | Alerts API and general API key support | Internal IR case management |
| **ServiceNow SIR** | Enterprise security incident response | REST API to write to Security Incident Import table | Enterprise escalation and tracking |
| **Jira Service Management Incidents** | Incident workflow automation | Incidents REST API | Lightweight or engineering-driven incident coordination |

Sources:
- https://docs.strangebee.com/thehive/api-docs
- https://docs.dfir-iris.org/operations/alerts/
- https://www.servicenow.com/docs/r/yokohama/security-management/security-incident-response/c_3rdPartyAlertMonToolInteg.html
- https://developer.atlassian.com/cloud/incidents/rest/api-group-incident/

---

## 5. Platforms Useful for Monitoring but Not Primary API Reporting Destinations

| Platform | API status | Recommendation |
|---|---|---|
| **Ransomware.live** | API available for ransomware victim/group intelligence | Use for monitoring and enrichment, not as the main reporting destination |
| **Shadowserver** | RESTful API for report data access; no STIX/TAXII currently | Use for inbound network exposure/threat reports and enrichment |
| **Have I Been Pwned** | API for breach account lookups | Use for exposure checks, not submitting new breach reports unless separately arranged |
| **OpenPhish** | No public lookup API; offers feed/module model | Use feed or email/manual reporting fallback |
| **Microsoft Defender submissions** | Portal and Microsoft Graph threat-submission resources for some Defender scenarios | Use when operating within a Microsoft tenant or Defender workflow |

Sources:
- https://www.ransomware.live/api
- https://api-pro.ransomware.live/
- https://www.shadowserver.org/faq/can-i-access-your-reports-through-an-api/
- https://haveibeenpwned.com/api/v3
- https://openphish.com/kb.html
- https://learn.microsoft.com/en-us/graph/api/resources/security-filethreatsubmission

---

## 6. Practical Routing Matrix

| Evidence type | First API destination | Second destination | Internal system |
|---|---|---|---|
| Malicious IP scanning/brute force | AbuseIPDB | Spamhaus if relevant | TheHive / DFIR-IRIS |
| Malware distribution URL | URLhaus | Google Web Risk / VirusTotal / urlscan.io | MISP / OpenCTI |
| Malware sample | MalwareBazaar | VirusTotal | TheHive / OpenCTI |
| Phishing URL | PhishTank / Netcraft / urlscan.io | Google Web Risk / Cloudflare if hosted/proxied there | MISP / TheHive |
| Cloudflare-proxied abuse | Cloudflare Abuse Reports API | Netcraft / PhishTank if phishing | Internal case platform |
| Suspicious email infrastructure | Spamhaus Submission API | AbuseIPDB for IPs | MISP / OpenCTI |
| Campaign-level indicators | CISA AIS / MISP | CERT/CSIRT | OpenCTI |
| Ransomware victim claim | Victim + CERT first | MISP only sanitized indicators | OpenCTI / TheHive |
| Leaked credentials/API keys | Victim first | CERT if severe | Internal IR case only |
| Critical infrastructure threat | CERT/CSIRT first | Victim + law enforcement | Internal restricted case |

---

## 7. Minimum Viable API Stack

For a new white-hat group, start with:

1. **MISP** — trusted sharing and structured IOC exchange.
2. **OpenCTI** — central intelligence normalization and knowledge graph.
3. **TheHive or DFIR-IRIS** — case management and triage.
4. **AbuseIPDB** — automated IP abuse reporting.
5. **URLhaus** — malware URL submission.
6. **MalwareBazaar** — malware sample submission, only with legal controls.
7. **urlscan.io** — URL evidence generation.
8. **Cloudflare Abuse Reports API** — infrastructure abuse reports.
9. **Spamhaus Submission Portal API** — IP/domain/URL/email reputation reporting.
10. **CISA AIS or national CERT sharing route** — campaign-level indicator sharing.

---

## 8. Data Handling Rules

### Never submit publicly

- Raw credentials
- API keys or session cookies
- Stolen databases
- Internal screenshots that identify victims without consent
- Exploit instructions
- Live access details
- Private source code
- Sensitive personal data

### Safe to submit when verified

- IP addresses
- Domains
- URLs, if they do not contain tokens or PII
- File hashes
- Malware samples, only where legally allowed
- Timestamps
- Actor handles
- Campaign labels
- CVEs
- MITRE ATT&CK techniques
- Sanitized screenshots
- Provider-neutral technical context

---

## 9. Recommended Submission Object

Use this normalized object internally before transforming to each API schema.

```json
{
  "case_id": "WG-2026-000001",
  "tlp": "AMBER",
  "severity": "A|B|C|D|E",
  "confidence": "low|medium|high",
  "threat_type": "phishing|malware|ransomware|credential_exposure|iab|botnet|vulnerability_exploitation",
  "victim": {
    "organization": "",
    "domain": "",
    "country": "",
    "sector": ""
  },
  "source": {
    "category": "forum|leak_site|telegram|honeypot|sensor|osint|tip",
    "first_seen": "",
    "last_seen": "",
    "collection_method": "lawful_osint_or_partner_feed"
  },
  "observables": {
    "ips": [],
    "domains": [],
    "urls": [],
    "hashes": [],
    "emails": [],
    "wallets": [],
    "cves": []
  },
  "evidence": {
    "summary": "",
    "sanitized_screenshots": [],
    "raw_evidence_location": "internal_restricted_storage"
  },
  "recommended_actions": [],
  "routing": {
    "primary_destinations": [],
    "secondary_destinations": [],
    "public_disclosure_allowed": false
  }
}
```

---

## 10. Final Recommendation

The most practical API-driven architecture is:

**Sensors / CTI sources → OpenCTI → TheHive or DFIR-IRIS → routing engine → MISP + provider abuse APIs + CERT/AIS channels → sanitized public reporting**

This keeps the group legally safer, avoids amplifying criminal material, and creates a repeatable path from early warning to real defensive action.