huntkit 0.3.0__py3-none-any.whl

huntkit/app/plugins_cmd.py

@@ -0,0 +1,79 @@
+"""`huntkit plugins` — browse the tool plugins HuntKit can drive."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..plugins import Category
+from ..utils import terminal as term
+
+plugins_app = typer.Typer(no_args_is_help=True, help="Browse and inspect tool plugins.")
+
+
+def _status(available: bool) -> str:
+    return "[ok]installed[/ok]" if available else "[muted]missing[/muted]"
+
+
+@plugins_app.command("list")
+def plugins_list(
+    ctx: typer.Context,
+    category: Optional[str] = typer.Option(
+        None, "--category", "-c", help="Filter by category (discovery/resolve/ports/urls/scan)."
+    ),
+    available_only: bool = typer.Option(
+        False, "--available", "-a", help="Show only installed tools."
+    ),
+) -> None:
+    """List plugins, their capability chain, and install status."""
+    app_ctx = ctx.obj
+    registry, runner = app_ctx.registry, app_ctx.runner
+
+    plugins = registry.all()
+    if category:
+        try:
+            plugins = registry.by_category(Category(category))
+        except ValueError:
+            term.error(f"unknown category: {category}")
+            raise typer.Exit(2) from None
+    if available_only:
+        plugins = [p for p in plugins if p.is_available(runner)]
+
+    table = term.make_table("Plugins", ["tool", "category", "consumes", "produces", "status"])
+    for p in plugins:
+        table.add_row(
+            p.name,
+            p.category.value,
+            p.consumes.value if p.consumes else "-",
+            p.produces.value,
+            _status(p.is_available(runner)),
+        )
+    term.console.print(table)
+    installed = len(registry.available(runner))
+    term.info(f"{installed}/{len(registry)} tools installed.")
+
+
+@plugins_app.command("show")
+def plugins_show(ctx: typer.Context, name: str = typer.Argument(..., help="Plugin name.")) -> None:
+    """Show one plugin's metadata and how to install it."""
+    app_ctx = ctx.obj
+    plugin = app_ctx.registry.get(name)
+    if plugin is None:
+        term.error(f"no such plugin: {name}")
+        raise typer.Exit(2)
+    available = plugin.is_available(app_ctx.runner)
+    rows = [
+        ("name", plugin.name),
+        ("category", plugin.category.value),
+        ("description", plugin.description or "-"),
+        ("consumes", plugin.consumes.value if plugin.consumes else "-"),
+        ("produces", plugin.produces.value),
+        ("input mode", plugin.input_mode.value),
+        ("status", "installed" if available else "missing"),
+    ]
+    if plugin.needs_api_key:
+        rows.append(("api key", plugin.needs_api_key))
+    if not available:
+        rows.append(("install", plugin.install))
+    term.print_table(f"plugin: {plugin.name}", ["field", "value"], rows)

huntkit/app/workspace_cmd.py

@@ -0,0 +1,62 @@
+"""`huntkit workspace` — list and inspect engagement workspaces."""
+
+from __future__ import annotations
+
+import typer
+
+from ..core.workspace import Workspace, default_base, list_workspaces
+from ..utils import terminal as term
+
+workspace_app = typer.Typer(no_args_is_help=True, help="List and inspect workspaces.")
+
+
+@workspace_app.command("list")
+def workspace_list(ctx: typer.Context) -> None:
+    """List every workspace under the workspace root."""
+    app_ctx = ctx.obj
+    base = app_ctx.base or default_base(app_ctx.config)
+    names = list_workspaces(base=base)
+    if not names:
+        term.warn(f"no workspaces yet under {base}")
+        term.info("create one with:  huntkit init <program> -s <domain>")
+        return
+    rows = []
+    for name in names:
+        ws = Workspace.open(name, config=app_ctx.config, base=app_ctx.base)
+        subs = ws.count("recon/subdomains.txt")
+        live = ws.count("recon/live.txt")
+        rows.append((name, str(subs), str(live), str(len(ws.scope_in))))
+    term.print_table(f"Workspaces ({base})", ["program", "subs", "live", "scope"], rows)
+
+
+@workspace_app.command("show")
+def workspace_show(
+    ctx: typer.Context,
+    program: str = typer.Argument(..., help="Workspace / program name."),
+) -> None:
+    """Show scope, counts, and stage status for one workspace."""
+    app_ctx = ctx.obj
+    ws = Workspace.open(program, config=app_ctx.config, base=app_ctx.base)
+    if not ws.has_scope() and not ws.state.counts:
+        term.warn(f"workspace '{program}' looks empty ({ws.root})")
+
+    term.banner(f"workspace: {program}")
+    term.info(f"path: {ws.root}")
+
+    scope_in = ws.scope_in or ["(none — everything in scope)"]
+    term.step("Scope")
+    for entry in scope_in:
+        term.bullet(entry, style="ok")
+    for entry in ws.scope_out:
+        term.bullet(f"{entry}  (excluded)", style="warn")
+
+    if ws.state.counts:
+        term.print_table(
+            "Assets", ["metric", "count"], [(k, str(v)) for k, v in ws.state.counts.items()]
+        )
+    if ws.state.stages:
+        rows = []
+        for name, rec in ws.state.stages.items():
+            dur = f"{rec.duration:.1f}s" if rec.duration else "-"
+            rows.append((name, rec.status.value, dur))
+        term.print_table("Stages", ["stage", "status", "time"], rows)

huntkit/core/__init__.py

@@ -0,0 +1,6 @@
+"""HuntKit core: configuration, logging, execution, cache, and state.
+
+The core layer sits above `utils` and below the feature packages (recon,
+scanners, intelligence, reporting, ai). Feature code depends on core; core
+never depends on feature code.
+"""

huntkit/core/cache.py

@@ -0,0 +1,67 @@
+"""Content-addressed result cache.
+
+Skips re-running an expensive tool when the same command + input has already
+produced output within a TTL. Keys are hashes so the same passive enumeration
+isn't repeated across runs of a workspace. Entirely local; lives in the
+workspace `cache/` directory.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+from ..utils import filesystem as fs
+
+
+def make_key(*parts: str) -> str:
+    """Stable cache key from arbitrary string parts (tool, args, stdin)."""
+    digest = hashlib.sha256("\x00".join(parts).encode("utf-8")).hexdigest()
+    return digest[:32]
+
+
+class Cache:
+    def __init__(self, root: Path, ttl_seconds: int = 86_400, enabled: bool = True) -> None:
+        self.root = root
+        self.ttl = ttl_seconds
+        self.enabled = enabled
+
+    def _path(self, key: str) -> Path:
+        return self.root / f"{key}.json"
+
+    def get(self, key: str) -> Optional[str]:
+        if not self.enabled:
+            return None
+        path = self._path(key)
+        if not path.exists():
+            return None
+        try:
+            record = json.loads(fs.read_text(path))
+        except (json.JSONDecodeError, OSError):
+            return None
+        if self.ttl and time.time() - record.get("ts", 0) > self.ttl:
+            return None
+        return record.get("value")
+
+    def set(self, key: str, value: str) -> None:
+        if not self.enabled:
+            return
+        fs.ensure_dir(self.root)
+        fs.write_text(self._path(key), json.dumps({"ts": time.time(), "value": value}))
+
+    def invalidate(self, key: str) -> None:
+        path = self._path(key)
+        if path.exists():
+            path.unlink()
+
+    def clear(self) -> int:
+        if not self.root.exists():
+            return 0
+        removed = 0
+        for f in self.root.glob("*.json"):
+            f.unlink()
+            removed += 1
+        return removed

huntkit/core/config.py

@@ -0,0 +1,272 @@
+"""Layered YAML configuration.
+
+Resolution order (later wins):
+  1. built-in defaults (this module)
+  2. user config      ~/.config/huntkit/huntkit.yaml   (or $HUNTKIT_CONFIG_HOME)
+  3. project config    ./huntkit.yaml                   (cwd, walked upward)
+  4. explicit --config path
+  5. environment       HUNTKIT_<SECTION>_<KEY>
+
+Everything is typed via dataclasses so the rest of the codebase gets
+autocomplete and mypy checking instead of dictionary spelunking.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+CONFIG_FILENAME = "huntkit.yaml"
+
+
+# --------------------------------------------------------------------------
+# Typed sections
+# --------------------------------------------------------------------------
+@dataclass
+class GeneralConfig:
+    workspace_path: str = "~/.huntkit"
+    threads: int = 20
+    rate: int = 150  # requests/sec hint passed to rate-aware tools
+    timeout: int = 300  # per-command seconds
+    retry: int = 1  # retries on transient failure
+    default_report_format: str = "markdown"
+    color: bool = True
+
+
+@dataclass
+class HttpConfig:
+    proxy: Optional[str] = None  # e.g. http://127.0.0.1:8080 (Burp)
+    user_agent: str = "HuntKit/0.2 (+https://github.com/Raresney/HuntKit)"
+    headers: dict[str, str] = field(default_factory=dict)
+    rate_limit: int = 150  # HTTP requests/sec hint passed to rate-aware tools
+    delay: float = 0.0  # seconds between requests for tools that support it
+    follow_redirects: bool = True
+
+
+@dataclass
+class ToolConfig:
+    """Per-tool overrides. `path` pins a binary; `extra_args` is appended."""
+
+    enabled: bool = True
+    path: Optional[str] = None
+    extra_args: list[str] = field(default_factory=list)
+    timeout: Optional[int] = None
+
+
+@dataclass
+class WordlistConfig:
+    dir_fuzz: Optional[str] = None
+    dns: Optional[str] = None
+    params: Optional[str] = None
+
+
+@dataclass
+class NucleiConfig:
+    templates: Optional[str] = None  # custom template dir
+    severity: str = "low,medium,high,critical"
+    extra_args: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AIConfig:
+    provider: str = "ollama"  # ollama|openai|claude|gemini
+    model: str = "llama3.2"
+    endpoint: str = "http://127.0.0.1:11434"
+    require_approval: bool = True  # never send engagement data silently
+    max_context_items: int = 40
+
+
+@dataclass
+class Config:
+    general: GeneralConfig = field(default_factory=GeneralConfig)
+    http: HttpConfig = field(default_factory=HttpConfig)
+    wordlists: WordlistConfig = field(default_factory=WordlistConfig)
+    nuclei: NucleiConfig = field(default_factory=NucleiConfig)
+    ai: AIConfig = field(default_factory=AIConfig)
+    tools: dict[str, ToolConfig] = field(default_factory=dict)
+    api_keys: dict[str, str] = field(default_factory=dict)
+
+    # provenance (not serialised into user config)
+    _sources: list[str] = field(default_factory=list, repr=False)
+
+    # ---- construction ----------------------------------------------------
+    @classmethod
+    def load(cls, explicit_path: Optional[Path] = None) -> Config:
+        cfg = cls()
+        for path in _candidate_paths(explicit_path):
+            data = _read_yaml(path)
+            if data:
+                cfg._merge(data)
+                cfg._sources.append(str(path))
+        cfg._apply_env()
+        return cfg
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Config:
+        cfg = cls()
+        cfg._merge(data or {})
+        return cfg
+
+    # ---- access ----------------------------------------------------------
+    def tool(self, name: str) -> ToolConfig:
+        """Return the (possibly default) config for a named tool."""
+        return self.tools.get(name, ToolConfig())
+
+    @property
+    def workspace_root(self) -> Path:
+        return Path(self.general.workspace_path).expanduser()
+
+    def to_dict(self) -> dict[str, Any]:
+        data = _dataclass_to_dict(self)
+        data.pop("_sources", None)
+        return data
+
+    # ---- internal merge --------------------------------------------------
+    def _merge(self, data: dict[str, Any]) -> None:
+        for key in ("general", "http", "wordlists", "nuclei", "ai"):
+            if key in data and isinstance(data[key], dict):
+                _merge_into(getattr(self, key), data[key])
+        if "tools" in data and isinstance(data["tools"], dict):
+            for name, tdata in data["tools"].items():
+                base = self.tools.get(name, ToolConfig())
+                _merge_into(base, tdata or {})
+                self.tools[name] = base
+        if "api_keys" in data and isinstance(data["api_keys"], dict):
+            self.api_keys.update({k: str(v) for k, v in data["api_keys"].items()})
+
+    def _apply_env(self) -> None:
+        """Override scalars from HUNTKIT_<SECTION>_<KEY> environment vars."""
+        for section_name in ("general", "http", "ai", "nuclei"):
+            section = getattr(self, section_name)
+            for f in fields(section):
+                env_key = f"HUNTKIT_{section_name.upper()}_{f.name.upper()}"
+                if env_key in os.environ:
+                    setattr(section, f.name, _coerce(os.environ[env_key], f.type))
+        # API keys: HUNTKIT_APIKEY_<NAME>
+        for env_key, val in os.environ.items():
+            if env_key.startswith("HUNTKIT_APIKEY_"):
+                self.api_keys[env_key[len("HUNTKIT_APIKEY_") :].lower()] = val
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+def _candidate_paths(explicit: Optional[Path]) -> list[Path]:
+    paths: list[Path] = []
+    # user-level
+    home = os.environ.get("HUNTKIT_CONFIG_HOME")
+    user_dir = Path(home).expanduser() if home else Path.home() / ".config" / "huntkit"
+    paths.append(user_dir / CONFIG_FILENAME)
+    # project-level: nearest huntkit.yaml walking up from cwd
+    project = _find_upwards(Path.cwd(), CONFIG_FILENAME)
+    if project:
+        paths.append(project)
+    if explicit:
+        paths.append(Path(explicit).expanduser())
+    return paths
+
+
+def _find_upwards(start: Path, filename: str) -> Optional[Path]:
+    for parent in [start, *start.parents]:
+        candidate = parent / filename
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _read_yaml(path: Path) -> Optional[dict[str, Any]]:
+    try:
+        if not path.is_file():
+            return None
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+        return loaded if isinstance(loaded, dict) else None
+    except (OSError, yaml.YAMLError):
+        return None
+
+
+def _merge_into(obj: Any, data: dict[str, Any]) -> None:
+    """Shallow-merge dict values onto a dataclass instance, by field name."""
+    valid = {f.name for f in fields(obj)}
+    for key, value in data.items():
+        if key in valid and value is not None:
+            setattr(obj, key, value)
+
+
+def _coerce(raw: str, target_type: Any) -> Any:
+    type_str = str(target_type)
+    if "int" in type_str:
+        try:
+            return int(raw)
+        except ValueError:
+            return raw
+    if "bool" in type_str:
+        return raw.strip().lower() in {"1", "true", "yes", "on"}
+    return raw
+
+
+def _dataclass_to_dict(obj: Any) -> Any:
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _dataclass_to_dict(v) for k, v in asdict(obj).items()}
+    return obj
+
+
+def sample_yaml() -> str:
+    """Render a documented default config for `huntkit config init`."""
+    return _SAMPLE_YAML
+
+
+_SAMPLE_YAML = """\
+# HuntKit configuration — https://github.com/Raresney/HuntKit
+# Place at ~/.config/huntkit/huntkit.yaml (global) or ./huntkit.yaml (project).
+# Every value below is a default; delete what you don't need to override.
+
+general:
+  workspace_path: ~/.huntkit
+  threads: 20
+  rate: 150
+  timeout: 300
+  retry: 1
+  default_report_format: markdown   # markdown | html | json
+  color: true
+
+http:
+  proxy: null                       # e.g. http://127.0.0.1:8080 for Burp
+  user_agent: "HuntKit/0.2 (+https://github.com/Raresney/HuntKit)"
+  headers: {}                       # e.g. { X-Bug-Bounty: my-handle }
+  rate_limit: 150
+  follow_redirects: true
+
+wordlists:
+  dir_fuzz: null                    # e.g. /usr/share/seclists/.../common.txt
+  dns: null
+  params: null
+
+nuclei:
+  templates: null                   # custom template directory
+  severity: low,medium,high,critical
+  extra_args: []
+
+ai:
+  provider: ollama                  # ollama | openai | claude | gemini
+  model: llama3.2
+  endpoint: http://127.0.0.1:11434
+  require_approval: true            # never send recon data without a prompt
+  max_context_items: 40
+
+# Per-tool overrides. Pin a binary path, disable a tool, or append args.
+tools:
+  amass:
+    enabled: true
+    # path: /opt/amass/amass
+    # extra_args: ["-active"]
+
+# Secrets pulled by data-source tools. Prefer env vars: HUNTKIT_APIKEY_<NAME>.
+api_keys: {}
+  # chaos: "..."
+  # github: "..."
+  # shodan: "..."
+"""

huntkit/core/logger.py

@@ -0,0 +1,66 @@
+"""Structured logging built on Rich.
+
+Console logging is human-friendly; an optional rotating file handler writes a
+full engagement log into the workspace `logs/` directory. Feature modules
+call `get_logger(__name__)` and never touch handler configuration.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from rich.logging import RichHandler
+
+from ..utils.terminal import console
+
+_CONFIGURED = False
+_ROOT = "huntkit"
+
+
+def setup_logging(
+    level: str = "INFO",
+    logfile: Optional[Path] = None,
+    *,
+    verbose: bool = False,
+) -> None:
+    """Configure the `huntkit` logger tree once.
+
+    Safe to call repeatedly (e.g. after a workspace is opened to attach a
+    file handler) — handlers are reset rather than duplicated.
+    """
+    global _CONFIGURED
+    logger = logging.getLogger(_ROOT)
+    logger.setLevel(logging.DEBUG if verbose else getattr(logging, level.upper(), logging.INFO))
+    logger.handlers.clear()
+    logger.propagate = False
+
+    rich_handler = RichHandler(
+        console=console,
+        show_time=verbose,
+        show_path=verbose,
+        rich_tracebacks=True,
+        markup=True,
+    )
+    rich_handler.setLevel(logging.DEBUG if verbose else logging.INFO)
+    logger.addHandler(rich_handler)
+
+    if logfile is not None:
+        logfile.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(logfile, encoding="utf-8")
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+        )
+        logger.addHandler(file_handler)
+
+    _CONFIGURED = True
+
+
+def get_logger(name: str = _ROOT) -> logging.Logger:
+    if not _CONFIGURED:
+        setup_logging()
+    if name == _ROOT or name.startswith(_ROOT + "."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"{_ROOT}.{name}")

huntkit/core/pacing.py

@@ -0,0 +1,71 @@
+"""Politeness — one policy that paces every rate-aware tool.
+
+Real bug-bounty programs ban noisy scanners, and "authorised" does not mean
+"hammer the target". HuntKit keeps a single rate / delay / concurrency policy
+(from config) and maps it onto each tool's native flags, so dialing a program
+down to a gentle crawl is one edit, not twelve scattered ones.
+
+Pure and offline: it only turns the policy into argv fragments.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+@dataclass(frozen=True)
+class Pace:
+    """The politeness policy, normalised from config.
+
+    ``rate`` is HTTP requests/sec; ``port_rate`` is packets/sec for the port
+    scanner (a different budget); ``delay`` is seconds between requests for the
+    tools that support it; ``concurrency`` caps workers. A zero rate/delay
+    means "no limit" / "no wait".
+    """
+
+    rate: int
+    port_rate: int
+    delay: float
+    concurrency: int
+
+    @classmethod
+    def from_config(cls, config: Config) -> Pace:
+        return cls(
+            rate=max(0, config.http.rate_limit),
+            port_rate=max(0, config.general.rate),
+            delay=max(0.0, config.http.delay),
+            concurrency=max(1, config.general.threads),
+        )
+
+
+def duration(seconds: float) -> str:
+    """Render seconds as a ProjectDiscovery duration string: '500ms', '2s'."""
+    if seconds < 1:
+        return f"{int(round(seconds * 1000))}ms"
+    whole = int(seconds)
+    return f"{whole}s" if seconds == whole else f"{seconds}s"
+
+
+def rate_arg(flag: str, rate: int) -> list[str]:
+    """``[flag, rate]`` when a positive limit is set, else nothing."""
+    return [flag, str(rate)] if rate > 0 else []
+
+
+def delay_arg(flag: str, seconds: float, *, unit: str = "pd") -> list[str]:
+    """``[flag, value]`` for an inter-request delay, in the tool's own unit.
+
+    ``unit`` picks the rendering: ``pd`` → a ProjectDiscovery duration string
+    ('500ms'), ``sec`` → plain fractional seconds (ffuf ``-p``), ``ms`` → whole
+    milliseconds (dalfox ``--delay``). A non-positive delay emits nothing.
+    """
+    if seconds <= 0:
+        return []
+    if unit == "sec":
+        return [flag, str(seconds)]
+    if unit == "ms":
+        return [flag, str(int(round(seconds * 1000)))]
+    return [flag, duration(seconds)]