The Red Guild's devcontainer explorations

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 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.

[!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:

Quickstart with Devcontainer Wizard

You can use any prebuilt container using our Devcontainer Wizard:

Available Devcontainer Variants

We now offer multiple devcontainer configurations to suit different security and development needs:

Air-gapped (.devcontainer/airgapped/)

Complete network hardening.

• 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)

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 hardening
• Network: Uses bridge networking (no network isolation by default)
• Extensions: Comprehensive security extensions (Ethereum Security Bundle, Trail of Bits tools)

Auditor (.devcontainer/auditor/)

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
• Features: Docker-in-Docker, specialized audit extensions, focused toolchain
• Extensions: Solidity visual auditor, metrics, audit tools, GitLens

Minimal (.devcontainer/minimal/)

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
• Extensions: Core development extensions only

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 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 hardening 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 hardening by default (can be enabled via --network=none)
• Extensions: None configured by default

Legacy (.devcontainer/legacy/)

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; workspace hardened via tmpfs
• Workspace: Hardened workspace (tmpfs mount, not host-bound)
• Extensions: Full extension suite, all security and development tools

Project Structure

The project supports multiple devcontainer configurations for different use cases:

.devcontainer/
├── hardened/          # Hardened
├── airgapped/         # Enhanced security with flexibility
├── eth-security-toolbox/ # Based on Trail of Bits's dockerfile
├── codespaces         # GitHub Codespaces Variant
├── auditor/           # Specialized audit environment
├── minimal/           # Essential tools only
└── legacy/            # Complete toolchain (original)

Quick Start

1. Choose your variant based on your needs (see above)
2. Navigate to the devcontainer directory: cd .devcontainer
3. Open in VS Code: code .
4. Reopen in Container: Select the appropriate devcontainer when prompted

Requirements

1. Visual Studio Code.
2. DevContainer extension by MS: ms-vscode-remote.remote-containers.
3. Must have installed on your local OS: docker and docker-buildx.

Kick-off

1. Start the docker service, and make sure your user is in the docker group. Otherwise, add yourself to it but you'll have to log in back again.
2. Clone this repo and navigate to your preferred devcontainer variant:

   git clone <this-repo>
   cd .devcontainer/[auditor|minimal|legacy-theredguild|legacy-minimal]
   

3. Open the variant folder with VS Code: Running code . works well.
4. Select "Reopen in Container" and wait. This will build the container volume.
5. First time setup: If this is your first time, you'll be prompted to press enter on a console log that triggers the terminal.
6. Subsequent uses: Go to the extensions section, click the Remote Explorer tab and select the active devcontainer.

Pro Tip: Each variant has its own configuration, so you can switch between them by opening different variant folders in VS Code.

Usage

If you open the Command Palette (Ctrl+Shift+p or whatever your shortcut is) you can access several features:

• You can attach VS Code to a running container, where you can open any folder or Clone a repository.
• You can open new folders or workspaces of your liking inside the current volume.
• You can even clone a new repository in a new volume based on the same devcontainer.

Features Overview

Note: The features listed below are primarily for the Legacy The Red Guild variant. Each variant has its own tailored set of features. Check the specific variant's configuration for details.

Extensions

• JuanBlanco.solidity
• tintinweb.solidity-visual-auditor
• tintinweb.solidity-metrics
• tintinweb.vscode-solidity-flattener
• tintinweb.vscode-vyper
• tintinweb.vscode-LLL
• streetsidesoftware.code-spell-checker
• gimenete.github-linker
• ryu1kn.partial-diff
• tintinweb.vscode-inline-bookmarks
• eamodio.gitlens
• tintinweb.vscode-ethover
• trailofbits.weaudit
• tintinweb.vscode-inline-bookmarks
• tintinweb.vscode-solidity-language
• tintinweb.graphviz-interactive-preview
• NomicFoundation.hardhat-solidity
• Olympixai.olympix
• trailofbits.contract-explorer
• tintinweb.vscode-decompiler

Frameworks

• Foundry: Really fast modular toolkit (forge, anvil, cast).
• Hardhat: Dev environment to develop, deploy, test and debug.

Security Tools

• Fuzzing:

  • Medusa: Parallelized, coverage-guided, mutational Solidity smart contract fuzzing, powered by go-ethereum.
  • Echidna: Fuzz testing for Ethereum contracts (prebuilt binary).
  • ityfuzz: Ethereum fuzzing tool for contract vulnerabilities.

• Static Analysis:

  • Slither: Static analysis for Solidity and Vyper.
    • Slitherin: Slither detectors.
  • Semgrep: Lightweight static analysis with custom rule definitions.

• Symbolic execution:

  • Mythril: A symbolic-execution-based securty analysis tool for EVM bytecode.
  • Halmos: A symbolic testing tool for EVM smart contracts.

• Decompilers:

  • Panoramix: Smart contract decompiler.

• Other:

  • Slither-LSP: Language server for enhanced contract analysis.
  • napalm: A project management utility for custom solidity vulnerability detectors. To include some default collections you need to i