Commander CLI Install

Follow these instructions to install Keeper Commander on your system for CLI access

Developer Instructions

Installing the CLI from source code with scripting capabilities

Making Changes

In order to add additional modules, change source code or make other edits to Commander, you will need to Install Commander in Developer mode. Developer mode clones the Commander source code to your local machine in a virtual environment.

Supported Operating systems

• Windows 10 (1903 and above)

• Windows Server 2016 (1803 and above)

Video Overview

Watch the video below to learn how to install and log in to Keeper Commander.

Typical Binary Installation (recommended)

⬇️ Download Keeper Commander .exe file from GitHub

On the Commander Github page, the current commander build is always available via the releases link.

The binary download is the file named: keeper-commander-windows-vX.XX.exe

Python (PIP) installation

Setup with Python3:

Download the current version of Python from https://www.python.org/

Recommended releases:

Windows 11 - Python 3.10.8

Windows 10 - Python 3.10.8

Server 2018 - Python 3.10.8

Server 2016 - Python 3.9.13

Validate Python is correctly installed by checking the installed version from launching the cmd prompt.

C:\>pip3 --version

From the command prompt, install Keeper Commander with pip3:

pip3 install keepercommander

Once installed, ensure you have the latest version by upgrading Commander:

pip3 install --upgrade keepercommander

Login to Keeper in order to validate Keeper Commander is properly installed:

keeper shell

Supported Operating systems

• Mac OS 10.15 or newer

Video Overview

Watch the video below to learn how to install and log in to Keeper Commander.

Binary installation

On the Commander Github page, the current commander build is always available via the releases link.

For mac installs download and install the file named: keeper-commander-mac-vx.xx.pkg

After installation, type "keeper shell" to login.

Python PIP3 installation

Pre-requisites

Download and install Python and pip3

Instructions

Installing Python:

Download the current version of Python from: https://www.python.org/

Validate Python is correctly installed by checking the installed version from a terminal window:

$ pip3 --version

From a terminal window, install Keeper Commander with pip3:

$ pip3 install keepercommander

Once installed, ensure you have the latest version by upgrading Commander:

$ pip3 install --upgrade keepercommander

To see which version of Keeper you're running:

$ keeper version -v    

To validate Keeper Commander is properly installed login:

$ keeper shell

Supported Operating systems:

• Ubuntu (Current release and latest LTS release)

• CentOS (Current)

• RedHat (Current)

Video Overview

Watch the video below to learn how to install and log in to Keeper Commander.

Pre-requisites

1. Install Python 3.x

2. Install Package installer for Python

Instructions

Installing Python:

‌Based on your distribution, follow the instructions to install Python 3.x, typical installation commands are listed below.

$ sudo apt install python3

OR

$ yum install -y python3

Also ensure the "Package installer for Python" is installed (you may need to run an apt-get update first):

$ sudo apt install python3-pip

OR

$ sudo yum install python3-pip

Next, upgrade pip3 to the latest version using the command:

$ sudo pip3 install --upgrade pip

$ pip3 --version

Next, install Keeper Commander using pip3:

$ pip3 install keepercommander

Once installed, ensure you have the latest version by upgrading Commander:

$ pip3 install --upgrade keepercommander

Now you can launch the keeper shell using command:

$ keeper shell

You should see:

Installation

To develop or test Keeper Commander from source, use a Python virtual environment to isolate dependencies.

Clone the Commander Repository

Clone the GitHub repository to your local machine: https://github.com/Keeper-Security/Commander

git clone https://github.com/Keeper-Security/Commander
cd Commander

The "master" branch will mirror the production release. The "release" branch references the upcoming release. To optionally switch to the release branch:

git checkout release

Install Python

Install the most recent Python3 installation from python.org.

Install Virtualenv

Create and Activate Virtual Environment

virtualenv -p python3 venv
source venv/bin/activate

python -m venv venv
.\venv\Scripts\activate

Install Dependencies and Set Up in Dev Mode

pip install -r requirements.txt
pip install -e .

Setup Complete

You can now launch the Commander CLI:

keeper shell

See the Logging in section to understand the authentication process. Explore all of the Commands available.

Sample Python Code

To run bash-formatted CLI commands directly from a python script, you can import the cli package from the keepercommander library and run its do_command function:

from keepercommander.__main__ import get_params_from_config
from keepercommander import cli

my_params = get_params_from_config("{{path_to_config_file}}")

cli.do_command(my_params, "{{cli_command}}")

In the above example, authentication is handled with the get_params_from_config function, which is pointing to your config.json file. See Building a Persistent Login Config for more information on how to build this configuration file.

Alternatively, you can leverage the full scope of the Commander SDK by using its internal classes and functions. Several standalone python scripts can be found here, with examples for searching records, creating teams and sharing folders, and more.

Overview

The Keeper Commander CLI is has been written in 3 languages (Python, .Net and Golang) with the source code available on Github.

.Net SDK

Keeper's .Net Commander tool provides basic vault access, a developer SDK for vault access and administrative functions: https://github.com/Keeper-Security/keeper-sdk-dotnet

For source integration into your .Net code, please utilize the KeeperSDK Library source code: https://github.com/Keeper-Security/keeper-sdk-dotnet/tree/release/KeeperSdk

API documentation

Find detailed API documentation at the following URL: https://keeper-security.github.io/gitbook-keeper-sdk/CSharp/html/R_Project_Documentation.htm

Developer Requirements

• .Net Framework 4.5

• .Net Core 2.1

• .Net Standard 2.0

Examples

For help with implementation of SDK features, please see the Sample Application: https://github.com/Keeper-Security/keeper-sdk-dotnet/tree/master/Sample

The .Net Commander CLI Sample App contains several basic operations such as logging in, authentication with two-factor, loading and decrypting the vault and updating passwords. https://github.com/Keeper-Security/keeper-sdk-dotnet/tree/release/Commander

Overview

A version of Keeper Commander is developed in .Net with a PowerShell module. This is published to the PowerShell Gallery as the PowerCommander module. This document provides instructions for installing and using this PowerShell Module.

PowerShell CLI

Keeper's PowerShell command-line tool (PowerCommander) provides basic vault access and administrative functions.

PowerShell module for Keeper Commander is available on the PowerShell Gallery:

PowerCommander 0.9.1nuget

PowerShell Gallery Install

To install PowerCommander from PowerShell Gallery:

Install-Module -Name PowerCommander

GitHub Repository

To run the PowerCommander module from the source, refer to the following GitHub Link:

https://github.com/Keeper-Security/keeper-sdk-dotnet/tree/master/PowerCommander

Installation Troubleshooting

Set Execution Policy Permissions

If you are unable to run PowerCommander commands, you may need to set the Execution Policy. To check this, run the following command:

PS> Get-ExecutionPolicy -List

Your output would be similar to this:

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser       Undefined
 LocalMachine       Undefined

If the Scope for your installation is Undefined or Restricted, set it to Unrestricted with the following command:

PS> Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Note: The above command set the CurrentUser scope

PowerCommander Commands

Cmdlets

Sharing Cmdlets

Enterprise Cmdlets

Secret Manager Cmdlets

Additional Commands

Not all capabilities of Keeper Commander (Python) have been added to the PowerShell module. We add them on request by customers. If you have requests for our engineering team, please email commander@keepersecurity.com.

Examples

Connect To Keeper Account

PS > Connect-Keeper
     Keeper Username: email_address@company.com
        ... Password:

List the content of Keeper folder

PS > kdir

    Vault Folder: \


Mode    UID                      Name
----    ---                      ----
f-----  b3TMAYfOWJqNxeLjlA6v_g   dasdasd
f----S  BvHeHGkdRJfhGaRcI-J5Ww   shared
-r-AO-  5qx_urh2EsrL0wBdi34nFw   Web
-r---S  ktY3jEBqwFDi9UYZSxmIpw   Control

• f - folder

• r - record

• S - shared

• A - file attachments

• O - owner

Show Two Factor Code for all records in the current Keeper folder

PS > kdir -ObjectType Record | Show-TwoFactorCode

Show Two Factor Code for all records in the Vault.

PS > kr|2fa

where

• kr is alias for Get-KeeperRecord

• 2fa is alias for Show-TwoFactorCode

Copy record password to clipboard

PS > 'contro' | kcc

where

• contro is a substring of the record title. See last entry of kdir output in example #2

• kcc is alias for Copy-KeeperToClipboard

or

PS > 'ktY3jEBqwFDi9UYZSxmIpw' | kcc

'ktY3jEBqwFDi9UYZSxmIpw' is the Record UID of the same record

Add/Modify Keeper record

PS > kadd -Title 'Record for John Doe' -GeneratePassword login=email@company.com url=https://company.com 'User Name=John Doe' 

creates a legacy record in Keeper

PS > kadd -RecordType login -Title 'Record for John Doe' -GeneratePassword login=email@company.com url=https://company.com 'User Name=John Doe' 

creates a record of login type in Keeper

PS > $address = @{"street1" = "123 Main St."; "city" = "Neitherville"; "state" = "CA"; "zip" = "12345"}
PS > kadd -RecordType address -Title 'Home Address' -address $address phone.Home='(555)123-4567' name="Doe, John"

PS > kadd -Uid <RECORD UID> -GeneratePassword 

generates a new password for existing record

Pre-defined fields supported by both legacy and typed records

• login Login

• password Password

• url Website Address

Copy owned record to folder

PS > Get-KeeperChildItem -ObjectType Record | Move-RecordToFolder 'Shared Folder'

copies all records in the current Keeper folder to the folder with name 'Shared Folder'

List all enterprise users

PS > Get-KeeperEnterpriseUser

Create a new Managed Company

PS> New-KeeperManagedCompany -Name "Company Name" -PlanId enterprisePlus -Allocated 5

Switch to a new Managed Company

PS> switch-to-mc "Company Name"

First Login on a New Device

To login to Commander for the first time, click the Keeper Commander icon or open a shell and type:

keeper shell

Set Server

The Keeper Commander CLI will default to the US data center. To change regions, use the server command:

US: server US EU: server EU AU: server AU CA: server CA JP: server JP GovCloud: server GOV

Use "server" command to change Keeper region > "server US"
	US: keepersecurity.com
	EU: keepersecurity.eu
	AU: keepersecurity.com.au
	CA: keepersecurity.ca
	JP: keepersecurity.jp
	GOV: govcloud.keepersecurity.us
To login type: login <email>

Login to the shell by typing login. If this is your first login, you will need to follow the device approval workflow. This is only needed once, as an extra layer of security to trust the device you are on.

First Login Example

Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander

Device Approval Required
Approve by selecting a method below:
        "email_send" to send email
        "email_code=<code>" to validate verification code sent via email
        "keeper_push" to send Keeper Push notification
        "2fa_send" to send 2FA code
        "2fa_code=<code>" to validate a code provided by 2FA application
        "approval_check" check for device approval
Type your selection: 

• If you wish to approve via email:

  • Type email_send or es

  • Enter the security code with email_code=<code>

• If you wish to approve via Keeper Push:

  • Type keeper_push

  • Approve via push

  • Then type approval_check

• If you wish to approve via 2fa code:

  • Input 2fa_send

  • Then input 2fa_code=<code>

Once complete you will receive the following message:

Device was approved

Logging in with a Master Password

After device approval, you will immediately move to the login process, or if you previously approved the device, this will be the first step.

Master Password Login Example

Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander
Enter password for yourname@email.com
Password: *********

Successfully authenticated with Login V3 (Password)
Syncing...
Decrypted [23] record(s)
My Vault>

Logging in With 2FA

If you have 2FA enforced on your account, you will be required to pass the 2FA step before logging in with a Master Password. Your login flow in commander will follow the same rules you have for logging into the Vault.

Login Example with 2FA

Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander
This account requires 2FA Authentication
     U2F (FIDO Security Key)
     Send SMS Code
  3. TOTP (Google Authenticator) [ ENABLED ]
     DUO
Selection:

Each 2FA method that is enabled will have a number next to it.

In this example, only TOTP is enabled, so 3 would need to be entered, followed by the TOTP code. Enter the corresponding number to proceed:

Selection: 3

Enter 2FA Code or Duration: 2fa_duration=forever
Enter 2FA Code or Duration: 123456

By default, Keeper Commander prompts for 2FA code on every login. To store 2FA authentication for this device either for 30 days or forever, type one of the following before entering the code:

• 2fa_duration=30_days to prompt for 2FA every 30 days, or...

• 2fa_duration=forever to never prompt again on this device

Logging in with a Proxy

If your network configuration requires using a proxy server you can use the proxy command before logging in.

My Vault> proxy -h                                                                                                                              
usage: proxy [-h] [-a {list,add,remove}] [schema://[user:password@]host:port]

Sets proxy server

positional arguments:
  schema://[user:password@]host:port
                        "add": proxy address. Schemas are "socks5h", "http", "socks4", etc

optional arguments:
  -h, --help            show this help message and exit
  -a {list,add,remove}, --action {list,add,remove}
                        action

Enterprise SSO Login

If SSO is configured for your Keeper enterprise, the following screen will appear for users that login to Commander:

Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander

SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/xxx

Navigate to SSO Login URL with your browser and complete login.
Copy a returned SSO Token into clipboard.
Paste that token into Commander

  a. SSO User with a Master Password
  c. Copy SSO Login URL to clipboard
  o. Navigate to SSO Login URL with the default web browser
  p. Paste SSO Token from clipboard
  q. Quit SSO login attempt and return to Commander prompt
  
Selection:

To login to Commander using SSO, you will need to paste a token provided by the SSO provider from your web browser into Commander. To receive the SSO token, follow these steps:

SSO Login Using Default Browser

To have Commander automatically open the default browser to the SSO Connect page, enter "o" in the SSO selection and hit Enter

The default browser for your system will open to the SSO Connect page.

SSO Login Using Pasted Token

You can copy the URL to your SSO's logins screen from the SSO Connect text in Commander, or enter "c" in the SSO selection and hit Enter to copy the URL to your clipboard.

SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/xxx

Once the URL is copied, paste it into a web browser to navigate to the SSO Connect page.

After a successful SSO login, the web page will show a yellow "Copy" button. Click the button to copy the token.

Paste the SSO Token

Once the token has been copied, go back to Commander to complete the SSO login.

In Commander enter "p" in the SSO selection screen and hit Enter to paste the token from your clipboard into Commander and complete SSO login.

Device Approval with SSO Login

If device approval is turned on for your account, the device approval selection will be shown after the first SSO login.

Approve this device by selecting a method below:
  1. Keeper Push. Send a push notification to your device.
  2. Admin Approval. Request your admin to approve this device.
  r. Resume SSO login after device is approved.
  q. Quit SSO login attempt and return to Commander prompt.
Selection: 

Enter your selection and hit Enter to continue with device approval.

1 : Approve with Keeper Push

2 : Approve with Admin Approval

r : Resume SSO login after the device has been approved

See First Login on a New Device section for more details on device approval.

Use a Master Password with SSO Login

Customers who normally login to their Keeper Vault using Enterprise SSO Login (SAML 2.0) can also login to Keeper Commander using a Master Password. To make use of this capability, it must be enabled by the Keeper Administrator and then configured by the user. The steps are below:

Login to the Keeper Admin Console

As the admin, login to the Keeper Admin Console as you normally do.

Enable SSO Master Password Policy

For the User/Role who will be accessing Keeper Commander, open the Role Enforcement Policy setting screen. Enable the option "Allow users who login with SSO to create a Master Password"

Login to the End-User Vault using SSO

As the user who will be using Commander, login to the Keeper Web Vault or Keeper Desktop app with your SSO provider as you normally do.

Create a Master Password

Visit the Settings > General screen and setup a Master Password

After the Master Password is created, you are now able to login to Keeper Commander.

Optional: Force SSO Master Password Login in Configuration File

Add the following line to your configuration file.

{ ...
    "sso_master_password": true,
...}

Persistent Login Sessions ("Stay Logged In")

Commander can be configured to stay logged in between sessions, and you can also configure how long the device will remain logged in without activity. This feature is referred to as persistent login or "Stay Logged In" in the Vault UI.

Use the this-device command to set your preferences.

Example:

My Vault> this-device
                     Device Name: Commander CLI on macOS
                Data Key Present: missing
                 IP Auto Approve: OFF
                Persistent Login: OFF
           Device Logout Timeout: 1 hour
       Enterprise Logout Timeout: 7 days
        Effective Logout Timeout: 1 hour
                     Is SSO User: True

To enable "Stay Logged In" so that you're not prompted for authentication, use these commands:

My Vault> this-device persistent-login on 
My Vault> this-device register

If persistent login is enabled, you won't be prompted to authenticate the next time you run Commander:

user@mycomputer ~ % keeper shell
Logging in to Keeper Commander
Successfully authenticated with Persistent Login

To set the inactivity logout timer to a certain number of minutes:

My Vault> this-device timeout 600
Successfully set "logout_timer" to 10 hours.

Working with Commander

Commander Configuration File

When you login to Commander for the first time, a config.jsonfile is created, if one does not exist. When launching Commander as an application, the config file is created at ~/.keeper on MacOS and Linux, and at C:\Users\[USERNAME]\.keeper on Windows. When using Commander from the command line or terminal, the config.json file is created in the current directory, unless the --config option is passed a different location.

Config File Example

{
    "server": "keepersecurity.eu",
    "user": "services@company.com",
    "password": "your_password_here",
    "private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
    "device_token": "g6RDMxr1t-bcVdBeBpz-xQ",
    "mfa_duration": "forever",
    "proxy": "http://proxy_user:proxy_password@host:port",
    "sso_master_password": false,
    "skip_records": false,
    "debug": false,
    "plugins": [],
    "commands": [],
    "timedelay": 0
}

Config File Options

• server Keeper data center region

  Commander defaults to the US region, so customers hosted in other regions will need to specify a server in the config.

  Region

  Property Setting for "server"

  US

  https://keepersecurity.com

  EU

  https://keepersecurity.eu

  AU

  https://keepersecurity.com.au

  GOV

  https://govcloud.keepersecurity.us

  CA

  https://keepersecurity.ca

  JP

  https://keepersecurity.jp

• debug enable or disable detailed crypto output and network logging

  • set to true or false

• plugins Set which password rotation plugin will be loaded.

  • Learn more about password rotation plugins for Commander.

• commands Comma-separated list of Keeper commands to run

• timedelay Run the specified commands every X seconds.

  • example: "timedelay":600 will run the commands every 10 minutes.

• private_key Device private key generated by Commander on a new device. This key is used to encrypt and decrypt vault data.

• device_token Device token generated by the backend for every new device. The device token is used to uniquely identify the device, and it controls the session behavior.

• proxy Proxy URL: schema://[user:password@]host:port where schema

  • http HTTP proxy

  • socks5 SOCKS5 proxy with local DNS

  • socks4 SOCKS4 proxy with local DNS

  • socks4a SOCKS4 proxy with remote DNS

  • socks5h SOCKS5 proxy with remote DNS

• sso_master_password Forces master password login for Enterprise SSO Accounts

• skip_records Prevents syncing of records if the value is set to true. For users with very large vaults, this allows you to login and perform commands without requiring a full sync of records. After login, to force sync records use sync-down --force Example line in config.json: "skip_records":true,

Running Commands from the Configuration File

Using the commands field allows for predetermined commands to be run on login.

Enter a comma-separated list of Keeper Commander commands to be run. Example:

config.json
{
 ...
 "commands": ["sync-down", "file-report -d"]
 ...
}

In this example, it will sync, and then download a report of the available files in the vault.

Configuration File Location

If you start Commander from the binary installer, the config file will be located in the user's home directory in a folder called ".keeper".

• On Mac environments, the configuration file is located in ~/.keeper/config.json

• In Windows environments, the configuration file is located in /Users/{Username}/Documents/.keeper/config.json

If you use Commander from a pip3 or source installation, the configuration file will be created in the current folder where the Commander executable is started from.

You can specify the config file to use when launching Commander, for example:

$ keeper shell --config /path/to/config.json

Authenticating on Multi-Server Environments

In an environment with multiple servers or dynamic servers, you can use the same config.json file for each instance as long as all of the fields are populated, and the device identifier has been "approved".

Example config.json file:

{
    "user": "service@company.com",
    "password": "RANDOM_LONG_PASSWORD",
    "server": "https://keepersecurity.com",
    "private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
    "device_token": "g6RDMxr1t-bcVdBeBpz-xQ"
}

As long as you have performed a device approval step at least one time, this configuration file can be loaded on any number of servers.

If you plan to distribute this file to multiple instances, we recommend protecting this file through secure storage facilities provided by your cloud infrastructure. We also recommend assigning the user account to a Role Enforcement policy on the Keeper Admin Console that is locked down based on IP range.

Persistent Login Sessions

Persistent Login allows a Commander device to authenticate to Keeper without having to populate the "password" in the configuration file. This is useful for automation scripts or calling Commander from other software.

In order to enable this feature, you need to register the device and turn on the persistent login setting. Once that's done the next time you login with the specified configuration file, the session will be resumed and the user will be automatically logged in. Several tokens are stored in the config.json file in order to resume a session automatically.

Creating a Persistent Login Config

Commands to enable persistent login on a device for 30 days (max):

My Vault> this-device register
My Vault> this-device persistent-login on
My Vault> this-device ip-auto-approve on
My Vault> this-device timeout 30d
My Vault> quit

Once persistent login is set up on a device, the config.json in the local folder will look something like this:

{
    "private_key": "8n0OqFi9o80xGh06bPzxTV1yLeKa5BdWc7f7CffZRQ",
    "device_token": "R2O5wkajo5UjVmbTmvWnwzf7DK1g_Yf-zZ3dWIbKPOng",
    "clone_code": "retObD9F0-WDABaUUGhP0Q",
    "user": "me@company.com",
    "server": "keepersecurity.com"
}

You can create any number of persistent login sessions. However, the persistent session option is not intended for dynamic multi-server environments. If you share the exact configuration file on multiple servers, persistent login will fail when attempting to login to the second server.

For multi-server dynamic environments, please refer to the prior section of using a fully populated config file that is distributed to each instance.

Executing Commands with Persistent Login

If you would like to maintain different configurations, you can run Commander with a specified config file. For example, this will open the CLI without prompting for login:

$ keeper --config=my_config.json shell

To leave the CLI, make sure to type "quit" instead of "logout". Typing "logout" will expire the session and you'll need to create a new persistent session config.

Another example would be executing a particular command without prompting for login. In the below example, a new record is created automatically with a single line.

$ keeper --config=config_demo.json "add --login myuser -g --url https://google.com -t 'Google'"

Batch Mode through STDIN

You can batch execute a series of commands and pipe the file to STDIN of Commander. For example, create a text file called test.cmd with the following lines:

add --login=user@gmail.com --pass=somemasterpass --url=https://google.com --force "Some Record Title"
upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="user@company.com" --write "Some Record Title"

To run this file in a batch mode:

cat test.cmd | keeper --batch-mode -

or

keeper test.cmd

Handling Errors

The batch execution is aborted if some command returns failure. Use @ in front of the command to suppress the possible command error.

add --login=user@gmail.com --pass=somemasterpass --url=https://google.com --force "Some Record Title"
@upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="user@company.com" --write "Some Record Title"

Batch Mode in Windows

Following example shows how to execute three commands using Windows command line:

(echo ls -l && echo whoami && echo tree) | keeper --batch-mode -

Combining Batch Mode and Persistent Login

By setting up a persistent login configuration (as described in the previous section), you can execute a series of batch commands without any prompt for login. For example:

$ keeper --config=my_config.json bunch_of_commands.cmd

Batch Mode from the CLI

Keeper supports a batch mode from within the CLI which can conveniently execute commands sequentially.

The command is called "run-batch" and can be executed like below:

My Vault> run-batch -d 10 "C:\My Drive\Keeper\commands.txt"

In this example, each command is executed with a delay of 10 seconds in between.

On Linux environments, the path can also be specified such as:

My Vault> run-batch -d 5 "/path/to/file.txt"

Store Configuration to Protected storage

The sensitive configuration file parameters (user, password, server, device_token, private_key, clone_code) can be optionally stored in 3rd party secrets managers or hardware security modules.

To use protected storage, add config_storage property to your config file. config_storage value has URL format. Please reference the appropriate section below for storage URL format.

Commander supports the following protected storages:

• AWS Secrets Manager

• AWS Key Management Service

Amazon AWS Secrets Manager can be utilized on an EC2 instance hosting Keeper Commander in order to protect and store the configuration data.

The AWS Secrets Manager protected storage resource URL format is as follows:

aws-sm://<SECRET-REGION>/<SECRET_NAME>

Example:

aws-sm://us-west-2/commander/config

The secret name should contain URL-safe characters and not start with forward slash /

Keeper Commander requires the following access permissions to the secret resource

• secretsmanager:GetSecretValue

• secretsmanager:PutSecretValue

Example AWS policy granting access to secret

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:<region-id>:<account-id>:secret:<unique-secret-name>"
        }
    ]
}

Amazon AWS Key Management Service can be utilized on an EC2 instance hosting Keeper Commander in order to protect and store the configuration data.

The AWS Key Management Service protected storage resource URL format is as follows:

aws-kms://<KEY-REGION>/<KEY ID or ALIAS>

Example:

aws-kms://us-east-1/12345678-abcd-1234-dcba-123456789012

aws-kms://eu-west-1/alias/key

The secret name should contain URL-safe characters

Keeper Commander requires "key users policy" to be granted to AWS user or role.

To set up a scheduled task in Windows to run a specific Keeper Commander CLI command on a scheduled basis, you can use the Task Scheduler tool.

In the below example, we'll re-generate a password in the vault on a daily basis.

Prerequisites:

(1) Install

Install Keeper Commander for Windows

(2) Login

Login to Commander by launching the application. For example:

server US
login email@company.com

(3) Enable persistent login

After login, set up persistent login so that the command can execute from Task Scheduler

As an example, the below commands will enable "Stay Logged In" for 30 days:

this-device register
this-device persistent-login on
this-device ip-auto-approve on
this-device timeout 30d
quit

To exit the shell session, type quit but don't type logout. Logout will expire the session and the automations won't work.

To confirm that persistent login is working, execute Commander again and it will automatically login to the shell.

(4) Create a record

From the command line, we'll create a quick record with a random password.

record-add -t "Test Record" password=$GEN --record-type=login

If you have the web vault or other Keeper vault opened, you'll see the record appear.

(5) Open Task Scheduler

• Press Win + R to open the Run dialog.

• Type taskschd.msc and press Enter. This opens the Task Scheduler.

(6) Create a New Basic Task

• In the Task Scheduler, click on the "Create Basic Task..." option on the right side.

• Enter a name and description for your task, such as "Daily Keeper Commander Task".

• Click Next.

(7) Set the Trigger

• Choose the "Daily" option and click Next.

• Set the start date and time for the task to run. Ensure the recurrence is set to "1 day" to repeat the task daily.

• Click Next.

(8) Set the Action

• Choose the "Start a program" option and click Next.

• In the "Program/script" field, enter the path to your Keeper Commander executable, for example:

"C:\Program Files (x86)\Keeper Commander\keeper-commander.exe"

• In the "Add arguments (optional)" field, enter your Keeper Commander CLI command. For example:

record-update -r "Test Record" password=$GEN

(9) Finish the Task

• Click Next to review the details of your task.

• Click Finish to create the task.

(10) Execute

• To make sure the command works, select the Task and click "Run" on the right side.

Summary

In this particular example, the password will rotate from the Keeper vault and you'll see this occur in realtime across all logged-in vault clients. Another example is running a security audit report, such as:

security-audit-report --output c:\path\to\file

Any feature or capability of the end-user vault or Admin Console can be automated this way. Take a look at all the Keeper Commander commands available.

To expand upon this use case, you would likely want to set up a Batch file and execute the batch of commands instead of adding them directly on the CLI arguments. More information about batch mode commands can be found here.

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

  • See the Installation and Setup page for download details

• A Keeper user account with a Master Password login method (SSO login and MFA will not work without human interaction)

• Access to AWS with permissions to create Lambda functions and associated layers, along with access to AWS CloudShell

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 CloudShell comes with Python 3.7 pre-installed, but just to be sure you are using a supported version of Python (versions 3.6 - 3.11) to build your Lambda Layer, go ahead and check the version of the installed Python interpreter in your CloudShell console.

$ python3 --version
Python 3.9.16

In case the Python version you're running is not supported by Commander, install one of the supported versions listed above 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.

#!/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
python -m venv $VENV
source ./$VENV/bin/activate

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

if test -f $OTHER_DEPS; then
  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.

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, so you may have to try at least a few times until one is found.

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 python<your-version>

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: ops@keepersecurity.com
#
#
import json
import os
import datetime
from typing import Optional

from email.mime.application import MIMEApplication
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

import boto3

from keepercommander import api
from keepercommander.commands.enterprise import UserReportCommand
from keepercommander.commands.security_audit import SecurityAuditReportCommand
from keepercommander.params import KeeperParams


# Create report (format: JSON) combining data from 2 existing Commander reports
def create_user_report(params):  # type: (KeeperParams) -> Optional[str]
    user_report = UserReportCommand()
    user_report_data = user_report.execute(params, format='json')
    data = json.loads(user_report_data)
    users = {x['email']: x for x in data}
    security_audit_report = SecurityAuditReportCommand()
    security_audit_report_data = security_audit_report.execute(params, format='json')
    if security_audit_report_data:
        data = json.loads(security_audit_report_data)
        for x in data:
            if 'email' in x:
                email = x['email']
                if email in users:
                    user = users[email]
                    for key in x:
                        if key not in user:
                            if key not in ('node_path', 'username'):
                                user[key] = x[key]
                else:
                    users[email] = x

    return json.dumps(list(users.values()), indent=2)


# This Lambda's entry point
def lambda_handler(event, context):
    params = get_params()
    api.login(params)
    api.query_enterprise(params, True)
    
    # Log Commander-related issues (e.g., incorrect credentials) 
    # using AWS's built-in logging module and abort
    if not params.session_token:
        print('Not connected') 
        return 'Error: See Lambda log for details'
    if not params.enterprise:
        print('Not enterprise administrator')
        return 'Error: See Lambda log for details'
    
    # Generate and send report 
    report = create_user_report(params)
    response = email_result(report)
    return response


# Email report data (as JSON attachment) to recipient specified in this Lambda
# function's environment variables
def email_result(report):
    sender = os.environ.get('KEEPER_SENDER')
    sendto = os.environ.get('KEEPER_SENDTO')
    region = 'us-east-1'
    ses_client = boto3.client('ses', region_name=region)

    message = MIMEMultipart('mixed')
    message['Subject'] = 'Keeper Commander User Security Report With  CSV (attached)'
    message['To'] = sendto
    message['From'] = sender
    now = datetime.datetime.now()

    body = MIMEText(f'User Report Output created and sent at {now}', 'plain')
    message.attach(body)

    attachment = MIMEApplication(report)
    attachment.add_header(
        'Content-Disposition',
        'attachment',
        filename='user-report.json'
    )
    message.attach(attachment)

    response = ses_client.send_raw_email(
        Source=message['From'],
        Destinations=[sendto],
        RawMessage={'Data': message.as_string()}
    )
    
    return response


# Get required Commander parameters from environment variables
def get_params():
    user = os.environ.get('KEEPER_USER')
    pw = os.environ.get('KEEPER_PASSWORD')
    server = os.environ.get('KEEPER_SERVER')
    private_key = os.environ.get('KEEPER_PRIVATE_KEY')
    token = os.environ.get('KEEPER_DEVICE_TOKEN')
    my_params = KeeperParams()
    
    # Force password-login (needed for SSO + Master Password accounts)
    my_params.config = {'sso_master_password': True}
    
    my_params.user = user
    my_params.password = pw
    my_params.server = server
    my_params.device_private_key = private_key
    my_params.device_token = token
    return my_params

The function 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.

Gathering Commander Parameters

Commander uses some parameters in order to authenticate the user account. We will attach these as environment variables and inject them into the Lambda. See further instructions below.

Commander Functions

The above steps are all that are required to run Commander in Lambda, once they have been done and Commander SDK code can be performed.

In this example, we run a user status report and send the results to an email address.

Setting Commander Parameters

Commander uses some parameters to authenticate the user account and identify what Keeper region to access. In order to pass these parameters into Lambda, we will set them as environment variables.

Gathering parameters

Commander automatically creates the required parameters when you login to the CLI. The easiest way to generate the required parameters is to login to the Commander CLI on your machine.

To get the Commander parameters, open the generated config.json file. By default this is located in the Users/[your username]/.keeper/ folder on your machine. See the config file documentation for more information.

You should see a file that looks similar to this:

{
    "clone_code": "36[...]A0g",
    "user": "user@example.com",
    "server": "keepersecurity.com",
    "private_key": "sxv[...]oz3p=fzw",
    "device_token": "xko[...]r2IxdiQ"
}

Setting Parameters in AWS Lambda

To set the required Commander parameters as environment variables, first head to the lambda configuration and select "Environment Variables".

Set each commander parameter as an environment variable to be used by the Lambda.

You will also need to add your keeper master password to be used to login to Commander.

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:

Invoking Lambda functions - AWS LambdaAWS Lambda

Configure For Sending Emails

In this example, we are sending an email with the report results. In order to enable the email, you will need to allow Lambda to access SES SendEmail/SendRawEmail service.

You will also need to create an IAM identity to enable email sending.

For more information on setting up email sending with AWS, see Amazon's documentation:

Send email using Lambda and Amazon SESAmazon Web Services, Inc.

In this example, we are sending an email with the report results. In order to enable the email, you will need to allow Lambda to access SES SendEmail/SendRawEmail service.

Next Steps

In this example, we run a report that combines the results of 2 Commander reports (user-report and security-audit-report) and send it via email as a JSON attachment, allowing us to obtain enterprise-wide security-monitoring data -- e.g., last-login date and overall security scores for each user in the enterprise -- in a regularly-scheduled and automated way. However, with this setup, any other set of Commander functions can be run with Lambda.

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.

Uninstallation - Python (pip3) Package

If you installed Keeper Commander with pip3, you can uninstall Keeper Commander by invoking the following command:

pip3 uninstall keepercommander

You will be prompted to confirm uninstallation:

$ pip uninstall keepercommander
Found existing installation: keepercommander 16.9.8
Uninstalling keepercommander-16.9.8:
  Would remove:
    /Library/Frameworks/Python.framework/Versions/3.11/bin/keeper
    /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/keepercommander-16.9.8.dist-info/*
    /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/keepercommander/*
Proceed (Y/n)? 

Uninstallation - Windows Binary (.exe)

If you installed Keeper Commander using the Windows binary, follow the following steps to uninstall:

1. Open Control Panel

2. Navigate to Programs > Programs & Features

3. Right Click "Keeper Commander" and select "Uninstall"

4. Follow the prompted directions on screen

For alternative ways on uninstalling program on Windows, refer to this page.

Uninstallation - Mac Binary (.pkg)

If you installed Keeper Commander using the Mac binary, follow the following steps to uninstall:

1. Open Finder

2. Navigate to Application Folder

3. Right Click "Keeper Commander" and select "Move to Trash"