huntkit 0.3.0__py3-none-any.whl

huntkit/plugins/base.py

@@ -0,0 +1,220 @@
+"""The plugin contract.
+
+Every external tool HuntKit drives is a :class:`ToolPlugin`. A plugin is a
+small, declarative description of *one* binary:
+
+  - metadata     name / category / install hint / description
+  - typing       what it consumes and what it produces (a :class:`Capability`)
+  - ``build_args``  turn a run context into the argv that follows the binary
+  - ``parse``       turn the process output into a list of items
+
+Everything hard — binary resolution, per-tool timeouts and extra args, proxy
+environment, retries, caching — already lives in :class:`~huntkit.core.runner.
+CommandRunner`. A plugin never touches subprocess; it only says *what* to run
+and *how to read the result*. That is what makes adding a new tool a matter of
+dropping one file into this package: the registry discovers it, the pipeline
+schedules it by capability, and nothing else changes.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+from ..utils.process import ProcResult
+
+if TYPE_CHECKING:  # avoid import cycle at runtime; only needed for typing
+    from ..core.config import Config
+    from ..core.runner import CommandRunner
+
+
+class Capability(str, Enum):
+    """The data types that flow between plugins in the recon pipeline.
+
+    A plugin ``consumes`` one type and ``produces`` another; the pipeline
+    chains plugins by matching output to input (subdomains -> hosts -> urls
+    -> findings) without any plugin knowing about the others.
+    """
+
+    DOMAIN = "domain"  # a seed root domain (example.com)
+    SUBDOMAIN = "subdomain"  # a discovered name (api.example.com)
+    HOST = "host"  # a name that resolves / is probed live
+    URL = "url"  # a live http(s) endpoint
+    PORT = "port"  # an open host:port
+    PARAM = "param"  # a discovered request parameter
+    JS = "js"  # a javascript asset
+    FINDING = "finding"  # a vuln / signal worth a human's attention
+
+
+class Category(str, Enum):
+    """Coarse grouping for `doctor`, help output, and pipeline stages."""
+
+    DISCOVERY = "discovery"  # find subdomains / assets
+    RESOLVE = "resolve"  # probe which are live + fingerprint
+    PORTS = "ports"  # port / service scanning
+    URLS = "urls"  # gather / crawl urls
+    SCAN = "scan"  # vuln / fuzz / param analysis
+    ENRICH = "enrich"  # metadata (asn, cdn, waf, favicon, ...)
+
+
+class InputMode(str, Enum):
+    """How the target feeds into the tool.
+
+    Only :data:`STDIN` is auto-wired by the base class; for the others the
+    plugin places the target/inputs itself inside :meth:`ToolPlugin.build_args`,
+    because flag placement differs per tool (``-d dom`` vs positional vs ``-t``).
+    """
+
+    TARGET = "target"  # a single seed placed by build_args (ctx.target)
+    STDIN = "stdin"  # ctx.inputs piped to the process stdin, newline-joined
+    ARGS = "args"  # ctx.inputs placed by build_args as argv
+    NONE = "none"  # takes no external target
+
+
+@dataclass
+class PluginContext:
+    """Everything a plugin needs to build and run one invocation.
+
+    Deliberately small and decoupled: a plugin sees the config and a runner,
+    a seed ``target`` (for discovery) and/or a list of ``inputs`` (for tools
+    that consume the previous stage's output). ``extra`` is an escape hatch
+    for one-off knobs (e.g. a FUZZ url) without growing this class.
+    """
+
+    config: Config
+    runner: CommandRunner
+    target: Optional[str] = None
+    inputs: list[str] = field(default_factory=list)
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class PluginResult:
+    """Outcome of a single plugin run."""
+
+    plugin: str
+    produces: Capability
+    items: list[str] = field(default_factory=list)
+    raw: Optional[ProcResult] = None
+    ok: bool = False
+    skipped: bool = False  # tool not installed / no input — not a failure
+    reason: str = ""
+
+    @property
+    def count(self) -> int:
+        return len(self.items)
+
+    def __bool__(self) -> bool:
+        return self.ok and not self.skipped
+
+
+class ToolPlugin(ABC):
+    """Base class for every tool integration.
+
+    Subclasses set the class attributes and implement :meth:`build_args`.
+    Override :meth:`parse` when the tool's output is not one item per line.
+    The registry instantiates each concrete subclass once (they are stateless).
+    """
+
+    # ---- metadata (override as class attributes) -------------------------
+    name: str = ""  # registry key; usually the binary name
+    binary: str = ""  # executable to resolve (defaults to name)
+    category: Category = Category.DISCOVERY
+    description: str = ""
+    install: str = ""  # copy-pasteable install hint
+    consumes: Optional[Capability] = None
+    produces: Capability = Capability.SUBDOMAIN
+    input_mode: InputMode = InputMode.TARGET
+    needs_api_key: Optional[str] = None  # api_keys entry required, if any
+
+    # A subclass is registrable only once it declares a name. The abstract
+    # base and any intermediate helpers stay out of the registry.
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        if not getattr(cls, "binary", "") and getattr(cls, "name", ""):  # type: ignore[arg-type]
+            cls.binary = cls.name
+
+    # ---- the two things a plugin must / may define -----------------------
+    @abstractmethod
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        """Return the argv that follows the binary for this invocation.
+
+        For STDIN tools this is just the flags (input arrives via stdin);
+        for TARGET/ARGS tools, place ``ctx.target`` / ``ctx.inputs`` here.
+        """
+
+    def parse(self, result: ProcResult, ctx: PluginContext) -> list[str]:
+        """Extract produced items from the output. Default: one per line."""
+        return result.lines
+
+    # ---- optional hooks --------------------------------------------------
+    def stdin_payload(self, ctx: PluginContext) -> Optional[str]:
+        """What to pipe to stdin. Default: inputs when in STDIN mode."""
+        if self.input_mode is InputMode.STDIN and ctx.inputs:
+            return "\n".join(ctx.inputs)
+        return None
+
+    def cache_key(self, ctx: PluginContext) -> Optional[str]:
+        """Content-addressed cache key, or None to disable caching.
+
+        Active only when the run opts in (``ctx.extra["use_cache"]``). The key
+        binds the binary, its arguments, and the stdin payload, so identical
+        invocations hit the cache and any change misses it.
+        """
+        if not ctx.extra.get("use_cache"):
+            return None
+        from ..core.cache import make_key
+
+        payload = self.stdin_payload(ctx) or ""
+        return make_key(self.binary, *self.build_args(ctx), payload)
+
+    def is_available(self, runner: CommandRunner) -> bool:
+        return runner.available(self.binary)
+
+    # ---- orchestration (do not usually override) -------------------------
+    def execute(self, ctx: PluginContext) -> PluginResult:
+        """Resolve, run, and parse — returning a uniform :class:`PluginResult`.
+
+        Never raises for the ordinary "tool missing" / "empty output" cases;
+        those are surfaced as ``skipped``/empty results so one gap does not
+        abort a whole pipeline.
+        """
+        from ..core.runner import ToolNotFound
+
+        if self.needs_api_key and not ctx.config.api_keys.get(self.needs_api_key):
+            return PluginResult(
+                self.name,
+                self.produces,
+                skipped=True,
+                reason=f"missing api key: {self.needs_api_key}",
+            )
+        if not self.is_available(ctx.runner):
+            return PluginResult(self.name, self.produces, skipped=True, reason="not installed")
+        if self.input_mode in (InputMode.STDIN, InputMode.ARGS) and not ctx.inputs:
+            return PluginResult(self.name, self.produces, skipped=True, reason="no input")
+
+        args = self.build_args(ctx)
+        try:
+            result = ctx.runner.run(
+                self.binary,
+                args,
+                stdin_data=self.stdin_payload(ctx),
+                cache_key=self.cache_key(ctx),
+            )
+        except ToolNotFound as exc:
+            return PluginResult(self.name, self.produces, skipped=True, reason=str(exc))
+
+        # Non-zero exit is common (empty source); still parse what came back.
+        items = self.parse(result, ctx)
+        return PluginResult(
+            self.name,
+            self.produces,
+            items=items,
+            raw=result,
+            ok=result.ok,
+        )
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"<{type(self).__name__} {self.name} {self.category.value}>"

huntkit/plugins/chaos.py

@@ -0,0 +1,20 @@
+"""chaos — ProjectDiscovery's Chaos subdomain dataset (needs an API key)."""
+
+from __future__ import annotations
+
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Chaos(ToolPlugin):
+    name = "chaos"
+    category = Category.DISCOVERY
+    description = "Query the ProjectDiscovery Chaos dataset"
+    install = "go install github.com/projectdiscovery/chaos-client/cmd/chaos@latest"
+    consumes = Capability.DOMAIN
+    produces = Capability.SUBDOMAIN
+    input_mode = InputMode.TARGET
+    needs_api_key = "chaos"
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        key = ctx.config.api_keys.get("chaos", "")
+        return ["-d", str(ctx.target), "-silent", "-key", key]

huntkit/plugins/dalfox.py

@@ -0,0 +1,24 @@
+"""dalfox — XSS scanning / parameter analysis (hahwul)."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, delay_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Dalfox(ToolPlugin):
+    name = "dalfox"
+    category = Category.SCAN
+    description = "XSS scanning / parameter analysis"
+    install = "go install github.com/hahwul/dalfox/v2@latest"
+    consumes = Capability.URL
+    produces = Capability.FINDING
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        # pipe mode reads candidate urls from stdin
+        pace = Pace.from_config(ctx.config)
+        args = ["pipe", "--silence", "--no-color", "--no-spinner"]
+        args += ["--worker", str(pace.concurrency)]
+        args += delay_arg("--delay", pace.delay, unit="ms")  # dalfox wants ms
+        return args

huntkit/plugins/dnsx.py

@@ -0,0 +1,19 @@
+"""dnsx — fast DNS resolver; filters a name list down to what resolves."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Dnsx(ToolPlugin):
+    name = "dnsx"
+    category = Category.RESOLVE
+    description = "Resolve a subdomain list, keeping only live DNS names"
+    install = "go install github.com/projectdiscovery/dnsx/cmd/dnsx@latest"
+    consumes = Capability.SUBDOMAIN
+    produces = Capability.HOST
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        return ["-silent", "-nc", *rate_arg("-rate-limit", Pace.from_config(ctx.config).rate)]

huntkit/plugins/ffuf.py

@@ -0,0 +1,34 @@
+"""ffuf — content/vhost/parameter fuzzing.
+
+Needs a URL containing the ``FUZZ`` marker and a wordlist. If the target has
+no marker, ``/FUZZ`` is appended; the wordlist comes from ``ctx.extra`` or
+``wordlists.dir_fuzz`` in config.
+"""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, delay_arg, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Ffuf(ToolPlugin):
+    name = "ffuf"
+    category = Category.SCAN
+    description = "Content/vhost/parameter fuzzing"
+    install = "go install github.com/ffuf/ffuf/v2@latest"
+    consumes = Capability.URL
+    produces = Capability.URL
+    input_mode = InputMode.TARGET
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        url = str(ctx.target or "")
+        if "FUZZ" not in url:
+            url = url.rstrip("/") + "/FUZZ"
+        args = ["-u", url, "-s", "-mc", "200,204,301,302,307,401,403"]
+        wordlist = ctx.extra.get("wordlist") or ctx.config.wordlists.dir_fuzz
+        if wordlist:
+            args += ["-w", str(wordlist)]
+        pace = Pace.from_config(ctx.config)
+        args += rate_arg("-rate", pace.rate)  # ffuf: total requests/sec
+        args += delay_arg("-p", pace.delay, unit="sec")  # seconds between requests
+        return args

huntkit/plugins/findomain.py

@@ -0,0 +1,18 @@
+"""findomain — fast passive subdomain enumeration."""
+
+from __future__ import annotations
+
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Findomain(ToolPlugin):
+    name = "findomain"
+    category = Category.DISCOVERY
+    description = "Fast passive subdomain enumeration"
+    install = "sudo apt install findomain  # or grab a release binary"
+    consumes = Capability.DOMAIN
+    produces = Capability.SUBDOMAIN
+    input_mode = InputMode.TARGET
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        return ["-t", str(ctx.target), "-q"]

huntkit/plugins/gau.py

@@ -0,0 +1,18 @@
+"""gau — fetch known URLs from wayback/otx/commoncrawl (lc/gau)."""
+
+from __future__ import annotations
+
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Gau(ToolPlugin):
+    name = "gau"
+    category = Category.URLS
+    description = "Fetch known URLs (wayback/otx/commoncrawl)"
+    install = "go install github.com/lc/gau/v2/cmd/gau@latest"
+    consumes = Capability.DOMAIN
+    produces = Capability.URL
+    input_mode = InputMode.TARGET
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        return ["--threads", str(ctx.config.general.threads), str(ctx.target)]

huntkit/plugins/hakrawler.py

@@ -0,0 +1,19 @@
+"""hakrawler — fast endpoint crawler that reads live urls from stdin."""
+
+from __future__ import annotations
+
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Hakrawler(ToolPlugin):
+    name = "hakrawler"
+    category = Category.URLS
+    description = "Crawl live hosts for endpoints and assets"
+    install = "go install github.com/hakluke/hakrawler@latest"
+    consumes = Capability.URL
+    produces = Capability.URL
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        # -u unique, -d crawl depth
+        return ["-u", "-d", "2"]

huntkit/plugins/httpx.py

@@ -0,0 +1,30 @@
+"""httpx — probe live hosts, titles, tech, status codes (ProjectDiscovery).
+
+Note: on a bug-bounty box this is ProjectDiscovery's ``httpx``. A Python
+package of the same name ships a different ``httpx`` CLI; pin
+``tools.httpx.path`` in config if both are installed.
+"""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, delay_arg, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Httpx(ToolPlugin):
+    name = "httpx"
+    category = Category.RESOLVE
+    description = "Probe live hosts (status, title, tech-detect)"
+    install = "go install github.com/projectdiscovery/httpx/cmd/httpx@latest"
+    consumes = Capability.SUBDOMAIN
+    produces = Capability.URL
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        pace = Pace.from_config(ctx.config)
+        args = ["-silent", "-no-color", "-t", str(ctx.config.general.threads)]
+        args += rate_arg("-rate-limit", pace.rate)
+        args += delay_arg("-delay", pace.delay)
+        if ctx.config.http.follow_redirects:
+            args.append("-follow-redirects")
+        return args

huntkit/plugins/katana.py

@@ -0,0 +1,23 @@
+"""katana — active crawler / URL discovery (ProjectDiscovery)."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Katana(ToolPlugin):
+    name = "katana"
+    category = Category.URLS
+    description = "Active crawler / URL discovery"
+    install = "go install github.com/projectdiscovery/katana/cmd/katana@latest"
+    consumes = Capability.URL
+    produces = Capability.URL
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        # urls arrive via stdin; -d = crawl depth, -c = concurrency
+        pace = Pace.from_config(ctx.config)
+        args = ["-silent", "-nc", "-d", "2", "-c", str(ctx.config.general.threads)]
+        args += rate_arg("-rate-limit", pace.rate)
+        return args

huntkit/plugins/naabu.py

@@ -0,0 +1,22 @@
+"""naabu — fast SYN/CONNECT port scanner (ProjectDiscovery)."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Naabu(ToolPlugin):
+    name = "naabu"
+    category = Category.PORTS
+    description = "Fast port scanner"
+    install = "go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest"
+    consumes = Capability.HOST
+    produces = Capability.PORT
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        # hosts arrive via stdin; emit host:port on stdout. port_rate is a
+        # packet budget, a different knob from the HTTP request rate.
+        pace = Pace.from_config(ctx.config)
+        return ["-silent", "-no-color", *rate_arg("-rate", pace.port_rate)]

huntkit/plugins/nmap.py

@@ -0,0 +1,39 @@
+"""nmap — port scan + service/version detection.
+
+Reads targets as argv (nmap has no stdin list mode) and emits greppable
+output on stdout, which we parse into ``host:port`` entries.
+"""
+
+from __future__ import annotations
+
+from ..utils.process import ProcResult
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Nmap(ToolPlugin):
+    name = "nmap"
+    category = Category.PORTS
+    description = "Port scan + service/version detection"
+    install = "sudo apt install nmap"
+    consumes = Capability.HOST
+    produces = Capability.PORT
+    input_mode = InputMode.ARGS
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        return ["-T4", "-Pn", "--top-ports", "1000", "-oG", "-", *ctx.inputs]
+
+    def parse(self, result: ProcResult, ctx: PluginContext) -> list[str]:
+        out: list[str] = []
+        for line in result.lines:
+            if "Ports:" not in line:
+                continue
+            parts = line.split()
+            if len(parts) < 2 or parts[0] != "Host:":
+                continue
+            host = parts[1]
+            # e.g. "Ports: 22/open/tcp//ssh///, 80/open/tcp//http///"
+            for chunk in line.split("Ports:", 1)[1].split(","):
+                fields = chunk.strip().split("/")
+                if len(fields) >= 2 and fields[1] == "open":
+                    out.append(f"{host}:{fields[0]}")
+        return out

huntkit/plugins/nuclei.py

@@ -0,0 +1,27 @@
+"""nuclei — template-based vulnerability scanner (ProjectDiscovery)."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Nuclei(ToolPlugin):
+    name = "nuclei"
+    category = Category.SCAN
+    description = "Template-based vulnerability scanner"
+    install = "go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest"
+    consumes = Capability.URL
+    produces = Capability.FINDING
+    input_mode = InputMode.STDIN
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        n = ctx.config.nuclei
+        args = ["-silent", "-nc"]
+        if n.severity:
+            args += ["-severity", n.severity]
+        if n.templates:
+            args += ["-t", n.templates]
+        args += rate_arg("-rate-limit", Pace.from_config(ctx.config).rate)
+        args += n.extra_args
+        return args

huntkit/plugins/registry.py

@@ -0,0 +1,117 @@
+"""Plugin discovery and lookup.
+
+The registry is the reason a new tool costs one file: on first use it walks
+this package, imports every module, and collects every concrete
+:class:`~huntkit.plugins.base.ToolPlugin` subclass. Nothing has to be listed
+by hand — drop ``huntkit/plugins/mytool.py`` in and it is picked up.
+
+Consumers ask by name, category, or capability so the CLI (`doctor`, `plugins`)
+and the recon pipeline can reason about tools generically.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Optional
+
+from .base import Capability, Category, ToolPlugin
+
+if TYPE_CHECKING:
+    from ..core.runner import CommandRunner
+
+
+class PluginRegistry:
+    """An in-memory index of plugin singletons, keyed by name."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[str, ToolPlugin] = {}
+
+    # ---- population ------------------------------------------------------
+    def register(self, plugin: ToolPlugin) -> None:
+        if not plugin.name:
+            raise ValueError(f"{type(plugin).__name__} has no name")
+        if plugin.name in self._by_name:
+            raise ValueError(f"duplicate plugin name: {plugin.name!r}")
+        self._by_name[plugin.name] = plugin
+
+    # ---- lookup ----------------------------------------------------------
+    def get(self, name: str) -> Optional[ToolPlugin]:
+        return self._by_name.get(name)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._by_name
+
+    def __len__(self) -> int:
+        return len(self._by_name)
+
+    def all(self) -> list[ToolPlugin]:
+        return sorted(self._by_name.values(), key=lambda p: (p.category.value, p.name))
+
+    def names(self) -> list[str]:
+        return sorted(self._by_name)
+
+    def by_category(self, category: Category) -> list[ToolPlugin]:
+        return [p for p in self.all() if p.category is category]
+
+    def producing(self, cap: Capability) -> list[ToolPlugin]:
+        return [p for p in self.all() if p.produces is cap]
+
+    def consuming(self, cap: Capability) -> list[ToolPlugin]:
+        return [p for p in self.all() if p.consumes is cap]
+
+    def available(self, runner: CommandRunner) -> list[ToolPlugin]:
+        """Plugins whose binary is installed / pinned right now."""
+        return [p for p in self.all() if p.is_available(runner)]
+
+    def missing(self, runner: CommandRunner) -> list[ToolPlugin]:
+        return [p for p in self.all() if not p.is_available(runner)]
+
+
+# --------------------------------------------------------------------------
+# Discovery
+# --------------------------------------------------------------------------
+def _iter_plugin_classes(package_name: str) -> Iterable[type[ToolPlugin]]:
+    """Import every module in the package and yield concrete plugin classes."""
+    package = importlib.import_module(package_name)
+    for mod in pkgutil.iter_modules(package.__path__):
+        if mod.name in {"base", "registry"} or mod.name.startswith("_"):
+            continue
+        importlib.import_module(f"{package_name}.{mod.name}")
+
+    seen: set[type[ToolPlugin]] = set()
+    stack: list[type[ToolPlugin]] = list(ToolPlugin.__subclasses__())
+    while stack:
+        cls = stack.pop()
+        if cls in seen:
+            continue
+        seen.add(cls)
+        stack.extend(cls.__subclasses__())
+        if inspect.isabstract(cls) or not getattr(cls, "name", ""):
+            continue
+        # only plugins that actually live in this package — never a stray
+        # subclass defined by tests or downstream code
+        if not cls.__module__.startswith(package_name):
+            continue
+        yield cls
+
+
+def discover(package_name: str = __package__ or "huntkit.plugins") -> PluginRegistry:
+    """Build a fresh registry by scanning ``package_name`` for plugins."""
+    registry = PluginRegistry()
+    for cls in _iter_plugin_classes(package_name):
+        registry.register(cls())
+    return registry
+
+
+_REGISTRY: Optional[PluginRegistry] = None
+
+
+def get_registry(*, refresh: bool = False) -> PluginRegistry:
+    """Return the process-wide registry, discovering plugins on first use."""
+    global _REGISTRY
+    if _REGISTRY is None or refresh:
+        _REGISTRY = discover()
+    return _REGISTRY

huntkit/plugins/subfinder.py

@@ -0,0 +1,21 @@
+"""subfinder — passive subdomain enumeration (ProjectDiscovery)."""
+
+from __future__ import annotations
+
+from ..core.pacing import Pace, rate_arg
+from .base import Capability, Category, InputMode, PluginContext, ToolPlugin
+
+
+class Subfinder(ToolPlugin):
+    name = "subfinder"
+    category = Category.DISCOVERY
+    description = "Passive subdomain enumeration"
+    install = "go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest"
+    consumes = Capability.DOMAIN
+    produces = Capability.SUBDOMAIN
+    input_mode = InputMode.TARGET
+
+    def build_args(self, ctx: PluginContext) -> list[str]:
+        args = ["-silent", "-d", str(ctx.target)]
+        args += rate_arg("-rate-limit", Pace.from_config(ctx.config).rate)
+        return args