diff --git a/.devcontainer/eth-security-toolbox b/.devcontainer/eth-security-toolbox deleted file mode 160000 index 78f2b0c..0000000 --- a/.devcontainer/eth-security-toolbox +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 78f2b0c2440709a9067ae7ca64f55d2199b03b8a diff --git a/.devcontainer/eth-security-toolbox/README.md b/.devcontainer/eth-security-toolbox/README.md new file mode 100644 index 0000000..b8f6f9b --- /dev/null +++ b/.devcontainer/eth-security-toolbox/README.md @@ -0,0 +1,156 @@ +# Ethereum Security Toolbox + +This repository contains scripts to create a Docker container preinstalled and +preconfigured with all of Trail of Bits’ Ethereum security tools, including: + +* [Echidna](https://github.com/crytic/echidna) property-based fuzz tester +* [Medusa](https://github.com/crytic/medusa) fuzz tester based on go-ethereum +* [Slither](https://github.com/crytic/slither) static analysis tool +* [solc-select](https://github.com/crytic/solc-select) to quickly switch between Solidity compiler versions +* [Building secure contracts](https://github.com/crytic/building-secure-contracts) repository + +Other useful tools developed by third-parties are also included: + +* [Foundry](https://github.com/foundry-rs/foundry), a toolkit for Ethereum app development +* [Vyper](https://github.com/vyperlang/vyper), a Pythonic Smart Contract language for the EVM +* [n](https://github.com/tj/n), a Node version manager +* npm and Yarn +* Python + +## Quickstart + +Use our prebuilt Docker container to quickly install and run the toolkit: + +```shell +docker pull ghcr.io/trailofbits/eth-security-toolbox:nightly +docker run -it ghcr.io/trailofbits/eth-security-toolbox:nightly +``` + +Alternatively, build the image from scratch: + +```shell +git clone https://github.com/trailofbits/eth-security-toolbox.git +cd eth-security-toolbox +docker build -t eth-security-toolbox . +``` + +## Usage + +Simply start an instance of the Docker container: + +```shell +docker run -it ghcr.io/trailofbits/eth-security-toolbox:nightly +``` + +Several Solidity versions are preinstalled via `solc-select`. By default, `solc` +corresponds to the latest release. This can be changed using the `solc-select` +tool: + +```shell +$ solc --version +solc, the solidity compiler commandline interface +Version: 0.8.22+commit.4fc1097e.Linux.g++ +$ solc-select use 0.4.26 +$ solc --version +solc, the solidity compiler commandline interface +Version: 0.4.26+commit.4563c3fc.Linux.g++ +``` + +You can also view the installed versions and install new ones: + +```shell +$ solc-select versions +0.8.22 (current, set by /home/ethsec/.solc-select/global-version) +0.7.6 +0.6.12 +0.5.17 +0.4.26 +ethsec@f95fb29a709d:~$ solc-select install 0.8.0 +Installing solc '0.8.0'... +Version '0.8.0' installed. +ethsec@f95fb29a709d:~$ solc-select use 0.8.0 +Switched global version to 0.8.0 +$ solc --version +solc, the solidity compiler commandline interface +Version: 0.8.0+commit.c7dfd78e.Linux.g++ +``` + +The toolbox comes preinstalled with a LTS version of Node, and +[n](https://github.com/tj/n), the Node version manager. You can install other +versions of Node if needed by using `n`. Refer to their website for further +instructions. + +```shell +$ sudo n 14 + installing : node-v14.21.3 + mkdir : /usr/local/n/versions/node/14.21.3 + fetch : https://nodejs.org/dist/v14.21.3/node-v14.21.3-linux-arm64.tar.gz + copying : node/14.21.3 + installed : v14.21.3 (with npm 6.14.18) +$ node --version +v14.21.3 +``` + +## Usage in CI + +A variant of the image is published on GitHub Container Registry as +[`ghcr.io/trailofbits/eth-security-toolbox/ci`](https://github.com/trailofbits/eth-security-toolbox/pkgs/container/eth-security-toolbox%2Fci). +This variant is meant to be slightly lighter, and better suited for its use in +CI contexts such as [GitHub workflow jobs](https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container): + + +```yaml +# workflow triggers, ... + +jobs: + tests: + runs-on: ubuntu-latest + container: ghcr.io/trailofbits/eth-security-toolbox/ci:nightly + steps: + # other steps ... + - run: medusa fuzz # or any tool from the image +``` + +The main differences are: + * The container does not have a dedicated non-root user. All tools are + installed under the root user. + * Most autocompletions are not installed. + * No solc binaries are preinstalled. You may continue to use `solc-select` to + install any binaries you may need. + * pyevmasm and the building secure contracts repository are not included. + +## Container image labels + +Both `eth-security-toolbox` and `eth-security-toolbox/ci` use the following +label convention: + +| Label | Description +|--------------------|-------------------------------------------------------- +| `nightly-YYYYMMDD` | Image built from the code in `master` on day YYYY-MM-DD +| `nightly` | Alias for the latest `nightly-YYYYMMDD` container image +| `testing-BRANCH` | Image built when the tip of `BRANCH` was last updated +| `edge` | Alias for `testing-master` +| `TAG` | Image built when `TAG` was tagged +| `latest` | Alias for the latest `TAG` container image + +To keep tooling in CI predictable, we recommend picking a `nightly-YYYYMMDD` +image and pinning it by hash on your workflow file. Then, establish a process +to review the changes and update the container reference on a regular cadence, +so that you can continue to benefit from tool improvements. The following +snippet shows the syntax used to pin the image on a GitHub Actions workflow; +the hashes may be obtained from the [container registry page](https://github.com/orgs/trailofbits/packages?repo_name=eth-security-toolbox). + +```yaml +container: ghcr.io/trailofbits/eth-security-toolbox/ci:nightly-YYYYMMDD@sha256:HASH_GOES_HERE +``` + +## Getting Help + +Feel free to stop by our [Slack channel](https://slack.empirehacking.nyc/) for +help on using or extending this toolbox. + +## License + +The Ethereum Security Toolbox is licensed and distributed under the +[AGPLv3](LICENSE) license. [Contact us](mailto:opensource@trailofbits.com) if +you’re looking for an exception to the terms. diff --git a/.devcontainer/eth-security-toolbox/devcontainer.json b/.devcontainer/eth-security-toolbox/devcontainer.json new file mode 100644 index 0000000..7c8a970 --- /dev/null +++ b/.devcontainer/eth-security-toolbox/devcontainer.json @@ -0,0 +1,91 @@ +{ + // For format details, see https://aka.ms/devcontainer.json. + // This is a Dev Container based on eth-security-toolbox image created by Trail of Bits + // check https://github.com/trailofbits/eth-security-toolbox for more information. + "name": "eth-security-toolbox", + + // 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" + } + } + }, + + // 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", + + // Docker run arguments for security hardening and resource management + "runArgs": [ + // Read only filesystem except for explicitly writable volumes (check mounts) + // For a dev environment this is more a hussle than a feature. + // "--read-only", + + // 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) + ] +} \ No newline at end of file diff --git a/.devcontainer/eth-security-toolbox/motd b/.devcontainer/eth-security-toolbox/motd new file mode 100644 index 0000000..f499599 --- /dev/null +++ b/.devcontainer/eth-security-toolbox/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` +