xwllz 0.1.0__tar.gz

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

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+      - name: Test
+        run: python -m pytest -q

xwllz-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.db
+.coverage

xwllz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xwllz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xwllz-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: xwllz
+Version: 0.1.0
+Summary: Attack-surface management for blue teams — discover, monitor, and report on your external perimeter.
+Project-URL: Homepage, https://xwllz.pages.dev
+Project-URL: Repository, https://github.com/stalane/xwllz-cli
+License: MIT
+License-File: LICENSE
+Keywords: asm,attack-surface,blue-team,cli,recon,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: dnspython>=2.6
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# xwllz — Attack-surface management for blue teams
+
+`xwllz` is a CLI for discovering, monitoring, and reporting on your **own external
+attack surface**. It maps the domains, subdomains, IPs, services, certificates, and
+exposure points an attacker can reach — so blue teams can see their perimeter before
+attackers do.
+
+## Quickstart
+
+```bash
+pip install xwllz
+
+xwllz init acme --domains example.com,corp.example.com
+xwllz discover acme
+xwllz monitor acme        # re-scan and show what changed
+xwllz report acme --format md
+```
+
+No system binaries are required. `xwllz` is pure Python by default; if you have
+`nmap`, `masscan`, `rustscan`, `nuclei`, `httpx`, `dnsx`, or `dig` on your PATH,
+it will detect and use them as accelerators automatically.
+
+## Data sources
+
+**Keyless by default:** crt.sh (certificate transparency), DNS (A/NS/MX/SPF/DMARC/DKIM),
+HTTP probing, TLS/cert inspection, socket port scans.
+
+**Optional keyed enrichment** (set env vars to enable):
+
+| Source | Env vars |
+|---|---|
+| Shodan | `SHODAN_API_KEY` |
+| SecurityTrails | `SECURITYTRAILS_API_KEY` |
+| Censys | `CENSYS_API_ID`, `CENSYS_API_SECRET` |
+| urlscan.io | `URL_SCAN_API_KEY` |
+| URLhaus | `URLHAUS_API_KEY` |
+| VirusTotal | `VIRUSTOTAL_API_KEY` |
+
+## Commands
+
+```
+xwllz init <org> --domains d1,d2      define the scope to monitor
+xwllz discover <org>                  enumerate the attack surface
+xwllz monitor <org>                   re-scan and report new/changed/removed
+xwllz report <org> --format md|json|html
+xwllz status <org>                    current surface dashboard
+xwllz intel <indicator>               URL/domain/IP lookup
+xwllz whois <domain>                  whois lookup
+xwllz cert <host>                     TLS certificate details
+```
+
+Data is stored in SQLite at `~/.local/share/xwllz/xwllz.db`.
+
+## License
+
+MIT

xwllz-0.1.0/README.md

@@ -0,0 +1,56 @@
+# xwllz — Attack-surface management for blue teams
+
+`xwllz` is a CLI for discovering, monitoring, and reporting on your **own external
+attack surface**. It maps the domains, subdomains, IPs, services, certificates, and
+exposure points an attacker can reach — so blue teams can see their perimeter before
+attackers do.
+
+## Quickstart
+
+```bash
+pip install xwllz
+
+xwllz init acme --domains example.com,corp.example.com
+xwllz discover acme
+xwllz monitor acme        # re-scan and show what changed
+xwllz report acme --format md
+```
+
+No system binaries are required. `xwllz` is pure Python by default; if you have
+`nmap`, `masscan`, `rustscan`, `nuclei`, `httpx`, `dnsx`, or `dig` on your PATH,
+it will detect and use them as accelerators automatically.
+
+## Data sources
+
+**Keyless by default:** crt.sh (certificate transparency), DNS (A/NS/MX/SPF/DMARC/DKIM),
+HTTP probing, TLS/cert inspection, socket port scans.
+
+**Optional keyed enrichment** (set env vars to enable):
+
+| Source | Env vars |
+|---|---|
+| Shodan | `SHODAN_API_KEY` |
+| SecurityTrails | `SECURITYTRAILS_API_KEY` |
+| Censys | `CENSYS_API_ID`, `CENSYS_API_SECRET` |
+| urlscan.io | `URL_SCAN_API_KEY` |
+| URLhaus | `URLHAUS_API_KEY` |
+| VirusTotal | `VIRUSTOTAL_API_KEY` |
+
+## Commands
+
+```
+xwllz init <org> --domains d1,d2      define the scope to monitor
+xwllz discover <org>                  enumerate the attack surface
+xwllz monitor <org>                   re-scan and report new/changed/removed
+xwllz report <org> --format md|json|html
+xwllz status <org>                    current surface dashboard
+xwllz intel <indicator>               URL/domain/IP lookup
+xwllz whois <domain>                  whois lookup
+xwllz cert <host>                     TLS certificate details
+```
+
+Data is stored in SQLite at `~/.local/share/xwllz/xwllz.db`.
+
+## License
+
+MIT

xwllz-0.1.0/docs/superpowers/specs/2026-08-23-xwllz-cli-design.md

@@ -0,0 +1,126 @@
+# xwllz CLI — Design Spec
+
+Date: 2026-08-23
+Status: Approved (design approved by user; implementation complete)
+
+## Overview
+
+A new open-source Python CLI, **`xwllz`**, for **blue-team attack-surface
+management** (ASM): discover, monitor, and report on an organization's own
+external perimeter — domains, subdomains, IPs, services, certificates, and
+exposure points. It is a separate project/repo from the `xwllz` marketing site,
+built to be distributable via PyPI with zero required system binaries.
+
+## Goals
+
+- OSS-distributable ASM CLI: works on any machine with Python ≥3.10 only.
+- Keyless data sources by default; optional keyed API enrichment when the user
+  supplies keys.
+- Optional accelerators: detect installed binaries (nmap, masscan, rustscan,
+  nuclei, httpx, dnsx, dig) and use them when present, degrading gracefully to
+  pure-Python paths otherwise.
+- Full ASM loop: discover → store → monitor (diff) → report.
+
+## Non-goals
+
+- Real product copy/branding, docs site, multi-language support.
+- Cloud deployment, SaaS, API server.
+- Offensive/red-team functionality (this is a blue-team tool).
+
+## Architecture
+
+Approach A chosen (from brainstorm): **pure-Python core with optional tool
+accelerators and optional keyed APIs**.
+
+Repo: `/home/david/Documents/xwllz-cli` (package name `xwllz`, PyPI-distributable).
+
+### Dependencies (runtime)
+`typer` (CLI), `rich` (output), `httpx` (HTTP probing + API calls),
+`dnspython` (DNS), `cryptography` (TLS/cert parsing). No system binaries required.
+
+### Layout
+```
+src/xwllz/
+  cli.py          Typer app, all subcommands, rich output
+  db.py           SQLite schema + migrations + upsert helpers
+  config.py       env-key loading + PATH tool detection
+  discovery.py    ASM pipeline (gather→resolve→scan→probe→detect→store)
+  detectors.py    passive blue-team findings
+  report.py       markdown/JSON/HTML renderers
+  intel.py        indicator lookup logic (URLhaus/VT/Shodan/urlscan)
+  sources/crt_sh.py   keyless cert-transparency subdomain harvest
+  sources/keyed.py    Shodan, SecurityTrails, Censys, URLhaus, urlscan, VT
+  engines/dns.py      dnspython A/NS/MX/SPF/DMARC/DKIM
+  engines/ports.py    async socket port scanner (pure Python)
+  engines/http.py     httpx HTTP/HTTPS probing + tech detection
+  engines/tls.py      ssl + cryptography cert inspection
+  integrations/       optional nmap/nuclei/dnsx wrappers (auto-detect)
+tests/              mocked unit tests (no live calls)
+```
+
+### Storage
+SQLite at `~/.local/share/xwllz/xwllz.db` (XDG data dir). Schema:
+`orgs`, `assets`, `services`, `findings`, `snapshots`, `intel`.
+Findings dedupe on org+kind+asset+service+title with NULLs coerced to 0 via a
+partial unique index (SQLite NULL-distinct gotcha handled).
+
+## Data sources & tool selection (blue team)
+
+| Phase | Pure-Python default | Optional accelerator | Keyed enrichment |
+|---|---|---|---|
+| Subdomain enum | crt.sh CT + DNS | dnsx brute | SecurityTrails, Shodan, Censys |
+| DNS posture | dnspython (SPF/DMARC/DKIM) | dig | — |
+| Port/service scan | async socket scan | nmap, masscan, rustscan | Shodan host data |
+| HTTP fingerprint | httpx probe (title/headers/tech) | httpx bin, whatweb | — |
+| TLS/cert | ssl + cryptography (expiry, SAN) | openssl | Censys |
+| Exposure checks | passive rules | nuclei templates | — |
+| Threat intel | — | — | URLhaus, urlscan, VirusTotal |
+
+Blue-team differentiator: built-in **posture findings** — missing SPF/DMARC/DKIM,
+expiring/expired certs, missing security headers (HSTS/CSP/nosniff/clickjack),
+and exposed high-risk ports (RDP/SMB/FTP/DB listeners).
+
+## Command surface
+
+```
+xwllz init <org> --domains d1,d2
+xwllz discover <org> [--passive] [--ports N] [--no-nmap]
+xwllz monitor <org> [--passive]          # re-scan + snapshot diff
+xwllz report <org> --format md|json|html
+xwllz status <org>                       # surface dashboard
+xwllz intel <indicator>                  # URL/domain/IP lookup
+xwllz whois <domain>
+xwllz cert <host> [--port N]
+```
+
+## Error handling / resilience
+
+- Per-phase isolation: a failing phase never aborts the run (try/except +
+  `# noqa: BLE001, S112` documented).
+- Missing tool → silent fallback to pure-Python path; missing API key → source
+  skipped.
+- Network errors → caught, source returns None; DNS failures → empty result.
+- `KeyboardInterrupt` handled in `discover`/`monitor`.
+
+## Testing
+
+- `pytest` (29 tests): DB upsert/dedupe, detectors, report rendering, discovery
+  pipeline with all network functions mocked (no live calls), config/key/tool
+  detection.
+- `ruff` lint clean.
+- Live smoke test on a new keyless target (`example.com`, passive): crt.sh
+  harvest (800 subdomains), DNS resolution, SPF/DMARC findings — verified.
+- CI: GitHub Actions on 3.10/3.12/3.14 (`pytest`).
+
+## Verified behavior
+
+- `xwllz --help`, `init`, `status`, `report`, `discover --passive` all run.
+- Engines verified against a local HTTP service (port scan → probe → detectors).
+- Live passive discover on example.com produced SPF + DMARC findings.
+
+## Deferred
+
+- GitHub Actions PyPI publish (v1 later).
+- nuclei integration wiring into the findings pipeline (wrapper exists, not yet
+  invoked from `discover`).
+- HTTPS-on-nonstandard-port TLS probing (only 443/8443 currently).

xwllz-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xwllz"
+version = "0.1.0"
+description = "Attack-surface management for blue teams — discover, monitor, and report on your external perimeter."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["security", "blue-team", "asm", "attack-surface", "recon", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Information Technology",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+]
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.7",
+  "httpx>=0.27",
+  "dnspython>=2.6",
+  "cryptography>=42.0",
+]
+
+[project.scripts]
+xwllz = "xwllz.cli:app"
+
+[project.urls]
+Homepage = "https://xwllz.pages.dev"
+Repository = "https://github.com/stalane/xwllz-cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xwllz"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xwllz-0.1.0/src/xwllz/__init__.py

@@ -0,0 +1,3 @@
+"""xwllz — attack-surface management for blue teams."""
+
+__version__ = "0.1.0"

xwllz-0.1.0/src/xwllz/cli.py

@@ -0,0 +1,252 @@
+"""xwllz CLI — attack-surface management for blue teams."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from xwllz import db, discovery
+from xwllz import intel as intel_mod
+from xwllz import report as report_mod
+from xwllz.config import load_config
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="Attack-surface management for blue teams.")
+console = Console()
+
+DEFAULT_PORTS = "top-1000"
+
+
+@app.command()
+def init(
+    org: str = typer.Argument(..., help="Org/scope name"),
+    domains: str = typer.Option(..., "--domains", help="Comma-separated root domains"),
+    db_path: str = typer.Option(None, "--db", help="SQLite database path"),
+) -> None:
+    """Define a scope to monitor."""
+    conn = db.connect(db_path)
+    try:
+        conn.execute("INSERT INTO orgs (name, domains) VALUES (?, ?)", (org, domains))
+        conn.commit()
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(1)
+    console.print(f"[green]✓[/green] org [bold]{org}[/bold] set up for {domains}")
+    console.print(f"  next: [bold]xwllz discover {org}[/bold]")
+
+
+def _load_org(name: str, db_path: str | None):
+    conn = db.connect(db_path)
+    try:
+        org = discovery.load_org(conn, name)
+    except KeyError as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    return conn, org
+
+
+@app.command()
+def discover(
+    org: str = typer.Argument(...),
+    passive: bool = typer.Option(False, "--passive", help="Subdomains + DNS posture only, no port scanning"),
+    ports: str = typer.Option(DEFAULT_PORTS, "--ports", help="Port list for scanning (nmap format) or 'top-1000'"),
+    no_nmap: bool = typer.Option(False, "--no-nmap", help="Force pure-Python port scan"),
+    db_path: str = typer.Option(None, "--db"),
+) -> None:
+    """Enumerate an org's attack surface."""
+    conn, org_obj = _load_org(org, db_path)
+    cfg = load_config()
+    console.print(f"[bold]xwllz discover {org}[/bold] — passive={passive}")
+    port_list = None if ports == DEFAULT_PORTS else [int(p) for p in ports.split(",") if p]
+    try:
+        stats = asyncio.run(
+            discovery.run_discovery(
+                conn, org_obj, cfg, passive_only=passive, ports=port_list, use_nmap=not no_nmap
+            )
+        )
+    except KeyboardInterrupt:
+        console.print("\n[yellow]interrupted[/yellow]")
+        raise typer.Exit(130)
+    table = Table(title=f"{org} — discovery results")
+    table.add_column("Phase", style="cyan")
+    table.add_column("Count", justify="right")
+    table.add_row("subdomains", str(stats.subdomains))
+    table.add_row("hosts resolved", str(stats.hosts_resolved))
+    table.add_row("open ports", str(stats.open_ports))
+    table.add_row("services probed", str(stats.services_probed))
+    table.add_row("findings", str(stats.findings))
+    console.print(table)
+    console.print(f"next: [bold]xwllz monitor {org}[/bold] or [bold]xwllz report {org}[/bold]")
+
+
+@app.command()
+def monitor(
+    org: str = typer.Argument(...),
+    passive: bool = typer.Option(False, "--passive"),
+    ports: str = typer.Option(DEFAULT_PORTS, "--ports"),
+    db_path: str = typer.Option(None, "--db"),
+) -> None:
+    """Re-run discovery and show what changed since the last snapshot."""
+    conn, org_obj = _load_org(org, db_path)
+    cfg = load_config()
+    baseline = conn.execute(
+        "SELECT id FROM snapshots WHERE org_id = ? ORDER BY id DESC LIMIT 1",
+        (org_obj.id,),
+    ).fetchone()
+    console.print(f"[bold]xwllz monitor {org}[/bold]")
+    port_list = None if ports == DEFAULT_PORTS else [int(p) for p in ports.split(",") if p]
+    try:
+        stats = asyncio.run(discovery.run_discovery(conn, org_obj, cfg, passive_only=passive, ports=port_list))
+    except KeyboardInterrupt:
+        console.print("\n[yellow]interrupted[/yellow]")
+        raise typer.Exit(130)
+
+    if baseline is None:
+        console.print("[green]first snapshot taken[/green] — no baseline to diff against")
+    else:
+        diff = discovery.diff_snapshots(conn, org_obj, 0)
+        table = Table(title="delta vs previous snapshot")
+        table.add_column("Metric")
+        table.add_column("Before", justify="right")
+        table.add_column("After", justify="right")
+        table.add_column("Δ", justify="right")
+        for key, label in (("assets", "assets"), ("services", "services"), ("findings", "findings")):
+            prev_n = diff[key]["prev"]
+            new_n = diff[key]["new"]
+            delta = new_n - prev_n
+            color = "red" if delta > 0 else ("green" if delta < 0 else "white")
+            table.add_row(label, str(prev_n), str(new_n), f"[{color}]{delta:+d}[/{color}]")
+        console.print(table)
+    console.print(f"new findings recorded this run: [bold]{stats.findings}[/bold]")
+
+
+@app.command()
+def report(
+    org: str = typer.Argument(...),
+    format: str = typer.Option("md", "--format", "-f", help="md | json | html"),
+    output: str = typer.Option(None, "--output", "-o", help="Write to file instead of stdout"),
+    db_path: str = typer.Option(None, "--db"),
+) -> None:
+    """Render a report for an org."""
+    if format not in ("md", "json", "html"):
+        console.print(f"[red]unsupported format {format!r} (use md|json|html)[/red]")
+        raise typer.Exit(1)
+    conn = db.connect(db_path)
+    try:
+        body = report_mod.render(conn, org, format)
+    except KeyError as exc:
+        console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    if output:
+        with open(output, "w") as fh:
+            fh.write(body)
+        console.print(f"[green]✓[/green] wrote {output}")
+    else:
+        console.print(body)
+
+
+@app.command()
+def status(
+    org: str = typer.Argument(...),
+    db_path: str = typer.Option(None, "--db"),
+) -> None:
+    """Show the current surface dashboard for an org."""
+    conn, org_obj = _load_org(org, db_path)
+    counts = conn.execute(
+        """SELECT
+             (SELECT COUNT(*) FROM assets WHERE org_id = ? AND status='active'),
+             (SELECT COUNT(*) FROM services s JOIN assets a ON s.asset_id=a.id
+                 WHERE a.org_id=? AND a.status='active'),
+             (SELECT COUNT(*) FROM findings WHERE org_id = ?)""",
+        (org_obj.id, org_obj.id, org_obj.id),
+    ).fetchone()
+    table = Table(title=f"{org} — current surface")
+    table.add_column("Metric")
+    table.add_column("Value", justify="right")
+    table.add_row("active assets", str(counts[0]))
+    table.add_row("live services", str(counts[1]))
+    table.add_row("open findings", str(counts[2]))
+    console.print(table)
+
+    top = conn.execute(
+        """SELECT severity, COUNT(*) n FROM findings WHERE org_id=? GROUP BY severity
+           ORDER BY CASE severity WHEN 'high' THEN 0 WHEN 'medium' THEN 1 WHEN 'low' THEN 2 ELSE 3 END""",
+        (org_obj.id,),
+    ).fetchall()
+    if top:
+        t = Table(title="findings by severity")
+        t.add_column("Severity")
+        t.add_column("Count", justify="right")
+        for row in top:
+            t.add_row(row["severity"], str(row["n"]))
+        console.print(t)
+
+
+@app.command()
+def intel(
+    indicator: str = typer.Argument(...),
+    db_path: str = typer.Option(None, "--db"),
+) -> None:
+    """Look up a URL/domain/IP across enabled intel sources."""
+    cfg = load_config()
+    conn = db.connect(db_path) if db_path else None
+    results = asyncio.run(intel_mod.run_lookup(indicator, cfg, conn))
+    if not results:
+        console.print("[yellow]no sources enabled — set SHODAN_API_KEY / VIRUSTOTAL_API_KEY / URLHAUS_API_KEY[/yellow]")
+        return
+    for source, payload in results.items():
+        console.print(f"[bold cyan]{source}:[/bold cyan]")
+        if source == "urlhaus":
+            status = (payload.get("data") or {}).get("query_status")
+            console.print(f"  query_status: {status}")
+            for url in (payload.get("data") or {}).get("urls", [])[:5]:
+                console.print(f"  - {url.get('url')} [{url.get('threat')}]")
+        elif source == "virustotal":
+            console.print(f"  stats: {payload['stats']}")
+        elif source == "shodan":
+            console.print(f"  ports: {payload['ports']}  org: {payload['org']}")
+
+
+@app.command()
+def whois(
+    domain: str = typer.Argument(...),
+) -> None:
+    """Look up whois for a domain (requires 'whois')."""
+    try:
+        out = subprocess.run(["whois", domain], capture_output=True, text=True, timeout=30, check=False)
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        console.print(f"[red]whois unavailable:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print(out.stdout)
+
+
+@app.command()
+def cert(
+    host: str = typer.Argument(...),
+    port: int = typer.Option(443, "--port"),
+) -> None:
+    """Show TLS certificate details for a host."""
+    from xwllz.engines.tls import fetch_cert
+
+    result = asyncio.run(fetch_cert(host, port))
+    if result.error:
+        console.print(f"[red]error:[/red] {result.error}")
+        raise typer.Exit(1)
+    console.print(f"host:    {result.host}")
+    console.print(f"subject: CN={result.cn}")
+    console.print(f"issuer:  {result.issuer}")
+    console.print(f"expires: {result.not_after} ({result.days_left} days)")
+    if result.san:
+        console.print(f"sans:    {', '.join(result.san[:8])}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xwllz-0.1.0/src/xwllz/config.py

@@ -0,0 +1,56 @@
+"""Configuration: API keys from env vars, optional tool detection on PATH."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass, field
+
+ENV_KEYS: dict[str, str] = {
+    "shodan": "SHODAN_API_KEY",
+    "securitytrails": "SECURITYTRAILS_API_KEY",
+    "censys": "CENSYS_API_ID",
+    "censys_secret": "CENSYS_API_SECRET",
+    "urlscan": "URL_SCAN_API_KEY",
+    "urlhaus": "URLHAUS_API_KEY",
+    "virustotal": "VIRUSTOTAL_API_KEY",
+}
+
+# Optional binaries that accelerate phases when present.
+TOOLS: list[str] = [
+    "nmap",
+    "masscan",
+    "rustscan",
+    "nuclei",
+    "httpx",
+    "dnsx",
+    "dig",
+    "whatweb",
+    "openssl",
+]
+
+
+@dataclass
+class Config:
+    """Resolved runtime configuration."""
+
+    keys: dict[str, str | None] = field(default_factory=dict)
+    tools: dict[str, str | None] = field(default_factory=dict)
+    http_timeout: float = 8.0
+    dns_timeout: float = 5.0
+    port_scan_concurrency: int = 256
+    max_workers: int = 32
+
+    def has(self, name: str) -> bool:
+        return bool(self.keys.get(name))
+
+    def tool(self, name: str) -> str | None:
+        """Path to an optional tool, or None if not installed."""
+        return self.tools.get(name)
+
+
+def load_config() -> Config:
+    cfg = Config()
+    cfg.keys = {name: os.getenv(var) or None for name, var in ENV_KEYS.items()}
+    cfg.tools = {name: shutil.which(name) for name in TOOLS}
+    return cfg