Darkfield Ransomware & Dark Web API

GET/ransomware/groups

List ransomware groups — Returns every tracked ransomware/extortion group ordered by total known victims (descending). Each entry includes a flattened MISP-galaxy enrichment copy (references, origin country, suspected state sponsor, incident type), MITRE ATT&CK mapping, YARA rules, IOCs, and aggregate top-countries / top-sectors / timeline. Requires any valid API key.

GET/ransomware/victims

List ransomware victims — Returns ransomware leak-site victims ordered by discovery date (descending). Supports filtering by group, country, sector, and a name substring search, plus limit/offset pagination. Optional AI-generated dossier (`enrichment`) is present when post-ingest enrichment has run. Requires any valid API key.

GET/ransomware/victims/{victim_id}

Get a single victim — Single ransomware victim lookup by UUID. Returns the same shape as the list endpoint plus the full `raw_content` of the original leak post. Requires any valid API key. Returns 404 when no victim matches the id.

GET/ransomware/stats

Aggregate ransomware statistics — Returns headline counts (total groups, active groups, total victims) and the top-10 distributions of victims by group, country, and sector. Requires any valid API key.

GET/ransomware/countries

Full victim count per country — Returns the complete (uncapped) victim count per country, ordered descending — powers the world-map choropleth. Country strings are returned raw (mixed full-names and ISO codes as stored); the consumer normalizes them. Requires any valid API key.

GET/ransomware/timeline

Monthly victim timeline — Returns monthly victim counts (truncated to the month, ISO timestamp) for the last N months. Requires any valid API key.

GET/ransomware/check

Check if a company appears in leak sites — Checks whether a company, domain, or email appears in tracked ransomware leak sites. Uses a two-stage SQL + word-boundary filter to avoid substring false-positives, deduplicates matches by (name, group), classifies each match (exact / contains / domain / partial), and attaches per-group context (aliases, status, total victims, recent related victims). Requires any valid API key.

GET/ransomware/groups/{group_name}/mitre

MITRE ATT&CK mapping for a group — Returns the MITRE ATT&CK tactic/technique mapping for a named group. When no mapping exists, `mitre` is null and a `message` field explains. Requires any valid API key.

GET/ransomware/groups/{group_name}/yara

YARA rules for a group — Returns the YARA detection rules associated with a named group. When none exist, `yara_rules` is an empty array and a `message` field explains. Requires any valid API key.

GET/ransomware/groups/{group_name}/ioc

Indicators of compromise for a group — Returns the indicators of compromise (IOCs) for a named group. When none exist, `iocs` is null and a `message` field explains. Requires any valid API key.

GET/ransomware/stats/advanced

Advanced ransomware statistics — Returns a rich statistics payload for the analytics surface: total victims, this-month vs last-month counts and growth rate, daily average, peak-day, last-24-month series, yearly series, day-of-week distribution, and top-10 groups/countries/sectors for the current month. Requires any valid API key.

GET/ransomware/country/{country_name}

Country detail stats — Returns detailed statistics for a single country: total victims, top-10 groups, top-10 sectors, and the 20 most recent victims (compact form). Requires any valid API key.

GET/ransomware/export/csv

Export victims as CSV — Streams up to 5000 victims as a CSV attachment (columns: Group, Victim, Country, Sector, Website, Data Size, Ransom, Status, Discovered), optionally filtered by group and/or country. Requires an API key whose tier includes the `export` permission; keys without it receive 403.

GET/search/

Full-text dark-web search — Advanced full-text search across the crawled dark-web corpus (`raw_contents` index) with optional source-type, date-range, and exclusion filters. Returns ranked content hits with highlighted fragments and also surfaces structured matches from the tracked-victim corpus (38k+ victims). Requires an API key with the `search` permission, so non-default keys are rejected with 403.

GET/search/feed

Global crawl feed — Returns the global firehose of crawled dark-web content, most recent first, with a short text preview per item. Supports offset-based pagination. Requires an API key with the `search` permission, so non-default keys are rejected with 403.

GET/search/stats

Crawl corpus statistics — Returns aggregate statistics for the crawled content corpus: total document count, number of unique URLs (approximate cardinality), and an hourly timeline of crawl volume. Available to any valid API key (default permission).

GET/credentials/search

Search compromised credentials by domain — Searches the proprietary compromised-credential corpus for a single domain and returns the matching records plus aggregate breach stats (counts by password strength, source, and stealer family).

GET/credentials/stats

Compromised-credential database statistics — Returns an overview of the entire compromised-credential corpus: total record count, unique domain and email counts, the top 20 domains by record count, and the 5 most recently discovered records.

POST/credentials/check-password

Check a password against HIBP Pwned Passwords — Looks up a candidate password against the full Have I Been Pwned Pwned Passwords corpus (13B+ records) using the privacy-preserving k-anonymity protocol.

POST/deep-scan/start

Start an autonomous deep dark-web scan — Kicks off an asynchronous, job-based deep scan of a domain across the internal database, Elasticsearch, Tor (.onion) search, page scraping, and AI analysis. The call is **async**: it dispatches a background Celery job and immediately returns a `scan_id` to poll via `GET /deep-scan/status/{scan_id}`. **Spends 10 Cyber Tokens** per scan (billed by the worker against the calling account); a `402` is returned when the account has insufficient tokens. Requires an API key whose tier includes the `scan` permission (otherwise `403`). When invoked by a logged-in session the SSO identity is propagated so the scan is owned by that account and counts toward Recent Activity; the `user_email` query param is a legacy fallback for API-key callers without a session.

GET/deep-scan/status/{scan_id}

Poll a deep scan for status and results — Returns the current status of a scan, with partial results streamed back as phases complete and the full results blob once finished. While the job is in flight, live progress is served from Redis; after completion the durable record is served from the database. **Ownership-scoped:** because results can contain credentials/PII, a scan is only visible to the user (or admin) who started it. A scan_id owned by another user yields `status: "not_found"` (or `404`) so existence is never leaked. Any valid API key may call this endpoint (default permission). A scan_id that has never existed returns a `200` with `status: "not_found"`.

GET/deep-scan/history

List the caller's own scan history — Returns a list of the caller's past deep scans, newest first. **Owner-scoped server-side:** results are hard-limited to scans owned by the authenticated user (`owner_user_id`); admins and trusted internal services see all rows, while an identity-less non-admin caller gets an empty list. There is no team sharing on scan history. Any valid API key may call this endpoint (default permission).

POST/forensic/start

Start a forensic analysis of a leaked sample — Kicks off an asynchronous forensic analysis of a leaked-data sample hosted at a public URL (downloads, identifies file types, extracts and classifies content, detects PII and credentials, and writes a report). This is an API-only capability — there is no equivalent in the public Observatory UI. Returns immediately with an `analysis_id`; poll `GET /forensic/status/{analysis_id}` for progress and results.

GET/forensic/status/{analysis_id}

Poll a forensic analysis for progress and results — Returns the current state of a forensic analysis. While the job is in flight, the live progress blob (phases, partial findings) is returned. Once finalized, the durable record is returned with the full results object, risk level, and completion timestamp.

GET/forensic/history

List your forensic analysis history — Returns the calling identity's own forensic analyses, newest first (ordered by start time). This is an API-only capability. The list is strictly owner-scoped server-side — you only see analyses started by your own API key / SSO identity (admins see all). If the caller has no resolvable owner identity, an empty array is returned. Any valid API key may call this endpoint; the default-permission key is sufficient.

POST/atlas/investigate

Launch an autonomous group investigation — Kicks off an asynchronous, autonomous investigation of a ransomware group by name (infrastructure discovery, link analysis, victim analysis, group-connection mapping, technical fingerprinting, and AI profiling). Returns immediately with a short `investigation_id` to poll via `GET /atlas/investigation/{investigation_id}`. Despite being a POST, all input is passed as a query parameter (no JSON body). Requires an API key whose tier includes the `scan` permission (keys without it receive 403).

GET/atlas/investigation/{investigation_id}

Poll investigation progress and results — Returns the live progress and results of an investigation. While the task is running, the response is the raw progress snapshot read from the Redis cache (shape varies by phase). Once persisted to the database, a normalized record is returned with per-phase status and the final `results` payload. If the id is unknown, `status` is "not_found". Available to any valid API key.

GET/atlas/investigations

List past investigations — Returns recent investigations ordered by start time (most recent first), each summarized with crawl/victim/connection counts and timestamps. Available to any valid API key.

GET/atlas/graph

Get atlas graph data — Returns the raw node/edge graph used by the Atlas visualization. Nodes are deduplicated .onion sites enriched with their owning group's victim count and crawl health. Edges are currently always empty (the cross-site link pipeline is retired). Optional filters narrow nodes by site status, group name, or a case-insensitive substring match against the last page title or URL. Available to any valid API key.

GET/risk/score

Calculate dark web risk score for a domain or brand — Computes a composite dark web exposure risk score (0-100) for the supplied domain or brand name. The score aggregates four weighted intelligence sources: ransomware exposure (0-35 pts, from the confirmed-victim database), credential exposure (0-25 pts, from HIBP breaches and Hudson Rock infostealer data), dark web presence (0-20 pts, from Elasticsearch mentions and severity-keyword co-occurrence), and recency/velocity (0-20 pts, weighting how recently and how fast threats are appearing). Returns the total score, a derived `risk_level` band (`none` / `low` / `medium` / `high` / `critical`), a per-category `breakdown`, and a small set of recent dark web mention `samples`. Available to any valid API key.

GET/stats/

Get alert statistics — Returns aggregate counts of monitoring alerts: the total number of alerts, a breakdown by severity (critical, high, medium, low), and a breakdown by status (new, reviewed, resolved, false_positive). Requires any valid API key (default permission).

GET/feed/stix2

Full STIX 2.1 bundle (groups + recent victims) — Returns a STIX 2.1 `bundle` describing tracked ransomware groups and their most recent victims. Each group is emitted as both a `malware` object (the ransomware family, `is_family: true`) and a `threat-actor` object (the operator), linked by a `uses` relationship. Each victim is emitted as an `identity` (organization) plus a `targets` relationship from the operating threat-actor to that identity. The bundle is produced by a constant `Darkfield Observatory` `identity` (`created_by_ref`) and marked `TLP:WHITE` via an included `marking-definition`. STIX object IDs are deterministic (UUIDv5 from canonical names), so consumers can dedupe across pulls. The response media type is `application/stix+json;version=2.1`. Compatible with MISP, OpenCTI, TheHive and most SOAR connectors. Requires any valid API key (default tier).

GET/feed/stix2/groups

STIX 2.1 bundle of ransomware groups only — Returns a STIX 2.1 `bundle` containing every tracked ransomware group with no victim data. Each group is emitted as a `malware` object (the ransomware family, `is_family: true`) and a `threat-actor` object (the operator), linked by a `uses` relationship. The bundle also includes the constant `Darkfield Observatory` producer `identity` (`created_by_ref`) and the `TLP:WHITE` `marking-definition`. Fixed size, no victim joins — cheaper than `/feed/stix2`. STIX object IDs are deterministic (UUIDv5 from canonical names) so consumers can dedupe across pulls. The response media type is `application/stix+json;version=2.1`. Requires any valid API key (default tier).

GET/blacklist/check

Check an indicator against all blacklist + breach sources — Looks up a single freeform indicator (crypto wallet address, email, domain, IP, or URL) across the sanctioned/scam wallet list, the phishing/IOC indicator list, and the known-breach catalog. The value is normalized: URLs are reduced to their host, hosts also match parent-domain entries (so `phishing.acme.com` hits an `acme.com` entry), and emails additionally match their domain against KnownBreach. Returns the candidate set that was actually checked plus every matching record. Requires any valid API key.

GET/blacklist/wallets

Browse blacklisted wallet addresses — Paginated browse of the blacklisted_addresses table (OFAC-sanctioned and scam crypto wallets), ordered by most recently updated. Supports filtering by source, category, chain, and an address substring. Requires any valid API key.

GET/blacklist/indicators

Browse phishing / malware / IOC indicators — Paginated browse of the phishing_indicators table (phishing domains, malware IOCs, and other indicators), ordered by most recently updated. Supports filtering by indicator type, source, and an indicator substring. Requires any valid API key.

GET/blacklist/breaches

List known data breaches — Lists known breaches mirrored from HaveIBeenPwned `/breaches`, ordered by pwn_count descending. Filter by company domain (exact, case-insensitive) and/or a free-text query that matches across breach name, title, and publisher domain. Requires any valid API key.

GET/blacklist/breaches/{name}

Get a single breach by name — Returns the full breach record (including the raw HIBP payload) by its HaveIBeenPwned name slug. Returns 404 if no breach matches the slug. Requires any valid API key.

GET/blacklist/credentials/pwned-check

k-anonymity Pwned Passwords check — Checks whether a password appears in the HaveIBeenPwned Pwned Passwords corpus using k-anonymity. Provide exactly one of `password` (hashed to SHA-1 locally before any network call — plaintext never leaves the API) or `sha1` (a pre-computed uppercase 40-hex-char SHA-1). Only the first 5 hex chars of the hash are sent upstream to haveibeenpwned.com; the suffix is matched locally. Returns 400 if neither/both inputs are given or the sha1 is malformed, and 502 on an upstream HIBP error. Requires any valid API key.

GET/blacklist/stats

Blacklist KPI / aggregate counts — Returns aggregate KPIs for the blacklist dataset: blacklisted address totals broken down by category, chain, and source; phishing/IOC indicator totals broken down by source and type; and known-breach totals with the summed pwned-record count. Requires any valid API key.

GET/zero-days/feed

Chronological zero-day signal feed — Returns a paginated, newest-first feed of zero-day-adjacent signals normalised across all watchtower sources (CISA KEV, GitHub PoC repos, Exploit-DB, Fortinet/GitLab PSIRT advisories, etc.). Sorted by `published_at` descending with `observed_at` as the tiebreaker so KEV catalog entries and PoC repos stay in real-world order. Supports filtering by source, vendor, KEV status, AI grading verdict, minimum credibility and lifecycle stage. Requires any valid API key. If the underlying `zero_day_signals` index does not yet exist, returns `{"total": 0, "items": []}`.

GET/zero-days/clusters

Cross-source zero-day correlation clusters — Returns cross-source correlation clusters — one row per CVE / vendor-product triangulated across the watchtower corpus. Each cluster aggregates the source identifiers, member signal IDs, KEV/PoC/advisory flags, max credibility and a deterministic `priority_score`. Default sort is `priority_score` descending then `last_seen` descending (a cheap, explainable structural sort with no AI tie-breakers). Requires any valid API key. If the `zero_day_clusters` index does not yet exist, returns `{"total": 0, "items": []}`.

GET/zero-days/stats

Zero-day corpus health statistics — Returns high-level corpus-health counts for the zero-day signal index: total signals, breakdown by source / vendor / lifecycle stage, plus counts of KEV-listed, CVE-bearing, AI-graded, confirmed-real-zero-day and high-credibility (>=0.7) signals. Powers the frontend 'corpus health' strip. Requires any valid API key. If the `zero_day_signals` index does not exist, returns a zeroed payload (`{"total": 0, "by_source": {}, "by_vendor": {}, "kev": 0, "with_cve": 0}`).

GET/intel/briefing

Latest weekly threat briefing — Returns the most recently generated weekly threat intelligence briefing — an AI analyst's structured read of the ransomware landscape (executive summary, threat landscape, top actors, geographic/sector analysis, emerging threats, forecast, and recommendations), grounded in the platform's real victim data for the period. Requires any valid API key. If no briefing has been generated yet, returns a status object with `status: "no_briefing"` instead of a full briefing.

GET/intel/briefing/history

Historical weekly briefings — Returns up to the last 12 weekly threat briefings, newest first. Each element has the same shape as the object returned by `GET /intel/briefing`. Returns an empty array if no briefings have been generated. Requires any valid API key.

GET/intel/pulse

Latest daily intel pulse — Returns the latest daily intel pulse — a tight 3-5 sentence prose read of what is happening right now in the ransomware/dark-web ecosystem, refreshed every morning from a 24-hour data window. Includes an overall 24h risk level, a short headline, and the raw 24h context used to write it. Requires any valid API key. If no pulse has been generated yet, returns a status object with `status: "no_pulse"`.

GET/intel/forecast

Latest 30-day threat forecast — Returns the latest AI-generated 30-day threat forecast: an overall risk band and numeric score, a set of predictions with confidence/impact ratings, sectors at risk, and groups to watch — all derived from the platform's real 30-day ransomware trends. Requires any valid API key. If no forecast has been generated yet, returns a status object with `status: "no_forecast"`.

POST/intel/ask

Ask the AI threat analyst a question — Submits a free-text question to the AI threat analyst, which answers using ONLY the platform's real 30-day ransomware data (top groups, countries, sectors, surging/new groups, monthly trend). The question is passed as a query parameter (not a JSON body) and is sanitized for prompt-injection markers before use. Returns the question echoed back, the analyst's answer, a generation timestamp, and the data period the answer is grounded in. Requires any valid API key. If the question sanitizes to empty, the response is `{"error": "Empty question"}`; if the analyst backend is unavailable, it is `{"error": "Analyst unavailable"}`.