wtfis: passive OSINT lookup that minimises API calls to stay inside free tiers

What it does and, more importantly, what it does not do

wtfis is a command line tool that gathers information about a domain, FQDN or IP address using various OSINT services. The project description is precise about the audience in a phrase, passive hostname, domain and IP lookup tool for non-robots, and the README explains what that means. Unlike other tools of its kind, it is built specifically for human consumption, providing results that are pretty, the README says YMMV, and easy to read and understand. The second constraint is the one that shapes the whole design: the tool assumes you are using free tier or community level accounts, and so it makes as few API calls as possible to minimise hitting quotas and rate limits. That is a real engineering constraint rather than a caveat, and it explains the fallback chains and the default service choices throughout the source list. The project name is a play on whois, and the licence is MIT.

Nine services, all optional, none required

The data source table is the reference for what the tool can draw on. Virustotal is used in every lookup and is the primary source of information. AbuseIPDB, Greynoise, IP2Location, IP2Whois, IPinfo, IPWhois, Shodan and URLhaus are used for IP addresses, domains or both. The Required column says No for all of them, and the Free Tier column says Yes for all except Shodan. So the tool runs with no keys at all, and each key adds a dimension. The enrichments are enabled by command line flags rather than by configuration, with -A to enable all possible enrichments, -s to use Shodan, -g to enable Greynoise, -a to enable AbuseIPDB and -u to use URLhaus, alongside a positional argument for the hostname, domain or IP to look up. The design is that the default output is what the primary source can give you for free, and everything else is an explicit choice.

usage: wtfis [-h] [-A] [-s] [-g] [-a] [-u] [-m N] [-n] [-1] [-V] [--geolocation-service {ip2location,ipinfo,ipwhois}] entity

positional arguments:
  entity                Hostname, domain or IP

options:
  -h, --help            show this help message and exit
  -A, --all             Enable all possible enrichments
  -s, --use-shodan      Use Shodan to enrich IPs
  -g, --use-greynoise   Enable Greynoise for IPs
  -a, --use-abuseipdb   Enable AbuseIPDB for IPs

Virustotal is the backbone, and the whois data is the weak point

Virustotal is described as the primary source of information, and for a domain, FQDN or IP it retrieves the latest analysis stats with vendor detail, the reputation score based on VT community votes, popularity ranks such as Alexa and Cisco Umbrella for FQDN and domain only, and the categories assigned by different vendors. For FQDN and domain it also pulls resolutions, the last n IP addresses with a default of 3 and a maximum of 10, and the latest analysis stats of each of those addresses. The whois part is where the tool is cautious, and the documentation is worth reading. IP2Whois is recommended over Virustotal for whois data for a couple of reasons: the VT whois data format is less consistent, and the IP2Whois data tends to be of better quality, and VT's registrant data is apparently anonymized. There is a practical bonus too, since offloading whois to IP2Whois saves one VT API call, which is exactly the constraint the tool is designed around. Virustotal whois is therefore a fallback only, used if IP2Whois credentials are not available.

The three geolocation services are alternatives, and the --geolocation-service flag picks one

Geolocation and ASN data can come from three places and the tool treats them as alternatives rather than as sources to combine. IPWhois is the default, retrieving geolocation, ASN, org and ISP, and the domain. IP2Location is an alternative, retrieving geolocation, ASN and org, plus whether the address is a proxy, and it shares a signup with IP2Whois, so one key covers both lookups. IPinfo is the third, retrieving geolocation, ASN and org, the hostname, and whether the address is anycast. The command line exposes this as --geolocation-service with the choices ip2location, ipinfo and ipwhois. The naming trap worth flagging is the one the README itself flags, that IPWhois and IP2Whois are different services, where IPWhois does IP geolocation and IP2Whois does domain whois data, and the two are easily confused.

The three enrichment sources and what each contributes

The optional enrichments each answer a different question. AbuseIPDB is a crowd-sourced database of reported malicious addresses, and through its API the tool shows the abuse confidence score from 0 to 100 and the number of reports. Greynoise uses the community API to say whether an IP is in one of its datasets, Noise meaning the IP has been seen regularly scanning the internet, and RIOT meaning it belongs to a common business application such as Microsoft O365, Google Workspace or Slack, and the API also returns a classification of benign, malicious or unknown. Shodan is fetched from the host endpoint and gives the list of open ports and services, the operating system if available, and the tags Shodan has assigned. URLhaus is a crowd-sourced database of reported malicious URLs, and it tells you the count of currently online and total malware URLs, whether the hostname or IP is currently in the DNSBL and SURBL public blocklists, and all the tags assigned to the URL over its history.

Keys, the ~/.env.wtfis file and the chmod that matters

wtfis uses a set of environment variables, all optional: VT_API_KEY, ABUSEIPDB_API_KEY, IP2LOCATION_API_KEY, IP2WHOIS_API_KEY, GREYNOISE_API_KEY, SHODAN_API_KEY, URLHAUS_API_KEY, plus WTFIS_DEFAULTS for default boolean arguments and GEOLOCATION_SERVICE for the geolocation and ASN lookup service to use. You can set them by your own method, or create a file in your home directory called .env.wtfis with the above options, with a template in .env.wtfis.example in the repository. The instruction in capitals is the one to follow, don't forget to chmod 400 the file, because this file holds API keys for several services and the permissions are the only thing standing between a leaked token and a quota drain. The dependency on python-dotenv is what makes the file work, and it is the only reason it is in the dependency list.

Installing it, and the packaging the project has settled on

Installation is pip install wtfis, with conda from conda-forge via a feedstock repository, and brew install wtfis for Homebrew users. The project publishes to PyPI and the package is a Hatch project named wtfis, with the console script mapped to wtfis.main:main, a version read from wtfis/__about__.py, and the publishing index disabled in the Hatch configuration. It requires Python 3.10 or later and has only four runtime dependencies, pydantic for the data models, python-dotenv for the env file, requests for the HTTP calls and rich for the terminal output. That last one is the reason the output looks the way it does. The development environment is configured through Hatch, with mypy for type checking, pytest for the tests, black, isort and flake8 with bugbear for linting, bandit for security checks, and a test matrix over Python 3.10 through 3.14.

pip install wtfis

brew install wtfis

The Docker image builds the latest tagged commit, not the branch

The repository ships a Dockerfile with a builder stage and a final image, and the builder stage does something particular. It installs git, then checks out the latest tagged commit with git checkout on the tag that git describe resolves, creating a branch called latest_tag, so the image contains the newest released version rather than whatever is on the branch tip. It then upgrades pip, installs hatch, and runs hatch build --clean to produce the wheel and the source distribution. The final stage is a python:3.10-slim image that creates a user called wtfis with a home directory, copies the built wheel in, installs it, removes the wheel file, and runs as that user with bash as the command. The Makefile has the matching targets, docker-image to build it with --rm and docker-run to run it with the env file passed through, which is how the tool gets its API keys inside a container.

docker build -t wtfis --rm .
docker run --env-file=$HOME/.env.wtfis -it wtfis

Editorial conclusion

wtfis suits an analyst who wants a quick, readable picture of a domain or an IP address from several free reputation sources at once, and who works within the quota limits of free tier accounts. It is the wrong choice if you need machine-readable output for correlation across many indicators, since the tool is explicitly built for human consumption, and a poor fit for a workflow that expects exhaustive coverage, because every enrichment beyond the primary source is opt-in and off by default. Before adopting it, read the geolocation service choice, since IPWhois, IPinfo and IP2Location are alternatives rather than additions, and note that the API keys live in a ~/.env.wtfis file that the documentation tells you to chmod 400.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pirxthepilot/wtfis on GitHub
4. README
5. Releases