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).

In this document, we focus on the anchorectl configuration file setup and options.

API Version Compatibility

It is highly recommended that the version of AnchoreCTL you are using is supported by the deployed version of Enterprise. Please refer to the Enterprise Release Notes for the supported version of AnchoreCTL.

The release of Anchore Enterprise v4.9.x, contains both the deprecated V1 API and the new V2 API.

  • AnchoreCTL v1.8.0 is compatible with the Anchore Enterprise v4.9.x V1 API.
  • AnchoreCTL v4.9.0 is compatible with the Anchore Enterprise v4.9.x V2 API.

Anchore Enterprise v5.x Releases, contain only the new V2 API.

  • AnchoreCTL v5.5.0 is compatible with the Anchore Enterprise v5.5.1 V2 API.

In AnchoreCTL v1.8.0, a version check was introduced to prevent accidental use of AnchoreCTL v1.8.x with an incompatible API endpoint. If the check fails but you are sure that the configured URL you have set is a V1 API endpoint, you can bypass the check by setting the skip-api-version-check field in the configuration to boolean true as in th example below.

url: "http://localhost:8228"
username: "admin"
password: "foobar"
skip-api-version-check: true
...

This can also be done with the environment variable: ANCHORECTL_SKIP_API_VERSION_CHECK=true

Config File Search Locations

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

.anchorectl.yaml, anchorectl.yaml, .anchorectl/config.yaml, ~/.anchorectl.yaml, ~/anchorectl.yaml, $XDG_CONFIG_HOME/anchorectl/config.yaml

Generating Your First .anchorectl.yaml

For the most basic functional invocation of anchorectl, the only parameters that should be set are listed here:

  # the URL to the Anchore Enterprise API (env var: "ANCHORECTL_URL")
  url: ""

  # the Anchore Enterprise username (env var: "ANCHORECTL_USERNAME")
  username: ""

  # the Anchore Enterprise user's login password (env var: "ANCHORECTL_PASSWORD")
  password: ""

For example, with a quickstart deployment of Anchore Enterprise running on your local system:

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

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.

AnchoreCTL Debug

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
[0000]  INFO anchorectl version: 1.6.0
[0000] DEBUG application config:
  url: http://localhost:8228
  username: admin
  password: '******'
  account: ""
  skip-api-version-check: false
  config: /your/homedir/.anchorectl.yaml
  update:
    check: true
    url: https://anchorectl-releases.anchore.io/anchorectl/releases/latest/metadata.json
  quiet: false
  log:
    level: debug
    file: ""
  debug:
    api: false
    events: false
  http:
    tls-insecure: false
    timeout: 180
    headers: {}
  dev:
    profile-cpu: false
    profile-mem: false
  registry:
    insecure-skip-tls-verify: false
    insecure-use-http: false
    auth: []
  secret-search:
    cataloger:
      enabled: false
      scope: AllLayers
    additional-patterns: {}
    exclude-pattern-names: []
    reveal-values: false
    skip-files-above-size: 1048576
  content-search:
    cataloger:
      enabled: false
      scope: AllLayers
    patterns: {}
    reveal-values: false
    skip-files-above-size: 1048576
  file-contents:
    cataloger:
      enabled: false
      scope: Squashed
    skip-files-above-size: 1048576
    globs: []

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.

Once you verify that your baseline configuration parameters are set, the tools is correctly consuming them, we recommend a quick test to confirm that your enterprise deployment is accessible and the tool is ready to go:

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

Configuring Catalogers for 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 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.

Last modified April 4, 2024