bif

README

BIF - The Fairwinds Base Image Finder Client

This utility interacts with the Fairwinds BIF-Server to find base images and report on their vulnerabilities.

What and Why is it?

When using a container scanning tool to identify known vulnerabilities (CVEs, or common vulnerabilities and exposures), it can be difficult to understand where the vulnerabilities exist in the container, and how to mitigate them. Often, the simplest and most efficient mitigation is to update the "base image" - or the image used in the FROM statement in your container definition.

BIF allows you to understand the impact of updating the base image of your container will have:

• First, it can detect what base image the container is using, even though it doesn't have access to the Dockerfile.
• Second, it will show you what vulnerabilities are present in that base image.
• Lastly, it will show you what versions of that base image don't have that vulnerability.

Installation

Download the latest binary from the releases page

Usage

Request a Token

First, you must request an API token to use with the base image finder. You can do this via the cli:

bif request-token
# Follow the prompt to enter your email address

You will receive your token via email. To automatically have BIF use this token, export it as INSIGHTS_OSS_TOKEN in your environment.

Extract Layers Using Skopeo and Find Base Image

bif find --image-layers $(skopeo inspect docker://us-docker.pkg.dev/fairwinds-ops/oss/polaris:7.0.0 | jq .Layers[] -rc)

Input:  [sha256:2408cc74d12b6cd092bb8b516ba7d5e290f485d3eb9672efc00f0583730179e8]

   BASE IMAGE   | LAST SCAN  |      CVE       | SEVERITY | CVSS |    FIXED IN
----------------+------------+----------------+----------+------+-----------------
  alpine:3.16.0 | 2023-02-28 | CVE-2022-2097  | MEDIUM   | 5.30 | 3.17.3, 3.16.5
                |            | CVE-2022-30065 | HIGH     | 7.80 | 3.17.3, 3.16.5
                |            | CVE-2022-37434 | CRITICAL | 9.80 | 3.17.3, 3.16.5
                |            | CVE-2022-4304  | MEDIUM   | 5.90 | 3.17.3, 3.16.5
                |            | CVE-2022-4450  | HIGH     | 7.50 | 3.17.3, 3.16.5
                |            | CVE-2023-0215  | HIGH     | 7.50 | 3.17.3, 3.16.5
                |            | CVE-2023-0286  | HIGH     | 7.40 | 3.17.3, 3.16.5

Use BIF with a publicly-available image

bif find --image us-docker.pkg.dev/fairwinds-ops/oss/polaris:7.0.0

Input: us-docker.pkg.dev/fairwinds-ops/oss/polaris 7.0.0

   BASE IMAGE   | LAST SCAN  |      CVE       | SEVERITY | CVSS |    FIXED IN
----------------+------------+----------------+----------+------+-----------------
  alpine:3.16.0 | 2023-02-28 | CVE-2022-2097  | MEDIUM   | 5.30 | 3.17.3, 3.16.5
                |            | CVE-2022-30065 | HIGH     | 7.80 | 3.17.3, 3.16.5
                |            | CVE-2022-37434 | CRITICAL | 9.80 | 3.17.3, 3.16.5
                |            | CVE-2022-4304  | MEDIUM   | 5.90 | 3.17.3, 3.16.5
                |            | CVE-2022-4450  | HIGH     | 7.50 | 3.17.3, 3.16.5
                |            | CVE-2023-0215  | HIGH     | 7.50 | 3.17.3, 3.16.5
                |            | CVE-2023-0286  | HIGH     | 7.40 | 3.17.3, 3.16.5

Troubleshooting

If you run into issues, you can try adding debug logging with the --debug flag. If you have further issues, please reach out in the community slack or file a github issue.

Documentation

Overview

Copyright © 2023 FairwindsOps, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 2023 FairwindsOps, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Variables
• type BaseImageVulnerabilityReport
• type Client
  • func (c *Client) GetBaseImageOutput() (string, error)
  • func (c *Client) GetBaseImageReport(image string) (*BaseImageVulnerabilityReport, error)
  • func (c *Client) GetImageLayerReport(imageLayers []string) (*BaseImageVulnerabilityReport, error)
  • func (c *Client) MakeRequest(req *http.Request) ([]byte, error)
  • func (c *Client) TableOutput(report *BaseImageVulnerabilityReport) (string, error)
  • func (c *Client) ValidateOptions() error
• type ImageUpgrade
• type ReportBaseImage
• type ReportVulnerability

Variables

var OutputFormats []string = []string{
	"json",
	"yaml",
	"table",
}

var SortColumns []string = []string{
	"id",
	"severity",
	"cvss",
}

var SortOrder []string = []string{
	"asc",
	"desc",
}

Types

type BaseImageVulnerabilityReport

type BaseImageVulnerabilityReport struct {
	ImageRepository string             `json:"image_repository"`
	ImageTag        string             `json:"image_tag"`
	ImagePlatform   *string            `json:"image_platform,omitempty"`
	BaseImages      []*ReportBaseImage `json:"base_images"`
}

type Client

type Client struct {
	APIURL string `json:"apiURL"`
	Token  string `json:"token"`

	// Table Output Options
	OutputFormat   string `json:"outputFormat"`
	ColorizeOutput bool   `json:"colorizeOutput"`
	SortBy         string `json:"sortBy"`
	SortOrder      string `json:"sortOrder"`

	// Inputs
	Image       string
	ImageLayers []string

	// Logger is an instance of the zap logger you can use to configure logging.
	Logger *zap.SugaredLogger
}

func (*Client) GetBaseImageOutput

func (c *Client) GetBaseImageOutput() (string, error)

func (*Client) GetBaseImageReport

func (c *Client) GetBaseImageReport(image string) (*BaseImageVulnerabilityReport, error)

func (*Client) GetImageLayerReport

func (c *Client) GetImageLayerReport(imageLayers []string) (*BaseImageVulnerabilityReport, error)

func (*Client) MakeRequest

func (c *Client) MakeRequest(req *http.Request) ([]byte, error)

MakeRequest performs an HTTP request using the client. It adds the proper headers as well as authentication and does error handling

func (*Client) TableOutput

func (c *Client) TableOutput(report *BaseImageVulnerabilityReport) (string, error)

func (*Client) ValidateOptions

func (c *Client) ValidateOptions() error

type ImageUpgrade

type ImageUpgrade struct {
	Type                 string                 `json:"type"`
	ImageTag             string                 `json:"image_tag"`
	LastScan             *time.Time             `json:"last_scan"`
	FixedVulnerabilities []*ReportVulnerability `json:"fixed_vulnerabilities"`
}

ImageUpgrade is a repository:tag combo with a list of fixed vulnerabilities over the base image

type ReportBaseImage

type ReportBaseImage struct {
	ImageRepository string                 `json:"image_repository"`
	ImageTag        string                 `json:"image_tag"`
	Vulnerabilities []*ReportVulnerability `json:"vulnerabilities,omitempty"`
	LastScan        *time.Time             `json:"last_scan"`
	Upgrades        *[]ImageUpgrade        `json:"upgrades,omitempty"`
}

type ReportVulnerability

type ReportVulnerability struct {
	ID       string  `json:"id,omitempty"`
	Severity string  `json:"severity,omitempty"`
	CVSS     float64 `json:"cvss,omitempty"`
}