QScanner Modes

Collect Data

In this mode, QScanner collects only the inventory data without uploading it to Qualys Enterprise TruRisk™ Platform.

Mode	--mode inventory-only
Format	./qscanner image <image_name or imageId> --mode inventory-only
Example	./qscanner image groovy --mode inventory-only

By default, a JSON file of the inventory is created at the specified path. You can use --format <format type> tag to change the output inventory format.

There are several configurable parameters related to data collection. See Commands and Options for the list of options supported by each command.

When multiple QScanner instances are present, using the --cache <option>, you can block other instances. Therefore, it is recommended not to use the cache option in scenarios that require concurrent usage.

There are different formats in which the inventory can be generated. To know about them, refer to Data Collection Formats.

Upload Data to Qualys Enterprise TruRisk™ Platform

In this mode, QScanner collects inventory data from the target and uploads it to the Qualys Platform. It performs LZMA compression on the changelist.db and uploads it in fragments.

Mode	--mode scan-only
Format	./qscanner image <image_name or imageid> --mode scan-only --pod <POD name> --access-token <token>
Example	./qscanner image python --mode scan-only --pod US1 --access-token <token>

The scan results are available on Qualys Enterprise TruRisk™ Platform under Container Security > Assets > Images tab. You can search the scanned images using QScanner with the help of following search token: source:COMMAND_LINE.

For communication with the platform, you need to pass the following options while running QScanner:

--pod <POD name>: Specify Qualys Enterprise TruRisk™ Platform (POD) for backend communication.
Examples of Qualys PODs: US1, US2, US3, US4, EU1, EU2, EU3, IN1, CA1, AE1, UK1, AU1, KSA1.
If your platform is not mentioned in above examples, provide the gateway URL using --gateway-url.
--gateway-url: Specify the Qualys Enterprise TruRisk™ Platform (POD) gateway URL for backend communication. Use this only if your platform is not listed on the Qualys Platform Identification page.
--access-token: This is a never-expiring access token that is required for authorization to the platform. You can pass the access token using two methods:
- By using the QUALYS_ACCESS_TOKEN environment variable: export QUALYS_ACCESS_TOKEN= <token>
- By passing the access token via QScanner using the --access-token <token> option. Preference is given to the value passed via QScanner.

The recommended way to provide the access token is via the environment variable.

To generate the access token, log in to the Qualys platform and navigate to Container Security > Configuration > Access Token.

Apart from this, you might also need to configure the following options depending on your environment:

--proxy <proxy url>: If specified, QScanner uses the proxy server configured on your machine. Instead of this, you can also configure https_proxy or http_proxy value of ENV variables.
--skip-verify-tls: If specified, secure TLS verification is skipped.
--cert-path: If a certificate path is provided, it is used. If this option is provided, skip-verify-tls is ignored.

Fetch a Report

In this mode, QScanner scans the target, uploads the scanned data to the platform, fetches a scan report from the platform, and shows it on the console. This is the default mode of QScanner. In addition to this, it creates the report in JSON format at the path specified in --output-dir.

Mode	--mode get-report
Format	./qscanner image <image_name or imageid> --mode get-report --pod <POD name> --access-token <token> --output-dir <path_to_output_dir>
Example	./qscanner image mydebian10 --mode get-report --pod UK1 --access-token <token> --output-dir /path/to/output/dir

This report contains details of QIDs detected, CVE IDs associated with the QIDs, severity, software name, installed version, and the version in which the fix is available. This report also contains inventory details. For more information, see .

Qualys combines vulnerability reports of the same image SHA. In a scenario where in 'Instance 1' QScanner scanned Image A with --scan-types, os and sca, and in 'Instance 2' QScanner scanned Image A with --scan-types os, the resultant vulnerability report contains both os and sca data. This gets apply to policy evaluation as well. 'Instance 2' of QScanner will get policy evaluation based on both os and sca.

Evaluate a Policy

You can use QScanner in a CI/CD pipeline and make use of the policy evaluation feature of Container Security. Based on policies that are configured on the platform, QScanner can pass or fail the scan result of a target.

In this mode, to evaluate appropriate policies, you need to pass a combination of tags using the --tags argument. The policies with the same combination of tags are fetched and evaluated.

Mode	--mode evaluate-policy
Format	./qscanner image <image_name or imageid> --mode evaluate-policy --pod <POD name> --access-token <token> --tags "tag1,tag2"
Example	./qscanner image known:latest --mode evaluate-policy --pod US2 --access-token <token> --tags "tag1,tag2"

The policy evaluation result is available in the generated report.

The evaluation result can be one of the following:

ALLOW: Evaluation against the configured policies indicates success. QScanner returns exits with code 0.
AUDIT: None of the policies were evaluated. This causes QScanner to exit with code 43.
DENY: Evaluation against the configured policies indicates that one or more rules failed. QScanner exits with code 42.

For more information about creating security policies, see Container Security Online Help: Creating Security Policies. Also, to know more details about Exit Codes, see Appendix: Exit Codes.