Conjur CLI

The Conjur CLI implements the Conjur REST API, providing an alternate interface for administering Conjur resources, including roles, privileges, policy, and secrets. You can start a CLI client session as a container local to the Conjur appliance, or remotely on a workstation.

CLI releases

The Conjur CLI is an open source tool that works for both Conjur Enterprise V5 and Conjur Open Source V1. We distribute the CLI as a containerized package on DockerHub and as a Ruby gem on GitHub. The same distribution works for both Conjur Enterprise V5 and Conjur Open Source V1. See the GitHub repo here.

 

CLI Release Train: 

Conjur CLI v6.x.x is the correct release train for Conjur Enterprise V5 and Conjur Open Source V1. To avoid confusion for Conjur Enterprise V5 users, the DockerHub label is conjur-cli:5. Be assured that it contains the latest released version from the CLI v6 release train.

Start a CLI container

This procedure pulls the latest CLI image from DockerHub, initializes to Conjur, and authenticates to Conjur.

  1. Create the CLI container:

     

    Attribute

    Description

    <folder-on-server>:\folder-in-container

    The -v option is required if you are planning to create or modify policy files; it is optional otherwise. Mapping a folder from your server into the container is required so that the files and any changes you make to them will persist after you close the CLI container.

     

    Do not confuse the concept of creating and editing policy files with the concepts of loading and updating policy into Conjur. Any policy that is successfully loaded into Conjur will persist in the database regardless of what happens to the policy files that were used to load the statements.

    <folder-on-server> is the persistent location of files, such as policy files.

     

    <folder-in-container> is the temporary mapping into the container.

    For example: 

    -v "$(pwd):/foo" maps your current folder to a folder named foo inside the container.

    <conjur-container-name>

    If local, use the container name of the Conjur appliance.

    If running the CLI client on another machine, this argument is not used.

    .

    For example:

     
    $ docker run --rm -it -v "$(pwd)/policy-files:/policy-files" --link conjur-appliance cyberark/conjur-cli:5

    or

     
    $ docker run --rm -it -v "$(pwd)/policy-files:/policy-files" cyberark/conjur-cli:5

    The example does the following:

  2. Starts a container, assigning it an arbitrary name.

  3. Removes the container when you exit the container.

  4. Creates an interactive Bash session within the container.

  5. Maps a folder named policy-files in your current directory $(pwd) to a folder named policy-files in the CLI container that is started.

  6. If running locally, connects the CLI container to the Conjur appliance. If running remotely, DNS will make the connection using the URL you supply in the conjur init command in the next step.

  7. Pulls the latest image from Dockerhub. This image can be used to connect to both Conjur Open Source V1 and Conjur Enterprise V5.

    If the command is successful, you are placed into the Bash session within the new container.

  8. Initialize to Conjur.

    1. At the Bash prompt, enter conjur init.

    2. Provide the URL of the Conjur appliance in the format https://<host-name>.

    3. Answer yes to the prompt about trusting the Conjur self-signed certificates.

    4. Enter the organizational account that was assigned to this Conjur appliance at installation.

    This command creates a self-signed certificate and writes files in your root directory. For example:

     
    # conjur init 
    Enter the URL of your Conjur service: https://conjur.node1.example
    
    SHA1 Fingerprint=FD:07:9C:79:B5:61:7C:B2:EB:E3:87:E8:5A:83:6F:3A:2F:C5:5E:06
    
    Please verify this certificate on the appliance using command:
                  openssl x509 -fingerprint -noout -in ~conjur/etc/ssl/conjur.pem
    
    Trust this certificate (yes/no): yes
    Enter your organization account name: demo
    Wrote certificate to /root/conjur-demo.pem
    Wrote configuration to /root/.conjurrc
    
  9. Authenticate to Conjur.

    1. Enter conjur authn login <user-name>.

      <user-name> must be a valid Conjur user name or the value admin.

    2. Enter the password at the prompt.

      An initial password was assigned to the admin user at installation. Recommended practice is to log in as admin immediately after installation and change the password. A user can change his own password only after logging in with the existing password, using conjur user update_password .

     
    # conjur authn login jane
    Please enter jane's password (it will not be echoed):
    Logged in
    #
    

Alternate ways to start a CLI container

The previous procedure is one way to create a CLI container that interacts with a Conjur appliance. Developers might modify this procedure for a production environment to create a customized optimal experience. For example:

  • The docker run command offers many options and flags that can enhance your user experience depending on your environment and goals.

  • This procedure starts a highly secure ephemeral container for the CLI that removes all files when it stops. See the CLI readme for a way to persist identity data so that subsequent sessions are quicker to start up.

  • If you have a Ruby environment, you may choose to install the Ruby gem. See the CLI readme.

Upgrades

After initial installation, use the CLI Changelog on GitHub to read about new CLI releases as they become available. The Changelog contains links to the distributions for each new release.

CLI help documentation

This section describes how to use and view the CLI help documentation.

Commands

For CLI documentation, use the command line help options:

To see a list of Conjur commands, enter conjur --help .

 
# conjur --help
NAME
    conjur - Command-line toolkit for managing roles, resources and privileges

SYNOPSIS
    conjur [global options] command [command options] [arguments...]

VERSION
    6.2.0

GLOBAL OPTIONS
    --help    - Show this message
    --version - Display the program version

COMMANDS
    authn       - Login and logout
    check       - Check for a privilege on a resource
    env         - Use values of Conjur variables in local context
    help        - Shows a list of commands or help for one command
    host        - Manage hosts
    hostfactory - Manage host factories
    init        - Initialize the Conjur configuration
    ldap-sync   - LDAP sync management commands
    list        - List objects
    plugin      - Manage plugins
    policy      - Manage policies
    pubkeys     - Public keys service operations
    resource    - Manage resources
    role        - Manage roles
    show        - Show an object
    user        - Manage users
    variable    - Manage variables

Sub-commands

To see a list of sub-commands:

 
# conjur <command> --help

For example, to see the sub commands under the user command:

 
# conjur user --help
NAME
    user - Manage users

SYNOPSIS
    conjur [global options] user rotate_api_key [--user arg|-u arg]
    conjur [global options] user update_password [-p arg|--password arg]

COMMANDS
    rotate_api_key  - Rotate a user's API key
    update_password - Update the password of the logged-in user

To see help on a specific sub-command:

 
# conjur <command> <subcommand> --help

For example, get syntax and options for the user list subcommand:

 
# conjur user update_password --help
NAME
    update_password - Update the password of the logged-in user

SYNOPSIS
    conjur [global options] user update_password [command options] 

COMMAND OPTIONS
    -p, --password=arg - Password to use, otherwise you will be prompted (default: none)

Troubleshooting

Before you run a CLI command, use RESTCLIENT_LOG=stderr conjur <command> to see a list of the API queries used by the CLI.

RestClient is a gem Conjur uses in the CLI to make REST API calls and it supports debug mode with the RESTCLIENT_LOG environment variable.

For example, to see the list of API queries used by authn login:

 
$ RESTCLIENT_LOG=stderr conjur authn login

This syntax sets the environment variable RESTCLIENT_LOG to the value of stderr for the specified command.

You can redirect the output to a file:

 
$ export RESTCLIENT_LOG=conjur.log

 

 
$ conjur show variable:vaultName/lob8/safe_0/obj_832/password
{
  "created_at": "2019-03-07T11:36:11.391+00:00",
  "id": "cucumber:variable:vaultName/lob8/safe_0/obj_832/password",
  "owner": "cucumber:policy:vaultName/lob8/safe_0",
  "policy": "cucumber:policy:vaultName/lob8/safe_0",
  "permissions": [
    {
      "privilege": "execute",
      "role": "cucumber:group:vaultName/lob8/safe_0/delegation/consumers",
      "policy": "cucumber:policy:vaultName/lob8/safe_0"
    },
    {
      "privilege": "read",
      "role": "cucumber:group:vaultName/lob8/safe_0/delegation/consumers",
      "policy": "cucumber:policy:vaultName/lob8/safe_0"
    }
  ],
  "annotations": [
    {
      "name": "cyberark-vault",
      "value": "true",
      "policy": "cucumber:policy:vaultName/lob8/safe_0"
    },
    {
      "name": "cyberark-vault/accounts",
      "value": "vaultName/safe_0/obj_832",
      "policy": "cucumber:policy:vaultName/lob8/safe_0"
    }
  ],
  "secrets": [
    {
      "version": 1,
      "expires_at": null
    },
    {
      "version": 2,
      "expires_at": null
    },
    {
      "version": 3,
      "expires_at": null
    },
    {
      "version": 4,
      "expires_at": null
    },
    {
      "version": 5,
      "expires_at": null
    },
    {
      "version": 6,
      "expires_at": null
    },
    {
      "version": 7,
      "expires_at": null
    }
  ]
}
$ conjur variable value vaultName/lob8/safe_0/obj_832/password
secret123
$ cat conjur.log
RestClient.post "https://cuke-master/authn/cucumber/admin/authenticate", "3j1aqpew0f2m02njp46c1pg0rft1j23r8a2zx878p3q5nb251njvkqh", "Accept"=>"*/*", "Accept-Encoding"=>"gzip, deflate", "Content-Length"=>"55", "Content-Type"=>"text/plain", "User-Agent"=>"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.4.1p111"
# => 200 OK | application/json 568 bytes
RestClient.get "https://cuke-master/resources/cucumber/variable/vaultName%2Flob8%2Fsafe_0%2Fobj_832%2Fpassword", "Accept"=>"*/*", "Accept-Encoding"=>"gzip, deflate", "Authorization"=>"Token token=\"eyJwcm90ZWN0ZWQiOiJleUpoYkdjaU9pSmpiMjVxZFhJdWIzSm5MM05zYjNOcGJHOHZkaklpTENKcmFXUWlPaUkxTldVNVptRTNaVE01TkRrNFl6SXlaV1JsTkRReFpEazJNR05qTVdZNFlpSjkiLCJwYXlsb2FkIjoiZXlKemRXSWlPaUpoWkcxcGJpSXNJbWxoZENJNk1UVTFNak15TVRFME9IMD0iLCJzaWduYXR1cmUiOiJFYTVncVdRSG03aE83aE00SzZKVlA3X1lPWFU0VV9Sd0t1SWE2Y0s2Y2w0VkRVTERPZFEzQlJIM0tKQzRmdW9VMTNfT21wYTEtY190TTJacXJETFFZSFc4MWpvTG55TWpGZGZUX09TU3d3dWlNRnNMeENwMzU0N3l4Vzd2QkpXMUZzS21OU2RyblI2MXc4Yk9MUTVNeVNGa3BzRjVqSU1sWDQxT1pQWmRzNnFhX19lUExpbWFIcl9mbHk2X0M0dkE0WVdVX0JMQlhXUVJsZjdJYTFNYVphd0s1OXY5N2xKbU1nWUtiMFlVSFp1aTU0RGRvTTM4ZVFLdXVaWWJYWkZJUzJjSTBXdWk0OGFkYXBGampUM29VMTloN1VLUGxMZXZoZmxDOTdyS1dlU01lUThaN2kxQ2luMWlGSmlCQk9BUERoVjREamIyQ2lKbEdxeU43UFZPNjBJeUYzRlVGeW80b183amtXVVVIX2s4MlB2WTB4cFBZeDJBcm5sTXN4R3MifQ==\"", "User-Agent"=>"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.4.1p111"
# => 200 OK | application/json 961 bytes
RestClient.post "https://cuke-master/authn/cucumber/admin/authenticate", "3j1aqpew0f2m02njp46c1pg0rft1j23r8a2zx878p3q5nb251njvkqh", "Accept"=>"*/*", "Accept-Encoding"=>"gzip, deflate", "Content-Length"=>"55", "Content-Type"=>"text/plain", "User-Agent"=>"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.4.1p111"
# => 200 OK | application/json 568 bytes
RestClient.get "https://cuke-master/secrets/cucumber/variable/vaultName%2Flob8%2Fsafe_0%2Fobj_832%2Fpassword/", "Accept"=>"*/*", "Accept-Encoding"=>"gzip, deflate", "Authorization"=>"Token token=\"eyJwcm90ZWN0ZWQiOiJleUpoYkdjaU9pSmpiMjVxZFhJdWIzSm5MM05zYjNOcGJHOHZkaklpTENKcmFXUWlPaUkxTldVNVptRTNaVE01TkRrNFl6SXlaV1JsTkRReFpEazJNR05qTVdZNFlpSjkiLCJwYXlsb2FkIjoiZXlKemRXSWlPaUpoWkcxcGJpSXNJbWxoZENJNk1UVTFNak15TVRFM00zMD0iLCJzaWduYXR1cmUiOiJlMGNmdkJpWVBxYUt1UVF1V05sU2tqSk9vYXVYMVhld05LbFpaSi1UU1hQdXdrdzZjZmp2Vjg5bXVNeEp6Mzczc3BEZWFrZGZia3dZS3gwdmNEdFJvYlJSOURrR2hTWFVkZ1M1Ny1xelVrYVFTZ0xSd2dqWGp2RWpTeXFvV3VPazdwQzktWGdOUlFMTHBrbEhSQllSUUFacUZTdk1hOHJWMnZWdkhGVDZzYTBHMEZ2VGROZlNKV0lqVkZ2S0NzMnNSOUstVUR4UU5JWTE0MFVpd1FHb3dUUHdKdW90eVRjYjhRNEVMUk5wUnotVnZpZ0R2QzNZcEpDSndiZEJtRmN2SE5xeXBOd3U0alRrbXdWTVYzWjJvZ096UHFmeG5za1FtSFVUa21YeVdfdlg4SzRkWHpfeW8zTDR0d1BxZy1Pcmg5d1RCbjVtNG43NlZNai04S1U5Zk52RXh4eXM4TlpoUWk5RnZCZnVZRUxYYlNfWFdON3M3dUdzTEVMZnBPbjIifQ==\"", "User-Agent"=>"rest-client/2.0.2 (linux-gnu x86_64) ruby/2.4.1p111"
# => 200 OK | application/octet-stream 9 bytes
 

This is raw protocol dump and can contain secrets, like the API key above. Use caution when using this DEBUGGING-only feature.

 
10.5