Deploy the instrumenter service

You can run the instrumenter using any of these options:

Option 1: Run instrumenter using docker CLI based command

Option 3: Run kubernetes instrumenter.yml

Option 1: Run instrumenter using docker CLI based command

This option lets you run the instrumenter in CLI mode (the default) for instrumenting images locally or in Daemon mode to use the instrumenter microservice to instrument images from the registry. You can run the instrumenter with or without a vault.

Pull the docker CLI files from github. You can download them from https://github.com/Qualys/qualys_crs_instrumenter
Edit instrumenter.sh to configure user specific details for proxy and vault usage. See file parameters for help.
Run the docker CLI script.
By default, the script will run in CLI mode and for this mode you must specify the endpoint and image. Policy ID is optional. Use this command to run the script:

sh instrumenter.sh --endpoint <qualys_username>:<qualys_password>@<api_gateway_url>/crs/v1.2 --image <image> [--policyid <policy id>]

To use the instrumenter microservice to instrument images from the registry, you must run the script in Daemon mode. Specify --daemon-mode and specify the endpoint. In this case, you do not specify the image or policy. Use this command to run the script:

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

Usage Examples

Default Example - CLI mode:

./instrumenter.sh --endpoint <endpoint> --image <image> [--policyid <policy id>]

Default Example - Daemon mode:

./instrumenter.sh --endpoint <endpoint> --daemon-mode

Vault Example - CLI mode:

./instrumenter.sh --endpoint <endpoint> --vault-token <token> --vault-engine <engine version> [--vault-base64] --vault-path <vault-path> --vault-address <vault-address> --image <image> [--policyid <policy id>]

Vault Example - Daemon mode:

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

Proxy Example - CLI mode:

./instrumenter.sh --endpoint <endpoint> --proxy <proxy> --image <image> [--policyid <policy id>]

Proxy Example - Daemon mode:

./instrumenter.sh --endpoint <endpoint> --proxy <proxy> --daemon-mode

Where:

<endpoint> is in the format of username:password@url if you are not using a vault. Only url is needed when you are using a vault.
<image> is the image Id (e.g. “6d9ae1a5c970”) or repository name:tag (e.g. “library/centos:centos72” or “java:latest”) for the container image you want to instrument using CLI mode. The image must be present locally where you’re running the CLI command.
<policy id> is the policy Id (e.g. “5fd20b4321dabf0001fdc464”) for the policy you want to immediately apply to the image being instrumented using CLI mode.

Option 2: Run docker compose file

This option is for using the instrumenter microservice to instrument images from the registry. Passing QUALYS_GATEWAY_ENDPOINT is required.

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

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

This option is for using the instrumenter microservice to instrument images from the registry.

Edit the required field QUALYS_GATEWAY_ENDPOINT in the kubernetes 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”