Highlight Automated Code Scan (Command Line)

This page details how to automate source code scans by leveraging the Highlight command line and integrating it within your build or CI/CD environments.  This will allow you to continuously track and monitor software health and cloud readiness of your projects and applications. For any questions not addressed in this documentation, don’t hesitate to contact our support team.

Before getting started…

What is a Command Line?

For those who are not familiar with this concept, the Highlight command line is a Java binary which can be programmatically run using scripts and/or automated tasks. It replaces the Local Agent user interface using options you can configure in order to automate the code scan and results upload. In other words, you can configure the command line once to automatically scan the source code of a folder multiple times.  You can also exclude (for instance) some technologies/folders you don’t want to scan, and upload the results automatically to the SaaS platform on a regular timeline (e.g., every sprint/release).

Also, note that you can also run the command line as a Docker container. Our Docker is especially recommended for MacOS users.
Download the Command Line 5.4.19
5046

Please read and accept the license agreement prior to downloading the command line.

I have read and agree with the end-user license agreement

How to use the command line

Examples

Find below some examples of options you can reuse for your own code scan configuration.

A simple code scan of a Windows folder

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src"  --skipUpload

A simple code scan of a Linux folder

java -jar HighlightAutomation.jar --workingDir "/home/user/highlight-myproject/" --sourceDir "/home/user/svn/myproject/src/"  --skipUpload

Scan only specific technologies (e.g. Java and Python)

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --technologies "Java,Python" --skipUpload

Exclude folders with a specific string (e.g. test, jquery)

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignoreDirectories "test,jquery" --skipUpload

Exclude paths with a specific pattern (e.g. vendor/js)

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignorePaths ".*\/vendor\/js" --skipUpload

Scan and automatically upload results to the platform

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --login "john.doe@acme.com" --password "*******" --applicationId 1234 --companyId 5678 --serverUrl "https://rpa.casthighlight.com"

Exclude files from the scan if they contain “foo” in the file name independently of the extension

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignoreFiles ".*foo.*" --skipUpload

Exclude files from the scan if they contain “foo” name and have a .js extension

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignoreFiles ".*foo.*\.js" --skipUpload

Exclude files from the scan based on a specific file extension (e.g. .vue)

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignoreFiles ".*\.vue" --skipUpload

Command Line Options

--help
 Displays the different options
--printTechnos
 Print the supported technologies (e.g. Java, Python, COBOL, etc.)

Scan Options

--sourceDir (mandatory)
 The absolute path to the directory that contains the source code to be scanned by Highlight.
--workingDir (mandatory)
 This is the absolute path to the Highlight working directory. Within this directory, a Highlight temporary folder ("HLTemporary") will be created and will contain scan result files (CSVs). To make it short, this is the directory where you want to store scan results.
--technologies (optional)
 Technologies you want to explicitly scan in your sources. Separated by "," and sorted by preferences (See --printTechnos option above).
--ignoreDirectories (optional)
 Directory name patterns to ignore during the scan (e.g. test folders, .git, etc.). Separated by ",". Source code within directories matching with these patterns will be automatically excluded from the scan.
--ignorePaths (optional) List of regular expressions to ignore paths. Source code within directories matching with this regexp will be automatically excluded from the scan.

--ignoreFiles (optional)
List of regular expression to ignore file names. Separated by ",". Files matching with these patterns will be automatically excluded from the scan. Example to exclude all files containing "foo" with a .js extension: --ignoreFiles ".*foo.*\.js"
--analyzerDir (optional) Alternate directory for Highlight's analyzer scripts.
--perlInstallDir (optional)
 Directory of perl installation (default: C:\Program Files\CAST\HighlightAgent\COTS\strawberry-perl-5.12.3.0).
--keywordScan (optional)
 Path and filename of your KeywordScan XML configuration file (e.g. C:\temp\KeywordScanner_GDPR.xml). Read this post for more information on the feature.
--skipUpload (optional)
 Will generate CSV results only, no result upload will be performed.
--analyzeBigFiles (optional)
 Will bypass the file size limitation of the analyzers (will eventually take longer to scan).
--allowGeneratedCode(optional)
Will bypass the default exclusion of generated code files.

Upload Options

Below are the required options to use when you want to automatically upload scan results to the Highlight platform. Then, the option “–skipUpload” should be removed.

--login (mandatory)
 Login of an active Highlight user.
--password (mandatory)
 Password for the login indicated above.
--basicAuth
Alternatively to login/password, you can use this option to pass your credentials encoded in base64
--tokenAuth
Alternatively to Basic authentication, you can use this option to pass your OAuth token

--companyId (mandatory) Identifyer for the company (can be retrieved from the Highlight portal, it is the ID displayed in the url when clicking on the top-level domain in "MANAGE PORTFOLIO > MANAGE APPLICATIONS" from the menu).
--applicationId (mandatory)
 Identifyer for the application (can be retried from the Highlight portal, it is the ID displayed in the url when editing an application in "MANAGE PORTFOLIO > MANAGE APPLICATIONS").
--serverUrl (mandatory)
 The Highlight server instance where the results has to be uploaded (user credentials have to work on this server). E.g. 'https://rpa.casthighlight.com'
--snapshotDatetime (optional)
 Time (epoch) to use for uploaded application snapshot.
--snapshotLabel (optional) The application snapshot label you want to display on the application result page on the portal (e.g. release version, build number, etc.).

Log files

The log file (HLAutomation.log) is produced after the command line is run and is stored in the working directory (–workingDir) that has been set in the options.

Requirements

For Windows
Java 11 and above is required.

Prior using the command line, it is preferable to install the Highlight Local Agent on your machine, in order to embed the required Perl binaries. Alternatively, you can install the required Perl distribution (Strawberry) if you don’t want to install the Local Agent. The Local Agent can be downloaded from your Highlight user account, in the APPLICATION SCANS page.

 

For Linux Debian/Ubuntu

The following components must be installed on your machine: Perl 5 (tested on Strawberry 5.12.3.0), libjson-perl, libxml-libxml-perl

$>perl -v
on debian/ubuntu systems
$>dpkg –get-selections libxml-libxml-perl libjson-perl

Java 11 and above
$>java -version

 

For Linux – RHEL/CENTOS based systems

Install the libraries: perl-XML-LibXML, perl-JSON and perl-Digest-SHA

$>yum -y install perl-Digest-SHA
$>yum -y install perl-JSON
$>yum -y install perl-XML-LibXML
$>yum -u install perl-Time-HiRes
$>yum -u install perl-Math-BigInt

 

For MacOS

For MacOS users, using our Docker image is recommended to run the command line as a container.

$>perl -v

$>cpan install XML::LibXML
$>cpan install JSON

Troubleshooting
CLI error codes


0
– Ok

1 – Command Line general failure
2 – Command Line options parse error
3 – Command Line techno discovery error
4 – Command Line analysis error
5 – Command Line result upload error
6 – Command Line source dir or output dir validation error
7 – Command Line result saving to zip file error
8 – Command Line upload from zip file error

 

CLI logs

Running the command line will create an HLAutomation.log that contains traces of a scan. This file is located in the specificed working directory (–workingDir).

 

Generated Code exclusion

By default, the command line excludes files that are known as generated code. These files are following the patterns below. In case you would want to scan these files, use the –allowGeneratedCode option.

*.designer.vb, *.designer.cs, *.reference.cs, *.reference.vb

Integration Templates & Tutorials

Feature Focus: How to automatically generate a License Risk Profile based on the CAST Highlight license rulebook

In CAST Highlight, you can manually or automatically create custom License Risk profiles that will specify the level of risk of licenses detected in the Open Source components your applications use. This article explains how to define a License Risk profile that can be automatically generated based on the license terms (rulebook).

Feature Focus: Open Source License Rulebooks

CAST Highlight now displays open source licenses terms, permissions, and constraints in a user-friendly manner: the license rulebooks. This article explains how to access this information from the dashboard to quickly understand the legal implications of OSS component licenses.

Feature Focus: How to exclude a CloudReady Blocker from CAST Highlight results

In some specific contexts, CAST Highlight will identify CloudReady Blockers in the code of an application that are not actually cloud migration blockers if they are addressed through some other method (e.g., infrastructure configuration). This article explains how to exclude Blockers from the results of an application and how this impacts the CloudReady scores.

How to install and use CAST Highlight SCA browser extension

Get Open Source component information (vulnerabilities, license risk, allow/deny status, available versions, etc.) directly in Chromium-based browsers when visiting repository pages on npmjs, nuget, github, packagist websites. This article explains how to install and use our SCA browser extension.

How to retrieve your CAST Highlight company identifier (companyId)

In order to use CAST Highlight API, command line and other tools, you need to know what is your company identifier. This article explains how to retrieve it from the CAST Highlight dashboard.

API change notice on getting application snapshot results

In order to improve performance of the API, we’re slightly changing the default returned result of the following endpoint: GET WS2/domains/{domainId}/applications/{applicationId} Instead of returning the last 10 snapshot results of an application by default, the API will now return the last snapshot only. This change will be effective as of November 6th 2021. To fetch […]

Feature Focus: Portfolio Advisor for Open Source, an automated and smart way to segment an application portfolio better prioritizing third-party component risks

We are very proud to present the Portfolio Advisor for Open Source which joins the growing family of Portfolio Advisors that have already been released for Cloud and Technical Debt. This capability automatically segments a portfolio of applications and identifies Open Source risk priorities for each application by combining unique Software Intelligence insights. Learn more about how the capability works in this article.

Feature Focus: Custom Portfolio Segmentation

Similar to the recent Portfolio Advisors for Cloud and Open Source, this capability allows portfolio managers to create their own custom portfolio segmentations based on a combination of Software Intelligence insights available in CAST Highlight. This article describes how it works and how to use this capability.