AutoPatcher Command line interface

AutoPatcher CLI uses the authenticaton provided by the Auth0 service. When you use the CLI for the first time it will open the web page with the login form. You have to log in using your business (@nordcloud.com) email. If you do not have permissions to use the CLI please ask on the #pat-autopatcher slack channel

Installation

Download the latest version (v1.135.0) of nc-autopatcher-cli for your platform and architecture:

For Linux and MacOS:

2.1. cp /path/to/downloaded/nc-autopatcher-cli-{VERSION}-{PLATFORM}-prod-{ARCH} ~/.local/bin/nc-autopatcher-cli

2.2. chmod +x ~/.local/bin/nc-autopatcher-cli

Configuration

Run the following command to configure the CLI for the usage with your customer environment:

nc-autopatcher-cli configure

The list of all available customers (with auto-completion capability) will be shown.

For more advanced configuration see Advanced configuration.

Usage

nc-autopatcher-cli COMMAND SUBCOMMAND [FLAGS]

COMMANDs are divided into three categories:

Commands for general API items access
Resource-specific commands
Other commands

General API items access

get ITEM - Get one item
list ITEMs - Get all items of some type (note the plural form of ITEMs)
create ITEM - Create an item
update ITEM - Update an items
delete ITEM - Delete an item

An ITEM can be one of:

machine
event
plan
pipeline
notification_group
update_log

Please note that not all general API item access commands can be used with all item types. Refer to the corresponding command's help to see valid combinations.

get, update and delete require an ID of the item to be passed through --id flag.

update and create commands require --file flag which defines a JSON file with data to populate an item with.

Examples:

nc-autopatcher-cli get event --id 43e60f1e-50c2-468f-afc0-bcdcedf26faa. Example output:

{
    "created_at": "2018-12-08T00:07:39+00:00",
    "description": "description",
    "hash": "74f5a89d-3003-4b45-b7ca-63dfc0ccb7a7",
    "id": "43e60f1e-50c2-468f-afc0-bcdcedf26faa",
    "machines": [],
    "name": "NAME-1",
    "customer_id": "1234",
    "parallel": 1,
    "patching_status": "DONE",
    "plan_id": "plan_with_spaces_1",
    "updated_at": "2018-12-08T00:07:39+00:00",
    "window_end_time": "2018-12-08T02:07:39+00:00",
    "window_start_time": "2018-12-08T00:07:39+00:00"
}

nc-autopatcher-cli list machines. Example output:

[
    {
        "access": {
            "ssm_machine_id": "mi-111111"
        },
        "allow_reboot": true,
        "created_at": "2018-12-07T10:47:27+00:00",
        "id": "m1",
        "name": "name",
        "customer_id": "1234",
        "plans": [],
        "updated_at": "2018-12-07T10:47:27+00:00"
    }
]

nc-autopatcher-cli create plan --file plan.json. Example output:

{
    "id": "67042200-46ae-4d8a-a8de-e7666ceb5c53"
}

plan.json contents:

{
    "customer_id": "1234",
    "name": "NAME",
    "description": "description",
    "cron_window_start": "0 3 * * *",
    "cron_window_end": "0 4 * * *",
    "parallel": 1,
    "machines": [
        {
            "id": "m1",
            "order": 3
        }
    ]
}

Resource-specific commands

event SUBCOMMAND
plan SUBCOMMAND
pipeline SUBCOMMAND

Each resource-specific command has different set of SUBCOMMANDs. Refer to the help for each command for details.

Examples:

nc-autopatcher-cli plan force_update --id 67042200-46ae-4d8a-a8de-e7666ceb5c53. Example output:
```
{
    "id": "dbbacd79-43b7-464e-801b-bf68e419aede"
}
```

nc-autopatcher-cli event generate_report --id 00b3d2d9-2086-45ac-9809-866cb8a21da1. Example output:

{
    "message": "Successfully started report generation.",
    "report_id": "00b3d2d9-2086-45ac-9809-866cb8a21da1"
}

nc-autopatcher-cli event get_report --id 00b3d2d9-2086-45ac-9809-866cb8a21da1. Example output:

{
    "id": "00b3d2d9-2086-45ac-9809-866cb8a21da1",
    "name": "NAME",
    "not_patched_machines": {},
    "patched_machines": {
        "m2": {
            "installed": [],
            "removed": [],
            "status": "Success",
            "updated": [
                "python3-software-properties_0.96.24.32.6_all.deb",
                "python3-update-manager_1%3a18.04.11.8_all.deb",
                "software-properties-common_0.96.24.32.6_all.deb",
                "update-manager-core_1%3a18.04.11.8_all.deb"
            ]
        }
    },
    "patching_status": "DONE",
    "plan_id": "67042200-46ae-4d8a-a8de-e7666ceb5c53",
    "window_end_time": "2018-12-12T04:00:00+00:00",
    "window_start_time": "2018-12-12T03:00:00+00:00"
}

Complex use-cases

Defining a dynamic plan

In order to define scanning conditions more granularly for a dynamic plan, the user needs to define the tag_condition field in the dynamic plan instead of the legacy tag_list. Below is an example of how to define a sample plan which will patch the machines which have both autopatcher-enable=true and patching-stage=dev-1 (or patching-stage=dev-2) tags attached:

Create a file named plan.json with the following content (when using this JSON payload for a real use-case please make sure to review all the fields carefully as this is just a sample):

{
  "cron_window_start": "0 0 31 2 *",
  "window_length": 2,
  "name": "Example dynamic plan",
  "machines_tag": {
    "iam_role_list": ["arn:aws:iam::000000000000:role/NordcloudAutoPatcherSSMServiceRole"],
    "regions": ["eu-west-1"],
    "tag_condition": {
      "expression": "autopatcher-enable=true AND patching-stage=dev-1,dev-2"
    }
  }
}

Run the following CLI command (for instructions on how to download and prepare the CLI for usage please visit this page):

nc-autopatcher-cli create plan --file plan.json

When the AWS account being scanned contains the following EC2 instances

Name	Tags
machine-1	`autopatcher-enable` = `true` `patching-stage` = `dev-1`
machine-2	`autopatcher-enable` = `true` `patching-stage` = `dev-2`
machine-3	`autopatcher-enable` = `true`
machine-4	`patching-stage` = `dev-1`
machine-5	`patching-stage` = `dev-2`
machine-6	`patching-stage` = `QA`
machine-7	`patching-stage` = `Production` `autopatcher-enable` = `true`
machine-8	`patching-stage` = `Production`

only machine-1 and machine-2 will be patched accordingly to the defined logical expression.

Detailed description of the `tag_condition` structure

The tag_condition structure in the machines_tag has two fields:

expression [REQUIRED] - a logical expression defining tag keys and values that the scanned machines should have. The case-insensitive AND, OR and NOT operators (and their respective short forms &, | and !) are allowed as well as arbitrary levels of parentheses. Each tag definition should have the <KEY>=<VALUES_LIST> form (note that the = character cannot be surrounded with white space). <KEY> is a single token whereas <VALUES_LIST> is a comma-separated list of tokens. Each token can consist of alphanumeric and _ (underscore), - (hyphen), . (period), : (colon) characters only.
placeholders [OPTIONAL] - if there is a need to specify a tag key or value with unsupported characters a special placeholder token (starting with a colon (:)) can be used. The values of all placeholders used in the expression should be defined in the placeholders field, otherwise an error will occur.

Example tag condition with placeholders:

{
  "tag_condition": {
    "expression": "key1=group-a AND (key2=:v1 OR !:k3=:v2,v4,:v5)",
    "placeholders": [
      {"key": "v1", "value": "tag value with spaces"},
      {"key": "k3", "value": "key -%^&"},
      {"key": "v2", "value": "special chars !@#$%^&*()"},
      {"key": "v5", "value": "a b c"}
    ]
  }
}

Other commands

Configure

nc-autopatcher-cli configure

This command is used to fill in the configuration file for the AutoPatcher CLI with values obtained by asking the user interactively.

Bash completion

. <(nc-autopatcher-cli bash_completion)

The above command sets up the current Bash session to be able to TAB-complete nc-autopatcher-cli commands. It can be added to ~/.bashrc to be available in each shell session automatically.

Help command

nc-autopatcher-cli help [COMMAND [SUBCOMMAND]]

Prints help about some command and its subcommands or, if the command is omitted, general usage.

Advanced configuration

There are several global configuration options available:

customer-id required - An ID of the customer with whose resources you will be working
api-host required - AutoPatcher GraphQL API endpoint
oauth-domain required - Address of the Auth0 login domain used for the authentication
oauth-client-id required - Id of the Auth0 clitn used for the authentication
api-key optional - API key used for alternative authentication, takes precedence over Auth0

Below are the three different ways of configuring the CLI

1. Configuration file

Configuration file is in YAML format with options defined as top-level keys. Example:

api-host:
  "https://api.autopatcher.nordcloudapp.com"
oauth-client-id:
  "4BgImeXVBzK2fqNxig6bh1xfxE4Fy9C1"
oauth-domain:
  "login.nordcloudapp.com"

Default config file location is $HOME/.nc-autopatcher-cli.yml.

Custom config file can be specified with --config flag:

nc-autopatcher-cli --config FILE [commands] ...

2. Environment variables (take precedence over config file)

Option	Environment variable
`api-host`	`AP_API_HOST`
`oauth-client-id`	`AP_OAUTH_CLIENT_ID`
`oauth-domain`	`AP_OAUTH_DOMAIN`
`customer-id`	`AP_CUSTOMER_ID`

3. Command line flags (take precedence over config file and environment variables)

In order to pass custom value for a configuration option on command line add a flag named as the option with two dashes prepended

Example:

nc-autopatcher-cli --api-host <CUSTOM_HOST> [COMMANDS] ...

AutoPatcher Command line interface

.css-1r0pe6c{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1r0pe6c:hover{-webkit-text-decoration:underline;text-decoration:underline;}Installation

Installation