huntkit 0.3.0__py3-none-any.whl

huntkit/shots/runner.py

@@ -0,0 +1,186 @@
+r"""Screenshots — capture a visual of every live URL for triage and the report.
+
+A wall of screenshots is how a hunter eyeballs a large surface fast: default
+landing pages, login portals, stack-trace error screens, and abandoned admin
+panels all jump out of a grid in a way a list of URLs never does. This layer
+drives a headless screenshotter (``gowitness`` by default) over the live URLs
+recon gathered and records a manifest the report turns into a gallery.
+
+It follows the scanner's shape: targets are read from the workspace's own,
+already scope-filtered result files *and* re-checked against scope here, so the
+camera never points at a host recon would have refused. The actual capture is
+injected (``CaptureFn``) so the orchestration — target collection, the
+manifest, scope enforcement — is tested without a browser or ``gowitness`` on
+the box.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from ..core.config import Config
+from ..core.runner import CommandRunner
+from ..core.workspace import Workspace
+
+# Where captures land (under reports/ so a self-contained report can embed
+# them) and where the manifest is written.
+SHOTS_DIR = "reports/shots"
+SHOTS_JSON = "scans/screenshots.json"
+SHOTS_STATE = "shots"
+TARGET_FILES = ["recon/live.txt", "urls/urls.txt"]
+
+# A capture backend: given the URLs and an output directory, take the shots and
+# return a mapping of url -> produced image filename (basename within the dir).
+# Any URL left out of the mapping is reported as not captured.
+CaptureFn = Callable[[list[str], Path], dict[str, str]]
+
+EventFn = Callable[[dict], None]
+
+
+@dataclass
+class Shot:
+    url: str
+    file: str = ""  # path relative to the workspace root, or "" if not captured
+    error: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.file)
+
+    def to_dict(self) -> dict:
+        return {"url": self.url, "file": self.file, "error": self.error}
+
+
+@dataclass
+class ShotSummary:
+    program: str
+    targets: int = 0
+    shots: list[Shot] = field(default_factory=list)
+
+    @property
+    def captured(self) -> int:
+        return sum(1 for s in self.shots if s.ok)
+
+
+def shot_targets(ws: Workspace) -> list[str]:
+    """Candidate URLs from the workspace, deduped and scope-checked."""
+    seen: dict[str, None] = {}
+    for rel in TARGET_FILES:
+        for url in ws.read_lines(rel):
+            host = _host_of(url)
+            if host and ws.in_scope(host):
+                seen[url] = None
+    return sorted(seen)
+
+
+def _host_of(url: str) -> Optional[str]:
+    parsed = urlparse(url if "://" in url else f"//{url}", scheme="http")
+    return parsed.hostname
+
+
+def run_shots(
+    ws: Workspace,
+    config: Config,
+    *,
+    runner: Optional[CommandRunner] = None,
+    capture: Optional[CaptureFn] = None,
+    on_event: Optional[EventFn] = None,
+) -> ShotSummary:
+    """Capture the live URLs and write ``scans/screenshots.json``."""
+    emit: EventFn = on_event or (lambda _e: None)
+    runner = runner or CommandRunner(config)
+    capture = capture or gowitness_capture(runner)
+
+    targets = shot_targets(ws)
+    summary = ShotSummary(program=ws.program, targets=len(targets))
+    ws.state.start(SHOTS_STATE)
+    emit({"event": "shots_start", "targets": len(targets)})
+
+    if not targets:
+        ws.state.skip(SHOTS_STATE)
+        emit({"event": "shots_done", "captured": 0})
+        return summary
+
+    outdir = Path(ws.path(SHOTS_DIR))
+    outdir.mkdir(parents=True, exist_ok=True)
+    try:
+        produced = capture(targets, outdir)
+    except Exception as exc:  # noqa: BLE001 — a backend crash is recorded, not raised
+        ws.state.skip(SHOTS_STATE)
+        emit({"event": "shots_error", "reason": str(exc) or type(exc).__name__})
+        return summary
+
+    for url in targets:
+        name = produced.get(url)
+        if name:
+            summary.shots.append(Shot(url=url, file=f"{SHOTS_DIR}/{name}"))
+        else:
+            summary.shots.append(Shot(url=url, error="not captured"))
+
+    _persist(ws, summary)
+    ws.state.done(SHOTS_STATE, targets=len(targets), captured=summary.captured)
+    emit({"event": "shots_done", "captured": summary.captured})
+    return summary
+
+
+def _persist(ws: Workspace, summary: ShotSummary) -> None:
+    payload = {
+        "program": summary.program,
+        "generated": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "dir": SHOTS_DIR,
+        "shots": [s.to_dict() for s in summary.shots if s.ok],
+    }
+    ws.path(SHOTS_JSON).write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def gowitness_capture(runner: CommandRunner) -> CaptureFn:
+    """A :data:`CaptureFn` backed by ``gowitness`` (best-effort, version-tolerant).
+
+    gowitness is driven over a URL list into ``outdir``; afterwards the
+    directory is scanned for the images it produced and each is paired with the
+    URL whose host appears in its filename, falling back to positional order
+    when the counts line up. The whole capture is skipped cleanly when the
+    binary is absent, so a box without gowitness still runs the rest of HuntKit.
+    """
+
+    def capture(urls: list[str], outdir: Path) -> dict[str, str]:  # pragma: no cover
+        if not runner.available("gowitness"):
+            return {}
+        listing = outdir / "_targets.txt"
+        listing.write_text("\n".join(urls) + "\n", encoding="utf-8")
+        # gowitness v3: `scan file -f <list> -s <screenshot-dir> --write-none`
+        runner.run(
+            "gowitness",
+            ["scan", "file", "-f", str(listing), "-s", str(outdir), "--write-none"],
+        )
+        return _pair_images(urls, outdir)
+
+    return capture
+
+
+def _pair_images(urls: list[str], outdir: Path) -> dict[str, str]:  # pragma: no cover
+    """Pair produced image files to the URLs that made them (best effort)."""
+    images = sorted(
+        (p for p in outdir.iterdir() if p.suffix.lower() in (".png", ".jpeg", ".jpg")),
+        key=lambda p: p.stat().st_mtime,
+    )
+    names = [p.name for p in images]
+    out: dict[str, str] = {}
+    unmatched = list(names)
+    for url in urls:
+        host = _host_of(url) or ""
+        hit = next((n for n in unmatched if host and host.replace(".", "-") in n), None)
+        hit = hit or next((n for n in unmatched if host and host in n), None)
+        if hit:
+            out[url] = hit
+            unmatched.remove(hit)
+    # positional fallback only when nothing matched by name but counts align
+    if not out and len(names) == len(urls):
+        out = dict(zip(urls, names, strict=True))
+    return out

huntkit/tui/__init__.py

@@ -0,0 +1,13 @@
+"""Terminal UI layer — a one-screen engagement dashboard.
+
+Built on Rich (already a runtime dependency); no TUI framework is added.
+:func:`render_dashboard` is a pure function returning a Rich renderable, so the
+view is unit-tested by rendering to a recording console and the live ``--watch``
+loop is a thin wrapper around it.
+"""
+
+from __future__ import annotations
+
+from .dashboard import render_dashboard
+
+__all__ = ["render_dashboard"]

huntkit/tui/dashboard.py

@@ -0,0 +1,160 @@
+"""A one-screen engagement dashboard, composed from what a workspace holds.
+
+`huntkit dashboard -p <prog>` paints the whole picture on a single screen —
+priority breakdown, recon surface, the top scored hosts and attack paths, the
+notable exposures, enrichment highlights, and when the surface last changed.
+With ``--watch`` it redraws on an interval, so a long recon in one terminal can
+be watched live in another.
+
+Built entirely on Rich (already a runtime dependency) — no TUI framework is
+added. :func:`render_dashboard` is a pure function returning a Rich renderable,
+so it is unit-tested by rendering to a recording console, and the live loop
+stays a thin wrapper around it.
+"""
+
+from __future__ import annotations
+
+import json
+
+from rich import box
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from ..core.workspace import Workspace
+from ..history import latest
+from ..intel import Priority
+from ..report import build as report_build
+from ..report.builder import Report
+from ..utils.severity import Severity
+
+_ENRICH_JSON = "scans/enrich.json"
+
+
+def _header(report: Report) -> Panel:
+    body = Text()
+    body.append(report.program, style="bold cyan")
+    scope = ", ".join(report.scope_in) or "—"
+    body.append(f"\nin scope: {scope}", style="dim")
+    if report.scope_out:
+        body.append(f"\nout of scope: {', '.join(report.scope_out)}", style="dim")
+    return Panel(body, title="HuntKit", title_align="left", box=box.ROUNDED)
+
+
+def _priority_bar(report: Report) -> Panel:
+    t = Table.grid(expand=True, padding=(0, 2))
+    labels = [p.label for p in sorted(Priority, reverse=True)]
+    for _ in labels:
+        t.add_column(justify="center", ratio=1)
+    counts = report.intel.summary
+    t.add_row(*[Text(str(counts.get(lbl, 0)), style=f"bold {lbl}") for lbl in labels])
+    t.add_row(*[Text(lbl, style="dim") for lbl in labels])
+    sig = len(report.intel.signals)
+    hosts = len(report.intel.hosts)
+    return Panel(t, title=f"priority · {sig} signals / {hosts} hosts", title_align="left")
+
+
+def _recon_bar(report: Report) -> Panel:
+    t = Table.grid(expand=True, padding=(0, 2))
+    items = list(report.recon.items())
+    for _ in items:
+        t.add_column(justify="center", ratio=1)
+    t.add_row(*[Text(str(n), style="bold") for _, n in items])
+    t.add_row(*[Text(label, style="dim") for label, _ in items])
+    return Panel(t, title="recon surface", title_align="left")
+
+
+def _hosts_table(report: Report, top: int) -> Table:
+    t = Table(title="top hosts", title_justify="left", box=box.SIMPLE, expand=True)
+    t.add_column("host", overflow="fold")
+    t.add_column("pri")
+    t.add_column("score", justify="right")
+    t.add_column("sig", justify="right")
+    t.add_column("playbooks", overflow="fold")
+    for h in report.intel.hosts[:top]:
+        t.add_row(
+            h.host,
+            Text(h.priority.label, style=h.priority.style),
+            str(h.score),
+            str(len(h.signals)),
+            ", ".join(h.playbooks[:3]) or "—",
+        )
+    return t
+
+
+def _paths_table(report: Report, top: int) -> Table:
+    t = Table(title="attack paths", title_justify="left", box=box.SIMPLE, expand=True)
+    t.add_column("playbook", overflow="fold")
+    t.add_column("sev")
+    t.add_column("hosts", justify="right")
+    for p in report.intel.attack_paths()[:top]:
+        t.add_row(p.name, Text(p.severity.label, style=p.severity.style), str(len(p.hosts)))
+    return t
+
+
+def _notable_table(report: Report, top: int) -> Table:
+    t = Table(title="notable exposures", title_justify="left", box=box.SIMPLE, expand=True)
+    t.add_column("sev")
+    t.add_column("host", overflow="fold")
+    t.add_column("finding", overflow="fold")
+    hot = sorted(
+        (s for s in report.intel.signals if int(s.severity) >= Severity.HIGH),
+        key=lambda s: (-int(s.severity), s.host),
+    )
+    for s in hot[:top]:
+        t.add_row(Text(s.severity.label, style=s.severity.style), s.host, s.title)
+    return t
+
+
+def _enrich_panel(ws: Workspace) -> Panel | None:
+    path = ws.path(_ENRICH_JSON)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return None
+    favs = [f for f in data.get("favicons", []) if f.get("hash") is not None]
+    asns = [a for a in data.get("asns", []) if a.get("asn")]
+    if not favs and not asns:
+        return None
+    body = Text()
+    body.append(f"favicons hashed: {len(favs)}\n", style="bold")
+    unique_asns = sorted({a["asn"] for a in asns}, key=lambda s: int(s)) if asns else []
+    body.append(f"ASNs: {len(asns)} host(s) across {len(unique_asns)} network(s)", style="bold")
+    if unique_asns:
+        body.append("  " + ", ".join(f"AS{a}" for a in unique_asns[:8]), style="dim")
+    return Panel(body, title="enrichment", title_align="left")
+
+
+def _snapshot_line(ws: Workspace) -> Text:
+    snap = latest(ws)
+    if snap is None:
+        return Text("no snapshot yet — `huntkit diff --save` to set a baseline", style="dim")
+    return Text(
+        f"last snapshot {snap.id} · live {snap.counts['live']} · "
+        f"urls {snap.counts['urls']} · findings {snap.counts['findings']}",
+        style="dim",
+    )
+
+
+def render_dashboard(ws: Workspace, *, top: int = 10) -> RenderableType:
+    """Compose the one-screen dashboard for a workspace (pure; no I/O beyond reads)."""
+    report = report_build(ws)
+    parts: list[RenderableType] = [
+        _header(report),
+        _priority_bar(report),
+        _recon_bar(report),
+    ]
+    if report.intel.hosts:
+        parts.append(_hosts_table(report, top))
+    if report.intel.attack_paths():
+        parts.append(_paths_table(report, top))
+    if any(int(s.severity) >= Severity.HIGH for s in report.intel.signals):
+        parts.append(_notable_table(report, top))
+    enrich = _enrich_panel(ws)
+    if enrich is not None:
+        parts.append(enrich)
+    parts.append(_snapshot_line(ws))
+    return Group(*parts)

huntkit/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Low-level, dependency-light helpers shared across HuntKit.
+
+Nothing in `utils` may import from `huntkit.core`, `huntkit.recon`, etc. —
+it is the bottom of the dependency graph so it can be reused everywhere
+without cycles.
+"""

huntkit/utils/filesystem.py

@@ -0,0 +1,109 @@
+"""Filesystem helpers: atomic writes, deduped line sets, safe joins.
+
+All text I/O is UTF-8 with newline normalisation so results are identical on
+Windows and Linux (the original tool produced cp1252 mojibake on Windows).
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from collections.abc import Iterable
+from pathlib import Path
+
+ENCODING = "utf-8"
+
+
+def _replace_with_retry(src: str, dst: Path, attempts: int = 5) -> None:
+    """os.replace, retrying transient Windows locks.
+
+    On Windows an antivirus/indexer can briefly hold a freshly written file
+    open, making os.replace fail with PermissionError (WinError 5) even in a
+    single-threaded run. A few short retries make atomic writes reliable.
+    """
+    for i in range(attempts):
+        try:
+            os.replace(src, dst)
+            return
+        except PermissionError:
+            if i == attempts - 1:
+                raise
+            time.sleep(0.05 * (i + 1))
+
+
+def ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def read_text(path: Path, default: str = "") -> str:
+    if not path.exists():
+        return default
+    return path.read_text(encoding=ENCODING)
+
+
+def write_text(path: Path, data: str) -> None:
+    """Atomically write text: write to a temp file, then replace.
+
+    Prevents half-written files if the process is interrupted mid-write —
+    important for state.json and long result sets.
+    """
+    ensure_dir(path.parent)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding=ENCODING, newline="\n") as fh:
+            fh.write(data)
+        _replace_with_retry(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            try:
+                os.unlink(tmp)
+            except OSError:  # pragma: no cover - best-effort cleanup
+                pass
+
+
+def read_lines(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    return [ln.strip() for ln in read_text(path).splitlines() if ln.strip()]
+
+
+def append_unique(path: Path, items: Iterable[str]) -> int:
+    """Merge items into a sorted, unique line file. Returns count of new lines.
+
+    This is the `anew`-style primitive the whole recon pipeline relies on to
+    never store the same asset twice.
+    """
+    incoming = {i.strip() for i in items if i and i.strip()}
+    if not incoming and not path.exists():
+        return 0
+    existing = set(read_lines(path))
+    new = incoming - existing
+    if not new and path.exists():
+        return 0
+    merged = sorted(existing | incoming)
+    write_text(path, "\n".join(merged) + ("\n" if merged else ""))
+    return len(new)
+
+
+def count_lines(path: Path) -> int:
+    return len(read_lines(path))
+
+
+def safe_join(base: Path, *parts: str) -> Path:
+    """Join under `base`, refusing any result that escapes it (traversal guard)."""
+    base = base.resolve()
+    target = base.joinpath(*parts).resolve()
+    if base != target and base not in target.parents:
+        raise ValueError(f"path escapes workspace: {target}")
+    return target
+
+
+def human_size(num_bytes: int) -> str:
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            return f"{size:.0f}{unit}" if unit == "B" else f"{size:.1f}{unit}"
+        size /= 1024
+    return f"{size:.1f}TB"

huntkit/utils/process.py

@@ -0,0 +1,104 @@
+"""Low-level subprocess execution.
+
+A single, safe choke-point for running external binaries. Everything is
+passed as an argv list (never a shell string) so there is no shell-injection
+surface, even though HuntKit forwards user-controlled domains to tools.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ProcResult:
+    """Outcome of a single command execution."""
+
+    code: int
+    stdout: str
+    stderr: str
+    argv: list[str]
+    duration: float = 0.0
+    timed_out: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return self.code == 0
+
+    @property
+    def lines(self) -> list[str]:
+        return [ln for ln in self.stdout.splitlines() if ln.strip()]
+
+    def __bool__(self) -> bool:  # allow `if result:`
+        return self.ok
+
+
+# Sentinels for failures that never reached the binary.
+NOT_FOUND = 127
+TIMEOUT = 124
+
+
+def which(binary: str) -> Optional[str]:
+    return shutil.which(binary)
+
+
+def execute(
+    argv: Sequence[str],
+    *,
+    timeout: Optional[int] = None,
+    stdin_data: Optional[str] = None,
+    env: Optional[dict] = None,
+    cwd: Optional[str] = None,
+) -> ProcResult:
+    """Run `argv`, capture output, and never raise on tool failure.
+
+    Recon tooling routinely exits non-zero (empty source, no results); that
+    is data, not an error, so we surface the code and let callers decide.
+    """
+    import time
+
+    argv = [str(a) for a in argv]
+    started = time.monotonic()
+    try:
+        proc = subprocess.run(
+            argv,
+            input=stdin_data,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        return ProcResult(
+            NOT_FOUND, "", f"binary not found: {argv[0]}", argv, duration=time.monotonic() - started
+        )
+    except subprocess.TimeoutExpired as exc:
+        partial = _decode(exc.stdout)
+        return ProcResult(
+            TIMEOUT,
+            partial,
+            f"timeout after {timeout}s",
+            argv,
+            duration=time.monotonic() - started,
+            timed_out=True,
+        )
+    return ProcResult(
+        proc.returncode,
+        proc.stdout,
+        proc.stderr,
+        argv,
+        duration=time.monotonic() - started,
+    )
+
+
+def _decode(data) -> str:
+    if data is None:
+        return ""
+    if isinstance(data, bytes):
+        return data.decode(errors="replace")
+    return str(data)

huntkit/utils/severity.py

@@ -0,0 +1,49 @@
+"""Shared severity vocabulary.
+
+One ordered :class:`Severity` enum for the whole framework: the intelligence
+engine scores with it, the knowledge base tags playbooks with it, and the
+reporter (phase 7) renders with it. It lives in ``utils`` — the bottom of the
+dependency graph — so every feature layer shares one definition instead of
+each redefining severity and drifting apart.
+
+``.label`` / ``.style`` map straight onto the Rich theme keys in
+:mod:`huntkit.utils.terminal`, so a severity colours itself consistently
+wherever it is printed.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    """Ordered so signals can be compared and aggregated numerically."""
+
+    INFO = 1
+    LOW = 2
+    MEDIUM = 3
+    HIGH = 4
+    CRITICAL = 5
+
+    @property
+    def label(self) -> str:
+        return "informational" if self is Severity.INFO else self.name.lower()
+
+    @property
+    def style(self) -> str:  # matches the theme keys in utils.terminal
+        return self.label
+
+    @classmethod
+    def from_name(cls, name: str) -> Severity:
+        """Parse a label back into a Severity ('informational'/'info' -> INFO).
+
+        The inverse of :attr:`label`, so severities that were serialised to
+        JSON (e.g. scans/intel.json) can be read back as ordered enums.
+        """
+        key = name.strip().lower()
+        if key in ("info", "informational"):
+            return cls.INFO
+        try:
+            return cls[key.upper()]
+        except KeyError:
+            raise ValueError(f"unknown severity: {name!r}") from None