hovel-sdk 0.1.0__tar.gz

hovel_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: hovel-sdk
+Version: 0.1.0
+Summary: Python SDK for Hovel JSON-RPC modules
+Requires-Python: >=3.12

hovel_sdk-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Python SDK
+
+The Python SDK is the quickest path for exploit, survey, and post-exploitation
+module work. Copy one of the examples in [`../../examples/python`](../../examples/python)
+and keep the public boundary small: subclass `HovelModule`, describe cheap
+metadata/configuration, then put target interaction in `run` or explicit step
+hooks.
+
+## Module Shape
+
+```python
+from hovel_sdk import Context, HovelModule, Requirement, Result, serve
+
+
+class MyModule(HovelModule):
+    name = "my-module"
+    version = "v0.1.0"
+    module_type = "exploit"
+    summary = "Run a scoped module action."
+    target_config = (
+        Requirement("target.host", "host", description="Target host or IP."),
+    )
+
+    def run(self, ctx: Context) -> Result:
+        ctx.log.info("module started", extra={"target": ctx.target})
+        return Result.ok({"target": ctx.target}, summary="module completed")
+
+
+if __name__ == "__main__":
+    serve(MyModule())
+```
+
+Rules that matter in real integrations:
+
+- Never print to stdout. The SDK uses stdout for framed JSON-RPC responses and
+  notifications.
+- Use `ctx.log` for progress and diagnostics; Hovel turns those into
+  `module/log` notifications.
+- Keep `info()` and `module_schema()` side-effect free. Hovel calls them while
+  cataloging modules.
+- Use `Result.ok` or `Result.failed`; attach `Finding`, `Artifact`,
+  `SessionRef`, and `InstalledPayload` values deliberately.
+
+## Extension Points
+
+| Need | Use |
+| --- | --- |
+| Regular module execution | `run(ctx) -> Result` or an awaitable `Result`. |
+| Config requirements | `Requirement` in `global_config` and `target_config`. |
+| Line-oriented post-exploitation sessions | `LineShellSession` opened with `await ctx.open_session(...)`. |
+| Durable installed payload inventory | `InstalledPayload` and `PayloadProviderRecord` in a result. |
+| Typed chain steps | Override `describe_steps`, `prepare_step`, `execute_step`, and `cleanup_step`. |
+
+Python does not currently dispatch payload-provider RPC methods such as
+`list_payloads` or `generate_payload`. Use Go for provider modules today, or
+return installed-payload descriptors from a Python exploit when it installs or
+observes a durable payload.
+
+## Test Loop
+
+Use `ModuleRPC` to test through the same framed protocol the daemon uses. This
+catches broken method names, result shapes, log notifications, and session
+round trips without starting `hoveld`.
+
+```python
+from hovel_sdk import ModuleRPC
+
+
+def test_module_executes():
+    with ModuleRPC(MyModule()) as rpc:
+        result = rpc.call("execute", {"runId": "run-1", "target": "lab-1"})
+
+    assert result["status"] == "succeeded"
+```
+
+Focused checks:
+
+```sh
+task test -- //sdk/python:hovel_sdk_test
+task test -- //examples/python/...
+task python:check
+```
+
+Full gate:
+
+```sh
+task ci
+```
+
+For deeper examples, compare:
+
+- [`../../examples/python/mock_survey`](../../examples/python/mock_survey)
+- [`../../examples/python/mock_exploit`](../../examples/python/mock_exploit)
+- [`../../examples/python/mock_exploit_session`](../../examples/python/mock_exploit_session)
+- [`../../examples/python/etro_exploit`](../../examples/python/etro_exploit)

hovel_sdk-0.1.0/hovel_sdk/__init__.py

@@ -0,0 +1,29 @@
+from hovel_sdk.config import Requirement
+from hovel_sdk.context import AgentContext, AgentEntity, Context
+from hovel_sdk.logging import setup_logging
+from hovel_sdk.module import HovelModule
+from hovel_sdk.result import AgentHint, Artifact, Finding, InstalledPayload, PayloadProviderRecord, Result
+from hovel_sdk.server import serve
+from hovel_sdk.session import LineShellSession, SessionRef
+from hovel_sdk.testing import ModuleRPC, RPCError, drive_module
+
+__all__ = [
+    "AgentContext",
+    "AgentEntity",
+    "AgentHint",
+    "Artifact",
+    "Context",
+    "Finding",
+    "HovelModule",
+    "InstalledPayload",
+    "LineShellSession",
+    "ModuleRPC",
+    "PayloadProviderRecord",
+    "RPCError",
+    "Requirement",
+    "Result",
+    "SessionRef",
+    "drive_module",
+    "serve",
+    "setup_logging",
+]

hovel_sdk-0.1.0/hovel_sdk/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Requirement:
+    key: str
+    type: str = "string"
+    required: bool = True
+    default: str = ""
+    description: str = ""
+    allowed: list[str] = field(default_factory=list)
+    secret: bool = False
+
+    def to_rpc(self) -> dict[str, Any]:
+        return {
+            "key": self.key,
+            "type": self.type,
+            "required": self.required,
+            "default": self.default,
+            "description": self.description,
+            "allowed": list(self.allowed),
+            "secret": self.secret,
+        }

hovel_sdk-0.1.0/hovel_sdk/context.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from hovel_sdk.session import Session, SessionRef
+
+if TYPE_CHECKING:
+    from hovel_sdk.session import SessionRegistry
+
+
+@dataclass(frozen=True)
+class AgentEntity:
+    id: str = ""
+    kind: str = ""
+    display_name: str = ""
+    agent: bool = False
+
+    @classmethod
+    def from_rpc(cls, value: Any) -> AgentEntity:
+        if not isinstance(value, dict):
+            return cls()
+        return cls(
+            id=str(value.get("id", "")),
+            kind=str(value.get("kind", "")),
+            display_name=str(value.get("displayName", "")),
+            agent=bool(value.get("agent", False)),
+        )
+
+
+@dataclass(frozen=True)
+class AgentContext:
+    schema: str = ""
+    entity: AgentEntity = field(default_factory=AgentEntity)
+    operation: str = ""
+    chain: str = ""
+    plan_id: str = ""
+    plan_hash: str = ""
+    approval_state: str = ""
+    phase: str = ""
+    resources: tuple[str, ...] = ()
+
+    @classmethod
+    def from_rpc(cls, value: Any) -> AgentContext | None:
+        if not isinstance(value, dict):
+            return None
+        resources = value.get("resources") or ()
+        if not isinstance(resources, (list, tuple)):
+            resources = ()
+        return cls(
+            schema=str(value.get("schema", "")),
+            entity=AgentEntity.from_rpc(value.get("entity")),
+            operation=str(value.get("operation", "")),
+            chain=str(value.get("chain", "")),
+            plan_id=str(value.get("planId", "")),
+            plan_hash=str(value.get("planHash", "")),
+            approval_state=str(value.get("approvalState", "")),
+            phase=str(value.get("phase", "")),
+            resources=tuple(str(item) for item in resources),
+        )
+
+
+@dataclass(frozen=True)
+class Context:
+    run_id: str
+    module_id: str
+    target: str
+    inputs: dict[str, Any] = field(default_factory=dict)
+    chain_config: dict[str, Any] = field(default_factory=dict)
+    target_config: dict[str, Any] = field(default_factory=dict)
+    agent: AgentContext | None = None
+    log: logging.Logger = field(default_factory=lambda: logging.getLogger("hovel.module"))
+    sessions: SessionRegistry | None = field(default=None, repr=False)
+
+    def input(self, key: str, default: Any = None) -> Any:
+        if key in self.inputs:
+            return self.inputs[key]
+        if key in self.target_config:
+            return self.target_config[key]
+        return self.chain_config.get(key, default)
+
+    async def open_session(
+        self,
+        session: Session,
+        *,
+        name: str = "",
+        kind: str = "shell",
+        transport: str = "stdio",
+        capabilities: tuple[str, ...] = ("read", "write", "close"),
+    ) -> SessionRef:
+        if self.sessions is None:
+            raise RuntimeError("session support is not available in this runtime")
+        return await self.sessions.open(
+            session,
+            name=name,
+            kind=kind,
+            transport=transport,
+            capabilities=capabilities,
+        )

hovel_sdk-0.1.0/hovel_sdk/framing.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any, BinaryIO
+
+MAX_FRAME_BYTES = 64 * 1024 * 1024
+
+
+class FrameError(Exception):
+    pass
+
+
+def encode_message(message: dict[str, Any]) -> bytes:
+    body = json.dumps(message, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return b"Content-Length: " + str(len(body)).encode("ascii") + b"\r\n\r\n" + body
+
+
+def read_message(stream: BinaryIO) -> dict[str, Any] | None:
+    header = _read_until(stream, b"\r\n\r\n")
+    if header == b"":
+        return None
+    content_length = _content_length_from_header(header)
+    body = stream.read(content_length)
+    if len(body) != content_length:
+        raise FrameError("truncated frame body")
+    return _decode_message_body(body)
+
+
+def _content_length_from_header(header: bytes) -> int:
+    content_length: int | None = None
+    for line in header.decode("ascii").split("\r\n"):
+        if not line:
+            continue
+        name, sep, value = line.partition(":")
+        if sep == "" or name.lower() != "content-length":
+            continue
+        try:
+            content_length = int(value.strip())
+        except ValueError as exc:
+            raise FrameError("invalid Content-Length") from exc
+    if content_length is None:
+        raise FrameError("missing Content-Length")
+    if content_length < 0:
+        raise FrameError("invalid Content-Length")
+    if content_length > MAX_FRAME_BYTES:
+        raise FrameError(f"Content-Length {content_length} exceeds maximum {MAX_FRAME_BYTES}")
+    return content_length
+
+
+def _decode_message_body(body: bytes) -> dict[str, Any]:
+    try:
+        decoded = json.loads(body.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise FrameError("invalid JSON frame body") from exc
+    if not isinstance(decoded, dict):
+        raise FrameError("JSON-RPC message must be an object")
+    return decoded
+
+
+def write_message(stream: BinaryIO, message: dict[str, Any]) -> None:
+    stream.write(encode_message(message))
+    stream.flush()
+
+
+class MessageWriter:
+    """Serialize framed writes to one stream.
+
+    A module may emit logs or session notifications from code paths that overlap
+    request handling. The protocol is stdout-framed, so every frame write must
+    be atomic with respect to other frame writes.
+    """
+
+    def __init__(self, stream: BinaryIO) -> None:
+        self._stream = stream
+        self._lock = threading.Lock()
+
+    def write(self, message: dict[str, Any]) -> None:
+        encoded = encode_message(message)
+        with self._lock:
+            self._stream.write(encoded)
+            self._stream.flush()
+
+
+def _read_until(stream: BinaryIO, marker: bytes) -> bytes:
+    data = bytearray()
+    while True:
+        chunk = stream.read(1)
+        if chunk == b"":
+            if not data:
+                return b""
+            raise FrameError("truncated frame header")
+        data.extend(chunk)
+        if data.endswith(marker):
+            return bytes(data[: -len(marker)])

hovel_sdk-0.1.0/hovel_sdk/logging.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import logging
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+_RESERVED = set(logging.LogRecord("", 0, "", 0, "", (), None).__dict__.keys())
+
+
+class RPCLogHandler(logging.Handler):
+    def __init__(self, emit: Callable[[dict[str, Any]], None]) -> None:
+        super().__init__()
+        self._emit = emit
+
+    def emit(self, record: logging.LogRecord) -> None:
+        fields: dict[str, Any] = {}
+        for key, value in record.__dict__.items():
+            if key.startswith("_") or key in _RESERVED:
+                continue
+            fields[key] = value
+        params: dict[str, Any] = {
+            "level": record.levelname.lower(),
+            "message": record.getMessage(),
+            "logger": record.name,
+            "fields": fields,
+        }
+        if record.exc_info:
+            params["exception"] = "".join(traceback.format_exception(*record.exc_info))
+        self._emit(params)
+
+
+def setup_logging(emit: Callable[[dict[str, Any]], None] | None = None) -> RPCLogHandler:
+    if emit is None:
+        def emit(_params: dict[str, Any]) -> None:
+            return
+
+    handler = RPCLogHandler(emit)
+    root = logging.getLogger()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+    return handler

hovel_sdk-0.1.0/hovel_sdk/module.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable
+from typing import Any, ClassVar
+
+from hovel_sdk.config import Requirement
+from hovel_sdk.context import Context
+from hovel_sdk.result import Result
+
+
+class HovelModule(ABC):
+    name: str = ""
+    version: str = "0.0.0"
+    summary: str = ""
+    module_type: str = ""
+    description: str = ""
+    tags: ClassVar[tuple[str, ...]] = ()
+    global_config: ClassVar[tuple[Requirement, ...]] = ()
+    target_config: ClassVar[tuple[Requirement, ...]] = ()
+    outputs: ClassVar[dict[str, Any]] = {}
+
+    def info(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "version": self.version,
+            "summary": self.summary,
+            "description": self.description,
+            "moduleType": self.module_type,
+            "tags": list(self.tags),
+        }
+
+    def module_schema(self) -> dict[str, Any]:
+        return {
+            "chainConfig": [requirement.to_rpc() for requirement in self.global_config],
+            "targetConfig": [requirement.to_rpc() for requirement in self.target_config],
+            "outputs": dict(self.outputs),
+        }
+
+    def describe_steps(self) -> dict[str, Any]:
+        return {"steps": []}
+
+    def prepare_step(self, request: dict[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError(f"{self.name or self.__class__.__name__} does not implement step.prepare")
+
+    def execute_step(self, request: dict[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError(f"{self.name or self.__class__.__name__} does not implement step.execute")
+
+    def cleanup_step(self, request: dict[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError(f"{self.name or self.__class__.__name__} does not implement step.cleanup")
+
+    @abstractmethod
+    def run(self, ctx: Context) -> Result | Awaitable[Result]:
+        raise NotImplementedError

hovel_sdk-0.1.0/hovel_sdk/result.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from hovel_sdk.session import SessionRef
+
+
+@dataclass(frozen=True)
+class AgentHint:
+    phase: str
+    audience: str
+    risk: str
+    text: str
+    schema: str = "hovel.agent_hint.v1"
+    applies_to: dict[str, str] = field(default_factory=dict)
+    provenance: dict[str, str] = field(default_factory=dict)
+
+    def to_rpc(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "schema": self.schema,
+            "phase": self.phase,
+            "audience": self.audience,
+            "risk": self.risk,
+            "text": self.text,
+        }
+        if self.applies_to:
+            out["appliesTo"] = dict(self.applies_to)
+        if self.provenance:
+            out["provenance"] = dict(self.provenance)
+        return out
+
+
+@dataclass(frozen=True)
+class Finding:
+    title: str
+    severity: str = "info"
+    detail: str = ""
+
+    def to_rpc(self) -> dict[str, Any]:
+        return {"title": self.title, "severity": self.severity, "detail": self.detail}
+
+
+@dataclass(frozen=True)
+class Artifact:
+    name: str
+    kind: str
+    data: str = ""
+    path: str = ""
+
+    @classmethod
+    def inline(cls, name: str, kind: str, data: str | bytes) -> Artifact:
+        if isinstance(data, bytes):
+            data = data.decode("utf-8", errors="replace")
+        return cls(name=name, kind=kind, data=data)
+
+    @classmethod
+    def text(cls, name: str, data: str | bytes) -> Artifact:
+        return cls.inline(name, "text/plain", data)
+
+    @classmethod
+    def json(cls, name: str, data: Any) -> Artifact:
+        return cls.inline(name, "application/json", json.dumps(data, sort_keys=True, separators=(",", ":")))
+
+    @classmethod
+    def file(cls, path: str | Path, *, name: str | None = None, kind: str = "application/octet-stream") -> Artifact:
+        path = Path(path)
+        return cls(name=name or path.name, kind=kind, path=str(path))
+
+    def to_rpc(self) -> dict[str, Any]:
+        out = {"name": self.name, "kind": self.kind}
+        if self.data:
+            out["data"] = self.data
+        if self.path:
+            out["path"] = self.path
+        return out
+
+
+@dataclass(frozen=True)
+class PayloadProviderRecord:
+    schema: str = ""
+    descriptor: dict[str, Any] = field(default_factory=dict)
+    provider_id: str = ""
+    schema_version: str = ""
+
+    def to_rpc(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.provider_id:
+            out["providerId"] = self.provider_id
+        if self.schema:
+            out["schema"] = self.schema
+        if self.schema_version:
+            out["schemaVersion"] = self.schema_version
+        if self.descriptor:
+            out["descriptor"] = dict(self.descriptor)
+        return out
+
+
+@dataclass(frozen=True)
+class InstalledPayload:
+    provider: str
+    payload_id: str
+    target: str
+    state: str
+    payload_version: str = ""
+    target_id: str = ""
+    transport: str = ""
+    endpoint: str = ""
+    instance_key: str = ""
+    stamp_id: str = ""
+    supports_reconnect: bool = False
+    supports_multiple_sessions: bool = False
+    reconnect: PayloadProviderRecord | None = None
+    cleanup: PayloadProviderRecord | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_rpc(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "provider": self.provider,
+            "payloadId": self.payload_id,
+            "target": self.target,
+            "state": self.state,
+        }
+        optional_strings = {
+            "payloadVersion": self.payload_version,
+            "targetId": self.target_id,
+            "transport": self.transport,
+            "endpoint": self.endpoint,
+            "instanceKey": self.instance_key,
+            "stampId": self.stamp_id,
+        }
+        out.update({key: value for key, value in optional_strings.items() if value})
+        if self.supports_reconnect:
+            out["supportsReconnect"] = True
+        if self.supports_multiple_sessions:
+            out["supportsMultipleSessions"] = True
+        if self.reconnect is not None:
+            out["reconnect"] = self.reconnect.to_rpc()
+        if self.cleanup is not None:
+            out["cleanup"] = self.cleanup.to_rpc()
+        if self.metadata:
+            out["metadata"] = dict(self.metadata)
+        return out
+
+
+@dataclass(frozen=True)
+class Result:
+    status: str
+    summary: str
+    findings: list[Finding] = field(default_factory=list)
+    artifacts: list[Artifact] = field(default_factory=list)
+    outputs: dict[str, Any] = field(default_factory=dict)
+    sessions: list[SessionRef] = field(default_factory=list)
+    installed_payloads: list[InstalledPayload | dict[str, Any]] = field(default_factory=list)
+    agent_hints: list[AgentHint | dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def ok(
+        cls,
+        outputs: dict[str, Any] | None = None,
+        *,
+        summary: str = "module completed",
+        findings: list[Finding] | None = None,
+        artifacts: list[Artifact] | None = None,
+        sessions: list[SessionRef] | None = None,
+    ) -> Result:
+        return cls(
+            status="succeeded",
+            summary=summary,
+            findings=findings or [],
+            artifacts=artifacts or [],
+            outputs=outputs or {},
+            sessions=sessions or [],
+        )
+
+    @classmethod
+    def failed(
+        cls,
+        summary: str,
+        *,
+        findings: list[Finding] | None = None,
+        artifacts: list[Artifact] | None = None,
+        outputs: dict[str, Any] | None = None,
+        sessions: list[SessionRef] | None = None,
+    ) -> Result:
+        return cls(
+            status="failed",
+            summary=summary,
+            findings=findings or [],
+            artifacts=artifacts or [],
+            outputs=outputs or {},
+            sessions=sessions or [],
+        )
+
+    def with_installed_payloads(self, *payloads: InstalledPayload | dict[str, Any]) -> Result:
+        return replace(self, installed_payloads=[*self.installed_payloads, *payloads])
+
+    def with_agent_hints(self, *hints: AgentHint | dict[str, Any]) -> Result:
+        return replace(self, agent_hints=[*self.agent_hints, *hints])
+
+    def to_rpc(self, *, sessions: list[SessionRef] | None = None) -> dict[str, Any]:
+        session_refs = list(self.sessions)
+        if sessions:
+            seen = {session.id for session in session_refs}
+            session_refs.extend(session for session in sessions if session.id not in seen)
+        out = {
+            "status": self.status,
+            "summary": self.summary,
+            "findings": [finding.to_rpc() for finding in self.findings],
+            "artifacts": [artifact.to_rpc() for artifact in self.artifacts],
+            "outputs": dict(self.outputs),
+            "sessions": [session.to_rpc() for session in session_refs],
+        }
+        if self.installed_payloads:
+            out["installedPayloads"] = [
+                payload.to_rpc() if hasattr(payload, "to_rpc") else dict(payload)
+                for payload in self.installed_payloads
+            ]
+        if self.agent_hints:
+            out["agentHints"] = [
+                hint.to_rpc() if hasattr(hint, "to_rpc") else dict(hint)
+                for hint in self.agent_hints
+            ]
+        return out