HostExec

HostExec is a secure host-agent architecture that allows binaries inside containers to request the execution of authorized commands on the host system via Unix Domain Sockets.

Features

• hostexec-daemon: A lightweight service running on the host that listens for execution requests.
• hostexec-client: A CLI binary used inside containers to communicate with the daemon.
• Real-time Streaming: Sub-second streaming of stdout and stderr.
• Comprehensive Exit Info: Returns exit codes, termination signals, and detailed error messages.
• Policy-driven Security:
  • Allowlist: Only explicitly defined commands in policy.toml are permitted.
  • Regex Validation: Arguments are validated using Perl-compatible regular expressions.
  • UID/GID Switching: Execute commands as specific host users or groups.
  • Environment Control: Only allowed environment variables are passed to the host command.
  • CWD Validation: Commands can be restricted to specific working directories.
  • Timeouts: Hard limits on command execution time to prevent hanging processes.
  • Resource Limits: Limits on output volume (bytes) to prevent DoS via log flooding.
• Stdin Support: Optional support for passing data to command stdin via Base64 encoding.
• Systemd Integration: Ready-to-use unit files for daemon management.

Project Structure

• hostexec-daemon/: Rust implementation of the host service.
• hostexec-client/: Rust implementation of the container CLI tool.
• examples/: Example Dockerfiles and a sample policy.toml.
• systemd/: Service definitions for Linux distribution deployment.

Getting Started

1. Build the components

cargo build --release

2. Configure the Policy

Create /etc/hostexec/policy.toml on the host:

[global]
socket_path = "/run/hostexec/hostexec.sock"
max_args = 64
default_timeout_secs = 60

[command.uname]
path = "/usr/bin/uname"
allowed_args_regex = '^(-[a-zA-Z]+)?$'
max_timeout_secs = 5

3. Run the Daemon

The daemon requires root privileges (or sufficient permissions) to listen on the socket and switch UIDs.

sudo ./target/release/hostexec-daemon

4. Execute from Container

Mount the Unix socket into your container and run:

hostexec uname -a

Security Model

HostExec follows a "zero-trust" approach toward the container. The daemon validates every aspect of the request (PID/UID of the caller, command path, arguments, and environment) against its local policy before spawning any process on the host.