Guide: .devcontainer Integration for Agent Sandboxing - Security and Isolation Patterns

# .devcontainer Integration for Agent Sandboxing: Security and Isolation Guide

## Overview

This guide provides comprehensive patterns for using .devcontainer configurations to create secure, isolated environments for coding agents. Based on research from the DevContainers specification and real-world implementations, this covers security considerations, isolation techniques, and integration patterns.

## Table of Contents

1. [Security Fundamentals](#security-fundamentals)
2. [Isolation Patterns](#isolation-patterns)
3. [User Management & Permissions](#user-management--permissions)
4. [Container Security Configuration](#container-security-configuration)
5. [CI/CD Integration](#cicd-integration)
6. [Best Practices](#best-practices)
7. [Example Configurations](#example-configurations)

## Security Fundamentals

### Core Security Principles

When designing .devcontainer environments for coding agents, consider these security layers:

1. **Container Isolation**: Leverage container boundaries to isolate agent execution
2. **User Privilege Separation**: Run agents with minimal required privileges
3. **Resource Constraints**: Limit CPU, memory, and storage access
4. **Network Isolation**: Control network access and communication
5. **Secret Management**: Secure handling of credentials and sensitive data

### Security Configuration Options

```json
{
  "name": "Secure Agent Environment",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "privileged": false,
  "capAdd": [],
  "capDrop": ["ALL"],
  "securityOpt": [
    "no-new-privileges:true",
    "seccomp=default"
  ],
  "init": true
}
```

## Isolation Patterns

### 1. Basic Isolation Pattern

**Use Case**: Simple agent tasks with minimal system access requirements

```json
{
  "name": "Basic Agent Sandbox",
  "image": "node:18-alpine",
  "containerUser": "node",
  "remoteUser": "node",
  "updateRemoteUserUID": true,
  "runArgs": [
    "--read-only",
    "--tmpfs=/tmp:rw,noexec,nosuid,size=100m",
    "--security-opt=no-new-privileges:true"
  ],
  "containerEnv": {
    "NODE_ENV": "sandbox",
    "AGENT_MODE": "restricted"
  }
}
```

### 2. Enhanced Security Pattern

**Use Case**: Agents requiring additional security controls

```json
{
  "name": "Enhanced Security Sandbox",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "containerUser": "vscode",
  "remoteUser": "agent",
  "privileged": false,
  "capDrop": ["ALL"],
  "capAdd": ["CHOWN", "DAC_OVERRIDE"],
  "securityOpt": [
    "no-new-privileges:true",
    "seccomp=default",
    "apparmor=docker-default"
  ],
  "runArgs": [
    "--memory=2g",
    "--cpus=1.0",
    "--pids-limit=100",
    "--ulimit=nofile=1024:1024"
  ]
}
```

### 3. Container-in-Container Pattern

**Use Case**: Agents that need to build or run containers (like Ansible dev tools)

```json
{
  "name": "Container-in-Container Sandbox",
  "image": "registry.redhat.com/ansible-automation-platform-25/ansible-dev-tools-rhel8:latest",
  "containerUser": "root",
  "runArgs": [
    "--cap-add=CAP_MKNOD",
    "--cap-add=NET_ADMIN", 
    "--cap-add=SYS_ADMIN",
    "--cap-add=SYS_RESOURCE",
    "--device=/dev/fuse",
    "--security-opt=seccomp=unconfined",
    "--security-opt=label=disable",
    "--security-opt=apparmor=unconfined",
    "--security-opt=unmask=/sys/fs/cgroup",
    "--userns=host",
    "--hostname=agent-container"
  ],
  "mounts": [
    "source=agent-container-storage,target=/var/lib/containers,type=volume"
  ]
}
```

## User Management & Permissions

### Non-Root User Configuration

```json
{
  "name": "Non-Root Agent Environment",
  "image": "mcr.microsoft.com/devcontainers/python:3.11",
  "containerUser": "vscode",
  "remoteUser": "agent",
  "updateRemoteUserUID": true,
  "containerEnv": {
    "_CONTAINER_USER": "vscode",
    "_REMOTE_USER": "agent"
  },
  "postCreateCommand": [
    "sudo chown -R agent:agent /workspace",
    "sudo chmod 755 /workspace"
  ]
}
```

### User Environment Variables

The DevContainers specification provides these user-related environment variables:

- `_REMOTE_USER`: The configured remoteUser
- `_CONTAINER_USER`: The container's default user
- `${localEnv:USERNAME}`: Local user's username
- `${containerWorkspaceFolder}`: Workspace path in container

## Container Security Configuration

### Secrets Management

```json
{
  "name": "Secure Agent with Secrets",
  "image": "node:18",
  "secrets": {
    "API_KEY": {
      "description": "External API access key",
      "documentationUrl": "https://docs.example.com/api-keys"
    },
    "DATABASE_PASSWORD": {
      "description": "Database connection password"
    },
    "SIGNING_KEY": {
      "description": "Code signing certificate key"
    }
  },
  "remoteEnv": {
    "API_KEY": "${localEnv:API_KEY}",
    "DATABASE_URL": "postgresql://user:${localEnv:DATABASE_PASSWORD}@db:5432/agentdb"
  },
  "containerEnv": {
    "SECURE_MODE": "true",
    "LOG_LEVEL": "info"
  }
}
```

### Network Security

```json
{
  "name": "Network-Isolated Agent",
  "image": "python:3.11-slim",
  "runArgs": [
    "--network=none",
    "--dns=8.8.8.8",
    "--add-host=api.example.com:192.168.1.100"
  ],
  "forwardPorts": [],
  "portsAttributes": {
    "8080": {
      "label": "Agent API",
      "onAutoForward": "ignore"
    }
  }
}
```

## CI/CD Integration

### Automated Agent Testing

```json
{
  "name": "CI Agent Environment",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "containerEnv": {
    "CI": "true",
    "AGENT_TEST_MODE": "true"
  },
  "postCreateCommand": "bash .devcontainer/setup-ci.sh",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-vscode.test-adapter-converter"
      ]
    }
  }
}
```

### Build Script Integration

```bash
#!/bin/bash
# CI build script using dev container CLI
set -e

BUILD_DATE="$(date +%s)"
ID_LABEL="agent-ci-build=${BUILD_DATE}"

# Create and start dev container
devcontainer up \
  --workspace-folder . \
  --id-label "${ID_LABEL}" \
  --skip-post-create

# Run agent tests in container
devcontainer exec \
  --workspace-folder . \
  --id-label "${ID_LABEL}" \
  npm run test:agent

# Run security scan
devcontainer exec \
  --workspace-folder . \
  --id-label "${ID_LABEL}" \
  npm audit --audit-level=high

# Cleanup
docker rm -f $(docker ps -aq --filter label=${ID_LABEL})
```

## Best Practices

### 1. Principle of Least Privilege

- Start with minimal permissions and add only what's necessary
- Use `capDrop: ["ALL"]` and selectively add required capabilities
- Run as non-root user whenever possible
- Use `updateRemoteUserUID: true` for proper file permissions

### 2. Resource Constraints

```json
{
  "runArgs": [
    "--memory=1g",
    "--cpus=0.5",
    "--pids-limit=50",
    "--ulimit=nofile=512:512",
    "--ulimit=nproc=32:32"
  ]
}
```

### 3. Security Monitoring

```json
{
  "containerEnv": {
    "AUDIT_LOG": "true",
    "SECURITY_SCAN": "enabled"
  },
  "postStartCommand": [
    "echo 'Container started at $(date)' >> /var/log/agent-audit.log"
  ]
}
```

### 4. Immutable Infrastructure

```json
{
  "runArgs": [
    "--read-only",
    "--tmpfs=/tmp:rw,noexec,nosuid,size=100m",
    "--tmpfs=/var/tmp:rw,noexec,nosuid,size=50m"
  ],
  "mounts": [
    "source=agent-data,target=/data,type=volume,readonly=false"
  ]
}
```

## Example Configurations

### Python Agent Sandbox

```json
{
  "name": "Python Agent Sandbox",
  "image": "python:3.11-slim",
  "containerUser": "nobody",
  "remoteUser": "agent",
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {
      "username": "agent",
      "userUid": 1000,
      "userGid": 1000
    }
  },
  "runArgs": [
    "--memory=512m",
    "--cpus=0.25",
    "--read-only",
    "--tmpfs=/tmp:rw,noexec,nosuid,size=50m",
    "--security-opt=no-new-privileges:true"
  ],
  "containerEnv": {
    "PYTHONPATH": "/workspace",
    "AGENT_SANDBOX": "true"
  },
  "postCreateCommand": "pip install --user -r requirements.txt"
}
```

### Node.js Agent with Network Isolation

```json
{
  "name": "Node.js Agent - Network Isolated",
  "image": "node:18-alpine",
  "containerUser": "node",
  "remoteUser": "node",
  "runArgs": [
    "--network=none",
    "--memory=256m",
    "--cpus=0.1",
    "--security-opt=no-new-privileges:true"
  ],
  "containerEnv": {
    "NODE_ENV": "sandbox",
    "NETWORK_DISABLED": "true"
  },
  "postCreateCommand": "npm ci --only=production"
}
```

### Multi-Language Agent Environment

```json
{
  "name": "Multi-Language Agent Sandbox",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "containerUser": "codespace",
  "remoteUser": "agent",
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.11"
    },
    "ghcr.io/devcontainers/features/node:1": {
      "version": "18"
    },
    "ghcr.io/devcontainers/features/go:1": {
      "version": "1.21"
    }
  },
  "runArgs": [
    "--memory=1g",
    "--cpus=0.5",
    "--security-opt=no-new-privileges:true"
  ],
  "containerEnv": {
    "MULTI_LANG_AGENT": "true",
    "SANDBOX_MODE": "strict"
  }
}
```

## Security Considerations Summary

1. **Container Boundaries**: Use containers as the primary isolation mechanism
2. **User Privileges**: Implement proper user separation and minimal privileges
3. **Resource Limits**: Apply memory, CPU, and process limits
4. **Network Controls**: Isolate network access when possible
5. **Secret Management**: Use proper secret injection mechanisms
6. **Monitoring**: Implement logging and audit trails
7. **Immutability**: Prefer read-only filesystems with specific writable areas
8. **Regular Updates**: Keep base images and dependencies updated

## Integration Patterns Summary

- **Direct CLI Usage**: For local development and testing
- **CI/CD Pipelines**: Automated testing and deployment
- **Pre-built Images**: Faster startup times with cached dependencies
- **Feature Composition**: Modular environment construction
- **Multi-stage Builds**: Optimized production images

This guide provides a foundation for implementing secure, isolated coding agent environments using .devcontainer configurations. Adapt these patterns based on your specific security requirements and agent capabilities.

## References

- [DevContainers Specification](https://containers.dev/)
- [DevContainers CLI Documentation](https://github.com/devcontainers/cli)
- [Container Security Best Practices](https://docs.docker.com/engine/security/)
- [Ansible Dev Tools Container Example](https://github.com/ansible/ansible-dev-tools)

---

*This guide is based on research from the DevContainers specification, security best practices, and real-world implementations including the Ansible Automation Platform development tools.*

Guide: .devcontainer Integration for Agent Sandboxing - Security and Isolation Patterns #665

Description

.devcontainer Integration for Agent Sandboxing: Security and Isolation Guide

Overview

Table of Contents

Security Fundamentals

Core Security Principles

Security Configuration Options

Isolation Patterns

1. Basic Isolation Pattern

2. Enhanced Security Pattern

3. Container-in-Container Pattern

User Management & Permissions

Non-Root User Configuration

User Environment Variables

Container Security Configuration

Secrets Management

Network Security

CI/CD Integration

Automated Agent Testing

Build Script Integration

Best Practices

1. Principle of Least Privilege

2. Resource Constraints

3. Security Monitoring

4. Immutable Infrastructure

Example Configurations

Python Agent Sandbox

Node.js Agent with Network Isolation

Multi-Language Agent Environment

Security Considerations Summary

Integration Patterns Summary

References

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions