start: adding support for email

Author: VamatoHD

tests/test_orchestrator.py

@@ -25,6 +25,16 @@ def test_generate_permutations():
 
     assert len(perms) > 1
 
+def test_generate_permutations_email():
+    perms = orchestrator.generate_permutations("[email protected]", "abc", limit=None, is_email=True)    
+    assert "[email protected]" in perms  
+    assert all(
+        p == "[email protected]" or
+        (p.startswith("john") and len(p) > len("[email protected]") and p.endswith("@email.com"))
+        for p in perms
+    )
+    assert len(perms) > 1
+
 def test_run_module_single_prints_json_and_csv(capsys):
     module = types.ModuleType("fake.testsite")
     module.__file__ = "<in-memory>/fake/testsite.py"

user_scanner/__main__.py

@@ -1,6 +1,7 @@
 import argparse
 import time
 import sys
+import re
 from user_scanner.cli import printer
 from user_scanner.core.orchestrator import generate_permutations, load_categories
 from colorama import Fore, Style
@@ -28,9 +29,15 @@ def main():
         prog="user-scanner",
         description="Scan usernames across multiple platforms."
     )
-    parser.add_argument(
+
+    group = parser.add_mutually_exclusive_group(required=True)
+
+    group.add_argument(
         "-u", "--username",  help="Username to scan across platforms"
     )
+    group.add_argument(
+        "-e", "--email",  help="Email to scan across platforms"
+    )
     parser.add_argument(
         "-c", "--category", choices=load_categories().keys(),
         help="Scan all platforms in a category"
@@ -44,22 +51,18 @@ def main():
     parser.add_argument(
         "-v", "--verbose", action="store_true", help="Enable verbose output"
     )
-
     parser.add_argument(
         "-p", "--permute",type=str,help="Generate username permutations using a string pattern (e.g -p 234)"
     )
     parser.add_argument(
         "-s", "--stop",type=int,default=MAX_PERMUTATIONS_LIMIT,help="Limit the number of username permutations generated"
     )
-
     parser.add_argument(
         "-d", "--delay",type=float,default=0,help="Delay in seconds between requests (recommended: 1-2 seconds)"
     )
-
     parser.add_argument(
         "-f", "--format", choices=["console", "csv", "json"], default="console", help="Specify the output format (default: console)"
     )
-
     parser.add_argument(
         "-o", "--output", type=str, help="Specify the output file"
     )
@@ -82,26 +85,27 @@ def main():
 
     check_for_updates()
 
-    if not args.username:
-        parser.print_help()
-        return
-
-
     if Printer.is_console:
         print_banner()
 
+    is_email = args.email is not None
+    if is_email and not re.findall(r"^[^@\s]+@[^@\s]+\.[^@\s]+$", args.email):
+        print(R + "[✘] Error: Invalid email." + X)
+        sys.exit(1)
+
     if args.permute and args.delay == 0 and Printer.is_console:
         print(
         Y
         + "[!] Warning: You're generating multiple usernames with NO delay between requests. "
         "This may trigger rate limits or IP bans. Use --delay 1 or higher. (Use only if the sites throw errors otherwise ignore)\n"
         + Style.RESET_ALL)
 
-    usernames = [args.username]  # Default single username list
+    name = args.username or args.email #Username or email
+    usernames = [name]  # Default single username list
 
     # Added permutation support , generate all possible permutation of given sequence.
     if args.permute:
-        usernames = generate_permutations(args.username, args.permute , args.stop)
+        usernames = generate_permutations(name, args.permute , args.stop, is_email)
         if Printer.is_console:
             print(
                 C + f"[+] Generated {len(usernames)} username permutations" + Style.RESET_ALL)

user_scanner/core/orchestrator.py

@@ -7,11 +7,12 @@
 from pathlib import Path
 from user_scanner.cli.printer import Printer
 from user_scanner.core.result import Result
+from types import ModuleType
 from typing import Callable, Dict, List
 from user_scanner.core.helpers import get_site_name, is_last_value
 
 
-def load_modules(category_path: Path):
+def load_modules(category_path: Path) -> List[ModuleType]:
     modules = []
     for file in category_path.glob("*.py"):
         if file.name == "__init__.py":
@@ -26,8 +27,9 @@ def load_modules(category_path: Path):
     return modules
 
 
-def load_categories() -> Dict[str, Path]:
-    root = Path(__file__).resolve().parent.parent / "user_scan"
+def load_categories(is_email: bool = False) -> Dict[str, Path]:
+    folder_name = "email_scan" if is_email else "user_scan"
+    root = Path(__file__).resolve().parent.parent / folder_name
     categories = {}
 
     for subfolder in root.iterdir():
@@ -39,33 +41,30 @@ def load_categories() -> Dict[str, Path]:
     return categories
 
 
-def find_module(name: str):
+def find_module(name: str, is_email: bool = False) -> List[ModuleType]:
     name = name.lower()
 
-    matches = [
+    return [
         module
-        for category_path in load_categories().values()
+        for category_path in load_categories(is_email).values()
         for module in load_modules(category_path)
         if module.__name__.split(".")[-1].lower() == name
     ]
 
-    return matches
 
-def find_category(module) -> str | None:
+def find_category(module: ModuleType) -> str | None:
 
     module_file = getattr(module, '__file__', None)
     if not module_file:
         return None
 
     category = Path(module_file).parent.name.lower()
-    categories = load_categories()
-    if category in categories:
+    if category in load_categories(False) or category in load_categories(True):
         return category.capitalize()
 
     return None
 
 
-
 def worker_single(module, username: str) -> Result:
     func = next((getattr(module, f) for f in dir(module)
                  if f.startswith("validate_") and callable(getattr(module, f))), None)
@@ -99,7 +98,6 @@ def run_module_single(module, username: str, printer: Printer, last: bool = True
     return [result]
 
 
-
 def run_checks_category(category_path: Path, username: str, printer: Printer, last: bool = True) -> List[Result]:
     modules = load_modules(category_path)
 
@@ -196,20 +194,30 @@ def contains(a, b): return (isinstance(a, list) and b in a) or (a == b)
     return generic_validate(url, inner, **kwargs)
 
 
-def generate_permutations(username, pattern, limit=None):
+def generate_permutations(username: str, pattern: str, limit: int | None = None, is_email: bool = False) -> List[str]:
     """
     Generate all order-based permutations of characters in `pattern`
     appended after `username`.
     """
-    permutations_set = {username}
 
+    if limit and limit <= 0:
+        return []
+
+    permutations_set = {username}
     chars = list(pattern)
 
+    domain = ""
+    if is_email:
+        username, domain = username.strip().split("@")
+
     # generate permutations of length 1 → len(chars)
-    for r in range(1, len(chars) + 1):
+    for r in range(len(chars)):
         for combo in permutations(chars, r):
-            permutations_set.add(username + ''.join(combo))
+            new = username + ''.join(combo)
+            if is_email:
+                new += "@" + domain
+            permutations_set.add(new)
             if limit and len(permutations_set) >= limit:
-                return list(permutations_set)[:limit]
+                return sorted(permutations_set)
 
     return sorted(permutations_set)