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

> Integrate user-scanner with other security tools using its Python API. Learn to import, execute scans, and export results for SIEMs and SOAR platforms.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/formatter.py) and [`user_scanner/core/pdf_generator.py`](https://github.com/kaifcodec/user-scanner/blob/main/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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python

# 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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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`](https://github.com/kaifcodec/user-scanner/blob/main/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.