Merge branch 'main' into test/pattern-improvements

Author: kaifcodec

CONTRIBUTING.md

@@ -7,7 +7,6 @@ This project separates two kinds of checks:
 - Username availability checks (under `user_scanner/user_scan/*`) — synchronous validators that the main username scanner uses.
 - Email OSINT checks (under `user_scanner/email_scan/`) — asynchronous, multi-step flows that probe signup pages or email-focused APIs. Put email-focused modules in `user_scanner/email_scan/` (subfolders like `social/`, `dev/`, `community`, `creator` etc. are fine — follow the existing tree).
 
-
 ---
 
 ## Module naming for both `email_scan` and `user_scan` modules
@@ -17,10 +16,10 @@ This project separates two kinds of checks:
 
 ---
 
-
 ## Email-scan (email_scan) — guide for contributors
 
 Minimal best-practices checklist for email modules
+
 - [ ] Put file in `user_scanner/email_scan/<category>/service.py`.
 - [ ] Export `async def validate_<service>(email: str) -> Result`.
 - [ ] Use `httpx.AsyncClient` for requests, with sensible timeouts and follow_redirects when needed.
@@ -37,13 +36,13 @@ from user_scanner.core.result import Result
 async def _check(email: str) -> Result:
     """
     Internal helper that performs the multi-step signup probe.
-    
-    This function demonstrates how to handle CSRF tokens, custom error 
+
+    This function demonstrates how to handle CSRF tokens, custom error
     messages (like IP bans), and passing the target URL back to Results.
     """
     # The display URL used for output and error reporting
     show_url = "https://mastodon.social"
-    
+
     signup_url = f"{show_url}/auth/sign_up"
     post_url = f"{show_url}/auth"
 
@@ -87,17 +86,17 @@ async def _check(email: str) -> Result:
             # 3. Analyze the response to determine account status
             if "has already been taken" in res_text:
                 return Result.taken(url=show_url)
-            
+
             elif "registration attempt has been blocked" in res_text:
                 return Result.error("Your IP has been flagged by Mastodon", url=show_url)
-            
+
             elif res_status == 429:
                 return Result.error("Rate limited; try using the '-d' flag", url=show_url)
-            
+
             elif res_status in [200, 302]:
                 # If no 'taken' message is found and status is OK/Redirect, it's available
                 return Result.available(url=show_url)
-            
+
             else:
                 return Result.error("Unexpected response body", url=show_url)
 
@@ -109,21 +108,19 @@ async def _check(email: str) -> Result:
 async def validate_mastodon(email: str) -> Result:
     """
     Public validator used by the email mode.
-    
-    All email modules must export a 'validate_<name>' function that 
+
+    All email modules must export a 'validate_<name>' function that
     returns a Result object.
     """
     return await _check(email)
 
 
 ```
 
-
 ---
 
 ## Username availability check guide:
 
-
 ### Validator function (user_scan/)
 
 Each module must expose exactly one validator function named:
@@ -134,6 +131,7 @@ def validate_<sitename>(user: str) -> Result:
 ```
 
 Rules:
+
 - Single parameter: the username (str).
 - Return a Result object (use Result.available(), Result.taken(), or Result.error(msg)).
 - Keep the function synchronous unless you are implementing an optional async variant; prefer sync for consistency.
@@ -146,6 +144,7 @@ Rules:
 To keep validators DRY, the repository provides helper functions in `core/orchestrator.py`. Use these where appropriate.
 
 1. generic_validate
+
 - Purpose: Run a request for a given URL and let a small callback (processor) inspect the httpx.Response and return a Result.
 - Typical signature (example — consult the actual orchestrator implementation for exact parameter names):
   - `generic_validate(url: str, processor: Callable[[httpx.Response], Result], headers: Optional[dict] = None, show_url=None, timeout: float = 5.0, follow_redirects: bool = False) -> Result`
@@ -155,6 +154,7 @@ To keep validators DRY, the repository provides helper functions in `core/orches
 - Use case: Sites that return 200 for both found and not-found states and require checking the HTML body for a unique "not found" string (or other content inspection).
 
 ### Example `github.py` module:
+
 - This example shows how to use `generic_validate()` and how to return Result values with optional error messages.
 
 ```python
@@ -166,7 +166,7 @@ def validate_github(user: str) -> Result:
     Use this when the site requires complex logic or response body parsing.
     """
     url = f"https://github.com/signup_check/username?value={user}"
-    
+
     # Define show_url for clean output display
     show_url = "https://github.com"
 
@@ -185,7 +185,7 @@ def validate_github(user: str) -> Result:
     def process(response):
         """
         Internal processing function.
-        Note: You don't need to pass 'url' here; 
+        Note: You don't need to pass 'url' here;
         generic_validate will attach it automatically from the kwargs.
         """
         if response.status_code == 200:
@@ -199,25 +199,13 @@ def validate_github(user: str) -> Result:
 
         return Result.error(f"GitHub returned unexpected status: {response.status_code}")
 
-    # Pass show_url into generic_validate so the Orchestrator 
+    # Pass show_url into generic_validate so the Orchestrator
     # can attach it to the final Result object.
     return generic_validate(url, process, headers=headers, show_url=show_url)
-
-
-if __name__ == "__main__":
-    user = input("Username?: ").strip()
-    result = validate_github(user)
-
-    if result.is_available():
-        print("Available!")
-    elif result.is_taken():
-        print(f"Unavailable! Site: {result.url}")
-    else:
-        print(f"Error: {result.get_reason()}")
-
 ```
 
 2. status_validate
+
 - Purpose: Simple helper for sites where availability can be determined purely from HTTP status codes (e.g., 404 = available, 200 = taken).
 - Typical signature (example):
   - `status_validate(url: str, available_status: int, taken_status: int, show_url=None, headers: Optional[dict] = None, timeout: float = 5.0, follow_redirects: bool = False) -> Result`
@@ -263,7 +251,6 @@ Note: The exact parameter names and behavior of the orchestrator functions are d
 
 ---
 
-
 ## Return values and error handling
 
 - Always return a Result object:

README.md

@@ -2,7 +2,7 @@
 
 ![User Scanner Logo](https://github.com/user-attachments/assets/49ec8d24-665b-4115-8525-01a8d0ca2ef4)
 <p align="center">
-  <img src="https://img.shields.io/badge/Version-1.3.0.2-blueviolet?style=for-the-badge&logo=github" />
+  <img src="https://img.shields.io/badge/Version-1.3.3.3-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" />
@@ -12,17 +12,17 @@
 
 ---
 
-A powerful *Email OSINT tool* that checks if a specific email is registered on various sites, combined with *username scanning* for branding or OSINT — 2-in-1 tool.  
+A powerful *Email OSINT tool* that checks if a specific email is registered on various sites, combined with *username scanning* for OSINT or branding — 2-in-1 tool.  
 
-Perfect for fast, accurate and lightweight email OSINT
+Perfect for fast, accurate username and email OSINT
 
-Perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instagram, and more, all in a single command.  
+Also perfect for finding a **unique username** across GitHub, Twitter, Reddit, Instagram, and more, all in a single command.  
 
 ## Features
 
 - ✅ Email & username OSINT: check email registrations and username availability across social, developer, creator, and other platforms  
 - ✅ Dual-mode usage: works as an email scanner, username scanner, or username-only tool  
-- ✅ Clear results: `Registered` / `Not Registered` for emails and `Available` / `Taken` / `Error` for usernames with precise failure reasons  
+- ✅ Clear results: `Registered` / `Not Registered` for emails and `Not Found` / `Found` / `Error` for usernames with precise failure reasons  
 - ✅ Fully modular architecture for easy addition of new platform modules  
 - ✅ Bulk scanning support for usernames and emails via input files  
 - ✅ Wildcard-based username permutations with automatic variation generation  
@@ -65,8 +65,8 @@ See [Important flags](docs/FLAGS.md) here and use the tool powerfully
 Scan a single email or username across **all** available modules/platforms:
 
 ```bash
-user-scanner -e john_doe@gmail.com   # single email scanning 
-user-scanner -u john_doe             # single username scanning 
+user-scanner -e johndoe@gmail.com   # single email scanning 
+user-scanner -u johndoe             # single username scanning 
 ```
 ### Verbose mode 
 
@@ -89,8 +89,8 @@ Output:
 Scan only specific categories or single modules:
 
 ```bash
-user-scanner -u john_doe -c dev                # developer platforms only
-user-scanner -e john_doe@gmail.com -m github   # only GitHub
+user-scanner -u johndoe -c dev                # developer platforms only
+user-scanner -e johndoe@gmail.com -m github   # only GitHub
 ```
 
 ### Bulk email/username scanning
@@ -151,31 +151,27 @@ Output:
 Validate proxies before scanning (tests each proxy against google.com):
 
 ```bash
-user-scanner -u john_doe -P proxies.txt --validate-proxies # recommended
+user-scanner -u johndoe -P proxies.txt --validate-proxies # recommended
 ```
 
 This will:
 1. Filter out non-working proxies
 2. Save working proxies to `validated_proxies.txt`
 3. Use only validated proxies for scanning
 
+### Screenshots:
+**Note**: Screenshots might be outdated
 
 ---
+<img width="1080" height="1350" alt="1000175086" src="https://github.com/user-attachments/assets/c90396d6-b8d9-4ea3-aac4-d2086f9b5756" />
 
-## Screenshots: 
-
-- Note*: New modules are constantly getting added so screenshots might show only limited, outdated output:
-
-<img width="1080" height="930" alt="1000146237" src="https://github.com/user-attachments/assets/3cbcecaf-3620-49be-9d0a-8f94790acdf0" />
 
 ---
+<img width="1080" height="730" alt="1000175084" src="https://github.com/user-attachments/assets/b399b924-6c4a-4b5b-af0d-67f7c0b39436" />
 
 
-<img width="1072" height="848" alt="user-scanner's main usage screenshot" src="https://github.com/user-attachments/assets/34e44ca6-e314-419e-9035-d951b493b47f" />
 
 ---
-
-
 ## ❤️ Support the project
 
 If this project helps you, consider supporting its development:
@@ -193,7 +189,7 @@ user_scanner/
 ├── email_scan/       # Currently in development
 │   ├── social/       # Social email scan modules (Instagram, Mastodon, X, etc.)
 |   ├── adult/        # Adult sites 
-|    ...               # New sites to be added soon
+|    ...
 ├── user_scan/
 │   ├── dev/          # Developer platforms (GitHub, GitLab, npm, etc.)
 │   ├── social/       # Social platforms (Twitter/X, Reddit, Instagram, Discord, etc.)
@@ -238,4 +234,3 @@ Some sites may return **403 Forbidden** or **connection timeout** errors, especi
 - Then run the tool again.
 
 These issues are caused by regional or network restrictions, not by the tool itself. If it still fails, report the error by opening an issue.
-

docs/FLAGS.md

@@ -1,20 +1,22 @@
 ## Important Flags
 
-| Flag | Description |
-|------|-------------|
-| `-u, --username USERNAME` | Scan a single username across platforms |
-| `-e, --email EMAIL`       | Scan a single email across platforms |
-| `-uf, --username-file FILE` | Scan multiple usernames from file (one per line) |
-| `-ef, --email-file FILE`  | Scan multiple emails from file (one per line) |
-| `-c, --category CATEGORY` | Scan all platforms in a specific category |
-| `-lu, --list-user`        | List all available modules for username scanning |
-| `-le, --list-email`       | List all available modules for email scanning |
-| `-v, --verbose`           | Enable verbose output to show urls of the websites |
-| `-m, --module MODULE`     | Scan a single specific module |
-| `-p, --permute PERMUTE`   | Generate username permutations using a pattern/suffix |
-| `-P, --proxy-file FILE`   | Use proxies from file (one per line) |
-| `--validate-proxies`      | Validate proxies before scanning (tests against google.com) |
-| `-s, --stop STOP`         | Limit the number of permutations generated |
-| `-d, --delay DELAY`       | Delay (in seconds) between requests |
-| `-f, --format {csv,json}` | Select output format |
-| `-o, --output OUTPUT`     | Save results to a file |
+| Flag                        | Description                                                 |
+| --------------------------- | ----------------------------------------------------------- |
+| `-u, --username USERNAME`   | Scan a single username across platforms                     |
+| `-e, --email EMAIL`         | Scan a single email across platforms                        |
+| `-uf, --username-file FILE` | Scan multiple usernames from file (one per line)            |
+| `-ef, --email-file FILE`    | Scan multiple emails from file (one per line)               |
+| `--only-found`              | Only show sites where the username/email was found          |
+| `--allow-loud`              | Enable scanning sites that may send emails/notifications    |
+| `-c, --category CATEGORY`   | Scan all platforms in a specific category                   |
+| `-lu, --list-user`          | List all available modules for username scanning            |
+| `-le, --list-email`         | List all available modules for email scanning               |
+| `-v, --verbose`             | Enable verbose output to show urls of the websites          |
+| `-m, --module MODULE`       | Scan a single specific module                               |
+| `-p, --permute PERMUTE`     | Generate username permutations using a pattern/suffix       |
+| `-P, --proxy-file FILE`     | Use proxies from file (one per line)                        |
+| `--validate-proxies`        | Validate proxies before scanning (tests against google.com) |
+| `-s, --stop STOP`           | Limit the number of permutations generated                  |
+| `-d, --delay DELAY`         | Delay (in seconds) between requests                         |
+| `-f, --format {csv,json}`   | Select output format                                        |
+| `-o, --output OUTPUT`       | Save results to a file                                      |