refactor: review feedback

Author: Marius Benthin

.github/workflows/build.yml

@@ -18,15 +18,6 @@ jobs:
       contents: read
       packages: write
 
-    strategy:
-      matrix:
-        include:
-          - thor_version: "10"
-            tag: thor10
-            extra_tags: latest
-          - thor_version: "11"
-            tag: thor11
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -44,16 +35,14 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=raw,value=${{ matrix.tag }},enable={{is_default_branch}}
-            type=raw,value=${{ matrix.extra_tags }},enable=${{ matrix.extra_tags != '' && github.ref_name == github.event.repository.default_branch }}
-            type=sha,prefix=sha-${{ matrix.tag }}-
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=sha-
 
       - name: Build and push image
         uses: docker/build-push-action@v6
         with:
           context: .
           file: Containerfile
-          build-args: THOR_VERSION=${{ matrix.thor_version }}
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

Containerfile

@@ -24,10 +24,8 @@ RUN mkdir -p \
     adduser -S -H -D -g "Thunderstorm User" thunderstorm && \
     chown -R thunderstorm "$TEMP_DIR" "$TARGET_DIR"
 
-# copy version-specific entrypoint script
-ARG THOR_VERSION
-RUN test -n "$THOR_VERSION" || (echo "THOR_VERSION is required!" && false)
-COPY entrypoint.thor${THOR_VERSION}.sh /entrypoint.sh
+# copy unified entrypoint script
+COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 
 USER thunderstorm

README.md

@@ -1,86 +1,69 @@
-# Deploy Thunderstorm in a Container Environment
+# Deploy Thunderstorm as a Container
 
-Many companies rely on the containerization of services to increase economic and technical efficiency. Customers which use containerization need to create images that make the services available as containers. In this guide, we provide you with the necessary requirements and templates to run Thunderstorm as a container.
+[THOR Thunderstorm](https://www.nextron-systems.com/thor-thunderstorm/) is a web service that lets you scan files with our compromise assessment tool THOR through a Web-API. This guide provides a base [container image](https://github.com/NextronSystems/thunderstorm-deployment/pkgs/container/thunderstorm-deployment) and a [Docker Compose template](https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.yml) so you can run Thunderstorm as a container with just providing your contract token.
 
-## Quick Start
 
-Thunderstorm is a web service which allows you to scan files with our compromise assessment tool THOR through a Web-API. Ready-to-use base images are published to the GitHub Container Registry and only require your contract token to run.
+## Quick-Start
 
-### Contract Token
-
-The contract token is used to download the THOR binaries on first container start. You can find it in the [Nextron Portal](https://portal.nextron-systems.com/ui/contracts/contracts) under *Contracts & Licenses → Contracts → Actions → cloud icon → THOR Download Token*.
-
-<img src="images/contract_token.png" alt="Contract Token location in Nextron Portal" width="500">
-
----
-
-
-Two versions are available:
-
-| Version | Image tag | Compose file | Default port |
-|---|---|---|---|
-| THOR 10.7 (stable) | `:thor10` | `docker-compose.thor10.yml` | 8080 |
-| THOR 11 (techpreview) | `:thor11` | `docker-compose.thor11.yml` | 8000 |
-
-### THOR 10.7
-
-1. Download the compose file
+1. Download the [Docker Compose](https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.yml) file
 
 ```
-curl -O https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.thor10.yml
+curl -O https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.yml
 ```
 
-2. Start the service with your contract token
-
-```
-CONTRACT_TOKEN=<CONTRACT_TOKEN> docker compose -f docker-compose.thor10.yml up -d
-```
+2. Get a contract token from the [Nextron Portal](https://portal.nextron-systems.com/ui/contracts/contracts) (see [Contract-Token](#contract-token))
 
-### THOR 11
-
-1. Download the compose file
+3. Start the service with your contract token
 
 ```
-curl -O https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.thor11.yml
+CONTRACT_TOKEN=<CONTRACT_TOKEN> docker compose up -d
 ```
 
-2. Start the service with your contract token
+Thunderstorm is exposed on port **8080** by default.
 
-```
-CONTRACT_TOKEN=<CONTRACT_TOKEN> docker compose -f docker-compose.thor11.yml up -d
-```
+## Contract-Token
 
-On first start, Thunderstorm downloads the THOR binaries using your `CONTRACT_TOKEN` (your non-host-based Thunderstorm license) and persists them in a Docker volume so subsequent restarts are instant. THOR signatures are updated automatically on every start.
+Deploying Thunderstorm as a container requires a **non-host-based** Thunderstorm license.
 
-Each compose file contains commented environment variables for all available configuration options.
+On first start, the container uses your contract token to download the THOR binaries and persists them in a Docker volume so subsequent restarts are instant. You can omit the contract token afterwards as long as the volume exists.
 
-## Signature Updates
+A contract token can be retrieved from the [Nextron Portal](https://portal.nextron-systems.com/ui/contracts/contracts) under *Contracts & Licenses → Contracts → Actions → cloud icon → THOR Download Token*.
 
-On every container start, THOR signatures are updated automatically. For THOR 11, signatures are additionally refreshed periodically while running (every 24 hours by default, configurable via `SIGNATURE_UPDATE_INTERVAL`).
+<img src="images/contract_token.png" alt="Contract Token location in Nextron Portal" width="500">
 
-### Rolling Deployment
+## Tech-Preview
 
-If you are running a single Thunderstorm instance, you may want to use a Rolling Deployment to prevent a downtime of your Thunderstorm service. A Rolling Deployment spawns a new container and stops the old one after ensuring that the new one is healthy and ready to accept requests. The configuration differs between container management systems such as Kubernetes, Docker or Docker Swarm.
+If you want to use the techpreview channel (currently THOR 11) you need to set `TECHPREVIEW=1`. If it is omitted it will downgrade to the stable channel again.
 
-For Docker we recommend `start-first` as value for `deploy.update_config.order`, as configured in both compose files.
+The compose file contains commented environment variables for all available configuration options. Some options only apply to specific THOR major versions, for example, `SIGNATURE_UPDATE_INTERVAL` is only available for THOR 11.
 
-### Multiple Replicas
+## Signature Updates
 
-If you want to deploy multiple Thunderstorm instances, we recommend to distribute the requests equally using a load-balancer such as [Traefik](https://traefik.io/traefik) or [Nginx](https://nginx.org).
+On every container start, THOR signatures are updated automatically. You can enforce a signature update by restarting the service with a brief downtime:
+```
+docker compose up -d --force-recreate
+```
 
-## Passing Additional Arguments
+If a brief downtime is not acceptable, you may want to consider a Docker Swarm setup with start-first update config or use the [techpreview channel](#tech-preview) (currently THOR 11) which allows you to update signatures periodically while running. By default, THOR 11 updates signatures every 24 hours but it can be customized via `SIGNATURE_UPDATE_INTERVAL` environment variable.
 
-Any argument supported by Thunderstorm or THOR can be passed via the `THUNDERSTORM_ARGS` and `THOR_ARGS` environment variables in the compose file. This means new parameters released in future versions are available immediately without any changes to the image or entrypoint.
+## Additional Arguments
 
-For example, to forward scan results to a remote SIEM (THOR 11):
+If you need to customize the THOR scan behavior, you can pass additional arguments via `THOR_ARGS` environment variable. For example, to forward scan results to a remote SIEM:
 
 ```yaml
 environment:
   THOR_ARGS: "--remote-log splunk.intern:514:DEFAULT:TCP --remote-log elastic.intern:1514:JSON:TCP"
 ```
 
+A full list of all supported arguments can be derived from the THOR binary using `./thor-linux-64 --fullhelp`.
+
 ## Security
 
 The communication between a client and the Thunderstorm service could involve sensitive files. Therefore, we highly recommend to encrypt the traffic using TLS by mounting the certificate and private key via the built-in secrets functionality of Docker or Kubernetes into the container. In addition, you need to specify the file path to the TLS certificate and private key in the environment variables `TLS_CERT` and `TLS_KEY`.
 
 Out of the box, Thunderstorm API is unauthenticated and does not support authentication providers at the moment. If you require an authentication layer, we suggest to use a proxy middleware which delegates the authentication to an external provider such as [Microsoft Entra ID](https://www.microsoft.com/de-de/security/business/identity-access/microsoft-entra-id).
+
+## Limitations
+
+### Load-Balancing
+Thunderstorm allows you to send **asynchronous requests** and poll the results using an ID. Currently, Thunderstorm instances do not share their results with each other. If you run multiple Thunderstorm containers behind a load-balancer and request the results of an async request, you may not get the result from the correct Thunderstorm instance. We recommend to use async requests in combination with remote logging only in a load-balancer setup.

docker-compose.thor11.yml

@@ -1,61 +1,52 @@
 services:
   thunderstorm:
-    image: ghcr.io/nextronsystems/thunderstorm-deployment:thor10
-    build:
-      context: .
-      dockerfile: Containerfile
-      args:
-        THOR_VERSION: "10"
+    image: ghcr.io/nextronsystems/thunderstorm-deployment:latest
     ports:
       - "${PORT:-8080}:8080"
     environment:
-      # Required: your non-host-based Thunderstorm contract token
+      # Required on initial startup: your non-host-based Thunderstorm contract token
       CONTRACT_TOKEN: "${CONTRACT_TOKEN}"
-      # Optional: TLS certificate and private key paths (mounted via secrets)
-      # TLS_CERT: "/run/secrets/tls_cert"
-      # TLS_KEY: "/run/secrets/tls_key"
+      # Optional: upgrade to THOR techpreview channel
+      # TECHPREVIEW: "true"
       # Optional: result cache size (default: 250000)
       # RESULT_CACHE_SIZE: "250000"
-      # Optional: sample persistence - "all", "malicious", or "none" (default: none)
-      # STORE_SAMPLES: "none"
-      # Optional: reserve THOR threads for synchronous requests only
-      # SYNC_ONLY_THREADS: ""
-      # Optional: only scan using YARA signatures, disables programmatic checks, STIX, Sigma and IOCs
-      # PURE_YARA: "true"
       # Optional: enforce maximum file size for all file types including registry hives and log files
       # FORCE_MAX_FILE_SIZE: "true"
-      # Optional: write text log to the logs volume (uncomment volume below)
+      # Optional: write log to the logs volume (uncomment volume below)
       # LOG_ENABLED: "true"
-      # Optional: additional Thunderstorm arguments (e.g. "--server-new-param value")
+      # Optional: TLS certificate and private key paths (mounted via secrets)
+      # TLS_CERT: "/run/secrets/tls_cert"
+      # TLS_KEY: "/run/secrets/tls_key"
+      # Optional: only scan using YARA signatures, disables programmatic checks, STIX, Sigma and IOCs
+      # PURE_YARA: "true"
+      # Optional: download YARA Forge community signatures on startup - ruleset: core, extended, full (not quality-assured by Nextron)
+      # YARA_FORGE: "full"
+      # Optional: additional Thunderstorm arguments
       # THUNDERSTORM_ARGS: ""
       # Optional: additional THOR arguments
       # THOR_ARGS: ""
+      #
+      # --- THOR 10 only ---
+      # Optional: sample persistence - "all", "malicious", or "none" (default: none)
+      # STORE_SAMPLES: "none"
+      # Optional: reserve THOR threads for synchronous requests only
+      # SYNC_ONLY_THREADS: ""
+      #
+      # --- THOR 11 only ---
+      # Optional: minimum score for storing samples (default: 200)
+      # STORE_SAMPLES_SCORE: "200"
+      # Optional: hours between signature updates (default: 24)
+      # SIGNATURE_UPDATE_INTERVAL: "24"
+      # Optional: upload queue size warning threshold (default: 50000)
+      # QUEUE_WARN_SIZE: "50000"
+      # Optional: enable VFS directory mirroring uploaded files per host (also uncomment volume below)
+      # VFS_ENABLED: "true"
     volumes:
+      # Persist Thor binaries and other artifacts across restarts
+      - thunderstorm:/opt/nextron/thunderstorm
       # Optional: mount TLS certificate and private key (uncomment TLS_CERT/TLS_KEY above as well)
       # - ./tls_cert:/run/secrets/tls_cert:ro
-      # - ./tls_key:/run/secrets/tls_key:ro
-      # Persist Thor binaries and other artifacts across restarts
-      - thor10-data:/opt/nextron/thunderstorm
-      - thor10-config:/opt/nextron/thunderstorm/config
-      - thor10-samples:/tmp/thunderstorm/uploads
-      - thor10-plugins:/opt/nextron/thunderstorm/plugins
-      - thor10-signatures:/opt/nextron/thunderstorm/signatures
-      - thor10-custom-signatures:/opt/nextron/thunderstorm/custom-signatures
-      # Optional: write text log to volume (uncomment LOG_ENABLED above as well)
-      # - thor10-logs:/tmp/thunderstorm/logs
-    deploy:
-      replicas: 1
-      update_config:
-        order: start-first
-      restart_policy:
-        condition: on-failure
+      # - ./tls_key:/run/secrets/tls_key:ro#
 
 volumes:
-  thor10-data:
-  thor10-config:
-  thor10-samples:
-  thor10-plugins:
-  thor10-signatures:
-  thor10-custom-signatures:
-  # Optional: write text log to volume
-  # thor10-logs:
+  thunderstorm: