🐉 Dragons Eye — Ransomware Tracker

Local-first ransomware leak-site collection, parsing, and threat-intelligence API.

Installation · Service management · Updates · Logs · API and CLI

Research use only. Do not use this project to access systems without authorization, interact with ransomware operators, or facilitate criminal activity.

Overview

Dragons Eye collects public data from ransomware leak sites, parses victim records, and serves the resulting data through a local FastAPI service. SQLite is the single live data source.

Service	Purpose	Default address
API	REST API and OpenAPI documentation	http://127.0.0.1:8000
Scheduler	Background scrape and parse cycles	No network listener
Web UI	Optional Next.js dashboard	http://127.0.0.1:8181

The API, scheduler, and CLI work without the UI. The UI uses only the REST API; it does not read SQLite or JSON files directly.

Installation

Supported platforms and prerequisites

install.sh supports macOS through Homebrew and Linux through apt, dnf, or pacman. It checks and installs required components in order:

• Git
• Python 3.9+ and virtual-environment support
• Project-local Python dependencies in .venv
• Playwright Firefox
• Tor, unless --skip-tor is used
• Node.js and npm when the Web UI is selected

Package installation can ask for sudo on Linux. Python packages are installed inside the project-local .venv, not into the system Python installation.

API and scheduler only

git clone https://github.com/frknaykc/DragonsEye-RansomwareTracker.git
cd DragonsEye-RansomwareTracker
./install.sh --non-interactive
./dragons start

The first installation creates the SQLite database and imports bundled JSON data once. Re-running install.sh does not overwrite live SQLite records.

Install with the Web UI

./install.sh --with-ui 8181

This installs frontend dependencies, starts the API and scheduler, then starts the UI in the background. Open http://localhost:8181.

Use another port if needed:

./install.sh --with-ui 3000

Installer reference

Option	Purpose
--non-interactive	Do not ask whether to install or start the UI.
--with-ui [port]	Install UI dependencies and start the UI. Default: 8181.
--skip-tor	Skip Tor installation and service startup.
--check	Report missing prerequisites without changing the machine.

./install.sh --help
./install.sh --check --skip-tor
./install.sh --non-interactive --skip-tor

Service management

Run lifecycle commands from the repository root.

Status

./dragons status

Example:

{
  "api": { "pid": 1234, "healthy": true },
  "scheduler": { "pid": 1235, "status": { "status": "idle" } },
  "ui": { "pid": 1236, "healthy": true, "port": 8181 }
}

• api.healthy: true means the API health endpoint responds.
• Scheduler status can be idle, scraping, parsing, or error.
• ui.healthy: true means the UI responds on its configured port.

Start

Start the API and scheduler:

./dragons start

Start the optional UI:

./dragons start-ui --port 8181

start-ui requires frontend dependencies. On a new installation, run ./install.sh --with-ui 8181 first.

Stop

# Stop every managed service
./dragons stop all

# Stop one service
./dragons stop api
./dragons stop scheduler
./dragons stop ui

Restart

./dragons stop all
./dragons start
./dragons start-ui --port 8181

Omit the last command if you do not use the UI. After a machine reboot, services must be started again with these commands.

Updates

After the initial installation, use:

./dragons update

./dragons upgrade is an alias for the same command.

The managed updater:

1. Stops if there are tracked local changes, so it does not overwrite them.
2. Pulls origin/main with git pull --ff-only.
3. Stops managed services.
4. Runs ./install.sh --non-interactive to apply Python dependencies, Playwright, and SQLite migrations.
5. Restarts only services that were running before the update.

If the UI was running, its Node dependencies are refreshed and it is restored on the same port.

If every service was stopped before ./dragons update, the command does not start services automatically. Start them manually after the update:

./dragons start
./dragons start-ui --port 8181

For an older checkout that does not yet have ./dragons update, use this one-time sequence:

./dragons stop all
git pull origin main
./install.sh --non-interactive
./dragons start
./dragons start-ui --port 8181

Monitoring and logs

Managed-service logs are stored in logs/.

File	Contents
logs/scheduler.log	Scheduler state, live scraper output, parser output, and cycle results.
logs/api.log	API startup, requests, and backend errors.
logs/ui.log	Next.js UI startup and frontend errors.

# Follow scraper and parser output live
tail -f logs/scheduler.log

# Follow API or UI logs
tail -f logs/api.log
tail -f logs/ui.log

Ctrl+C stops log following only. It does not stop managed services.

Typical scheduler output:

[scrape] [group-name] Scraping http://...
[scrape] [group-name] OK (18KB) - page title
[scrape] [group-name] Attempt 2 failed, retrying...
✅ Scrape completed successfully
🔄 Starting parse operation...
✅ Parse completed successfully

NS_ERROR_UNKNOWN_HOST, NS_ERROR_CONNECTION_REFUSED, timeouts, 403 Forbidden, and CAPTCHA messages often mean that a target site is offline, moved, unreachable, or protected. The scheduler records the failure and continues with other groups. A final Scrape failed or Parse failed status means the complete phase exited unsuccessfully; inspect the preceding log lines for the cause.

The default collection interval is six hours. Set SCRAPE_INTERVAL_HOURS in .env to override it.

API and CLI

API health and documentation

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/api/v1/status

Interactive documentation is at http://127.0.0.1:8000/docs.

curl 'http://127.0.0.1:8000/api/v1/victims?limit=10'
curl 'http://127.0.0.1:8000/api/v1/groups?limit=10'
curl 'http://127.0.0.1:8000/api/v1/stats/summary'

Query SQLite without the UI

./dragons query victims --limit 10
./dragons query groups --limit 10
./dragons query decryptors --limit 10
./dragons query ransom_notes --limit 10

Export a JSON backup

SQLite remains the live source of truth. JSON files are initial import sources and explicit exports.

./dragons backup --output backups/manual-$(date +%Y%m%d-%H%M%S)

Do not use ./dragons setup --force for normal operation. It intentionally rebuilds the SQLite dataset from import sources.

Complete dragons command reference

Command	Purpose
./dragons setup	Create or migrate SQLite and import JSON only when the database has not been initialized.
./dragons setup --force	Explicitly rebuild SQLite from import sources; destructive to live SQLite state.
./dragons backup [--output PATH]	Export the current SQLite data to JSON.
./dragons start [--port PORT]	Start the API and scheduler.
./dragons start --no-scheduler	Start only the API.
./dragons start-ui [--port PORT]	Start the optional UI in the background.
./dragons status [--port PORT] [--ui-port PORT]	Report API, scheduler, and UI state.
./dragons stop [api|scheduler|ui|all]	Stop one managed service or all of them.
./dragons update [--port PORT] [--ui-port PORT]	Fast-forward source, refresh dependencies, and restore previously running services.
./dragons upgrade	Alias for ./dragons update.
./dragons query <victims|groups|decryptors|ransom_notes>	Query the selected SQLite dataset.

Use ./dragons <command> --help for the exact options available in the installed version.

Data layout

Path	Purpose
db/dragons_eye.sqlite3	Live data for the API, CLI, scheduler, scraper, parser, and UI.
db/*.json	Bundled one-time import data.
backups/	JSON exports created by ./dragons backup.
logs/	API, scheduler, and UI logs.
tmp/run/	PID files for managed background processes.
.venv/	Project-local Python runtime created by the installer.

Optional configuration

Copy the environment template before adding settings:

cp env.example .env

DRAGONS_HOME=/path/to/DragonsEye-RansomwareTracker
SCRAPE_INTERVAL_HOURS=6
TOR_PROXY_SERVER=socks5://127.0.0.1:9050

# Optional AI enrichment
OPENAI_BASE_URL=http://localhost:1234/v1
# OPENAI_API_KEY=your-key

Keep .env private. Do not commit credentials, tokens, or API keys.

Manual maintenance

The managed scheduler is the supported collection path. Use manual commands only for troubleshooting or controlled maintenance:

# Run a full scheduler cycle in the foreground
.venv/bin/python bin/scheduler.py --once

# Run one phase
.venv/bin/python bin/scheduler.py --scrape
.venv/bin/python bin/scheduler.py --parse

# Show SQLite-backed scheduler state
.venv/bin/python bin/scheduler.py --status

Stop the background scheduler before manual collection to avoid overlap:

./dragons stop scheduler
.venv/bin/python bin/scheduler.py --once
./dragons start

Contributing

Contributions that improve parsers, collection reliability, data quality, documentation, and the UI are welcome. Keep credentials and target-specific private data out of commits.

License

This project is released under the Unlicense.

🐉 Dragons Eye — Ransomware Tracker
Made with 🔥 by Dragons Community for the cybersecurity community