Contrast CLI commands

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. The CLI also prints the sign-in URL so you can paste it into a browser if the window that opened cannot be used.

If you are already signed in, the CLI offers to reconfigure or exit instead of starting a new sign-in.

If you cancel with Ctrl+C, or you do not finish signing in within 5 minutes, the command exits.

After you sign in, the CLI fetches your Contrast API key and service key.

Sign-in credentials are stored in your operating system keychain under the service name contrast-cli. They include your access token, your refresh token, the URL of your instance, your API key, your service key, and your user ID. The CLI does not write secrets in plain text to a file.

If you are not an existing Contrast customer, you can try CVE Shield for free.

Accepts zero or more arguments. Each can be the path to a Dockerfile, a directory that contains Dockerfiles, or part of a Dockerfile name.

If no argument is given, the CLI looks for Dockerfiles in the current directory and prompts you to select one or more eligible files. In a Git repository, it also finds Dockerfiles in subdirectories and skips files that Git ignores. Outside a Git repository, it checks only the current directory, not its subdirectories, and tells you so.

If a given name matches more than one file, you are prompted to select one before making any change, unless --yes or -y is passed.

Before it writes anything, the CLI shows the change and asks you to confirm, unless --yes or -y is passed. If you decline, or there is no terminal to ask at, the CLI leaves every file unchanged and exits with a nonzero code.

If a Dockerfile already has Contrast built in, the CLI skips it and reports it as already instrumented. The CLI also skips and reports a Dockerfile that already sets LD_PRELOAD to something else or whose last line ends in a line continuation. In those cases, the command exits with a nonzero code.

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 CLI edits only the Dockerfile text. It does not check whether the base image can run the agent.

The agent is added to the container after you run your build process to recreate the container with the application.

Accepts zero or more arguments. Each can be the path to a Dockerfile, a directory that contains Dockerfiles, or part of a Dockerfile name. The CLI finds Dockerfiles the same way that contrast-cli agent install does.

If no argument is given and the CLI finds more than one Dockerfile, you are prompted to select one or more. With --yes or -y, the CLI selects all of them. A selected file that does not have Contrast installed is left unchanged and reported as not installed, which is not an error.

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 --yes or -y is passed.

After a successful uninstall, the target Dockerfile contains no Contrast agent configuration data. The CLI removes only the lines that install added, and leaves the rest of the file exactly as it was.

The CLI refuses to change a file and exits with a nonzero code in two cases. If the marker comment is present but the lines after it were edited, the CLI reports the file as edited. If the lines are present without the marker comment, the CLI reports the file as unmarked, and the next build still includes the agent, so remove those lines yourself.

Changes take effect after the container is rebuilt and redeployed. A container that is already running from the instrumented image stays instrumented until then.

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 --yes or -y is passed.

You are prompted to confirm before any container is instrumented, unless --yes or -y is 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.

If the new container cannot be created, the CLI restores the original container and reports the failure.

After the new container starts, the CLI reads its logs for up to 30 seconds for confirmation that the agent loaded, because a container can report healthy without the agent having loaded. If the agent reports a failure or does not confirm in time, the CLI reports that it could not confirm the agent and exits with a nonzero code. The new container keeps running.

The CLI skips a container, leaves it unchanged, and reports why when the container already has the agent, is not running, is paused, was started with --rm, already sets LD_PRELOAD to something else, already mounts something at /contrast, or cannot be recreated with its current settings. A container that already has the agent is not an error. Any other skipped container makes the command exit with a nonzero code.

The CLI does not edit a Dockerfile or a compose file. If Docker Compose manages the container, the CLI recreates it like any other container, and the agent is gone the next time you run docker compose up for that service.

Instrumentation persists across container restarts, but is removed if the container is rebuilt, deleted, or run through contrast-cli agent disable.

Accepts zero or more container targets. With none given, the CLI offers only the containers that the enable command previously attached to. If more than one container qualifies, you are prompted to select one or more, unless --yes or -y is passed, in which case the CLI detaches all of them.

If a given name matches more than one running container, you are prompted to select one before anything is disabled, unless --yes or -y is 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 --yes or -y is passed.

Disabling restarts the container with the agent removed, following the same stop-and-recreate mechanism as the contrast-cli agent enable command. Files written at runtime in the old container are not preserved. If the new container cannot be created, the CLI restores the original container and reports the failure.

The CLI cannot confirm that the agent unloaded. It reports only that the new container started and, if the container defines a health check, Docker's health status.

Downloads the sample application and its MySQL database images if they are not already on your machine.

Starts both containers with a Contrast agent attached to the sample application, and waits for the application to respond and the agent to load.

Waits about 30 seconds for the agent to arm CVE Shield.

Exploits CVE-2021-45046 (a Log4Shell vulnerability) using a built-in payload.

Waits for CVE Shield to report the exploit, then prints a link to the result in Northstar.

Removes the demo containers. Your findings stay in Northstar.