AQtive Guard Configuration Reference↑

Key	Required?	Type	Description
`ASSETS_AUTO_BUILD`			Internal, do not modify.
`CS_ON_PREMISES`		bool	Set to `true` for on-premise setups. Do not modify.
`CS_LICENSE_SERVER`			Internal, do not modify.
`DATABASE_SCHEMA`		str	Set to use a custom database schema. Default: `"public"`
`DATABASE_URL`	yes	str	Set to a Postgres URL. See Database URL Section for a more detailed explanation.
`DISABLE_HTTPS_REDIRECT`		bool	Set to `true` to disable automatic redirection to HTTPS. This is useful if AQtive Guard is located behind a load balancer that handles SSL endpoint termination. Default: `false`
`LOG_FILE`		str	Define a file to which logs should be written. If unset, logs are written to journalctl.
`LOG_FILE_AUDIT`		str	Define a file to which audit logs should be written. If unset, audit logs are written along with the rest of the logs.
`LOG_LEVEL`		str	Set logging level of the AQtive Guard instance. Possible values: `"debug"`, `"info"`, `"warning"`, `"error"`. Default: `"info"`
`LOG_LEVEL_AUDIT`		str	Set logging level of audit logs for this instance. Possible values: `"debug"`, `"info"`, `"warning"`, `"error"`. Default: `"info"`
`LOG_ROTATE_DAILY`		bool	If set to `true` and if `LOG_FILE` is set, then log files will be rotated every 24 hours. Logs continue being written to the file referenced in `LOG_FILE`. After the 24h period, old logs get moved to `[original name].[timestamp]`. Requires `LOG_FILE` to be set.
`LOG_ROTATE_DAILY_AUDIT`		bool	If set to `true` and if `LOG_FILE_AUDIT` is set, then audit log files will be rotated every 24 hours. Logs continue being written to the file referenced in `LOG_FILE_AUDIT`. After the 24h period, old logs get moved to `[original name].[timestamp]`. Requires `LOG_FILE_AUDIT` to be set.
`LOG_ROTATE_MAX`		int, strictly greater than 0	If set, only LOG_ROTATE_MAX rotating log files will be kept. Old log files will be deleted. Requires `LOG_FILE` and `LOG_ROTATE_DAILY` to be set. If unset, log files will never be deleted.
`LOG_ROTATE_MAX_AUDIT`		int, strictly greater than 0	If set, only LOG_ROTATE_MAX_AUDIT rotating audit log files will be kept. Old log files will be deleted. Requires `LOG_FILE_AUDIT` and `LOG_ROTATE_DAILY_AUDIT` to be set. If unset, log files will never be deleted.
`REDIS_URL`	yes	str	URL to a redis instance. See Redis URL Section for a more detailed explanation.
`S3_ENDPOINT`	yes	str	HTTP Endpoint of the storage solution.
`S3_ENDPOINT_USE_EXTERNAL`		bool	Caution: This option needs to be set to `false` if AQtive Guard uses a storage solution situated on a different machine. If the `S3_ENDPOINT` is pointing to anything other than `localhost` , then set this option to `false`! Default: `true`
`S3_TRACE_AWS_ACCESS_KEY_ID`	yes	str	The Access Key ID for the storage solution account.
`S3_TRACE_AWS_SECRET_ACCESS_KEY`	yes	str	The Secret Access Key for the storage solution account.
`S3_TRACE_BUCKET`	yes	str	The name of the bucket in which AQtive Guard should store its files.
`S3_REGION`		str	Set this option only if AQtive Guard is using AWS S3.
`STORAGE_USE_PUT`		bool	Set this option if AQtive Guard should use the PUT method to upload traces to the storage solution. Note: StorageGRID only supports PUT upload.
`STORAGE_EXTENDED_HEALTH_CHECK`		bool	Set this option to enable storage health checks that do not use the HEAD method, but instead perform write, read and delete operations.
`SECRET_KEY`	yes	str	Set this value to a random, hex-encoded string of at least 64 characters long. If AQtive Guard is installed in a high-availability setting, it is critical that all instances share the same `SECRET_KEY`.
`SECRET_PROVIDER`	no	str	JSON-encoded secret manager parameters. See Secret Managers for a more detailed explanation.
`SESSION_DURATION_SECONDS`	no	int	Timeout of the login session, in seconds. Default: 86400 (24h)
`RATELIMIT_ENABLED`		bool	Toggle the rate-limiter protection. It is recommended to leave this option active. Default: `true`
`OIDC_DISCOVERY_URL`	only for OIDC	str	Discovery URL, meant for autoconfiguration of the OpenID endpoints. It generally look like `https://your.id_provider.com/.well-known/openid-configuration`.
`OIDC_SERVER_CERT`	no	str	Path to SSL CA bundle (a file or directory) used to verify OpenID Servers (e.g. "/etc/web/cert.pem"). Default: If unset or the path is invalid, defaults to the SSL certificate used by the underlying OS.
`OIDC_CLIENT_NAME`	only for OIDC	str	Name you assigned to AQtive Guard when you configured your identity server.
`OIDC_SECRET`	only for OIDC	str	Secret password associated to AQtive Guard.
`OIDC_USE_PING_FEDERATE`		bool	Set this to `true` the identity provider is PingFederate. Default: `false`
`OIDC_BUTTON_LABEL`		str	Text that will be displayed on the SSO login button. Default: `"Log in with OpenID"`
`OIDC_DEFAULT_ORG_ID`	only for OIDC	int	The ID of the default organization a user identified by the SSO will belong to.
`OIDC_RESOURCE`		str	Optional parameter that hints the role claim(s) to be included in the Access Token upon successful user authentication. Set this if required by the identity provider.
`GUNICORN_NUM_WORKERS`		int	Number of gunicorn workers. Default: `2`.
`GUNICORN_NUM_THREADS`		int	Number of gunicorn gthreads instantiated within a gunicorn worker. Default: `4`.
`GUNICORN_SSL_CERT_FILE`		str	(Not recommended) Full path to SSL certificate file in PEM file format. Setting this option will start application web server with TLS enabled, which is not required in normal operation. This parameter is mutually exclusive with `GUNICORN_SSL_KEYSTORE_FILE`, and can be set in the configuration file or passed as the environment variable.
`GUNICORN_SSL_KEYSTORE_FILE`		str	(Not recommended) Full path to KeyStore in PKCS12 file format. This will start application web server with TLS enabled, not required in normal operation. This option is mutually exclusive with `GUNICORN_SSL_KEY_FILE`, and can be set in the configuration file or passed in the environment variable.
`GUNICORN_SSL_KEY_FILE`		str	(Not recommended) Full path to SSL private key file, if not included in the `GUNICORN_SSL_CERT_FILE` or `GUNICORN_SSL_KEYSTORE_FILE` files. Not required in normal operation. This parameter can be set in the configuration file or environment variable.
`GUNICORN_SSL_KEY_PASSWORD`		str	Optional password for decrypting SSL private key. This parameter is used for decrypting private key supplied in `GUNICORN_SSL_CERT_FILE`, `GUNICORN_SSL_KEYSTORE_FILE` or `GUNICORN_SSL_KEY_FILE`. This parameter can be set in the configuration file or environment variable.
`GUNICORN_SSL_CA_CERTS_FILE`		str	(Not recommended) Full path to SSL CA certificate file for client certificate validation. It is only used when the application web server is running with TLS enabled. Not required in normal operation. This parameter can be set in the configuration file or environment variable.
`ENABLE_GQL_OPERATION_LOGGING`		bool	Whether to log the failed operation when a GraphQL operation fails. To avoid leaking any privileged information, the operation will have all constant values removed. Default: `true`.
`ENABLE_EXCEPTION_TRACE_LOGGING`		bool	Whether to log the stack trace of any exception associated with a log message. Default: `true`.

Database URL↑

The database URL follows URL formatting. A basic form without authentication might be "postgresql://<host>/<database>".

To set a username and password, use basic auth:

"postgresql://<user>:<password>@<host>/<database>"

The username and password must be URL-encoded.

A custom port can be passed in the <host> value:

"postgresql://<hostname>:5431/<database>"`

To enforce SSL verification, use the sslmode=required option, following the URL arguments syntax:

"postgresql://<host>/<database>?sslmode=require"

Available options are:

disable: Disable SSL
allow: Allow SSL, but favor cleartext connections.
prefer: Favor SSL, but allow cleartext connections.
require: Require SSL, but do not verify certificates .
verify-ca: Require SSL, validate certificates against the local trust OS store.
verify-full: Require SSL, validate certificate against the provided root CA.

For more extensive option documentation, refer to the official JDBC postgres documentation.

Redis URL↑

The Redis URL follows URL formatting. A basic URL without authentication might be "redis://<host>".

A username and password can be provided using the basic auth syntax:

"redis://<username>:<password>@<host>"

The username and password must be URL-encoded. Even if the username is empty, the colon in front of the password must be kept.

A custom port can be passed in the <host> value:

"redis://<hostname>:1234/"

SSL can be enabled by using the rediss protocol:

"rediss://<host>/"

AQtive Guard does not allow for custom certificates for the Redis connection; the OS trust store will be used for CA verification.

Configuration in a high-availability setting↑

It is strongly recommended to use the identical configuration file for all AQtive Guard machines in a high-availability setting.

Secret Manager configuration↑

AQtive Guard can fetch secret values from a secret manager instead of storing them in the configuration file.

To enable a secret manager, set the SECRET_PROVIDER configuration key to a JSON-encoded object, with 3 keys:

provider: the name of the provider (such as "aws").

config: an object containing all the specific keys required by the secret provider.

labels: an object with all the configuration keys that should contain a secret value. Each key is mapped to either:
- a label (string) of the secret stored inside the secret provider, OR
- an object {label: str | object, encoding: str, auth_type: str} where label is either a) the name of the secret stored inside the secret provider, or b) an object containing information necessary to generate an RDS auth token using the current IAM role; encoding specifies the secret encoding type (“RAW”, “URL”, “JSON”, or “UNICODE”); and auth_type is one of (“CREDENTIALS”, “IAM”). Note that the values for encoding and auth_type are not case-sensitive).
  - If no encoding is provided, RAW is used and no transformations are done to the secret.
  - If no auth_type is provided, CREDENTIALS is used by default. It can be safely ommitted except when specifying IAM (see below)
  - If auth_type is set to IAM, AQtive Guard will attempt to generate an auth token to use as a password instead of connecting to the secret provider directly
    - This functionality is currently only supported for use with the DATABASE_URL key, and only when using AWS as a secret provider.
    - When using IAM, label must be an object containing the top-level keys "username", "port", and "hostname". These values will be used to generate the IAM authentication token to be passed to postgres.
  - If encoding is set to URL or UNICODE, the string will be decoded in the corresponding format after being fetched from the secret provider.
    - JSON encoding is designed to support Amazon RDS credentials managed by AWS Secrets Manager but may work for other use cases. It assumes the secret will be a JSON string with two top-level keys, “username” and “password”.
    - If JSON is specified and the JSON string cannot be decoded, or if these top-level keys are missing from the decoded JSON object, a ConfigError error is raised.
    - If an invalid encoding is specified, an UnsupportedConfigValue error is raised.
      
      Caution
      
      Rotating a managed database secret while AQtive Guard is running may result in brief service interruptions to the user. AQtive Guard will detect password authentication failures to the database, and attempt to retrieve a new secret from the configured secret manager for subsequent database connections.

AWS Secrets Manager: a real-life example↑

Use the following to configure AQtive Guard to use AWS Secrets Manager to fetch the database password (unicode-encoded), redis password (raw string), and SECRET_KEY (raw string, default):

JSON

{
    "provider": "aws",
    "labels": {
        "DATABASE_URL": {"label": "sandboxaq/database", "encoding": "unicode"},
        "REDIS_URL": {"label": "sandboxaq/redis", "encoding": "raw"},
        "SECRET_KEY": "sandboxaq/secret-key",
    },
    "config": {
        "region_name": "us-east-1",
    }
}

Note

Both "KEY": {"label": "some-label", "encoding": "raw"} and "KEY": "some-label" are equivalent and treat the secretId as a raw string.

The following keys can be specified in labels:

DATABASE_URL
REDIS_URL
SECRET_KEY
S3_TRACE_AWS_SECRET_ACCESS_KEY

Refer to AWS Secrets Manager integration for more information.

Secrets in URLs↑

For passwords used in URLs, the secret is fetched from the secret provider and then merged into the URL specified in the configuration file. It is expected that the URL does not contain a password. Otherwise, the application will not start.

This covers:

DATABASE_URL
REDIS_URL

The following keys configure a redis instance at redis-host.com with the username user and the password p@sswordstored at label redis-password in the AWS Secrets Manager:

REDIS_URL=redis://user:@redis-host.com/
SECRET_PROVIDER={"provider":"aws","labels":{"REDIS_URL":"redis-password"}}

If the password is url-encoded, use the following label instead:

REDIS_URL=redis://user:@redis-host.com/
SECRET_PROVIDER={"provider":"aws","labels":{"REDIS_URL": {"label": "redis-password", "encoding": "url"}}}

Secret values↑

For secret values, the secret is simply fetched for the secret provider. It is expected that no value is set for the configuration key in the configuration file. Otherwise, the application will not start.

This covers:

SECRET_KEY
S3_TRACE_AWS_SECRET_ACCESS_KEY

E.g. if the SECRET_KEY is stored in the AWS Secrets Manager at the label cap-secret-key, use the following configuration key:

SECRET_KEY=
SECRET_PROVIDER={"provider":"aws","labels":{"SECRET_KEY":"cap-secret-key"}}

AWS Secrets Manager integration↑

To integrate the AWS Secrets Manager, use the "aws" provider. Secrets can be plaintext passwords or RDS credentials. The AWS Secrets Manager client will use IAM authentication when fetching secrets.

The following specific configuration keys are required:

"region_name": the region name of the AWS Secrets Manager instance, such as "us-east-1".

Refer to Secret Manager configuration for configuration details.

Example↑

The following configures a user username and password Passw0rd on host database.company.com:

SECRET_KEY=
DATABASE_URL="postgresql://username:@database.company.com/sandboxaq"
SECRET_PROVIDER='{"provider":"aws", "config":{"region_name": "us-east-1"}, "labels":{"DATABASE_URL": {"label": "sandboxaq/database", "SECRET_KEY": "sandboxaq/secretkey"}}}'

Inside the AWS Secrets Manager, add plaintext secrets:

label: "sandboxaq/database"
value: "Passw0rd"

label: "sandboxaq/secretkey"
value: "Th1sIsASecret"

When configuring DATABASE_URL to use Amazon RDS credentials, it is necessary to specify JSON encoding in SECRET_PROVIDER (see Secret Manager configuration). In this case, it is also unnecessary to specify the username in DATABASE_URL since it is included in the RDS credentials managed by AWS:

DATABASE_URL="postgresql://:@database.company.com/sandboxaq"
SECRET_PROVIDER='{"provider":"aws", "config":{"region_name": "us-east-1"}, "labels":{"DATABASE_URL": {"label": "rds!db-ffffffff-ffff-ffff-ffff-ffffffffffff", "encoding": "JSON"}}'

To connect to an RDS instance using an IAM auth token instead of username and password, supply the "auth_type" key with a value of "IAM" in the DATABASE_URL object. IAM authentication also requires the value of "label" in the same object to be an object containing the username, hostname, and port for the target RDS instance. Note that if using a proxy, this information must match the identity of the RDS instance itself, and might differ from the values in the DATABASE_URL environment variable. In this case a database user (postgres, below) must also still be specified in the value of the DATABASE_URL environment variable:

DATABASE_URL="postgresql://postgres:@database.company.com/sandboxaq"
SECRET_PROVIDER='{"provider":"aws", "config":{"region_name": "us-east-1"}, "labels":{"DATABASE_URL": {"label": {"username": "postgres", "hostname": "database.company.com", "port": 5432 }, "encoding": "RAW", "auth_type": "IAM"}}'

Tanium Configuration↑

We expose the following settings for the Tanium integration. All the settings are optional and have a default value.

Key	Default value	Type	Description
`TANIUM_REQUEST_TIMEOUT`	`30`	integer	Maximum duration in seconds of a single `HTTP` request made to the Tanium API. This doesn’t include download calls.
`TANIUM_DOWNLOAD_REQUEST_TIMEOUT`	`90`	integer	Maximum duration in seconds of the download `HTTP` request made to the Tanium API.
`TANIUM_MIN_REQUEST_TIMEOUT`	`30`	integer	Minimum allowed configurable request timeout value used for the Tanium settings configuration.
`TANIUM_MAX_REQUEST_TIMEOUT`	`300`	integer	Maximum allowed configurable request timeout value used for the Tanium settings configuration.
`TANIUM_MAX_CONNECTION_TO_HOST_ATTEMPTS`	`3`	integer	The number of attempts made to establish a direct connection to each host during retrieval before declaring the retrieval as failed.
`TANIUM_MAX_WAIT_ON_HOST_CONNECTION_ATTEMPTS`	`3`	integer	The number of checks made for the Direct Connection status of each host. We declare the retrieval as failed if it’s still not connected after this many checks.
`TANIUM_WAIT_ON_HOST_CONNECTION_ATTEMPT_DELAY`	`1`	integer	The delay in seconds between each iteration of the Direct Connection status check.
`TANIUM_TRACE_LINUX_PATH`	`"/opt/cryptosense/out/trace.cst.gz"`	string	Full path location where we expect the trace file to be located on a Linux host machine.
`TANIUM_TRACE_LINUX_DIRECTORY`	`"/opt/cryptosense/out"`	string	Directory where we expect the trace file to be located on a Linux host machine. This should match the relevant portion of the `TANIUM_TRACE_LINUX_PATH` value.
`TANIUM_TRACE_LINUX_FILE_NAME`	`"trace.cst.gz"`	string	Trace file name we expect on a Linux host machine. This should match the relevant portion of the `TANIUM_TRACE_LINUX_PATH` value.
`TANIUM_TRACE_WINDOWS_PATH`	`"C:\Program Files (x86)\cryptosense\out\trace.cst.gz"`	string	Full path location where we expect the trace file to be located on a Windows host machine.
`TANIUM_TRACE_WINDOWS_DIRECTORY`	`"C:\Program Files (x86)\cryptosense\out"`	string	Directory where we expect the trace file to be located on a Windows host machine. This should match the relevant portion of the `TANIUM_TRACE_WINDOWS_PATH` value.
`TANIUM_TRACE_WINDOWS_FILE_NAME`	`"trace.cst.gz"`	string	Trace file name we expect on a Windows host machine. This should match the relevant portion of the `TANIUM_TRACE_WINDOWS_PATH` value.
`TANIUM_MAX_UPLOAD_TRACE_FROM_HOST_ATTEMPTS`	`3`	integer	The number of attempts to create a Tanium upload from the host to the Saved Evidence task during retrieval before declaring the retrieval as failed.
`TANIUM_UPLOAD_TRACE_FROM_HOST_ATTEMPT_DELAY`	`1`	integer	The delay in seconds between each attempt to create an upload from the host to the Saved Evidence task.
`TANIUM_MAX_WAIT_FOR_HOST_FILE_UPLOAD_ATTEMPTS`	`10`	integer	The number of status checks made during retrieval after creating an upload from the host to the Saved Evidence task before declaring the retrieval as failed.
`TANIUM_WAIT_FOR_HOST_FILE_UPLOAD_ATTEMPT_DELAY`	`3`	integer	The delay in seconds between each status check of created upload from the host to the Saved Evidence task.
`TANIUM_MAX_REMOVE_SAVED_EVIDENCE_ATTEMPTS`	`3`	integer	The number of times we’ll attempt to run a Saved Evidence cleanup after ingestion.
`TANIUM_REMOVE_SAVED_EVIDENCE_ATTEMPT_DELAY`	`1`	integer	The delay in seconds between each cleanup attempt.