If your daily routine is a wall of browser tabs — VirusTotal in one, Shodan in another, three more for a username or a phishing domain — Corvid replaces that wall with a single keyboard-first search bar. Paste an IP, domain, hash, email, or username and it's routed to the right tools automatically; type a tool name to jump straight to it.
Corvid is self-hostable and built for single-user operation: it runs in one Docker container on your own infrastructure, so investigation data and API keys never pass through a third-party SaaS. It's a workbench, not a data warehouse — no long-term case management, just fast, on-demand IOC lookups, email/image forensics, phishing-domain discovery, identity correlation (Reddit, GitHub, usernames), and detection-rule authoring, with generative AI wired in to speed up analysis and write-ups along the way.
curl -fsSL https://raw.githubusercontent.com/z0rats/corvid/main/install.sh | bashPulls pre-built images and starts the app at http://localhost:4000 — no auto-update, see Deploy with docker for details and the build-from-source alternative.
IOC lookups auto-route to the right services based on the type you paste in:
- IPs — AbuseIPDB, AlienVault, CheckPhish.ai, CrowdSec, GitHub, IPQualityScore, Maltiverse, Pulsedive, Reddit, Shodan, ThreatFox, Twitter/X, VirusTotal
- Domains — AlienVault, CheckPhish.ai, GitHub, Maltiverse, Pulsedive, Reddit, Shodan, ThreatFox, Twitter/X, URLScan, VirusTotal
- URLs — AlienVault, CheckPhish.ai, GitHub, Google Safe Browsing, Maltiverse, Pulsedive, Reddit, Shodan, ThreatFox, Twitter/X, URLScan, VirusTotal
- Emails — Emailrep.io, GitHub, Have I Been Pwned, Hunter.io, Reddit, Twitter/X
- Hashes — AlienVault, GitHub, Maltiverse, Pulsedive, Reddit, ThreatFox, Twitter/X, VirusTotal
- CVEs — GitHub, NIST NVD
- Crypto addresses (EVM & Bitcoin) — screened against a self-hosted blacklist built from the OFAC SDN sanctions list and ScamSniffer's open phishing-address dataset, refreshed daily in the background; no API key or third-party calls required
The Newsfeed module keeps you up to date about the latest cybersecurity news by aggregating articles from trusted sources such as Wired, The Hacker News, Security Magazine, Threatpost, TechCrunch Security, and Dark Reading. Stay up-to-date with industry trends and potential threats without having to visit multiple websites or subscribe to numerous newsletters. The module extracts IOCs automatically from the news articles and lets you analyze news in no time using AI.
The IOC Tools module helps you analyze different types of indicators of compromise (IOCs) such as IP addresses, hashes, email addresses, domains, URLs, and crypto addresses (EVM and Bitcoin). It leverages services like VirusTotal, AlienVault, AbuseIPDB, and social media platforms like Reddit and Twitter to gather information about the IOCs. Crypto addresses are screened against a self-hosted reputation blacklist built from the OFAC SDN sanctions list and ScamSniffer's open phishing-address dataset, refreshed daily — no API key or third-party calls needed for this check. The module automatically detects the type of IOC being analyzed and utilizes the appropriate services to provide relevant information, enabling you to identify potential threats and take necessary actions to protect your organization. Analysis can be done individual per IOC or in bulk. Also fanging and defanging is possible for sharing IOCs safely.
The Email Analyzer module allows you to analyze .eml files for potential threats. Simply drag and drop an .eml file into the module, and it will parse the file, perform basic security checks, extract indicators of compromise (IOCs), and analyze messages with the help of AI. Analyze the IOCs using various open-source intelligence (OSINT) services, and enhance your organization's email security.
The Image Tools module lets you inspect an image file for OSINT purposes. Upload a picture to see every piece of metadata it carries — EXIF camera/device info, capture timestamp, GPS location with a map link, embedded thumbnail, file properties, and MD5/SHA1/SHA256 hashes. You can also kick off a reverse image search without any API keys: provide the image's URL to get deep links straight into Google Lens, Yandex, Bing, and TinEye, or use the same buttons to open each engine for a manual upload.
The Domain Finder module helps you to protect your organization from phishing attacks by searching for recently registered domains that match specific patterns. By utilizing the URLScan.io API, you can view screenshots of websites associated with domains without visiting them directly. Additionally, you can check each domain and its resolved IP against multiple threat intelligence services, further enhancing your organization's security.
The AI Templates module provides powerful AI-based solutions for log data analysis, email text analysis, and source code explanation. It lets you create templates for AI tasks and supports you in the prompt engineering process.
The CVSS Calculator module allows you to calculate the CVSS 3.1 score of a vulnerability and export the calculation as a markdown or JSON file.
The Detection Rules module is a GUI for creating Sigma, Yara and Snort/Suricate rules.
The Reddit Search module finds a Reddit user's full post and comment history, including content removed by moderators or deleted by its author, by querying the public Arctic Shift and PullPush archive APIs in parallel — no API key required. Filter by subreddit, date range, or NSFW status, and page through results by post or comment. Each search is saved to history so you can revisit it later.
The Git Recon module correlates names, emails, and GitHub logins from git commit history using gitcolombo. Search mode queries GitHub's API only (PGP-key UIDs + public commit search) for a username, no cloning required. Repo/user modes clone one repository or every public repository of a GitHub user/org and cross-reference author vs. committer identities to surface aliases and shared-identity clusters. A GitHub personal access token (configured under Settings > API Keys) is optional but recommended to avoid unauthenticated GitHub rate limits.
Corvid is built around a single search bar instead of hunting through menus. Press / or
⌘K/Ctrl+K from anywhere to open it, then:
- Type a tool's name —
reddit,git recon,whois— to jump straight to it. - Paste a raw value — an IP, domain, e-mail, hash, CVE ID, or crypto address — and Corvid suggests which tools can look it up.
- Add a tool name after a value (
john_doe reddit) to open that tool with the value already filled in. - Filter with
#tag(#recon,#ioc) ortype:kind(type:email). - Prefix
>for quick actions (>settings,>theme). defang <value>/fang <value>copies a de-fanged/re-fanged IOC straight to your clipboard — nothing to open.- Paste an image (
⌘V/Ctrl+V) to jump into Image Tools with it already loaded.
No keyboard handy? The panel on the left lists every tool, grouped the same way the search tags do — click through instead of typing.
Press ? any time for the full shortcut list.
- Docker Engine 24+ with the Docker Compose v2 plugin (the
docker composecommand, not the legacy standalonedocker-composebinary) - Linux, macOS, or Windows (via Docker Desktop/WSL2)
- At least ~1 GB free disk for the app itself; more if you enable
email_search's optional headless checkers, which lazily download a Chromium binary (~150-300 MB) on first use — see Disk usage below - Outbound HTTPS access for the third-party services you configure (VirusTotal, Shodan, etc.) — no inbound ports need to be exposed
- No GPU or special hardware needed. CPU/RAM haven't been formally benchmarked, but as a single-user tool with no background crawling by default, it's light — a small VM (1-2 vCPU, 2 GB RAM) is comfortable for typical use
Option A — one-line install (pre-built images). Pulls ready-made images from GHCR instead of
building from source. Installs into ~/corvid by default (override with CORVID_DIR):
curl -fsSL https://raw.githubusercontent.com/z0rats/corvid/main/install.sh | bashOnce it's running, open http://localhost:4000. There's no auto-update — new versions aren't
pulled without your say-so. To update later, run ./update.sh from the install directory (it
pulls the latest images and recreates the containers).
Option B — build from source. Gives you a local build instead of pulling from a registry, and lets you review the Dockerfiles before anything runs:
- Download the repository and extract the files
- Navigate to the directory where the
docker-compose.yamlfile is located - Start the application:
make up— start backend and frontend without rebuildingmake rebuild— rebuild images (e.g. after dependency or Dockerfile changes) and startmake up-backend/make up-frontend— start a single service without rebuildingmake rebuild-backend/make rebuild-frontend— rebuild and start a single service
- Once the container is running, you can access the application in your browser at http://localhost:4000
Database migrations run automatically on container startup — no manual step needed after
make rebuild. If you need to run one by hand (e.g. to check for pending migrations without
starting the app), you can still run: docker compose run --rm backend alembic upgrade head
The app has no user accounts, so it's protected by a single access token instead of a login form.
On first startup, a token is generated automatically and printed to the backend logs
(docker compose logs backend) and saved to data/.access_token on the host. Open
http://localhost:4000, and you'll be asked to paste that token once — it's then remembered in
the browser.
To set your own fixed token instead of the auto-generated one, set API_ACCESS_TOKEN in .env
before starting the container.
Copy .env.example to .env to override any setting (all of them have working
defaults, so this is optional). .env is read automatically by docker compose up.
Show details
Everything Corvid needs to keep running lives under the host-mounted data/ directory — back it
up as a whole (stop the container first for a consistent SQLite snapshot, or use sqlite3 .backup
for a live one):
data/corvid.db— the SQLite database: investigation history, settings, and encrypted API keys.data/.encryption_key— decrypts the API keys stored in the database. Losing this file makes stored keys unrecoverable even though the database itself is intact; re-entering the keys is the only fix.data/.access_token— the bearer token protecting the app. Losing it isn't a data-loss risk — a new one is generated on next startup and you just re-enter it in the browser.data/logs/— optional, rotated application logs.
Losing data/ entirely means starting over from a blank instance; there is no other durable state.
Permissions travel with the backup. .encryption_key and .access_token are written 0600
on the host, but that only protects them in place. A backup method that doesn't preserve file
modes/ownership (a permissive tar extraction, copying into a world-readable cloud-sync folder,
chmod -R during restore) — or that lands the backup somewhere with broader access than the
source host — defeats the encryption-at-rest story: the key ends up sitting right next to the
ciphertext it decrypts. Preserve permissions in transit (tar --preserve-permissions, rsync -a)
and restrict access to the backup destination at least as tightly as data/ itself.
Show details
data/ has no total-size guard, so keep an eye on the host mount over time. Rough steady-state
contributors: the SQLite database and rotated logs stay small (tens of MB); maigret's site
database and its own image-hash cache add tens of MB; email_search's headless checkers
(if enabled) lazily download a Chromium binary the first time they run (~150-300 MB, plus its own
runtime footprint); exported reports accumulate if you generate a lot of them and never clean up.
The backend logs a warning at startup (and the disk field in
GET /api/healthcheck/detailed reports "status": "low") once free space on the data/ mount
drops below 1 GB, but nothing actively stops writes past that point — treat it as an early signal,
not a hard limit.
Show details
This tool talks to third-party services (VirusTotal, Shodan, target mail servers via
email_search's SMTP checks, etc.) using your own infrastructure's IP, and stores investigation
history in a local database. Some practices worth following, especially for sensitive engagements:
- Isolate the instance. Run it on a dedicated VM/VPS or an isolated host, not your daily-driver machine — a target under investigation can potentially see inbound lookups against them.
- Route sensitive lookups through Tor/a proxy.
email_searchsupportsuse_tor/proxy_url, andusername_search's maigret source has its own proxy setting, for when a target could plausibly monitor who's probing them. - Never enable
SECURITY_ALLOW_PRIVATE_NETWORK_TARGETSoutside dev/testing — it's a direct SSRF opt-out. - Segment and rotate API keys per engagement where the provider supports multiple keys, so a compromised key from one case doesn't expose others.
- Don't cross-contaminate identities. Some features (e.g. Image Tools' reverse-search deep-links) open external services directly in your browser — use a separate, logged-out browser profile for sensitive lookups so they don't tie back to your personal accounts.
Corvid is a tool, not a policy — how you point it is on you. It's built for legitimate use cases: internal security teams triaging IOCs, threat intel analysts enriching indicators, researchers investigating abuse, and similar authorized work. It is not built for stalking, harassment, unauthorized surveillance, or investigating people without a lawful basis for doing so.
Several modules (Reddit Search, Git Recon, Image Tools' reverse-search, email/username lookups) pull together data that's technically public but can still identify or locate a real person when combined. Before running them against an individual rather than an IOC or organization, make sure you have a legitimate basis to do so and that it complies with the laws of your jurisdiction and the target's (data protection/privacy law, computer-misuse law, and your organization's own policies, at minimum). Some integrated services carry their own terms of use and rate limits that are yours to respect — Corvid doesn't police that for you.
None of this constitutes legal advice, and the author takes no responsibility for how the tool ends up being used. When in doubt, check with your legal/compliance function before running an investigation, not after.
Corvid is licensed under the GNU Affero General Public License v3.0.
You are free to use, modify, and distribute this software, provided that any modified versions or services built on it are also made available under AGPL-3.0, including when offered as a network service.
If AGPL-3.0 doesn't fit your use case — for example, if you want to integrate Corvid into a proprietary product or offer it as a managed service without open-sourcing your modifications — a commercial license is available.
Contact: [z0rats.alex@gmail.com]
Versions up to and including v0.1.0 were released under the MIT License and remain available under those terms.