IAM Zero client libraries are configured with three mechanisms:
- Initialisation variables passed to the
iamzeroobject in your programming language
- Environment variables
- The IAM Zero config file (
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
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 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:
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
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:
The following configuration variables exist for IAM Zero:
|Variable||Environment Variable||Description||Default Value|
|url||IAMZERO_URL||The URL of the IAM Zero server to dispatch alerts to||http://localhost:9090|
|debug||IAMZERO_DEBUG||Whether to print additional debug logging messages||False|
|token||IAMZERO_TOKEN||The authentication token for the IAM Zero server||-|
|max_batch_size||IAMZERO_MAX_BATCH_SIZE||The maximum number of alerts to send in a single batch to the IAM Zero server||100|
|send_frequency||IAMZERO_SEND_FREQUENCY||The frequency in seconds at which to dispatch batches of alerts to the IAM Zero server||0.25|
|user_agent_addition||IAMZERO_USER_AGENT_ADDITION||An additional string to be added to the User Agent header in dispatches to the IAM Zero server||-|
|transport||IAMZERO_TRANSPORT||The transport mechanism to use (one of "http", "sqs")||http|
|transport_custom_aws_session||-||A custom ||-|
|transport_sqs_queue_url||IAMZERO_TRANSPORT_SQS_QUEUE_URL||The queue URL of the SQS queue to dispatch events to||-|
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.
Initialisation variables passed to the iamzero initialisation method at runtime will always take precedence over other configuration methods.
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.
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:
This file is configured automatically when you run the
iamzero local command. The format of the file is similar to below:
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.