Host Scanner reference manual
The SandboxAQ Host Scanner is a command-line application that scans the filesystem or a container image to find cryptographic material and logs them in a format suitable for treatment by the SandboxAQ Security Suite.
Before you can use the Host scanner, see installation instructions.
How it works
Starting at the root location chosen by the user, The SandboxAQ Host Scanner visits every file in the directory tree below that point, recursively descending into all subdirectories (but not following symbolic links). For each file, the first bytes are tested against a list of detectors for supported formats. For those that are supported, it parses them and logs the cryptographic material found in a format suitable for treatment by the SandboxAQ Security Suite. No secret data (e.g. private keys) is stored. In the case of encrypted keystores, if a password is provided, the Host Scanner also tries to decrypt the encrypted parts of it using that password.
Scanning a filesystem
Getting started will explain you how to use the Host scanner to scan the filesystem.
Detecting cryptographic material inside a zip file
When it encounters a zip file, the SandboxAQ Host Scanner scans the files inside it. It performs the same checks as it would for regular files on a filesystem, with the following limitations:
- JAR files inside ZIP archives are not supported
- ZIP files inside ZIP archives are not supported
It is also worth noting that the host-scanner only supports files following the original PKZIP file format specification that does not span across several files. In particular, it does not support ZIP64 archives.
Scanning a container image
To run the Host scanner on a container image, replace the
--root option by the
--image-name one. For example:
Note: This feature is not available for Windows.
Detecting hard-coded keys and certificates inside JAR files
To detect hard-coded keys and certificates, the Host Scanner calls the Static Scanner to retrieve hard-coded strings in JAR files.
To run the Host Scanner with the Static Scanner:
The output trace then only contains keys and certificates found in JAR files. Using
--module all will make it contain both those and the ones found in other types of files.
The Host scanner is configured using command-line options. For example, to configure the
directory where the Host scanner will write the resulting trace, use the
Here is a list of the available options:
--root: Path to a directory to start searching from if the scan target is a filesystem. The host scanner will search everything below this point.
--image-name: The image name if the scan target is a container.
--output(required): File to write the trace to. This is a trace in CST format, which can be uploaded to the web application and analyzed to produce a cryptography usage report.
--max-file-size: Cutoff size for files to be scanned, in bytes (doesn’t apply to ZIP files). Defaults to 1000000 (1MB). If set to 0, the cutoff is disabled.
default): Choices are
default(which means all modules except
jar). May be present more than once to specify multiple modules to use.
--static-scanner-path: The path to the Static Scanner binary, which is needed to run the Host Scanner with
--password: An optional password to be used to attempt decryption of encrypted data.
--allow-secrets-in-trace: Allow secrets to be written inside the output trace. For the moment, it only concerns the password passed using the
--tag: Tag(s) that will characterize the trace to be generated. Can be given several times.
--exclude: Exclude a file or directory from scan. Can be specified multiple times to exclude several files or directories. This is useful e.g. for preventing network filesystem from being scanned.
--max-files-per-second: Limit on the number of files scanned per second. 0 is considered as no limit and is the default value.
--work-load: Limit, as a percentage, on the CPU load of the Host Scanner during its execution. Default value is
--quiet: Print less information. Can be given several times. Opposite of
--verbose: Print more information. Can be given several times. Opposite of
--help: Print a list of all command-line options and an explanation of what they do.
You must either use the
--root option (if the target is a filesystem) or the
--image-name option (if the target is a container image).
To get information about all the options, run:
Here are some configuration examples: