- Shell 95.5%
- Dockerfile 4.5%
|
|
||
|---|---|---|
| app | ||
| haproxy | ||
| tests | ||
| .gitignore | ||
| app-firewall.sh | ||
| devcontainer-lock.json | ||
| devcontainer.json | ||
| docker-compose.yml | ||
| generate-repo-mounts.sh | ||
| install-egress-proxy.sh | ||
| nuget.env.example | ||
| readme.md | ||
| repos.env.example | ||
| setup-claude-plugins.sh | ||
| setup-nuget.sh | ||
Relatively Secure Harness
A development container for Claude Code and .NET work, with explicitly selected repositories and allowlisted HTTPS egress. Designed for rootless Podman on Linux.
The harness limits network access and protects selected host-side configuration. It is not a complete sandbox: tools inside the container can read credentials and modify the repositories you mount.
flowchart TB
subgraph host["HOST-ENFORCED CONTROLS - outside the app"]
policy["Host-owned network policy and repository selection<br/>Not writable from app"]
engine["Container engine<br/>Internal-only app network; resource and privilege limits"]
end
subgraph internal["INTERNAL NETWORK - app has no direct internet route"]
app["APP DEVCONTAINER<br/>Claude Code, Node, .NET as vscode<br/>All capabilities dropped; no-new-privileges<br/>8 GiB memory / 4096 process limit"]
proxy["SEPARATE EGRESS PROXY<br/>dnsmasq directs DNS to proxy<br/>HAProxy permits allowlisted TLS SNI only<br/>Rejects configured private/reserved destinations"]
end
policy --> engine
policy -->|"Defines allowlist"| proxy
engine -->|"Enforces restrictions"| app
repos["Selected host repositories"] -->|"Writable files; read-only Git / IDE config overlays"| app
feeds["Local package credentials"] -->|"Read-only file; still readable by app"| app
app -->|"DNS and TLS :443"| proxy
app -.->|"Direct external IP / SSH: no route"| blocked["BLOCKED by network isolation"]
proxy -->|"Allowed TLS passthrough on :443"| internet["Internet services on allowlist"]
proxy -->|"Unlisted SNI / raw SSH"| denied["REJECTED by proxy"]
blocked ~~~ provenance["generated with AI"]
internet ~~~ provenance
denied ~~~ provenance
style app fill:#fff3cd,stroke:#856404,color:#212529
style proxy fill:#d4edda,stroke:#155724,color:#212529
style blocked fill:#f8d7da,stroke:#721c24,color:#212529
style denied fill:#f8d7da,stroke:#721c24,color:#212529
style provenance fill:transparent,stroke:transparent,font-size:10px
How it works
Two Compose services separate development tools from outbound network access:
appjoins only an internal network. It has no direct internet route.dnsmasqmaps hostname lookups to the proxy. It does not forward other DNS queries upstream.- HAProxy checks the TLS SNI hostname, resolves permitted destinations independently, and forwards the encrypted stream without decrypting it.
- Resolved destinations in the configured private and reserved IPv4 ranges are rejected.
- The proxy joins both the internal and internet-connected networks.
DNS steering directs traffic to the proxy; enforcement comes from the container engine's network isolation and HAProxy policy, not an in-container firewall.
What hardens the app
The app does not control its own network boundary. Its only configured path to external services is a separate proxy, and the app cannot rewrite the host-owned Compose configuration or proxy policy.
| Control | Effect on tools running inside the app |
|---|---|
| Internal-only network, enforced by the engine | Connecting to an external IP directly does not bypass DNS or the proxy policy. |
| Separate allowlisting proxy | Only permitted SNI destinations are forwarded on port 443; raw SSH and unlisted hosts are rejected. |
| Host-owned harness configuration, outside mounted repos | Editing workspace files cannot change the configured networks, allowlist, or repository selection. |
| Selected mounts and read-only configuration overlays | Limits exposed host files and prevents writes to the overlaid Git hooks/config and existing IDE settings. |
Unprivileged user, dropped capabilities, no-new-privileges |
Reduces privilege and prevents gaining privileges through setuid executables; this complements, rather than replaces, network isolation. |
| Engine-enforced memory and process limits | Caps resource consumption by builds, tools, or runaway processes. |
These controls reduce access and blast radius, not all risk. The app can still change mounted source files, read mounted tokens, and send data to allowed services. Host/gateway reachability depends on runtime and host firewall behavior; this architecture is not a claim that every local host service is unreachable.
Requirements
- Linux with rootless Podman, a working Docker-compatible CLI, and a Compose provider.
- Node.js and npm on the host for the recommended
@devcontainers/clipackage. - Bash and Git on the host.
- Internet access during image builds and feature installation.
The configuration uses Podman's userns_mode: keep-id and SELinux bind-mount labels. It is not a portable, unchanged Docker configuration.
Getting started
1. Place the harness beside your repositories
Copy this repository's contents into a .devcontainer directory in the parent folder you will open:
~/repos/
├── .devcontainer/ harness files; not mounted as a directory
├── ExampleService/ selected repository
├── AnotherRepo/ selected repository
└── OtherRepo/ not mounted
Keep the harness outside every mounted repository so container processes cannot edit its network policy or repository selection.
2. Select repositories
From the parent folder:
cp .devcontainer/repos.env.example .devcontainer/repos.env
Edit the local file:
ALLOWED_REPOS=ExampleService,AnotherRepo
Entries are comma-separated sibling directory names, not paths. Each must be a non-symlink directory with a .git directory. Git worktrees and submodules with a .git file are not supported.
3. Prepare local configuration
bash .devcontainer/install-egress-proxy.sh
The installer:
- Checks required files and sets script executable permissions.
- Creates missing
repos.envandnuget.envfrom their templates. - Restricts
nuget.envpermissions to600, without overwriting existing values. - Generates repository mounts and validates Compose when the Docker-compatible CLI is available.
- Suppresses rendered Compose output to avoid exposing configuration values.
Configure private package feeds in nuget.env as described below. Leave NUGET_SOURCES="" if none are needed.
4. Start and use the container
Recommended: use the Dev Container CLI rather than starting or attaching through VS Code. Install the npm package on the host, then run from the parent folder:
npm install -g @devcontainers/cli
devcontainer up --workspace-folder "$PWD"
devcontainer exec --workspace-folder "$PWD" bash
Selected repositories appear under /workspaces/<repository>.
VS Code credential risk: Dev Containers can automatically forward your host SSH agent when you open or attach to a container. This exposes access to loaded SSH identities through an agent socket, not necessarily a mount of the private-key files themselves. VS Code can also make host Git credentials available. Processes inside the container may then use those credentials.
Egress restrictions do not make credential forwarding safe: allowed HTTPS services remain reachable, and an exposed SSH agent can perform signing operations even when outbound SSH is blocked. Prefer CLI-only use without agent or credential forwarding. If you use VS Code, disable automatic credential sharing/agent forwarding and inspect the effective mounts and environment before running untrusted tools. Starting with the CLI does not prevent VS Code from introducing forwarding if you attach later.
The app starts from the Ubuntu Dev Containers base with tmux and Vim installed. Features add Node, Claude Code, Herdr, and .NET SDK 10.0. The post-create hook attempts to install the Lattice Claude plugin; plugin failures are logged but do not block setup. Each start configures NuGet sources and prepares Claude's temporary directory.
Run herdr inside the container for agent-focused terminal sessions; detach with Ctrl-b, then q, and run herdr again to reattach. Use local sessions without SSH integration or host control-socket mounts. Container stops terminate running processes. See the Herdr documentation for session restoration and controls. Herdr is installed through a community-maintained feature.
Herdr SSH integration is not configured by this harness: do not add remote machines, use --remote, or forward a host SSH agent. The feature installs the binary only; it has no SSH-disable option, so remote functionality remains part of the executable rather than being explicitly disabled.
Herdr is pinned to v0.9.5: the published community feature's latest lookup does not follow the GitHub API redirect after the upstream repository move. Keep an explicit release version until the published installer is fixed.
Use tmux new -As work inside the container to create or reattach to a terminal session. Detach with Ctrl-b, then d. Sessions survive terminal disconnections, but not container stops or recreation. Use vim <file> to edit files.
Use the Dev Container CLI to create or rebuild the app. Starting it directly through Compose can omit the feature-enriched image and its tooling.
Configuration
Tooling for other ecosystems
Add or replace entries in the features object in devcontainer.json to install tooling for Python, Go, Rust, Java, and other ecosystems. Browse the Dev Container Features catalog for feature IDs, versions, and configuration options.
For example, add Python alongside the existing features:
"ghcr.io/devcontainers/features/python:1": {
"version": "3.13"
}
Rebuild through the Dev Container CLI to apply changes. Check each feature's base-image requirements; build-time installation has network access, but package downloads after startup still need to pass the HTTPS allowlist. Put custom image-level dependencies in app/Dockerfile, rather than granting the running app sudo access.
Repository mounts
generate-repo-mounts.sh runs on the host through initializeCommand. It validates repos.env and atomically generates docker-compose.repos.yml.
Each selected repository is writable, with read-only overlays for:
.git/hooks.git/config.vscodeand.idea, when present during generation
These overlays reduce opportunities to change configuration that the host later executes. They do not make repository contents safe or read-only. Git operations that write local configuration, such as git remote add or git push -u, must run on the host.
After changing repository selection, rebuild or reopen the container to apply the mounts.
NuGet feeds
Copy nuget.env.example to nuget.env, or let the installer create it. This Git-ignored file is mounted read-only and loaded by setup-nuget.sh.
NUGET_SOURCES="internal public"
NUGET_internal_NAME="company-packages"
NUGET_internal_URL="https://nuget.example.com/v3/index.json"
NUGET_internal_USERNAME="package-user"
NUGET_internal_PASSWORD='replace-with-read-only-token'
NUGET_internal_AUTH_TYPES="basic"
NUGET_public_NAME="nuget.org"
NUGET_public_URL="https://api.nuget.org/v3/index.json"
NUGET_SOURCESis a space-separated list of IDs. Each ID replaces<id>inNUGET_<id>_<FIELD>.- IDs are case-sensitive, start with a letter, and contain only letters, digits, or underscores.
NAMEis the unique registered NuGet source name.URLmust use HTTPS without embedded credentials.- Set both
USERNAMEandPASSWORDfor authenticated feeds; omit both for public feeds. - Use a read-only package token/PAT as
PASSWORD, with no publish, write, or admin access. Single-quote literal tokens to prevent shell expansion. AUTH_TYPESis optional. Usebasicfor Azure DevOps PATs; other supported values arenegotiate,kerberos,ntlm, anddigest, comma-separated.
The script validates all entries before changing sources. Existing sources are matched by name and updated; unlisted sources are left untouched. Omitting credentials does not erase credentials already saved by NuGet.
Restart the container after edits, or run inside it:
bash /opt/devcontainer/setup-nuget.sh
Custom feed hosts must also be allowed by the egress policy.
Credential handling: nuget.env is trusted Bash input, not an arbitrary dotenv file. Do not load untrusted content. It is not passed through Compose env_file or exported container-wide, but container processes can read the mounted file. NuGet also stores supplied credentials in clear text on Linux. Use narrowly scoped tokens and protect both files.
HTTPS allowlist
Edit haproxy/haproxy.cfg. Exact hostnames and domain families use separate ACL entries:
acl sni_allowed req.ssl_sni -m str -i packages.example.com
acl sni_allowed req.ssl_sni -m end -i .example.com
A leading-dot suffix allows subdomains, not the apex hostname. Prefer exact entries; a suffix grants access to the entire matching domain family.
From the parent folder, rebuild and recreate only the proxy:
docker compose -f .devcontainer/docker-compose.yml \
-f .devcontainer/docker-compose.repos.yml up -d --build egress-proxy
The committed policy covers Claude services, GitHub, npm, NuGet, Azure package infrastructure, and VS Code downloads. The configuration file is the source of truth.
Security boundaries and limitations
- The app drops all Linux capabilities, uses
no-new-privileges, and removes the base image's passwordlessvscodesudo grant. - The proxy has a read-only root filesystem, temporary writable directories, and limited capabilities. HAProxy drops to its unprivileged user.
- Both services have memory/process limits and IPv6 disabled.
- The app resolver is bind-mounted at
/etc/resolv.conf, avoiding reliance on Podman applying Compose'sdns:setting. - Plain HTTP, SSH, and arbitrary outbound TCP/UDP protocols are not supported. HTTPS clients must send visible TLS SNI.
- Hostnames resolve to the proxy even when blocked; denial normally appears as a TLS/connectivity error rather than a DNS failure.
- HAProxy checks hostnames, not HTTP paths, accounts, repositories, or request bodies. Allowed services can still be used to send data, especially shared hosting and package services.
- Network restrictions apply to the running app, not host-side image builds or feature installation.
- Mounted repository files remain writable, and package credentials are accessible inside the app. Review changes before running them on the host.
Do not add an internet-connected network, container-engine socket, or broader host mounts to the app without reconsidering these boundaries.
Validation and troubleshooting
Run offline regression tests from the harness directory:
bash tests/test-setup-nuget.sh
Tests use a fake dotnet; they do not contact package feeds. They cover source setup, invalid input, failures, local-file preservation, and installer preparation.
Optional host-side checks from the parent folder:
bash .devcontainer/install-egress-proxy.sh --validate-runtime
bash .devcontainer/install-egress-proxy.sh --devcontainer-up
Runtime validation uses container images and may download packages. The second command starts the devcontainer.
View proxy logs without relying on a particular Compose project name:
docker compose -f .devcontainer/docker-compose.yml \
-f .devcontainer/docker-compose.repos.yml logs -f egress-proxy
HAProxy emits event=egress records with the SNI hostname, selected backend, termination state, and traffic/timing information. The healthcheck checks processes rather than opening port 443, since a connection without SNI would itself be denied.
From a terminal inside the devcontainer:
getent hosts platform.claude.com
curl -I --connect-timeout 15 https://platform.claude.com
curl -I --connect-timeout 8 https://example.com
dotnet nuget list source
The lookup should return 10.10.10.10. The allowed host should reach its HTTPS service, though its HTTP status may vary. The example.com TLS connection should fail.
| Symptom | Check |
|---|---|
| Repository preparation fails | Verify sibling names in repos.env, real directories, and .git directories. |
| Allowed download fails | Inspect proxy logs for redirect/CDN hostnames and review whether they should be allowed. |
| Bind-mounted files are unreadable | Check host permissions, Podman UID mapping, and SELinux labels. |
| Git cannot update local configuration | Run that operation on the host; .git/config is read-only inside. |
| .NET or Node is missing | Rebuild through Dev Containers, not plain Compose. |
| Package authentication fails | Check the source ID/keys, read-only token scope, username, and AUTH_TYPES. |
Files
| File | Role |
|---|---|
| devcontainer.json | Features, workspace, and lifecycle hooks |
| docker-compose.yml | Services, networks, mounts, and resource limits |
| app/Dockerfile | App base image and user setup |
| app/resolv.conf | Static resolver pointing to the proxy |
| haproxy/ | Proxy image, DNS configuration, and HTTPS policy |
| generate-repo-mounts.sh | Host-side repository mount generation |
| install-egress-proxy.sh | Local preparation and optional validation/startup |
| setup-nuget.sh | Configurable NuGet source setup |
| setup-claude-plugins.sh | Best-effort Lattice plugin installation |
| repos.env.example | Repository selection template |
| nuget.env.example | Feed configuration template |
| tests/test-setup-nuget.sh | Offline regression tests |
Local repos.env and nuget.env, and generated docker-compose.repos.yml, are Git-ignored. Do not commit credentials or edit generated mounts directly.
generated with AI