User-Scanner Command-Line Options: Complete OSINT Flag Reference

The user-scanner CLI from kaifcodec provides over 20 command-line flags for target selection, reconnaissance depth, and output formatting, all parsed in user_scanner/__main__.py and orchestrated through the modular core engine.

The kaifcodec/user-scanner repository is a powerful OSINT tool designed for automated username and email investigations across digital platforms. Mastering the user-scanner command-line options enables security researchers to execute precise reconnaissance workflows while controlling proxy rotation, concurrency limits, and cross-platform pivoting behaviors. All supported flags are cataloged in docs/FLAGS.md and implemented across the user_scanner/core/ package.

Target Selection Options

The CLI supports four mutually exclusive input methods defined in the argument parser within user_scanner/__main__.py.

Single Target Scanning

Use -u, --username USERNAME to scan a single username across every supported platform, or -e, --email EMAIL to investigate a single email address. These flags dispatch to core/orchestrator.py and core/email_orchestrator.py respectively.

Bulk Target Scanning

For scale, use -uf, --username-file FILE or -ef, --email-file FILE to ingest newline-delimited lists. The orchestrators iterate through each entry, applying the same network and filtering options to every target.

Scanning Control and Cross-Platform Pivoting

Advanced reconnaissance is handled by the cross-scan engine in core/cross_scan.py, which enables automated pivoting from discovered data.

Behavioral Flags

• --allow-loud enables sites that may trigger email notifications or security alerts during scanning.
• --no-nsfw excludes adult-rated platforms from the scan scope.
• --hudson or --hudson-scan queries the Hudson Rock breach-intelligence API for compromised credential data.

Cross-Scan Configuration

The --cross-scan flag initiates recursive investigation, following discovered usernames, links, and emails for additional leads. This is controlled by several parameters:

• --cross-links {all,verified,none} determines which hyperlinks trigger pivoting (default: all).
• --cross-emails {all,verified,none} filters which email addresses are pursued (default: verified).
• --cross-depth N sets the number of recursive follow rounds (default: 1).
• --cross-sweep N defines sweep passes across modules (default: 3, where 0 disables sweeping).

Scope and Module Filtering

Restrict execution to specific data sources or generate target variations using the scope flags.

• -c, --category CATEGORY limits the scan to specific platform categories, accepting comma-separated values.
• -m, --module MODULE runs only specified modules, useful for targeted investigations against single platforms.
• -p, --permute PERMUTE generates username permutations based on patterns or suffixes before scanning.
• -s, --stop STOP caps the number of generated permutations to prevent combinatorial explosion.

Network Configuration and Performance Tuning

The async engine in core/engine.py handles all HTTP concurrency, respecting the following flags:

• -P, --proxy-file FILE loads a list of proxies (one per line) for request rotation.
• --validate-proxies tests each proxy against google.com before scanning begins, filtering out dead routes.
• -d, --delay DELAY inserts a sleep interval (in seconds) between HTTP requests to avoid rate limiting.
• -t, --timeout TIMEOUT overrides the default request timeout value.
• -C, --concurrency CONC adjusts the maximum concurrent worker count processed by the engine.

Output Formats and Reporting

Results are aggregated into Result objects defined in core/result.py and formatted according to these options:

• -f, --format {csv,json,pdf} selects the output serialization format.
• -o, --output OUTPUT writes results to a file path, inferring format from the extension if -f is omitted.
• -v, --verbose displays detailed request URLs and real-time progress indicators.
• --all includes negative results ("Not Found"), errors, and skipped entries in the final report.

Maintenance and Version Control

System-level flags are handled by core/version.py and the entry point dispatcher:

• -U, --update pulls and installs the latest released version from the repository.
• --version prints the current installed version string.

Practical Usage Examples

Execute single-target investigations with custom timeouts:

user-scanner -u johndoe -t 30
user-scanner -e admin@example.com --no-nsfw

Process bulk lists with proxy validation and increased concurrency:

user-scanner -uf usernames.txt -P proxies.txt --validate-proxies -C 20
user-scanner -ef emails.txt -f json -o bulk_results.json

Enable recursive cross-scanning with verified-link pivoting and depth limiting:

user-scanner -u alice --cross-scan --cross-depth 2 \
    --cross-links verified --cross-emails verified --verbose

Generate permutations and export as PDF:

user-scanner -u bob -p "_{year}" -s 100 -f pdf -o bob_report.pdf

Show complete results including negative findings:

user-scanner -e charlie@example.com --all -f csv -o full_scan.csv

Summary

• user-scanner accepts usernames via -u/--username and emails via -e/--email, with bulk file inputs supported via -uf and -ef.
• The cross-scan engine (core/cross_scan.py) enables recursive pivoting through --cross-scan, controlled by depth, link quality, and sweep parameters.
• Network behavior is managed through proxy files (-P), validation (--validate-proxies), delays (-d), and concurrency limits (-C) handled by core/engine.py.
• Output formats include CSV, JSON, and PDF, configured via -f and -o, with verbose (-v) and complete (--all) reporting modes available.
• All arguments are parsed in user_scanner/__main__.py and dispatched to specialized orchestrators that coordinate module execution and result aggregation.

Frequently Asked Questions

How do I scan multiple usernames at once with user-scanner?

Use the -uf, --username-file FILE flag to specify a text file containing one username per line. The orchestrator in core/orchestrator.py processes each entry sequentially while applying your selected network and filtering options uniformly across the batch.

What is the difference between --cross-scan and --cross-links?

--cross-scan activates the recursive pivoting engine defined in core/cross_scan.py, enabling the tool to follow discovered entities for additional scans. --cross-links is a sub-parameter that filters which discovered hyperlinks qualify for pivoting, accepting all, verified, or none to control signal quality during recursion.

How does user-scanner handle proxy validation?

When --validate-proxies is provided alongside -P, --proxy-file, the engine tests each proxy against google.com before initiating the scan. Only responsive proxies are retained, ensuring that the concurrency pool in core/engine.py contains valid exit nodes before OSINT requests begin.

Where are the command-line arguments parsed in the source code?

Argument parsing occurs in user_scanner/__main__.py, which instantiates the CLI parser and dispatches to core/orchestrator.py for username targets or core/email_orchestrator.py for email targets. The canonical reference for all flags is maintained in docs/FLAGS.md.

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