docker-intrude

Linux statically-linked utility that executes local host binaries inside a specific Docker network namespace.

It spins up a temporary container with a static IP, uses nsenter to attach your command to its network, and runs it under your current user.

Security & Trust Model

By default, docker-intrude is designed to run tools that require Linux file capabilities (like /bin/ping or gdb). To balance usability and security, it applies the following isolation measures before executing your command:

• Capability Shedding: Drops all Effective, Permitted, Inheritable, and Ambient capabilities.
• Setuid Protection: Activates SECBIT_NOROOT to prevent legacy setuid-root binaries from automatically acquiring root privileges during execution.
• Bounding Set Preservation: Leaves the Capability Bounding Set intact by default so that legitimate file capabilities continue to function.

Accepted Design Tradeoffs & Operational Limits

Because docker-intrude is designed as a local development and debugging wrapper, certain operational behaviors are intentional tradeoffs:

• Environment Variable Inheritance: The target command inherits your current environment variables unaltered (including PATH, HOME, and API tokens). This is required for build tools (like Maven, Gradle, or npm) to function properly, but means docker-intrude does not scrub sensitive variables from the target process.
• Elevated File Capabilities (setcap): The binary requires cap_sys_admin, cap_sys_ptrace, and cap_setpcap to manipulate kernel network namespaces without sudo. Users in the local docker group are already equivalent to root on Linux systems; these capabilities are restricted to executing namespaces and should only be installed on single-tenant or trusted developer workstations.
• Custom Socket Paths (DOCKER_HOST): The tool honors the DOCKER_HOST environment variable if pointing to a local UNIX socket. While docker-intrude validates that the socket owner matches the current user or root, users should ensure their environment variables are not manipulated.

Strict Mode (--strict)

If your command doesn't need file capabilities, or if you prefer maximum privilege isolation, pass the --strict flag to clear the Bounding Set as well:

docker-intrude --name my-project --net dev-net --ip 172.18.0.22 --strict -- ping 172.18.0.1

How It Works & DNS Resolution

docker-intrude provisions a temporary network container to hold a specific Docker network namespace open.

It then uses kernel namespaces (setns) to attach your host command to that network.

Host binary would still read the host's /etc/resolv.conf and fail to resolve names in most distros. To address this without modifying your host filesystem, docker-intrude overrides the configuration:

1. It unshares the mount namespace (CLONE_NEWNS) to isolate filesystem changes from the host.
2. It marks the root mount as private (MS_PRIVATE | MS_REC) to prevent mount propagation.
3. It creates a temporary file (/dev/shm) and writes Docker's embedded DNS configuration (nameserver 127.0.0.11\noptions ndots:0\n) to it.
4. It bind-mounts this file directly over /etc/resolv.conf and unlinks the source file from /dev/shm.

Prerequisites

• Linux only (relies on native kernel namespaces).
• Docker running and accessible.

Installation

Install the latest pre-compiled binary via curl:

curl -sSL \
  [https://github.com/optionfactory/docker-intrude/releases/latest/download/docker-intrude-linux-amd64-musl](https://github.com/optionfactory/docker-intrude/releases/latest/download/docker-intrude-linux-amd64-musl) \
  | sudo tee /usr/local/bin/docker-intrude > /dev/null \
  && sudo chown root:docker /usr/local/bin/docker-intrude \
  && sudo chmod 750 /usr/local/bin/docker-intrude \
  && sudo setcap cap_sys_admin,cap_sys_ptrace,cap_setpcap+ep /usr/local/bin/docker-intrude

Build from Source

Ensure you have Rust installed, then clone the repository and build:

git clone [https://github.com/optionfactory/docker-intrude](https://github.com/optionfactory/docker-intrude)
cd docker-intrude
make build-release 
make install

Usage

docker-intrude --name <name> --net <network> --ip <ip-address> [-v] -- <command...>

Example

Run a local Maven project inside the dev-net Docker network:

docker-intrude --name my-project --net dev-net --ip 172.18.0.22 -- ./mvn spring-boot:run

Options

• --name, -n : Name of the temporary Docker container.
• --net : The Docker network to join.
• --ip : The IP address to assign to the container.
• --verbose, -v : Enable detailed setup and status logging.
• -- : Separates wrapper arguments from the command being executed.