crowdstrike / ivan

Falcon Image Vulnerability Analysis (IVAN) is a command-line image assessment tool.

Overview

Falcon Image Vulnerability Analysis (IVAN) is a command-line image assessment tool. It works by creating an inventory of packages on an image and then sending the package metadata to the CrowdStrike cloud for assessment.

IVAN results are returned as a JSON report in the terminal. IVAN differs from other methods of image assessment because only the image metadata is uploaded to the CrowdStrike cloud. The image and metadata do not appear anywhere in the Falcon Console.

Comparing assessment methods

Capability	IVAN	Registry connection	Image push
Image being assessed stays local	Y	N	N
Assessment results are available in Falcon console	N	Y	Y
Assessment results are available via API	N	Y	Y
Container Software Bill of Materials (SBOM) includes OS and application package, and version information	N	Y	Y
OS package vulnerability assessment	N	Y	Y
Software Composition Analysis (SCA) includes python, javascript, go, ruby, and java	N	Y	Y
Misconfiguration detection includes hardcoded secrets and industry best practice benchmarking	N	Y	Y
Malware detection	N	Y	Y
Vulnerability exceptions and allow-listing support	Y	Y	Y

Requirements

• Docker: You must have the latest version of Docker.
• CrowdStrike subscription: Falcon Cloud Workload Protection
• API client: You can create a new API client on API Client and keys.
  • Your API client must have Falcon Container CLI scope with Write permission.

Note To use IVAN, the latest version of Docker must be installed on the executing machine. Currently, podman and other container runtimes are unsupported.

Supported operating systems

OS	Supported versions
Alpine Linux	3.9 through 3.17.9
Amazon Linux	1, 2
CentOS	7 through 8.3
Debian GNU	9, 10, 11
Oracle Linux	6.0 through 8.9
Red Hat Enterprise Linux (RHEL)	7 through 8.6
SUSE Linux Enterprise Server (SLES)	11.4, 12.2, 12.3, 12.4, 12.5, 15, 15.0, 15.1, 15.2
Ubuntu	16.04, 18.04, 20.04, 22.04

IVAN releases

You can download the latest IVAN release at https://github.com/CrowdStrike/ivan/releases.

Install IVAN

Download IVAN and make it executable.

1. Download the latest version of IVAN for your OS from here.
2. Extract the archive. In a terminal, run:

   tar xvzf ivan_<version>.tar.gz

3. Make the binary executable. In a terminal, run:

   chmod +ux ivan

4. (Optional) Move the binary into $PATH (example:/usr/local/bin).

Authenticate IVAN

Provide IVAN with your CrowdStrike API client ID and secret. You are prompted for these credentials the first time you run IVAN or when you use the -reset-creds option.

If you want to set up non-interactive shell login, set the API client ID and secret as environment variables:

export FALCON_CLIENT_ID=<clientID>
export FALCON_CLIENT_SECRET=<clientSecret>

Note To create an API client, see API Client and keys.

Your API credentials are applied automatically for subsequent image assessments. The credentials are stored in $HOME/crowdstrike/config.json.

{
 "region": {
   "client_id": "e2f…d06",
   "client_secret": "aba…4To"
 },
 "region2": {
   "client_id": "l9f…d06",
   "client_secret": "cdc…j4To"
 },
 "region3": {
   "client_id": "p6f…d06",
   "client_secret": "plo…nj4To"
 }
}

Image assessment location

IVAN assesses images through the Docker daemon. Use docker pull to make images available for IVAN, or load local images to Docker by running the following command:

docker load < <image_name>

IVAN General usage

Use this syntax to run IVAN image assessment on a Docker image.

ivan [options] [region] [image]

IVAN CLI Flags

Flag	Required	Description
-image <imageName:tag>	Required	Specifies the image to assess. If a tag is not specified, Docker appends latest tag to the image name.
-region <string>	Required	Sets the CrowdStrike cloud region. Possible values are us-1, us-2, eu-1, us-gov-1.
-dry-run	Optional	Lists the image packages but doesn’t send it to the CrowdStrike cloud for image assessment.
-license	Optional	Prints the IVAN license to the terminal.
-runtime <string>	Optional	Choose one of container runtimes. Possible values are docker, podman, containerd, crio. The default is docker.
-socketpath <string>	Optional	Specify the .sock path of the runtime if different from default else leave empty. The default is unix:///run/docker.sock.
-timeout <integer>	Optional	Sets the client timeout duration. The default is 30 seconds.
-reset-creds	Optional	Initiates terminal prompt to re-enter API client ID and password.

Image assessment report

The report returns the following info in JSON format:

Object	Type	Description
count	integer	The count of vulnerabilities on image
layerHash	string	The layer hash containing the vulnerabilities
os	string	The OS and version on the image
vulnerabilities	array	An array of vulnerabilities and their info
CVEID	string	The Common Vulnerabilities and Exposures (CVE) ID of the vulnerability
Product	string	The product name associated with the vulnerability
Severity	string	The CVE severity of the vulnerability: CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN, or NONE.
Version	string	The version of the product associated with the vulnerability
Description	string	The CVE description

Examples using IVAN

Here are some examples of the input and output for assessing images with IVAN.

Assess an image

ivan -region us-1 -image alpine:3.17.0

Output when vulnerabilities are found:

{
  "count": 2,
  "layerHash": "7528…c933",
  "os": "Alpine 3.17.0",
  "vulnerabilities": [
   {
    "CVEID": "CVE-2022-3996",
    "Product": "libcrypto3",
    "Severity": "HIGH",
    "Version": "3.0.7-r0",
    "Description": "If an X.509 certificate … functions."
   },
   {
    "CVEID": "CVE-2022-3996",
    "Product": "libssl3",
    "Severity": "HIGH",
    "Version": "3.0.7-r0",
    "Description": "If an X.509 certificate … functions."
   }
  ]
 }

Output when no vulnerabilities are found:

{
  "count": 0,
  "layerHash": "b1a6…7392",
  "os": "Ubuntu 20.04",
  "vulnerabilities": null
 }

List the inventory of packages on an image

ivan -dry-run -region us-1 -image myApp:latest

Note The -dry-run option blocks the inventory from being sent to the CrowdStrike cloud for image assessment. The inventory shows a complete list of packages found on the image. It does not show package vulnerabilities.

{
  "osversion": "Ubuntu 16.04",
  "packages": [
    {
      "Vendor": "Ubuntu Core developers",
      "Product": "libquadmath0",
      "MajorVersion": "5.4.0-6ubuntu1~16.04.12",
      "SoftwareArchitecture": "amd64",
      "PackageProvider": "DPKG",
      "PackageSource": "libquadmath0 5.4.0-6ubuntu1~16.04.12"
    },
    
    ...
    
],
"applicationPackages": [
    {
      "type": "PYTHON",
      "libraries": [
        {
          "Name": "pip",
          "Version": "19.0.3",
          "License": "Unknown",
          "LayerHash": "2fcf…c367f"
        },
        {
          "Name": "PyYAML",
          "Version": "5.4.1",
          "License": "Unknown",
          "LayerHash": "ea8d…507e1"
        }
      ]
    }
  ]
}

ivan's Issues

Mac M1 - too many open files

Seeing this error constantly as i try to run the latest version

"level":"fatal","msg":"open /var/folders/q0/{some random string of numbers I took out}/T: too many open files","time":"2023-02-17T15:41:54Z"}

Any ideas? Previous version does not have this issue

Product Path is missing

Product Path is missing in the json output

Unable to add the client Secret , gives error

Earlier when i ran this it worked fine and the scanning went well, but now when I try to scan a new image it asked for the creds. I added the client ID and the moment I add client secret , it just doesnt work and gives the following error.

image error (): could not parse reference:

Update assessment matrix for Registry Connection to have SCA

https://github.com/CrowdStrike/ivan?tab=readme-ov-file#comparing-assessment-methods

Image Push and Registry Connection should have SCA.

support for sarif format

can we generate the output in sarif format?

Linux ARM version is missing

Please create a Linux ARM version -
Use Case :

• When running containers on Mac M1
• Running a linux VM on Mac M1

README.md has incorrect config.json path documented

The README.md file describes the location of cached API keys as $HOME/crowdstrike/config.json, this should read $HOME/.crowdstrike/config.json

add "applicationPackages" section in scan output json

Just like there is a seperate section in json for "applicationPackages" when we run the ivan command with -dry-run.
Can we have the same section "applicationPackages" in the output json when we actually perform the scan.
This way we can diffrentiate CVEs found in docker base image and applicationPackages.

Assessment method table inconsistent with CS console docs

Hello,

The method comparison table is inconsistent with what is shown on CS console, and also seems inconsistent with prior release notes.

Table here indicates no supported functions for IVAN. However, in CS console it shows SCA and OS package assessment as supported.
GitHub:

CS Console:

Source: https://falcon.crowdstrike.com/documentation/page/aa4fccee/container-security#j06e79a9

Release notes at https://supportportal.crowdstrike.com/s/article/Release-Notes-Falcon-Image-Vulnerability-Analysis-CLI-Includes-Software-Composition-Analysis make me think the GitHub version is incorrect.

Would you mind updating it?

Also, should GitHub page indicate that the CS console docs are the authoritative source?

Unable to run 1.0.6 on AL2

Following error given when running on amazon-coretto:21 container (AL2).

ivan: /lib64/libc.so.6: version `GLIBC_2.28' not found (required by ivan)``` 

0.34 works aok, any guidance highly appreciated.