SaaS Shield Tenant Security Logdriver

The Tenant Security Logdriver is a service that is delivered as a Docker container. You run that container within your SaaS infrastructure. The Logdriver acts as a gateway between your application and your customers’ cloud logging infrastructure. This service supports SaaS Shield’s Real Time Security Events, which creates rich audit trails containing detailed security events from your Tenant Security Proxy, such as requests to wrap or unwrap keys, and pushes them to your tenants’ logging / SIEM systems. Logdriver can communicate with cloud logging instances running in GCP and Splunk (see full list of supported logging services here). If a tenant has not provided a logging configuration, Logdriver will send their events to stdout instead.

Tenant admins control their logging configuration using the Configuration Broker.

The Logdriver service requires persistent storage; when events are pushed to the Logdriver, they are stored to disk before they are bundled and delivered so that events can be recovered if the service is prematurely shut down. On the next startup of the service, it will attempt to deliver all of the stored events.

Installation

The Logdriver Docker container is hosted publicly on the IronCore Labs Docker registry. Find the latest tag available and pull down the image by running this command:

bash

docker pull us-docker.pkg.dev/ironcore-images/gcr.io/tenant-security-logdriver:{tag}

You can see the changes in each version of the Logdriver in its changelog.

After you have successfully pulled the Logdriver, you should be able to see the image listed in your docker images list.

Startup

In order to successfully start the Docker container, you need to provide it with a configuration generated from the Configuration Broker and a volume to persist logging events. Once you have this configuration, you can run

bash

docker run \
  --env-file config-broker-config.conf \
  -e LOGDRIVER_HTTP_BIND_ADDRESS=0.0.0.0:5555 \
  -p 5555:5555 \
  -m 1256Mi \
  --cpus=2
  --mount 'type=volume,src=<VOLUME-PATH>,dst=/logdriver' \
  us-docker.pkg.dev/ironcore-images/gcr.io/tenant-security-logdriver:{tag}

If the image starts successfully, then the Logdriver service is running locally.

LOGDRIVER_HTTP_BIND_ADDRESS is the one variable the Logdriver will not start without, since it is the address security events arrive on. It has no default; 5555 above is just the port the rest of our examples use. This runs the listener in plaintext with no token, which is fine locally and not otherwise. See required configuration for the TLS certificate and shared token a real deployment needs.

The volume that you provide is used to store security events so they can be recovered in the event of a restart of the container. The events are removed from the store as they are delivered to tenant logging systems, so it is used as an elastic buffer. It will not grow without bound, and the consequence of using zone-local storage is minimal. We recommend providing a 50GB volume, which should be more than sufficient to handle busy logging streams.

The -m argument to Docker sets the amount of memory available to the container. We recommend allocating 1256Mi for the container - the logging service uses the disk as a backup, but for performance, the events are normally processed using in-memory queues with a cap on the number of events. 1256Mi allows for a substantial rate of event logging and will be enough for fully loaded event queues.

The --cpus argument sets the number of CPUs available to the container. We recommend at least two CPUs to allow Logdriver to continue to service log events while still performing CPU intensive tasks like decrypting logging configurations.

When the Logdriver service starts, it immediately attempts to make a request to the Configuration Broker to retrieve and decrypt all of the logging configurations that were created by each of your tenants. The decrypted configurations are kept in memory only.

Every 10 minutes, the container re-fetches the list of encrypted tenant configurations from the Configuration Broker. This allows the Logdriver to get updates on any new or changed logging configurations for your tenants.

Once the container has successfully started, it listens for security events on LOGDRIVER_HTTP_BIND_ADDRESS and delivers them to your customers’ logging and SIEM services. Each Tenant Security Proxy connects out to that address and POSTs batches of events to it, so one address can front a pool of Logdrivers and the two services are sized independently rather than paired 1-to-1. See event ingest for the listener’s configuration, sizing the pool for how many Logdrivers a TSP fleet needs, and the example docker compose for the smallest working pair.

Starting Locally for Development

If you want to run the Logdriver in Docker on your local machine, the command is slightly different

bash

docker run --env-file <CONFIG-FILE> -m 1256Mi \
  -e LOGDRIVER_HTTP_BIND_ADDRESS=0.0.0.0:5555 \
  -p 5555:5555 \
  --mount 'type=bind,src=<VOLUME-PATH>,dst=/logdriver' \
  us-docker.pkg.dev/ironcore-images/gcr.io/tenant-security-logdriver:{tag}

Note that VOLUME-PATH must be an absolute path of an existing directory.

Deployment and Tuning

Running Logdriver and TSP in a production deployment is usually more involved than just starting it up. See the deployment documentation for Kubernetes and docker compose examples, health check information, configuration, performance tuning, and troubleshooting information.