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 also prints the sign-in URL so you can paste it into a browser.

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.

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

Accepts a path to a Dockerfile, a directory that contains Dockerfiles, or part of a Dockerfile name. 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.

Before it writes anything, the CLI shows the change and asks you to confirm, unless --yes or -y is passed. If you decline, the CLI leaves every file unchanged and exits.

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.

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 a path to a Dockerfile, a directory that contains Dockerfiles, or part of a Dockerfile name. If the CLI finds more than one Dockerfile, you are prompted to select one, multiple or all of them.

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.

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.

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 disabled 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.

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.

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, the load. the agent, and arm CVE Shield.

Exploits CVE-2021-45046 (a Log4Shell vulnerability) using a built-in payload, waits for CVE Shield to report the exploit, and prints a link to the result in Northstar.

Removes the demo containers. Your findings stay in Northstar.