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 the deploy-instrumenter.sh file and make changes on the fields below to pass user/platform specific values. See file parameters for help.

#declare const
USERNAME=""
PASSWORD=""
DOCKER_URL=""
ENDPOINT=""

# proxy const
IS_PROXY=""
PROXY=""
SKIP_TLS="true"

# vault const
V_ENGINE=""
V_BASE64=""
V_PATH=""
V_TOKEN=""
V_ADDRESS=""

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.

General

Description

Username

Your Qualys username.

Password

Your Qualys password.

API Gateway URL

The Qualys API Gateway URL where your Qualys account resides. To identify your Qualys platform and get the API URL, visit: https://www.qualys.com/platform-identification/

Docker URL

The default docker URL is: tcp://qualys-docker-proxy.dockersock.jail:2375

Endpoint

The endpoint should be formatted as:

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

Sample:

qualys_joe:my-password@https://gateway.qg1.apps.qualys.com/crs/v1.2

Proxy

 

Is Proxy / Allow Proxy

Set to “true” to define proxy settings if you have a proxy in your docker host.

Proxy

Enter the proxy address. Sample: http://squid:3128

Skip TLS

Set to “true” to skip TLS verification.

Vault

 

Engine

Enter the version of vault engine. Sample: kv-v2.

Base64

Set to “false” by default. Change to “true” if you store base64 version of credentials in the vault.

Path

Enter the path where the vault credentials reside. Sample: /secret/data/qgsuser

Token

Enter the vault token that you use.

Address

Enter the vault address. Sample: http://vault:8200

 

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”