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).

Download the Command Line 5.0.20
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 pattern (e.g. test, jquery)

java -jar HighlightAutomation.jar --workingDir "C:\highlight-myproject" --sourceDir "C:\myproject\src" --ignoreDirectories "test,jquery" --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"

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.
--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.

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.
--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
Prior using the command line, you’ll have to install the Highlight Local Agent on your machine, in order to embed the required Perl binaries. The Local Agent can be downloaded from your Highlight user account, in the APPLICATION SCANS page.

 

For Linux

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 8
$>java -version

 

For MacOS (tested on Sierra)

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

$>perl -v

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

Integration Templates & Tutorials

Good practices when defining the scope of a code scan

In this post, we have compiled a few good practices to keep in mind when scanning a code base with CAST Highlight in order to let you consume the most consistent software analytics possible, depending on your use case (software health, open source detection for license compliance or vulnerability checks, etc.).

How OSS licenses are mined and detected in Highlight’s Software Composition Analysis feature

CAST has developed unique algorithms to mine and detect licenses from Open Source components to let you get a (more accurate) sense of IP and legal impacts your software is exposed to. Here is how it works.

How to detect apps using Oracle’s JDK 1.8 (and others) at the portfolio level

As you probably already know, Oracle announced a major change of their release and support rules for Java. This article is not meant to explain how that’s going to work now, but long story short you’ll have to either a) update your JDK very fast; b) be exposed to unpatched (and perhaps vulnerable) Java versions […]

The Power is Yours: Custom Indicators

In case you missed it, the CAST Highlight last release notes announced many great new capabilities. We’re proud and excited to include Software Composition Analysis (SCA) as a compelling new feature, which brings a new angle to our Application Portfolio Analysis foundation. In addition to SCA, this release includes another game-changing capability – custom indicators. This blog will cover how to implement and use this great new feature.

How to estimate size and health of high frequency code iterations using the delta analysis feature

The "Application Trends" feature (also known as delta analysis) dramatically increases the value of using Highlight in an Agile context. In a nutshell, Highlight now computes software health scores and metrics of scanned source files based on their status, whether they have been added or modified during the last iteration. This post will explain how [...]

How to configure a Keyword Scan for GDPR (or anything else)

In this product tutorial, we'll see how to configure and take advantage of the Keyword Scan feature to support a GPDR assessment of your application portfolio. The feature can be used to search for any kind of keywords (API secret token or passwords in clear text for instance) but really makes sense in a GPDR [...]

How to run the Highlight Command Line from Apache Ant

Let’s in this article how to clone a repository from Github and run Highlight’s analyzers from Apache Ant, and upload scan results to the portal and quickly get unprecedented software Analytics.

How to integrate Highlight’s Command Line in a Jenkins Pipeline

As the Highlight command line is a real hit across users who want to automate the scan of their code bases, we thought it could be helpful to provide a series of templates and code samples for the different build tools where you would integrate our code scans. The script below illustrates how to integrate the command line within a Jenkins pipeline.