argis 0.1.0__tar.gz

argis-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v
+
+  publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distribution
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

argis-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+*.csv
+*.md.export
+.env

argis-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,104 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argis"
+version = "0.1.0"
+description = "Asynchronous username hunter with historical diff tracking across social platforms."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "mohilisop" }]
+keywords = ["osint", "username", "cli", "security", "async"]
+dependencies = [
+    "typer>=0.12.0",
+    "httpx[http2]>=0.27.0",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+argis = "argis.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argis"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/argis/sites.json" = "argis/sites.json"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

argis-0.1.0/src/argis/__init__.py

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

argis-0.1.0/src/argis/__main__.py

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

argis-0.1.0/src/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-0.1.0/src/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