hunterxsec 7.0.0__py3-none-any.whl

hunterx/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+#
+# HunterX v7 — AI-Powered Security Orchestration & Intelligence Platform
+
+"""HunterX v7 core package.
+
+This package is the Clean Architecture backbone of the HunterX platform. It
+contains only foundation code: domain model, application services, engines,
+infrastructure adapters, and the public SDKs. No scanners, no tool
+implementations, no AI models, and no business logic live here.
+
+Package layout follows the ratified Development Bible
+(``docs/bible/03 - Folder Structure.md``):
+
+- :mod:`hunterx.domain`         — pure domain layer (entities, ports, services)
+- :mod:`hunterx.application`    — use-case layer
+- :mod:`hunterx.infrastructure` — adapters (db, cache, queue, ai, sandbox, ...)
+- :mod:`hunterx.engines`        — engine facades (mission, workflow, planner, ...)
+- :mod:`hunterx.agents`         — multi-agent platform
+- :mod:`hunterx.plugins`        — plugin system + public plugin SDK
+- :mod:`hunterx.tools`          — tool adapter SDK + parser/normalizer framework
+- :mod:`hunterx.knowledge`      — knowledge engine + knowledge graph
+- :mod:`hunterx.scheduler`      — scheduler + jobs
+- :mod:`hunterx.reporting`      — reporting infrastructure
+- :mod:`hunterx.config`         — configuration manager
+- :mod:`hunterx.shared`         — cross-cutting helpers (ids, masking, di, result)
+- :mod:`hunterx.api`            — REST API framework (routing structure)
+- :mod:`hunterx.cli`            — CLI framework (command structure)
+"""
+
+from __future__ import annotations
+
+__version__ = "7.0.0"
+__author__ = "Ahmed Awad (NullC0d3)"
+__license__ = "Apache-2.0"
+
+# NOTE: deliberately NOT importing any submodules here to keep the package
+# import cheap and side-effect free. Subsystems are imported on demand.
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+]

hunterx/agents/__init__.py

@@ -0,0 +1,30 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Multi-agent platform.
+
+Provides the abstract :class:`~hunterx.agents.base.SecurityAgent` contract,
+the agent registry, orchestrator and shared agent infrastructure. Concrete
+agents (recon, scanner, analyst, reporter) are provided by plugins.
+"""
+
+from __future__ import annotations
+
+from hunterx.agents.base import AgentCapability, SecurityAgent
+from hunterx.agents.context import AgentContext
+from hunterx.agents.memory import AgentMemory
+from hunterx.agents.messaging import AgentMessage
+from hunterx.agents.orchestrator import AgentOrchestrator
+from hunterx.agents.registry import AgentRegistry
+from hunterx.agents.state import AgentState
+
+__all__ = [
+    "SecurityAgent",
+    "AgentCapability",
+    "AgentRegistry",
+    "AgentOrchestrator",
+    "AgentContext",
+    "AgentMemory",
+    "AgentMessage",
+    "AgentState",
+]

hunterx/agents/base.py

@@ -0,0 +1,71 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent abstraction.
+
+An agent is a specialized worker that performs a bounded set of security
+operations. Agents declare their capabilities, run within an orchestrated
+lifecycle, and communicate exclusively through :class:`AgentMessage`.
+"""
+
+from __future__ import annotations
+
+import abc
+from enum import Enum
+
+from hunterx.agents.context import AgentContext
+from hunterx.agents.memory import AgentMemory
+from hunterx.agents.messaging import AgentMessage
+from hunterx.agents.state import AgentState
+
+
+class AgentCapability(Enum):
+    """Capabilities an agent can declare."""
+
+    RECON = "recon"
+    SCAN = "scan"
+    DETECT = "detect"
+    ANALYZE = "analyze"
+    CORRELATE = "correlate"
+    REPORT = "report"
+    ENRICH = "enrich"
+
+
+class SecurityAgent(abc.ABC):
+    """Base class for all agents.
+
+    Subclasses implement :meth:`run`, which receives the agent context and
+    returns a list of messages to hand off to the orchestrator.
+    """
+
+    #: Unique agent name (e.g. ``"recon.agent"``).
+    name: str = ""
+    #: Human-readable description.
+    description: str = ""
+    #: Capabilities this agent provides.
+    capabilities: tuple[AgentCapability, ...] = ()
+
+    def __init__(self, memory: AgentMemory | None = None) -> None:
+        self._memory = memory or AgentMemory()
+        self._state = AgentState.IDLE
+
+    @property
+    def memory(self) -> AgentMemory:
+        """Return this agent's working memory."""
+        return self._memory
+
+    @abc.abstractmethod
+    def run(self, context: AgentContext) -> list[AgentMessage]:
+        """Execute the agent's work and return hand-off messages."""
+
+    def can(self, capability: AgentCapability) -> bool:
+        """Return ``True`` if the agent declares ``capability``."""
+        return capability in self.capabilities
+
+    @property
+    def state(self) -> AgentState:
+        """Return the agent's current lifecycle state."""
+        return self._state
+
+    def _transition(self, state: AgentState) -> None:
+        self._state = state

hunterx/agents/capabilities.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent capability helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from hunterx.agents.base import AgentCapability
+
+
+class CapabilitySet(frozenset):
+    """A frozenset of :class:`AgentCapability` values with query helpers."""
+
+    def __new__(cls, capabilities: Iterable[AgentCapability] = ()) -> CapabilitySet:
+        """Construct a frozen set from an iterable of capabilities."""
+        return super().__new__(cls, capabilities)  # type: ignore[arg-type]
+
+    def requires(self, capability: AgentCapability) -> bool:
+        """Return ``True`` when the set includes ``capability``."""
+        return capability in self
+
+    @classmethod
+    def from_names(cls, names: Iterable[str]) -> CapabilitySet:
+        """Build a set from capability names (case-insensitive)."""
+        return cls(AgentCapability(name) for name in names)

hunterx/agents/context.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class AgentContext:
+    """The execution context handed to an agent for a single run.
+
+    Attributes:
+        mission_id: owning mission.
+        target: target identifier the agent should operate on.
+        parameters: agent-specific run parameters.
+        workspace: scratch data shared across agents in a run.
+
+    """
+
+    mission_id: str
+    target: str = ""
+    parameters: dict[str, Any] = field(default_factory=dict)
+    workspace: dict[str, Any] = field(default_factory=dict)

hunterx/agents/coordinator.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent coordinator.
+
+Runs a multi-phase agent pipeline (recon → scan → analyze) for a mission by
+dispatching to agents at each phase and merging their results. This is the
+mission-level counterpart to the lower-level :class:`AgentOrchestrator`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from hunterx.agents.context import AgentContext
+from hunterx.agents.messaging import AgentMessage
+from hunterx.agents.orchestrator import AgentOrchestrator
+from hunterx.shared.result import Failure, Result, Success
+
+#: Default phase pipeline: ordered capability groups.
+_PIPELINE: tuple[tuple[str, ...], ...] = (
+    ("recon.enumerate", "recon.fingerprint"),
+    ("scan.vulnerabilities",),
+    ("analyze.correlate", "analyze.prioritize"),
+)
+
+
+class AgentCoordinator:
+    """Coordinate a phased agent run over a mission.
+
+    Each phase dispatches work to the named agents; if a phase has no agent
+    registered, it is skipped without failing the mission.
+    """
+
+    def __init__(self, orchestrator: AgentOrchestrator, *, pipeline: tuple[tuple[str, ...], ...] = _PIPELINE) -> None:
+        self._orchestrator = orchestrator
+        self._pipeline = pipeline
+
+    def run_mission(self, mission_id: str, *, targets: Iterable[str]) -> Result[list[AgentMessage], Exception]:
+        """Execute the pipeline across every target and merge the results."""
+        all_messages: list[AgentMessage] = []
+        for phase in self._pipeline:
+            for target in targets:
+                for agent_name in phase:
+                    context = AgentContext(mission_id=mission_id, target=target)
+                    outcome = self._orchestrator.dispatch(agent_name=agent_name, context=context)
+                    if isinstance(outcome, Failure):
+                        return outcome
+                    all_messages.extend(outcome.value)
+        return Success(all_messages)
+
+    @staticmethod
+    def collect_findings(messages: Iterable[AgentMessage]) -> list[dict[str, object]]:
+        """Extract ``finding``-kind payloads from merged agent messages."""
+        return [message.payload for message in messages if message.kind == "finding"]

hunterx/agents/events.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent event adapters.
+
+Converts agent messages into canonical domain events so the rest of the
+platform (event bus, telemetry, plugins) can observe agent activity uniformly.
+"""
+
+from __future__ import annotations
+
+from hunterx.agents.messaging import AgentMessage
+from hunterx.domain.events import DomainEvent
+
+
+def message_to_event(message: AgentMessage) -> DomainEvent:
+    """Wrap an agent message as a domain event."""
+    return DomainEvent(
+        event_type=f"agent.{message.kind}",
+        payload={
+            "message_id": message.message_id,
+            "sender": message.sender,
+            "recipient": message.recipient,
+            "data": message.payload,
+        },
+        source=message.sender,
+        occurred_at=message.created_at,
+    )

hunterx/agents/memory.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent memory."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+
+class AgentMemory:
+    """A bounded, thread-safe working memory for a single agent.
+
+    Stores observations and results as key/value entries. Used for the
+    lifetime of a mission run; long-term knowledge belongs in the knowledge
+    engine instead.
+    """
+
+    def __init__(self, *, max_entries: int = 1000) -> None:
+        self._max_entries = max_entries
+        self._entries: dict[str, Any] = {}
+        self._lock = threading.RLock()
+
+    def store(self, key: str, value: Any) -> None:
+        """Store or overwrite an entry."""
+        with self._lock:
+            if key not in self._entries and len(self._entries) >= self._max_entries:
+                # Evict the oldest entry to keep the memory bounded.
+                self._entries.pop(next(iter(self._entries)))
+            self._entries[key] = value
+
+    def retrieve(self, key: str) -> Any | None:
+        """Return an entry by key or ``None``."""
+        with self._lock:
+            return self._entries.get(key)
+
+    def forget(self, key: str) -> None:
+        """Remove an entry by key."""
+        with self._lock:
+            self._entries.pop(key, None)
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a shallow copy of all entries."""
+        with self._lock:
+            return dict(self._entries)
+
+    def clear(self) -> None:
+        """Remove all entries."""
+        with self._lock:
+            self._entries.clear()

hunterx/agents/messaging.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent messaging."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from hunterx.shared.ids import generate_id
+from hunterx.shared.time import utcnow_iso
+
+
+@dataclass(frozen=True, slots=True)
+class AgentMessage:
+    """A message exchanged between agents or between an agent and a caller.
+
+    Attributes:
+        sender: agent name that produced the message.
+        recipient: target agent name (``"*"`` for broadcast).
+        kind: message kind (``finding``, ``request``, ``result``, ``event``).
+        payload: JSON-serializable content.
+
+    """
+
+    sender: str
+    recipient: str = "*"
+    kind: str = "event"
+    payload: dict[str, Any] = field(default_factory=dict)
+    message_id: str = field(default_factory=generate_id)
+    created_at: str = field(default_factory=utcnow_iso)

hunterx/agents/orchestrator.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent orchestrator.
+
+Routes messages to the right agents and sequences multi-agent runs. The
+orchestrator is dependency-injection friendly: agents are supplied by a
+registry, and routing policy is pluggable.
+"""
+
+from __future__ import annotations
+
+from hunterx.agents.base import AgentCapability, SecurityAgent
+from hunterx.agents.context import AgentContext
+from hunterx.agents.messaging import AgentMessage
+from hunterx.agents.registry import AgentRegistry
+from hunterx.domain.exceptions import OperationError, PluginNotFoundError
+from hunterx.shared.result import Failure, Result, Success
+
+
+class AgentOrchestrator:
+    """Dispatch work to capable agents and fan their results back."""
+
+    def __init__(self, registry: AgentRegistry) -> None:
+        self._registry = registry
+
+    def dispatch(
+        self,
+        *,
+        capability: AgentCapability | None = None,
+        agent_name: str | None = None,
+        context: AgentContext,
+    ) -> Result[list[AgentMessage], Exception]:
+        """Run the agent(s) matching ``capability`` or ``agent_name``.
+
+        Only one of ``capability`` / ``agent_name`` may be given. Returns the
+        collected messages produced by the executed agents.
+        """
+        if agent_name is not None and capability is not None:
+            return Failure(OperationError("Specify either agent_name or capability, not both."))
+
+        agents: list[SecurityAgent]
+        if agent_name is not None:
+            try:
+                agents = [self._registry.get(agent_name)]
+            except PluginNotFoundError as exc:
+                return Failure(exc)
+        elif capability is not None:
+            agents = [agent for agent in self._registry.list() if agent.can(capability)]
+        else:
+            return Failure(OperationError("Specify agent_name or capability to dispatch."))
+
+        messages: list[AgentMessage] = []
+        for agent in agents:
+            try:
+                messages.extend(agent.run(context))
+            except Exception as exc:
+                return Failure(exc)
+        return Success(messages)

hunterx/agents/registry.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent registry."""
+
+from __future__ import annotations
+
+from threading import RLock
+
+from hunterx.agents.base import SecurityAgent
+from hunterx.domain.exceptions import DuplicateRegistrationError, PluginNotFoundError
+
+
+class AgentRegistry:
+    """Thread-safe registry of available agents."""
+
+    def __init__(self) -> None:
+        self._agents: dict[str, SecurityAgent] = {}
+        self._lock = RLock()
+
+    def register(self, agent: SecurityAgent) -> None:
+        """Register an agent instance by its name."""
+        with self._lock:
+            if agent.name in self._agents:
+                raise DuplicateRegistrationError(agent.name)
+            self._agents[agent.name] = agent
+
+    def unregister(self, name: str) -> None:
+        """Remove an agent by name."""
+        with self._lock:
+            self._agents.pop(name, None)
+
+    def get(self, name: str) -> SecurityAgent:
+        """Return an agent by name or raise :class:`PluginNotFoundError`."""
+        with self._lock:
+            agent = self._agents.get(name)
+        if agent is None:
+            raise PluginNotFoundError(name)
+        return agent
+
+    def list(self) -> list[SecurityAgent]:
+        """Return all registered agents."""
+        with self._lock:
+            return list(self._agents.values())

hunterx/agents/scheduler.py

@@ -0,0 +1,95 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent scheduler.
+
+Dispatches agent runs on a recurring schedule. This is the agent-level
+scheduler; mission-level schedules belong to :mod:`hunterx.scheduler`.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+
+from hunterx.agents.context import AgentContext
+from hunterx.agents.orchestrator import AgentOrchestrator
+from hunterx.shared.result import Failure
+
+
+@dataclass(frozen=True, slots=True)
+class AgentSchedule:
+    """A recurring agent dispatch.
+
+    Attributes:
+        name: unique schedule name.
+        agent_name: agent to dispatch.
+        interval_seconds: seconds between dispatches.
+        mission_id: mission to attach to the context.
+        target: target identifier for the context.
+        parameters: extra run parameters.
+
+    """
+
+    name: str
+    agent_name: str
+    interval_seconds: float
+    mission_id: str = ""
+    target: str = ""
+    parameters: dict[str, object] = field(default_factory=dict)
+
+
+class AgentScheduler:
+    """Schedule agent dispatches in a background thread.
+
+    Each schedule runs independently; a failed dispatch is recorded and does
+    not stop future dispatches of that schedule.
+    """
+
+    def __init__(self, orchestrator: AgentOrchestrator) -> None:
+        self._orchestrator = orchestrator
+        self._schedules: dict[str, AgentSchedule] = {}
+        self._last_run: dict[str, float] = {}
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def register(self, schedule: AgentSchedule) -> None:
+        """Register a recurring schedule."""
+        self._schedules[schedule.name] = schedule
+        self._last_run[schedule.name] = 0.0
+
+    def start(self) -> None:
+        """Start the background dispatch loop."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, name="hunterx-agent-scheduler", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the background dispatch loop."""
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            now = time.monotonic()
+            for schedule in list(self._schedules.values()):
+                if now - self._last_run[schedule.name] >= schedule.interval_seconds:
+                    self._last_run[schedule.name] = now
+                    self._dispatch(schedule)
+            self._stop.wait(1.0)
+
+    def _dispatch(self, schedule: AgentSchedule) -> None:
+        context = AgentContext(
+            mission_id=schedule.mission_id,
+            target=schedule.target,
+            parameters=dict(schedule.parameters),
+        )
+        outcome = self._orchestrator.dispatch(agent_name=schedule.agent_name, context=context)
+        if isinstance(outcome, Failure):
+            # Recorded only; the loop keeps scheduling.
+            return

hunterx/agents/state.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent state."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AgentState(Enum):
+    """Lifecycle states of an agent."""
+
+    IDLE = "idle"
+    ACTIVE = "active"
+    BLOCKED = "blocked"
+    STOPPED = "stopped"

hunterx/api/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Ahmed Awad (NullC0d3)
+# SPDX-License-Identifier: Apache-2.0
+
+"""REST API framework.
+
+Provides a FastAPI application factory, a router registry for endpoint
+definition, base schemas and dependency helpers. Importing ``hunterx.api``
+never requires FastAPI; it is only needed to build the app.
+"""
+
+from __future__ import annotations
+
+from hunterx.api.router import ApiRouter, RouteSpec
+from hunterx.api.schemas import ErrorResponse
+
+__all__ = ["ApiRouter", "RouteSpec", "ErrorResponse"]