Supported Scans

You can specify the scans you want to perform by using --scan-types <scan-types> flag. QScanner offers the following scan options.

• Operating System (OS) Scan
• Software Composition Analysis (SCA) 
• Secret Scan

Operating System (OS) Scan

OS scan broadly performs:

• OS fingerprinting
  Information about the target OS. The OS name collected is in the format that Qualys' signature evaluation expects.
• Collecting OS packages
  Creates a list of OS installed packages.

To know about supported OSs, refer to Appendix: Supported Operating Systems. 

Supported Package Managers

QScanner supports the collection of OS installed packages from the following package managers:

• APK
• DPKG
• RPM

Software Composition Analysis (SCA)

With SCA it is possible to scan for vulnerabilities in the application dependencies. To know about supported SCA languages, refer to Appendix: Supported SCA Languages.

To disable collection of packages for certain SCA languages, use --disable-sca-languages <languages_to_disable>. The values of this flag are case-insensitive. For example, the below command will not collect Ruby, .NET, and Node.js packages from the given image.

$ ./qscanner image sentry --disable-sca-languages ruby,.net,Node.js 

Java Index Database (java-db)

Java Index database is an SQlite DB that stores ArtifactID, GroupID, Version and SHA1 for JAR files. This data is created by parsing all indices from the Maven repository.
QScanner runs in Online scan mode by default. In this mode, it downloads the java-db from https://ghcr.io/v2 periodically. This database is used when scanning JAR files so that QScanner can identify the groupId, artifactId, and version of JAR files. It is automatically downloaded and updated when needed. This gets downloaded in java-db directory within the QScanner cache directory - $USER_CACHE_DIR/qualys/qscanner/ or the path specified using --cache-dir flag.
The default cache directory is /root/.cache/qualys/qscanner/.

- When using the clear-local-cache command, the entire cache directory, including the local cache database and the Java index database, will be cleared.
- Java-db will be downloaded and initialized only if the jar files are detected in an image. If the Java DB download fails, QScanner will fall back to the Offline Scan.

Supported Java DB Repositories

In addition to https://ghcr.io/v2, the following are the additional repositories where the java-db gets published.

• aws: https://public.ecr.aws/v2/
• docker: https://index.docker.io/v2/

By default, QScanner uses the https://ghcr.io/v2 link. You can override this behavior using QSCANNER_ENABLED_JAVADB_REPOS env variable.
For example, export QSCANNER_ENABLED_JAVADB_REPOS=ghcr,aws,docker

This allows QScanner to attempt to download the java-db from all the provided repositories in case of failure.

The order defined using QSCANNER_ENABLED_JAVADB_REPOS is the order in which QScanner tries the repository to download the java-db.

Offline Scan

It is possible to avoid downloading java-db and run in --offline-scan=true. Use this parameter to disable internet access for the SCA and run the scan in Offline mode instead.

It is recommended to run a scan in Online mode. The quality of software package enumeration for Java substantially degrades when the scan is run in offline mode. This can affect the accuracy of the vulnerability posture of the image.

./qscanner image maven \
    --mode inventory-only \
    --format json \
    --offline-scan=true  

Secret Scan

Secret scanning can be used to collect secrets based on a rule file (Secret Config). The Secret config file is a file that contains rules that define what should be treated as a secret. This file can be specified using --secret-config-file <file_path>. If the config file is not provided or does not contain any configurations, QScanner downloads secret-config from the backend.

QScanner downloads secret-config from backend and store it in the cache directory - {QSCANNER_CACHE_DIR}/secret_config.json

On subsequent runs, it uses the cached rule file. This file remains in cache by default for 24 hours (configurable via --secret-config-refresh-duration) after which QScanner attempts to check backend if there are any changes to the rules file. If there are no changes, then it will continue using the existing secret_config.json.

If the rules have been updated (decided based on the content hash), a new Secret Config file will be downloaded.

To forcefully refresh the secret-config, use --force-refresh-secret-config=true flag.
To use a custom secret-config rules file, use --secret-config-file <path-to-rule-file>. If this file is provided, QScanner will not attempt to download secret-config from the Qualys backend.
 

Secret Config

The Secret Config file contains the following parameters:

• id: Unique identifier for each rule.
• category: Rule category.
• title: User-friendly name of the rule.
• regex: Actual regex that is matched against the file content to categorize it as secret. This is encoded in base64 format.
• severity: Severity of secret detected using this rule.
• keywords: These keywords are matched against the content of the file before evaluating the regex. If the file does not have any of the mentioned keywords, then this rule is not evaluated. If no keywords are provided, the rule will be evaluated against the regex.
• show-secret-content: By default, if a secret is detected, only its line number and filename are shown in the secret results. If the matched content of a rule is required to be revealed, then this field can be set to true.

Scanning Multi-architectural Images

QScanner supports scanning of images built on multiple architectures. You need to specify the platform flag (--platform) along with `<os>/<architecture>/<variant>` format. Depending on architecture of the image, a default variant is used automatically. You need not provide all the 3 components (os, arch & variant).

For example, see valid inputs of 'os, architecture, and variant' format for the `--platform` flag.

• linux/arm64/v8
• linux/arm64
• linux/amd64/v2
• linux/amd64

Provide all the values that are applicable for the target image wherein OS and architecture are the mandatory parameters.  
Below are the formats for the the 'platform' flag in which image can be provided:  
1. `<index-digest>` + `--platform`
2. `<name>:<tag>` + `--platform`
3. `<name>:<tag>@<index-digest>` + `--platform`
4. `<name>:<tag>@<manifest-digest>` (platform flag not required)

When a multi-arch image is pulled, for example, using `docker pull <name>@<manifest-digest>` (without using the 'platform' flag), output of `docker images` shows 'none' in image's tag. In this case, you should use option #4 (as mentioned above) to scan it. 

If `--platform` flag is not mentioned or the value is empty then Qscanner will use OS and Architecture value of the host and perform scanning based on that.

For more details, refer to:  https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63  

QScanner supports scanning of images built on multiple architectures using `--platform` flag in the following conditions and targets as of now.

Category	Target	Platform flag applicable - Yes/No?
	Remote images	Yes
	archive (oci/docker)	No
Runtime	docker	No
	containerd	Yes
	podman	No
	crio	No
Runtime with Storage Driver	docker-overlay	Yes
	docker-overlay2	No
	containerd-overlay	Yes
	podman-overlay	No
	crio-overlay	No