kaifcodec/user-scanner: a Python OSINT suite for email and username footprints

What user-scanner actually does with a handle or an address

The project is a command line enumerator. You give it one username or one email address, and it walks a fixed catalogue of platform modules, asking each one whether that identity exists there. The README puts the catalogue at 1080+ scan vectors, split into 200+ email-integrated sites and 880+ username platforms. That split matters more than the total: the email side is a smaller, more specialised list, while the username side is the bulk of the work.

The intended audience is narrow. Security researchers doing footprinting, red teamers preparing a target profile, and investigators who need a first pass before manual work. It is not a background monitoring service and it is not a people-search product. The README frames the output as metadata: avatars, bios, follower counts, UID numbers, seller statuses. Those fields are scraped from the platforms that expose them, so the quality of any single result depends on what that platform renders publicly.

The pitch that deserves scrutiny is the phrase deep data extraction from a single input. In practice a single input gives you a list of confirmed or unconfirmed registrations. The depth comes from the pivot step, which the project ships as a separate flag rather than as default behaviour.

The pivot engine is the real mechanism, not the 1080 count

A plain scan is one pass: N modules, one identity, N answers. The README describes --cross-scan as a second stage that mines handles, profile links and exposed email addresses from the profiles that matched, then re-runs the scan against those newly discovered targets. The README gives a four-row pivot table: email to username, username to username, username to email, email to email. Each row names what gets mined, for example public email addresses published on target profile pages.

That is a graph walk, and it has the usual properties of one. The first pass is cheap and predictable. Every subsequent pass multiplies requests, and the README does not state a depth limit or a request budget. If you run --cross-scan against a target with a common handle, you are asking the tool to expand a frontier you have not bounded. The transport layer is httpx with HTTP/2 plus curl_cffi for TLS fingerprint impersonation, which the README presents as a way to survive bot detection. That is a reasonable engineering choice and also the reason a runaway pivot can look like abuse to the platforms involved.

The MCP server is the other structural piece. pyproject.toml declares an optional dependency group mcp with mcp>=1.2.0,<2 and a second console script, user-scanner-mcp, pointing at user_scanner.mcp.server:main. The README lists Claude Desktop, Cursor and Antigravity as intended hosts. So the tool can be driven by an agent that decides its own pivots, which is exactly the scenario where an unbounded frontier is least comfortable.

Installing user-scanner with pip and running a first scan

The README recommends PyPI. Python 3.10 or newer is required, per requires-python in pyproject.toml. The two commands below upgrade pip and install the package.

python3 -m pip install --upgrade pip
pip install user-scanner

If you want the MCP server, the README documents an extras install. The bracket syntax is quoted in the README to keep the shell from interpreting it.

pip install "user-scanner[mcp]"

A virtual environment is the safer route if you already have OSINT tooling installed globally. The README gives the venv sequence, including the Windows activation path.

python3 -m venv .venv
source .venv/bin/activate
pip install user-scanner

With the package installed, the entry point is the user-scanner script declared in pyproject.toml. A single username scan looks like this.

user-scanner -u johndoe

The README states you should see a terminal UI with progress tracking and per-category status. An email scan uses -e instead, and the README shows a variant that also tries the handle across provider domains.

user-scanner -e [email protected]
user-scanner -u johndoe --email-domains global

If you are on Linux or macOS and prefer not to install at all, the README documents a Nix path that runs straight from the repository.

nix run github:kaifcodec/user-scanner/main -- --help

For exports, the README lists PDF, JSON and CSV. The PDF path is a separate extras group in pyproject.toml, so a plain install will not have reportlab or pillow present.

Where user-scanner breaks down or is the wrong tool

The hardest limitation is epistemic, not technical. A module that reports nothing is not proof of absence. Platforms change their response codes, add interstitials, or return a soft 200 for a missing profile, and the README does not document a per-module confidence level or a verification pass. Treat a negative as a gap in the catalogue, not as a finding.

Second, the README does not document rate-limit budgets, backoff behaviour, or a retry policy. It documents proxy rotation with protocol auto-detection for http and socks5, plus a --validate-proxies pre-scan health check. That tells you the project expects to be throttled or blocked, but it does not tell you what happens when a module starts refusing connections mid-scan. If your use case needs a reproducible, auditable request log, this is the wrong shape of tool.

Third, the repository layout includes a directory named abandoned/ at the top level. The README does not explain it. Anyone reading the module count as a stable contract should look at that directory first, because it suggests vectors get retired without the headline number changing.

Fourth, covert collection is out of scope. The tool impersonates a TLS fingerprint, which is evasion of a sort, but it is still an HTTP client hitting public endpoints from your address or your proxy. If the engagement requires staying invisible, this is not the layer for it.

How user-scanner differs from WhatsMyName and one-shot lookup sites

WhatsMyName is the closest reference point and the one people search for alongside this project. It is a community-maintained data set of site definitions with a companion checker; the emphasis is on the definition list and on keeping it current through contributions. user-scanner bundles its own module set and adds behaviour on top: the pivot engine, breach intel via the --hudson flag, proxy rotation, multi-format exports, and the MCP server. If you want a definition file you can read, diff and reuse in your own tooling, WhatsMyName is the more transparent artefact. If you want a single command that enumerates and then follows the leads it finds, user-scanner is doing more work per invocation.

Against hosted lookup sites, the difference is custody. A web service holds your queries and returns a rendered answer; user-scanner runs locally and writes JSON or CSV you keep. That is a real advantage for investigation work where the query itself is sensitive. The cost is that you own the maintenance: when a platform changes its markup, you wait for a release or patch the module yourself. The release cadence visible in the repository is v1.5.0 on 2026-08-13, v1.5.1 on 2026-08-28 and v1.5.2 on 2026-09-17, with the last push to main on 2026-09-22. That is frequent enough that module drift is being addressed, but it also means the tool is a moving target for anyone pinning a version.

Licence, upgrade cost and what the repository commits you to

The licence is MIT, declared in pyproject.toml as license = {file = "LICENSE"} and stated in the repository metadata. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with it. What MIT does not do is give you any warranty or indemnity, and it says nothing about the legality of the queries you run. Whether enumerating an address against 200+ sites is lawful depends on your jurisdiction and your authorisation, and the README does not discuss that at all. That silence is worth noting before you put this in a client deliverable.

Upgrade cost is dominated by dependency churn rather than API churn. pyproject.toml pins httpx[http2] to >=0.27,<0.29, curl_cffi to >=0.7,<1, socksio to >=1.0,<2, colorama to >=0.4,<1 and rich to >=13.0. The upper bounds on httpx and curl_cffi are the ones to watch, because both projects move quickly and a major bump will require a coordinated release here. The optional groups are separate: pdf pulls reportlab>=4.0.0, pillow>=10.0.0 and svglib>=1.5.0, and mcp pulls mcp>=1.2.0,<2. If you need PDF reports in CI, install the pdf extra explicitly; the base install will not produce them.

There is also a sponsorship section in the README pointing at commercial OSINT platforms. That is a funding arrangement, not a feature, but it is a signal about where the project's attention may sit over time.

Editorial conclusion

Adopt user-scanner if you need a scriptable, MIT-licensed enumeration pass over a handle or address and you are willing to read the module list before trusting a negative result. Skip it if you need covert collection, guaranteed uptime, or a compliance paper trail, because the project documents neither rate-limit budgets nor a retry policy. Before relying on it, run one scan with --validate-proxies against a proxy list you control and compare the hit set with the JSON export, since the PDF path is a separate optional dependency group.

Frequently asked questions

Official sources

1. Issues
2. kaifcodec/user-scanner on GitHub
3. License: MIT
4. README
5. Releases