container_shell: isolated network by default, plus optional network transport

[anticomputer]

The container_shell MCP server currently starts its managed Docker container on the default bridge network, so any command run through shell_exec has unrestricted outbound network access. For an analysis sandbox that runs untrusted code and processes untrusted inputs, network access should be opt-in rather than the default. This PR makes that the default and, relatedly, lets the server itself run as a network-reachable MCP endpoint so it can be deployed as an isolated sidecar.

Isolated container network by default

This change starts containers with --network none by default, so the container is egress-locked unless a caller explicitly enables networking.

• Add a CONTAINER_NETWORK environment variable (default none) that selects the Docker network mode passed to docker run --network. Callers opt into networking by setting it to bridge, host, or a user-defined network name.
• Fail closed: an unset, empty, or whitespace-only value falls back to none, so the isolation default cannot be silently disabled by a blank variable.
• Expose CONTAINER_NETWORK on the container_shell toolboxes. The base, sast, and malware_analysis toolboxes inherit the isolated default; the network_analysis toolbox defaults to bridge because its recon tools (e.g. nmap) need egress.

Verified end-to-end against a real Docker daemon:

CONTAINER_NETWORK	HostConfig.NetworkMode	interfaces	egress to 1.1.1.1
unset	none	lo	BLOCKED
none	none	lo	BLOCKED
bridge	bridge	eth0, lo	REACHED

Selecting a network mode from a toolbox

The agent forwards only a toolbox's declared env entries to this server, so a network mode is run-time selectable only if the toolbox exposes the knob. A toolbox opts in with a passthrough line in its env block, e.g. CONTAINER_NETWORK: "{{ env('CONTAINER_NETWORK', 'none') }}" (use 'bridge' as the default for a toolbox that should be networked by default). A toolbox that omits the line inherits the isolated none default. This is documented in the container_shell module docstring.

Optional network transport

container_shell runs only over stdio today, as a subprocess launched locally by the agent. That is the right default when the server sits next to a local Docker daemon, but it means the server cannot be run as a standalone, network-reachable MCP endpoint. This adds an opt-in transport selector so the same server can also be served over HTTP/SSE and connected to as a remote MCP server, without changing existing behavior.

• CONTAINER_SHELL_TRANSPORT — MCP transport. Defaults to stdio (unchanged behavior). Set to http, streamable-http, or sse to serve over the network.
• CONTAINER_SHELL_HOST / CONTAINER_SHELL_PORT — bind address for the network transports (default 127.0.0.1 / 8080); ignored for stdio.
• A blank/whitespace CONTAINER_SHELL_TRANSPORT falls back to stdio, so the local default cannot be silently changed; an unknown transport raises a clear ValueError listing the supported values.

Which Docker daemon the server drives is orthogonal to the transport: the docker CLI already honours DOCKER_HOST from the environment, so pointing the server at a specific daemon needs no code change here.

Manual smoke test: started the server with CONTAINER_SHELL_TRANSPORT=http, confirmed it binds the configured host/port and answers an MCP initialize handshake over HTTP (serverInfo.name: "ContainerShell"), then verified the listener is released on shutdown.

Rename the tool to container_shell_exec

The shell tool is renamed from shell_exec to container_shell_exec so it is unambiguous when several MCP servers are loaded together. FastMCP derives the tool name from the function name, so the rename covers the tool definition, the confirm lists in every container shell toolbox, the tests, and the docs. Verified over MCP: list_tools against the running server returns ['container_shell_exec'].

Remote container shell toolbox

Adds container_shell_remote, a toolbox that connects to a container_shell server already running elsewhere over Streamable HTTP instead of launching it as a local stdio subprocess. The endpoint is read from CONTAINER_SHELL_URL. This is what lets a network-isolated agent use containerized shell execution without being handed a Docker socket: the server owns the daemon and is reached over a single allowlisted host service port.

This toolbox depends on GitHubSecurityLab/seclab-taskflow-agent#279, which env-templates the toolbox url so url: "{{ env('CONTAINER_SHELL_URL') }}" resolves at connect time. Verified by loading the real toolbox through the agent model and confirming the url resolves to the concrete endpoint.

Verification

Added unit tests covering the network default/opt-in/blank-fallback, persistent-container keying by network mode, the stdio transport default, blank-transport fallback, the host blank-fallback, lazy port parsing (an invalid port leaves stdio working but fails a network transport), the exact mcp.run(...) wiring for each network transport, and the unknown-transport error. Full container_shell suite passes (47 tests) and hatch fmt --linter --check is clean.

The tool rename keeps the full container_shell suite green (47 tests). The remote toolbox's url resolution is covered by the agent PR above.

[Copilot]

Pull request overview

This PR hardens the container_shell MCP server by making Docker containers start with networking disabled by default (--network none), requiring callers/toolboxes to explicitly opt into outbound connectivity via a new CONTAINER_NETWORK environment variable.

Changes:

• Add CONTAINER_NETWORK (defaulting to none, with blank/whitespace values failing closed to none) and pass it to docker run --network.
• Add unit tests covering default, opt-in (bridge), and unset/blank fallback behavior.
• Plumb CONTAINER_NETWORK through the container_shell toolbox YAMLs, with network_analysis defaulting to bridge.

Show a summary per file

File	Description
src/seclab_taskflows/mcp_servers/container_shell.py	Introduces CONTAINER_NETWORK and applies it to docker run for default network isolation.
tests/test_container_shell.py	Adds tests for default/opt-in/fallback network behavior.
src/seclab_taskflows/toolboxes/container_shell_base.yaml	Exposes CONTAINER_NETWORK to the base toolbox environment.
src/seclab_taskflows/toolboxes/container_shell_sast.yaml	Exposes CONTAINER_NETWORK to the SAST toolbox environment.
src/seclab_taskflows/toolboxes/container_shell_malware_analysis.yaml	Exposes CONTAINER_NETWORK to the malware analysis toolbox environment.
src/seclab_taskflows/toolboxes/container_shell_network_analysis.yaml	Exposes CONTAINER_NETWORK with a default of bridge for network tooling.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Low

[anticomputer]

Thanks for the review — both issues were valid and are addressed in 065b75b.

Persistent container reuse ignored network mode (flagged at _persistent_name and the reuse path): the configured network mode is now part of the persistent container name hash (key_material = f"{CONTAINER_IMAGE}:net={CONTAINER_NETWORK}"). A run configured for none therefore looks up a different container name than one created with bridge/host and never reuses a more-permissive container, so the isolation default holds for persistent runs too. Verified end-to-end against Docker with CONTAINER_PERSIST=true: a pre-existing bridge container (egress reachable) is not reused by a subsequent none run — a distinct container is created and egress is blocked.

step	CONTAINER_NETWORK	container	egress to 1.1.1.1
1	bridge	seclab-persist-02af9e7e5eb0	REACHED
2	none (same image, persist)	seclab-persist-574436321ef4	BLOCKED

Test reload leakage (flagged on the two fallback tests): the tests now capture the real CONTAINER_NETWORK value up front and restore it before the final importlib.reload, via a _restore_env_and_reload helper, so the reloaded module reflects the actual environment rather than the monkeypatched one and nothing leaks into later tests.

Added a test_persistent_name_varies_with_network unit test. Full suite: 33 passing, hatch fmt --linter --check clean.

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Low

[anticomputer]

Also addressed the second-pass note about atexit handler accumulation on reload (900131e): the tests now unregister the current _stop_container handler before every importlib.reload, so exactly one handler remains. Verified atexit._ncallbacks() stays flat across repeated dedup reloads (5 → 5) where a naive reload would accumulate (5 → 8). Suite still 33 passing, lint clean.

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Low