diff --git a/.devcontainer/hardened/Dockerfile b/.devcontainer/airgapped/Dockerfile similarity index 100% rename from .devcontainer/hardened/Dockerfile rename to .devcontainer/airgapped/Dockerfile diff --git a/.devcontainer/hardened/devcontainer.json b/.devcontainer/airgapped/devcontainer.json similarity index 78% rename from .devcontainer/hardened/devcontainer.json rename to .devcontainer/airgapped/devcontainer.json index dc217dd..e39cb6e 100644 --- a/.devcontainer/hardened/devcontainer.json +++ b/.devcontainer/airgapped/devcontainer.json @@ -3,7 +3,7 @@ // This is the HARDENED version of TRG's DevContainer - provides enhanced security // with capability dropping, security options, and resource limits while maintaining // network connectivity for development. - "name": "Hardened TRG's DevContainer", + "name": "Air-gapped TRG's DevContainer", // Build configuration - uses the local Dockerfile in this directory "build": { @@ -23,23 +23,13 @@ // Container environment variables "containerEnv": { "SHELL": "/bin/zsh", // Use zsh as the default shell - "DEVCONTAINER_ID_LABEL": "hardened-web3-devcontainer" // Label for container identification + "DEVCONTAINER_ID_LABEL": "airgapped-web3-devcontainer" // Label for container identification }, // Configure tool-specific properties for VS Code "customizations": { "vscode": { // Web3 security and development extensions - "extensions": [ - "tintinweb.ethereum-security-bundle", // Comprehensive Ethereum security tools - "tintinweb.vscode-ethover", // Ethereum hover information - "trailofbits.weaudit", // Trail of Bits audit tools - "tintinweb.vscode-inline-bookmarks", // Inline code bookmarks - "tintinweb.vscode-solidity-language", // Solidity language support - "tintinweb.graphviz-interactive-preview", // Graph visualization - "trailofbits.contract-explorer", // Smart contract exploration - "tintinweb.vscode-decompiler" // Contract decompilation - ], // VS Code settings for security and functionality "settings": { // Security settings - killswitch for automated tasks @@ -69,7 +59,7 @@ // If you need to extract something from within the container, you can use docker cp, but use it at your own risk. // If you want to develop your devcontainer, you should comment this things, otherwise your changes inside the live container won't persist. // Disables mounting the host workspace into the container for isolation. - "workspaceMount": "type=tmpfs,destination=/workspace", + "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", // Sets a workspace path entirely isolated within the container "workspaceFolder": "/workspace", @@ -98,15 +88,7 @@ // Network security configuration // If you really want to isolate it, just disconnect it from the internet. // You should COPY your working files inside before, otherwise you'll have to mount them manually. - // "--network=none", - - // IPv6 security - disable IPv6 to reduce attack surface - "--sysctl=net.ipv6.conf.all.disable_ipv6=1", // Disable IPv6 globally - "--sysctl=net.ipv6.conf.default.disable_ipv6=1", // Disable IPv6 by default - - // Network capability restrictions - "--cap-drop=NET_RAW", // Disable raw packet access - "--network=bridge", // Use bridge networking + "--network=none", // DNS configuration for security and reliability "--dns=1.1.1.1", // Primary DNS (Cloudflare) diff --git a/.devcontainer/auditor/devcontainer.json b/.devcontainer/auditor/devcontainer.json index 8bc2fd1..338c3a2 100644 --- a/.devcontainer/auditor/devcontainer.json +++ b/.devcontainer/auditor/devcontainer.json @@ -58,11 +58,8 @@ } }, - // Mount isolation configuration for security and development workflow - // If you need to extract something from within the container, you can use docker cp, but use it at your own risk. - // If you want to develop your devcontainer, you should comment this things, otherwise your changes inside the live container won't persist. - // Disables mounting the host workspace into the container for isolation. - "workspaceMount": "type=tmpfs,destination=/workspace", + // Mount copying host folder into container, no isolation. + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", // Sets a workspace path entirely isolated within the container "workspaceFolder": "/workspace", diff --git a/.devcontainer/eth-security-toolbox b/.devcontainer/eth-security-toolbox new file mode 160000 index 0000000..78f2b0c --- /dev/null +++ b/.devcontainer/eth-security-toolbox @@ -0,0 +1 @@ +Subproject commit 78f2b0c2440709a9067ae7ca64f55d2199b03b8a diff --git a/.devcontainer/isolated/Dockerfile b/.devcontainer/isolated/Dockerfile index cdf4868..5278264 100644 --- a/.devcontainer/isolated/Dockerfile +++ b/.devcontainer/isolated/Dockerfile @@ -1,14 +1,16 @@ # syntax=docker/dockerfile:1.8 # check=error=true # -# ISOLATED TRG DevContainer Dockerfile -# This Dockerfile creates a highly isolated development environment for Web3 security research -# with maximum security isolation, read-only filesystem, and network isolation. +# HARDENED TRG DevContainer Dockerfile +# This Dockerfile creates a security-hardened development environment for Web3 security research +# with enhanced security features, capability dropping, and minimal attack surface. # # Key security features: +# - Multi-stage build for Echidna binary # - Non-root user execution # - Minimal package installation # - Security-hardened toolchain +# - Reduced tool set for security focus ## Multi-stage build for Echidna # Pull latest prebuilt Echidna binary from Crytic's official image @@ -17,7 +19,7 @@ FROM --platform=linux/amd64 ghcr.io/crytic/echidna/echidna:latest AS echidna # Base image: Latest Debian with VS Code DevContainer support # This provides a stable, security-focused base for development -FROM mcr.microsoft.com/vscode/devcontainers/base:debian +FROM mcr.microsoft.com/devcontainers/base:bookworm # Install essential system packages for development # These are the minimal packages needed for Web3 development tools @@ -35,6 +37,8 @@ RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-ins zsh # Advanced shell \ && rm -rf /var/lib/apt/lists/* + + # Install Python development dependencies # Required for Python-based security tools and package management RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ @@ -100,17 +104,6 @@ USER vscode ENV PNPM_HOME=${HOME}/.local/share/pnpm ENV PATH=${PATH}:${PNPM_HOME} -# Install Python-based security analysis tools (reduced set for security focus) -# These tools provide essential smart contract security analysis -# Focused on core tools: slither, mythril, crytic-compile, halmos, solc-select -RUN uv tool install slither-analyzer && \ - uv tool install crytic-compile && \ - uv tool install slither-lsp && \ - uv tool install mythril && \ - uv tool install halmos && \ - uv tool install solc-select && \ - solc-select install 0.4.26 0.5.17 0.6.12 0.7.6 0.8.10 latest && solc-select use latest - # Install Foundry framework for Ethereum development # Foundry provides Forge (testing), Cast (interaction), and Anvil (local blockchain) RUN curl -fsSL https://foundry.paradigm.xyz | zsh && \ @@ -135,6 +128,17 @@ RUN git clone https://github.com/crytic/medusa $HOME/medusa && \ WORKDIR $HOME RUN rm -rf medusa/ +# Install Python-based security analysis tools (reduced set for security focus) +# These tools provide essential smart contract security analysis +# Focused on core tools: slither, mythril, crytic-compile, halmos, solc-select +RUN uv tool install slither-analyzer && \ + uv tool install crytic-compile && \ + uv tool install slither-lsp && \ + uv tool install mythril && \ + uv tool install halmos && \ + uv tool install solc-select && \ + solc-select install 0.4.26 0.5.17 0.6.12 0.7.6 0.8.10 latest && solc-select use latest + # Copy Echidna binary from echidna stage to final image # This provides the prebuilt Echidna tool without rebuilding USER root diff --git a/.devcontainer/isolated/devcontainer.json b/.devcontainer/isolated/devcontainer.json index ea65f75..56a26c7 100644 --- a/.devcontainer/isolated/devcontainer.json +++ b/.devcontainer/isolated/devcontainer.json @@ -1,7 +1,8 @@ { // For format details, see https://aka.ms/devcontainer.json. - // This is the ISOLATED version of TRG's DevContainer - provides maximum security isolation - // with a read-only filesystem and network isolation for high-security Web3 development. + // This is the HARDENED version of TRG's DevContainer - provides enhanced security + // with capability dropping, security options, and resource limits while maintaining + // network connectivity for development. "name": "Isolated TRG's DevContainer", // Build configuration - uses the local Dockerfile in this directory @@ -29,7 +30,6 @@ "customizations": { "vscode": { // Web3 security and development extensions - // check out https://marketplace.visualstudio.com/items?itemName=tintinweb.ethereum-security-bundle for more information "extensions": [ "tintinweb.ethereum-security-bundle", // Comprehensive Ethereum security tools "tintinweb.vscode-ethover", // Ethereum hover information @@ -56,54 +56,70 @@ "terminal.integrated.defaultProfile.linux": "zsh", // Use zsh by default "terminal.integrated.profiles.linux": { "zsh": { "path": "/usr/bin/zsh" } } // Using bash might be more safe and stable, but zsh provides better features - } + }, } }, // Commands to run during container lifecycle - "initializeCommand": "echo 'Initializing isolated dev container...'", + "initializeCommand": "echo 'Initializing hardened dev container...'", "postStartCommand": "echo '๐Ÿš€ Dev container is ready for Web3 development!'", - // Workspace configuration - isolated within container - "workspaceFolder": "/workspace", - // Mount workspace as tmpfs for complete isolation - no host file access. - // This ensures that the workspace is ephemeral and does not persist data. - "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", - - // Docker run arguments for security and isolation - "runArgs": [ - // Security hardening - drop all Linux capabilities to reduce attack surface - "--cap-drop=ALL", - - // Read-only filesystem for maximum security, preventing any persistent changes - "--read-only", - - // Security options for container isolation - "--security-opt", - "no-new-privileges:true", // Prevent privilege escalation from within the container - "--security-opt", - "apparmor=docker-default", // Apply Docker's default AppArmor profile for enhanced security - - // Network isolation - completely disconnect from the internet for a secure environment - "--network=none", - - // --- Writable, EXECUTABLE Mounts for VS Code Server --- - "--tmpfs", "/home/vscode/.vscode-server:rw,exec,nosuid,size=512m,uid=1000,gid=1000", - "--tmpfs", "/home/vscode/.vscode-server-insiders:rw,exec,nosuid,size=256m,uid=1000,gid=1000", - // --- Writable, NON-EXECUTABLE Mounts for Caches, Configs, and Logs --- - "--tmpfs", "/home/vscode/.cache:rw,noexec,nosuid,size=256m,uid=1000,gid=1000", - "--tmpfs", "/home/vscode/.config:rw,noexec,nosuid,size=128m,uid=1000,gid=1000", - "--tmpfs", "/home/vscode/.local:rw,noexec,nosuid,size=256m,uid=1000,gid=1000", - "--tmpfs", "/home/vscode/.gnupg:rw,noexec,nosuid,size=32m,uid=1000,gid=1000", - "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m", - "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=512m", - "--tmpfs", "/var/log:rw,noexec,nosuid,size=128m", - "--tmpfs", "/run:rw,noexec,nosuid,size=128m", - "--tmpfs", "/home/vscode/.devcontainer:rw,noexec,nosuid,size=32m,uid=1000,gid=1000" + // Mount isolation configuration for security and development workflow + // If you need to extract something from within the container, you can use docker cp, but use it at your own risk. + // If you want to develop your devcontainer, you should comment this things, otherwise your changes inside the live container won't persist. + // Disables mounting the host workspace into the container for isolation. + "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", + // Sets a workspace path entirely isolated within the container + "workspaceFolder": "/workspace", - // Resource limits for container performance and stability - // "--memory=1g", // Limit container memory to 1GB to prevent resource exhaustion - // "--cpus=2" // Limit container to 2 CPU cores for predictable performance - ] + // Docker run arguments for security hardening and resource management + "runArgs": [ + + // Temporary filesystem mounts with security restrictions + // These provide isolated, size-limited temporary storage + "--tmpfs=/tmp:rw,noexec,nosuid,size=512m", // Main temporary directory + "--tmpfs=/var/tmp:rw,noexec,nosuid,size=512m", // System temporary directory + "--tmpfs=/dev/shm:rw,noexec,nosuid,size=64m", // Shared memory directory + + // Security hardening - drop all Linux capabilities + // This reduces the attack surface by removing unnecessary privileges + "--cap-drop=ALL", + + // Security options for container isolation + // A few security additions (AppArmor & no new privileges) + "--security-opt", "no-new-privileges", // Prevent privilege escalation + "--security-opt", "apparmor:docker-default", // Use Docker's default AppArmor profile + + // Use seccomp's default security profile + // seccomp provides system call filtering for additional security + // "--security-opt", "seccomp=default", + + // Network security configuration + // If you really want to isolate it, just disconnect it from the internet. + // You should COPY your working files inside before, otherwise you'll have to mount them manually. + // "--network=none", + + // IPv6 security - disable IPv6 to reduce attack surface + "--sysctl=net.ipv6.conf.all.disable_ipv6=1", // Disable IPv6 globally + "--sysctl=net.ipv6.conf.default.disable_ipv6=1", // Disable IPv6 by default + + // Network capability restrictions + "--cap-drop=NET_RAW", // Disable raw packet access + "--network=bridge", // Use bridge networking + + // DNS configuration for security and reliability + "--dns=1.1.1.1", // Primary DNS (Cloudflare) + "--dns=1.0.0.1", // Secondary DNS (Cloudflare) + + // Resource limits for container performance and security + // Play a little bit with resources to prevent resource exhaustion + // "--memory=512m", // Memory limit (commented out) + // "--cpus=2" // CPU limit (commented out) + ], + + // Writable mounts in case you want to set --read-only above. + // Currently no additional mounts are configured + "mounts": [ + ] } \ No newline at end of file diff --git a/.devcontainer/minimal/devcontainer.json b/.devcontainer/minimal/devcontainer.json index d84d413..156be46 100644 --- a/.devcontainer/minimal/devcontainer.json +++ b/.devcontainer/minimal/devcontainer.json @@ -25,12 +25,8 @@ // } }, - // Mount isolation configuration for security and development workflow - // If you need to extract something from within the container, you can use docker cp, but use it at your own risk. - // If you want to develop your devcontainer, you should comment this things, otherwise your changes inside the live container won't persist. - // Disables mounting the host workspace into the container for isolation. - "workspaceMount": "type=tmpfs,destination=/workspace", - // Sets a workspace path entirely isolated within the container + // Mount copying host folder into container, no isolation. + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", "workspaceFolder": "/workspace", // Docker run arguments for security hardening and resource management diff --git a/.devcontainer/paranoid/Dockerfile b/.devcontainer/paranoid/Dockerfile new file mode 100644 index 0000000..cdf4868 --- /dev/null +++ b/.devcontainer/paranoid/Dockerfile @@ -0,0 +1,151 @@ +# syntax=docker/dockerfile:1.8 +# check=error=true +# +# ISOLATED TRG DevContainer Dockerfile +# This Dockerfile creates a highly isolated development environment for Web3 security research +# with maximum security isolation, read-only filesystem, and network isolation. +# +# Key security features: +# - Non-root user execution +# - Minimal package installation +# - Security-hardened toolchain + +## Multi-stage build for Echidna +# Pull latest prebuilt Echidna binary from Crytic's official image +# Echidna is a fuzzing tool for Ethereum smart contracts +FROM --platform=linux/amd64 ghcr.io/crytic/echidna/echidna:latest AS echidna + +# Base image: Latest Debian with VS Code DevContainer support +# This provides a stable, security-focused base for development +FROM mcr.microsoft.com/vscode/devcontainers/base:debian + +# Install essential system packages for development +# These are the minimal packages needed for Web3 development tools +RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + bash-completion # Shell completion support \ + build-essential # Compilation tools (gcc, make, etc.) \ + curl # HTTP client for downloading tools \ + git # Version control system \ + jq # JSON processor for tool outputs \ + pkg-config # Package configuration helper \ + sudo # Privilege escalation (needed for some tools) \ + unzip # Archive extraction \ + vim # Text editor \ + wget # Alternative HTTP client \ + zsh # Advanced shell \ + && rm -rf /var/lib/apt/lists/* + +# Install Python development dependencies +# Required for Python-based security tools and package management +RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + python3-pip # Python package installer \ + libpython3-dev # Python development headers \ + python3-dev # Python development tools \ + python3-venv # Python virtual environment support \ + && rm -rf /var/lib/apt/lists/* + +# Switch to vscode user for security (drop privileges) +# This ensures all subsequent operations run as non-root user +USER vscode +WORKDIR /home/vscode +ENV HOME=/home/vscode + +# Install uv +RUN curl -LsSf https://astral.sh/uv/install.sh | sh + +# Update PATH environment for tool access +# Configure paths for Python, Node.js, and other tools +ENV UV_LOCAL_BIN=$HOME/.cargo/bin +ENV USR_LOCAL_BIN=/usr/local/bin +ENV LOCAL_BIN=${HOME}/.local/bin +ENV PNPM_HOME=${HOME}/.local/share/pnpm +ENV PATH=${PATH}:${USR_LOCAL_BIN}:${LOCAL_BIN}:${PNPM_HOME}:${UV_LOCAL_BIN} + +# Install Python 3.12 with uv +RUN uv python install 3.12 + +# Set the default shell execution for subsequent RUN commands +# Use zsh for better shell features and compatibility +ENV SHELL=/usr/bin/zsh +SHELL ["/bin/zsh", "-ic"] + +# Install Rust programming language +# Required for various Web3 security tools and Foundry framework +RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +ENV PATH="$HOME/.cargo/bin:$PATH" + +# Install Go programming language through asdf version manager +# asdf provides consistent version management across different tools +# Set asdf manager version for reproducibility +RUN git clone https://github.com/asdf-vm/asdf.git $HOME/.asdf --branch v0.15.0 && \ + echo '. $HOME/.asdf/asdf.sh' >> $HOME/.zshrc && \ + echo 'fpath=(${ASDF_DIR}/completions $fpath)' >> $HOME/.zshrc && \ + echo 'autoload -Uz compinit && compinit' >> $HOME/.zshrc && \ + . $HOME/.asdf/asdf.sh && \ + asdf plugin add golang && \ + asdf install golang latest && \ + asdf global golang latest + +# Switch to root user temporarily for Node.js installation +# Some tools require root access for system-wide installation +USER root + +# Install Node.js, npm, yarn, and pnpm through devcontainer features +# These are essential for JavaScript/TypeScript Web3 development +RUN curl -o- https://raw.githubusercontent.com/devcontainers/features/main/src/node/install.sh | bash +RUN chown -R vscode:vscode ${HOME}/.npm + +# Switch back to vscode user for security +USER vscode +ENV PNPM_HOME=${HOME}/.local/share/pnpm +ENV PATH=${PATH}:${PNPM_HOME} + +# Install Python-based security analysis tools (reduced set for security focus) +# These tools provide essential smart contract security analysis +# Focused on core tools: slither, mythril, crytic-compile, halmos, solc-select +RUN uv tool install slither-analyzer && \ + uv tool install crytic-compile && \ + uv tool install slither-lsp && \ + uv tool install mythril && \ + uv tool install halmos && \ + uv tool install solc-select && \ + solc-select install 0.4.26 0.5.17 0.6.12 0.7.6 0.8.10 latest && solc-select use latest + +# Install Foundry framework for Ethereum development +# Foundry provides Forge (testing), Cast (interaction), and Anvil (local blockchain) +RUN curl -fsSL https://foundry.paradigm.xyz | zsh && \ + echo 'export PATH="$HOME/.foundry/bin:$PATH"' >> ~/.zshrc && \ + export PATH="$HOME/.foundry/bin:$PATH" && \ + ~/.foundry/bin/foundryup + +# Install Hardhat globally for Ethereum development framework +# Hardhat is a popular development environment for Ethereum +RUN pnpm install hardhat -g + +# Build and install Medusa fuzzing tool +# Medusa is a fuzzing tool for smart contracts, similar to Echidna +WORKDIR $HOME/medusa +RUN git clone https://github.com/crytic/medusa $HOME/medusa && \ + export LATEST_TAG="$(git describe --tags | sed 's/-[0-9]+-gw+$//')" && \ + git checkout "$LATEST_TAG" && \ + go build -trimpath -o=$HOME/.local/bin/medusa -ldflags="-s -w" && \ + chmod 755 $HOME/.local/bin/medusa + +# Return to home directory and clean up build artifacts +WORKDIR $HOME +RUN rm -rf medusa/ + +# Copy Echidna binary from echidna stage to final image +# This provides the prebuilt Echidna tool without rebuilding +USER root +COPY --from=echidna /usr/local/bin/echidna /usr/local/bin/echidna +RUN chmod 755 /usr/local/bin/echidna + +# Final setup and verification +USER vscode +RUN echo 'Development environment ready!' && \ +echo 'Tools installed:' && \ + ls -la $HOME/.local/bin/ || true + +# Set working directory to workspace for development +WORKDIR /workspace \ No newline at end of file diff --git a/.devcontainer/paranoid/devcontainer.json b/.devcontainer/paranoid/devcontainer.json new file mode 100644 index 0000000..2438d74 --- /dev/null +++ b/.devcontainer/paranoid/devcontainer.json @@ -0,0 +1,93 @@ +{ + // For format details, see https://aka.ms/devcontainer.json. + // This is the ISOLATED version of TRG's DevContainer - provides maximum security isolation + // with a read-only filesystem and network isolation for high-security Web3 development. + "name": "(EXPERIMENTAL) Paranoid TRG's DevContainer", + + // Build configuration - uses the local Dockerfile in this directory + "build": { + "dockerfile": "Dockerfile" + }, + + // Use vscode user for security (non-root execution) + "remoteUser": "vscode", + + // Features to add to the dev container. More info: https://containers.dev/features. + // Git and GitHub CLI features for version control and GitHub integration + "features": { + "ghcr.io/devcontainers/features/git:1": {}, + "ghcr.io/devcontainers/features/github-cli:1": {} + }, + + // Container environment variables + "containerEnv": { + "SHELL": "/bin/zsh", // Use zsh as the default shell + "DEVCONTAINER_ID_LABEL": "paranoid-web3-devcontainer" // Label for container identification + }, + + // Configure tool-specific properties for VS Code + "customizations": { + "vscode": { + // Web3 security and development extensions + // check out https://marketplace.visualstudio.com/items?itemName=tintinweb.ethereum-security-bundle for more information + + // VS Code settings for security and functionality + "settings": { + // Security settings - killswitch for automated tasks + "task.autoDetect": "off", // Disable automatic task detection + "task.problemMatchers.autoDetect": "off", // Disable automatic problem matchers + + // Trust and security configuration + "security.workspace.trust.enabled": false, // Trust no one by default + + // Privacy settings - killswitch for telemetry + "telemetry.telemetryLevel": "off", // Disable all telemetry collection + + // Terminal configuration + "terminal.integrated.defaultProfile.linux": "zsh", // Use zsh by default + "terminal.integrated.profiles.linux": { "zsh": { "path": "/usr/bin/zsh" } } + // Using bash might be more safe and stable, but zsh provides better features + } + } + }, + + // Commands to run during container lifecycle + "initializeCommand": "echo 'Initializing isolated dev container...'", + "postStartCommand": "echo '๐Ÿš€ Dev container is ready for Web3 development!'", + + // Workspace configuration - isolated within container + "workspaceFolder": "/workspace", + // Mount workspace as tmpfs for complete isolation - no host file access. + // This ensures that the workspace is ephemeral and does not persist data. + "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", + + // Docker run arguments for security and isolation + "runArgs": [ + // Security hardening - drop all Linux capabilities to reduce attack surface + "--cap-drop=ALL", + + // Read-only filesystem for maximum security, preventing any persistent changes + "--read-only", + + // Security options for container isolation + "--security-opt", + "no-new-privileges:true", // Prevent privilege escalation from within the container + "--security-opt", + "apparmor=docker-default", // Apply Docker's default AppArmor profile for enhanced security + + // --- Writable, EXECUTABLE Mounts for VS Code Server --- + "--tmpfs", "/home/vscode/.vscode-server:rw,exec,nosuid,size=512m,uid=1000,gid=1000", + "--tmpfs", "/home/vscode/.vscode-server-insiders:rw,exec,nosuid,size=256m,uid=1000,gid=1000", + + // --- Writable, NON-EXECUTABLE Mounts for Caches, Configs, and Logs --- + "--tmpfs", "/home/vscode/.cache:rw,noexec,nosuid,size=256m,uid=1000,gid=1000", + "--tmpfs", "/home/vscode/.config:rw,noexec,nosuid,size=128m,uid=1000,gid=1000", + "--tmpfs", "/home/vscode/.local:rw,noexec,nosuid,size=256m,uid=1000,gid=1000", + "--tmpfs", "/home/vscode/.gnupg:rw,noexec,nosuid,size=32m,uid=1000,gid=1000", + "--tmpfs", "/tmp:rw,noexec,nosuid,size=512m", + "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=512m", + "--tmpfs", "/var/log:rw,noexec,nosuid,size=128m", + "--tmpfs", "/run:rw,noexec,nosuid,size=128m", + "--tmpfs", "/home/vscode/.devcontainer:rw,noexec,nosuid,size=32m,uid=1000,gid=1000" + ] +} \ No newline at end of file diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 22d8e99..c17b1bf 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -21,8 +21,9 @@ jobs: subFolder: - .devcontainer/auditor - .devcontainer/minimal - - .devcontainer/hardened - .devcontainer/isolated + - .devcontainer/airgapped + - .devcontainer/eth-security-toolbox steps: - name: Checkout repository uses: actions/checkout@v4 @@ -94,10 +95,12 @@ jobs: cast --version || echo "โŒ Cast not found" anvil --version || echo "โŒ Anvil not found" echo "โœ… Foundry tools verification completed" + echo "๐Ÿงช Testing Hardhat installation and functionality..." + hardhat --version || echo "โŒ Hardhat not found" push: never - name: Test Auditor Tools - if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && contains(fromJSON('[".devcontainer/auditor", ".devcontainer/hardened", ".devcontainer/isolated"]'), matrix.subFolder) + if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && contains(fromJSON('[".devcontainer/auditor", ".devcontainer/isolated", ".devcontainer/airgapped"]'), matrix.subFolder) uses: devcontainers/ci@v0.3 with: subFolder: ${{ matrix.subFolder }} @@ -111,7 +114,7 @@ jobs: echo "โœ… Auditor tools verification completed" push: never - - name: Test Isolation + - name: Test Filesystem Isolation if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && matrix.subFolder == '.devcontainer/isolated' uses: devcontainers/ci@v0.3 with: @@ -119,12 +122,35 @@ jobs: configFile: ${{ matrix.subFolder }}/devcontainer.json runCmd: | - echo "๐Ÿงช Testing Isolation..." - if (touch /test.txt); then echo "โŒ Filesystem is not read-only"; exit 1; else echo "โœ… Filesystem is read-only"; fi + echo "๐Ÿงช Verifying that no host content is present in /workspace..." + if [ -d "/workspace" ]; then + if [ -n "$(ls -A /workspace 2>/dev/null || true)" ]; then + echo "โŒ Found content in /workspace (possible host mount)" + ls -la /workspace || true + exit 1 + else + echo "โœ… /workspace exists but is empty (no host content)" + fi + else + echo "โœ… /workspace does not exist inside the container (no host mount)" + fi + echo "โœ… /workspace isolation verification completed" + push: never + + - name: Test Network Isolation + if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && matrix.subFolder == '.devcontainer/airgapped' + uses: devcontainers/ci@v0.3 + with: + subFolder: ${{ matrix.subFolder }} + configFile: ${{ matrix.subFolder }}/devcontainer.json + + runCmd: | + echo "๐Ÿงช Testing Network Isolation..." if (curl -sS https://www.google.com); then echo "โŒ Network is not isolated"; exit 1; else echo "โœ… Network is isolated"; fi - echo "โœ… Isolation verification completed" + echo "โœ… Network isolation verification completed" push: never + - name: Purge Docker cache and resources (on success) if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' run: | diff --git a/README.md b/README.md index b6e40e8..2bf60a8 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,91 @@ -# The Red Guild's devcontainer exploration +# The Red Guild's devcontainer explorations -This container is always a work in progress. Feel free to suggest improvements or requirements as +This repo is always a work in progress. Feel free to suggest improvements or requirements as well. Check out similar projects like **@Deivitto**'s auditor-docker and **@trailofbit's** eth-security-toolbox. -The most important thing about this devcontainer, is that we always try to find the best way to -install the most popular tools, so they can all work seamlessly, and at the same time add security -by default. If you want to know more, and really want to take advante of this devcontainer read +The most important thing about these devcontainers is that we always try to find the best way to +install the most popular tools, so they can all work seamlessly, and at the same time, add security +by default. If you want to know more and really want to take advantage of these devcontainers, read below. +## Quickstart with Devcontainer Wizard + +You can use any prebuilt container using our [Devcontainer Wizard](https://github.com/theredguild/devcontainer-wizard): + +![Simple wizard Example](./assets/wizard.gif) + +## Quickstart with Github Codespaces + +You can also run prebuilt containers using GitHub Codespaces: + +[![Open in Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&template_repository=theredguild/devcontainer) + ## Available Devcontainer Variants We now offer multiple devcontainer configurations to suit different security and development needs: +### **Air-gapped** (`.devcontainer/airgapped/`) + High-security development with complete network isolation. Perfect for analyzing malicious smart contracts, handling sensitive private keys, or working with classified projects that require zero external connectivity. + +- **Focus**: Isolated workspace using tmpfs; secure defaults while keeping connectivity +- **Includes**: Git, GitHub CLI; security tools available via Dockerfile +- **Security**: Capability dropping, AppArmor, no-new-privileges, multiple tmpfs mounts; not read-only +- **Network**: Uses bridge networking (no network isolation by default) +- **Extensions**: None configured by default (because it fails with `network-none`) + ### **Isolated** (`.devcontainer/isolated/`) -**Best for**: Maximum security isolation, air-gapped environments -- **Focus**: Complete isolation with read-only filesystem and network isolation -- **Includes**: All security tools, fuzzing tools (Echidna, Medusa), static analysis -- **Security**: Read-only filesystem, network isolation, capability dropping, tmpfs mounts -- **Extensions**: Comprehensive Ethereum security bundle, audit tools, decompilers -- **Use case**: High-security research and isolated analysis - -### **Hardened** (`.devcontainer/hardened/`) -**Best for**: Enhanced security with development flexibility -- **Focus**: Security hardening with maintained network connectivity -- **Includes**: Core security tools, Foundry, Hardhat, reduced tool set for security focus -- **Security**: Capability dropping, security options, resource limits, DNS hardening -- **Extensions**: Essential security extensions, development tools -- **Use case**: Secure development, security-focused research, balanced security/functionality +**Use case**: Execute untrusted code. Example: job interview. + +- **Focus**: Security hardening with maintained network connectivity and security extensions +- **Includes**: Security tools, Foundry, Hardhat, audit tools via Dockerfile +- **Security**: Capability dropping, AppArmor, no-new-privileges, tmpfs workspace isolation +- **Network**: Uses bridge networking (no network isolation by default) +- **Extensions**: Comprehensive security extensions (Ethereum Security Bundle, Trail of Bits tools) ### **Auditor** (`.devcontainer/auditor/`) -**Best for**: Smart contract auditors and security researchers -- **Focus**: Specialized audit tooling and Docker-in-Docker support +**Use case**: Do smart contract audits, security analysis, research workflows. + +- **Focus**: Specialized audit tooling with Docker-in-Docker support - **Includes**: Slither, Mythril, Crytic-compile, Foundry, Hardhat, Echidna +- **Workspace**: Host workspace bind-mounted into `/workspace` (no isolation) - **Features**: Docker-in-Docker, specialized audit extensions, focused toolchain - **Extensions**: Solidity visual auditor, metrics, audit tools, GitLens -- **Use case**: Comprehensive smart contract audits, security analysis, research workflows ### **Minimal** (`.devcontainer/minimal/`) -**Best for**: Essential development with basic security +**Use case**: Use Hardhat and Foundry without setup. Basic development, resource-constrained environments. + - **Focus**: Core tools only, streamlined development environment - **Includes**: Foundry, Hardhat, basic Solidity support, essential Python tools - **Security**: Basic hardening, capability dropping, IPv6 disabled +- **Workspace**: Host workspace bind-mounted into `/workspace` (no isolation) - **Extensions**: Core development extensions only -- **Use case**: Quick prototyping, learning, basic development, resource-constrained environments + +### **ETH Security Toolbox** (`.devcontainer/eth-security-toolbox/`) +**Use case**: Audit smart contracts using all the tools selected by Trail of Bits. + +- **Focus**: All the tools in the ETH Security Toolbox. +- **Includes**: All the tools in the ETH Security Toolbox. +- **Workspace**: Host workspace bind-mounted into `/workspace` (no isolation) +- **Extensions**: All the tools in the ETH Security Toolbox. + +### **(EXPERIMENTAL) Paranoid** (`.devcontainer/paranoid/`) +**Use case**: Maximum security isolation with read-only filesystem and ephemeral workspace. Designed for the most security-conscious developers who need to analyze potentially malicious code or work with highly sensitive data. + +- **Focus**: Strong isolation with read-only filesystem and ephemeral workspace +- **Includes**: Git, GitHub CLI; minimal by default +- **Security**: Read-only filesystem, capability dropping, extensive tmpfs mounts for VS Code and caches +- **Network**: No explicit network isolation by default (can be enabled via `--network=none`) +- **Extensions**: None configured by default ### **Legacy** (`.devcontainer/legacy/`) -**Best for**: Complete toolchain with all features (original experience) +**Use case**: Comprehensive development, learning, full-stack projects, research + - **Focus**: Full-featured development environment with comprehensive security tools - **Includes**: Complete tool suite, all security tools, fuzzing tools, analysis tools -- **Security**: Comprehensive hardening, isolation features, security options +- **Security**: Comprehensive hardening; workspace isolated via tmpfs +- **Workspace**: Isolated workspace (tmpfs mount, not host-bound) - **Extensions**: Full extension suite, all security and development tools -- **Use case**: Comprehensive development, learning, full-stack projects, research ## Project Structure @@ -60,7 +94,7 @@ The project supports multiple devcontainer configurations for different use case ``` .devcontainer/ โ”œโ”€โ”€ isolated/ # Maximum security isolation -โ”œโ”€โ”€ hardened/ # Enhanced security with flexibility +โ”œโ”€โ”€ airgapped/ # Enhanced security with flexibility โ”œโ”€โ”€ auditor/ # Specialized audit environment โ”œโ”€โ”€ minimal/ # Essential tools only โ””โ”€โ”€ legacy/ # Complete toolchain (original) diff --git a/assets/wizard.gif b/assets/wizard.gif new file mode 100644 index 0000000..7900e69 Binary files /dev/null and b/assets/wizard.gif differ