Skip to main content

Client Configuration

IAM Zero client libraries are configured with three mechanisms:

  1. Initialisation variables passed to the iamzero object in your programming language
  2. Environment variables
  3. The IAM Zero config file (~/.iamzero.ini)

Initialisation variables take precedence over environment variables, and environment variables take precedence over the IAM Zero config file. For example, if you had set debug = false in your IAM Zero config file, but then set IAMZERO_DEBUG=true as an environment variable, the environment variable would take precedence and the debug configuration variable would be True.

Event Transport Configuration#

The mechanism that IAM Zero uses to send events from the client to the collector can be customised. This may be useful if you have existing event aggregation or logging infrastructure you'd like to re-use in your cloud environment. The transport mode can be customised through the transport configuration variable as shown in the configuration table below.

HTTP Transport#

HTTP transport is the default transport mode. In this mode, a HTTP POST request is sent to the /api/v1/events endpoint, containing a batch of events captured by IAM Zero. The IAM Zero token is included as the x-iamzero-token HTTP header in this request.

HTTP Transport is supported in the following client libraries:

  • Python

SQS Transport#

SQS transport uses an AWS SQS queue to dispatch events to the server. To configure SQS transport, set the transport configuration variable to "sqs". The queue URL must be specified as transport_sqs_queue_url.

In the Python client, you can additionally specify a custom AWS session using the transport_custom_aws_session variable. Note that this must be passed in the call to iamzero.init() rather than through an environment variable. Using a custom session you can configure a separate profile to use for transporting events, compared to the profile that your application is executing as.

In the SQS transport the client version and the IAM Zero token are included as SQS message attributes.

SQS Transport is supported in the following client libraries:

  • Python

Available configuration variables#

The following configuration variables exist for IAM Zero:

VariableEnvironment VariableDescriptionDefault Value
urlIAMZERO_URLThe URL of the IAM Zero server to dispatch alerts tohttp://localhost:9090
debugIAMZERO_DEBUGWhether to print additional debug logging messagesFalse
tokenIAMZERO_TOKENThe authentication token for the IAM Zero server-
max_batch_sizeIAMZERO_MAX_BATCH_SIZEThe maximum number of alerts to send in a single batch to the IAM Zero server100
send_frequencyIAMZERO_SEND_FREQUENCYThe frequency in seconds at which to dispatch batches of alerts to the IAM Zero server0.25
user_agent_additionIAMZERO_USER_AGENT_ADDITIONAn additional string to be added to the User Agent header in dispatches to the IAM Zero server-
transportIAMZERO_TRANSPORTThe transport mechanism to use (one of "http", "sqs")http
transport_custom_aws_session-A custom boto3 session to use when dispatching messages if the SQS transport is used-
transport_sqs_queue_urlIAMZERO_TRANSPORT_SQS_QUEUE_URLThe queue URL of the SQS queue to dispatch events to-

Initialisation variables#

When initialisating the IAM Zero client in your application you can inject any of the above variables to the client. This is well suited if you have any custom logic around configuring the IAM Zero client. An example configuration is shown below.

import iamzero
iamzero.init(debug=True, url="http://localhost:9091", token="123456")

Initialisation variables passed to the iamzero initialisation method at runtime will always take precedence over other configuration methods.

Environment variables#

Additionally, you can configure the IAM Zero client through environment variables. This is well suited to running IAM Zero with containerised or serverless applications. The relevant environment variables are shown in the table above for each setting.

IAM Zero config file#

Finally, you can configure the IAM Zero client through a configuration file. This is well suited to running IAM Zero in a development environment, especially if you are running an IAM Zero server to build least-permission policies across multiple applications and projects that your team is working on. By default, this file is stored in ~/.iamzero.ini on Mac or Linux based systems. On Windows, you can determine the location of this folder as follows:

python -c "import os; print(os.path.expanduser(path='~/.iamzero.ini'))"

This file is configured automatically when you run the iamzero local command. The format of the file is similar to below:

token = 172db0070b6576f33b06eeab9a6eff70
url = http://localhost:9090

Including any of the variables in the table above in the iamzero section of the file will configure the IAM Zero client accordingly.


Note that both environment variables and initialisation variables will override any config set in the IAM Zero config file.