Skip to content

USAGE.md

Latest commit

 

History

History
253 lines (220 loc) · 5.83 KB

USAGE.md

File metadata and controls

253 lines (220 loc) · 5.83 KB

🛠 Library Mode Usage Guide

User Scanner provides a powerful Library Mode via its core engine. This allows you to integrate OSINT capabilities directly into your own Python scripts, returning clean, structured data in JSON or CSV formats.

Quick Start: Single Module Scan

The engine automatically detects whether you are using a module from email_scan or user_scan by inspecting its path. It then adjusts the result labels (e.g., "Registered" vs "Found") automatically.

Email Scan Example

import asyncio
from user_scanner.core import engine
from user_scanner.email_scan.social import instagram

async def main():
    # Engine detects 'email_scan' path -> Result status: "Registered" / "Not Registered" / "Error"
    result = await engine.check(instagram, "target@gmail.com")
    
    # Get structured data
    json_data = result.to_json()
    csv_data = result.to_csv()
    
    print(json_data)
    
asyncio.run(main())

Output:

{
        "email": "target@gmail.com",
        "category": "Social",
        "site_name": "Instagram",
        "status": "Registered",
        "url": "https://instagram.com",
        "extra": "",
        "reason": ""
}

Username Scan Example

import asyncio
from user_scanner.core import engine
from user_scanner.user_scan.dev import github

async def main():
    # Engine detects 'user_scan' path -> Result status: "Not Found" / "Found" / "Error"
    result = await engine.check(github, "johndoe123")
    
    print(result.to_json())

asyncio.run(main())

Output:

{
        "username": "johndoe123",
        "category": "Dev",
        "site_name": "Github",
        "status": "Found",
        "url": "https://github.com",
        "extra": "",
        "reason": ""
}

Batch & Category Scans

You can scan entire folders of modules (e.g., all social media, all forums) or perform a full system scan across all categories.

Scan a Specific Category

import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json

async def main():
    target = "johndoe123"
    
    # Scans everything inside 'user_scan/social/'
    # Use is_email=False to tell the engine where to look for the category folder
    results = await engine.check_category("social", target, is_email=False)
    
    # 'into_json' wraps the results into a valid JSON array []
    print(into_json(results))

asyncio.run(main())

Output:

[
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Bluesky",
    "status": "Found",
    "url": "https://bsky.social",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Discord",
    "status": "Found",
    "url": "https://discord.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Instagram",
    "status": "Found",
    "url": "https://instagram.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Mastodon",
    "status": "Found",
    "url": "https://mastodon.social",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Pinterest",
    "status": "Found",
    "url": "https://pinterest.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Reddit",
    "status": "Found",
    "url": "https://reddit.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Snapchat",
    "status": "Found",
    "url": "https://snapchat.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Soundcloud",
    "status": "Error",
    "url": "https://soundcloud.com",
    "extra": "",
    "reason": "[403] Request forbidden try using proxy or VPN"
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Telegram",
    "status": "Found",
    "url": "https://t.me",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Threads",
    "status": "Found",
    "url": "https://threads.net",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Tiktok",
    "status": "Error",
    "url": "https://tiktok.com",
    "extra": "",
    "reason": "ConnectTimeout: Timed out"
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "X (Twitter)",
    "status": "Found",
    "url": "https://x.com",
    "extra": "",
    "reason": ""
  },
  {
    "username": "johndoe123",
    "category": "Social",
    "site_name": "Youtube",
    "status": "Found",
    "url": "https://m.youtube.com",
    "extra": "",
    "reason": ""
  }
]

Full OSINT Scan (All Categories)

import asyncio
from user_scanner.core import engine
from user_scanner.core.formatter import into_json

async def main():
    email = "target@example.com"
    
    # Scans every module available in 'email_scan/'
    results = await engine.check_all(email, is_email=True)
    
    # Save results to a file
    with open("report.json", "w") as f:
        f.write(into_json(results))

asyncio.run(main())

Available Output Formats

Every Result object returned by the engine supports the following methods:

Method Description
.to_json() Returns a formatted JSON string for a single result.
.to_csv() Returns a comma-separated string for a single result.
.as_dict() Returns a Python dictionary (useful for APIs).
.show() Prints a colorized string to the console (CLI style).

To format a List of results, use the formatter:

  • into_json(results_list)
  • into_csv(results_list)