Contrast CLI Commands for CVE Shield
General commands for the CLI are structured as follows:
contrast-cli [command] [options]
CLI Commands for CVE Shield and the Contrast Agents use the following structure:
contrast-cli agent [command] [options]
Common options
The options below are available for every command:
Option | Behavior |
|---|---|
| Skips all confirmation prompts, including multiple file detection. Recommended for scripted or unattended installs. |
| Displays available commands, usage, and options. |
contrast-cli configure
Authenticates the CLI with your existing Contrast account. You only need to run this command once after you install the CLI. You must run this command before running any other CLI commands to ensure proper operation of the CLI.
Usage
contrast-cli configure --url [--yes]
You will be prompted to provide the --url of your Contrast instance if not provided. Alternatively, you can set the --url to the CONTRAST_URL environment variable.
Behavior
If no valid sign-in is stored, your default browser opens to the Contrast sign-in page where you can enter your credentials. The CLI receives the result through a redirect back to your own machine. Sign-in credentials are stored in your operating system keychain, including your access token, your refresh token, and your organization and user data. The CLI does not write secrets in plain text to its own configuration file.
If you are not an existing Contrast customer, you can try CVE Shield for free.
contrast-cli agent install
Instruments a Dockerfile so the Contrast CVE Shield agent survives rebuilds, redeploys, and new instances without needing to run these actions repeatedly. This Contrast CLI command for CVE Shield supports Free tier prospects who find instrumenting their first application challenging.
Paid customers can use them too, but they are intended for temporary debugging, troubleshooting, and evaluation. For production rollouts, keep using your usual agent deployment method.
Note
This command updates your pre-built Dockerfiles so a CLI agent attachment stays in place. Without it, an agent attached with enable disappears the next time the container is rebuilt or deleted.
With it, rebuilds, redeploys, and new instances keep the agent, so you don't repeat the setup each time. It's also low commitment, because contrast-cli agent uninstall removes only what install added. Changes take effect when you next rebuild your container.
Usage
contrast-cli agent install [Dockerfile...] [--yes]
Behavior
Accepts zero or more Dockerfile paths.
If no Dockerfile path is given, the CLI scans the current directory and subdirectories and prompts you to select one or more eligible files.
If a given name matches more than one file, you are prompted to select one before making any change, unless
--yesor-yis passed.If a Dockerfile already has Contrast built in, the CLI skips it.
Configuration added to the Dockerfile is written with a unique, identifiable marker so it can be cleanly removed later by contrast-cli agent uninstall. Do not modify this marker.
The agent is added to the container after you run your build process to recreate the container with the application.
contrast-cli agent uninstall
Reverses contrast-cli agent install, removing only the configuration that the install command added. This command never touches source images, compose files, or pod specifications beyond that.
Usage
contrast-cli agent uninstall [Dockerfile...] [--yes]
Behavior
Accepts zero or more Dockerfile targets. With none given, the CLI removes Contrast from every detected file where it is currently installed.
If a given name matches more than one file, you are prompted to select one before making any change.
You are prompted for confirmation before anything is removed, unless
--yesor-yis passed.After a successful uninstall, the target Dockerfile contains no Contrast agent configuration data.
Changes take effect after the container is rebuilt and redeployed.
contrast-cli agent enable
Attaches a Contrast CVE Shield agent to an already-running Docker container without rebuilding the container. Use this command to evaluate protection on infrastructure you don't own, or on short-lived targets, where running contrast-cli agent install isn't practical. This Contrast CLI command for CVE Shield supports Free tier prospects who find instrumenting their first application challenging.
Paid customers can use them too, but they are intended for temporary debugging, troubleshooting, and evaluation. For production rollouts, keep using your usual agent deployment method.
Note
Enable attaches the Flex Agent to a container that is already running, so you don't have to change your build or redeploy through your pipeline. That makes it a fast way to test CVE Shield on a service you haven't instrumented yet, reproduce a problem with the agent attached, or evaluate protection on a short-lived target. Plan for brief downtime, because enable replaces the container with a new one that has the agent attached. The agent stays across restarts, and contrast-cli agent disable removes it when you're done.
Usage
contrast-cli agent enable [container...] [--yes]
Behavior
Accepts zero or more running container names.
If no container is given, the CLI lists running Docker containers for you to choose from.
If a given name matches more than one running container, you are prompted to select one before making any change, unless
--yesor-yis passed.You are prompted to confirm before any container is instrumented, unless
--yesor-yis passed. The CLI displays the active Docker context as part of that confirmation.Enabling stops the current container and starts a new one with the same settings plus the agent attached. This looks like a restart, but is technically a new container. Files written at runtime in the old container are not preserved, and there will be brief downtime during the switch.
Instrumentation persists across container restarts, but is removed if the container is rebuilt, deleted, or run through contrast-cli agent disable.
contrast-cli agent disable
Detaches Contrast from a container that was instrumented with contrast-cli agent enable. This command has no effect on containers instrumented with contrast-cli agent install.
Usage
contrast-cli agent disable [container...] [--yes]
Behavior
Accepts zero or more container targets. With none given, the CLI targets every container that the enable command previously attached to.
If a given name matches more than one running container, you are prompted to select one before anything is disabled, unless
--yesor-yis passed.Containers that don't have Contrast attached via the contrast-cli agent enable command are skipped.
You are prompted to confirm before any container is disabled, unless
--yesor-yis passed.Disabling restarts the container with the agent removed, following the same stop-and-recreate mechanism as the contrast-cli agent enable command.
contrast-cli demo
Launches a sample vulnerable application in Docker with a Contrast agent attached, so you can see CVE Shield detect a real vulnerability without instrumenting anything of your own.
Usage
contrast-cli demo [--guided]
Options
Option | Outcome |
|---|---|
| A manual step-by-step walkthrough of the demo that performs the following actions:
|
Behavior
Defaults to automatic mode that performs the following actions:
Downloads a sample container and attaches a Contrast agent to it.
Starts the container and waits ~30 seconds for it to report running.
Creates a user inside the app.
Exploits CVE-2021-45046 (a Log4Shell vulnerability) using a built-in payload.
After a successful exploit, a link to viewing exploit data is provided.
See CVE Shield and Review Contrast CVE Shield states documentation to learn more about CVE Shield in Northstar.