user-scanner 1.0.6.0__tar.gz → 1.0.8.0__tar.gz

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: user-scanner
-Version: 1.0.6.0
+Version: 1.0.8.0
 Summary: Check username availability across multiple popular platforms
 Keywords: username,checker,availability,social,tech,python,user-scanner
 Author-email: Kaif <kafcodec@gmail.com>
@@ -15,7 +15,7 @@ Project-URL: Homepage, https://github.com/kaifcodec/user-scanner
 
 ![1000136215](https://github.com/user-attachments/assets/49ec8d24-665b-4115-8525-01a8d0ca2ef4)
 <p align="center">
-  <img src="https://img.shields.io/badge/Version-1.0.6.0-blueviolet?style=for-the-badge&logo=github" />
+  <img src="https://img.shields.io/badge/Version-1.0.8.0-blueviolet?style=for-the-badge&logo=github" />
   <img src="https://img.shields.io/github/issues/kaifcodec/user-scanner?style=for-the-badge&logo=github" />
   <img src="https://img.shields.io/badge/Tested%20on-Termux-black?style=for-the-badge&logo=termux" />
   <img src="https://img.shields.io/badge/Tested%20on-Windows-cyan?style=for-the-badge&logo=Windows" />
@@ -34,6 +34,7 @@ Perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instag
 - ✅ Check usernames across **social networks**, **developer platforms**, and **creator communities**.
 - ✅ Clear **Available / Taken / Error** output for each platform.
 - ✅ Fully modular: add new platform modules easily.
+- ✅ Wildcard-based username permutations for automatic variation generation
 - ✅ Command-line interface ready: works directly after `pip install`.
 - ✅ Can be used as username OSINT tool.
 - ✅ Very low and lightweight dependencies, can be run on any machine.
@@ -60,14 +61,37 @@ Optionally, scan a specific category or single module:
 user-scanner -u <username> -c dev
 user-scanner -l # Lists all available modules
 user-scanner -u <username> -m github
+user-scanner -u <username> -p <suffix> 
 
 ```
+
+Generate multiple username variations by appending a suffix:
+
+```bash
+user-scanner -u <username> -p <suffix> 
+
+```
+Optionally, scan a specific category or single module with limit:
+
+```bash
+user-scanner -u <username> -p <suffix> -c dev
+user-scanner -u <username> -p <suffix> -m github
+user-scanner -u <username> -p <suffix> -s <number> # limit generation of usernames
+user-scanner -u <username> -p <suffix> -d <seconds> #delay to avoid rate-limits
+```
+
 ---
 ### Screenshot: 
 
 - Note*: New modules are constantly getting added so this might have only limited, outdated output:
 
-<img width="1008" height="568" alt="1000139959" src="https://github.com/user-attachments/assets/467a4aa0-238d-4110-b9a6-d4b96c244432" />
+
+<img width="1080" height="770" alt="1000140392" src="https://github.com/user-attachments/assets/4638c8f6-40c6-46f8-ae17-ac65cd199d81" />
+
+
+---
+
+<img width="1080" height="352" alt="1000140393" src="https://github.com/user-attachments/assets/578b248c-2a05-4917-aab3-6372a7c28045" />
 
 
 ### Contributing: 
@@ -94,9 +118,6 @@ user_scanner/
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
 
-### 📧 Contact:
-- [Email](kaifcodec@gmail.com)
-  
 ---
 
 ### Dependencies: 

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/README.md

@@ -2,7 +2,7 @@
 
 ![1000136215](https://github.com/user-attachments/assets/49ec8d24-665b-4115-8525-01a8d0ca2ef4)
 <p align="center">
-  <img src="https://img.shields.io/badge/Version-1.0.6.0-blueviolet?style=for-the-badge&logo=github" />
+  <img src="https://img.shields.io/badge/Version-1.0.8.0-blueviolet?style=for-the-badge&logo=github" />
   <img src="https://img.shields.io/github/issues/kaifcodec/user-scanner?style=for-the-badge&logo=github" />
   <img src="https://img.shields.io/badge/Tested%20on-Termux-black?style=for-the-badge&logo=termux" />
   <img src="https://img.shields.io/badge/Tested%20on-Windows-cyan?style=for-the-badge&logo=Windows" />
@@ -21,6 +21,7 @@ Perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instag
 - ✅ Check usernames across **social networks**, **developer platforms**, and **creator communities**.
 - ✅ Clear **Available / Taken / Error** output for each platform.
 - ✅ Fully modular: add new platform modules easily.
+- ✅ Wildcard-based username permutations for automatic variation generation
 - ✅ Command-line interface ready: works directly after `pip install`.
 - ✅ Can be used as username OSINT tool.
 - ✅ Very low and lightweight dependencies, can be run on any machine.
@@ -47,14 +48,37 @@ Optionally, scan a specific category or single module:
 user-scanner -u <username> -c dev
 user-scanner -l # Lists all available modules
 user-scanner -u <username> -m github
+user-scanner -u <username> -p <suffix> 
 
 ```
+
+Generate multiple username variations by appending a suffix:
+
+```bash
+user-scanner -u <username> -p <suffix> 
+
+```
+Optionally, scan a specific category or single module with limit:
+
+```bash
+user-scanner -u <username> -p <suffix> -c dev
+user-scanner -u <username> -p <suffix> -m github
+user-scanner -u <username> -p <suffix> -s <number> # limit generation of usernames
+user-scanner -u <username> -p <suffix> -d <seconds> #delay to avoid rate-limits
+```
+
 ---
 ### Screenshot: 
 
 - Note*: New modules are constantly getting added so this might have only limited, outdated output:
 
-<img width="1008" height="568" alt="1000139959" src="https://github.com/user-attachments/assets/467a4aa0-238d-4110-b9a6-d4b96c244432" />
+
+<img width="1080" height="770" alt="1000140392" src="https://github.com/user-attachments/assets/4638c8f6-40c6-46f8-ae17-ac65cd199d81" />
+
+
+---
+
+<img width="1080" height="352" alt="1000140393" src="https://github.com/user-attachments/assets/578b248c-2a05-4917-aab3-6372a7c28045" />
 
 
 ### Contributing: 
@@ -81,9 +105,6 @@ user_scanner/
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
 
-### 📧 Contact:
-- [Email](kaifcodec@gmail.com)
-  
 ---
 
 ### Dependencies: 

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "user-scanner"
-version = "1.0.6.0"
+version = "1.0.8.0"
 description = "Check username availability across multiple popular platforms"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -26,4 +26,4 @@ Homepage = "https://github.com/kaifcodec/user-scanner"
 user-scanner = "user_scanner.__main__:main"
 
 [tool.flit.sdist]
-exclude = ["tests/", "docs/", ".github/", ".git", "rm_pycache", "che.py", ".gitignore"]
+exclude = ["tests/", "docs/", ".github/", ".git", "rm_pycache.py", "che.py", ".gitignore"]

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/__main__.py

@@ -1,38 +1,22 @@
 import argparse
+import time
 import re
-from user_scanner.core.orchestrator import run_checks, load_modules
+from user_scanner.core.orchestrator import run_checks, load_modules , generate_permutations, load_categories
 from colorama import Fore, Style
 from .cli import banner
 from .cli.banner import print_banner
 
-CATEGORY_MAPPING = {
-    "dev": "dev",
-    "social": "social",
-    "creator": "creator",
-    "community": "community",
-    "gaming": "gaming",
-    "donation": "donation"
-}
-
+MAX_PERMUTATIONS_LIMIT = 100 # To prevent excessive generation
 
 def list_modules(category=None):
-    from user_scanner import dev, social, creator, community, gaming, donation
-    packages = {
-        "dev": dev,
-        "social": social,
-        "creator": creator,
-        "community": community,
-        "gaming": gaming,
-        "donation": donation
-    }
-
-    categories_to_list = [category] if category else packages.keys()
+    categories = load_categories()
+    categories_to_list = [category] if category else categories.keys()
 
     for cat_name in categories_to_list:
-        package = packages[cat_name]
-        modules = load_modules(package)
+        path = categories[cat_name]
+        modules = load_modules(path)
         print(Fore.MAGENTA +
-              f"\n== {cat_name.upper()} SITES =={Style.RESET_ALL}")
+            f"\n== {cat_name.upper()} SITES =={Style.RESET_ALL}")
         for module in modules:
             site_name = module.__name__.split(".")[-1]
             print(f"  - {site_name}")
@@ -47,7 +31,7 @@ def main():
         "-u", "--username",  help="Username to scan across platforms"
     )
     parser.add_argument(
-        "-c", "--category", choices=CATEGORY_MAPPING.keys(),
+        "-c", "--category", choices=load_categories().keys(),
         help="Scan all platforms in a category"
     )
     parser.add_argument(
@@ -59,16 +43,28 @@ 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)"
+    )
+    
     args = parser.parse_args()
-
-    if args.module and "." in args.module:
-        args.module = args.module.replace(".", "_")
-
+        
     if args.list:
         list_modules(args.category)
         return
-
+    
+    if not args.username:
+        parser.print_help()
+        return
+        
     # Special username checks before run
     if (args.module == "x" or args.category == "social"):
         if re.search(r"[^a-zA-Z0-9._-]", args.username):
@@ -78,37 +74,60 @@ def main():
         if re.search(r"[^a-zA-Z0-9\.-]", args.username):
             print(
                 Fore.RED + f"[!] Username '{args.username}' contains unsupported special characters. Bluesky will throw error. (Supported: only hyphens and digits)" + Style.RESET_ALL + "\n")
-    if not args.username:
-        parser.print_help()
-        return
-    else:
-        print_banner()
+    print_banner()
+
+    if args.permute and args.delay == 0:
+        print(
+        Fore.YELLOW
+        + "[!] 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
+    
+    #Added permutation support , generate all possible permutation of given sequence.
+    if args.permute:
+        usernames = generate_permutations(args.username, args.permute , args.stop)
+        print(Fore.CYAN + f"[+] Generated {len(usernames)} username permutations" + Style.RESET_ALL)
+
+    
+    
+    if args.module and "." in args.module:
+        args.module = args.module.replace(".", "_")
 
-    from user_scanner import dev, social, creator, community, gaming, donation
 
     if args.module:
         # Single module search across all categories
-        packages = [dev, social, creator, community, gaming, donation]
         found = False
-        for package in packages:
-            modules = load_modules(package)
+        for cat_path in load_categories().values():
+            modules = load_modules(cat_path)
             for module in modules:
                 site_name = module.__name__.split(".")[-1]
                 if site_name.lower() == args.module.lower():
                     from user_scanner.core.orchestrator import run_module_single
-                    run_module_single(module, args.username)
+                    for name in usernames:   # <-- permutation support here
+                        run_module_single(module, name)
+                        if args.delay > 0:
+                            time.sleep(args.delay)
                     found = True
         if not found:
             print(
                 Fore.RED + f"[!] Module '{args.module}' not found in any category." + Style.RESET_ALL)
     elif args.category:
         # Category-wise scan
-        category_package = eval(CATEGORY_MAPPING[args.category])
+        category_package = load_categories().get(args.category)
         from user_scanner.core.orchestrator import run_checks_category
-        run_checks_category(category_package, args.username, args.verbose)
+        
+        for name in usernames:   # <-- permutation support here
+            run_checks_category(category_package, name, args.verbose)
+            if args.delay > 0:
+                time.sleep(args.delay)
     else:
         # Full scan
-        run_checks(args.username)
+        for name in usernames:
+            run_checks(name)
+            if args.delay > 0:
+                time.sleep(args.delay)
 
 
 if __name__ == "__main__":

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/core/orchestrator.py

@@ -1,28 +1,43 @@
 import importlib
-import pkgutil
 from colorama import Fore, Style
 import threading
-
+from itertools import permutations
 import httpx
-from httpx import ConnectError, TimeoutException
+from pathlib import Path
+from user_scanner.core.result import Result, AnyResult
+from typing import Callable, Dict, List
 
 lock = threading.Condition()
 # Basically which thread is the one to print
 print_queue = 0
 
 
-def load_modules(package):
-
+def load_modules(category_path: Path):
     modules = []
-    for _, name, _ in pkgutil.iter_modules(package.__path__, package.__name__ + "."):
-        try:
-            module = importlib.import_module(name)
-            modules.append(module)
-        except Exception as e:
-            print(f"Failed to import {name}: {e}")
+    for file in category_path.glob("*.py"):
+        if file.name == "__init__.py":
+            continue
+        spec = importlib.util.spec_from_file_location(file.stem, str(file))
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        modules.append(module)
     return modules
 
 
+def load_categories() -> Dict[str, Path]:
+    root = Path(__file__).resolve().parent.parent  # Should be user_scanner
+    categories = {}
+
+    for subfolder in root.iterdir():
+        if subfolder.is_dir() and \
+                not subfolder.name.lower() in ["cli", "utils", "core"] and \
+                not "__" in subfolder.name:  # Removes __pycache__
+            categories[subfolder.name] = subfolder.resolve()
+
+    return categories
+
+
 def worker_single(module, username, i):
     global print_queue
 
@@ -36,12 +51,17 @@ def worker_single(module, username, i):
     if func:
         try:
             result = func(username)
+            reason = ""
+
+            if isinstance(result, Result) and result.has_reason():
+                reason = f" ({result.get_reason()})"
+
             if result == 1:
-                output = f"  {Fore.GREEN}[✔] {site_name}: Available{Style.RESET_ALL}"
+                output = f"  {Fore.GREEN}[✔] {site_name} ({username}): Available{Style.RESET_ALL}"
             elif result == 0:
-                output = f"  {Fore.RED}[✘] {site_name}: Taken{Style.RESET_ALL}"
+                output = f"  {Fore.RED}[✘] {site_name} ({username}): Taken{Style.RESET_ALL}"
             else:
-                output = f"  {Fore.YELLOW}[!] {site_name}: Error{Style.RESET_ALL}"
+                output = f"  {Fore.YELLOW}[!] {site_name} ({username}): Error{reason}{Style.RESET_ALL}"
         except Exception as e:
             output = f"  {Fore.YELLOW}[!] {site_name}: Exception - {e}{Style.RESET_ALL}"
     else:
@@ -62,11 +82,11 @@ def run_module_single(module, username):
     worker_single(module, username, print_queue)
 
 
-def run_checks_category(package, username, verbose=False):
+def run_checks_category(category_path:Path, username:str, verbose=False):
     global print_queue
 
-    modules = load_modules(package)
-    category_name = package.__name__.split('.')[-1].capitalize()
+    modules = load_modules(category_path)
+    category_name = category_path.stem.capitalize()
     print(f"{Fore.MAGENTA}== {category_name} SITES =={Style.RESET_ALL}")
 
     print_queue = 0
@@ -82,18 +102,14 @@ def run_checks_category(package, username, verbose=False):
 
 
 def run_checks(username):
-    from user_scanner import dev, social, creator, community, gaming, donation
-
-    packages = [dev, social, creator, community, gaming, donation]
-
     print(f"\n{Fore.CYAN} Checking username: {username}{Style.RESET_ALL}\n")
 
-    for package in packages:
-        run_checks_category(package, username)
+    for category_path in load_categories().values():
+        run_checks_category(category_path, username)
         print()
 
 
-def make_get_request(url, **kwargs):
+def make_get_request(url: str, **kwargs) -> httpx.Response:
     """Simple wrapper to **httpx.get** that predefines headers and timeout"""
     if not "headers" in kwargs:
         kwargs["headers"] = {
@@ -110,39 +126,55 @@ def make_get_request(url, **kwargs):
     return httpx.get(url, **kwargs)
 
 
-def generic_validate(url, func, **kwargs):
+def generic_validate(url: str, func: Callable[[httpx.Response], AnyResult], **kwargs) -> AnyResult:
     """
     A generic validate function that makes a request and executes the provided function on the response.
     """
     try:
         response = make_get_request(url, **kwargs)
         return func(response)
-    except (ConnectError, TimeoutException):
-        return 2
-    except Exception:
-        return 2
+    except Exception as e:
+        return Result.error(e)
 
 
-def status_validate(url, available, taken, **kwargs):
+def status_validate(url: str, available: int | List[int], taken: int | List[int], **kwargs) -> Result:
     """
     Function that takes a **url** and **kwargs** for the request and 
     checks if the request status matches the availabe or taken.
     **Available** and **Taken** must either be whole numbers or lists of whole numbers.
     """
-    def inner(response):
+    def inner(response: httpx.Response):
         # Checks if a number is equal or is contained inside
         def contains(a, b): return (isinstance(a, list) and b in a) or (a == b)
-
         status = response.status_code
         available_value = contains(available, status)
         taken_value = contains(taken, status)
 
         if available_value and taken_value:
-            return 2  # Can't be both available and taken
+            # Can't be both available and taken
+            return Result.error("Invalid status match. Report this on Github.")
         elif available_value:
-            return 1
+            return Result.available()
         elif taken_value:
-            return 0
-        return 2
+            return Result.taken()
+        return Result.error("Status didn't match. Report this on Github.")
 
     return generic_validate(url, inner, **kwargs)
+
+def generate_permutations(username, pattern, limit=None):
+    """
+    Generate all order-based permutations of characters in `pattern`
+    appended after `username`.
+    """
+    permutations_set = {username}
+
+    chars = list(pattern)
+
+    # generate permutations of length 1 → len(chars)
+    for r in range(1, len(chars) + 1):
+        for combo in permutations(chars, r):
+            permutations_set.add(username + ''.join(combo))
+            if limit and len(permutations_set) >= limit:
+                return list(permutations_set)[:limit]
+
+    return sorted(permutations_set)

user_scanner-1.0.8.0/user_scanner/core/result.py

@@ -0,0 +1,79 @@
+from enum import Enum
+from typing import Literal
+
+
+def humanize_exception(e: Exception) -> str:
+    msg = str(e).lower()
+
+    if "10054" in msg:
+        return "Connection closed by remote server"
+    if "11001" in msg:
+        return "Could not resolve hostname"
+
+    return str(e)
+
+
+class Status(Enum):
+    TAKEN = 0
+    AVAILABLE = 1
+    ERROR = 2
+
+
+class Result:
+    def __init__(self, status: Status, reason: str | Exception | None = None):
+        self.status = status
+        self.reason = reason
+
+    @classmethod
+    def taken(cls):
+        return cls(Status.TAKEN)
+
+    @classmethod
+    def available(cls):
+        return cls(Status.AVAILABLE)
+
+    @classmethod
+    def error(cls, reason: str | Exception | None = None):
+        return cls(Status.ERROR, reason)
+
+    @classmethod
+    def from_number(cls, i: int, reason: str | Exception | None = None):
+        try:
+            status = Status(i)
+        except ValueError:
+            return cls(Status.ERROR, "Invalid status. Please contact maintainers.")
+
+        return cls(status,  reason if status == Status.ERROR else None)
+
+    def to_number(self) -> int:
+        return self.status.value
+
+    def has_reason(self) -> bool:
+        return self.reason != None
+
+    def get_reason(self) -> str:
+        if self.reason == None:
+            return ""
+        if isinstance(self.reason, str):
+            return self.reason
+        #Format the exception
+        msg = humanize_exception(self.reason)
+        return f"{type(self.reason).__name__}: {msg.capitalize()}"
+
+    def __str__(self):
+        return self.get_reason()
+
+    def __eq__(self, other):
+        if isinstance(other, Status):
+            return self.status == other
+
+        if isinstance(other, Result):
+            return self.status == other.status
+
+        if isinstance(other, int):
+            return self.to_number() == other
+
+        return NotImplemented
+
+
+AnyResult = Literal[0, 1, 2] | Result

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/creator/hashnode.py

@@ -1,6 +1,5 @@
 import httpx
-import json
-from httpx import ConnectError, TimeoutException
+from user_scanner.core.result import Result
 
 
 def validate_hashnode(user):
@@ -27,21 +26,17 @@ def validate_hashnode(user):
 
             if 'status' in data:
                 if data['status'] == 1:
-                    return 1
+                    return Result.available()
                 elif data['status'] == 0:
-                    return 0
+                    return Result.taken()
 
-            return 2
+            return Result.error("Status not found")
 
         else:
-            return 2
-
-    except (ConnectError, TimeoutException):
-        return 2
-    except json.JSONDecodeError:
-        return 2
-    except Exception:
-        return 2
+            return Result.error("Invalid status code")
+
+    except Exception as e:
+        return Result.error(e)
 
 
 if __name__ == "__main__":

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/creator/itch_io.py

@@ -2,11 +2,6 @@ from user_scanner.core.orchestrator import status_validate
 
 
 def validate_itch_io(user):
-    """
-    Checks if a itch.io username is available.
-    Returns: 1 -> available, 0 -> taken, 2 -> error
-    """
-
     url = f"https://{user}.itch.io"
 
     return status_validate(url, 404, 200, follow_redirects=True)

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/creator/medium.py

@@ -1,5 +1,5 @@
-import httpx
-from httpx import ConnectError, TimeoutException
+from user_scanner.core.orchestrator import generic_validate
+from user_scanner.core.result import Result
 
 
 def validate_medium(user):
@@ -10,24 +10,19 @@ def validate_medium(user):
         'Accept': "text/html",
     }
 
-    try:
-        response = httpx.get(url, headers=headers, timeout=3.0)
-
+    def process(response):
         if response.status_code == 200:
             html_text = response.text
 
             username_tag = f'property="profile:username" content="{user}"'
 
             if username_tag in html_text:
-                return 0
+                return Result.taken()
             else:
-                return 1
-        return 2
+                return Result.available()
+        return Result.error()
 
-    except (ConnectError, TimeoutException):
-        return 2
-    except Exception:
-        return 2
+    return generic_validate(url, process, headers=headers)
 
 
 if __name__ == "__main__":

{user_scanner-1.0.6.0 → user_scanner-1.0.8.0}/user_scanner/creator/patreon.py

@@ -8,12 +8,6 @@ def validate_patreon(user):
 
 
 if __name__ == "__main__":
-    try:
-        import httpx
-    except ImportError:
-        print("Error: 'httpx' library is not installed.")
-        exit()
-
     user = input("Username?: ").strip()
     result = validate_patreon(user)