Add Ransomware.Live Pro API engine for domain victim lookup

[Copilot]

Adds a new ransomware_live engine that queries the Ransomware.Live Pro API to check whether a domain has ever appeared as a ransomware victim on a data leak site (DLS).

Summary

• New engine querying GET https://api-pro.ransomware.live/victims/search with X-API-KEY header authentication and q query parameter
• Supports FQDN and URL observables (URL → domain extraction via existing pattern)
• Returns: found flag, victim count, per-victim details (post_title, group_name, website, discovered timestamp, permalink link to Ransomware.Live entry)
• Strips client email field from the API response — never stored or exposed
• Builds a search_url (https://www.ransomware.live/search?q=<domain>&scope=all) for direct GUI navigation, URL-encoded for safety
• Gracefully returns None when API key is absent
• API is limited to 3,000 calls/day (sufficient for typical usage)
• Full UI integration: card/table layouts, display_cards.html, display_table.html, index.html checkbox (☠️, alphabetical), clipboard copy in format_results.js, ransomware group nodes in graph.html
• Docs: new API key guide (docs/api-keys/Get-Ransomware-Live-API-key.md) referencing https://www.ransomware.live/api, engine entry in API-usage-and-engine-names.md, mkdocs.yml sidebar entry

Scope

• Bug fix
• New feature
• Refactor
• Documentation
• New engine
• Other (describe):

Validation (required)

• I ran relevant tests locally and they pass.
• I validated real behavior (not only code style or static checks).
• I checked edge cases and failure paths.

Test evidence

17 tests covering: victim found/not-found, correct endpoint/header/param usage, URL domain extraction, missing API key, HTTP 401/403/404/500, connection timeout, invalid JSON, multiple victims, export row formatting, and engine properties.

pytest tests/engines/test_ransomware_live.py -v
# 17 passed in 0.19s

pytest tests/ -q
# 1206 passed

AI-assisted contribution disclosure

• This PR includes AI-assisted work.
• I reviewed and understood all generated code.
• I refined AI output where needed (no low-quality slop).
• I am fully responsible for this submission.

Engine scaffolding, templates, test suite, and UI integration were AI-assisted.

Maintainer merge policy acknowledgement

• I understand uncertain changes may be merged to dev first for additional validation.
• I understand main is kept clean/stable for releases and tags.

New engine checklist (only if applicable)

Engine Implementation

• Added engine file in engines/ransomware_live.py (using existing engines as template).
• Added engine import/registration in engines/__init__.py.
• Added engine config/secret variable in utils/config.py (ransomware_live_api_key).

Configuration & Secrets

• Added needed API key/config vars to .env.sample (RANSOMWARE_LIVE_API_KEY).
• Verified variable templating in docker-compose.yml.

UI & Frontend

• Engine result is copyable via GUI in static/format_results.js.
• Added/updated layouts in templates/engine_layouts/ for card/table rendering.
• Added engine in templates/display_cards.html and templates/display_table.html.
• Added engine in templates/index.html with description (alphabetic order).
• Added engine support for graph view in templates/graph.html.

Documentation

• Added docs in docs/api-keys/Get-Ransomware-Live-API-key.md (if relevant).
• Added API key guide link in docs/index.md (if relevant).
• Added engine to docs/quick-start/API-usage-and-engine-names.md.
• Added page in mkdocs.yml sidebar.
• Updated docs/quick-start/Quick-start-&-Installation.md and .env examples.
• Added env vars to docs/quick-start/Advanced-options-for-deployment.md (docker compose example).
• Updated README.md references (env vars and API/services section).

Risk and rollback

• Risk level: Low
• Potential impact: Additive only — no changes to existing engines or shared logic
• Rollback strategy: Remove engine file and revert load_engines.py / config.py / template additions

Additional notes

• The Pro API requires a paid key; the engine silently returns None without one, consistent with other keyed engines.
• Remaining unchecked items (docker-compose.yml, docs/index.md, Quick-start docs, README.md) are follow-up tasks.

[stanfrbd]

@copilot

This method doesn't exist.

API Details

• Base URL: https://api-pro.ransomware.live
• Search Endpoint: GET /victims/search
• Key Parameters: - query: Use this to search for a victim name or a domain (e.g., "example.com").
• Authentication: Requires an 'api-key' in the request header.

Task

1. Explain how to use the /victims/search endpoint to monitor a specific domain.
2. Detail the structure of a Python request to this endpoint.
3. Describe how to interpret the JSON response, which typically includes:
   • victim_name: The targeted entity.
   • group_name: The ransomware group involved.
   • website: The victim's URL (confirming the domain match).
   • discovered: The timestamp when the leak was indexed.

Implementation Guide

Provide a concise Python example using 'requests' with the following structure:

• URL: base_url + "/victims/search"
• Headers: {"api-key": "YOUR_API_KEY"}
• Params: {"query": "target-domain.com"}

[Copilot]

@copilot

This method doesn't exist. ...

Fixed in 408365d. The engine now uses:

• Endpoint: GET https://api-pro.ransomware.live/victims/search
• Auth: {"api-key": api_key} header
• Query param: {"query": domain}
• Response fields mapped: victim_name, group_name, website, discovered

[stanfrbd]

@copilot

Actually the real API key header is

X-API-KEY

And the query parameter is not query but q

[Copilot]

@copilot

Actually the real API key header is ...

Fixed in 553def3. The engine now uses X-API-KEY as the header and q as the query parameter.

[stanfrbd]

@copilot

Well actually here is a valid example with curl

curl -X 'GET' \
  'https://api-pro.ransomware.live/victims/search?q=cisco.com&order=discovered' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: REDACTED'

Response

{
  "client": REDACTED_EMAIL_REQUESTER,
  "query": "cisco.com",
  "group": null,
  "sector": null,
  "country": null,
  "order": "discovered",
  "count": 4,
  "victims": [
    {
      "post_title": "Cisco Systems, Inc. (cisco.com)",
      "group_name": "shinyhunters",
      "discovered": "2026-04-01 13:14:13.378173",
      "description": "3 breaches ( UNC6040 , Salesforce Aura, and AWS accounts). Total over 3M Salesforce records containing PII, Github repositories, AWS buckets and other internal corporate data have been compromised. This is a final warning to reach out by 3 Apr 2026 before we leak along with several annoying (digital) problems that'll come your way. Make the right decision, don't be the next headline. | Updated: 31 Mar 2026 | Warning: FINAL WARNING",
      "website": "cisco.com",
      "published": "2024-04-24 00:00:00.000000",
      "post_url": "",
      "country": "US",
      "activity": "Technology",
      "duplicates": [
        {
          "date": "2026-04-01 13:14:13.441685",
          "group": "kraken",
          "link": "https://www.ransomware.live/id/d3d3LmNpc2NvLmNvbUBrcmFrZW4=",
          "attackdate": "2024-04-24 00:00:00.000000"
        }
      ],
      "extrainfos": [],
      "screenshot": "",
      "infostealer": {
        "update": "2024-04-19 08:22:28",
        "employees": 556,
        "users": 332412,
        "thirdparties": 1053,
        "employees_url": 100,
        "users_url": 100
      },
      "press": null,
      "id": "Q2lzY28gU3lzdGVtcywgSW5jLiAoY2lzY28uY29tKUBzaGlueWh1bnRlcnM=",
      "permalink": "https://www.ransomware.live/id/Q2lzY28gU3lzdGVtcywgSW5jLiAoY2lzY28uY29tKUBzaGlueWh1bnRlcnM="
    },
    {
      "post_title": "www.cisco.com",
      "group_name": "kraken",
      "discovered": "2025-02-09 19:05:56.838028",
      "description": "You lied to us and play for time to kick us out.\n\nWe will meet you soon, again. Next time you'll have no chance.\n\ncisco.com\\...",
      "website": "cisco.com",
      "published": "2024-04-24 00:00:00.000000",
      "post_url": "http://krakenccj3wr23452a4ibkbkuph4d6soyx2xgjoogtuamc3m7u7wemad.onion/news/473748aaaa880d98c509a58e1c39021c",
      "country": "US",
      "activity": "Technology",
      "duplicates": [
        {
          "date": "2025-02-09 19:05:56.841735",
          "group": "ransomhub",
          "link": "https://www.ransomware.live/id/d3d3LnBvcnRvc2FvZnJhbmNpc2NvLmNvbS5ickByYW5zb21odWI=",
          "attackdate": "2024-04-24 00:00:00.000000"
        }
      ],
      "screenshot": "https://images.ransomware.live/victims/9c012ee3a56ef1bad6511523a0117dd3.png",
      "infostealer": {
        "update": "2024-04-19 08:22:28",
        "employees": 556,
        "users": 332412,
        "thirdparties": 1053,
        "employees_url": 100,
        "users_url": 100
      },
      "press": null,
      "id": "d3d3LmNpc2NvLmNvbUBrcmFrZW4=",
      "permalink": "https://www.ransomware.live/id/d3d3LmNpc2NvLmNvbUBrcmFrZW4="
    },
    {
      "post_title": "www.portosaofrancisco.com.br",
      "group_name": "ransomhub",
      "discovered": "2024-06-04 23:16:50.220985",
      "description": "",
      "website": "portosaofrancisco.com.br",
      "published": "2024-04-24 00:00:00.000000",
      "post_url": "http://ransomxifxwc5eteopdobynonjctkxxvap77yqifu2emfbecgbqdw6qd.onion/856e9aa1-b97a-4295-8d55-1e2c5aab3107/",
      "country": "BR",
      "activity": "Transportation/Logistics",
      "duplicates": [],
      "screenshot": "https://images.ransomware.live/victims/5931d4c5f1ce772c3f6943ebb9b73ad4.png",
      "infostealer": {
        "update": "2024-06-05 00:21:57",
        "employees": 0,
        "users": 9,
        "thirdparties": 0,
        "employees_url": 0,
        "users_url": 0
      },
      "press": null,
      "id": "d3d3LnBvcnRvc2FvZnJhbmNpc2NvLmNvbS5ickByYW5zb21odWI=",
      "permalink": "https://www.ransomware.live/id/d3d3LnBvcnRvc2FvZnJhbmNpc2NvLmNvbS5ickByYW5zb21odWI="
    },
    {
      "post_title": "Hey cisco!",
      "group_name": "hellogookie",
      "discovered": "2024-04-19 08:12:51.262820",
      "description": "You lied to us and play for time to kick us out. We will meet you soon, again. Next time you'll have no chance. cisco.com\\Administrator:500:aad3b435b51404eeaad3b435b51404ee:4e0de2e548880cd48c588f1391fa6386:::\ncisco.com\\carriep:12342831:aad3b435b5140...",
      "website": "cisco.com",
      "published": "2024-04-19 08:12:51.262790",
      "post_url": "http://hellogookie256cvccntvenyxrvn7ht73bs6ss3oj2ocfkjt5y6vq6gfi2tad.onion/news/473748aaaa880d98c509a58e1c39021c",
      "country": "US",
      "activity": "Technology",
      "duplicates": [],
      "screenshot": "",
      "infostealer": {
        "update": "2024-04-19 08:22:28",
        "employees": 556,
        "users": 332412,
        "thirdparties": 1053,
        "employees_url": 100,
        "users_url": 100
      },
      "press": null,
      "id": "SGV5IGNpc2NvIUBoZWxsb2dvb2tpZQ==",
      "permalink": "https://www.ransomware.live/id/SGV5IGNpc2NvIUBoZWxsb2dvb2tpZQ=="
    }
  ]
}

You have to remove the client email address from the response and be creative with this: I will need permalink and url search request of the GUI that will look like this:

https://www.ransomware.live/search?q=cisco.com&scope=all

Be consistent with other engines and checklists.

Be aware that the API is limited to 3000 calls per day, which is enough!

Add this to the docs with reference https://www.ransomware.live/api

[Copilot]

@copilot

Well actually here is a valid example with curl...

Done in 8f797b2 (+ URL-encoding fix in e1e8ecf). Here's a summary of what was changed:

Engine (engines/ransomware_live.py):

• Parses the correct response envelope (data["victims"] dict, not a bare list)
• Maps post_title, group_name, website, discovered, permalink per victim — client email field is never stored
• search_url is now https://www.ransomware.live/search?q={encoded_domain}&scope=all
• create_export_row uses post_title for the victims column

Templates:

• Card layout: shows post_title, group, website, discovered, per-victim permalink link, and a search link at the bottom
• Table layout: shows victim count + groups, with a "Search on Ransomware.Live" link
• Wired into display_cards.html, display_table.html (header + cell), templates/index.html (☠️ checkbox, alphabetical), static/format_results.js (copy with permalink), templates/graph.html (ransomware group nodes)

Docs:

• docs/api-keys/Get-Ransomware-Live-API-key.md — references https://www.ransomware.live/api
• docs/quick-start/API-usage-and-engine-names.md — engine entry added
• mkdocs.yml — sidebar entry added

All 1206 tests pass.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• www.spamhaus.org
  • Triggering command: /home/REDACTED/.local/bin/pytest pytest tests/ -q (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)