Filesystem Scanner reference

The SandboxAQ Filesystem Scanner (formerly Host Scanner) is a command-line application designed to scan the filesystem or a container image, identifying cryptographic material and logging it in a format suitable for analysis with AQtive Guard.

Scanning

Scanning a filesystem

For information on scanning a filesystem, refer to the Windows or Linux getting started guides.

Scanning a container image

To run the Filesystem Scanner on a container image, substitute the --root option with the --image-name option. For instance:

Bash

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

Note

This feature isn’t available for Windows.

Detecting hard-coded keys and certificates inside JAR files

To detect hard-coded keys and certificates, the Filesystem Scanner invokes the Java Bytecode Scanner to extract hard-coded strings from JAR files.

To run the Filesystem Scanner with the Static Scanner, run:

Bash

./cs-host-scanner \
  --root /path/to/root/directory \
  --output "output_file.cst" \
  --module jar
  --static-scanner-path "path-to-static-scanner"

Tip

While the generated trace only contains keys and certificates found in JAR files, using the --module all option will expand its coverage to include those found in other file types.

Configuration

The Filesystem Scanner is configured through command-line options. For instance, to set the directory where the Filesystem 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

Below is a list of available command-line options:

• -r, --root: Specify the directory path to start searching from if the scan target is a filesystem. The Filesystem Scanner will traverse everything below this designated point. This can be specified multiple times.

• --image, --image-name: The image name if the scan target is a container. This option is also mutually exclusive with the --root and --scan-windows-stores options. That is, you can use one or the other in a single command, but not both.

• -o, --output (required): Specify the file to write the trace to. This is a trace in .cst format, which can be uploaded to the web application and analyzed to generate a cryptography usage report.

• --max-file-size: The cutoff size in bytes for files to be scanned (not applicable to ZIP files). The default is 1000000 (1MB). If set to 0, the cutoff is disabled.

• -m, --module (default: default): The choices are pem, der, ssh, jks, jceks, keys (representing pem, der and ssh), keystore (representing jks and jceks), jar and default (which covers all modules except jar). You can include this more than once to specify multiple modules to use.

• --sc, --static-scanner-path: The path to the Static Scanner binary, required for running the Filesystem Scanner with --module jar.

• -p, --password: An optional password to be used while attempting decryption of encrypted data. This can be specified multiple times.

• --allow-secrets-in-trace: Allow secrets to be included in the generated trace. This only applies to the password provided using the --password command-line option.

• -t, --tag: Assign tags to categorize the generated trace. This can be specified multiple times.

• -x, --exclude: Exclude a file or directory from a scan. Wildcards can be used to specify a pattern:

  • * matches any sequence of characters within a filename.
  • ** matches any sequence of characters within a file path. You can specify this multiple times to exclude several files, directories, or patterns. An example is shown in Multiple file exclusion.

• -l, --max-files-per-second: Set the limit on the number of files scanned per second. The default value is 0 which is no limit.

• -w, --work-load: Define the limit as a percentage on the CPU load of the Filesystem Scanner during its execution. The default value is 100, which is no limit.

• -q, --quiet: Print less information. You can use this option multiple times. The opposite of -v.

• -v, --verbose: Print more information. You can use this option multiple times. The opposite of -q.

• --help: Display a list of all command-line options with an explanation of what they do.

• --scan-windows-stores: Allow the Filesystem Scanner to discover X.509 certificates managed using Windows Microsoft Management Console (MMC). The CurrentUser and LocalMachine locations are scanned and any stores with non-ASCII characters in their name are skipped. Keep in mind that the name of the certificate shown may differ from what is in MMC. The names shown in your session are the true names of the certificate store, while the names shown in MMC are the names of the certificate stores you may reference with the CERT:drive.

• --io-kbps-limit: Set a limit on the IOPS and allow throttling of file I/0 operations. The default is no limit.

Examples

Below are some configuration examples:

Help command

Bash

./cs-host-scanner --help

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

The scanner doesn’t avoid any filesystem by default, but you can use the --exclude option to avoid scanning a network filesystem.

Bash

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

Multiple file exclusion

This example shows how to exclude several files from a scan by specifying multiple exclude patterns:

• Exclude zip files located in any subdirectories of /foo
• Exclude every PEM file no matter which directory they’re in
• Exclude all Thumbs.db files

Bash

./cs-host-scanner \
  --root / \
  --exclude "/foo/**/*.zip" \
  --exclude "**.pem" \
  --exclude "**/Thumbs.db" \
  --output path/to/scan.cst.gz

Note

The * characters need to be escaped with quotes when using a Linux shell.

Tags

Bash

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

Host system antivirus exclusions

Using the Filesystem scanner (formerly Host Scanner) with antivirus monitoring may increase the CPU load on the endpoints by more than 3x. The Filesystem Scanner detects cryptographic assets such as keys and certificates in file systems or container images. This requires scanning a large volume of files, which antivirus software may flag unless exclusions are properly configured.

To maximize scan performance and minimize the impact on system resources, we recommend excluding the scanner process. The following example provides detailed steps and considerations for configuring exclusions in Microsoft Defender Antivirus.

Configuring Microsoft Defender Antivirus

To avoid false positives in Microsoft Defender Antivirus when using the Filesystem Scanner on-premises, you must configure exclusions for file extensions, folder locations, and specific processes.

Configure File and Folder Exclusions

Exclusions prevent Microsoft Defender Antivirus from scanning specified files, folders, or processes. This avoids unnecessary CPU load and potential conflicts.

• Folder Exclusions - Avoid scanning entire directories that contain numerous files unrelated to security threats but necessary for Filesystem Scanner operations. For instance:

  • Windows: C:\Program Files (x86)\cryptosense\
  • Linux: /opt/cryptosense/

• File Exclusions - Target specific executable files related to the Filesystem Scanner to prevent them from being scanned:

  • Windows: C:\Program Files (x86)\cryptosense\bin\cs-host-scanner.exe
  • Linux: /opt/cryptosense/cs-host-scanner

These exclusions can be set up through the Windows Security app or using PowerShell with commands like Add-MpPreference to add exclusions.

More details on managing these settings through PowerShell and Windows Management Instrumentation (WMI) are available in the Microsoft document Configure and validate exclusions based on file extension and folder location.

Note

If you use a different antivirus software, refer to its documentation for specific details and best practices.

Configure Process Exclusions

Excluding specific processes is crucial to ensure that the antivirus doesn’t interfere with background services like those of the Filesystem Scanner.

• Process Exclusions by Path - Use the full path to the executable to ensure accuracy and prevent other potentially malicious programs with the same name from being excluded. For example, using PowerShell:

  • Add-MpPreference -ExclusionProcess "C:\Program Files (x86)\cryptosense\bin\cs-host-scanner.exe"

• Using Wildcards - Wildcards can be used in path exclusions to generalize the exclusions where applicable. Be cautious when using wildcards to avoid overly broad exclusions that might compromise security​​​​.

Configure Exclusions through Group Policy

Managing exclusions through Group Policy offers organizations centralized control over antivirus settings across multiple systems.

• Group Policy Management - This method involves setting antivirus configurations at the group level and provides a robust way to ensure consistent security settings across all endpoints. Detailed instructions for setting up exclusions via Group Policy are found in Microsoft’s official guides​​. Refer to the links at the end of this document.

Regular Review and Adjustment

For optimal performance and security, it’s essential to regularly review and update exclusion settings to adapt to any changes in the file system layout, Filesystem Scanner updates, or antivirus capabilities.

• Review Settings - Review the exclusions list periodically to ensure it still aligns with current operational requirements and doesn’t inadvertently exclude required security scans​​.
• Adjust as Necessary - Modify the exclusions as the system evolves, such as after software updates or changes in system architecture.

Documentation and Compliance

Ensure that all configurations are well-documented and comply with organizational IT security policies. Consider the implications of excluding certain files or processes on the overall security posture of the organization.

Additional information

For more comprehensive guides on configuring and best practices for Microsoft Defender Antivirus, please refer to Microsoft’s official documentation:

• Configure and validate exclusions based on extension, name, or location
• Review or edit your next-generation protection policies