diff --git a/.devcontainer/airgapped/devcontainer.json b/.devcontainer/airgapped/devcontainer.json index e39cb6e..5607691 100644 --- a/.devcontainer/airgapped/devcontainer.json +++ b/.devcontainer/airgapped/devcontainer.json @@ -55,19 +55,19 @@ "postStartCommand": "echo 'πŸš€ Dev container is ready for Web3 development!'", - // Mount isolation configuration for security and development workflow + // Mount hardening 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. + // Disables mounting the host workspace into the container for hardening. "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", - // Sets a workspace path entirely isolated within the container + // Sets a hardened workspace "workspaceFolder": "/workspace", // Docker run arguments for security hardening and resource management "runArgs": [ // Temporary filesystem mounts with security restrictions - // These provide isolated, size-limited temporary storage + // These provide 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 @@ -76,7 +76,7 @@ // This reduces the attack surface by removing unnecessary privileges "--cap-drop=ALL", - // Security options for container isolation + // Security options for container hardening // 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 diff --git a/.devcontainer/auditor/devcontainer.json b/.devcontainer/auditor/devcontainer.json index 338c3a2..64571be 100644 --- a/.devcontainer/auditor/devcontainer.json +++ b/.devcontainer/auditor/devcontainer.json @@ -58,9 +58,9 @@ } }, - // Mount copying host folder into container, no isolation. + // Mount copying host folder into container, no hardening. "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", - // Sets a workspace path entirely isolated within the container + // Sets a hardened workspace path "workspaceFolder": "/workspace", // Docker run arguments for security hardening and resource management diff --git a/.devcontainer/codespaces/devcontainer.json b/.devcontainer/codespaces/devcontainer.json new file mode 100644 index 0000000..c1bc01e --- /dev/null +++ b/.devcontainer/codespaces/devcontainer.json @@ -0,0 +1,38 @@ +{ + // For format details, see https://aka.ms/devcontainer.json. + // This is a Dev Container for Github Codespaces based on eth-security-toolbox image created by Trail of Bits + // check https://github.com/trailofbits/eth-security-toolbox for more information. + "name": "Codespaces TRG's DevContainer", + + // Build configuration - uses the eth-security-toolbox image + "image": "ghcr.io/trailofbits/eth-security-toolbox:nightly", + // Configure tool-specific properties for VS Code + "customizations": { + "vscode": { + // Specialized extensions for smart contract auditing and development + "extensions": [ + // check out https://marketplace.visualstudio.com/items?itemName=tintinweb.ethereum-security-bundle for more information + "tintinweb.ethereum-security-bundle", // includes what is listed above ^ + "tintinweb.vscode-ethover", + "trailofbits.weaudit", + "trailofbits.contract-explorer", + "trailofbits.sarif-explorer" + ], + // VS Code settings optimized for auditing workflows + "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": "bash" + } + } + }, +} \ No newline at end of file diff --git a/.devcontainer/codespaces/motd b/.devcontainer/codespaces/motd new file mode 100644 index 0000000..f499599 --- /dev/null +++ b/.devcontainer/codespaces/motd @@ -0,0 +1,29 @@ + +β”Œβ”€β”€ β”Œβ”€β”€β” ──┬── +β”œβ”€ └──┐ β”‚ +└──THEREUM─┴──┴ECURITY─┴OOLBOX + +https://github.com/trailofbits/eth-security-toolbox + +by ################ + ##########TRAIL# + #### + #### ########### + #### ########### + \### #### #### + /\\# of #### #### + / \ ############ + \__/ #### #### + \### #### + /\\######### + /__\\##BITS# + +Security Tools and Resources Installed: + +https://github.com/crytic/echidna +https://github.com/crytic/medusa +https://github.com/crytic/slither +https://github.com/crytic/building-secure-contracts + +Use `solc-select` to switch between different versions of `solc` + diff --git a/.devcontainer/eth-security-toolbox/devcontainer.json b/.devcontainer/eth-security-toolbox/devcontainer.json index 7c8a970..65df438 100644 --- a/.devcontainer/eth-security-toolbox/devcontainer.json +++ b/.devcontainer/eth-security-toolbox/devcontainer.json @@ -36,9 +36,9 @@ } }, - // Mount copying host folder into container, no isolation. + // Mount copying host folder into container, no hardening. "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", - // Sets a workspace path entirely isolated within the container + // Sets a workspace path entirely hardened within the container "workspaceFolder": "/workspace", // Docker run arguments for security hardening and resource management @@ -48,7 +48,7 @@ // "--read-only", // Temporary filesystem mounts with security restrictions - // These provide isolated, size-limited temporary storage + // These provide hardened, 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 @@ -57,7 +57,7 @@ // This reduces the attack surface by removing unnecessary privileges "--cap-drop=ALL", - // Security options for container isolation + // Security options for container hardening // 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 diff --git a/.devcontainer/isolated/Dockerfile b/.devcontainer/hardened/Dockerfile similarity index 100% rename from .devcontainer/isolated/Dockerfile rename to .devcontainer/hardened/Dockerfile diff --git a/.devcontainer/isolated/devcontainer.json b/.devcontainer/hardened/devcontainer.json similarity index 93% rename from .devcontainer/isolated/devcontainer.json rename to .devcontainer/hardened/devcontainer.json index 56a26c7..833be0a 100644 --- a/.devcontainer/isolated/devcontainer.json +++ b/.devcontainer/hardened/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": "Isolated TRG's DevContainer", + "name": "Hardened TRG's DevContainer", // Build configuration - uses the local Dockerfile in this directory "build": { @@ -23,7 +23,7 @@ // Container environment variables "containerEnv": { "SHELL": "/bin/zsh", // Use zsh as the default shell - "DEVCONTAINER_ID_LABEL": "isolated-web3-devcontainer" // Label for container identification + "DEVCONTAINER_ID_LABEL": "hardened-web3-devcontainer" // Label for container identification }, // Configure tool-specific properties for VS Code @@ -65,19 +65,18 @@ "postStartCommand": "echo 'πŸš€ Dev container is ready for Web3 development!'", - // Mount isolation configuration for security and development workflow + // Mount hardening 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. + // Disables mounting the host workspace into the container for hardening. "workspaceMount": "type=tmpfs,destination=/workspace,tmpfs-mode=1777", - // Sets a workspace path entirely isolated within the container "workspaceFolder": "/workspace", // Docker run arguments for security hardening and resource management "runArgs": [ // Temporary filesystem mounts with security restrictions - // These provide isolated, size-limited temporary storage + // These provide hardened, 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 @@ -86,7 +85,7 @@ // This reduces the attack surface by removing unnecessary privileges "--cap-drop=ALL", - // Security options for container isolation + // Security options for container hardening // 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 diff --git a/.devcontainer/legacy/devcontainer.json b/.devcontainer/legacy/devcontainer.json index bece536..4dd064d 100644 --- a/.devcontainer/legacy/devcontainer.json +++ b/.devcontainer/legacy/devcontainer.json @@ -21,10 +21,10 @@ // } }, - // Mount isolation. 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. + // Mount hardening. 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. "workspaceMount": "type=tmpfs,destination=/workspace", - // Sets a workspace path entirely isolated within the container + // Sets a workspace path entirely hardened within the container "workspaceFolder": "/home/vscode/quests", "runArgs": [ // Read only filesystem except for explicitly writable volumes (check mounts) diff --git a/.devcontainer/minimal/devcontainer.json b/.devcontainer/minimal/devcontainer.json index 156be46..e296490 100644 --- a/.devcontainer/minimal/devcontainer.json +++ b/.devcontainer/minimal/devcontainer.json @@ -1,6 +1,6 @@ { // For format details, see https://aka.ms/devcontainer.json. - // This is the MINIMAL version of TRG's DevContainer - provides essential security isolation + // This is the MINIMAL version of TRG's DevContainer - provides essential security hardening // with a balanced approach between security and usability for Web3 development. "name": "Minimal TRG's DevContainer", @@ -25,7 +25,7 @@ // } }, - // Mount copying host folder into container, no isolation. + // Mount copying host folder into container, no hardening. "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached", "workspaceFolder": "/workspace", @@ -36,7 +36,7 @@ // "--read-only", // Temporary filesystem mounts with security restrictions - // These provide isolated, size-limited temporary storage + // These provide hardened, 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 @@ -45,7 +45,7 @@ // This reduces the attack surface by removing unnecessary privileges "--cap-drop=ALL", - // Security options for container isolation + // Security options for container hardening // 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 diff --git a/.devcontainer/paranoid/Dockerfile b/.devcontainer/paranoid/Dockerfile index cdf4868..622d929 100644 --- a/.devcontainer/paranoid/Dockerfile +++ b/.devcontainer/paranoid/Dockerfile @@ -1,9 +1,9 @@ # 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. +# PARANOID TRG DevContainer Dockerfile +# This Dockerfile creates a highly paranoid development environment for Web3 security research +# with maximum security hardening, read-only filesystem, and network hardening. # # Key security features: # - Non-root user execution diff --git a/.devcontainer/paranoid/devcontainer.json b/.devcontainer/paranoid/devcontainer.json index 2438d74..f7ffc4a 100644 --- a/.devcontainer/paranoid/devcontainer.json +++ b/.devcontainer/paranoid/devcontainer.json @@ -1,7 +1,7 @@ { // 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 maximum security hardening + // with a read-only filesystem and network hardening for high-security Web3 development. "name": "(EXPERIMENTAL) Paranoid TRG's DevContainer", // Build configuration - uses the local Dockerfile in this directory @@ -52,16 +52,16 @@ }, // 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 + // Workspace configuration - hardened within container "workspaceFolder": "/workspace", - // Mount workspace as tmpfs for complete isolation - no host file access. + // Mount workspace as tmpfs for complete hardening - 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 + // Docker run arguments for security and hardening "runArgs": [ // Security hardening - drop all Linux capabilities to reduce attack surface "--cap-drop=ALL", @@ -69,7 +69,7 @@ // Read-only filesystem for maximum security, preventing any persistent changes "--read-only", - // Security options for container isolation + // Security options for container hardening "--security-opt", "no-new-privileges:true", // Prevent privilege escalation from within the container "--security-opt", diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c17b1bf..3e99333 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -21,7 +21,7 @@ jobs: subFolder: - .devcontainer/auditor - .devcontainer/minimal - - .devcontainer/isolated + - .devcontainer/hardened - .devcontainer/airgapped - .devcontainer/eth-security-toolbox steps: @@ -100,7 +100,7 @@ jobs: push: never - name: Test Auditor Tools - if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && contains(fromJSON('[".devcontainer/auditor", ".devcontainer/isolated", ".devcontainer/airgapped"]'), matrix.subFolder) + if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && contains(fromJSON('[".devcontainer/auditor", ".devcontainer/hardened", ".devcontainer/airgapped"]'), matrix.subFolder) uses: devcontainers/ci@v0.3 with: subFolder: ${{ matrix.subFolder }} @@ -114,8 +114,8 @@ jobs: echo "βœ… Auditor tools verification completed" push: never - - name: Test Filesystem Isolation - if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && matrix.subFolder == '.devcontainer/isolated' + - name: Test Filesystem Hardening + if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && matrix.subFolder == '.devcontainer/hardened' uses: devcontainers/ci@v0.3 with: subFolder: ${{ matrix.subFolder }} @@ -134,10 +134,10 @@ jobs: else echo "βœ… /workspace does not exist inside the container (no host mount)" fi - echo "βœ… /workspace isolation verification completed" + echo "βœ… /workspace Hardening verification completed" push: never - - name: Test Network Isolation + - name: Test Network Hardening if: success() && steps.check.outputs.exists == 'true' && steps.changed.outputs.changed == 'true' && matrix.subFolder == '.devcontainer/airgapped' uses: devcontainers/ci@v0.3 with: @@ -145,9 +145,9 @@ jobs: 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 "βœ… Network isolation verification completed" + echo "πŸ§ͺ Testing Network Hardening..." + if (curl -sS https://www.google.com); then echo "❌ Network is not hardened"; exit 1; else echo "βœ… Network is hardened"; fi + echo "βœ… Network Hardening verification completed" push: never diff --git a/README.md b/README.md index 2bf60a8..327f425 100644 --- a/README.md +++ b/README.md @@ -9,37 +9,48 @@ install the most popular tools, so they can all work seamlessly, and at the same by default. If you want to know more and really want to take advantage of these devcontainers, read below. +> [!IMPORTANT] +> Dev Containers can improve your workflow, but they are **not a fully secure environment**. +> If you need to run untrusted or suspicious code, use GitHub Codespaces, GitPod, or a similar remote setup β€” **never run it directly on your machine**. + + +> [!CAUTION] +> **VS Code considerations:** +> +> VS Code does a lot to improve user experience, but that doesn't come without security tradeoffs. VS Code might allow API calls that can lead to running arbitrary commands on the host machine, and by default, it shares sockets such as the gpg-agent’s, which means keys stored outside the container can be used for signing. This opens the door to blind-signing commits scenarios, where a process inside the container may trigger signatures without the user’s full awareness. If you want to deep dive into these "tricks", we're working on an article covering the most relevant of them β€” stay tuned. + +## Quickstart with GitHub Codespaces + +You can also run our prebuilt container intended for 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%2Fdevcontainer&skip_quickstart=true&repo=772110522&machine=basicLinux32gb&geo=UsEast&devcontainer_path=.devcontainer%2Fcodespaces%2Fdevcontainer.json) + ## 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. + Complete network hardening. -- **Focus**: Isolated workspace using tmpfs; secure defaults while keeping connectivity +- **Focus**: Hardened workspace using tmpfs without network. - **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/`) -**Use case**: Execute untrusted code. Example: job interview. +### **Hardened** (`.devcontainer/hardened/`) +**Use case**: Use an hardened workspace without copying your environment. - **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 +- **Security**: Capability dropping, AppArmor, no-new-privileges, tmpfs workspace hardening - **Network**: Uses bridge networking (no network isolation by default) - **Extensions**: Comprehensive security extensions (Ethereum Security Bundle, Trail of Bits tools) @@ -48,7 +59,7 @@ We now offer multiple devcontainer configurations to suit different security and - **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) +- **Workspace**: Host workspace bind-mounted into `/workspace` - **Features**: Docker-in-Docker, specialized audit extensions, focused toolchain - **Extensions**: Solidity visual auditor, metrics, audit tools, GitLens @@ -58,7 +69,7 @@ We now offer multiple devcontainer configurations to suit different security and - **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) +- **Workspace**: Host workspace bind-mounted into `/workspace` - **Extensions**: Core development extensions only ### **ETH Security Toolbox** (`.devcontainer/eth-security-toolbox/`) @@ -66,16 +77,20 @@ We now offer multiple devcontainer configurations to suit different security and - **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) +- **Workspace**: Host workspace bind-mounted into `/workspace` (no hardening) - **Extensions**: All the tools in the ETH Security Toolbox. +### **Codespaces** (`.devcontainer/codespaces/`) + +Intended for use with GitHub Codespaces, is like `eth-security-toolbox` variant without `runArgs`. + ### **(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. +**Use case**: Maximum security hardening with read-only filesystem and ephemeral workspace. -- **Focus**: Strong isolation with read-only filesystem and ephemeral workspace +- **Focus**: Strong hardening 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`) +- **Network**: No explicit network hardening by default (can be enabled via `--network=none`) - **Extensions**: None configured by default ### **Legacy** (`.devcontainer/legacy/`) @@ -83,8 +98,8 @@ We now offer multiple devcontainer configurations to suit different security and - **Focus**: Full-featured development environment with comprehensive security tools - **Includes**: Complete tool suite, all security tools, fuzzing tools, analysis tools -- **Security**: Comprehensive hardening; workspace isolated via tmpfs -- **Workspace**: Isolated workspace (tmpfs mount, not host-bound) +- **Security**: Comprehensive hardening; workspace hardened via tmpfs +- **Workspace**: Hardened workspace (tmpfs mount, not host-bound) - **Extensions**: Full extension suite, all security and development tools ## Project Structure @@ -93,7 +108,7 @@ The project supports multiple devcontainer configurations for different use case ``` .devcontainer/ -β”œβ”€β”€ isolated/ # Maximum security isolation +β”œβ”€β”€ hardened/ # Hardened β”œβ”€β”€ airgapped/ # Enhanced security with flexibility β”œβ”€β”€ auditor/ # Specialized audit environment β”œβ”€β”€ minimal/ # Essential tools only