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
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=""
Use this command to run the script:
sh deploy-instrumenter.sh --endpoint <qualys_username>:<qualys_password>@<api_gateway_url>/crs/v1.2
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.
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
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
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 |
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"
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
To view logs for the CRS instrumenter, run “docker logs instrumenter”
To view logs for the Docker socket proxy, run “docker logs proxy”