phonsint 0.1.0__py3-none-any.whl

phonsint/__init__.py

@@ -0,0 +1,5 @@
+"""
+phonsint - Advanced Silent Phone Reconnaissance & Identity Footprinting Suite
+"""
+
+__version__ = "0.1.0"

phonsint/__main__.py

@@ -0,0 +1,150 @@
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from colorama import Fore, Style, init
+
+from phonsint import __version__
+from phonsint.core.helpers import ScanConfig, load_categories, load_modules
+from phonsint.core.orchestrator import run_scan
+from phonsint.core.parser import parse_phone_number
+from rich.console import Console
+from rich.table import Table
+
+init(autoreset=True)
+console = Console()
+
+BANNER = rf"""{Fore.CYAN}
+    ____  __                      _       __ 
+   / __ \/ /_  ____  ____  _____ (_)___  / /_
+  / /_/ / __ \/ __ \/ __ \/ ___// / __ \/ __/
+ / ____/ / / / /_/ / / / (__  )/ / / / / /_  
+/_/   /_/ /_/\____/_/ /_/____//_/_/ /_/\__/  
+{Fore.LIGHTBLACK_EX}   phonsint v{__version__} | Silent Phone Reconnaissance & Intelligence Suite
+{Style.RESET_ALL}"""
+
+
+def print_banner() -> None:
+    print(BANNER)
+
+
+
+
+def list_modules() -> None:
+    print_banner()
+    categories = load_categories()
+    if not categories:
+        print(f"{Fore.YELLOW}[!] No modules found.{Style.RESET_ALL}")
+        return
+
+    table = Table(title="[bold cyan]Available Scan Modules[/bold cyan]", border_style="cyan")
+    table.add_column("Category", style="magenta", width=18)
+    table.add_column("Module", style="green", width=22)
+    table.add_column("Path", style="dim white")
+
+    for cat_name, cat_path in sorted(categories.items()):
+        mods = load_modules(cat_path)
+        for m in mods:
+            table.add_row(cat_name.capitalize(), m.__name__.split(".")[-1], str(m.__file__))
+
+    console.print(table)
+
+
+def export_results(results, file_path: str, fmt: str = "json") -> None:
+    out = Path(file_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    if fmt == "csv" or out.suffix.lower() == ".csv":
+        with open(out, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            writer.writerow(["site_name", "category", "phone", "status", "url", "extra", "media", "reason"])
+            for r in results:
+                writer.writerow([
+                    r.site_name,
+                    r.category,
+                    r.phone,
+                    r.status.to_label(),
+                    r.url,
+                    json.dumps(r.extra) if r.extra else "",
+                    json.dumps(r.media) if r.media else "",
+                    r.reason or "",
+                ])
+    else:
+        with open(out, "w", encoding="utf-8") as f:
+            json.dump([r.to_dict() for r in results], f, indent=2)
+
+    print(f"\n{Fore.GREEN}[+] Results successfully exported to: {out}{Style.RESET_ALL}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="phonsint",
+        description="phonsint: High-Throughput Silent Phone Number Reconnaissance & Identity Footprinting",
+    )
+    parser.add_argument("-p", "--phone", help="Target phone number (e.g. +14155552671)")
+    parser.add_argument("-r", "--region", help="Default ISO country code if number lacks '+' prefix (e.g. US, GB, IN, FR)")
+    parser.add_argument("-c", "--category", help="Limit scan to specific comma-separated categories (e.g. auth,social)")
+    parser.add_argument("-m", "--module", help="Limit scan to specific comma-separated modules (e.g. microsoft,facebook)")
+    parser.add_argument("-l", "--list", action="store_true", help="List all available categories and modules")
+    parser.add_argument("--all", action="store_true", help="Show all results including not registered and errors")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Display URLs and diagnostic reasons")
+    parser.add_argument("-t", "--timeout", type=float, default=15.0, help="Per-module request timeout in seconds")
+    parser.add_argument("-C", "--concurrency", type=int, default=15, help="Maximum concurrent requests")
+    parser.add_argument("--allow-loud", action="store_true", help="Allow modules that may trigger SMS/notifications")
+    parser.add_argument("-f", "--format", choices=["json", "csv"], default="json", help="Export format (json/csv)")
+    parser.add_argument("-o", "--output", help="Save scan results to file")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+
+    if args.list:
+        list_modules()
+        return
+
+    if not args.phone:
+        print_banner()
+        parser.print_help()
+        print(f"\n{Fore.RED}[!] Error: Please provide a target phone number using -p / --phone.{Style.RESET_ALL}")
+        sys.exit(1)
+
+    print_banner()
+
+    # Step 1: Parse and validate phone number
+    phone_info = parse_phone_number(args.phone, args.region)
+    print(f"\n{Fore.CYAN} Checking phone: {phone_info.e164}{Style.RESET_ALL}")
+
+    if not phone_info.is_valid:
+        print(f"{Fore.YELLOW}[!] Warning: '{args.phone}' is not a standard allocated number according to E.164.{Style.RESET_ALL}")
+        print(f"{Fore.YELLOW}[*] Proceeding with best-effort scan anyway...{Style.RESET_ALL}\n")
+
+    # Step 2: Build scan configuration
+    configs = ScanConfig(
+        allow_loud=args.allow_loud,
+        show_all=args.all,
+        verbose=args.verbose,
+        timeout=args.timeout,
+        concurrency=args.concurrency,
+    )
+
+    # Step 3: Run platform scan
+    results = run_scan(
+        phone_info,
+        configs,
+        category_filter=args.category,
+        module_filter=args.module,
+    )
+
+    # Summary count
+    taken_count = sum(1 for r in results if r.is_found())
+    print(f"\n{Fore.CYAN}== SUMMARY =={Style.RESET_ALL}")
+    print(f"Total Sites Scanned: {len(results)}")
+    print(f"Registered / Found:  {Fore.GREEN}{taken_count}{Style.RESET_ALL}")
+
+    # Step 4: Export if requested
+    if args.output:
+        export_results(results, args.output, args.format)
+
+
+if __name__ == "__main__":
+    main()

phonsint/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+Core modules for phonsint
+"""

phonsint/core/helpers.py

@@ -0,0 +1,74 @@
+import importlib.util
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Callable, Dict, List, Optional, cast
+
+# List of modules that could potentially alert the target via SMS or phone call
+LOUD_MODULES: List[str] = []
+
+
+@dataclass(frozen=True)
+class ScanConfig:
+    allow_loud: bool = False
+    show_all: bool = False
+    verbose: bool = False
+    timeout: Optional[float] = None
+    concurrency: int = 15
+
+
+def is_loud(site_name: str) -> bool:
+    return site_name.lower() in LOUD_MODULES
+
+
+def get_site_name(module: ModuleType) -> str:
+    name = module.__name__.split(".")[-1].replace("_", " ").title()
+    return name
+
+
+def find_category(module: ModuleType) -> str:
+    parts = module.__name__.split(".")
+    if len(parts) >= 3 and parts[-3] == "modules":
+        return parts[-2].capitalize()
+    return "General"
+
+
+def load_categories() -> Dict[str, Path]:
+    root = Path(__file__).resolve().parent.parent / "modules"
+    categories: Dict[str, Path] = {}
+    if not root.exists():
+        return categories
+
+    for subfolder in root.iterdir():
+        if subfolder.is_dir() and not subfolder.name.startswith("__"):
+            categories[subfolder.name] = subfolder.resolve()
+
+    return categories
+
+
+def load_modules(category_path: Path) -> List[ModuleType]:
+    modules = []
+    for file in category_path.glob("*.py"):
+        if file.name.startswith("__"):
+            continue
+        spec = importlib.util.spec_from_file_location(file.stem, str(file))
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+            modules.append(module)
+        except Exception:
+            continue
+    return modules
+
+
+def get_scan_func(module: ModuleType) -> Optional[Callable[..., Any]]:
+    for attr_name in dir(module):
+        if not attr_name.startswith("validate_"):
+            continue
+        f = getattr(module, attr_name)
+        if inspect.isfunction(f) or inspect.iscoroutinefunction(f):
+            return cast(Callable[..., Any], f)
+    return None

phonsint/core/impersonate.py

@@ -0,0 +1,97 @@
+import asyncio
+import threading
+from typing import Literal, Optional, cast
+from curl_cffi import requests as cffi
+
+DEFAULT_IMPERSONATE = "chrome"
+DEFAULT_TIMEOUT = 15.0
+
+_sessions: dict[tuple, cffi.Session] = {}
+_key_locks: dict[tuple, threading.Lock] = {}
+_warmed: set[tuple] = set()
+_lock = threading.Lock()
+_global_timeout: Optional[float] = None
+_global_proxy: Optional[str] = None
+
+
+def set_global_timeout(val: Optional[float]) -> None:
+    global _global_timeout
+    _global_timeout = val
+
+
+def get_global_timeout() -> float:
+    return _global_timeout if _global_timeout is not None else DEFAULT_TIMEOUT
+
+
+def set_global_proxy(val: Optional[str]) -> None:
+    global _global_proxy
+    _global_proxy = val
+
+
+def get_global_proxy() -> Optional[str]:
+    return _global_proxy
+
+
+def _get_warm_session(
+    impersonate: str,
+    proxy: Optional[str],
+    warmup_url: Optional[str] = None,
+) -> cffi.Session:
+    key = (impersonate, proxy)
+    with _lock:
+        session = _sessions.get(key)
+        if session is None:
+            session = cffi.Session(
+                impersonate=impersonate,  # type: ignore[arg-type]
+                proxies={"http": proxy, "https": proxy} if proxy else None,
+            )
+            _sessions[key] = session
+            _key_locks[key] = threading.Lock()
+
+        key_lock = _key_locks.get(key)
+        if key_lock is None:
+            key_lock = threading.Lock()
+            _key_locks[key] = key_lock
+
+    if warmup_url and key not in _warmed:
+        with key_lock:
+            if key not in _warmed:
+                try:
+                    session.get(warmup_url, timeout=get_global_timeout())
+                except Exception:
+                    pass
+                _warmed.add(key)
+
+    return session
+
+
+def impersonate_request(
+    url: str,
+    method: Literal["GET", "POST"] = "GET",
+    warmup_url: Optional[str] = None,
+    impersonate: str = DEFAULT_IMPERSONATE,
+    **kwargs,
+) -> cffi.Response:
+    """Issue a request through a cookie-persistent browser-impersonating curl_cffi session."""
+    session = _get_warm_session(impersonate, get_global_proxy(), warmup_url)
+    kwargs.setdefault("timeout", get_global_timeout())
+    kwargs.setdefault("allow_redirects", False)
+    return cast(cffi.Response, session.request(method, url, **kwargs))
+
+
+async def impersonate_request_async(
+    url: str,
+    method: Literal["GET", "POST"] = "GET",
+    warmup_url: Optional[str] = None,
+    impersonate: str = DEFAULT_IMPERSONATE,
+    **kwargs,
+) -> cffi.Response:
+    """Async wrapper around impersonate_request."""
+    return await asyncio.to_thread(
+        impersonate_request,
+        url,
+        method=method,
+        warmup_url=warmup_url,
+        impersonate=impersonate,
+        **kwargs,
+    )

phonsint/core/orchestrator.py

@@ -0,0 +1,176 @@
+import asyncio
+import inspect
+from types import ModuleType
+from typing import Callable, List, Optional, Set
+from colorama import Fore, Style
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, SpinnerColumn, TextColumn
+
+from phonsint.core.helpers import (
+    ScanConfig,
+    find_category,
+    get_scan_func,
+    get_site_name,
+    is_loud,
+    load_categories,
+    load_modules,
+)
+from phonsint.core.parser import PhoneInfo
+from phonsint.core.result import Result
+
+
+async def _async_worker(
+    module: ModuleType,
+    phone_info: PhoneInfo,
+    sem: asyncio.Semaphore,
+    configs: ScanConfig,
+    cat_override: Optional[str] = None,
+    on_start: Optional[Callable[[str], None]] = None,
+) -> Result:
+    async with sem:
+        site_name = get_site_name(module)
+        if on_start:
+            on_start(site_name)
+
+        func = get_scan_func(module)
+        category = cat_override or find_category(module)
+
+        params = {
+            "site_name": site_name,
+            "phone": phone_info.e164,
+            "category": category,
+        }
+
+        if not func:
+            return Result.error(f"{site_name} has no validate_ function", **params)
+
+        if not configs.allow_loud and is_loud(site_name):
+            return Result.skipped(reason="Loud module skipped (use --allow-loud)", **params)
+
+        try:
+            timeout_val = (configs.timeout or 15.0) + 5.0
+            # Check if function accepts phone_info object or string
+            sig = inspect.signature(func)
+            arg = phone_info if len(sig.parameters) == 1 and next(iter(sig.parameters.values())).name in ("phone_info", "info") else phone_info.e164
+
+            if inspect.iscoroutinefunction(func):
+                raw_res = await asyncio.wait_for(func(arg), timeout=timeout_val)
+            else:
+                raw_res = await asyncio.wait_for(asyncio.to_thread(func, arg), timeout=timeout_val)
+
+            if isinstance(raw_res, Result):
+                result = raw_res
+            else:
+                result = Result.error("Module returned invalid result type")
+        except asyncio.TimeoutError:
+            result = Result.error(f"Timed out after {timeout_val}s")
+        except Exception as e:
+            result = Result.error(str(e))
+
+        return result.update(**params)
+
+
+async def run_scan_async(
+    phone_info: PhoneInfo,
+    configs: ScanConfig,
+    category_filter: Optional[str] = None,
+    module_filter: Optional[str] = None,
+) -> List[Result]:
+    all_categories = load_categories()
+    if not all_categories:
+        return []
+
+    # Apply category filter if requested
+    if category_filter:
+        cat_targets = [c.strip().lower() for c in category_filter.split(",") if c.strip()]
+        categories = {k: v for k, v in all_categories.items() if k.lower() in cat_targets}
+    else:
+        categories = all_categories
+
+    # Collect modules to run
+    category_modules: List[tuple[str, List[ModuleType]]] = []
+    total_modules = 0
+
+    mod_targets = (
+        [m.strip().lower() for m in module_filter.split(",") if m.strip()]
+        if module_filter
+        else None
+    )
+
+    for cat_name, cat_path in categories.items():
+        mods = load_modules(cat_path)
+        if mod_targets:
+            mods = [m for m in mods if m.__name__.split(".")[-1].lower() in mod_targets]
+        if mods:
+            display_name = cat_name.capitalize()
+            category_modules.append((display_name, mods))
+            total_modules += len(mods)
+
+    if total_modules == 0:
+        print(f"{Fore.YELLOW}[!] No matching scan modules found.{Style.RESET_ALL}")
+        return []
+
+    sem = asyncio.Semaphore(configs.concurrency)
+    all_results: List[Result] = []
+    printed_cats: Set[str] = set()
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        transient=True,
+    ) as progress:
+        task_id = progress.add_task(f"[cyan]Scanning {phone_info.e164}...", total=total_modules)
+
+        def on_start_cb(site: str):
+            progress.update(task_id, description=f"[cyan]Scanning {phone_info.e164}... ({site})")
+
+        spawned_category_tasks = []
+        for display_name, modules in category_modules:
+            tasks = []
+            for module in modules:
+                t = asyncio.create_task(
+                    _async_worker(
+                        module,
+                        phone_info,
+                        sem,
+                        configs,
+                        cat_override=display_name,
+                        on_start=on_start_cb,
+                    )
+                )
+                t.add_done_callback(lambda _: progress.advance(task_id))
+                tasks.append(t)
+            spawned_category_tasks.append((display_name, tasks))
+
+        for display_name, tasks in spawned_category_tasks:
+            if not tasks:
+                continue
+
+            if configs.show_all:
+                if display_name not in printed_cats:
+                    print(f"\n{Fore.MAGENTA}== {display_name.upper()} SITES =={Style.RESET_ALL}")
+                    printed_cats.add(display_name)
+
+            for coro in asyncio.as_completed(tasks):
+                result = await coro
+                if configs.show_all or result.is_visible(configs):
+                    cat = result.category or display_name
+                    if cat not in printed_cats:
+                        print(f"\n{Fore.MAGENTA}== {cat.upper()} SITES =={Style.RESET_ALL}")
+                        printed_cats.add(cat)
+
+                result.show(configs)
+                all_results.append(result)
+
+    return all_results
+
+
+def run_scan(
+    phone_info: PhoneInfo,
+    configs: ScanConfig,
+    category_filter: Optional[str] = None,
+    module_filter: Optional[str] = None,
+) -> List[Result]:
+    return asyncio.run(run_scan_async(phone_info, configs, category_filter, module_filter))

phonsint/core/parser.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from typing import Optional
+import phonenumbers
+
+
+@dataclass(frozen=True)
+class PhoneInfo:
+    """Represents a validated and normalized phone number for platform checks."""
+    raw_input: str
+    is_valid: bool
+    e164: str
+    international_format: str
+    national_format: str
+    country_code: int
+    national_number: int
+    region_code: str
+
+
+def parse_phone_number(raw: str, default_region: Optional[str] = None) -> PhoneInfo:
+    """
+    Parse and normalize a raw phone number into standard formats (E.164, national, country code).
+    """
+    cleaned = raw.strip()
+    test_parse = cleaned if (cleaned.startswith("+") or default_region) else ("+" + cleaned)
+
+    try:
+        parsed = phonenumbers.parse(cleaned if cleaned.startswith("+") else test_parse, default_region)
+    except phonenumbers.NumberParseException:
+        try:
+            parsed = phonenumbers.parse(cleaned, default_region or "US")
+        except phonenumbers.NumberParseException:
+            return PhoneInfo(
+                raw_input=raw,
+                is_valid=False,
+                e164=cleaned,
+                international_format=cleaned,
+                national_format=cleaned,
+                country_code=0,
+                national_number=0,
+                region_code="",
+            )
+
+    is_valid = phonenumbers.is_valid_number(parsed)
+    e164 = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
+    intl = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.INTERNATIONAL)
+    natl = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.NATIONAL)
+    country_code = parsed.country_code
+    national_number = parsed.national_number
+    region_code = phonenumbers.region_code_for_number(parsed) or ""
+
+    return PhoneInfo(
+        raw_input=raw,
+        is_valid=is_valid,
+        e164=e164,
+        international_format=intl,
+        national_format=natl,
+        country_code=country_code or 0,
+        national_number=int(national_number) if national_number is not None else 0,
+        region_code=region_code,
+    )