huntkit 0.3.0__py3-none-any.whl

huntkit/__init__.py

@@ -0,0 +1,4 @@
+"""HuntKit - a local bug bounty recon & methodology copilot."""
+
+__version__ = "0.3.0"
+__all__ = ["__version__"]

huntkit/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m huntkit`` to launch the Typer interface."""
+
+from __future__ import annotations
+
+from .app import run
+
+if __name__ == "__main__":
+    run()

huntkit/ai/__init__.py

@@ -0,0 +1,42 @@
+"""AI layer — optional, multi-provider advisor over the intel report.
+
+A feature layer (like intel/knowledge/report) that builds on ``core`` and
+``intel``. Local providers (Ollama) run fully offline; cloud providers are
+gated behind explicit approval so engagement data is never sent silently.
+"""
+
+from __future__ import annotations
+
+from .advisor import (
+    SYSTEM_PROMPT,
+    Advice,
+    Advisor,
+    ApprovalDenied,
+    build_context,
+    make_advisor,
+)
+from .providers import (
+    AnthropicProvider,
+    OllamaProvider,
+    OpenAIProvider,
+    Provider,
+    ProviderError,
+    get_provider,
+    provider_names,
+)
+
+__all__ = [
+    "SYSTEM_PROMPT",
+    "Advice",
+    "Advisor",
+    "ApprovalDenied",
+    "AnthropicProvider",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "Provider",
+    "ProviderError",
+    "build_context",
+    "get_provider",
+    "make_advisor",
+    "provider_names",
+]

huntkit/ai/advisor.py

@@ -0,0 +1,133 @@
+"""AI advisor — turn a scored intel report into a prioritised action plan.
+
+The advisor is where the security guarantee lives: for a **cloud** provider it
+refuses to send anything unless an ``approve`` callback (shown the exact text)
+returns True. That check runs in this layer, not just the CLI, so no caller can
+accidentally exfiltrate engagement data — the gate is enforced before
+``provider.complete`` is ever reached.
+
+It reasons only over data HuntKit already gathered (an :class:`IntelReport`);
+it never touches the target.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Optional
+
+from ..core.config import Config
+from ..intel import IntelReport
+from .providers import Provider, get_provider
+
+SYSTEM_PROMPT = (
+    "You are HuntKit's triage advisor for AUTHORISED bug-bounty and "
+    "penetration-testing engagements only. You are given a scored summary of "
+    "reconnaissance findings the operator has ALREADY gathered against in-scope "
+    "targets. Produce a concise, prioritised action plan: which hosts and "
+    "attack paths to focus on first, and the concrete next checks for each, "
+    "mapped to the bug classes shown.\n"
+    "Rules: assume the testing is authorised and in-scope; never suggest actions "
+    "outside the listed scope, indiscriminate mass exploitation, or destructive "
+    "steps. Prefer precise, verifiable checks over noisy scanning. Be brief and "
+    "actionable — bullet points, no preamble."
+)
+
+
+class ApprovalDenied(RuntimeError):
+    """Raised when a cloud send was required but not approved. Nothing was sent."""
+
+
+@dataclass
+class Advice:
+    provider: str
+    model: str
+    is_local: bool
+    endpoint: str
+    prompt: str  # the exact context that was sent
+    answer: str
+
+
+def build_context(report: IntelReport, *, max_items: int = 40) -> str:
+    """Render the intel report into the compact text the model reasons over.
+
+    This is exactly what leaves the machine for a cloud provider, so it is kept
+    plain, bounded, and free of anything but recon-derived facts.
+    """
+    out: list[str] = [f"Program: {report.program}", ""]
+
+    out.append("Prioritised hosts:")
+    for h in report.hosts[:max_items]:
+        pbs = ", ".join(h.playbooks[:4]) or "-"
+        out.append(f"- {h.host} [{h.priority.label}] score={h.score} playbooks={pbs}")
+
+    paths = report.attack_paths()
+    if paths:
+        out += ["", "Attack paths:"]
+        for p in paths[:max_items]:
+            out.append(
+                f"- {p.name} ({p.playbook}) severity={p.severity.label} hosts={len(p.hosts)}"
+            )
+
+    hot = sorted(
+        (s for s in report.signals if int(s.severity) >= 4),
+        key=lambda s: (-int(s.severity), s.host),
+    )
+    if hot:
+        out += ["", "Notable exposures:"]
+        for s in hot[:max_items]:
+            out.append(f"- [{s.severity.label}] {s.host}: {s.title} ({s.evidence})")
+
+    return "\n".join(out).strip() + "\n"
+
+
+class Advisor:
+    """Pairs a provider with config and enforces the cloud-approval gate."""
+
+    def __init__(self, provider: Provider, config: Config) -> None:
+        self.provider = provider
+        self.config = config
+
+    def resolve_model(self, explicit: Optional[str] = None) -> str:
+        if explicit:
+            return explicit
+        # only honour the configured model for the configured provider —
+        # e.g. don't send ollama's 'llama3.2' default to Anthropic
+        if self.provider.name == self.config.ai.provider and self.config.ai.model:
+            return self.config.ai.model
+        return self.provider.default_model
+
+    def advise(
+        self,
+        report: IntelReport,
+        *,
+        model: Optional[str] = None,
+        approve: Optional[Callable[[str], bool]] = None,
+    ) -> Advice:
+        """Ask the provider for guidance. Cloud providers require approval first."""
+        ctx = build_context(report, max_items=self.config.ai.max_context_items)
+        model_id = self.resolve_model(model)
+
+        if (
+            not self.provider.is_local
+            and self.config.ai.require_approval
+            and (approve is None or not approve(ctx))
+        ):
+            raise ApprovalDenied(f"sending recon data to '{self.provider.name}' was not approved")
+
+        answer = self.provider.complete(SYSTEM_PROMPT, ctx, model=model_id, config=self.config)
+        return Advice(
+            provider=self.provider.name,
+            model=model_id,
+            is_local=self.provider.is_local,
+            endpoint=self.provider.endpoint_host(self.config),
+            prompt=ctx,
+            answer=answer,
+        )
+
+
+def make_advisor(config: Config, provider_name: Optional[str] = None) -> Optional[Advisor]:
+    """Build an advisor for the named (or configured) provider; None if unknown."""
+    name = (provider_name or config.ai.provider or "ollama").strip().lower()
+    provider = get_provider(name)
+    return Advisor(provider, config) if provider is not None else None

huntkit/ai/providers.py

@@ -0,0 +1,200 @@
+"""AI providers — a thin, dependency-free abstraction over one HTTP call.
+
+Each provider turns a (system, prompt) pair into completion text. They talk raw
+JSON over stdlib ``urllib`` so the AI layer stays optional and adds no
+dependencies (HuntKit is lean-dep on purpose; Ollama has no SDK anyway).
+
+The security-relevant property is :attr:`Provider.is_local`. Local providers
+(Ollama on 127.0.0.1) never send engagement data off the machine; cloud
+providers do, and the advisor gates them behind explicit approval.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+from ..core.config import Config
+
+
+class ProviderError(RuntimeError):
+    """A provider could not produce a completion (network, auth, empty reply)."""
+
+
+def _post_json(url: str, headers: dict[str, str], payload: dict, timeout: int) -> dict:
+    """POST JSON and parse the JSON reply. Raises ProviderError on any failure.
+
+    Kept module-level so tests can stub the whole network round-trip.
+    """
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={"content-type": "application/json", **headers},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")[:400]
+        raise ProviderError(f"{url}: HTTP {e.code} — {detail}") from None
+    except urllib.error.URLError as e:
+        raise ProviderError(f"cannot reach {url}: {e.reason}") from None
+    except (TimeoutError, OSError, ValueError) as e:
+        raise ProviderError(f"request to {url} failed: {e}") from None
+
+
+def _api_key(config: Config, name: str, *env_names: str) -> str:
+    """Resolve an API key: config.api_keys first, then well-known env vars."""
+    key = config.api_keys.get(name)
+    if key:
+        return key
+    for env in env_names:
+        val = os.environ.get(env)
+        if val:
+            return val
+    return ""
+
+
+class Provider:
+    """Base provider. Subclasses set the class attrs and implement ``complete``."""
+
+    name: str = ""
+    default_model: str = ""
+    is_local: bool = False
+
+    def available(self, config: Config) -> bool:
+        """Whether this provider can be used right now (key present, etc.)."""
+        return True
+
+    def endpoint_host(self, config: Config) -> str:
+        """Human-readable destination, shown at the approval gate."""
+        return ""
+
+    def complete(self, system: str, prompt: str, *, model: str, config: Config) -> str:
+        raise NotImplementedError
+
+
+class OllamaProvider(Provider):
+    """Local Ollama (offline). Data never leaves the machine — no approval gate."""
+
+    name = "ollama"
+    default_model = "llama3.2"
+    is_local = True
+
+    def endpoint_host(self, config: Config) -> str:
+        return config.ai.endpoint
+
+    def complete(self, system: str, prompt: str, *, model: str, config: Config) -> str:
+        url = config.ai.endpoint.rstrip("/") + "/api/chat"
+        data = _post_json(
+            url,
+            {},
+            {
+                "model": model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                "stream": False,
+            },
+            timeout=config.general.timeout,
+        )
+        text = (data.get("message") or {}).get("content", "").strip()
+        if not text:
+            raise ProviderError("Ollama returned no content (is the model pulled?)")
+        return text
+
+
+class AnthropicProvider(Provider):
+    """Anthropic Claude via the Messages API (cloud → gated)."""
+
+    name = "claude"
+    default_model = "claude-opus-4-8"
+    is_local = False
+
+    def _key(self, config: Config) -> str:
+        return _api_key(config, "anthropic", "ANTHROPIC_API_KEY")
+
+    def available(self, config: Config) -> bool:
+        return bool(self._key(config))
+
+    def endpoint_host(self, config: Config) -> str:
+        return "api.anthropic.com"
+
+    def complete(self, system: str, prompt: str, *, model: str, config: Config) -> str:
+        key = self._key(config)
+        if not key:
+            raise ProviderError("no Anthropic API key (set HUNTKIT_APIKEY_ANTHROPIC)")
+        data = _post_json(
+            "https://api.anthropic.com/v1/messages",
+            {"x-api-key": key, "anthropic-version": "2023-06-01"},
+            {
+                "model": model,
+                "max_tokens": 1024,
+                "system": system,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+            timeout=config.general.timeout,
+        )
+        text = "".join(
+            b.get("text", "") for b in data.get("content", []) if b.get("type") == "text"
+        ).strip()
+        if not text:
+            raise ProviderError("Anthropic returned no text content")
+        return text
+
+
+class OpenAIProvider(Provider):
+    """OpenAI chat completions (cloud → gated)."""
+
+    name = "openai"
+    default_model = "gpt-4o-mini"
+    is_local = False
+
+    def _key(self, config: Config) -> str:
+        return _api_key(config, "openai", "OPENAI_API_KEY")
+
+    def available(self, config: Config) -> bool:
+        return bool(self._key(config))
+
+    def endpoint_host(self, config: Config) -> str:
+        return "api.openai.com"
+
+    def complete(self, system: str, prompt: str, *, model: str, config: Config) -> str:
+        key = self._key(config)
+        if not key:
+            raise ProviderError("no OpenAI API key (set HUNTKIT_APIKEY_OPENAI)")
+        data = _post_json(
+            "https://api.openai.com/v1/chat/completions",
+            {"authorization": f"Bearer {key}"},
+            {
+                "model": model,
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+            },
+            timeout=config.general.timeout,
+        )
+        choices = data.get("choices") or []
+        text = (choices[0].get("message", {}).get("content", "") if choices else "").strip()
+        if not text:
+            raise ProviderError("OpenAI returned no content")
+        return text
+
+
+_PROVIDERS: dict[str, Provider] = {
+    p.name: p for p in (OllamaProvider(), AnthropicProvider(), OpenAIProvider())
+}
+
+
+def get_provider(name: str) -> Provider | None:
+    return _PROVIDERS.get(name.strip().lower())
+
+
+def provider_names() -> list[str]:
+    return list(_PROVIDERS)

huntkit/app/__init__.py

@@ -0,0 +1,13 @@
+"""HuntKit's Typer command-line interface (v0.2).
+
+The application object and its entry point live here. During the v0.2
+transition the legacy argparse CLI (``huntkit.cli``) remains the default
+``huntkit`` console script; this interface is reachable via
+``python -m huntkit`` until it reaches feature parity.
+"""
+
+from __future__ import annotations
+
+from .main import app, run
+
+__all__ = ["app", "run"]

huntkit/app/config_cmd.py

@@ -0,0 +1,65 @@
+"""`huntkit config` — inspect and scaffold configuration."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+import yaml
+
+from ..core.config import CONFIG_FILENAME, Config, sample_yaml
+from ..utils import filesystem as fs
+from ..utils import terminal as term
+
+config_app = typer.Typer(no_args_is_help=True, help="Inspect and scaffold configuration.")
+
+
+def _user_config_path() -> Path:
+    home = os.environ.get("HUNTKIT_CONFIG_HOME")
+    base = Path(home).expanduser() if home else Path.home() / ".config" / "huntkit"
+    return base / CONFIG_FILENAME
+
+
+@config_app.command("init")
+def config_init(
+    path: Optional[Path] = typer.Option(
+        None, "--path", "-o", help="Where to write (default: user config dir)."
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite if it exists."),
+) -> None:
+    """Write a documented default huntkit.yaml."""
+    target = path or _user_config_path()
+    if target.exists() and not force:
+        term.warn(f"{target} already exists — use --force to overwrite.")
+        raise typer.Exit(1)
+    fs.write_text(target, sample_yaml())
+    term.ok(f"wrote config: {target}")
+    term.info("edit it, or override any value with HUNTKIT_<SECTION>_<KEY> env vars.")
+
+
+@config_app.command("show")
+def config_show(ctx: typer.Context) -> None:
+    """Print the resolved, merged configuration (secrets redacted)."""
+    config: Config = ctx.obj.config
+    data = config.to_dict()
+    if data.get("api_keys"):
+        data["api_keys"] = dict.fromkeys(data["api_keys"], "***")
+    term.console.print(yaml.safe_dump(data, sort_keys=False, default_flow_style=False).rstrip())
+    if config._sources:
+        term.info("merged from: " + ", ".join(config._sources))
+    else:
+        term.info("using built-in defaults (no config file found).")
+
+
+@config_app.command("path")
+def config_path() -> None:
+    """Show where HuntKit looks for configuration."""
+    user = _user_config_path()
+    project = Path.cwd() / CONFIG_FILENAME
+    rows = [
+        ("user", str(user), "yes" if user.exists() else "no"),
+        ("project", str(project), "yes" if project.exists() else "no"),
+    ]
+    term.print_table("Config search path", ["scope", "path", "exists"], rows)

huntkit/app/context.py

@@ -0,0 +1,50 @@
+"""The object passed down every command via Typer's context.
+
+Built once in the root callback from the global options, so each command
+gets a ready configuration, a runner, a cache, and the plugin registry
+without re-parsing anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from ..core.cache import Cache
+from ..core.config import Config
+from ..core.logger import setup_logging
+from ..core.runner import CommandRunner
+from ..plugins import get_registry
+from ..plugins.registry import PluginRegistry
+
+
+@dataclass
+class AppContext:
+    config: Config
+    runner: CommandRunner
+    cache: Cache
+    registry: PluginRegistry
+    base: Optional[Path] = None  # workspace base override (--workspace)
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        config_path: Optional[Path] = None,
+        workspace: Optional[Path] = None,
+        verbose: bool = False,
+        quiet: bool = False,
+    ) -> AppContext:
+        config = Config.load(config_path)
+        level = "DEBUG" if verbose else ("ERROR" if quiet else "INFO")
+        setup_logging(level=level, verbose=verbose)
+        cache = Cache(config.workspace_root / ".cache")
+        runner = CommandRunner(config, cache=cache)
+        return cls(
+            config=config,
+            runner=runner,
+            cache=cache,
+            registry=get_registry(),
+            base=workspace,
+        )