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
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.
1) Pull the docker CLI files from github. You can download them from https://github.com/Qualys/qualys_crs_instrumenter
2) Edit instrumenter.sh to configure user specific details for proxy and vault usage. See file parameters for help.
3) 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
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.
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
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
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
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”