Skip to content

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.

Installation

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.

Usage

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:

Bash
./cs-host-scanner \
  --image-name python:latest \
  --output scan.cst.gz

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:

Bash
./cs-host-scanner \
  --root /path/to/root/directory \
  --output "output_file.cst" \
  --module jar
  --static-scanner-path "path-to-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.

Configuration

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 --output option:

Bash
./cs-host-scanner \
  --root /path/to/root/directory \
  --output path/to/scan.cst.gz

Command-line options

Here is a list of the available options:

  • -r, --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, --image-name: The image name if the scan target is a container.
  • -o, --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.
  • -m, --module (default: default): Choices are pem, der, ssh, jks, jceks, keys (which means pem, der and ssh), keystore (which means jks and jceks), jar and default (which means all modules except jar). May be present more than once to specify multiple modules to use.
  • --sc, --static-scanner-path: The path to the Static Scanner binary, which is needed to run the Host Scanner with --module jar.
  • -p, --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 --password command-line option.
  • -t, --tag: Tag(s) that will characterize the trace to be generated. Can be given several times.
  • -x, --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.
  • -l, --max-files-per-second: Limit on the number of files scanned per second. 0 is considered as no limit and is the default value.
  • -w, --work-load: Limit, as a percentage, on the CPU load of the Host Scanner during its execution. Default value is 100 (no limit).
  • -q, --quiet: Print less information. Can be given several times. Opposite of -v.
  • -v, --verbose: Print more information. Can be given several times. Opposite of -q.
  • --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:

Bash
./cs-host-scanner --help

Examples

Here are some configuration examples:

PKCS#12 Keystore Decryption

Bash
./cs-host-scanner \
  --root /path/to/root/directory \
  --password 'This is a command\-line password' \
  --output path/to/scan.cst.gz

I/O and CPU load limitation

Bash
./cs-host-scanner \
  --root /path/to/root/directory \
  -l 2500 -w 60. \
  --output path/to/scan.cst.gz

Network directory exclusion

Bash
./cs-host-scanner \
  --root / \
  --exclude /path/to/network/directory \
  --output path/to/scan.cst.gz

Tags

Bash
./cs-host-scanner \
  --root /path/to/root/directory \
  --tag "Tag 1" --tag "Tag 2" \
  --output path/to/scan.cst.gz