Home | CRS Home

Deploy the instrumenter service

The instrumenter service is needed to instrument your images. You’ll deploy this service in your environment. Then when you choose to instrument an image from the Container Security UI, the instrumenter service will be used to pull down the unprotected image, package our solution into it, and then push it back to the registry as a protected image.

You can run the instrumenter using any of these options:

Option 1: Run instrumenter using docker CLI based command

Option 2: Run docker compose file

Option 3: Run kubernetes instrumenter.yml

File parameters

Option 1: Run instrumenter using docker CLI based command

You can run the instrumenter with or without a vault.

1) Pull the docker CLI files from github. You can download them from https://github.com/Qualys/qualys_crs_instrumenter

2) Edit deploy-instrumenter.sh to configure user specific details for proxy and vault usage. See file parameters for help.

3) Run the docker CLI script. Use this command to run the script:

sh deploy-instrumenter.sh --endpoint <qualys_username>:<qualys_password>@<api_gateway_url>/crs/v1.2

Usage Examples

Default:

./deploy-instrumenter.sh --endpoint <endpoint>

Using vault:

./deploy-instrumenter.sh --endpoint <endpoint> --vault-token <token> --vault-engine <engine-version> [--vault-base64] --vault-path <vault-path>

Using proxy:

./deploy-instrumenter.sh --endpoint <endpoint> --proxy <proxy>

Note: <endpoint> is in the format of username:password@url if you are not using a vault. Only url is needed for the endpoint when you are using a vault.

Option 2: Run docker compose file

Launch instrumenter using the example below. Passing QUALYS_GATEWAY_ENDPOINT is required.

QUALYS_GATEWAY_ENDPOINT="<qualys_username>:<qualys_password>@<api_gateway_url>/crs/v1.2" docker-compose up

Note: Use this command at the directory level where the docker compose file is present.

Please edit the fields in the docker compose file and remove # to uncomment and declare the constant you would like to use. See file parameters for help.

LI_MQURL: qas://${QUALYS_GATEWAY_ENDPOINT} # set the username password and qualys endpoint for instrumenter in env or directly to this file
# VAULT CONFIG (Change these settings if you have your own vault)
# LI_VAULT_SECRET_ENGINE: "kv-v2"
# LI_VAULT_DATA_VALUES_BASE64: "false"
# LI_VAULTPATH: "${USER_VAULT_PATH}"
# LI_VAULT_TOKEN: "${VAULT_TOKEN}"
# LI_VAULT_ADDRESS: "http://vault:8200"

# PROXY SETTINGS (Uncomment and fill required values for proxy)
# LI_ALLOWHTTPPROXY: true
# https_proxy: http://squid:3128
# LI_MQSKIPVERIFYTLS: true

Option 3: Run kubernetes instrumenter.yml

Edit the required field QUALYS_GATEWAY_ENDPOINT in the kubenetes file. Replace QUALYS_GATEWAY_ENDPOINT with the following:

<qualys_username>:<qualys_password>@<api_gateway_url>/crs/v1.2

Edit the vault and proxy fields, as required. See file parameters for help.

- name: LI_MQURL
value: qas://{{QUALYS_GATEWAY_ENDPOINT}} # Enter the username password of crs and qualys instrumenter pod endpoint

# VAULT CONFIG Change these settings if you have your own vault
# - name: LI_VAULTPATH
#   value: /secret/data/qgsuser # Enter path where the vault credentials reside
# - name: LI_VAULT_ADDRESS
#   value: http://vault:8200 # Change if you have your own vault
# - name: LI_VAULT_DATA_VALUES_BASE64
#   value: "false" # Change if you store base64 version of credentials in vault
# - name: LI_VAULT_SECRET_ENGINE
#   value: kv-v2 # Set the version of vault engine you use
# - name: LI_VAULT_TOKEN
#   value: {{VAULT_TOKEN}} # Set the vault token that you use

# proxy settings (Uncomment this if you have a proxy in your docker host)
# - name: LI_ALLOWHTTPPROXY
#   value: true
# - name: https_proxy
#   value: http://proxy:3128
# - name: LI_MQSKIPVERIFYTLS
#   value: true

Then launch instrumenter using the following command:

kubectl apply -f instrumenter.yml

File parameters

Regardless of the option you pick for deploying the instrumenter service, there are certain user/platform specific parameters you’ll need to provide. See the table below.

After the instrumenter has been deployed

Check the instrumenter logs to verify the instrumenter is online and functional.

docker logs instrumenter | grep "Awaiting InstrumentRequests"

The output should print something similar to:

"[2020-05-26T21:37:52Z] DEBUG instrumenter: Awaiting InstrumentRequests"

Troubleshooting

Credentials issues when deploying without a vault service

If you are not using a vault service, your Qualys credentials are being passed in plain text in a URL. If you are using special characters in your password (recommended), you will need to encode the special characters using HTML encoding.

HTML encoding site for reference: https://www.w3schools.com/tags/ref_urlencode.ASP

Logging

To view logs for the CRS instrumenter, run “docker logs instrumenter”

To view logs for the Docker socket proxy, run “docker logs proxy”