Troubleshooting

In the event that our unquestionably perfect code fails to run here are some things to try...

UID Starts With '-'

Record UIDs are randomly generated and sometimes begin with the '-' (hyphen) character. When this happens, it prevents Commander CLI from recognizing the UID as a UID value.

To use UIDs in a positional parameter that begin with '-' add '--' before the UID.

Example:

get -- -UREsVJNP7vU-KTyZ3YF9A

Commander CLI will then recognize the UID without confusing it for a command switch. In this case, it will search for a record with the UID -UREsVJNP7vU-KTyZ3YF9A

Pairing UIDs that begin with '-' with additional command switches

If you plan on pairing the UID with additional command switches, then the UID needs to be placed after all the command switches. In other words, the UID needs to placed as the last positional parameter.

Example:

get --format json -- -UREsVJNP7vU-KTyZ3YF9A

Using UID that begins with '-' as an argument

If you need to use the UID as an argument for a command flag, there is instead a different format.

To do this, add "=" after the flag, and wrap the UID in quotation marks.

Example:

secrets-manager share add --app TestApp --secret="-fwZjKGbKnZCo1Fh8gsf5w"

Typed vs Untyped Records (V3 vs V2)

When using Commander you may encounter references to typed vs untyped or V2 vs V3 records. There are a few fundamental differences between these records which cause them to interact differently in some aspects of the platform.

What is a Typed Record (V3)

Records which have a record type are considered 'typed' or sometimes referred to as 'V3'. These records have a malleable structure which can be defined and customized as well as an updated encryption model with heightened security.

Typed records are required for some features, such as Keeper Secrets Manager.

What is a Legacy Record (V2)

Older records which were created before the release of record types are called 'untyped', 'legacy' or 'V2' records. These records have a set structure with a login, password, url, totp, and file attachment field (as well as notes). Any other fields must be added as custom fields to the record.

How to Identify Typed vs Legacy Records

In Commander, when you view the details of a record with the get command, Typed records will always show a type field, while Legacy records will have no type field at all.

Typed Record
My Vault> get uxRrj[...]ZAM0bSQ

                 UID: uxRrj[...]ZAM0bSQ
                Type: databaseCredentials
               Title: LastPass Database
               Notes: LP DB Notes
         type (text): SQL
              (host): hostName | 3030
             (login): SQL_Admin
     Database (text): MyDB
     
Legacy Record
My Vault> get 4XjSH[...]Gy1LAEg

                 UID: 4XjSH[...]Gy1LAEg
               Title: My Record
               Login: Login
            Password: Password

Additionally, the ls -l command shows records in a list with type as one column. Any record with a value in that field is typed, and any record with no value is legacy.

My Vault> ls -l
    #  Record UID  Type                 Title                    Login                      URL
---  ------------- -------------------  -----------------------  -------------------------  -----------------------------------
  1  V[...]w       login                Typed                    MyLogin                    example.com
  2  q[...]A                            Legacy                   MyLegacyLogin              legacy.com

Differences in Brief

	Legacy	Typed
Names	Legacy, Untyped, V2	Typed, V3
Fields	Set (login, password, url, totp, files, notes)	Customizable by type
Type Value (get [UID] command )	empty (No type field)	Type: type value e.g. 'login'

Command Permissions

You may encounter the following error message when attempting to perform an action with Commander:

You do not have the required privilege to perform this operation

The message indicates that the current logged in account does not have permission to perform the requested action.

Many Commander commands require some form of permission policy to be enabled. When relevant, the documentation should indicate when a permission is required to use a command.

There are three main permission types that can lead to this message.:

Role Enforcement Policies

Keeper roles can specify permissions allowed for all users in that role. For example a role can determine if users can share records or use Keeper Secrets Manager. When a user has multiple roles, the most restrictive permissions apply.

Read more about Role Enforcement Polices in the docs:

Enforcement PoliciesEnterprise Guide

Administrative Permissions

Keeper administrators have access to account-level actions and features which can be turned off and on with these permission policies. These include things like running compliance reports.

Read more about Administrative Permissions in the docs:

Delegated AdministrationEnterprise Guide

Secure Add-Ons

Some features require an additional add-on to be used. These include features such as Keeper Secrets Manager and the Advanced Reporting and Alerts Module which is required to run custom reports. Secure add-ons can be managed in the Secure Add-Ons section of the Keeper Admin Console.

Read more about managing add-ons in the docs:

Keeper Admin Console OverviewEnterprise Guide

Installation Issues with Python

Dependency issues are the most common problem, so please make sure you have an updated version of Python 3 installed.

On Windows

C:\>pip3 --version

Validate WinPython is correctly installed by checking the installed version from launching the "WinPython Command Prompt" in the installation folder:

On Mac

MacOS ships with a default python installation that is too old and unsupported. A current version of Python needs to be installed

Depending on your operating system security settings you may need to "Allow" the application to run or install. To do this open "System Preferences" > "Security and Privacy" > "General" tab

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

$ pip3 --version

Don't run the below, it'll report the older version of python:

$  --version

Working with MS-DOS / Windows Paths

When using Commander in a Microsoft (Windows / DOS) environment, you may find it expedient to use its native filesystem path formatting (with backslashes) when referring to an external file in the context of a command call (e.g., when specifying a file in which to store the output of a command instead of printing it to the screen).

Please note that, in such cases, it is recommended that the file-path be wrapped in quotes (either single or double) in order for the command to be parsed correctly by Commander.

For example, let's say you'd like to run the list command and output the results (in CSV format) to C:\Users\user1\my_records.csv

The command in that case would be

list --format csv --output 'C:\Users\user1\my_records.csv'

Security Audit Report Score Re-alignment Process

Context

Due to Keeper's zero-trust and zero-knowledge encryption model, enterprise-level security audit reporting can sometimes result in vault-level security scores that are inconsistent with the corresponding vault's own security audit reporting. In most cases, correcting these mismatching scores can be done simply by having each vault owner log in to their account via the Web Vault app, without the need for any administrative action.

In the event that the above remedy does not result in re-aligned security scores, however, a security data sync can be performed manually via the following process:

The Process

As a Keeper administrator, log in to Commander and run the following:

security-audit sync --hard <USER_EMAIL_1> <USER_EMAIL_2> ... <USER_EMAIL_N> 

where <USER_EMAIL_1> ... <USER_EMAIL_N> are the emails associated with the vaults to be synced.

Alternatively, you can opt to initiate a sync for all vaults (instead of targeting them individually as in the example above) using the following command:

security-audit sync --hard @all

To complete the process, have the owner of each affected vault log in to their account using the latest version of Commander (installer available for download here under the "Assets" heading).

Please be aware that immediately following either of the command calls described above, you may see inaccurate security audit scores for the corresponding vaults.

This is temporary and will be corrected once each affected vault owner has logged in to their account via the Commander app.

SSL Certificate Errors

When running Commander or related Keeper SDK code, if you receive SSL certificate errors such as:

Certificate validation error. More info:

https://docs.keeper.io/secrets-manager/commander-cli/using-commander/troubleshooting-commander-cli#ssl-certificate-errors

or

requests.exceptions.SSLError: HTTPSConnectionPool(host='keepersecurity.com', port=443): Max retries exceeded with url: /api/rest/authentication/get_device_token (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)')))

If you receive this message, please make sure that your network is not attempting to do packet inspection with a proxy. Due to our advanced encryption, Keeper traffic cannot be intercepted by a network proxy device. Consult with your IT team to allow traffic to keepersecurity.[com|eu|com.au] on the firewall outbound.

Found a Bug?

Please let us know. Send an email to [e-mail] or open a ticket on our Github Repo.

Vulnerability Disclosure Program

Keeper has partnered with Bugcrowd to manage our vulnerability disclosure program. Please submit reports through https://bugcrowd.com/keepersecurity or send an email to [e-mail].