User Scanner
User Scanner Architecture: Modules, Concurrency, Pivots, Reports, and MCP
Trace User Scanner from target normalization through platform modules, concurrent HTTP, cross-scan pivots, report writers, and agent-facing MCP tools.
What you will learn
- Explain module, pivot, report, and MCP layers
- Run a bounded scan and interpret uncertainty
- Apply authorization, rate-limit, and data-retention controls
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- Separate module, transport, pivot, report, and MCP contracts.
- Cross-scan is a bounded graph traversal with provenance and de-duplication.
- Different report formats and AI clients must preserve uncertainty and redaction.
Model the engine as contracts
The README describes a Python engine with email and username module catalogs, rich metadata extraction, an `httpx`/`curl_cffi` high-throughput layer, proxy validation, cross-scan pivots, report exporters, and an MCP server. Treat each as a separate contract with inputs, outputs, limits, and evidence.
A module response should carry platform, target type, status, URL or identifier, timestamp, and uncertainty. The engine should not collapse `not found`, timeout, blocked, and ambiguous into one boolean.
Follow a pivot edge
An initial username or email scan can emit handles, profile links, or public addresses. The cross-scan engine classifies those links, applies depth and verification policy, queues secondary modules, and records parent/child relationships. This is a graph traversal, not a single request.
Bound breadth and depth, de-duplicate normalized targets, and keep an audit record of why each edge was accepted or rejected. A recursive pivot must not silently expand the investigation scope.
Connect reports and MCP
PDF, JSON, and CSV writers project the same observation graph into different consumers; PDF may include profile photos while JSON is better for pipelines. The MCP layer exposes scan, email, and module-discovery tools to compatible clients, so schemas and errors must remain stable and redacted.
Keep the client as an orchestrator of evidence, not an authority that invents identity confidence or widens permissions.
Review failure boundaries
Concurrency, TLS fingerprinting, proxies, provider changes, and module-specific parsers can fail independently. Test timeouts, rate limits, malformed responses, duplicate pivots, partial exports, and MCP cancellation; each should leave a named, recoverable state.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Map target normalization, module registry, transport, and response schema.
- 2
Trace one parent target into a verified child pivot.
- 3
Follow JSON/CSV/PDF projections and MCP tool schemas.
- 4
Inject timeout, block, duplicate, and partial-export failures.
Copy-ready example
target normalize -> module registry -> httpx/curl_cffi
response/status -> pivot classifier -> bounded graph
observations -> JSON/CSV/PDF + MCP schemasFrequently asked questions
Is a platform module result a binary truth value?
No. Preserve status, evidence URL/identifier, timestamp, and ambiguity such as timeout or block.
Why model cross-scan as a graph?
Each discovered handle/email/link can create parent-child edges, requiring depth, verification, and de-duplication controls.
Sources
- User Scanner README (captured 2026-08-31)Source checked 2026-08-31
- User Scanner repositorySource checked 2026-08-31