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

{user_scanner-1.0.4.2 → user_scanner-1.0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: user-scanner
-Version: 1.0.4.2
+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>
@@ -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.4.2-blueviolet?style=for-the-badge&logo=github" />
+  <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" />
@@ -33,8 +33,10 @@ 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.
+- ✅ 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.
-- ✅ Command-line interface ready: works directly after `pip install`.
+- ✅ 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.
 ---
@@ -60,56 +62,39 @@ 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> 
 
 ```
----
-### Example Output: 
 
-- Note*: New modules are constantly getting added so this might have only limited, outdated output: 
+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
- Checking username: johndoe078
-
-== DEV SITES ==
-  [✔] Codeberg: Available
-  [✔] Cratesio: Available
-  [✔] Dockerhub: Available
-  [✘] Github: Taken
-  [✔] Gitlab: Available
-  [✔] Launchpad: Available
-  [✔] Npmjs: Available
-  [✔] Replit: Available
-
-== SOCIAL SITES ==
-  [✔] Bluesky: Available
-  [✔] Discord: Available
-  [✘] Instagram: Taken
-  [✔] Mastodon: Available
-  [✔] Pinterest: Available
-  [✘] Reddit: Taken
-  [✔] Snapchat: Available
-  [✔] Telegram: Available 
-  [✘] Threads: Taken
-  [✔] X (Twitter): Available
-  [✔] Youtube: Available
-
-== CREATOR SITES ==
-  [✔] Devto: Available
-  [✔] Hashnode: Available
-  [✔] Kaggle: Available
-  [✔] Medium: Available
-  [✔] Patreon: Available
-
-== COMMUNITY SITES ==
-  [✔] Coderlegion: Available
-
-== GAMING SITES ==
-  [✔] Chess_com: Available
-  [✔] Osu: Available
-  [✔] Roblox: Available
-  ...
-  ...
-  ...
+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:
@@ -121,21 +106,21 @@ user_scanner/
 ├── 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:**
-- Each module must define a `validate_<site>()` function that takes a `username` and returns:
-  - `1` → Available  
-  - `0` → Taken  
-  - `2` → Error / Could not check
-- Use `httpx` for requests, `colorama` for colored output.
-- Optional: modules can define a CLI parser if they support custom arguments.
+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.
 
-### 📧 Contact:
-- [Email](kaifcodec@gmail.com)
-  
 ---
 
 ### Dependencies: 
@@ -149,8 +134,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
 This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
 
 
-<!--- 
-## 🌟 Stars: 
+---
+
+### Star History
 
 <a href="https://www.star-history.com/#kaifcodec/user-scanner&type=date&legend=top-left">
  <picture>
@@ -159,7 +145,4 @@ This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for d
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
  </picture>
 </a>
---->
----
-## ⚠️ `community/` and `gaming/` are small, looking for contributions
 

{user_scanner-1.0.4.2 → user_scanner-1.0.8.1}/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.4.2-blueviolet?style=for-the-badge&logo=github" />
+  <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" />
@@ -20,8 +20,10 @@ 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.
+- ✅ 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.
-- ✅ Command-line interface ready: works directly after `pip install`.
+- ✅ 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.
 ---
@@ -47,56 +49,39 @@ 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> 
 
 ```
----
-### Example Output: 
 
-- Note*: New modules are constantly getting added so this might have only limited, outdated output: 
+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
- Checking username: johndoe078
-
-== DEV SITES ==
-  [✔] Codeberg: Available
-  [✔] Cratesio: Available
-  [✔] Dockerhub: Available
-  [✘] Github: Taken
-  [✔] Gitlab: Available
-  [✔] Launchpad: Available
-  [✔] Npmjs: Available
-  [✔] Replit: Available
-
-== SOCIAL SITES ==
-  [✔] Bluesky: Available
-  [✔] Discord: Available
-  [✘] Instagram: Taken
-  [✔] Mastodon: Available
-  [✔] Pinterest: Available
-  [✘] Reddit: Taken
-  [✔] Snapchat: Available
-  [✔] Telegram: Available 
-  [✘] Threads: Taken
-  [✔] X (Twitter): Available
-  [✔] Youtube: Available
-
-== CREATOR SITES ==
-  [✔] Devto: Available
-  [✔] Hashnode: Available
-  [✔] Kaggle: Available
-  [✔] Medium: Available
-  [✔] Patreon: Available
-
-== COMMUNITY SITES ==
-  [✔] Coderlegion: Available
-
-== GAMING SITES ==
-  [✔] Chess_com: Available
-  [✔] Osu: Available
-  [✔] Roblox: Available
-  ...
-  ...
-  ...
+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:
@@ -108,21 +93,21 @@ user_scanner/
 ├── 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:**
-- Each module must define a `validate_<site>()` function that takes a `username` and returns:
-  - `1` → Available  
-  - `0` → Taken  
-  - `2` → Error / Could not check
-- Use `httpx` for requests, `colorama` for colored output.
-- Optional: modules can define a CLI parser if they support custom arguments.
+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.
 
-### 📧 Contact:
-- [Email](kaifcodec@gmail.com)
-  
 ---
 
 ### Dependencies: 
@@ -136,8 +121,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for examples.
 This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
 
 
-<!--- 
-## 🌟 Stars: 
+---
+
+### Star History
 
 <a href="https://www.star-history.com/#kaifcodec/user-scanner&type=date&legend=top-left">
  <picture>
@@ -146,6 +132,3 @@ This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for d
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=kaifcodec/user-scanner&type=date&legend=top-left" />
  </picture>
 </a>
---->
----
-## ⚠️ `community/` and `gaming/` are small, looking for contributions

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

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "user-scanner"
-version = "1.0.4.2"
+version = "1.0.8.1"
 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.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.4.2 → user_scanner-1.0.8.1}/user_scanner/cli/banner.py

@@ -23,10 +23,12 @@ INFO_BOX = f"""{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)