About Trend Micro Artifact Scanner (TMAS)

Trend Micro Artifact Scanner (TMAS) is an artifact scanner from Trend Micro. It performs pre-runtime scans on artifacts (see Supported artifacts), enabling you to identify and fix issues before they reach the production environment such as, for example, Kubernetes for container images.

TMAS can perform open source vulnerability scanning. The vulnerability database receives up-to-date threat data from open source vulnerability feeds. The scanner can find vulnerabilities in the following operating systems:

• Alpine
• Amazon Linux
• BusyBox
• CentOS
• Debian
• Distroless
• Oracle Linux
• Red Hat (RHEL)
• Ubuntu

The scanner can find vulnerabilities in the code of the following programming languages:

• Ruby (Gems)
• Java (JAR, WAR, EAR, JPI, HPI)
• JavaScript (NPM, Yarn)
• Python (Egg, Wheel, Poetry, requirements.txt and setup.py files)
• Dotnet (deps.json)
• Golang (go.mod)
• PHP (Composer)
• Rust (Cargo)

How does TMAS fit into a CI/CD pipeline?

TMAS can be integrated into your continuous integration (CI) or continuous delivery (CD) pipeline.

For example, Jenkins projects can automatically build, test, and push Docker images to a Docker registry. Once pushed, the image may be instantly available to run in an orchestration environment. If open source vulnerabilities exist in the image, then they are a risk when the image is run. Since images are intended to be immutable, images should be scanned before they are deployed to a cluster.

TMAS scans artifacts inside your CI/CD pipelines. You can install the TMAS CLI into your CI/CD pipeline to perform vulnerability scanning before artifacts are deployed to production. TMAS takes the artifact that you wish to be scanned and generates a Software Bill of Materials (SBOM). It then uploads the SBOM to Trend Cloud One for processing and returns a vulnerability report.

Examples of artifacts that TMAS can scan include the following:

• Container Images

• Binary Files

• Directories with source code

• OCI Archives

Download and install

You can check the latest version via metadata.json.

System requirements

The minimum system requirements outlined in the following table are sufficient to scan most artifacts.

Your system must have enough storage capacity to accommodate the size of your target artifact. For images, your system must have sufficient space for its uncompressed size.

Memory consumption of the TMAS CLI scales with the number of files an artifact contains. Some artifacts may require additional memory to complete successfully. Performance can be improved by increasing memory resources.

Upgrade to the latest version of the TMAS CLI

To ensure optimal performance and access to the latest features, upgrade to the most recent version of TMAS on a regular basis, as follows:

1. Download the updated binary. Links to download the latest version of the TMAS CLI are provided in Download and install.

2. Adjust your system's binary path settings by replacing the existing TMAS binary with the updated TMAS binary. For information, see the Add TMAS CLI to your PATH step described in Set up.

TMAS is now successfully updated to the latest version.

Set up

The TMAS CLI requires a valid API key to be stored in the environment variable. Add the API key associated with the Trend Cloud One region that you wish to call as an environment variable TMAS_API_KEY, as follows:

export TMAS_API_KEY=<your_cloud_one_api_key>

Note that the TMAS CLI can also be used in Trend Vision One. For more information, see About Trend Micro Artifact Scanner in Trend Vision One.

Obtain a Trend Cloud One API key:

1. Log in to the Trend Cloud One console.
2. Navigate to Container Security > Scanners.

3. Create a new API key through any of the following options:

   • Generate a new key through the Trend Cloud One Container Security Scanners page, as per the following illustration:

   

   • Directly configure a new key on the Trend Cloud One API Keys page, as follows:

   • Navigate to the Trend Cloud One Administration page.
     

   • Verify that the scanner role exists; if not, create a new scanner role, as per the following illustration:

   

   • Configure a new API key using the scanner role, as per the following illustration:

   

When obtaining the API key, ensure that the API key is associated with the endpoint you are calling. For instance, create an API key in a us-1 account if you are planning to call the us-1 region endpoint to ensure proper authorization.

You manage these keys from the Trend Cloud One Administration console.

Add TMAS CLI to your PATH:

export PATH="/path/to/tmas/binary/directory:$PATH"

General usage

tmas [command] [flags]

Available commands

Global flags

Scan command usage

tmas scan [artifact] [flags]

Scan command flags

Supported artifacts

Scans are limited to artifacts for which the generated SBOM data is less than 10 MB. The malware scan only supports docker, docker-archive, oci-archive, oci-dir and registry artifact types.

Examples

Scanning an artifact:

tmas scan <artifact_to_scan> --region us-1

Using the required region flag to switch to a different Trend Cloud One region:

tmas scan docker:yourrepo/yourimage:tag --region au-1

When switching to a different region, ensure that the TMAS_API_KEY, which is stored as an environment variable, is associated with that Trend Cloud One region. A mismatch causes the scan command to fail with a 403 Forbidden or APIKeyPlatformMismatchError error.

Scanning an image in a remote registry:

tmas scan registry:yourrepo/yourimage:tag --region us-1

Using a registry as an artifact source does not require a container runtime. In addition, scan results from registry artifact sources can be used for policy evaluations in Trend Cloud One Container Security.

Scanning images from private registries requires that you login to the registry using tools such as docker login before attempting the scan. TMAS follows Docker's authentication behavior in order to use Docker's pre-configured credentials.

Enabling info mode:

tmas scan docker:yourrepo/yourimage:tag --region us-1 -v

Saving SBOM used for vulnerability analysis to disk:

tmas scan docker:yourrepo/yourimage:tag --region us-1 --saveSBOM

When the --saveSBOM flag is enabled, the generated SBOM is saved in the local directory before it is sent to Trend Cloud One for scanning.

Using the platform flag to specify platform or architecture of container images:

This flag allows you to specify which platform or architecture to use when scanning multiple-architecture container images:

tmas scan registry:yourrepo/yourimage:tag@sha256:<multiple-architecture-digest> --region us-1 --platform=arm64

Attempting to specify an architecture for multi-arch registry images without support for that architecture will result in an error. When scanning architecture-specific registry images, the platform flag is ignored:

tmas scan docker:yourrepo/yourimage:tag@sha256:<arm64-specific-digest> --region us-1 --platform=arm64

This flag is necessary when attempting to scan images from the Docker or Podman daemon with different architectures than the host that is running TMAS.

Enabling malware scan:

tmas scan docker:yourrepo/yourimage:tag --region us-1 --malwareScan

When scanning images from private registries with the --malwareScan flag enabled, ensure that you have already logged into the registry using tools such as docker login.
If you are using docker credsStore (.docker/config.json), add the credential-helpers=<your credsStore> in .config/containers/registries.conf. For example, if docker credsStore is desktop, add the following:

credential-helpers = ["desktop"]

Overriding vulnerability findings:

tmas scan <artifact_to_scan> --override path/to/tmas_vuln_overrides.yml

Override false positives or other vulnerability findings you wish to ignore. For more information, see Override vulnerability findings.

Scan subcommands

tmas scan [subcommand] [artifact] [flags]

Vulnerability subcommand

Scanning an artifact:

tmas scan vulnerabilities <artifact_to_scan>

Malware subcommand

Note the following:

• Results from the malware subcommand are not included in the Container Security admission control evaluation. Use the combined vulnerability and malware scanner tmas scan --malwareScan to include malware results in admission control evaluation.
• Malware scans only support docker, docker-archive, oci-archive, oci-dir and registry artifact types.

Scanning an artifact:

tmas scan malware <artifact_to_scan>

Proxy configuration

The CLI tool loads the proxy configuration from the following set of optional environment variables:

Clean up temporary files

Each scan initiated against a registry image using the Trend Micro Artifact Scanner generates a new temporary directory under $TMPDIR to download and analyze the image.

For version 1.35.0 and later, this tool automatically removes those temporary files after scan execution. To clean up existing temporary files that were generated with prior versions or by an interrupted scan, use the following commands (or its platform equivalent) under your discretion:

echo $TMPDIR
ls $TMPDIR | grep "stereoscope-"
cd $TMPDIR && rm -rf ./stereoscope-*
ls $TMPDIR | grep "stereoscope-"

Override vulnerability findings

If TMAS reports a vulnerability which has been determined to be a false positive or any other vulnerability finding you wish to ignore, you may instruct TMAS to override these findings by defining one or more rules in an override configuration file (for example, ~/tmas_vuln_overrides.yml).

You may then execute a scan using these rules by providing TMAS with a path to the override file using the --override flag.

tmas scan <artifact_to_scan> --override path/to/tmas_vuln_overrides.yml

The override file is structured as a list of rules. Each rule can specify any combination of the following criteria:

• Vulnerability ID (for example, "CVE-2008-4318")
• Fix state (allowed values: "fixed", "not-fixed", "wont-fix", or "unknown")
• Package name (for example, "libcurl")
• Package version (for example, "1.5.1")
• Package type (for example, "npm", "go-package", "rpm", or any package type appearing in the TMAS JSON vulnerability report)
• Package location (for example, "/usr/local/lib/node_modules/**"; supports glob patterns)

Each rule must also be accompanied by a reason indicating why the rule was implemented (for example, "false positive", "mitigated", "vulnerable package function is not called", and so on).

vulnerabilities:
  # This is the full set of supported rule fields:
  - rule:
      vulnerability: CVE-0000-0000
      fix-state: unknown
      package:
        name: libcurl
        version: 1.5.1
        type: npm
        location: "/usr/local/lib/node_modules/**"
    reason: A descriptor specifying why the override rule implemented

A given vulnerability finding is overridden if any of the rules specified in the override file apply to the finding. A rule is considered to apply to a finding only if all the fields in the rule match those found in the vulnerability finding.

vulnerabilities:
  # Override vulnerability findings whose CVE-ID is CVE-0000-0000
  - rule:
      vulnerability: CVE-0000-0000
    reason: Not executed

  # Override vulnerability findings detected on libcurl version 1.5.1
  - rule:
      package:
        name: libcurl
        version: 1.5.1
    reason: Dev dependency

Any vulnerability finding that matches a rule is presented in the JSON report in an "Overridden" section, rather than classified under its severity.

{
  "totalVulnCount": 1,
  "criticalCount": 0,
  "highCount": 0,
  "mediumCount": 0,
  "lowCount": 0,
  "negligibleCount": 0,
  "unknownCount": 0,
  "overriddenCount": 1,
  "findings": {
    "High": [],
    "Low": [],
    "Medium": [],
    "Negligible": [],
    "Overridden": [
      {
        "name": "libcurl",
        "type": "npm",
        "version": "1.5.1",
        "id": "CVE-0000-0000",
        "source": "https://nvd.nist.gov/vuln/detail/CVE-0000-0000",
        "severity": "Low",
        "fix": "not-fixed",
        "locations": ["/usr/local/lib/node_modules/**"],
        "cvssSummaries": [],
        "relatedVulnerabilities": []
      }
    ]
  }
}