|
2 | 2 |
|
3 | 3 | 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. |
4 | 4 |
|
5 | | -## Containerize Thunderstorm |
| 5 | +## Quick Start |
6 | 6 |
|
7 | | -Thunderstorm is a web service which allows you to scan files with our compromise assessment tool THOR through a Web-API. By sane defaults, the web service listens to `127.0.0.1` on port `8000` only. However, if we want the Thunderstorm API to be accessible from anywhere, we need to adjust the binding address via command line parameter `--host`. |
| 7 | +Thunderstorm is a web service which allows you to scan files with our compromise assessment tool THOR through a Web-API. A ready-to-use base image is published to the GitHub Container Registry and only requires your contract token to run. |
8 | 8 |
|
9 | | -We created an `entrypoint.sh` which accepts optional environment variables from a Containerfile and deployment configuration. First, the shell script updates the THOR signatures to download all detection rules published after the image was created. Subsequently, the Thunderstorm executable is started which will run infinitely until the container is stopped. |
10 | | - |
11 | | -### Build Container Image |
12 | | - |
13 | | -The Thunderstorm binary is not publicly available and requires a non-host-based license from our portal. Therefore, we cannot provide a ready-to-use image. However, you can use the following Containerfile in combination with your contract token to build your personal Thunderstorm image. |
14 | | - |
15 | | -1. Clone the repository |
| 9 | +1. Download the `docker-compose.yml` from this repository |
16 | 10 |
|
17 | 11 | ``` |
18 | | -git clone https://github.com/NextronSystems/thunderstorm-deployment.git |
| 12 | +curl -O https://raw.githubusercontent.com/NextronSystems/thunderstorm-deployment/master/docker-compose.yml |
19 | 13 | ``` |
20 | 14 |
|
21 | | -2. Change to repository directory |
| 15 | +2. Start the service with your contract token |
22 | 16 |
|
23 | 17 | ``` |
24 | | -cd thunderstorm-deployment/ |
| 18 | +CONTRACT_TOKEN=<CONTRACT_TOKEN> docker compose up -d |
25 | 19 | ``` |
26 | 20 |
|
27 | | -3. Build image where `<TAG>` could be the Thunderstorm version and `<CONTRACT_TOKEN>` is the contract token of your non-host-based Thunderstorm license. |
| 21 | +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 and periodically while running. |
28 | 22 |
|
29 | | -``` |
30 | | -docker build -f Containerfile -t thunderstorm:<TAG> --build-arg CONTRACT_TOKEN=<CONTRACT_TOKEN> . |
31 | | -``` |
32 | | - |
33 | | -4. Push image to your container registry |
34 | | - |
35 | | -``` |
36 | | -docker tag thunderstorm:<TAG> registry.internal/thunderstorm/thunderstorm:<TAG> |
37 | | -docker push registry.internal/thunderstorm/thunderstorm:<TAG> |
38 | | -``` |
| 23 | +The `docker-compose.yml` contains commented environment variables for all available configuration options such as TLS, port, queue size, and signature update interval. |
39 | 24 |
|
40 | 25 | ## Signature Updates |
41 | 26 |
|
42 | | -By default, Thunderstorm tries to download new THOR signatures every 24 hours while running. You should keep in mind that the THOR signature release cycle may differ, so there is not always a new package available. The signature update interval can be modified on an hourly basis by specifying the environment variable `SIGNATURE_UPDATE_INTERVAL` in the `Containerfile` or `docker-compose.yml`. |
| 27 | +By default, Thunderstorm tries to download new THOR signatures every 24 hours while running. You should keep in mind that the THOR signature release cycle may differ, so there is not always a new package available. The signature update interval can be modified on an hourly basis by specifying the environment variable `SIGNATURE_UPDATE_INTERVAL` in the `docker-compose.yml`. |
43 | 28 |
|
44 | 29 | ### Rolling Deployment |
45 | 30 |
|
46 | 31 | 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. |
47 | 32 |
|
48 | | -For Docker we recommend `start-first` as value for `deploy.update_config.order`. A docker-compose template can be found under `ochestration/docker/docker-compose.yml`. |
| 33 | +For Docker we recommend `start-first` as value for `deploy.update_config.order`, as configured in the `docker-compose.yml` at the repository root. |
49 | 34 |
|
50 | 35 | ### Multiple Replicas |
51 | 36 |
|
52 | 37 | 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). |
53 | 38 |
|
54 | | -We created a docker-compose template for a Docker Swarm setup with Traefik under `ochestration/docker-swarm/docker-compose.yml`. |
| 39 | +## Passing Additional Arguments |
55 | 40 |
|
56 | | -## Remote Logging |
| 41 | +Any argument supported by Thunderstorm or THOR can be passed via the `THUNDERSTORM_ARGS` and `THOR_ARGS` environment variables in `docker-compose.yml`. This means new parameters released in future versions are available immediately without any changes to the image or entrypoint. |
57 | 42 |
|
58 | | -Thunderstorm is able to pass custom parameters to the THOR executable. By default, the respective Container Image disables the generation of JSON reports with `--no-json` because the reports will be deleted after the container stops (unless a persistence volume is used). However, you usually want to log the scan results to a remote SIEM system such as [Splunk](https://www.splunk.com) or [Elastic](https://www.elastic.co). Therefore, you may want to specify your remote logging systems inside the `custom-thor.yml` template file. |
| 43 | +For example, to forward scan results to a remote SIEM: |
59 | 44 |
|
60 | 45 | ```yaml |
61 | | -# Send scan output to a remote server |
62 | | -remote-log: |
63 | | - - splunk.intern:514:DEFAULT:TCP |
64 | | - - elastic.intern:1514:JSON:TCP |
| 46 | +environment: |
| 47 | + THOR_ARGS: "--remote-log splunk.intern:514:DEFAULT:TCP --remote-log elastic.intern:1514:JSON:TCP" |
65 | 48 | ``` |
66 | 49 |
|
67 | 50 | ## Security |
68 | 51 |
|
69 | 52 | 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`. |
70 | 53 |
|
71 | | -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). |
| 54 | +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). |
0 commit comments