Deploying with CLI

Deploy Trend Vision One™ File Security with the CLI

Integrating into a CI/CD pipeline

Include File Security in your CI/CD pipeline to detect malware before files are distributed to production pipeline or storage. Easily integrate File Security CLI into your continuous integration (CI) or continuous delivery (CD) pipeline. For example, Jenkins® projects can automatically build, test, and push files and applications to production environment. If any malware exist in those files, then they are a risk when the file is run or distributed to other parts of the production pipeline.

File Security CLI is versatile and can be employed in production environments where files are uploaded or distributed by third-party vendors or supply chain partners. It scans any received files to ensure there is no malicious lateral movement within the corporate boundary before allowing them to proceed to other parts of the corporate environment.

Examples of files that can be scanned using File Security CLI include:

Binary Files
Directories with various file types
Large media files
Files received from third party or supply chain partners

Installing File Security CLI

To ensure optimal performance and access to the latest features, we recommend that you install the most recent version of File Security CLI. To check for the latest version, go to metadata.json.

Note

If you are updating to a new version of File Security CLI, you need to adjust your system's binary path settings by doing one of the following:

replacing the existing File Security CLI binary with the updated file binary
modifying your PATH to point to the new File Security CLI binary location

Architecture
Darwin_arm64 (MacOS - Apple Silicon chipset)
Darwin_x86_64 (MacOS - Intel chipset)
Linux_arm64
Linux_i386
Linux_x86_64
Windows_arm64
Windows_i386
Windows_x86_64

Obtaining an API Key

File Security CLI requires a valid API Key stored in the environment variable. It can accept Trend Vision One API keys. Please add the API Key associated with the Trend Vision One region that you wish to call as an environment variable.

macOS and Linux

export TMFS_API_KEY=<your_vision_one_api_key>

Windows Command Prompt (cmd)

set
                        TMFS_API_KEY=<your_vision_one_api_key>

Windows PowerShell

$env:TMFS_API_KEY="<your_vision_one_api_key>"

Note

When obtaining the API Key, associate it with your Trend Vision One region. Use the -- region flag when running File Security CLI to specify the region of that API key and to ensure you have proper authorization. The list of supported Trend Vision One regions can be found under the region flag.

Procedure

Create a new Trend Vision One API key:
1. Navigate to the Trend Vision One User Roles page.
2. Verify that there is a role with the "Run file scan via SDK" permission enabled. If not, create a role by clicking Add Role and then click Save once finished.
3. Directly configure a new key on the Trend Vision One API Keys page, using the role with the "Run file scan via SDK" permission. We recommend that you set an expiry time for the API key and make a record of it for future reference. You can manage these keys from the Trend Vision One API Keys Page.
Add the File Security CLI to your PATH:
- macOS and Linux:export PATH="/path/to/tmfs/binary/directory:$PATH"
- Windows Command Prompt (cmd):setx PATH "%PATH%;C:\path\to\tmfs\binary\directory"
  
  Note
  
  Close and reopen the command prompt for the changes to take effect.
- Windows PowerShell:
```
$pathToAdd = "C:\path\to\tmfs\binary\directory"
[System.Environment]::SetEnvironmentVariable("Path", "$($env:Path);$pathToAdd", [System.EnvironmentVariableTarget]::User)
```
  Note
  
  Close and reopen PowerShell for the changes to take effect.

General usage

For examples of commands using File Security CLI, see the Examples section.

tmfs scan [target] [flags]

Available commands

Command	Description
`scan`	scan a target (file or directory)
`version`	get current CLI version (long)
`help`	help

Command examples

// use region flag and file target
tmfs scan --region us-east-1 file:/Users/XXX/Downloads/eicar.tar.gz --tag "owner=johndoe" --tag "stack=prod"
 
// use endpoint flag and directory target
tmfs scan --endpoint antimalware.us-1.cloudone.trendmicro.com:443 dir:/Users/XXX/Uploads --tag "owner=janedoe" --tag "stack=dev"

Using Command flags

Command Flags

Scope	Flag	Description	Examples
scan command	`-r, -- region`	(string) vision one region options=[us-east-1, eu-central-1, ap-northeast-1, ap-southeast-2, ap-southeast-1]	V1 regions ap-northeast-1 ap-south-1 ap-southeast-1 ap-southeast-2 eu-central-1 us-east-1
scan command	`-- timeoutInSecs`	Timeout in seconds for a single file scan	180
scan command	`-t, -- tag`	Tag to be used for the scan The maximum number of tags is 8 The length of each tag can't exceed 63	--tag "stack=production" --tag "owner=johndoe" --tag "type=OCR" --tag "purpose=customer_upload"
scan command	`--pml`	Specify to enable Predictive Machine Learning (PML).	`--pml true`
scan command	`--feedback`	Specify to enable Trend Smart Protection Network (SPN) feedback.	`--feedback true`
scan command	`--allResults`	only for dir scanning shows all scan results including no malware scanning	`--allResults`
global	`--verbose`	Increase verbosity (-v = info, -vv = debug
global	`-h, --help`	Help

Supported targets

File Security CLI supports both directory and file targets.

Supported Targets

Targets	Description	Notes
`dir:path/to/yourproject`	Reads directly from a path on disk (any directory)	File Security CLI will scan the files in this directory in parallel. The default number of concurrency is 10. Only scans the first level of directories. Only scans regular files, excluding symbolic links, device files, sub directories. The default timeout for the whole process is 15mins.
`file:path/to/yourproject/file`	Reads directly from a path on a disk (any file)

Note

Scans are limited to files less than 1GB for the File Security Preview release.

File Security CLI response payload

The File Security CLI response payload includes parameters for both files and directories.

File

Parameter	Type	Description
scannerVersion	string	The scanner version
schemaVersion	string	The schema version
scanResult	int	Number of malware files found
scanID	string	A unique identifier for the scan
scanTimestamp	string	The timestamp indicating when the scan occurred
fileName	string	The name of the scanned file
foundMalwares	object	An array containing details about the identified malware (if any)
fileSHA1	string	The SHA-1 hash of the scanned file
fileSHA256	string	The SHA-256 hash of the scanned file
foundMalware[].fileName	string	The name of the file in which malware was detected
foundMalware[]malwareName	string	The name or identifier of the detected malware

Example

{
    "scannerVersion": "1.0.0-9271111",
    "schemaVersion": "1.0.0",
    "scanResult": 1,
    "scanId": "6a018277-f969-403d-aa63-eba1223337e1",
    "scanTimestamp": "2023-11-20T18:50:43.663Z",
    "fileName": "./test/eicar-alpine.tar",
    "foundMalwares": [
        {
            "fileName": "malware/eicar.com",
            "malwareName": "Eicar_test_file"
        }
    ],
    "fileSHA1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "fileSHA256": "e5f24b4ac134a7d923ae0f9689b86f015f86edbc3cc95e4c9f9406412914de05"
}

Parameter	Type	Description	Notes
startTime	string	The timestamp indicating when the scan operation started
endTime	string	The timestamp indicating when the scan operation concluded
totalMalwareCount	int	Total malware count of all scan results
scanResults	object	An array containing all scan results	Collects only files containing malware
scanResults[].scannerVersion	string	The scanner version
scanResults[].schemaVersion	string	The schema version
scanResults[].scanResults	int	Number of malware found
scanResults[].scanId	string	A unique identifier for the scan
scanResults[].scanTimestamp	string	The timestamp indicating when the scan was performed
scanResults[].fileName	string	The name of the scanned file
scanResults[].foundMalwares	object	An array containing the details about the identified malware (if any)
scanResults[].SHA1	string	The SHA-1 hash of the scanned file
scanResults[].SHA256	string	The SHA-256 hash of the scanned file
scanResults[].foundMalwares[].fileName	string	The name of the file where malware was detected
scanResults[].foundMalwares[].malwareName	string	The name or identifier of the detected malware

Proxy configuration

File Security CLI loads the proxy configuration from a set of optional environment variables.

Environment Variables

Environment Variable

Required/Optional

Description

NO_PROXY

Optional

Adds the File Security Malware Scanning as a Service endpoints to the comma-separated list of host names. Use if you want to skip proxy settings for File Security CLI.

Note

Use an asterisk * to match all hosts.

HTTP_PROXY

Optional

http://proxy.example.com

HTTPS_PROXY

Optional

https://proxy.example.com

Note

If the proxy server is a SOCKS5 proxy, you must specify the SOCKS5 protocol in the URL. For example, socks5://socks.proxy.com

PROXY_USER

Optional

Username for authentication header used in Proxy-Authorization

PROXY_PASS

Optional

Password for authentication header used in Proxy-Authorization. Used only when PROXY_USER is configured.

Integrating into a CI/CD pipeline

Installing File Security CLI

Note

Obtaining an API Key

Note

Procedure

Note

Note

General usage

Available commands

Command examples

Using Command flags

Command Flags

Supported targets

Supported Targets

Note

File Security CLI response payload

File

Directory

Proxy configuration

Environment Variables

Note

Note