On-demand Scanning

Tip. This feature is only available on GuardMode 2023.1 or higher.

On-demand scanning allows you to perform targeted scans to identify potentially compromised files. This feature is accessible through both the REST API and the Command Line Interface (CLI), providing versatility in managing and executing scans.

What Files are Considered Suspicious?

A file is considered suspicious if:

• It fails both the entropy check and magic number check.

• The file matches the blocklist pattern. (if --check-blocklist flag is enabled)

• There is any error during scanning, e.g., the file cannot be opened because it is locked.

To start a scan, you need to specify the paths of the directories you want to scan, along with flags that dictate the scan's behavior. The scanning process recursively examines all files within the specified directories. If any path is inaccessible due to issues like non-existence, permission restrictions, or pointing to an unmapped drive, it will be marked as an error and skipped. You can find details about such paths through the scan show CLI command or the GET /scans API endpoint.

During the scan, each file is subjected to Entropy and Magic Number checks to assess if it's encrypted. If you set the --check-blocklist flag, filenames are also compared against blocklist patterns. Files matching these patterns are considered encrypted. This blocklist check operates is identical to the blocklist detection strategy, where excluded extensions are considered to bypass the check.

If you choose to receive alerts, notifications will be sent for every suspicious file detected. Information about these files is accessible via the scan show CLI command or the GET /scans/{id}/suspicious-files API endpoint.

Excluded Paths and File Types

Attention! On-demand scanning uses the global excluded files list. This might cause some files to be skipped during the scan.

On-demand scanning ignores the following file types:

• Temporary files

• Hidden files

• Inaccessible files

• Files that are special file types like sockets, device files, etc.

The scanning process only examines regular files, read-only files, and backup archives.

See also. To learn more about excluded paths, see Excluded Paths Configuration.

Executing a Scan

Note. YARA analysis can be enabled for on-demand scans to enhance malware detection capabilities. To enable YARA for on-demand scans, set the checkYaraRules parameter to true in the scan request. For details, see Configuring YARA.

From the CLI

To execute a scan from the CLI, use the scan execute command with the paths of the directories you want to scan. This command allows you to specify if blocklist patterns should be checked and if alerts should be sent for detected suspicious files.

You can run scan execute command, using:

./Catalogic.GuardMode.Agent scan execute <directorypaths...> [options]

Note. You can only use absolute paths. Adding a path containing ../ will result in an error.

The available options are:

• --update-interval: Interval, in seconds, between scan information prompts. Default: 5.

• --check-blocklist: If set, file names will be analyzed during the scan to find files with suspicious names often used by ransomware. Default: False.

• --send-alert-notifications: If true, send out alerts on suspicious files found. Default: True.

The scan provides real-time updates about suspicious files and periodic diagnostic data. If you need to cancel the scan, sending Ctrl-C will stop the process. However, you can still access information about the files that were scanned before the cancellation. Additionally, the status of the scan will be updated to indicate that it was canceled before it could complete the entire scanning process.

From the REST API

To start a scan via the REST API, use the POST /scans endpoint. This action initiates the scan and returns a 202 status code with the scan ID in the Location header.

You can monitor the scan's progress using the GET /scans/{id} endpoint, and details about suspicious files found can be accessed through the GET /scans/{id}/suspicious-files endpoint.

To cancel an ongoing scan, use the POST /scans/{id}/stop endpoint. This action stops the scan but retains information about the files that have already been scanned.

Attention! Scans started from the CLI can only be canceled via the CLI, not via the API.

See also. For more detailed instructions and options, see REST API documentation.

Scanning Windows Shares

For scanning network folders, use Universal Naming Convention (UNC) paths instead of locally mapped drive paths, like:

\\Server1\Shared\Directory

This ensures accurate location tracking and scanning of directories on another machine in the network.