user-scanner 1.0.0.4__tar.gz → 1.0.8.1__tar.gz

user_scanner-1.0.8.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: user-scanner
+Version: 1.0.8.1
+Summary: Check username availability across multiple popular platforms
+Keywords: username,checker,availability,social,tech,python,user-scanner
+Author-email: Kaif <kafcodec@gmail.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: colorama
+Project-URL: Homepage, https://github.com/kaifcodec/user-scanner
+
+# 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.8.1-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" />
+  <img src="https://img.shields.io/badge/Tested%20on-Linux-balck?style=for-the-badge&logo=Linux" />
+  <img src="https://img.shields.io/pepy/dt/user-scanner?style=for-the-badge" />
+</p>
+
+---
+
+Scan a username across multiple social, developer, and creator platforms to see if it’s available.  
+Perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instagram, and more, all in one command.
+
+
+### Features
+
+- ✅ Check usernames across **social networks**, **developer platforms**, and **creator communities**.
+- ✅ Clear **Available / Taken / Error** output for each platform.
+- ✅ Robust error handling: It prints the exact reason (e.g. Cannot use underscores, hyphens at the start/end)
+- ✅ Fully modular: add new platform modules easily.
+- ✅ Wildcard-based username permutations for automatic variation generation using provided suffix
+- ✅ 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.
+---
+
+### Installation
+
+```bash
+pip install user-scanner
+```
+
+---
+
+### Usage
+
+Scan a username across all platforms:
+
+```bash
+user-scanner -u <username>
+```
+Optionally, scan a specific category or single module:
+
+```bash
+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="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: 
+
+Modules are organized by category:
+
+```
+user_scanner/
+├── dev/        # Developer platforms (GitHub, GitLab, etc.)
+├── social/     # Social platforms (Twitter/X, Reddit, Instagram, etc.)
+├── creator/    # Creator platforms (Hashnode, Dev.to, Medium, etc.)
+├── community/  # Community platforms (forums, niche sites)
+├── gaming/     # Gaming sites (chess.com, roblox, monkeytype etc.)
+├── donation/   # Donation taking sites (buymeacoffe.com, similar...)
+```
+
+**Module guidelines:**
+This project contains small "validator" modules that check whether a username exists on a given platform. Each validator is a single function that returns a Result object (see `core/orchestrator.py`).
+
+Result semantics:
+- Result.available() → `available`
+- Result.taken() → `taken`
+- Result.error(message: Optional[str]) → `error`, blocked, unknown, or request failure (include short diagnostic message when helpful)
+
+Follow this document when adding or updating validators.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
+
+---
+
+### Dependencies: 
+- [httpx](https://pypi.org/project/httpx/)
+- [colorama](https://pypi.org/project/colorama/)
+
+---
+
+### License
+
+This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+
+---
+
+### Star History
+
+<a href="https://www.star-history.com/#kaifcodec/user-scanner&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
+ </picture>
+</a>
+

user_scanner-1.0.8.1/README.md

@@ -0,0 +1,134 @@
+# 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.8.1-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" />
+  <img src="https://img.shields.io/badge/Tested%20on-Linux-balck?style=for-the-badge&logo=Linux" />
+  <img src="https://img.shields.io/pepy/dt/user-scanner?style=for-the-badge" />
+</p>
+
+---
+
+Scan a username across multiple social, developer, and creator platforms to see if it’s available.  
+Perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instagram, and more, all in one command.
+
+
+### Features
+
+- ✅ Check usernames across **social networks**, **developer platforms**, and **creator communities**.
+- ✅ Clear **Available / Taken / Error** output for each platform.
+- ✅ Robust error handling: It prints the exact reason (e.g. Cannot use underscores, hyphens at the start/end)
+- ✅ Fully modular: add new platform modules easily.
+- ✅ Wildcard-based username permutations for automatic variation generation using provided suffix
+- ✅ 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.
+---
+
+### Installation
+
+```bash
+pip install user-scanner
+```
+
+---
+
+### Usage
+
+Scan a username across all platforms:
+
+```bash
+user-scanner -u <username>
+```
+Optionally, scan a specific category or single module:
+
+```bash
+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="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: 
+
+Modules are organized by category:
+
+```
+user_scanner/
+├── dev/        # Developer platforms (GitHub, GitLab, etc.)
+├── social/     # Social platforms (Twitter/X, Reddit, Instagram, etc.)
+├── creator/    # Creator platforms (Hashnode, Dev.to, Medium, etc.)
+├── community/  # Community platforms (forums, niche sites)
+├── gaming/     # Gaming sites (chess.com, roblox, monkeytype etc.)
+├── donation/   # Donation taking sites (buymeacoffe.com, similar...)
+```
+
+**Module guidelines:**
+This project contains small "validator" modules that check whether a username exists on a given platform. Each validator is a single function that returns a Result object (see `core/orchestrator.py`).
+
+Result semantics:
+- Result.available() → `available`
+- Result.taken() → `taken`
+- Result.error(message: Optional[str]) → `error`, blocked, unknown, or request failure (include short diagnostic message when helpful)
+
+Follow this document when adding or updating validators.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
+
+---
+
+### Dependencies: 
+- [httpx](https://pypi.org/project/httpx/)
+- [colorama](https://pypi.org/project/colorama/)
+
+---
+
+### License
+
+This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+
+---
+
+### Star History
+
+<a href="https://www.star-history.com/#kaifcodec/user-scanner&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
+ </picture>
+</a>

{user_scanner-1.0.0.4 → user_scanner-1.0.8.1}/pyproject.toml

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

user_scanner-1.0.8.1/user_scanner/__main__.py

@@ -0,0 +1,134 @@
+import argparse
+import time
+import re
+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
+
+MAX_PERMUTATIONS_LIMIT = 100 # To prevent excessive generation
+
+def list_modules(category=None):
+    categories = load_categories()
+    categories_to_list = [category] if category else categories.keys()
+
+    for cat_name in categories_to_list:
+        path = categories[cat_name]
+        modules = load_modules(path)
+        print(Fore.MAGENTA +
+            f"\n== {cat_name.upper()} SITES =={Style.RESET_ALL}")
+        for module in modules:
+            site_name = module.__name__.split(".")[-1]
+            print(f"  - {site_name}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="user-scanner",
+        description="Scan usernames across multiple platforms."
+    )
+    parser.add_argument(
+        "-u", "--username",  help="Username to scan across platforms"
+    )
+    parser.add_argument(
+        "-c", "--category", choices=load_categories().keys(),
+        help="Scan all platforms in a category"
+    )
+    parser.add_argument(
+        "-m", "--module", help="Scan a single specific module across all categories"
+    )
+    parser.add_argument(
+        "-l", "--list", action="store_true", help="List all available modules by category"
+    )
+    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.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):
+            print(
+                Fore.RED + f"[!] Username '{args.username}' contains unsupported special characters. X (Twitter) doesn't support these." + Style.RESET_ALL)
+    if (args.module == "bluesky" or args.category == "social"):
+        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")
+    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(".", "_")
+
+
+    if args.module:
+        # Single module search across all categories
+        found = False
+        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
+                    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 = load_categories().get(args.category)
+        from user_scanner.core.orchestrator import run_checks_category
+        
+        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
+        for name in usernames:
+            run_checks(name)
+            if args.delay > 0:
+                time.sleep(args.delay)
+
+
+if __name__ == "__main__":
+    main()

user_scanner-1.0.8.1/user_scanner/cli/banner.py

@@ -0,0 +1,34 @@
+import json
+from colorama import Fore, Style, init
+from ..utils.version import load_local_version
+
+
+version, version_type = load_local_version()
+init(autoreset=True)
+C_RED = Fore.RED + Style.BRIGHT
+C_CYAN = Fore.CYAN + Style.BRIGHT
+C_GREEN = Fore.GREEN + Style.BRIGHT
+C_WHITE = Fore.WHITE + Style.BRIGHT
+C_MAGENTA = Fore.MAGENTA + Style.BRIGHT
+BANNER_ASCII = fr"""{C_CYAN}      _   _ ___  ___ _ __      ___  ___ __ _ _ __  _ __   ___ _ __
+     | | | / __|/ _ \ '__|____/ __|/ __/ _` | '_ \| '_ \ / _ \ '__|
+     | |_| \__ \  __/ | |_____\__ \ (_| (_| | | | | | | |  __/ |
+      \__,_|___/\___|_|       |___/\___\__,_|_| |_|_| |_|\___|_| Version: {version}
+{Style.RESET_ALL}""".strip()
+
+INFO_BOX = f"""{C_MAGENTA}      ╔════════════════════════════════════════╗
+      ║ {C_RED}♚ {C_GREEN}Project Name{C_WHITE} : UserScanner           {C_MAGENTA}║
+      ║ {C_RED}♚ {C_GREEN}Author{C_WHITE} : Kaif                        {C_MAGENTA}║
+      ║ {C_RED}♚ {C_GREEN}Github{C_WHITE} : github.com/kaifcodec        {C_MAGENTA}║
+      ║ {C_RED}♚ {C_GREEN}Email{C_WHITE}  : kaifcodec@gmail.com         {C_MAGENTA}║
+      ══════════════════════════════════════════{Style.RESET_ALL}""".strip()
+
+
+def print_banner():
+    print(BANNER_ASCII)
+    print(INFO_BOX)
+    print(" ")
+
+
+if __name__ == "__main__":
+    print_banner()

user_scanner-1.0.8.1/user_scanner/community/__init__.py

@@ -0,0 +1 @@
+# community

user_scanner-1.0.8.1/user_scanner/community/coderlegion.py

@@ -0,0 +1,19 @@
+from user_scanner.core.orchestrator import status_validate
+
+
+def validate_coderlegion(user):
+    url = f"https://coderlegion.com/user/{user}"
+
+    return status_validate(url, 404, 200, timeout=15.0)
+
+
+if __name__ == "__main__":
+    user = input("Username?: ").strip()
+    result = validate_coderlegion(user)
+
+    if result == 1:
+        print("Available!")
+    elif result == 0:
+        print("Unavailable!")
+    else:
+        print("Error occured!")

user_scanner-1.0.8.1/user_scanner/community/stackoverflow.py

@@ -0,0 +1,35 @@
+from user_scanner.core.orchestrator import generic_validate
+from user_scanner.core.result import Result
+
+def validate_stackoverflow(user: str) -> Result:
+    url = f"https://stackoverflow.com/users/filter?search={user}"
+
+    def process(response):
+        if response.status_code == 200:
+            text = response.text
+
+            if "No users matched your search." in text:
+                return Result.available()
+
+            pattern = f'>{user}<'
+            if pattern in text:
+                return Result.taken()
+
+            return Result.available()
+
+        return Result.error("Unexpected status code from Stack Overflow")
+
+    return generic_validate(url, process)
+
+
+if __name__ == "__main__":
+    user = input("Username?: ").strip()
+    result = validate_stackoverflow(user)
+
+    if result == Result.available():
+        print("Available!")
+    elif result == Result.taken():
+        print("Unavailable!")
+    else:
+        msg = result.get_reason()
+        print("Error occurred!" + msg)