Host-Factory new CLI command

[szamir1]

Feature Overview & Customer Need

As a Conjur user I would like to use the Conjur cli In order to automatically creates hosts and enrolls them into one or more layers.

Overview

The host-factory feature enables the user to create hosts and grant them permissions in a dynamic way. Each host will be created using the token (which is common for all creations), each host still has a dedicated API key for fetching secrets. For more information on Host-factory see here and here.

Process logic and requirements

User flow

1. Conjur user with a machine that the Python CLI already been installed and conjur init & login run against a Conjur/ Conjur Enterprise machine.
2. User created and loaded a hostfactory policy with the relevant ID and layers.

- !host-factory 
id: <name> 
owner: !<kind-of-role> <role-name> 
layers: [ !layer <layer-name>, ... ] 
annotations:
    <key>: <value>

3. The user creates hostfactory token by demand.
4. The user can create hosts using the returned token.

Commands Logic and UX

A new command will be called hostfactory. It will be used to create and manage host factories services. We will also use sub commands, as described below.

Usage Conjur [global options] hostfactory [sub command]

Subcommands token create - creates one or more identical tokens token revoke - revoke multiple tokens at the same time host create- creates host with a token

Common Options -h, --help - Display help screen and exit

Tokens

Create token/s for hosts with restrictions

This command creates one or more identical tokens. A token is always created with an expiration time, which by default is 1 hour from now. The expiration time can be customised with command arguments specifying the number of minutes, hours, days for which the token will be valid. By default, this command creates one token. Optionally, it can be used to create multiple identical tokens.

conjur [global options] hostfactory token create --hostfactoryid <HostFactory ID> --cidr <CIDR>
--duration-days <Duration In Days> --duration-hours <Duration In Hours> --duration-minutes <Duration In minutes>

Args description: --hostfactoryid , -id- (Mandatory) the ID of the host factory you would like to work with. This parameter is mandatory, so we need to prompt a message/error if it's missing. --cidr - (Optional) the CIDR address that contains all IPs that can use this token to create hosts. --duration-days , -dd - (Optional) the number of days the token will be valid. --duration-hours -dh - (Optional) the number of hours the token will be valid. --duration-minutes, -dm- (Optional) the number of minutes the token will be valid.

• The durations can be defined all together, for example 1 day, 1 hour and 5 minutes,

For example conjur hostfactory token create --hostfactoryid Sap_factory --cidr 10.10.1.2/31 --dd 2

Output should be

[
  {
    "token": "3csgc7v36f7aq81j6q78r3wr375b1c2ehpe3tzq9ht2ywt9j4jz6zt2",
    "expiration": "2021-05-01T14:20:00+00:00",
    "cidr": [
      "10.10.1.2/31"
    ]
  }
]

If the restriction must be left but no content has been entered

[
  {
    "token": "3csgc7v36f7aq81j6q78r3wr375b1c2ehpe3tzq9ht2ywt9j4jz6zt2",
    "expiration": "not set",
    "cidr": [
      "not set"
    ]
  }

Revoke (delete) existing tokens

The user can revoke multiple tokens at the same time

conjur [global options] hostfactory token revoke --token <TOKEN> OR conjur [global options] hostfactory token revoke --token <TOKEN1>,<TOKEN2>,<TOKEN3> ..

Args description: --token, -t - (Mandatory) the token itself

For example conjur hostfactory tokens revoke --token "3csgc7v36f7aq81j6q78r3wr375b1c2ehpe3tzq9ht2ywt9j4jz6zt2" returned result today Token revoked

We want to add the token value to the output:

1. When the token has bees revoked the output should be: token “123456789” revoked successfully
2. If several tokens have been removed, the following output:

token “123456789” revoked successfully
token “123456789” revoked successfully
token “123456789” revoked successfully
token “123456789” failed revoked

Hosts

create - Use a token to create a host

conjur [global options] hostfactory host create -i <HOST_ID> -t <TOKEN>

Options -i, --id - (Mandatory) the host ID you wish to create -t, --token - (Mandatory) the token itself

for example conjur hostfactory host create -i sapir -t "6pv3409nr1gd10f4w9g1wz28vw3zjkgpz193b1eq249aypq1qffz5x" should output:

{
  "created_at": "2021-04-29T14:50:20.527+00:00",
  "id": "SapirDAP:host:sapir",
  "owner": "SapirDAP:host_factory:Sap_factory",
  "permissions": [

  ],
  "annotations": [

  ],
  "restricted_to": [

  ],
  "api_key": "4rxwt41jvq09b1exs80h16kfbr7asfgdk105zpa2w7vz662abyfsn"
}

Open questions - out of scope for this feature

- do we want hostfactory to be created for Conjur authenticators? - as a Conjur user, I want to be able to create multiple hosts for different authenticators I have, similar to what we have for regular hosts. - do we want hosts to be also managed dynamically and not only created dynamically, for example deletion or creating them with restrictions? - do we want the CLI to be interactive? - I don't think so, just verifying.

Failure scenarios

1. If a mandatory argument is missing we need to return that the command failed, and the help of the command

2. If the host-id given already exists, should return proper log message. Failed to create hostfactory. ID already exist

3. If a user tries to create a host with a token which he doesn't have the right permissions for (for example not the granted IP address or tried to use it when it was already revoked/does not exist) we need to prevent the host from being created with a proper error (today "Unable to authenticate with Conjur. Please check your credentials.")

4. Is there a minimum of characters or invalid characters when naming a hostfactory? If so, we need to enforce that too.

5. Duration parameter invalid – duration must be set as positive number/0. if duration is set to negative number we should fail the command.

6. In revoke tokens command - if the token doesn't exist, we should not perform any action and fail the command and print 'Token does not exist/was already revoked'.

User messages

All user messages regarding hostfactory actions should be reviewed

Mock and command matrix

Expected behavior should not change from the corresponding command in Ruby CLI

Command matrix - https://z0slp2.axshare.com/#id=c63xjv&p=commands_matrix___rules Help is according to -

Quality

• Make sure we have test coverage of the host-factory command.
• Create test plan and execute accordingly.

Documentation

Please provide enhance documentation in online help and readme. We also need to add to the host-factory docs a link on how to create the hostfactory policy, as this is a mandatory step before running the host-factory token/host creation.
And how to create the host afterwards with examples.

Demo

Demo each option that was implemented:

• Show that the host factory was created and returned the token which will be used to create the other hosts.
• Show that the host factory was created and returned the token with the relevant restrictions -
  • CIDR
  • Duration in days, hours, minutes
• Show the token expired according to restrictions and other hosts can't be created with it anymore/login with it anymore
• Show added user messages/errors

DOD

• [ ] Implement the host-factory commands Conjur Python CLI in all 3 platforms
• [ ] Demo the flow described above
• [ ] Automatic integration tests written according to a test plan and passed successfully
• [ ] Fill in the user messages - link to a page with all user messages for CLI saved and reviewed.
• [ ] Fill in the logs and place here a link to the logs files - link to a page with all logs for CLI saved and reviewed.
• [ ] Logs were reviewed by TW and PO
• [ ] Are there new Audits to this feature? If so please document them and provide here a link (N/A)