---
title: "Install Auditor"
description: "Install Auditor with Docker Compose or Helm, create its access token and connect it to AppSec Portal."
url: https://whitespots.io/docs/appsec-portal/get-started/install-the-auditor
slug: appsec-portal/get-started/install-the-auditor
publish_date: 2026-10-30T19:42:15.000Z
last_modified: 2026-10-30T19:42:15.000Z
---

# Install Auditor

Auditor runs the scanners for Portal. It clones your repositories,
pulls your images, runs each scan job in its own container and sends the results back. Install it
next to Portal, then connect the two.

Auditor is free. Running audits from Portal needs a license that
includes Auditor: an Auditor license or a paid one.
See [License](https://whitespots.io/docs/appsec-portal/administration/license).

## Before you start

- **A server of its own.** Auditor runs several scanners at once, and each scanner is a
  container that needs CPU and memory. Don't share the server with Portal. The
  more cores and memory it has, the more scans run in parallel; add more when audits queue up.
- **x86-64.** The images are built for x86-64 only. ARM servers and Apple Silicon Macs aren't
  supported.
- **Privileged containers.** Scanners run in Docker inside Docker, which needs privileged mode.
- **Network access** in both directions:
  - Portal reaches Auditor on its web address;
  - Auditor reaches Portal, your version control, your container
    registries, and the registries it pulls scanner images from.

## Docker Compose

You need [Docker](https://docs.docker.com/engine/install/) with the Compose plugin
(`docker compose`), `git`, `curl`, `jq` and `openssl`.

1. Download the install files:

   ```bash verify
   git clone https://gitlab.com/whitespots-public/auditor.git auditor
   cd auditor
   ```

2. To use your own PostgreSQL server, write its settings to `.env` first: `DB_HOST`, `DB_PORT`,
   `DB_NAME`, `DB_USER` and `DB_PASS`. To use your own Redis, add `AMQP_HOST_STRING`, for example
   `redis://:<password>@redis.example.com:6379/0`. Otherwise skip this step.

3. Run the installer:

   ```bash verify
   sh install.sh
   ```

   The installer takes the latest release, generates the passwords and the encryption key, and
   starts Auditor. Then it creates the [access token](#create-the-access-token) and
   restarts Auditor with it. Everything is saved to `.env`.

   Keep a copy of `.env`. The `ACCESS_TOKEN` in it connects Portal, and
   `DOCKER_ENCRYPTION_TOKEN` encrypts the registry passwords that Auditor saves: with a
   different key, the saved passwords can't be read, and you have to enter them again.

The web interface listens on port 8080 over plain HTTP. To serve it over HTTPS, put a reverse
proxy with your certificate in front of it.

To update, run `git pull` and `sh install.sh` again. It keeps the settings in `.env` and moves
Auditor to the latest release.

## Helm

You need Helm 3, a Kubernetes cluster and an ingress controller.

1. Add the chart repository:

   ```bash verify
   helm repo add auditor https://gitlab.com/api/v4/projects/51993931/packages/helm/stable
   helm repo update
   ```

2. Write the settings to `values.yaml`:

   ```yaml
   ingress:
     ingressClassName: nginx
     host: auditor.example.com
   postgresql:
     auth:
       password: <password>
   ```

   The chart runs PostgreSQL and Redis in the cluster, and PostgreSQL keeps its data on a volume.
   To use your own servers, set `postgresql.enabled: false` and fill in `externalPostgresql`, or
   `redis-ha.enabled: false` and `externalRedis`, the same way as for
   [Portal](https://whitespots.io/docs/appsec-portal/get-started/install#helm).

3. Install it:

   ```bash verify
   helm upgrade --install auditor auditor/appsecauditor \
     -n auditor --create-namespace -f values.yaml
   ```

   The chart generates the key that encrypts the registry passwords Auditor saves, and
   keeps it in its Secret. Every upgrade keeps it. If you delete the release or the namespace, the
   key is gone, and the saved passwords have to be entered again.

4. [Create the access token](#create-the-access-token) right away, then pass it to the chart and
   restart the pods, so the scanners pick it up:

   ```bash
   helm upgrade auditor auditor/appsecauditor -n auditor -f values.yaml \
     --set configs.secret.access_token=<token>
   kubectl rollout restart deployment -n auditor
   ```

To update, run `helm repo update` and `helm upgrade auditor auditor/appsecauditor -n auditor -f
values.yaml`. The upgrade keeps the access token and the key.

If you deploy with Argo CD or `helm template`, the chart can't read its Secret in the cluster: set
`configs.secret.docker_encryption_token` (`openssl rand -hex 16`) and `configs.secret.access_token`
in your values, and keep them there.

## Create the access token

With Docker Compose, the installer creates the token and saves it to `.env` as `ACCESS_TOKEN`.

With Helm, open the Auditor address in a browser. The first time, Auditor asks you to
create an access token. It does this only once, and anyone who opens it first can do it, so
create the token as soon as Auditor is up.

Save the token in your password manager. It's the only way to log in to Auditor, and
Portal uses it to connect. The scanners need it too: with Helm, add it to the
configuration as described in the steps above.

### If you lose the token

Auditor keeps only a hash of the token, so it can't be shown again. Delete it from the
database and restart Auditor:

```bash
docker compose exec postgres psql -U postgres appsec_db -c 'TRUNCATE accesstoken RESTART IDENTITY'
sh stop.sh && sh run.sh
```

Then create a new token, and replace the old one in `.env` or `auditor-secrets.yaml` and in the
**Auditor** settings of Portal.

## Connect it to Portal

1. In Portal, open the settings, then **Auditor**.
2. Enter the **Auditor URL**, for example `https://auditor.location/`, and the
   **Access Token**. Turn off **Verify SSL** only if Auditor uses a self-signed
   certificate. That's all the connection needs: **Connection status** under these fields shows
   whether Auditor is reachable and the token is accepted.
3. Check the **Internal Portal URL** shown under it. Auditor sends
   the results to this address, so it must be reachable from the Auditor server. Change
   it in **Workflow Settings** if it isn't.
4. To scan private repositories, add under **Configure pipeline environments** the
   **Private SSH key** that Auditor clones them with. Give it read access to every
   repository you want scanned.
5. If your scanner images or your own images are in a private registry, fill in the **Docker
   registry** credentials, or connect the registry as a
   [container registry](https://whitespots.io/docs/appsec-portal/integrations/container-registries).

**Get started** on the dashboard also shows whether Auditor is
healthy, next to the other setup steps.

Next, see [First steps](https://whitespots.io/docs/appsec-portal/get-started/first-steps).

---

## Navigation

- Location: [Docs](https://whitespots.io/docs) > [Application Security Portal](https://whitespots.io/docs/appsec-portal) > [Get started](https://whitespots.io/docs/appsec-portal/get-started)
- Previous: [Install](https://whitespots.io/docs/appsec-portal/get-started/install)
- Next: [First steps](https://whitespots.io/docs/appsec-portal/get-started/first-steps)