init: scaffold psyc — defensive CTI routing & evidence-sealing platform
Stage-1 vertical slice: Pydantic Case model, SQLAlchemy Core persistence, URLhaus Scoutline fetcher, FastAPI/Jinja cockpit (cases list + detail), flat Typer CLI, Result[T, E] type module, structlog config. Architecture in docs/dossier.md; 12-fold style guide in docs/style.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
m17hr1l
518
docs/archive/routeline.md
Normal file
518
docs/archive/routeline.md
Normal file
@@ -0,0 +1,518 @@
|
||||
# Blue48 Reporting and API Escalation Architecture v2
|
||||
|
||||
**Document type:** Project record / operational architecture
|
||||
**Scope:** API-eligible reporting platforms, routing order, evidence handling, CERT mapping, abuse routing, receipts, and audit controls
|
||||
**Status:** Draft v2
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines how Blue48 routes defensive cyber-intelligence to the correct recipients using structured APIs, trusted communities, CERT/CSIRT channels, abuse-reporting endpoints, and authority-sealed evidence packages.
|
||||
|
||||
The platform is designed for lawful white-hat operations. It should not amplify stolen data, expose victims prematurely, or interact with criminal actors.
|
||||
|
||||
Core principle:
|
||||
|
||||
> Validate the signal, protect the evidence, route only what each destination is authorized to receive, and prove every external action through an immutable ledger.
|
||||
|
||||
---
|
||||
|
||||
## 2. Recommended Reporting Order
|
||||
|
||||
### Normal cases
|
||||
|
||||
```text
|
||||
Victim Security Team
|
||||
→ National CERT / CSIRT
|
||||
→ Sector ISAC / trusted community
|
||||
→ Law enforcement cyber unit when criminal evidence exists
|
||||
→ Provider / registrar / abuse APIs
|
||||
→ Public sanitized report after mitigation
|
||||
```
|
||||
|
||||
### Imminent harm or critical infrastructure
|
||||
|
||||
```text
|
||||
National CERT / CSIRT
|
||||
→ Victim Security Team
|
||||
→ Law enforcement cyber unit
|
||||
→ Sector ISAC / regulator
|
||||
→ Provider / registrar / abuse APIs
|
||||
→ Trusted CTI community
|
||||
→ Public sanitized report after mitigation or clearance
|
||||
```
|
||||
|
||||
### Malicious infrastructure
|
||||
|
||||
```text
|
||||
Hosting provider / CDN / cloud abuse desk
|
||||
→ Registrar abuse contact
|
||||
→ Registry escalation
|
||||
→ National CERT / CSIRT
|
||||
→ Law enforcement when warranted
|
||||
→ Trusted CTI community
|
||||
```
|
||||
|
||||
### Mass exploitation
|
||||
|
||||
```text
|
||||
Affected vendor
|
||||
→ National CERT / CSIRT
|
||||
→ Affected sectors / ISACs
|
||||
→ MISP / trusted CTI community
|
||||
→ Public advisory after coordinated mitigation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Authority-Sealed Evidence Handling
|
||||
|
||||
Blue48 does not treat full evidence protection as “sanitization.” Sensitive evidence should be preserved, encrypted, and routed only to authorized recipients.
|
||||
|
||||
Use the term:
|
||||
|
||||
> **Authority-Sealed Evidence Handling**
|
||||
|
||||
Purpose:
|
||||
|
||||
- preserve high-value evidence
|
||||
- prevent uncontrolled internal access
|
||||
- prevent accidental redistribution
|
||||
- allow victims or authorities to decrypt when authorized
|
||||
- destroy local plaintext and unwrapped keys after successful sealing
|
||||
|
||||
---
|
||||
|
||||
## 4. Evidence Protection Models
|
||||
|
||||
### Model A: Authority public-key encryption
|
||||
|
||||
Authorities or victims provide public encryption keys.
|
||||
|
||||
```text
|
||||
Evidence collected
|
||||
→ sensitive evidence packaged
|
||||
→ package encrypted with authority/victim public key
|
||||
→ encrypted package submitted
|
||||
→ local plaintext destroyed
|
||||
→ only recipient can decrypt
|
||||
```
|
||||
|
||||
This is the cleanest model because Blue48 never holds the recipient private key.
|
||||
|
||||
### Model B: One-time evidence key wrapped for recipients
|
||||
|
||||
```text
|
||||
Generate random evidence key
|
||||
→ encrypt evidence with evidence key
|
||||
→ wrap evidence key to recipient public keys
|
||||
→ submit encrypted package
|
||||
→ destroy local plaintext
|
||||
→ destroy local unwrapped evidence key
|
||||
```
|
||||
|
||||
Package example:
|
||||
|
||||
```json
|
||||
{
|
||||
"evidence_package_id": "uuid",
|
||||
"encrypted_evidence": "ciphertext-reference",
|
||||
"wrapped_keys": [
|
||||
{
|
||||
"recipient": "CERT-Bund",
|
||||
"key_id": "authority-key-id",
|
||||
"wrapped_key": "encrypted-evidence-key"
|
||||
},
|
||||
{
|
||||
"recipient": "Victim Security Team",
|
||||
"key_id": "victim-key-id",
|
||||
"wrapped_key": "encrypted-evidence-key"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"tlp": "AMBER",
|
||||
"severity": "critical",
|
||||
"created_at": "2026-05-13T00:00:00Z",
|
||||
"retention_policy": "plaintext destroyed after encryption"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Destination Minimization
|
||||
|
||||
Authority-sealed evidence handling does not mean every platform receives full evidence. Public and semi-public APIs should receive only the minimum necessary payload.
|
||||
|
||||
| Destination type | Payload |
|
||||
|---|---|
|
||||
| CERT / law enforcement | Encrypted full evidence package when authorized. |
|
||||
| Victim security team | Encrypted full or partial evidence package. |
|
||||
| Trusted MISP community | TLP-filtered STIX indicators and context. |
|
||||
| Provider / registrar abuse API | Minimal abuse report with infrastructure evidence. |
|
||||
| URLhaus / MalwareBazaar | Malware URL/hash/sample only when legally allowed. |
|
||||
| AbuseIPDB | IP, category, timestamp, short comment. |
|
||||
| VirusTotal | Hash, URL, or sample only when policy allows. |
|
||||
| Public report | Sanitized narrative, no raw sensitive evidence. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Priority Platform Order
|
||||
|
||||
For European or global operations, use MISP and national CERT routing before US-specific AIS.
|
||||
|
||||
| Priority | Platform / route | Role |
|
||||
|---:|---|---|
|
||||
| 1 | **MISP / CIRCL / trusted MISP communities** | Primary CTI sharing backbone. |
|
||||
| 2 | **National CERT / CSIRT** | Country-specific authority route. |
|
||||
| 3 | **CERT-EU / ENISA CSIRTs Network** | EU institutions and European coordination. |
|
||||
| 4 | **CISA AIS** | US-relevant machine-to-machine indicator sharing. |
|
||||
| 5 | **OpenCTI** | Internal graph and knowledge base, not necessarily an external reporting destination. |
|
||||
| 6 | **Provider / CDN / cloud abuse APIs** | Infrastructure mitigation and takedown. |
|
||||
| 7 | **Registrar / registry abuse channels** | Domain suspension or escalation. |
|
||||
| 8 | **abuse.ch, URLhaus, MalwareBazaar** | Malware URL/sample ecosystem reporting. |
|
||||
| 9 | **AbuseIPDB / Spamhaus / PhishTank / urlscan.io** | Public/semi-public abuse and phishing ecosystem reporting. |
|
||||
| 10 | **Public advisory channels** | Sanitized reporting after mitigation. |
|
||||
|
||||
---
|
||||
|
||||
## 7. CERT / CSIRT Routing Map
|
||||
|
||||
The routing engine should pick receivers based on victim country, sector, and legal jurisdiction.
|
||||
|
||||
| Country / region | Receiver | Channel type |
|
||||
|---|---|---|
|
||||
| Germany | BSI / CERT-Bund | Structured email, trusted channels, MISP community where available. |
|
||||
| France | ANSSI / CERT-FR | CERT channel, structured reporting, TAXII/MISP where available. |
|
||||
| United Kingdom | NCSC-UK | Structured reporting, early-warning services, official channels. |
|
||||
| Netherlands | NCSC-NL | CERT channel, trusted community/MISP where available. |
|
||||
| Spain | CCN-CERT / INCIBE-CERT | Public-sector/private-sector split, CERT channels, MISP where available. |
|
||||
| EU institutions | CERT-EU | EU institutional route. |
|
||||
| EU criminal coordination | Europol EC3 | Usually via national CERT/law-enforcement channels, not first-call technical sharing. |
|
||||
| United States | CISA / FBI IC3 / FBI field office | CISA for technical reporting, IC3/FBI for crime reporting. |
|
||||
|
||||
Implementation note:
|
||||
|
||||
> Europol EC3 should not be treated as the first technical receiver. Route through the relevant national CERT or law-enforcement channel first unless a formal coordination channel exists.
|
||||
|
||||
---
|
||||
|
||||
## 8. Severity and Class Mapping
|
||||
|
||||
Blue48 may keep an internal class model, but outbound reports should include standard severity.
|
||||
|
||||
| Internal class | Meaning | External severity |
|
||||
|---|---|---|
|
||||
| A | Imminent harm / attack likely underway | Critical |
|
||||
| B | Credible planned attack | High |
|
||||
| C | Confirmed exposure | High / Medium |
|
||||
| D | Campaign intelligence | Medium / High |
|
||||
| E | Weak signal / watchlist | Low / Monitor |
|
||||
|
||||
---
|
||||
|
||||
## 9. Normalized Case Object
|
||||
|
||||
All workers should read and write the same normalized case object.
|
||||
|
||||
```json
|
||||
{
|
||||
"case_id": "B48-2026-000001",
|
||||
"summary": "Short defensive summary",
|
||||
"classification": {
|
||||
"class": "A | B | C | D | E",
|
||||
"severity": "low | medium | high | critical",
|
||||
"tlp": "RED | AMBER | GREEN | CLEAR",
|
||||
"incident_type": "access_sale | ransomware | credential_leak | phishing | malware | exploit | botnet | data_leak"
|
||||
},
|
||||
"confidence": {
|
||||
"level": "low | medium | high",
|
||||
"source_reliability": "A | B | C | D | E | F | unknown",
|
||||
"information_credibility": "1 | 2 | 3 | 4 | 5 | 6 | unknown"
|
||||
},
|
||||
"victim": {
|
||||
"name": "",
|
||||
"domain": "",
|
||||
"country": "",
|
||||
"sector": "",
|
||||
"critical_infrastructure": false
|
||||
},
|
||||
"actor": {
|
||||
"name": "",
|
||||
"aliases": [],
|
||||
"campaign": "",
|
||||
"confidence": "low | medium | high"
|
||||
},
|
||||
"observables": {
|
||||
"domains": [],
|
||||
"ips": [],
|
||||
"urls": [],
|
||||
"hashes": [],
|
||||
"cves": [],
|
||||
"wallets": [],
|
||||
"emails": []
|
||||
},
|
||||
"evidence": {
|
||||
"raw_evidence_location": "internal-only-reference",
|
||||
"sealed_package_id": "",
|
||||
"payload_hash": "",
|
||||
"plaintext_destroyed": false,
|
||||
"local_unwrapped_key_destroyed": false
|
||||
},
|
||||
"routing": {
|
||||
"recommended_routes": [],
|
||||
"blocked_routes": [],
|
||||
"human_approval_required": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. TLP Enforcement
|
||||
|
||||
Every destination must define a maximum allowed TLP.
|
||||
|
||||
Routing precondition:
|
||||
|
||||
```text
|
||||
submission.tlp <= destination.max_tlp_allowed
|
||||
```
|
||||
|
||||
Example destination policy:
|
||||
|
||||
| Destination | Max TLP | Payload type |
|
||||
|---|---|---|
|
||||
| CERT / CSIRT trusted route | RED or AMBER depending channel | Sealed evidence package. |
|
||||
| Victim security team | RED or AMBER depending identity verification | Sealed package or controlled extract. |
|
||||
| MISP trusted community | AMBER or GREEN depending sharing group | STIX/MISP event. |
|
||||
| Public MISP community | GREEN or CLEAR | Public-safe indicators. |
|
||||
| AbuseIPDB | CLEAR | Minimal IP abuse report. |
|
||||
| URLhaus | CLEAR / GREEN depending policy | Malicious URL report. |
|
||||
| VirusTotal | CLEAR only unless legal approval exists | Hash/URL/sample where permitted. |
|
||||
| Public advisory | CLEAR | Sanitized intelligence. |
|
||||
|
||||
---
|
||||
|
||||
## 11. API-Eligible Destination Categories
|
||||
|
||||
### 11.1 CTI sharing
|
||||
|
||||
| Platform | Purpose | Integration style |
|
||||
|---|---|---|
|
||||
| MISP | Threat intelligence sharing and communities. | REST API / PyMISP / STIX. |
|
||||
| OpenCTI | Internal CTI graph and knowledge management. | GraphQL API / STIX. |
|
||||
| CISA AIS | US-relevant automated indicator sharing. | TAXII/STIX-style exchange. |
|
||||
|
||||
### 11.2 Abuse and takedown
|
||||
|
||||
| Platform | Purpose | Integration style |
|
||||
|---|---|---|
|
||||
| Cloudflare Abuse Reports | Report abuse behind Cloudflare services. | Abuse Reports API / portal. |
|
||||
| Registrar abuse channels | Domain abuse escalation. | API where available, otherwise structured email/WHOIS abuse contact. |
|
||||
| Registry escalation | Escalation for TLD-level issues. | Registry-specific process. |
|
||||
| URLhaus | Malware URL reporting. | API submission. |
|
||||
| MalwareBazaar | Malware sample/hash ecosystem. | API submission/query. |
|
||||
| AbuseIPDB | IP reputation and abuse reports. | API. |
|
||||
| Spamhaus | Spam, botnet, and malicious infrastructure reporting. | Submission portal/API where available. |
|
||||
| PhishTank | Phishing URL reporting. | API/community workflow. |
|
||||
| urlscan.io | URL scan and malicious page evidence. | API submission. |
|
||||
| Google Web Risk | Unsafe URL submission where permitted. | Restricted API. |
|
||||
| VirusTotal | URL/file/hash enrichment and submission. | API, policy controlled. |
|
||||
| Netcraft | Phishing and abuse reporting. | API/enterprise options and reporting channels. |
|
||||
|
||||
### 11.3 Internal case-management
|
||||
|
||||
| Platform | Purpose |
|
||||
|---|---|
|
||||
| TheHive | Security case management and observables. |
|
||||
| DFIR-IRIS | Incident response case management. |
|
||||
| ServiceNow SIR | Enterprise incident response workflow. |
|
||||
| Jira Service Management | Case routing and task management. |
|
||||
|
||||
---
|
||||
|
||||
## 12. Registrar and Registry Abuse Flow
|
||||
|
||||
For malicious domains, phishing portals, C2 domains, impersonation infrastructure, and ransomware-related web infrastructure:
|
||||
|
||||
```text
|
||||
Identify domain
|
||||
→ identify hosting provider and CDN/proxy
|
||||
→ identify registrar from WHOIS/RDAP
|
||||
→ report to hosting/CDN abuse
|
||||
→ report to registrar abuse
|
||||
→ escalate to registry if registrar fails or emergency applies
|
||||
→ notify CERT if critical or cross-border
|
||||
```
|
||||
|
||||
Payload should include:
|
||||
|
||||
- domain
|
||||
- abuse type
|
||||
- timestamp
|
||||
- evidence hash
|
||||
- screenshot hash or sealed evidence reference
|
||||
- safe reproduction summary
|
||||
- victim impersonated, if relevant
|
||||
- requested action
|
||||
|
||||
Avoid sending raw credentials, stolen data, or private victim details to registrar/registry channels unless legally justified.
|
||||
|
||||
---
|
||||
|
||||
## 13. Rate Limits and Queueing
|
||||
|
||||
Every destination should define a quota object.
|
||||
|
||||
```json
|
||||
{
|
||||
"destination": "AbuseIPDB",
|
||||
"quota": {
|
||||
"limit": 1000,
|
||||
"period": "day",
|
||||
"priority_policy": "critical_first",
|
||||
"backoff": "exponential"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
RateLimiter responsibilities:
|
||||
|
||||
- prevent dropped submissions
|
||||
- queue low-priority submissions during bursts
|
||||
- reserve budget for critical cases
|
||||
- retry transient failures
|
||||
- record rate-limit errors in Ledger
|
||||
|
||||
---
|
||||
|
||||
## 14. Receipt and Effectiveness Tracking
|
||||
|
||||
ReceiptCollector and Watcher should capture feedback from every destination.
|
||||
|
||||
Receipt schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"case_id": "B48-2026-000001",
|
||||
"destination": "Cloudflare Abuse API",
|
||||
"submitted_at": "2026-05-13T00:00:00Z",
|
||||
"acknowledged_at": "2026-05-13T00:05:00Z",
|
||||
"receipt_id": "external-case-id",
|
||||
"status": "submitted | acknowledged | rejected | actioned | closed",
|
||||
"outcome": "pending | takedown_confirmed | duplicate | no_action | escalated"
|
||||
}
|
||||
```
|
||||
|
||||
Success metrics:
|
||||
|
||||
| Destination type | Success metric |
|
||||
|---|---|
|
||||
| CERT / CSIRT | Acknowledgement, case opened, mitigation guidance issued. |
|
||||
| Provider / registrar | Infrastructure suspended, blocked, or investigated. |
|
||||
| MISP | Event accepted, sightings, correlations. |
|
||||
| URLhaus / MalwareBazaar | URL/sample accepted, classified, distributed. |
|
||||
| Public report | Defenders consume advisory, no sensitive data leak. |
|
||||
|
||||
---
|
||||
|
||||
## 15. Immutable Audit Log
|
||||
|
||||
Every external submission or destructive action must write an immutable record.
|
||||
|
||||
Audit row:
|
||||
|
||||
```text
|
||||
(timestamp, case_id, destination, payload_hash, submitter_identity, tlp, response_id, outcome)
|
||||
```
|
||||
|
||||
Also audit:
|
||||
|
||||
- evidence sealing
|
||||
- recipient key addition/removal
|
||||
- plaintext destruction
|
||||
- local key destruction
|
||||
- route approval
|
||||
- route blocking
|
||||
- public publication
|
||||
- dataset export
|
||||
- policy modification
|
||||
|
||||
---
|
||||
|
||||
## 16. Public Reporting Rules
|
||||
|
||||
Public reports may include:
|
||||
|
||||
- sector trend
|
||||
- country/region if safe
|
||||
- actor or campaign if already public or properly attributed
|
||||
- TTPs
|
||||
- CVEs
|
||||
- defensive recommendations
|
||||
- sanitized IOCs
|
||||
- non-sensitive timeline
|
||||
|
||||
Public reports must not include:
|
||||
|
||||
- raw credentials
|
||||
- stolen data
|
||||
- direct links to stolen data
|
||||
- live access details
|
||||
- internal screenshots
|
||||
- private victim communications
|
||||
- exact criminal-source links
|
||||
- exploit instructions
|
||||
- anything that increases victim harm before mitigation
|
||||
|
||||
---
|
||||
|
||||
## 17. Initial Adapter Build Order
|
||||
|
||||
Recommended Block G adapter priority:
|
||||
|
||||
1. MISP via PyMISP
|
||||
2. AbuseIPDB
|
||||
3. URLhaus
|
||||
4. Cloudflare Abuse Reports
|
||||
5. urlscan.io
|
||||
6. MalwareBazaar
|
||||
7. Registrar abuse structured email/RDAP helper
|
||||
8. VirusTotal enrichment/submission with strict policy guard
|
||||
9. OpenCTI internal graph integration
|
||||
10. TheHive or DFIR-IRIS case export
|
||||
|
||||
These cover the most common evidence and routing cases while keeping legal risk manageable.
|
||||
|
||||
---
|
||||
|
||||
## 18. Secrets Handling
|
||||
|
||||
Every adapter needs credentials.
|
||||
|
||||
Rules:
|
||||
|
||||
- credentials live in `.env` or secret manager
|
||||
- credentials are injected at runtime
|
||||
- credentials are never baked into container images
|
||||
- credentials are rotatable
|
||||
- credentials are scoped per adapter
|
||||
- every API call writes to the Ledger
|
||||
- failed authentication events are logged and alerted
|
||||
|
||||
---
|
||||
|
||||
## 19. Summary
|
||||
|
||||
The v2 architecture changes the platform from a list of reporting sites into an operational routing system.
|
||||
|
||||
The most important revisions are:
|
||||
|
||||
- MISP and national CERTs are prioritized over CISA AIS for European/global work.
|
||||
- CERT routing is country-specific.
|
||||
- Registrar and registry abuse flows are included.
|
||||
- Sensitive evidence is protected through authority-sealed encryption, not casual sanitization.
|
||||
- Public and semi-public APIs receive minimized payloads only.
|
||||
- TLP enforcement, rate limits, receipts, and immutable audit logs are mandatory.
|
||||
Reference in New Issue
Block a user