How to Integrate User-Scanner with Other Security Tools: A Complete API Guide

Integrate user-scanner with other security tools by importing the public Python API from user_scanner.core, executing scans via run_user_full(), and serializing the normalized Result objects to JSON or CSV for ingestion into SIEMs, SOAR platforms, and threat intelligence systems.

The kaifcodec/user-scanner repository provides a pure-Python OSINT engine designed to function both as a standalone CLI utility and as an embeddable library. Because the core API contains no external binary dependencies, you can import the scanning engine directly into Python 3.9+ environments to enrich security workflows, automate threat hunting, or feed data into centralized monitoring platforms.

Understanding the User-Scanner Architecture

The library's architecture centers on orchestrators that manage parallel scan workers, a cross-scan engine that pivots on discovered handles and secondary identifiers, and a set of formatters that normalize output for downstream consumption. The transport layer in core/impersonate.py uses httpx and curl_cffi to handle TLS fingerprint impersonation and Cloudflare challenges, ensuring high-throughput scanning even against protected endpoints.

Core Integration Components

When you integrate user-scanner with other security tools, you interact with five primary components:

• run_user_full in user_scanner/core/orchestrator.py — The synchronous entry point that accepts a username or email and a ScanConfig object, returning a list of Result objects representing platform availability states.

• run_user_module / run_user_category in the same file — Targeted functions that execute a single module (e.g., Twitter) or an entire category (e.g., all social-media sites), useful for constrained scans within specific intelligence requirements.

• cross_scan in user_scanner/core/cross_scan.py — An enrichment engine that mines discovered handles, profile links, and secondary emails to trigger secondary scans, expanding the initial dataset automatically.

• Result model in user_scanner/core/result.py — A normalized data structure containing available, taken, or error states, plus an extra metadata dictionary and media URLs for retrieved content.

• Formatters in user_scanner/core/formatter.py and user_scanner/core/pdf_generator.py — Utilities that convert Result lists into JSON, CSV, or PDF formats for compliance archives or automated ingestion pipelines.

Step-by-Step Integration Workflow

Configure the Scan Environment

Instantiate a ScanConfig object to define timeout, concurrency, proxy settings, and SSL verification. This configuration object ensures the scan respects your environment's network policies and performance constraints.

from user_scanner.core.orchestrator import ScanConfig

cfg = ScanConfig(
    timeout=15,          # per-request timeout in seconds

    concurrency=20,      # parallel workers

    proxy="http://127.0.0.1:8080",  # or None for direct connection

    verify_ssl=True,
)

Execute the Primary Scan

Invoke run_user_full() with the target identifier and configuration. The function blocks until completion and returns a List[Result] that you can immediately process or store.

from user_scanner.core.orchestrator import run_user_full

results = run_user_full("john_doe", cfg)

# results is a list of Result objects with platform, status, and metadata

Enrich Results with Cross-Scanning

Feed the initial results into cross_scan() to identify additional pivot points such as linked accounts, bio references, or secondary email addresses. This step is essential for deep intelligence gathering before pushing data to threat-intel platforms.

from user_scanner.core.cross_scan import cross_scan

enhanced_results = cross_scan(results, cfg)

Serialize and Export Data

Convert the enriched dataset into your required format. The JSON formatter produces machine-readable output ideal for REST APIs, while the CSV formatter generates Splunk- or TheHive-compatible files.

from user_scanner.core.formatter import json_formatter, csv_formatter

json_payload = json_formatter(enhanced_results)
csv_data = csv_formatter(enhanced_results)

Practical Integration Examples

Ingesting Data into Elasticsearch

The JSON formatter produces output compatible with Elasticsearch's bulk API. After scanning, push the normalized results directly into a security index for correlation with other log sources.

from user_scanner.core.orchestrator import run_user_full, ScanConfig
from user_scanner.core.formatter import json_formatter
import json

cfg = ScanConfig(timeout=15, concurrency=20, proxy=None, verify_ssl=True)
results = run_user_full("target_username", cfg)
json_payload = json_formatter(results)

# Example Elasticsearch ingestion

# from elasticsearch import Elasticsearch

# es = Elasticsearch("http://localhost:9200")

# es.bulk(index="user_scanner", body=[{"index": {}}, r] for r in json_payload)

Exporting to Splunk or TheHive via CSV

Security operations centers often require CSV exports for import into case management systems. Combine cross-scanning with CSV output to create comprehensive investigation packages.

from user_scanner.core.orchestrator import run_user_full, ScanConfig
from user_scanner.core.cross_scan import cross_scan
from user_scanner.core.formatter import csv_formatter

cfg = ScanConfig()
base_results = run_user_full("alice@example.com", cfg)
enhanced = cross_scan(base_results, cfg)

with open("investigation_alice.csv", "w", encoding="utf-8") as f:
    f.write(csv_formatter(enhanced))

Embedding in SOAR Playbooks

SOAR platforms expect structured return values that can be parsed by playbook engines. Wrap the user-scanner API in a function that returns a dictionary with a standard data key, enabling seamless integration with automation logic.

import json
from user_scanner.core.orchestrator import run_user_full, ScanConfig

def soar_lookup(target: str, is_email: bool = False) -> dict:
    """SOAR-compatible lookup function returning standardized JSON."""
    cfg = ScanConfig()
    results = run_user_full(target, cfg)
    return {"data": [r.to_dict() for r in results]}

# Example invocation from playbook engine

output = json.dumps(soar_lookup("bob@corp.com"), indent=2)

AI-Driven Automation with MCP

For agent-oriented platforms like Claude Desktop, Cursor, or Antigravity, install the optional [mcp] extra to expose a Model-Context-Protocol server. This allows AI agents to invoke scans autonomously via HTTP POST requests.

# Install: pip install "user-scanner[mcp]"

# Start the MCP server locally, then query via HTTP

import requests

response = requests.post(
    "http://127.0.0.1:8000/scan",
    json={"target": "charlie", "type": "username"},
    timeout=30,
)
scan_results = response.json()

Summary

• Import the public API from user_scanner.core.orchestrator to embed scanning capabilities without CLI dependencies.
• Use ScanConfig to control network behavior, including proxies, concurrency limits, and SSL verification.
• Leverage cross_scan in user_scanner/core/cross_scan.py to enrich initial findings with secondary identifiers and linked profiles.
• Export via formatters in user_scanner/core/formatter.py to produce JSON for SIEMs or CSV for case management systems.
• Enable MCP server mode by installing the [mcp] extra for integration with AI-driven security agents and autonomous scanning workflows.

Frequently Asked Questions

What Python version is required to integrate user-scanner with other security tools?

According to the source code in kaifcodec/user-scanner, the library requires Python 3.9 or higher. The core API uses modern async patterns and type hints introduced in recent Python versions, ensuring compatibility with contemporary security automation frameworks.

Can I run specific scan modules instead of full scans when integrating?

Yes. Instead of run_user_full(), use run_user_module() to target a specific platform (e.g., Twitter) or run_user_category() to scan an entire category (e.g., all social-media sites). Both functions are located in user_scanner/core/orchestrator.py and accept the same ScanConfig object, allowing precise control over scan scope in resource-constrained environments.

How do I handle proxy configurations and TLS verification in automated workflows?

Pass a ScanConfig instance to any orchestrator function with the proxy parameter set to your proxy URL (e.g., "http://127.0.0.1:8080") and verify_ssl set to True or False based on your security policy. The core/impersonate.py transport layer respects these settings globally, ensuring all httpx and curl_cffi requests route through your specified infrastructure.

Is the Model-Context-Protocol (MCP) server compatible with Claude Desktop and similar AI agents?

Yes. The optional [mcp] extra installs a lightweight HTTP server that exposes scan endpoints at localhost:8000. According to the implementation, you can POST JSON payloads containing the target and scan type, receiving structured results suitable for AI-driven analysis. This enables autonomous security agents to perform OSINT lookups as part of larger investigative playbooks without human intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}