Merge branch 'master' into feat/capture-return-values

.github/workflows/docker.yml

@@ -0,0 +1,56 @@
+name: Docker
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "*"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        id: buildx
+        with:
+          install: true
+
+      - name: Set Docker metadata
+        id: metadata
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=tag
+            type=ref,event=branch,prefix=testing-
+            type=edge
+
+      - name: GitHub Container Registry Login
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker Build and Push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64
+          target: final-ubuntu
+          file: Dockerfile
+          pull: true
+          push: true
+          tags: ${{ steps.metadata.outputs.tags }}
+          labels: ${{ steps.metadata.outputs.labels }}
+          cache-from: ${{ (github.event_name != 'schedule' && 'type=gha') || '' }}
+          cache-to: type=gha,mode=max

Dockerfile

@@ -0,0 +1,53 @@
+## medusa build process
+FROM golang:1.22 AS medusa
+
+WORKDIR /src
+COPY . /src/medusa/
+RUN cd medusa && \
+    go build -trimpath -o=/usr/local/bin/medusa -ldflags="-s -w" && \
+    chmod 755 /usr/local/bin/medusa
+
+
+## Python dependencies
+FROM ubuntu:noble AS builder-python3
+RUN apt-get update && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-suggests --no-install-recommends \
+        gcc \
+        python3 \
+        python3-dev \
+        python3-venv
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+ENV PIP_NO_CACHE_DIR=1
+RUN python3 -m venv /venv && /venv/bin/pip3 install --no-cache --upgrade setuptools pip
+RUN /venv/bin/pip3 install --no-cache slither-analyzer solc-select
+
+
+## final image assembly
+FROM ubuntu:noble AS final-ubuntu
+
+RUN apt-get update && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-suggests --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        jq \
+        python3 \
+        && \
+    rm -rf /var/lib/apt/lists/*
+
+# Include python tools
+COPY --from=builder-python3 /venv /venv
+ENV PATH="$PATH:/venv/bin"
+
+# Include JS package managers, actions/setup-node can get confused if they're not around
+RUN curl -fsSL https://raw.githubusercontent.com/tj/n/v10.1.0/bin/n -o n && \
+    if [ ! "a09599719bd38af5054f87b8f8d3e45150f00b7b5675323aa36b36d324d087b9  n" = "$(sha256sum n)" ]; then \
+        echo "N installer does not match expected checksum! exiting"; \
+        exit 1; \
+    fi && \
+    cat n | bash -s lts && rm n && \
+    npm install -g n yarn && \
+    n stable --cleanup && n prune && npm --force cache clean
+
+# Include medusa
+COPY --chown=root:root --from=medusa /usr/local/bin/medusa /usr/local/bin/medusa

cmd/fuzz_flags.go

@@ -69,8 +69,11 @@ func addFuzzFlags() error {
 	// Exploration mode
 	fuzzCmd.Flags().Bool("explore", false, "enables exploration mode")
 
-	// Run slither on-the-fly
-	fuzzCmd.Flags().Bool("use-slither", false, "runs slither")
+	// Run slither while still trying to use the cache
+	fuzzCmd.Flags().Bool("use-slither", false, "runs slither and use the current cached results")
+
+	// Run slither and overwrite the cache
+	fuzzCmd.Flags().Bool("use-slither-force", false, "runs slither and overwrite the cached results")
 	return nil
 }
 
@@ -196,7 +199,7 @@ func updateProjectConfigWithFuzzFlags(cmd *cobra.Command, projectConfig *config.
 		}
 	}
 
-	// Update configuration to run slither
+	// Update configuration to run slither while using current cache
 	if cmd.Flags().Changed("use-slither") {
 		useSlither, err := cmd.Flags().GetBool("use-slither")
 		if err != nil {
@@ -207,5 +210,17 @@ func updateProjectConfigWithFuzzFlags(cmd *cobra.Command, projectConfig *config.
 		}
 	}
 
+	// Update configuration to run slither and overwrite the current cache
+	if cmd.Flags().Changed("use-slither-force") {
+		useSlitherForce, err := cmd.Flags().GetBool("use-slither-force")
+		if err != nil {
+			return err
+		}
+		if useSlitherForce {
+			projectConfig.Slither.UseSlither = true
+			projectConfig.Slither.OverwriteCache = true
+		}
+	}
+
 	return nil
 }

compilation/types/slither.go

@@ -16,14 +16,18 @@ type SlitherConfig struct {
 	UseSlither bool `json:"useSlither"`
 	// CachePath determines the path where the slither cache file will be located
 	CachePath string `json:"cachePath"`
+	// OverwriteCache determines whether to overwrite the cache or not
+	// We will not serialize this value since it is something we want to control internally
+	OverwriteCache bool `json:"-"`
 }
 
 // NewDefaultSlitherConfig provides a default configuration to run slither. The default configuration enables the
 // running of slither with the use of a cache.
 func NewDefaultSlitherConfig() (*SlitherConfig, error) {
 	return &SlitherConfig{
-		UseSlither: true,
-		CachePath:  "slither_results.json",
+		UseSlither:     true,
+		CachePath:      "slither_results.json",
+		OverwriteCache: false,
 	}, nil
 }
 
@@ -53,7 +57,7 @@ func (s *SlitherConfig) RunSlither(target string) (*SlitherResults, error) {
 	var haveCachedResults bool
 	var out []byte
 	var err error
-	if s.CachePath != "" {
+	if s.CachePath != "" && !s.OverwriteCache {
 		// Check to see if the file exists in the first place.
 		// If not, we will re-run slither
 		if _, err = os.Stat(s.CachePath); os.IsNotExist(err) {

docs/src/cli/fuzz.md

@@ -109,6 +109,28 @@ The `--deployer` flag allows you to update `medusa`'s contract deployer (equival
 medusa fuzz --deployer "0x40000"
 ```
 
+### `--use-slither`
+
+The `--use-slither` flag allows you to run Slither on the codebase to extract valuable constants for mutation testing.
+Equivalent to [`slither.useSlither`](../project_configuration/slither_config.md#useslither). Note
+that if there are cached results (via [`slither.CachePath`](../project_configuration/slither_config.md#cachepath)) then
+the cache will be used.
+
+```shell
+# Run slither and attempt to use cache, if available
+medusa fuzz --use-slither
+```
+
+### `--use-slither-force`
+
+The `--use-slither-force` flag is similar to `--use-slither` except the cache at `slither.CachePath` will be
+overwritten.
+
+```shell
+# Run slither and overwrite the cache
+medusa fuzz --use-slither-force
+```
+
 ### `--fail-fast`
 
 The `--fail-fast` flag enables fast failure (equivalent to
@@ -142,7 +164,8 @@ medusa fuzz --no-color
 
 ### `--explore`
 
-The `--explore` flag enables exploration mode. This sets the [`StopOnFailedTest`](../project_configuration/testing_config.md#stoponfailedtest) and [`StopOnNoTests`](../project_configuration/testing_config.md#stoponnotests) fields to `false` and turns off assertion, property, and optimization testing.
+The `--explore` flag enables exploration mode. This sets the [`StopOnFailedTest`](../project_configuration/testing_config.md#stoponfailedtest) and [`StopOnNoTests`](../project_configuration/testing_config.md#stoponnotests)
+fields to `false` and turns off assertion, property, and optimization testing.
 
 ```shell
 # Enable exploration mode

fuzzing/fuzzer.go

@@ -533,9 +533,9 @@ func chainSetupFromCompilations(fuzzer *Fuzzer, testChain *chain.TestChain) (*ex
 						Block:            block,
 						TransactionIndex: len(block.Messages) - 1,
 					}
-					// Revert to genesis and re-run the failed contract deployment tx.
+					// Revert to one block before and re-run the failed contract deployment tx.
 					// We should be able to attach an execution trace; however, if it fails, we provide the ExecutionResult at a minimum.
-					err = testChain.RevertToBlockNumber(0)
+					err = testChain.RevertToBlockNumber(block.Header.Number.Uint64() - 1)
 					if err != nil {
 						return nil, fmt.Errorf("failed to reset to genesis block: %v", err)
 					} else {