From c00dfe77cef531ce4522b37130df58578a11eebd Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 29 Nov 2025 15:35:35 +0000 Subject: [PATCH] Add secure devcontainer setup for Claude Code CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Configure devcontainer with Node.js 20, Claude Code CLI, and dev tools - Add firewall script to restrict network access to whitelisted domains - Create run-container.sh helper for interactive and non-interactive usage - Support interactive mode (no args) for authentication/credential storage - Support non-interactive mode with prompt argument or stdin 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .devcontainer/Dockerfile | 91 +++++++++++++++++++++ .devcontainer/devcontainer.json | 57 +++++++++++++ .devcontainer/init-firewall.sh | 137 +++++++++++++++++++++++++++++++ CLAUDE.md | 133 ++++++++++++++++++++++++++++++ mise.toml | 2 + run-container.sh | 138 ++++++++++++++++++++++++++++++++ 6 files changed, 558 insertions(+) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/devcontainer.json create mode 100755 .devcontainer/init-firewall.sh create mode 100644 CLAUDE.md create mode 100644 mise.toml create mode 100755 run-container.sh diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..8b48f6a --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,91 @@ +FROM node:20 + +ARG TZ +ENV TZ="$TZ" + +ARG CLAUDE_CODE_VERSION=latest + +# Install basic development tools and iptables/ipset +RUN apt-get update && apt-get install -y --no-install-recommends \ + less \ + git \ + procps \ + sudo \ + fzf \ + zsh \ + man-db \ + unzip \ + gnupg2 \ + gh \ + iptables \ + ipset \ + iproute2 \ + dnsutils \ + aggregate \ + jq \ + nano \ + vim \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# Ensure default node user has access to /usr/local/share +RUN mkdir -p /usr/local/share/npm-global && \ + chown -R node:node /usr/local/share + +ARG USERNAME=node + +# Persist bash history. +RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \ + && mkdir /commandhistory \ + && touch /commandhistory/.bash_history \ + && chown -R $USERNAME /commandhistory + +# Set `DEVCONTAINER` environment variable to help with orientation +ENV DEVCONTAINER=true + +# Create workspace and config directories and set permissions +RUN mkdir -p /workspace /home/node/.claude && \ + chown -R node:node /workspace /home/node/.claude + +WORKDIR /workspace + +ARG GIT_DELTA_VERSION=0.18.2 +RUN ARCH=$(dpkg --print-architecture) && \ + wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \ + sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \ + rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" + +# Set up non-root user +USER node + +# Install global packages +ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global +ENV PATH=$PATH:/usr/local/share/npm-global/bin + +# Set the default shell to zsh rather than sh +ENV SHELL=/bin/zsh + +# Set the default editor and visual +ENV EDITOR=nano +ENV VISUAL=nano + +# Default powerline10k theme +ARG ZSH_IN_DOCKER_VERSION=1.2.0 +RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \ + -p git \ + -p fzf \ + -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \ + -a "source /usr/share/doc/fzf/examples/completion.zsh" \ + -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \ + -x + +# Install Claude +RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} + + +# Copy and set up firewall script +COPY init-firewall.sh /usr/local/bin/ +USER root +RUN chmod +x /usr/local/bin/init-firewall.sh && \ + echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \ + chmod 0440 /etc/sudoers.d/node-firewall +USER node diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..7f6a172 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,57 @@ +{ + "name": "Claude Code Sandbox", + "build": { + "dockerfile": "Dockerfile", + "args": { + "TZ": "${localEnv:TZ:America/Los_Angeles}", + "CLAUDE_CODE_VERSION": "latest", + "GIT_DELTA_VERSION": "0.18.2", + "ZSH_IN_DOCKER_VERSION": "1.2.0" + } + }, + "runArgs": [ + "--cap-add=NET_ADMIN", + "--cap-add=NET_RAW" + ], + "customizations": { + "vscode": { + "extensions": [ + "anthropic.claude-code", + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "eamodio.gitlens" + ], + "settings": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" + }, + "terminal.integrated.defaultProfile.linux": "zsh", + "terminal.integrated.profiles.linux": { + "bash": { + "path": "bash", + "icon": "terminal-bash" + }, + "zsh": { + "path": "zsh" + } + } + } + } + }, + "remoteUser": "node", + "mounts": [ + "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume", + "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume" + ], + "containerEnv": { + "NODE_OPTIONS": "--max-old-space-size=4096", + "CLAUDE_CONFIG_DIR": "/home/node/.claude", + "POWERLEVEL9K_DISABLE_GITSTATUS": "true" + }, + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated", + "workspaceFolder": "/workspace", + "postStartCommand": "sudo /usr/local/bin/init-firewall.sh", + "waitFor": "postStartCommand" +} diff --git a/.devcontainer/init-firewall.sh b/.devcontainer/init-firewall.sh new file mode 100755 index 0000000..e788801 --- /dev/null +++ b/.devcontainer/init-firewall.sh @@ -0,0 +1,137 @@ +#!/bin/bash +set -euo pipefail # Exit on error, undefined vars, and pipeline failures +IFS=$'\n\t' # Stricter word splitting + +# 1. Extract Docker DNS info BEFORE any flushing +DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true) + +# Flush existing rules and delete existing ipsets +iptables -F +iptables -X +iptables -t nat -F +iptables -t nat -X +iptables -t mangle -F +iptables -t mangle -X +ipset destroy allowed-domains 2>/dev/null || true + +# 2. Selectively restore ONLY internal Docker DNS resolution +if [ -n "$DOCKER_DNS_RULES" ]; then + echo "Restoring Docker DNS rules..." + iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true + iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true + echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat +else + echo "No Docker DNS rules to restore" +fi + +# First allow DNS and localhost before any restrictions +# Allow outbound DNS +iptables -A OUTPUT -p udp --dport 53 -j ACCEPT +# Allow inbound DNS responses +iptables -A INPUT -p udp --sport 53 -j ACCEPT +# Allow outbound SSH +iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT +# Allow inbound SSH responses +iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT +# Allow localhost +iptables -A INPUT -i lo -j ACCEPT +iptables -A OUTPUT -o lo -j ACCEPT + +# Create ipset with CIDR support +ipset create allowed-domains hash:net + +# Fetch GitHub meta information and aggregate + add their IP ranges +echo "Fetching GitHub IP ranges..." +gh_ranges=$(curl -s https://api.github.com/meta) +if [ -z "$gh_ranges" ]; then + echo "ERROR: Failed to fetch GitHub IP ranges" + exit 1 +fi + +if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then + echo "ERROR: GitHub API response missing required fields" + exit 1 +fi + +echo "Processing GitHub IPs..." +while read -r cidr; do + if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then + echo "ERROR: Invalid CIDR range from GitHub meta: $cidr" + exit 1 + fi + echo "Adding GitHub range $cidr" + ipset add allowed-domains "$cidr" +done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q) + +# Resolve and add other allowed domains +for domain in \ + "registry.npmjs.org" \ + "api.anthropic.com" \ + "sentry.io" \ + "statsig.anthropic.com" \ + "statsig.com" \ + "marketplace.visualstudio.com" \ + "vscode.blob.core.windows.net" \ + "update.code.visualstudio.com"; do + echo "Resolving $domain..." + ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}') + if [ -z "$ips" ]; then + echo "ERROR: Failed to resolve $domain" + exit 1 + fi + + while read -r ip; do + if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then + echo "ERROR: Invalid IP from DNS for $domain: $ip" + exit 1 + fi + echo "Adding $ip for $domain" + ipset add allowed-domains "$ip" + done < <(echo "$ips") +done + +# Get host IP from default route +HOST_IP=$(ip route | grep default | cut -d" " -f3) +if [ -z "$HOST_IP" ]; then + echo "ERROR: Failed to detect host IP" + exit 1 +fi + +HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/") +echo "Host network detected as: $HOST_NETWORK" + +# Set up remaining iptables rules +iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT +iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT + +# Set default policies to DROP first +iptables -P INPUT DROP +iptables -P FORWARD DROP +iptables -P OUTPUT DROP + +# First allow established connections for already approved traffic +iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT +iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT + +# Then allow only specific outbound traffic to allowed domains +iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT + +# Explicitly REJECT all other outbound traffic for immediate feedback +iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited + +echo "Firewall configuration complete" +echo "Verifying firewall rules..." +if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then + echo "ERROR: Firewall verification failed - was able to reach https://example.com" + exit 1 +else + echo "Firewall verification passed - unable to reach https://example.com as expected" +fi + +# Verify GitHub API access +if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then + echo "ERROR: Firewall verification failed - unable to reach https://api.github.com" + exit 1 +else + echo "Firewall verification passed - able to reach https://api.github.com as expected" +fi diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a77662e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,133 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Container Setup + +This repository is configured with a secure development container based on Anthropic's reference devcontainer setup. The container provides: + +- **Isolated environment**: Containerized Claude Code CLI with firewall restrictions +- **Security features**: Network access limited to whitelisted domains (GitHub, npm, Anthropic APIs, etc.) +- **Pre-configured tools**: Node.js 20, Claude Code CLI, git-delta, zsh with powerline10k, fzf, and more +- **Persistent storage**: Volumes for bash history and Claude configuration + +### Opening in DevContainer + +**Option 1: Using run-container.sh script (easiest for non-interactive usage)** + +The repository includes a helper script for running Claude Code non-interactively: + +```bash +# Make the script executable (first time only) +chmod +x run-container.sh + +# Run with a prompt +./run-container.sh "explain the fibonacci sequence" + +# Run with stdin +echo "create a hello world function in Python" | ./run-container.sh + +# Analyze a file +./run-container.sh "explain this code" < myfile.js +``` + +The script automatically: +- Builds the Docker image if needed +- Creates persistent volumes for history and config +- Initializes the firewall +- Runs claude with streaming output and --dangerously-skip-permissions +- Cleans up the container after execution + +**Option 2: Using devcontainer CLI (recommended for interactive development)** + +Install the devcontainer CLI: +```bash +npm install -g @devcontainers/cli +``` + +Build and run the container: +```bash +# Build the container +devcontainer build --workspace-folder . + +# Run the container and execute a command +devcontainer exec --workspace-folder . claude -p "your prompt" --dangerously-skip-permissions + +# Or open an interactive shell +devcontainer exec --workspace-folder . zsh +``` + +**Option 3: Using Docker directly** + +Build and run manually: +```bash +# Build the image +docker build -t claude-dev-container .devcontainer + +# Create volumes for persistence +docker volume create claude-code-bashhistory +docker volume create claude-code-config + +# Run interactively +docker run -it --rm \ + --cap-add=NET_ADMIN \ + --cap-add=NET_RAW \ + -v "$(pwd):/workspace" \ + -v claude-code-bashhistory:/commandhistory \ + -v claude-code-config:/home/node/.claude \ + -e NODE_OPTIONS="--max-old-space-size=4096" \ + -e CLAUDE_CONFIG_DIR="/home/node/.claude" \ + -w /workspace \ + --user node \ + claude-dev-container zsh + +# Inside the container, initialize the firewall: +sudo /usr/local/bin/init-firewall.sh + +# Then use Claude Code: +claude -p "your prompt" --dangerously-skip-permissions +``` + +**Option 4: VS Code** +1. Install the "Dev Containers" extension +2. Open this repository in VS Code +3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container") +4. Wait for the container to build and the firewall to initialize + +**First-time setup:** +- You'll need to authenticate Claude Code on first use +- Run `claude` in the container terminal and follow the authentication prompts + +### Running Claude Code Non-Interactively + +The devcontainer's firewall allows running Claude Code with `--dangerously-skip-permissions` for non-interactive operation: + +```bash +# Stream output in non-interactive mode +claude -p "your prompt here" --dangerously-skip-permissions + +# Example: Analyze a file +claude -p "explain this code" --dangerously-skip-permissions < myfile.js + +# Example: Generate code with streaming output +echo "create a fibonacci function" | claude -p --dangerously-skip-permissions +``` + +**Security notes:** +- The `--dangerously-skip-permissions` flag bypasses permission prompts +- This is safe within the devcontainer due to firewall restrictions +- Network access is limited to: GitHub, npm registry, Anthropic APIs, VS Code services +- All other outbound connections are blocked + +### Container Configuration Files + +- `.devcontainer/devcontainer.json` - Container and VS Code configuration +- `.devcontainer/Dockerfile` - Container image definition +- `.devcontainer/init-firewall.sh` - Network security rules (runs on container start) + +### Environment Setup (Outside Container) + +This repository uses [mise](https://mise.jdx.dev/) for tool version management. + +- Node.js version: 24 (configured in `mise.toml`) +- Install tools: `mise install` diff --git a/mise.toml b/mise.toml new file mode 100644 index 0000000..6ea5a7e --- /dev/null +++ b/mise.toml @@ -0,0 +1,2 @@ +[tools] +node = "24" diff --git a/run-container.sh b/run-container.sh new file mode 100755 index 0000000..88dc6c3 --- /dev/null +++ b/run-container.sh @@ -0,0 +1,138 @@ +#!/bin/bash +set -euo pipefail + +# Script to run Claude Code in a secure devcontainer +# Usage: ./run-container.sh "your prompt here" +# Or with stdin: echo "your prompt" | ./run-container.sh + +IMAGE_NAME="claude-dev-container" +CONTAINER_NAME="claude-dev-container-$$" +VOLUME_HISTORY="claude-code-bashhistory" +VOLUME_CONFIG="claude-code-config" + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +# Function to print colored messages +log_info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +log_warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +# Check if Docker is available +if ! command -v docker &> /dev/null; then + log_error "Docker is not installed or not in PATH" + exit 1 +fi + +# Build image if it doesn't exist +if ! docker image inspect "$IMAGE_NAME" &> /dev/null; then + log_info "Image '$IMAGE_NAME' not found. Building..." + docker build -t "$IMAGE_NAME" .devcontainer + log_info "Image built successfully" +else + log_info "Using existing image '$IMAGE_NAME'" +fi + +# Create volumes if they don't exist +if ! docker volume inspect "$VOLUME_HISTORY" &> /dev/null; then + log_info "Creating volume '$VOLUME_HISTORY'" + docker volume create "$VOLUME_HISTORY" > /dev/null +fi + +if ! docker volume inspect "$VOLUME_CONFIG" &> /dev/null; then + log_info "Creating volume '$VOLUME_CONFIG'" + docker volume create "$VOLUME_CONFIG" > /dev/null +fi + +# Get the prompt from arguments or stdin +PROMPT="" +if [ $# -gt 0 ]; then + # Use arguments as prompt + PROMPT="$*" +elif [ ! -t 0 ]; then + # Read from stdin if available + PROMPT=$(cat) +fi + +# Check if running in interactive mode (no prompt provided) +if [ -z "$PROMPT" ]; then + log_info "No prompt provided. Starting interactive mode..." + log_info "You can now run 'claude' to authenticate or use Claude Code interactively" + + # Run the container in interactive mode + docker run --rm -it \ + --name "$CONTAINER_NAME" \ + --cap-add=NET_ADMIN \ + --cap-add=NET_RAW \ + -v "$(pwd):/workspace" \ + -v "$VOLUME_HISTORY:/commandhistory" \ + -v "$VOLUME_CONFIG:/home/node/.claude" \ + -e NODE_OPTIONS="--max-old-space-size=4096" \ + -e CLAUDE_CONFIG_DIR="/home/node/.claude" \ + -e POWERLEVEL9K_DISABLE_GITSTATUS="true" \ + -w /workspace \ + --user node \ + "$IMAGE_NAME" \ + /bin/bash -c " + # Initialize firewall + echo 'Initializing firewall...' + sudo /usr/local/bin/init-firewall.sh + + echo '' + echo 'Container ready! Firewall initialized.' + echo 'Run \"claude\" to authenticate or use Claude Code interactively.' + echo 'Type \"exit\" to leave the container.' + echo '' + + # Start interactive shell + exec zsh + " + exit $? +fi + +log_info "Running Claude Code in container..." + +# Run the container with the command +# The command will: initialize firewall, then run claude +docker run --rm \ + --name "$CONTAINER_NAME" \ + --cap-add=NET_ADMIN \ + --cap-add=NET_RAW \ + -v "$(pwd):/workspace" \ + -v "$VOLUME_HISTORY:/commandhistory" \ + -v "$VOLUME_CONFIG:/home/node/.claude" \ + -e NODE_OPTIONS="--max-old-space-size=4096" \ + -e CLAUDE_CONFIG_DIR="/home/node/.claude" \ + -e POWERLEVEL9K_DISABLE_GITSTATUS="true" \ + -w /workspace \ + --user node \ + "$IMAGE_NAME" \ + /bin/bash -c " + # Initialize firewall + echo 'Initializing firewall...' >&2 + sudo /usr/local/bin/init-firewall.sh >&2 + + # Run claude with the prompt + echo 'Running Claude Code...' >&2 + claude -p \"$PROMPT\" --dangerously-skip-permissions + " + +EXIT_CODE=$? + +if [ $EXIT_CODE -eq 0 ]; then + log_info "Command completed successfully" +else + log_error "Command failed with exit code $EXIT_CODE" + exit $EXIT_CODE +fi