Configuring AnchoreCTL

The anchorectl command can be configured with command-line arguments, environment variables, and/or a configuration file. Typically, a configuration file should be created to set any static configuration parameters (your Anchore Enterprise’s URL, logging behavior, cataloger configurations, etc), so that invocations of the tool only require you to provide command-specific parameters as environment/cli options. However, to fully support stateless scripting, a configuration file is not strictly required (settings can be put in environment/cli options).

Important AnchoreCTL is version-aligned with Anchore Enterprise for major/minor. Please refer to the Enterprise Release Notes for the supported version of AnchoreCTL.

The anchorectl tool will search for an available configuration file using the following search order, until it finds a match:

1. .anchorectl.yaml
2. anchorectl.yaml
3. .anchorectl/config.yaml
4. ~/.anchorectl.yaml
5. ~/anchorectl.yaml
6. $XDG_CONFIG_HOME/anchorectl/config.yaml

Note The anchorectl can also utilize inline Environment Variables which override any configuration file settings.

For the most basic functional invocation of anchorectl, the only required parameters are listed below:

  url: ""        # the URL to the Anchore Enterprise API (env var: "ANCHORECTL_URL")
  username: ""   # the Anchore Enterprise username (env var: "ANCHORECTL_USERNAME")
  password: ""   # the Anchore Enterprise user's login password (env var: "ANCHORECTL_PASSWORD")

For example, with our Docker Compose quickstart deployment of Anchore Enterprise running on your local system, your ~/.anchorectl.yaml would look like the following

  url:      "http://localhost:8228"
  username: "admin"
  password: "yourstrongpassword"

A good way to quickly test that your anchorectl client is ready to use against a deployed and running Anchore Enterprise endpoint is to exercise the system status call, which will display status information fetched from your Enterprise deployment. With ~/.anchorectl.yaml installed and populated correctly, no environment or parameters are required:

anchorectl system status
 ✔ Status system
┌─────────────────┬────────────────────┬─────────────────────────────┬──────┬────────────────┬────────────┬──────────────┐
│ SERVICE         │ HOST ID            │ URL                         │ UP   │ STATUS MESSAGE │ DB VERSION │ CODE VERSION │
├─────────────────┼────────────────────┼─────────────────────────────┼──────┼────────────────┼────────────┼──────────────┤
│ analyzer        │ anchore-quickstart │ http://analyzer:8228        │ true │ available      │ 5110       │ 5.11.1       │
│ policy_engine   │ anchore-quickstart │ http://policy-engine:8228   │ true │ available      │ 5110       │ 5.11.1       │
│ apiext          │ anchore-quickstart │ http://api:8228             │ true │ available      │ 5110       │ 5.11.1       │
│ reports         │ anchore-quickstart │ http://reports:8228         │ true │ available      │ 5110       │ 5.11.1       │
│ reports_worker  │ anchore-quickstart │ http://reports-worker:8228  │ true │ available      │ 5110       │ 5.11.1       │
│ data_syncer     │ anchore-quickstart │ http://data-syncer:8228     │ true │ available      | 5110       │ 5.11.1       │
│ simplequeue     │ anchore-quickstart │ http://queue:8228           │ true │ available      │ 5110       │ 5.11.1       │
│ notifications   │ anchore-quickstart │ http://notifications:8228   │ true │ available      │ 5110       │ 5.11.1       │
│ catalog         │ anchore-quickstart │ http://catalog:8228         │ true │ available      │ 5110       │ 5.11.1       │
└─────────────────┴────────────────────┴─────────────────────────────┴──────┴────────────────┴────────────┴──────────────┘

Congratulations you should now have a working AnchoreCTL.

Using Environment Variables

For some use cases being able to supply inline environment variables can be useful, see the following system status call as an example.

ANCHORECTL_URL="http://localhost:8228" ANCHORECTL_USERNAME="admin" ANCHORECTL_PASSWORD="foobar" anchorectl system status
 ✔ Status system
┌─────────────────┬────────────────────┬─────────────────────────────┬──────┬────────────────┬────────────┬──────────────┐
│ SERVICE         │ HOST ID            │ URL                         │ UP   │ STATUS MESSAGE │ DB VERSION │ CODE VERSION │
├─────────────────┼────────────────────┼─────────────────────────────┼──────┼────────────────┼────────────┼──────────────┤
│ reports         │ anchore-quickstart │ http://reports:8228         │ true │ available      │ 5110        │ 5.11.1        │
│ analyzer        │ anchore-quickstart │ http://analyzer:8228        │ true │ available      │ 5110        │ 5.11.1        │
│ notifications   │ anchore-quickstart │ http://notifications:8228   │ true │ available      │ 5110        │ 5.11.1        │
│ apiext          │ anchore-quickstart │ http://api:8228             │ true │ available      │ 5110        │ 5.11.1        │
│ policy_engine   │ anchore-quickstart │ http://policy-engine:8228   │ true │ available      │ 5110        │ 5.11.1        │
│ reports_worker  │ anchore-quickstart │ http://reports-worker:8228  │ true │ available      │ 5110        │ 5.11.1        │
│ simplequeue     │ anchore-quickstart │ http://queue:8228           │ true │ available      │ 5110        │ 5.11.1        │
│ catalog         │ anchore-quickstart │ http://catalog:8228         │ true │ available      │ 5110        │ 5.11.1        │
└─────────────────┴────────────────────┴─────────────────────────────┴──────┴────────────────┴────────────┴──────────────┘

All the environment variable options can be seen by using anchorectl --help

Using API Keys

If you do not want to expose your private credentials in the configuration file, you can generate an API Key that allows most of the functionality of anchorectl. Please see Generating API Keys

Once you generate the API Key, the UI will give you a key value. You can use this key with the anchorectl configuration:

  url: "http://localhost:8228"
  username: "_api_key"
  password: <API Key Value>

NOTE: API Keys authenticate using HTTP basic auth. The username for API keys has to be _api_key.

Without setting up ~/.anchorectl.yaml or any configuration file, you can interact using environment variables:

Using Distributed Analysis Mode

If you intend to use anchorectl in Distributed Analysis mode, then you’ll need to enable two additional catalogers (secret-search, and file-contents) to mirror the behavior of Anchore Enterprise defaults, when performing an image analysis in Centralized Analysis mode. Below are the ~/.anchorectl.yaml settings to mirror the Anchore Enterprise defaults.

  secret-search:
    cataloger:
      enabled: true
      scope: Squashed
    additional-patterns: {}
    exclude-pattern-names: []
    reveal-values: false
    skip-files-above-size: 10000
  content-search:
    cataloger:
      enabled: false
      scope: Squashed
    patterns: {}
    reveal-values: false
    skip-files-above-size: 10000
  file-contents:
    cataloger:
      enabled: true
      scope: Squashed
    skip-files-above-size: 1048576
    globs: ['/etc/passwd']

For more information on using anchorectl in Distributed Analysis mode, see Concepts: Image Analysis and AnchoreCTL Usage: Images.

Using AnchoreCTL Help & Debug Modes

The anchorectl tool has extensive built-in help information for each command and operation, with many of the parameters allowing for environment overrides. To start with anchorectl, you can run the command with --help to see all the operation sections available:

anchorectl --help

A convenient way to see your changes taking effect is to instruct anchorectl to output DEBUG level logs to the screen using the -vv flag, which will display the full configuration that the tool is using (including the options you set, plus all the defaults and additional configuration file options available).

anchorectl --vv

NOTE: if you would like to capture the full default configuration as displayed when running with -vv, you can paste that output as the contents of your .anchorectl.yaml, and then work with the settings for full control.

If you need any more help, please learn about Verifying Service Health