Quick start with Xygeni CLI

A Scan is the action performed by the Xygeni Scanner to find security issues in your project.

If you are planning to use the local CLI for a quick scan to validate how everything works, an easier way to do a quick installation and scaner could be done with the GUI wrapper following instructions at Quick start with Xygeni GUI

If you still want to deploy the CLI for full control from your workstation, you can follow the steps below:

1. Install the Scanner CLI

2. Fetch your Xygeni credentials

3. Set the XYGENI_TOKEN Variable

4. (Recommended) Add the scanner folder to path

5. Run your first scan

6. View the scan results

Xygeni CLI

1. Install the Scanner CLI

Please see Xygeni CLI Prerequisites before installing.

Download the Scanner

Run the one of the following which better matches your preferences:

mac/Linux

curl -sLO https://get.xygeni.io/latest/scanner/xygeni-release.zip

Windows

Or go to https://get.xygeni.io and dowload it manually.

Verify the integrity of the script

Xygeni publishes a SHA-256 checksum of published components in the xygeni/xygeni GitHub repository, so you may verify the integrity of a downloaded artifact.

This GitHub repository website is hosted in a completely different platform from the download site. Hackers need to compromise two different sites to keep tampered components, like the scanner or the installation script, undetected by the checksum verification.

To ensure that the downloaded installation script checksum matches the checksum published in Xygeni repository, meaning that probably it was not tampered with:

mac/Linux

echo "$(curl -s https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/xygeni-release.zip.sha256) xygeni-release.zip" | sha256sum --check

If under macOS, as sha256sum is probably not installed in your host, you may:

1. read this to install it,

2. or use shasum -a 256 instead or sha256sum if the shasum command is installed,

echo "$(curl -s https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/xygeni-release.zip.sha256) xygeni-release.zip" | sha256 -a 256 --check

1. or use openssl to compute the SHA-256 checksum of the installation script and compare it with the published checksum.

Windows

Unzip the scanner

Unzip the Xygeni Scanner zip that you have just downloaded to a new folder.

mac/Linux

If unzip command is not available you can use:

sudo apt install unzip

unzip xygeni-release.zip -d /destination/path

Windows

2. Fetch your Xygeni API token

Active Xygeni account credentials are mandatory to run the script, so make sure you’ve signed up first! Visit Create a Free Trial account or Log in to Xygeni

Go your profile pannel and navigate to Organization/Personal Tokens:

Create a new token. The difference betweeen Organization tokens and Personal tokens is who can see and revoke those tokens. Select either one and generate a new token.

In order to run scans, the only permission that is needed is the "Upload scan results" permission. However, if you want to use the same token with the REST API, you’ll need to grant it additional permissions.

3. Set XYGENI_TOKEN environment variable

In order to run scans, a new environment variable must be set, the name of this variable must be "XYGENI_TOKEN" and it content has to be the token that was created in the previous step.

mac/Linux

nano ~/.bashrc

Add this line at the end of the file:

export XYGENI_TOKEN="<TOKEN>"

Apply the changes:

source ~/.bashrc

Windows

This will create the XYGENI_TOKEN environment variable for the current user.

4. (Recommended) Add the scanner folder to path

In order to execute the Xygeni application as another command, the Xygeni Scanner folder must be added to the path.

This step is optional but highly recommended to facilitate future scans.

mac/Linux

nano ~/.bashrc

Add this line at the end of the file:

export PATH="$PATH:/Path/To/Scanner"

Apply the changes:

source ~/.bashrc

Windows

This will modify the Current User Path.

5. Run your first scan

To begin, ensure that you have a file system folder containing your project content. This folder may be a clone of your repository or simply a directory housing the source code for your project.

Navigate to your project directory, with the command cd /my/project. Once there, initiate a scan by running xygeni scan. All vulnerabilities identified are listed, including their path and fix guidance.

$ cd /my/project
$ xygeni scan 

You can also use these commands below for other cases:

# Assuming that $XYGENI_HOME in path or xygeni shortcut set
# Scan a directory
$ xygeni scan -n <your_project_name> --dir <path_to_analyze>

# Scan a repository
$ xygeni scan --repository <repo_url>

# Scan a container image
$ xygeni scan --image <image> [--image-platform <platform>]

# You may add --no-upload to the scan command if you want to view
# the results before uploading to Xygeni platform. 

IMPORTANT: In case you want the scanner performs checks against your repository and organization (See CI/CD Misconfigurations Detection), ensure that you provide your SCM and/or CI/ CD systems tokens to the scanner.

Usually, the preferred option is to pass the token in an environment variable (like GITHUB_TOKEN or GITLAB_TOKEN).

See SCM and CI/ CD tokens to know more about this topic.

See Xygeni Scanner Reference for the full scanner command-line reference.

6. View scan results

After the scan is done, log into the Dashboard and navigate to the Governance tab to access the Security Posture Summary screen.

Go to Xygeni Web UI for a guide to browse the dashboard.