Install Auditor

#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 with the Compose plugin (docker compose), git, curl, jq and openssl.

1. Download the install files:

   bashCopy
   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:

   bashCopy
   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 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:

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

2. Write the settings to values.yaml:

   yamlCopy
   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.

3. Install it:

   bashCopy
   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 right away, then pass it to the chart and restart the pods, so the scanners pick it up:

   bashCopy
   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:

bashCopy
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.

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

Next, see First steps.