HOVEL // chapter 03
Chapter 03 Part 01 / Foundations

Safety and Scope

Hovel is intended for authorized security testing, adversary emulation, internal lab research, CTF-style training, defensive validation, and controlled red-team development.

The framework may orchestrate dangerous primitives because realistic security tooling often requires them. Public documentation and examples should emphasize authorization, lab use, auditability, reproducibility, and operator accountability.

Public examples should prefer benign transports, local lab devices, toy payloads, and non-destructive demonstrations. The first demonstration may use authenticated SSH because it is easy to reason about, easy to log, and does not require publishing exploit code.

Caller Trust Model

Hovel does not treat human operators, AI agents, CLI clients, TUI clients, REST clients, or MCP clients as inherently trusted. Every caller uses the same application services, validation model, scope guardrails, and audit trail.

MCP should eventually be able to do everything an operator can do. Safety should come from shared guardrails, explicit confirmations, descriptor metadata, module-level validation, throw planning, and auditability, not from giving MCP a weaker private API.

Full MCP execution parity should be phased. Inspection and planning tools may ship first. Execution tools require the same plan review, explicit confirmation records, and audit events as CLI and REST.

Launch-key policy is the optional multi-entity gate for throws. In that mode, an agent can prepare a throw, but starting it requires every required operation entity to approve the exact reviewed plan hash according to daemon policy.

Third-party modules and services are explicitly supported. Installing a module is a trust decision: package scripts and module execution can run arbitrary code as the operator. Hovel provides descriptors, process supervision, scope guardrails, logs, artifacts, checksums, and replayable records so operators can make informed decisions, but it does not prove arbitrary third-party code is safe.

Safety Requirements

  1. Every throw must start from a persisted throw plan.
  2. Starting a throw must require an explicit recorded confirmation that the plan was reviewed. In interactive flows this means the operator saw the final configuration and typed yes, or deliberately used throw --now.
  3. Throws must record operator intent, reviewed configuration, target IDs, timestamps, resolved module package references, installed payload descriptors, materialized artifact hashes, structured events, and errors.
  4. Public modules should avoid destructive behavior by default.
  5. Throws block modules tagged dangerous unless the operator passes --allow-dangerous or enables the equivalent workspace policy.
  6. Listeners binding beyond localhost should require explicit configuration.
  7. MCP execution tools should require the same validation and audit trail as CLI and REST execution.
  8. Artifacts should be content-addressed or hash-tracked.
  9. Cleanup surfaces, such as installed-payload state changes and cleanup steps, must be visible and evented.
  10. Throw plans surface the reviewed chain, target, module/step, configuration snapshot, risk labels, external binds, file writes, credential use, network reachability, and cleanup behavior before execution.
  11. Modules should have maximum practical optionality to perform validation, survey, compatibility checks, and target-specific safety checks before performing work.

Core payload providers with post-exploitation capabilities, including Squatter, must carry the dangerous tag when they participate in throws. The guardrail enforces that tag through --allow-dangerous or workspace policy. Review output surfaces payload capabilities, transport, whether communication is encrypted, listener or post-connect behavior, produced payload artifact hashes, installed payload handles, reconnect behavior, and cleanup handles.

Installed payload inventory is an audit surface. Hovel must create or update it only from explicit provider or module descriptors, never by inferring state from terminal text or generic artifacts. Every installed payload state change must be recorded as a structured event with operation, chain, target, throw, run, and provider provenance when those fields are known.

throw --now is an explicit bypass of the typed confirmation prompt, not a bypass of planning, persistence, guardrails, logging, artifact handling, or audit records. The confirmation record for a --now throw must preserve that the bypass flag was used.

Hovel does not impose corporate secret-management behavior on chain configuration. Passwords, tokens, keys, and other sensitive values are ordinary operator-controlled configuration values. Operators are responsible for securing their machines, workspaces, and data sources. Hovel supports config value types and validation, but it must not silently redact, omit, or special-case saved configuration values in a way that degrades offensive workflow ergonomics.

Code Trust Model

Hovel assumes local single-user or trusted small-team infrastructure, but not trusted intent. The operator chooses modules and services to install and throw, while Hovel records decisions and enforces configured scope guardrails. Hovel isolates where practical, but never implies that arbitrary third-party code is safe.

Isolation levels:

none        local process, full user privileges
process     separate supervised process
venv        Python virtual environment isolation
pbs         python-build-standalone runtime isolation
binary      native binary process isolation
container   future optional container isolation
remote      future remote service isolation