Automating with AWS Lambda

Run Commander in the AWS Cloud

About

Commander is a powerful tool that can solve many issues and provide valuable information about your Keeper Security environment. In addition to using Commander on a local desktop or server, Commander can be run in a cloud environment such as AWS for performing scheduled or on-demand requirements.

In this example, we will demonstrate how to use Commander with AWS Lambda to run user and usage reports on a scheduled basis.

Prerequisites

• Commander installed on a local machine for one-time device setup

  • See the Installation and Setup page for download details

• A dedicated Keeper user account with a Master Password login method, used exclusively by this Lambda (SSO login and MFA will not work without human interaction)

• Access to AWS with permissions to create Lambda functions, Lambda layers, and SSM Parameter Store parameters, along with access to AWS CloudShell

One-Time Device Setup

Before Lambda can authenticate, you must complete device approval once on a local machine. Keeper requires all devices to be approved before password authentication can succeed — Lambda has no interactive shell to complete this step, so it must use a pre-approved device identity.

Steps

1. On your local machine, login to Commander with the dedicated Lambda account:

$ keeper shell

1. Complete the device approval process (email link, push notification, 2FA, or admin approval depending on your enterprise settings)

2. After successful login, locate the device_token in your config file:

$ cat ~/.keeper/config.json | grep device_token

Your config file format may vary depending on how Commander was installed. The CLI typically stores device_token at the top level, but SDK-based installations may use a nested structure (devices[].device_token). Open the file and locate the token manually if the grep command does not return a result.

1. Store the following four values as Lambda environment variables (or SSM parameters for production — see below):

   • KEEPER_DEVICE_TOKEN — the pre-approved device identity from step 3

   • KEEPER_USER — the account email address

   • KEEPER_PASSWORD — the master password

   • KEEPER_SERVER — the region endpoint (e.g., keepersecurity.com for US, keepersecurity.eu for EU)

What you do NOT need to store:

• private_key — Commander generates one automatically during password login. If you enable persistent login for warm-container optimization, the private_key is created and stored in /tmp as part of that setup.

• clone_code — regenerated automatically on every password login. Only used for persistent login session resumption, which is handled automatically in /tmp if enabled.

Steps

Create a Lambda Layer With AWS CloudShell

Setup

Commander needs to be packaged on a machine that matches what it will run on in AWS Lambda. To do this, we can create the Commander package in CloudShell.

AWS Lambda supports Python 3.10 or 3.11 for this workflow (Python 3.9 and earlier are no longer supported by AWS Lambda). Make sure your CloudShell environment is using one of these versions to build your Lambda Layer by checking the installed Python interpreter:

$ python3 --version
Python 3.11.6

If the Python version available in CloudShell does not match a runtime supported by AWS Lambda, install Python 3.10 or 3.11 prior to proceeding.

Building the Layer Content

For the next part of the process, we provide a convenient shell script for you to run from within your CloudShell environment, which will create the zip file that contains the keepercommander package needed for our Lambda Layer.

This script is intended to simplify and streamline much of the layer-content packaging process, both by encapsulating the various command calls that are standard for the process, and by abstracting away some build-process quirks specific to the keepercommander package and its dependencies. As such, we highly recommend using this approach over a more generic one, as it is much less likely to be error-prone.

View Script

package_layer_content.sh

#!/usr/bin/env bash

#   To create a `keepercommander` dependency layer for your AWS Lambda function :
#   1. Upload this script to any folder in your CloudShell environment.
#   2. (Optional) Upload your project's `requirements.txt` file  to the same folder.
#   3. In that folder, run
#             source ./package_layer_content.sh
#   4. There should now be a file named `commander-layer.zip` that can be uploaded
#     to your S3 bucket, where it can then be used to create a new Lambda layer

MAX_LIB_SIZE=262144000
LAYER_FILENAME='commander-layer.zip'
LAYER_PATH=$(pwd)/$LAYER_FILENAME
LIB_DIR='python'
VENV='commander-venv'
OTHER_DEPS='requirements.txt'

# Clean up previous artifacts
test -f $LAYER_FILENAME && rm $LAYER_FILENAME
test -d $LIB_DIR && rm -rf $LIB_DIR
test -d $VENV && rm -rf $VENV

# Create package folder to zip
mkdir $LIB_DIR

# Create and run virtual environment
python3 -m venv $VENV
source ./$VENV/bin/activate

# Install dependencies and package
python3 -m pip install cryptography --platform manylinux2014_x86_64 --only-binary=:all: -t $LIB_DIR
python3 -m pip install keepercommander -t $LIB_DIR

if test -f $OTHER_DEPS; then
  python3 -m pip install -r $OTHER_DEPS -t $LIB_DIR
fi

deactivate

# Check uncompressed library size
LIB_SIZE=$(du -sb $LIB_DIR | cut -f 1)
LIB_SIZE_MB=$(du -sm $LIB_DIR | cut -f 1)

if [ "$LIB_SIZE" -ge $MAX_LIB_SIZE ]; then
  echo "*****************************************************************************************************************"
  echo 'Operation was aborted'
  echo "The resulting layer has too many dependencies and its size ($LIB_SIZE_MB MB) exceeds the maximum allowed (~262 MB)."
  echo 'Try breaking up your dependencies into smaller groups and package them as separate layers.'
  echo "*****************************************************************************************************************"
else
  zip -r $LAYER_FILENAME $LIB_DIR
  echo "***************************************************************************"
  echo "***************************************************************************"
  echo 'Lambda layer file has been created'
  printf "To download, copy the following file path: %s\n%s\n$LAYER_PATH%s\n%s\n"
  echo 'and click on "Actions" in the upper-right corner of your CloudShell console'
  echo "***************************************************************************"
fi

# Clean-up
rm -rf $LIB_DIR
rm -rf $VENV

To use the script provided above, perform the following steps after downloading the file:

1. Upload the script to any folder (preferably an empty one) in your CloudShell environment

   • (Optional) If your project has a requirements.txt file containing a list of its dependencies, you can upload it to the same folder to include those dependencies in the resulting layer in addition to the keepercommander package.

2. In that same folder, run the following command in the terminal:

source ./package_layer_content.sh

1. You should now have a zip file (commander-layer.zip) in your current folder, which represents the content of your Lambda Layer.

There is a size limit on packaged Lambda layer content (even if stored in S3). So if you try to include additional dependencies by providing the requirements.txt file for the script above, and it results in the total content size exceeding this limit, the resulting zip file will be unusable. Hence, no layer content will be output when the script detects this scenario, and a helpful message will be shown to the user instead.

A relatively simple solution is to break up your dependencies into smaller groups to be packaged into corresponding separate layers. You can remove some (or all) dependencies from requirements.txt and run the script again. Any dependencies excluded from the resulting package can then be packaged separately into another layer using the standard packaging process.

Creating / Updating a Layer from the Content Zip File

Because the resulting zip file is going to be bigger than 50MB (the maximum allowed to be uploaded directly to a Lambda Layer), we'll have to first upload it to an AWS S3 Bucket, and then link the resulting S3 item to our Lambda Layer.

There are multiple ways to complete the remaining steps just mentioned, and if you prefer a GUI-based route, using the AWS Console is a perfectly valid option at this point. But since we're already in our CloudShell environment, using its built-in AWS CLI command-line tool seems like the simplest and most direct way forward, so that is the method we'll show here.

1. First, we need to upload our zip file to AWS S3. If you didn't previously create a S3 bucket for this task, you can do so by running the following command in CloudShell:

$ aws s3 mb <bucket-name>

where <bucket-name> is required to be a globally unique name.

1. Upload the newly-packaged zip file from CloudShell to your S3 bucket

$ aws s3 cp ./commander-layer.zip 's3://<bucket-name>'

1. Publish the Lambda layer with the uploaded content

$ aws lambda publish-layer-version --layer-name <layer-name> \
--description <layer-description> \
--content "S3Bucket=<bucket-name>,S3Key=commander-layer.zip" \
--compatible-runtimes python3.11

Create a Lambda

In AWS Lambda, use the Lambda editor to write a Python function.

The lambda_handler function is triggered by Lambda when it is processed.

See a complete example of a Commander Lambda function below:

#  _  __
# | |/ /___ ___ _ __  ___ _ _ ®
# | ' </ -_) -_) '_ \/ -_) '_|
# |_|\_\___\___| .__/\___|_|
#              |_|
#
# Keeper Commander
# Copyright 2024 Keeper Security Inc.
# Contact: [email protected]

import os
import json

# Without mounted volumes, Lambda can only write to /tmp. 
os.environ['HOME'] = '/tmp'
os.environ['TMPDIR'] = '/tmp'
os.environ['TEMP'] = '/tmp'

from keepercommander import api
from keepercommander.__main__ import get_params_from_config

keeper_tmp = '/tmp/.keeper'
os.makedirs(keeper_tmp, exist_ok=True)

# ------------------------------------------------------
# Keeper initialization function
# ------------------------------------------------------
def get_params():
    # Read credentials from environment variables
    user = os.environ.get('KEEPER_USER')
    password = os.environ.get('KEEPER_PASSWORD')
    server = os.environ.get('KEEPER_SERVER', 'keepersecurity.com')
    device_token = os.environ.get('KEEPER_DEVICE_TOKEN')

    # Write config.json with the pre-approved device_token
    config_path = keeper_tmp + '/config.json'
    with open(config_path, 'w') as f:
        json.dump({
            'user': user,
            'server': server,
            'device_token': device_token
        }, f)

    # Load params from the config we just wrote
    params = get_params_from_config(config_path)
    params.password = password
    return params

# ------------------------------------------------------
# Keeper JSON report function
# ------------------------------------------------------
def get_keeper_report(params, kwargs):
    from keepercommander.commands.aram import AuditReportCommand
    from json import loads
    
    report_class = AuditReportCommand()
    report = report_class.execute(params, **kwargs)
    return loads(report)
    
# ------------------------------------------------------
# Keeper CLI function
# ------------------------------------------------------
def run_keeper_cli(params, command):
    from keepercommander import cli
    
    cli.do_command(params, command)
    
# ------------------------------------------------------
# Lambda handler
# ------------------------------------------------------
def lambda_handler(event, context):
    # Initialize Keeper Commander params with pre-approved device token
    params = get_params()

    # Keeper login (uses the pre-approved device_token) and sync
    api.login(params)
    api.sync_down(params)
    # Enterprise sync (for enterprise commands)
    api.query_enterprise(params)

    # Approve any OTHER pending devices in the enterprise
    run_keeper_cli(
        params, 
        'device-approve -a'
    )
    
    run_keeper_cli(
        params, 
        'action-report --target locked --apply-action delete --dry-run'
    )

    return get_keeper_report(
        params,
        {
            'report_type':'raw', 
            'format':'json',
            'limit':100,
            'event_type':['login']
        }
    )

The program is made up of several parts:

The lambda_handler() function

This function is called when the lambda is triggered, all other functions should be called from this one.

The get_params() function

This function reads the pre-approved device token and credentials from environment variables, writes a config.json with the device identity, and returns a params object ready for api.login(). The device_token is the critical piece — it represents the device identity that was approved during the one-time setup on your local machine.

Why the device_token matters:

Keeper requires device approval before password authentication can succeed. Lambda has no interactive shell to complete device approval, so it must use a device_token that was pre-approved on another machine.

Multiple Lambda containers can share the same device_token and authenticate concurrently with password — each container writes the same device identity to its local /tmp/.keeper/config.json and logs in independently. The clone_code gets regenerated on each password login, but this does not matter since we are not using persistent login.

Commander Functions

Once logged in and synced up, you can run functions and create classes from the Commander SDK. The program above includes two functions - get_keeper_report(), which returns a JSON report (equivalent to audit-report command), and run_keeper_cli(), which simply executes CLI commands (without returning data in Python).

Storing Keeper credentials

The example above reads four values from Lambda environment variables:

Variable	Description
KEEPER_DEVICE_TOKEN	The pre-approved device identity from one-time setup
KEEPER_USER	Account email address
KEEPER_PASSWORD	Master password
KEEPER_SERVER	Region endpoint (defaults to keepersecurity.com)

This is the simplest approach and requires no additional AWS setup. However, environment variables are visible to anyone with lambda:GetFunctionConfiguration permission and may appear in CloudWatch logs if logged. For production deployments, use SSM Parameter Store instead (see next section).

Production: Using SSM Parameter Store

For production deployments, store credentials in AWS SSM Parameter Store as SecureString parameters. This keeps credentials out of your Lambda configuration and CloudWatch logs, uses KMS for encryption at rest, and lets you scope read access with IAM policies.

Create the following parameters in SSM (these are example paths — customize as needed):

• /keeper/lambda/device_token

• /keeper/lambda/user

• /keeper/lambda/password

• /keeper/lambda/server

Then replace the get_params() function in your Lambda code with this SSM-based version:

import os
import json
import boto3

os.environ['HOME'] = '/tmp'
os.environ['TMPDIR'] = '/tmp'
os.environ['TEMP'] = '/tmp'

from keepercommander import api
from keepercommander.__main__ import get_params_from_config

keeper_tmp = '/tmp/.keeper'
os.makedirs(keeper_tmp, exist_ok=True)

# Create SSM client once at module level
ssm_client = boto3.client('ssm')

def get_ssm_parameter(name):
    response = ssm_client.get_parameter(Name=name, WithDecryption=True)
    return response['Parameter']['Value']

def get_params():
    user = get_ssm_parameter('/keeper/lambda/user')
    password = get_ssm_parameter('/keeper/lambda/password')
    server = get_ssm_parameter('/keeper/lambda/server')
    device_token = get_ssm_parameter('/keeper/lambda/device_token')

    config_path = keeper_tmp + '/config.json'
    with open(config_path, 'w') as f:
        json.dump({'user': user, 'server': server, 'device_token': device_token}, f)

    params = get_params_from_config(config_path)
    params.password = password
    return params

Grant the Lambda execution role only the IAM permission it needs (ssm:GetParameter scoped by resource ARN), and do not log the retrieved credentials.

SSM standard parameters are free; SecureString uses KMS which has its own free tier (20,000 requests/month) — effectively no cost for typical Lambda workloads. For enterprise deployments that need built-in rotation, fine-grained audit, or cross-account access, use AWS Secrets Manager instead (adds a per-secret cost).

A note on persistent login

Commander supports persistent login to skip password entry on subsequent logins. However, persistent login is not viable for multi-container Lambda deployments.

Per the Keeper documentation, persistent login is "not intended for dynamic multi-server environments." When any instance logs in with password using the same device_token, it regenerates the clone_code and invalidates persistent login sessions on all other instances sharing that device identity. The persisted session also lives only in the container's /tmp and is lost whenever AWS recycles the container.

For single-container scheduled Lambdas (e.g., a once-daily cron where the same warm container handles every invocation), persistent login may provide a minor latency optimization on warm invocations. See the this-device command documentation for setup instructions.

For most Lambda use cases, password-based authentication on every invocation (as shown in the example above) is the correct approach.

Configure Lambda

Set Timeout

In the general configuration section of the Lambda configuration, it is recommended to change the timeout value. Some Commander functions take time, so if your script takes longer to complete than this number, the Lambda will automatically end without finishing.

You can set this to any number you are comfortable with. A value of 300 seconds (5 minutes) should be more than enough time for most processes.

Select Layer

In the Lambda editor, select the layer that you created above to include the Commander package in your Lambda build.

Create run Schedule

Create an EventCloud trigger to trigger the Lambda and set it to trigger at a cadence of your choice (for example once per day, or once every 30 days).

AWS can also be configured to trigger Lambda from a number of other sources including email and SMS triggers. See Amazon's documentation on invoking Lambda for more options:

Understanding Lambda function invocation methods - AWS LambdaAWS Lambda

Next Steps

We encourage you to experiment with other Commander functionality, Lambda invocation methods, and other AWS services (such as SNS for utilizing various methods for push notifications -- including SMS messages) to bring automated value to your Keeper processes.

For some examples of using the Commander SDK code, see the example scripts in the Commander GitHub repo:

Commander/examples at master · Keeper-Security/CommanderGitHub

To learn more about Commander's various methods, see the Command Reference section.

Command Reference