argis 0.1.0__py3-none-any.whl

argis/__init__.py

@@ -0,0 +1,3 @@
+"""Argis — the all-seeing username scanner."""
+
+__version__ = "0.1.0"

argis/__main__.py

@@ -0,0 +1,4 @@
+from argis.cli import app
+
+if __name__ == "__main__":
+    app()

argis/cli.py

@@ -0,0 +1,147 @@
+"""Command-line interface for Argis. Parses flags and delegates to core.py
+and diff.py — this module should stay free of scanning/HTTP logic."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from argis import diff as diffmod
+from argis.core import ArgisEngine
+from argis.exceptions import ArgisError
+from argis.utils import display
+from argis.utils.display import console
+from argis.utils.export import export_results
+
+app = typer.Typer(
+    help="Argis: the all-seeing username scanner. Hunt down accounts across "
+    "dozens of platforms and track how a username's footprint changes over time."
+)
+
+
+@app.command()
+def scan(
+    username: str = typer.Argument(..., help="The target username to hunt down."),
+    diff: bool = typer.Option(
+        False, "--diff", "-d", help="Compare this scan against the last saved scan."
+    ),
+    save: bool = typer.Option(
+        True, "--save/--no-save", help="Save this scan to history for future --diff runs."
+    ),
+    proxy: Optional[str] = typer.Option(
+        None, "--proxy", help="Route requests through a proxy, e.g. socks5://127.0.0.1:9050"
+    ),
+    tor: bool = typer.Option(
+        False, "--tor", help="Route requests through a local Tor SOCKS5 proxy."
+    ),
+    timeout: float = typer.Option(7.0, "--timeout", help="Per-request timeout in seconds."),
+    concurrency: int = typer.Option(
+        30, "--concurrency", help="Maximum number of simultaneous requests."
+    ),
+    export: Optional[str] = typer.Option(
+        None, "--export", help="Export format: csv, json, or markdown."
+    ),
+    output: Optional[Path] = typer.Option(
+        None, "-o", "--output", help="Output file path for --export (default: <username>.<ext>)."
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Suppress the progress bar and live [+] hits."
+    ),
+):
+    """Search for a target username across all configured platforms."""
+    if not quiet:
+        display.print_banner(username)
+
+    try:
+        engine = ArgisEngine(
+            username,
+            proxy=proxy,
+            use_tor=tor,
+            timeout=timeout,
+            concurrency=concurrency,
+        )
+        results = asyncio.run(engine.run_scan(quiet=quiet))
+    except ArgisError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(code=1)
+
+    if not quiet:
+        console.print()
+        display.print_results_table(results, username)
+        display.print_summary(results)
+
+    if diff:
+        previous = diffmod.get_last_scan(username)
+        console.print()
+        if previous is None:
+            console.print(
+                "[dim]No previous scan found for this username — nothing to diff "
+                "against. This scan will become the baseline.[/dim]"
+            )
+        else:
+            delta = diffmod.compute_diff(previous["results"], results)
+            display.print_diff(delta)
+
+    if save:
+        diffmod.save_scan(username, results)
+
+    if export:
+        fmt = export.lower()
+        ext = {"json": "json", "csv": "csv", "markdown": "md"}.get(fmt)
+        if ext is None:
+            console.print(f"[bold red]Unsupported export format:[/bold red] {export}")
+            raise typer.Exit(code=1)
+        out_path = output or Path(f"{username}.{ext}")
+        export_results(results, username, fmt, out_path)
+        console.print(f"[dim]Exported results to {out_path}[/dim]")
+
+
+@app.command()
+def history(
+    username: str = typer.Argument(..., help="Username whose scan history to display."),
+    limit: int = typer.Option(10, "--limit", help="Maximum number of past scans to show."),
+):
+    """Show past scan timestamps and found-profile counts for a username."""
+    records = diffmod.load_history(username)
+    if not records:
+        console.print(f"[dim]No history found for '{username}'.[/dim]")
+        return
+
+    table = Table(title=f"Scan history for @{username}")
+    table.add_column("#")
+    table.add_column("Timestamp")
+    table.add_column("Found")
+    table.add_column("Total sites")
+
+    for i, record in enumerate(records[-limit:], start=1):
+        found = sum(1 for r in record["results"].values() if r["status"] == "FOUND")
+        table.add_row(str(i), record["timestamp"], str(found), str(len(record["results"])))
+
+    console.print(table)
+
+
+@app.command("clear-history")
+def clear_history(
+    username: str = typer.Argument(..., help="Username whose history should be deleted."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+):
+    """Delete all saved scan history for a username."""
+    if not yes:
+        confirmed = typer.confirm(f"Delete all saved history for '{username}'?")
+        if not confirmed:
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit()
+
+    removed = diffmod.clear_history(username)
+    if removed:
+        console.print(f"[green]History cleared for '{username}'.[/green]")
+    else:
+        console.print(f"[dim]No history existed for '{username}'.[/dim]")
+
+
+if __name__ == "__main__":
+    app()

argis/core.py

@@ -0,0 +1,155 @@
+"""The operational heart of Argis: loads site rules, runs concurrent async
+HTTP checks, and applies detection rules to filter out false positives."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import pathlib
+
+import httpx
+
+from argis.exceptions import SiteConfigError
+from argis.utils.display import console, make_progress, print_found
+from argis.utils.network import build_client, random_user_agent
+
+# Generic markers that indicate a WAF/bot-challenge page rather than a real
+# answer about account existence (e.g. Cloudflare's "Client Challenge",
+# reCAPTCHA walls). These can return HTTP 200, so status-code rules alone
+# would misread them as FOUND. Checked before any per-site rule runs.
+_CHALLENGE_MARKERS = (
+    "client challenge",
+    "checking your browser",
+    "attention required",
+    "verify you are human",
+    "just a moment...",
+    "captcha",
+)
+
+
+class ArgisEngine:
+    def __init__(
+        self,
+        username: str,
+        *,
+        proxy: str | None = None,
+        use_tor: bool = False,
+        timeout: float = 7.0,
+        concurrency: int = 30,
+        sites_path: pathlib.Path | None = None,
+    ):
+        self.username = username
+        self.proxy = proxy
+        self.use_tor = use_tor
+        self.timeout = timeout
+        self.sites = self._load_sites(sites_path)
+        self._semaphore = asyncio.Semaphore(concurrency)
+
+    def _load_sites(self, sites_path: pathlib.Path | None) -> dict:
+        """Locate and load target site config relative to the package path."""
+        path = sites_path or (pathlib.Path(__file__).parent / "sites.json")
+        if not path.exists():
+            raise SiteConfigError(f"sites.json not found at {path}")
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                sites = json.load(fh)
+        except json.JSONDecodeError as exc:
+            raise SiteConfigError(f"sites.json is not valid JSON: {exc}") from exc
+
+        for name, rules in sites.items():
+            if "url" not in rules or "error_type" not in rules:
+                raise SiteConfigError(
+                    f"Site '{name}' is missing required 'url' or 'error_type' key"
+                )
+        return sites
+
+    async def check_platform(
+        self, client: httpx.AsyncClient, name: str, rules: dict
+    ) -> dict:
+        """Evaluate a single site against its detection rule. Never raises."""
+        target_url = rules["url"].format(self.username)
+        headers = {"User-Agent": random_user_agent()}
+
+        async with self._semaphore:
+            try:
+                response = await client.get(target_url, headers=headers)
+            except httpx.TooManyRedirects:
+                return {"status": "UNKNOWN", "url": target_url}
+            except httpx.TimeoutException:
+                return {"status": "TIMEOUT", "url": target_url}
+            except httpx.RequestError:
+                return {"status": "UNKNOWN", "url": target_url}
+            except Exception:
+                # Catches low-level transport/protocol errors that escape
+                # httpx's own exception hierarchy (e.g. a raw h2.ProtocolError
+                # from a connection torn down mid-handshake under high
+                # concurrency). A single misbehaving connection should never
+                # take down the whole scan's asyncio.gather.
+                return {"status": "UNKNOWN", "url": target_url}
+
+        # 429 / 403 usually mean a WAF or rate limiter intervened, not a
+        # legitimate answer about account existence.
+        if response.status_code in (403, 429):
+            return {"status": "BLOCKED", "url": target_url}
+
+        # Some WAFs (e.g. Cloudflare) serve a challenge page with a 200,
+        # which would otherwise be misread as a legitimate FOUND result.
+        lowered_text = response.text[:2000].lower()
+        if any(marker in lowered_text for marker in _CHALLENGE_MARKERS):
+            return {"status": "BLOCKED", "url": target_url}
+
+        error_type = rules["error_type"]
+        error_criteria = rules.get("error_criteria")
+
+        if error_type == "status_code":
+            if response.status_code == int(error_criteria):
+                return {"status": "NOT_FOUND", "url": target_url}
+        elif error_type == "message":
+            if error_criteria and error_criteria in response.text:
+                return {"status": "NOT_FOUND", "url": target_url}
+        elif error_type == "response_url":
+            if error_criteria and str(response.url).rstrip("/") == error_criteria.rstrip("/"):
+                return {"status": "NOT_FOUND", "url": target_url}
+
+        if response.status_code == 200:
+            return {"status": "FOUND", "url": target_url}
+
+        return {"status": "UNKNOWN", "url": target_url}
+
+    async def run_scan(self, *, quiet: bool = False) -> dict[str, dict]:
+        """Run all site checks concurrently with a live progress bar."""
+        results: dict[str, dict] = {}
+
+        async with build_client(
+            proxy=self.proxy, use_tor=self.use_tor, timeout=self.timeout
+        ) as client:
+            if quiet:
+                tasks = [
+                    self.check_platform(client, name, rules)
+                    for name, rules in self.sites.items()
+                ]
+                outcomes = await asyncio.gather(*tasks)
+                for (name, _), outcome in zip(self.sites.items(), outcomes):
+                    results[name] = outcome
+                return results
+
+            with make_progress() as progress:
+                task_id = progress.add_task(
+                    "[yellow]Probing networks...", total=len(self.sites)
+                )
+
+                async def run_one(name: str, rules: dict) -> None:
+                    outcome = await self.check_platform(client, name, rules)
+                    results[name] = outcome
+                    if outcome["status"] == "FOUND":
+                        progress.console.print(
+                            f"[bold green][+][/bold green] [white]{name}:[/white] "
+                            f"[underline cyan]{outcome['url']}[/underline cyan]"
+                        )
+                    progress.advance(task_id)
+
+                await asyncio.gather(
+                    *(run_one(name, rules) for name, rules in self.sites.items())
+                )
+
+        return results

argis/diff.py

@@ -0,0 +1,119 @@
+"""Persist scan history per-username as JSON and compute deltas between runs.
+
+History layout: ~/.argis/history/<username>.json
+    [
+      {"timestamp": "2026-07-06T10:00:00+00:00", "results": {name: {"status": ..., "url": ...}}},
+      ...
+    ]
+
+The most recent entry is always last in the list.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from argis.exceptions import HistoryError
+
+
+def history_dir() -> Path:
+    """Return (and create if needed) the directory holding all history files."""
+    directory = Path.home() / ".argis" / "history"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def _safe_filename(username: str) -> str:
+    """Sanitize a username into a filesystem-safe file stem."""
+    keep = "-_."
+    return "".join(c if c.isalnum() or c in keep else "_" for c in username) + ".json"
+
+
+def history_file(username: str) -> Path:
+    return history_dir() / _safe_filename(username)
+
+
+def load_history(username: str) -> list[dict]:
+    """Load all past scans for a username, oldest first. Empty list if none."""
+    path = history_file(username)
+    if not path.exists():
+        return []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        if not isinstance(data, list):
+            raise ValueError("history file is not a list")
+        return data
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise HistoryError(f"Could not read history for '{username}': {exc}") from exc
+
+
+def get_last_scan(username: str) -> dict | None:
+    history = load_history(username)
+    return history[-1] if history else None
+
+
+def save_scan(username: str, results: dict[str, dict], *, max_entries: int = 50) -> None:
+    """Append a new scan snapshot to the username's history file.
+
+    Args:
+        username: the target username.
+        results: mapping of platform name -> {"status": ..., "url": ...}.
+        max_entries: cap on retained history entries (oldest are dropped).
+    """
+    history = load_history(username)
+    history.append(
+        {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "results": results,
+        }
+    )
+    # Keep history bounded so the file doesn't grow unbounded over years of use.
+    history = history[-max_entries:]
+
+    path = history_file(username)
+    try:
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(history, fh, indent=2)
+    except OSError as exc:
+        raise HistoryError(f"Could not write history for '{username}': {exc}") from exc
+
+
+def clear_history(username: str) -> bool:
+    """Delete a username's history file. Returns True if a file was removed."""
+    path = history_file(username)
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def compute_diff(previous: dict[str, dict], current: dict[str, dict]) -> dict:
+    """Compare two result snapshots and return added/removed/unchanged info.
+
+    A platform is "added" if it wasn't FOUND before but is FOUND now.
+    A platform is "removed" if it was FOUND before but is not FOUND now.
+    """
+    added: list[tuple[str, str]] = []
+    removed: list[tuple[str, str]] = []
+    unchanged = 0
+
+    all_names = set(previous) | set(current)
+    for name in sorted(all_names):
+        prev_status = previous.get(name, {}).get("status")
+        curr_status = current.get(name, {}).get("status")
+        curr_url = current.get(name, {}).get("url", previous.get(name, {}).get("url", ""))
+
+        was_found = prev_status == "FOUND"
+        is_found = curr_status == "FOUND"
+
+        if is_found and not was_found:
+            added.append((name, curr_url))
+        elif was_found and not is_found:
+            removed.append((name, curr_url))
+        else:
+            unchanged += 1
+
+    return {"added": added, "removed": removed, "unchanged_count": unchanged}

argis/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions used across Argis."""
+
+
+class ArgisError(Exception):
+    """Base class for all Argis-specific errors."""
+
+
+class SiteConfigError(ArgisError):
+    """Raised when sites.json is missing, malformed, or fails validation."""
+
+
+class SiteBlockedError(ArgisError):
+    """Raised when a target site actively blocks or rate-limits the scanner."""
+
+    def __init__(self, site_name: str, detail: str = ""):
+        self.site_name = site_name
+        self.detail = detail
+        message = f"{site_name} blocked the request"
+        if detail:
+            message += f": {detail}"
+        super().__init__(message)
+
+
+class HistoryError(ArgisError):
+    """Raised when reading or writing scan history fails."""

argis/sites.json

@@ -0,0 +1,506 @@
+{
+  "GitHub": {
+    "url": "https://github.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "GitLab": {
+    "url": "https://gitlab.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Bitbucket": {
+    "url": "https://bitbucket.org/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "SourceForge": {
+    "url": "https://sourceforge.net/u/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "PyPI": {
+    "url": "https://pypi.org/user/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "npm": {
+    "url": "https://www.npmjs.com/~{}",
+    "error_type": "message",
+    "error_criteria": "Cannot GET",
+    "category": "coding"
+  },
+  "Docker Hub": {
+    "url": "https://hub.docker.com/u/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Replit": {
+    "url": "https://replit.com/@{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "CodePen": {
+    "url": "https://codepen.io/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Kaggle": {
+    "url": "https://www.kaggle.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Stack Overflow": {
+    "url": "https://stackoverflow.com/users/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "HackerRank": {
+    "url": "https://www.hackerrank.com/{}",
+    "error_type": "message",
+    "error_criteria": "Page Not Found",
+    "category": "coding"
+  },
+  "HackerOne": {
+    "url": "https://hackerone.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "security"
+  },
+  "Bugcrowd": {
+    "url": "https://bugcrowd.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "security"
+  },
+  "Keybase": {
+    "url": "https://keybase.io/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "security"
+  },
+  "Reddit": {
+    "url": "https://www.reddit.com/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "X (Twitter)": {
+    "url": "https://x.com/{}",
+    "error_type": "message",
+    "error_criteria": "This account doesn’t exist",
+    "category": "social"
+  },
+  "Instagram": {
+    "url": "https://www.instagram.com/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "Facebook": {
+    "url": "https://www.facebook.com/{}",
+    "error_type": "message",
+    "error_criteria": "This content isn't available",
+    "category": "social"
+  },
+  "TikTok": {
+    "url": "https://www.tiktok.com/@{}",
+    "error_type": "message",
+    "error_criteria": "Couldn't find this account",
+    "category": "social"
+  },
+  "Snapchat": {
+    "url": "https://www.snapchat.com/add/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "Pinterest": {
+    "url": "https://www.pinterest.com/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "Tumblr": {
+    "url": "https://{}.tumblr.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "LinkedIn": {
+    "url": "https://www.linkedin.com/in/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "Mastodon (mastodon.social)": {
+    "url": "https://mastodon.social/@{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "social"
+  },
+  "VK": {
+    "url": "https://vk.com/{}",
+    "error_type": "message",
+    "error_criteria": "This page has been deleted",
+    "category": "social"
+  },
+  "Quora": {
+    "url": "https://www.quora.com/profile/{}",
+    "error_type": "message",
+    "error_criteria": "Page Not Found",
+    "category": "social"
+  },
+  "YouTube": {
+    "url": "https://www.youtube.com/@{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Twitch": {
+    "url": "https://www.twitch.tv/{}",
+    "error_type": "message",
+    "error_criteria": "Sorry. Unless you've got a time machine",
+    "category": "media"
+  },
+  "Vimeo": {
+    "url": "https://vimeo.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "SoundCloud": {
+    "url": "https://soundcloud.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Spotify": {
+    "url": "https://open.spotify.com/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Last.fm": {
+    "url": "https://www.last.fm/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Flickr": {
+    "url": "https://www.flickr.com/people/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "DeviantArt": {
+    "url": "https://{}.deviantart.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Behance": {
+    "url": "https://www.behance.net/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Dribbble": {
+    "url": "https://dribbble.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "500px": {
+    "url": "https://500px.com/p/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Medium": {
+    "url": "https://medium.com/@{}",
+    "error_type": "response_url",
+    "error_criteria": "https://medium.com/404",
+    "category": "blogging"
+  },
+  "Dev.to": {
+    "url": "https://dev.to/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "Hashnode": {
+    "url": "https://hashnode.com/@{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "Substack": {
+    "url": "https://{}.substack.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "WordPress": {
+    "url": "https://{}.wordpress.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "Blogger": {
+    "url": "https://{}.blogspot.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "Wattpad": {
+    "url": "https://www.wattpad.com/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "blogging"
+  },
+  "Goodreads": {
+    "url": "https://www.goodreads.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "Letterboxd": {
+    "url": "https://letterboxd.com/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "MyAnimeList": {
+    "url": "https://myanimelist.net/profile/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "Chess.com": {
+    "url": "https://www.chess.com/member/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "Lichess": {
+    "url": "https://lichess.org/@/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "Steam": {
+    "url": "https://steamcommunity.com/id/{}",
+    "error_type": "message",
+    "error_criteria": "The specified profile could not be found",
+    "category": "gaming"
+  },
+  "Xbox Gamertag": {
+    "url": "https://xboxgamertag.com/search/{}",
+    "error_type": "message",
+    "error_criteria": "This profile is currently unavailable",
+    "category": "gaming"
+  },
+  "Itch.io": {
+    "url": "https://{}.itch.io/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "gaming"
+  },
+  "Patreon": {
+    "url": "https://www.patreon.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "funding"
+  },
+  "Ko-fi": {
+    "url": "https://ko-fi.com/{}",
+    "error_type": "message",
+    "error_criteria": "This page is not available",
+    "category": "funding"
+  },
+  "Buy Me a Coffee": {
+    "url": "https://www.buymeacoffee.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "funding"
+  },
+  "GoFundMe": {
+    "url": "https://www.gofundme.com/f/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "funding"
+  },
+  "Product Hunt": {
+    "url": "https://www.producthunt.com/@{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "startup"
+  },
+  "AngelList (Wellfound)": {
+    "url": "https://wellfound.com/u/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "startup"
+  },
+  "Gravatar": {
+    "url": "https://gravatar.com/{}",
+    "error_type": "message",
+    "error_criteria": "profile isn't available",
+    "category": "identity"
+  },
+  "About.me": {
+    "url": "https://about.me/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "identity"
+  },
+  "Linktree": {
+    "url": "https://linktr.ee/{}",
+    "error_type": "message",
+    "error_criteria": "This page is unavailable",
+    "category": "identity"
+  },
+  "Imgur": {
+    "url": "https://imgur.com/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Telegram": {
+    "url": "https://t.me/{}",
+    "error_type": "message",
+    "error_criteria": "If you have Telegram, you can contact",
+    "category": "messaging"
+  },
+  "SlideShare": {
+    "url": "https://www.slideshare.net/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "docs"
+  },
+  "Issuu": {
+    "url": "https://issuu.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "docs"
+  },
+  "Codeforces": {
+    "url": "https://codeforces.com/profile/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "LeetCode": {
+    "url": "https://leetcode.com/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Codewars": {
+    "url": "https://www.codewars.com/users/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "Hacker News": {
+    "url": "https://news.ycombinator.com/user?id={}",
+    "error_type": "message",
+    "error_criteria": "No such user.",
+    "category": "coding"
+  },
+  "Sourcehut": {
+    "url": "https://sr.ht/~{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "coding"
+  },
+  "osu!": {
+    "url": "https://osu.ppy.sh/users/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "gaming"
+  },
+  "Kongregate": {
+    "url": "https://www.kongregate.com/accounts/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "gaming"
+  },
+  "Newgrounds": {
+    "url": "https://{}.newgrounds.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "gaming"
+  },
+  "Bandcamp": {
+    "url": "https://{}.bandcamp.com/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Mixcloud": {
+    "url": "https://www.mixcloud.com/{}/",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Dailymotion": {
+    "url": "https://www.dailymotion.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "ArtStation": {
+    "url": "https://www.artstation.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "VSCO": {
+    "url": "https://vsco.co/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "media"
+  },
+  "Pastebin": {
+    "url": "https://pastebin.com/u/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "docs"
+  },
+  "Fiverr": {
+    "url": "https://www.fiverr.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "startup"
+  },
+  "Open Collective": {
+    "url": "https://opencollective.com/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "funding"
+  },
+  "Untappd": {
+    "url": "https://untappd.com/user/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  },
+  "Ravelry": {
+    "url": "https://www.ravelry.com/people/{}",
+    "error_type": "status_code",
+    "error_criteria": 404,
+    "category": "lifestyle"
+  }
+}

argis/utils/display.py

@@ -0,0 +1,93 @@
+"""Rich-based terminal UI components: progress bars, tables, diff views."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+)
+from rich.table import Table
+
+console = Console()
+
+STATUS_STYLES = {
+    "FOUND": "bold green",
+    "NOT_FOUND": "dim red",
+    "UNKNOWN": "yellow",
+    "TIMEOUT": "yellow",
+    "BLOCKED": "bold magenta",
+}
+
+
+def make_progress() -> Progress:
+    """Build the live progress bar used while scanning platforms."""
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        console=console,
+    )
+
+
+def print_banner(username: str) -> None:
+    console.print(f"[bold white]\U0001f441\ufe0f  Argis Engine[/bold white] initializing...")
+    console.print(f"Targeting handle: [bold cyan]@{username}[/bold cyan]\n")
+
+
+def print_found(name: str, url: str) -> None:
+    console.print(f"[bold green][+][/bold green] [white]{name}:[/white] "
+                  f"[underline cyan]{url}[/underline cyan]")
+
+
+def print_results_table(results: dict[str, dict], username: str) -> None:
+    """Render a full results table (name, status, url)."""
+    table = Table(title=f"Argis scan results for @{username}", show_lines=False)
+    table.add_column("Platform", style="white")
+    table.add_column("Status")
+    table.add_column("URL", style="cyan", overflow="fold")
+
+    for name, info in sorted(results.items()):
+        status = info["status"]
+        style = STATUS_STYLES.get(status, "white")
+        table.add_row(name, f"[{style}]{status}[/{style}]", info["url"])
+
+    console.print(table)
+
+
+def print_summary(results: dict[str, dict]) -> None:
+    found = sum(1 for r in results.values() if r["status"] == "FOUND")
+    total = len(results)
+    console.print(
+        Panel.fit(
+            f"[bold green]{found}[/bold green] / {total} platforms show an "
+            f"active profile",
+            title="Summary",
+        )
+    )
+
+
+def print_diff(diff: dict) -> None:
+    """Render a diff report: newly found, newly gone, unchanged counts."""
+    table = Table(title="Diff since last scan")
+    table.add_column("Change", style="white")
+    table.add_column("Platform")
+    table.add_column("URL", style="cyan", overflow="fold")
+
+    for name, url in diff.get("added", []):
+        table.add_row("[bold green][+] REGISTERED[/bold green]", name, url)
+    for name, url in diff.get("removed", []):
+        table.add_row("[bold red][-] DELETED[/bold red]", name, url)
+
+    if not diff.get("added") and not diff.get("removed"):
+        console.print("[dim]No changes detected since the last scan.[/dim]")
+    else:
+        console.print(table)
+
+    unchanged = diff.get("unchanged_count", 0)
+    console.print(f"[dim]{unchanged} platform(s) unchanged.[/dim]")

argis/utils/export.py

@@ -0,0 +1,44 @@
+"""Serialize scan results to csv, json, or markdown."""
+
+from __future__ import annotations
+
+import csv
+import json
+from io import StringIO
+from pathlib import Path
+
+
+def to_json(results: dict[str, dict]) -> str:
+    return json.dumps(results, indent=2)
+
+
+def to_csv(results: dict[str, dict]) -> str:
+    buffer = StringIO()
+    writer = csv.writer(buffer)
+    writer.writerow(["platform", "status", "url"])
+    for name, info in sorted(results.items()):
+        writer.writerow([name, info["status"], info["url"]])
+    return buffer.getvalue()
+
+
+def to_markdown(results: dict[str, dict], username: str) -> str:
+    lines = [f"# Argis scan results for `@{username}`", "", "| Platform | Status | URL |", "|---|---|---|"]
+    for name, info in sorted(results.items()):
+        lines.append(f"| {name} | {info['status']} | {info['url']} |")
+    return "\n".join(lines) + "\n"
+
+
+FORMATTERS = {
+    "json": lambda results, username: to_json(results),
+    "csv": lambda results, username: to_csv(results),
+    "markdown": to_markdown,
+}
+
+
+def export_results(results: dict[str, dict], username: str, fmt: str, out_path: Path) -> Path:
+    formatter = FORMATTERS.get(fmt)
+    if formatter is None:
+        raise ValueError(f"Unsupported export format: {fmt}")
+    content = formatter(results, username)
+    out_path.write_text(content, encoding="utf-8")
+    return out_path

argis/utils/network.py

@@ -0,0 +1,60 @@
+"""HTTP client construction, user-agent rotation, and proxy/Tor routing."""
+
+from __future__ import annotations
+
+import random
+
+import httpx
+
+# A small rotation pool. Real browser UAs reduce the odds of a WAF (e.g.
+# Cloudflare) flagging the scan as bot traffic.
+USER_AGENTS = [
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4_1) AppleWebKit/605.1.15 "
+    "(KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:125.0) "
+    "Gecko/20100101 Firefox/125.0",
+    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) "
+    "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 "
+    "Safari/604.1",
+]
+
+TOR_PROXY_URL = "socks5://127.0.0.1:9050"
+
+
+def random_user_agent() -> str:
+    """Return a random desktop/mobile User-Agent string."""
+    return random.choice(USER_AGENTS)
+
+
+def build_client(
+    *,
+    proxy: str | None = None,
+    use_tor: bool = False,
+    timeout: float = 7.0,
+    http2: bool = False,
+) -> httpx.AsyncClient:
+    """Construct a configured httpx.AsyncClient.
+
+    Args:
+        proxy: Explicit proxy URL (e.g. "socks5://127.0.0.1:9050" or
+            "http://user:pass@host:port"). Takes precedence over use_tor.
+        use_tor: If True and no explicit proxy given, route through a local
+            Tor SOCKS5 proxy (assumes Tor is running on the default port).
+        timeout: Per-request timeout in seconds.
+        http2: Enable HTTP/2 multiplexing support.
+    """
+    proxy_url = proxy or (TOR_PROXY_URL if use_tor else None)
+
+    kwargs: dict = {
+        "http2": http2,
+        "timeout": httpx.Timeout(timeout),
+        "follow_redirects": True,
+    }
+    if proxy_url:
+        kwargs["proxy"] = proxy_url
+
+    return httpx.AsyncClient(**kwargs)

argis-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: argis
+Version: 0.1.0
+Summary: Asynchronous username hunter with historical diff tracking across social platforms.
+Author: mohilisop
+License: MIT
+Keywords: async,cli,osint,security,username
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]>=0.27.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Argis 👁️
+
+**The all-seeing username scanner.**
+
+Argis hunts down a username across dozens of platforms concurrently, tells
+you where it's registered, and — unlike most tools in this space — tracks
+how that footprint *changes* over time.
+
+Named after Argus, the hundred-eyed giant of Greek myth: one scan, every
+platform, watched at once.
+
+## Features
+
+- **Async everything.** Built on `httpx` + `asyncio`; scans 80+ sites in
+  parallel instead of one at a time.
+- **Diff engine.** `--diff` compares the current scan against your last
+  saved run and shows exactly what got registered or deleted.
+- **False-positive resistant.** Detection rules per site (status code,
+  page-text match, or redirect-URL match) instead of blindly trusting a
+  200 OK.
+- **Pretty terminal UI.** Live progress bar and color-coded results via
+  `rich`.
+- **Exportable.** `--export csv|json|markdown` for piping into other tools.
+- **Proxy / Tor support.** Route scans through a proxy or local Tor.
+
+## Install
+
+```bash
+# From source, editable (for development):
+pip install -e .
+
+# Or with pipx (recommended once published):
+pipx install argis
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+```bash
+# Basic scan
+argis scan john_doe
+
+# Scan and compare against the last saved run
+argis scan john_doe --diff
+
+# Don't save this run to history
+argis scan john_doe --no-save
+
+# Export results
+argis scan john_doe --export markdown -o john_doe_report.md
+
+# Route through Tor
+argis scan john_doe --tor
+
+# View past scans
+argis history john_doe
+
+# Wipe saved history
+argis clear-history john_doe
+```
+
+## How detection works
+
+Each entry in `src/argis/sites.json` defines a URL template plus a rule for
+recognizing a "not found" response:
+
+| `error_type`   | Meaning                                                          |
+|----------------|-------------------------------------------------------------------|
+| `status_code`  | Account doesn't exist if the response status matches `error_criteria` |
+| `message`      | Account doesn't exist if `error_criteria` text appears in the HTML |
+| `response_url` | Account doesn't exist if the final (post-redirect) URL matches    |
+
+Add your own targets by editing `sites.json` — no code changes required.
+
+## History storage
+
+Scan history is stored per-username as JSON at
+`~/.argis/history/<username>.json`. Each file holds a bounded list of past
+snapshots (newest last), which is what `--diff` and `argis history` read
+from.
+
+## Project layout
+
+```
+argis/
+├── pyproject.toml
+├── src/argis/
+│   ├── cli.py          # typer commands
+│   ├── core.py          # async scanning engine
+│   ├── diff.py           # history storage + diff computation
+│   ├── exceptions.py
+│   ├── sites.json        # target platforms + detection rules
+│   └── utils/
+│       ├── display.py    # rich UI
+│       ├── network.py    # httpx client, UA rotation, proxy/Tor
+│       └── export.py      # csv/json/markdown export
+└── tests/
+```
+
+## Disclaimer
+
+Use responsibly. Only look up usernames you have a legitimate reason to
+investigate, and respect the terms of service of the sites you query.

argis-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+argis/__init__.py,sha256=EYtv235kanrA-_viKjVuSrWpJrysBzeWl3rlryv0Yhc,72
+argis/__main__.py,sha256=nbC5WGa8tJJHmgEl_KaVtcTMPtWj5UCwwsNkjxm65ic,64
+argis/cli.py,sha256=C7EhNsHyQuAw493Ab9bbt32G51IRsUjVwFFCtSoTweA,5158
+argis/core.py,sha256=IxXbqMIl4iy5-TugHV4Yj7b_AWNYeRsw7lgaghMsp6c,6346
+argis/diff.py,sha256=iB6boQWIgljrzsoWmD0yQQECybf6prWgApVkGEQskpM,3922
+argis/exceptions.py,sha256=RLSasG9qZIxd0F4z4sJgn99qC6pyOV1cj0REZ7Pt02o,719
+argis/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+argis/utils/display.py,sha256=jKxemFKxwikh8R1o316MyE34MxQlpCuMkvHoozeTHdk,2945
+argis/utils/export.py,sha256=DLdqh0kJQoQJVIJ9Y3PpfMIugzGC7Pdz6HCURd8V-Lw,1366
+argis/utils/network.py,sha256=d3zT99eqwBLeCScXZclyZD3OxoGl7ER62pzEIdzySN4,1987
+argis/sites.json,sha256=gvzqkeZq36QeDsZiuZw7SdQwY5ix9kNjy-HGWWPVhlE,12742
+argis-0.1.0.dist-info/METADATA,sha256=a1HtHIatgsv2lTWw9wTDFPGdM9PVbxR3uE0tRtns15A,3678
+argis-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+argis-0.1.0.dist-info/entry_points.txt,sha256=MjCc3_UW3cgb8Ja6PSMKQvz5Ulv1dk4NLCg1pn_xNfA,40
+argis-0.1.0.dist-info/RECORD,,

argis-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

argis-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+argis = argis.cli:app