> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# anchore/anchore-engine

Anchore Engine is a docker container static analysis and policy-based compliance tool that
automates the inspection, analysis, and evaluation of images to allow high confidence in
container deployments by ensuring workload content meets the required criteria.


## Commands

### add_private_registry

Adds credentials for private registries to anchore engine.
Set registry credentials with $DOCKER_USER & $DOCKER_PASS env vars.
Must run on executor with anchore-engine running & anchore-cli installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `registry_name` | string | docker.io | Name of private registry (eg - docker.io). |
| `registry_pass` | string | $DOCKER_PASS | Password for private registry (use env var to populate). |
| `registry_user` | string | $DOCKER_USER | Username for private registry (use env var to populate). |

### analyze_image

Add image to anchore engine and start analyzing.
image_name is required, timeout is optional.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image_name` | string |  | Image repository & tag (eg - "docker.io/anchore/anchore-engine:latest"). |
| `timeout` | string | 300 | Timeout used for Anchore Engine image scanning. |

### analyze_local_image

Pushes a local image to a temporary registry container.
Image is then scanned with anchore engine. Stores all reports as artifacts.
Must be run in job with setup_remote_docker & using an image with docker installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `anchore_version` | string | $ANCHORE_VERSION | Version of anchore inline-scan image. |
| `dockerfile_path` | string |  | Path to dockerfile used to build image |
| `image_name` | string |  | Image repository & tag (eg - "docker.io/anchore/anchore-engine:latest"). |
| `policy_bundle_file_path` | string | ${HOME}/project/.circleci/.anchore/policy_bundle.json | Specify file path to policy bundle. |
| `policy_failure` | boolean | false | Set to True if pipeline should stop on policy evaluation status 'fail'. |
| `timeout` | string | 300 | Timeout used for Anchore Engine image scanning. |

### parse_reports

Prints analysis report of package vulnerabilities using JQ.

### policy_evaluation

Perform policy evaluation using Anchore Engine image analysis. A customized policy bundle can be utilized for evaluation.
Custom policy bundles should be added to your repository at .circleci/.anchore/policy_bundle.json. If using multiple policy
bundles, or if using executor other than anchore/anchore_engine a custom policy bundle path can be set as a parameter.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image_name` | string |  | Image repository & tag (eg - "docker.io/anchore/anchore-engine:latest"). |
| `policy_bundle_file_path` | string | ${HOME}/project/.circleci/.anchore/policy_bundle.json | Specify file path to policy bundle. |
| `policy_failure` | boolean | false | Set to True if pipeline should stop on policy evaluation status 'fail'. |

### start_engine

Start & wait for Anchore Engine

| Parameter | Type | Default | Description |
|---|---|---|---|
| `anchore_version` | string | $ANCHORE_VERSION | Version of anchore inline-scan image. |
| `timeout` | string | 300 | Timeout used for Anchore Engine image scanning. |

## Jobs

### image_scan

Performs a static security analysis of docker container with anchore engine.
A custom policy can be used for evaluation, add custom Anchore policy bundle
to .circleci/.anchore/policy_bundle.json in your repository. Anchore engine pulls
image from public/private docker registries. Requires registry credentials
to access private images, use ENV vars $DOCKER_USER & $DOCKER_PASS


| Parameter | Type | Default | Description |
|---|---|---|---|
| `after_analyze` | steps |  | Optional steps to run after analyzing the docker image. |
| `after_checkout` | steps |  | Optional steps to run after checking out the code. |
| `before_analyze` | steps |  | Optional steps to run before analyzing the docker image. |
| `image_name` | string |  | Image repository & tag (eg - docker.io/anchore/anchore-engine:latest). |
| `policy_bundle_file_path` | string | ${HOME}/project/.circleci/.anchore/policy_bundle.json | Specify file path to policy bundle. |
| `policy_failure` | boolean | false | Set to True if pipeline should stop on policy evaluation status 'fail'. |
| `private_registry` | boolean | false | Set to True if image is only accessible from a private registry. |
| `registry_name` | string | docker.io | Name of private registry (eg - docker.io) |
| `registry_pass` | string | $DOCKER_PASS | Password for private registry (use env var $DOCKER_PASS to populate). |
| `registry_user` | string | $DOCKER_USER | Username for private registry (use env var $DOCKER_USER to populate). |
| `timeout` | string | 300 | Timeout used for Anchore Engine image scanning. |

## Executors

### anchore_engine

Docker stable image with ANCHORE_VERSION environment variable set.


## Examples

### local_image_scan

Use the analyze_local_image command within a container build pipeline,
it can be used to scan an image that hasn't been pushed to a registry yet.
If Anchore policy evaluation gives 'fail' status, the CI job will be marked
as a failure. A custom policy can be used for evaluation, add custom Anchore
policy bundle to .circleci/.anchore/policy_bundle.json in your repository.
The Dockerfile used for building your image can be passed for policy evaluation.


```yaml
jobs:
  local_image_scan:
    executor: anchore/anchore_engine
    steps:
      - setup_remote_docker
      - checkout
      - run:
          command: docker build -t "example/test:latest" .
          name: build container
      - anchore/analyze_local_image:
          dockerfile_path: ./Dockerfile
          image_name: example/test:latest
          policy_bundle_file_path: .circleci/.anchore/policy_bundle.json
          policy_failure: true
          timeout: '500'
      - anchore/parse_reports
      - store_artifacts:
          path: anchore-reports
orbs:
  anchore: anchore/anchore-engine@1
version: 2.1
```

### multiple_local_image_scan

Use the analyze_local_image command within a container build pipeline,
it can be used to scan multiple images that haven't been pushed to a registry yet.
If Anchore policy evaluation gives 'fail' status, the CI job will be marked
as a failure. A custom policy can be used for evaluation, add custom Anchore
policy bundle to .circleci/.anchore/policy_bundle.json in your repository.
Scanning multiple images does not support passing a dockerfile.


```yaml
jobs:
  local_image_scan:
    executor: anchore/anchore_engine
    steps:
      - setup_remote_docker
      - checkout
      - run:
          command: |
            docker build -t "example/test:dev" dev/
            docker build -t "example/test:staging" staging/
            docker build -t "example/test:latest" prod/
          name: build containers
      - anchore/analyze_local_image:
          image_name: example/test:dev example/test:staging example/test:latest
          policy_bundle_file_path: .circleci/.anchore/policy_bundle.json
          policy_failure: true
          timeout: '500'
      - anchore/parse_reports
      - store_artifacts:
          path: anchore-reports
orbs:
  anchore: anchore/anchore-engine@1
version: 2.1
```

### private_image_scan

Use this job to scan an image located in a private registry. A custom
policy can be used for evaluation, add custom Anchore policy bundle to
.circleci/.anchore/policy_bundle.json in your repository.


```yaml
orbs:
  anchore: anchore/anchore-engine@1
version: 2.1
workflows:
  scan_image:
    jobs:
      - anchore/image_scan:
          image_name: docker.io/anchore/anchore-engine:latest
          private_registry: true
          registry_name: docker.io
          registry_pass: $DOCKER_PASS
          registry_user: $DOCKER_USER
```

### standard_image_scan

Use this job to scan an image located in a public registry. A custom
policy can be used for evaluation, add custom Anchore policy bundle to
.circleci/.anchore/policy_bundle.json in your repository.


```yaml
orbs:
  anchore: anchore/anchore-engine@1
version: 2.1
workflows:
  scan_image:
    jobs:
      - anchore/image_scan:
          image_name: docker.io/anchore/anchore-engine:latest
          policy_bundle_file_path: .circleci/.anchore/policy_bundle.json
          timeout: '300'
```