Skip to main content

Tool - ctx-scan

The command line ctx-scan tool imitates a classic malware scanner - submits files for processing by Contextal Platform, and outputs the results based on the actions, marking files as clean or malicious. It can be used to integrate Contextal Platform with services, that have an interface for running 3rd party malware scanners.

Installation​

The tool is part of the contextal package:

pip install contextal

Usage​

To use the tool, you need to configure access to Contextal Platform - please refer to ctx tool examples on how to create profiles.

Available Options​

$ ctx-scan -h
usage: ctx-scan [-h] [--recursive] [--max-dir-recursion MAX_DIR_RECURSION]
                [--ttl TTL] [--max-object-recursion MAX_OBJECT_RECURSION]
                [--org ORG] [--profile PROFILE]
                [--actions-priority ACTIONS_PRIORITY]
                [--ignored-actions IGNORED_ACTIONS] [--report-all] [-i]
                path

positional arguments:
  path                  File or directory to submit

options:
  -h, --help            show this help message and exit
  --recursive           Scan directories recursively (default: False)
  --max-dir-recursion MAX_DIR_RECURSION
                        Maximum depth directories are scanned at (default: 15)
  --ttl TTL             Number of seconds allowed to fully complete this work
                        request (optional) (default: 300)
  --max-object-recursion MAX_OBJECT_RECURSION
                        Depth limit for processing nested objects (default:
                        None)
  --org ORG             Organization identifier (default: None)
  --profile PROFILE     Platform configuration profile to use (default: None)
  --actions-priority ACTIONS_PRIORITY
                        The list of actions ordered from highest to lowest
                        priority, which can be reported. Actions not listed
                        here will be ignored (default:
                        ALLOW,BLOCK,QUARANTINE,ALERT,SPAM)
  --ignored-actions IGNORED_ACTIONS
                        Comma separated list of actions that should not be
                        reported (default: ALLOW)
  --report-all          Report all triggered actions. By default the highest
                        priority action, which is not set as ignored, gets
                        reported (default: False)
  -i, --infected        Print only infected files (default: False)

Scan Single File​

$ ctx-scan notepad.exe
notepad.exe: Clean
$ ctx-scan invoice-240912.lnk
invoice-240912.lnk: Contextal-Action-BLOCK: Suspicious LNK
note

In the default configuration, if one or more ALLOW actions is present, the tool will automatically ignore all actions, and report the file as clean. The ALLOW action has the highest priority and is ignored at the same time - this is used as a whitelisting mechanism to make sure that data matching specific criteria always gets through, and can be used both to avoid and address false positive alerts.

tip

By default, only single action with the highest priority will be reported for "infected" files. You can change that with the --report-all switch, however in that case you should handle the logic for the ALLOW action on your own.

Scan Directory​

Recursively scan directory and provide an organization identifier that will be assigned to all input objects:

ctx-scan --org "Contextal:ctx-scan" /some/dir
tip

Organization identifiers can help distinguish data from different sources submitted to Contextal Platform. You can fully customize them and use to mark data coming from different customers or feeds.