Skip to content

AQtive Guard Configuration Reference↑

Key Required? Type Description
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 must be set to true if AQtive Guard uses a storage location under the same hostname as itself. If the S3_ENDPOINT points to anything other than localhost , set this option to false!

Default: false
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.
RQ_JOB_TIMEOUT int Maximum execution time (in seconds) of any analysis background job.

Default: 2.
TRACE_TIMEOUT int Maximum execution time (in seconds) allowed for the complete lifecycle of a trace (from its generation to the end of pre-analysis). If this limit is exceeded, the trace is marked as failed.

Default: 14400.
REPORT_TIMEOUT int Maximum execution time (in seconds) allowed for the complete lifecycle of a report (from its generation to the end of analysis). If this limit is exceeded, the report is marked as failed.

Default: 14400.
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”); auth_type is one of (“CREDENTIALS”, “IAM”); and mapping describes a JSONPath mapping of the expected data structure. 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.

        • The keys read when using a JSON configuration can be mapped by using the additional parameter mapping on the same level of JSON structure as encoding and label. This mapping is a JSON object with optional keys username and password and values set to JSONPath coordinates of username and password in the JSON structure expected in the Secret.
        • JSON encoding is designed to support Amazon RDS and ElastiCache credentials managed by AWS Secrets Manager without using mapping, but may work for other use cases. It assumes the secret will be a JSON string with top-level optional keys username and password.
        • 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
  • S3_REPORT_EXPORT_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
  • S3_REPORT_EXPORT_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’s necessary to specify JSON encoding in SECRET_PROVIDER. Refer to Secret Manager configuration for details.

In this case, it’s also unnecessary to specify the username in DATABASE_URL since it’s 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"}}'

The mapping configuration value can be used as well:

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", "mapping": {"username": "$.username", "password": "$.authToken"}}}'

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.

Keep in mind that if you’re 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.

S3 Report Export↑

To export generated File System scan reports as JSON files during analysis, you can use the following configuration. All Required parameters must be configured to enable this feature.

Key Required Type Description
S3_REPORT_EXPORT yes bool Set to true to enable S3 JSON Report Upload feature (File System scans only).

Default: false
S3_REPORT_EXPORT_BUCKET yes str The name of the bucket where AQtive Guard will store its report files.
Warning: The value must be the bucket name only (no directories). For directory specification, use S3_REPORT_EXPORT_PREFIX.
S3_REPORT_EXPORT_PREFIX str Specifies the path where reports will be exported in the bucket. The value can be a path or an empty string.

Default: "AQG"
S3_REPORT_EXPORT_DISABLE_DB bool Set to true to disable uploading crypto data to the database when S3 JSON Report Upload is enabled (File system scans only).
Warning: Generated reports will be empty in the AQtive Guard database and interface. As a result, cryptographic objects (keys/certificates) in the exported report files won’t have global IDs.

Default: false

Note: The path of exported reports is in the format {prefix}/{year}/{month}/{day}/{report name}_{datetime}.json (with datetime as ISO 8601: {year}-{month}-{day}T{hour}:{minute}:{seconds}).

  • Example without setting a prefix:
    "AQG/2025/01/17/Report for trace_3.cst.gz_2025-01-17T15:13:03.json”
  • Example with S3_REPORT_EXPORT_PREFIX=reports/app:
    "reports/app/2025/01/17/Report for trace_3.cst.gz_2025-01-17T15:13:03.json"

Separate storage configuration↑

For greater flexibility, the Report storage solution can be configured independently of the existing Trace storage solution. All related configuration keys are optional and default to S3_TRACE_... if not explicitly set.

Key Type Description
S3_REPORT_EXPORT_AWS_ACCESS_KEY_ID str The Access Key ID for the Report storage solution account.

If not set, defaults to S3_TRACE_AWS_ACCESS_KEY_ID.
S3_REPORT_EXPORT_AWS_SECRET_ACCESS_KEY str The Secret Access Key for the Report storage solution account.

If not set, defaults to S3_TRACE_AWS_SECRET_ACCESS_KEY.
S3_REPORT_EXPORT_ENDPOINT str HTTP Endpoint of the report storage solution.

If not set, defaults to S3_ENDPOINT.
S3_REPORT_EXPORT_REGION str Set this option only if AQtive Guard is using AWS S3.

If not set, defaults to S3_REGION.
S3_REPORT_EXPORT_ENDPOINT_USE_EXTERNAL bool This option must be set to true if AQtive Guard uses a storage location under the same hostname as itself. If the S3_REPORT_EXPORT_ENDPOINT points to anything other than localhost, set this option to false.

If either this key or S3_REPORT_EXPORT_ENDPOINT is not set, it defaults to S3_ENDPOINT_USE_EXTERNAL.