harpoon is a Python CLI that consolidates dozens of OSINT and threat intelligence data sources — Shodan, Censys, VirusTotal, passive DNS — into one command interface for authorized investigations.
| Tool | Te-k/harpoon — OSINT / Threat Intelligence CLI tool written in Python, distributed via PyPI |
| Category | OSINT aggregation framework / threat intelligence command-line utility |
| Primary Use | Centralizing indicator enrichment across Shodan, Censys, VirusTotal, crt.sh, MISP, passive DNS and similar sources during authorized investigations |
| Safe Use | Intended for authorized security assessments, threat intelligence research, and defensive enrichment of indicators within scopes you are permitted to investigate |
| Telemetry Note | Every query is executed against third-party APIs under your own keyed accounts, leaving audit trails on Shodan, Censys, VirusTotal and other provider logs tied to your API keys |
harpoon is a long-lived open source project by Te-k that answers a deceptively simple question: why should an analyst keep forty browser tabs and a folder of API scripts open when one command-line tool can front-end all of them? The repository is tagged with osint, osint-framework, threat-intelligence and threatintel, and the README describes it plainly as an OSINT / Threat Intel CLI tool. With nearly thirteen hundred stars, a GPL-3.0 license and a published package on PyPI, it sits squarely in the category of operational analyst tooling rather than a weekend experiment. The project is written in Python, which matters because the installation path leans on native XML libraries and the standard packaging ecosystem rather than shipping a heavyweight binary.
Architecturally, harpoon is a plugin shell. The harpoon executable dispatches to subcommands, each of which wraps a specific external API or public data source. The README lists roughly fifty commands, and the breadth is the point: asn, ip, dns, email, intel, and subdomains act as aggregation commands, while a long tail of source-specific commands such as shodan, censys, vt, otx, greynoise and misp bind directly to named platforms. This is the classic osint-framework pattern — a thin, uniform CLI veneer over heterogeneous REST APIs — and it is the reason tools like this become muscle memory for analysts who spend their day pivoting between indicators.
Installation is straightforward but not dependency-free. The README calls out lxml prerequisites at the OS level, with package lists for Debian/Ubuntu (libxml2-dev, libxslt-dev, python3-dev) and a considerably longer chain for Fedora. Once those are satisfied, pip install harpoon is the primary path, with a source route via git clone followed by pip3 install . for users who prefer virtualenvs or need the cutting edge. A companion package, harpoontools, is mentioned as optional and providing additional commands built on harpoon features — a hint that the author expects the ecosystem to grow around the core shell.
One requirement deserves attention because it quietly shapes the geolocation workflow: geoipupdate, MaxMind's official updater, must be installed and configured with GeoLite2-Country, GeoLite2-City and GeoLite2-ASN editions listed in EditionIDs. This tells you harpoon does local GeoIP resolution from downloaded databases rather than hammering a geolocation API for every lookup, which is both faster and quieter from an operational-security standpoint. Analysts who skip this step will find the ip and asn commands degraded, so treat it as a first-run chore rather than an optional extra.
Configuration follows the expected pattern for key-heavy tooling. harpoon config walks you through entering API keys, harpoon update downloads the data files the tool needs locally, and harpoon config -c reports which plugins are actually configured — a genuinely useful touch, since the gap between 'installed' and 'usable' in OSINT tools is almost always a missing credential. The README links a wiki for deeper documentation, and per-command help is available through harpoon help COMMAND, which is how you discover the flags each plugin exposes without leaving the terminal.
The source list is where harpoon shows its age in a good way — it is a map of the intelligence landscape. Certificate transparency arrives via crtsh and certspotter, with the README candidly noting that certspotter's paid tier (expired certificates) offers little over crtsh or censys. Passive DNS is covered three ways: circl against the CIRCL passive DNS database, dnsdb against Farsight DNSDB, and zetalytics. Sandbox and malware repositories are represented by hybrid, malshare and urlhaus, while hashlookup queries the CIRCL hash lookup database for file reputation. Threat-platform integrations include misp for MISP servers, otx for AlienVault OTX, xforce for IBM X-Force Exchange and pt for PassiveTotal — the last of which is particularly valuable for domain infrastructure attribution.
The web-visibility side is equally broad. shodan, censys and binaryedge cover external attack-surface scanning data; robtex, spyonweb and securitytrails cover domain-to-IP and hosting history pivots; urlscan both searches and submits URLs for scanning; safebrowsing checks Google's blocklists and umbrella checks the Cisco Umbrella top-one-million list. Reputation and blocklist angle checks include quad9 for DNS-level blocking status and tor for matching an IP against the public Tor exit-node list. On the human-intelligence side, email, hibp, hunter, fullcontact, numverify, pgp, telegram and twitter pull breach data, contact enrichment, phone metadata and keyserver lookups — the classic identity-expansion toolkit for phishing assessment pre-work or attribution research.
From an authorized-workflow perspective, harpoon fits best in the reconnaissance and enrichment phases of a scoped assessment, and in threat-intel triage where an analyst needs a first-pass answer on an indicator in seconds. The intel command, which the README describes as gathering information on a domain, appears to be the aggregation entry point — the one command that fans out across configured plugins and stitches the results, sparing the analyst from running each source manually. For blue-team use, the same commands double as enrichment for IOC lists: run vt, otx and urlhaus against a batch of indicators and you have a quick confidence score before anything touches a SIEM.
Operational considerations are worth stating plainly. Every plugin executes against a third-party service under your account and API key, so your query patterns are visible to those providers and rate limits apply; an analyst investigating a sensitive actor should assume Shodan and VirusTotal logs tie those searches to their key. The README also documents a cache command for requesting webpage caches from different sources and a save command that archives a page to cache platforms — a defensible evidence-preservation pattern when you need a timestamped snapshot without repeatedly touching the target infrastructure directly.
A few details round out the picture. GreyNoise support distinguishes between Community and Enterprise API via the api_type config setting, though both still require a key — a welcome bit of honesty about licensing tiers. The koodous command targets Android malware analysis through the Koodous platform, an unusual inclusion that makes harpoon useful for mobile threat research too. Updating is handled either through pip install -U harpoon for PyPI installs or git pull plus pip install . for source installs, and a contributed-credits section names several GitHub contributors, signaling a small but real maintenance community.
For defenders, harpoon is best understood as a visibility tool that works both directions: it accelerates your own enrichment, and understanding it helps you reason about what an adversary's passive reconnaissance of your externally visible estate looks like, since every source it queries — certificate logs, passive DNS, scan archives — is equally available to them. The GPL-3.0 license means teams can fork and extend it with internal sources, and the plugin structure makes that extension realistic. If your daily work involves pivoting across IPs, domains, certificates and breach data inside an authorized scope, harpoon is one of the more complete CLI consolidations available, and its PyPI distribution keeps the barrier to adoption close to zero.
Te-k/harpoon.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.