Getting Started

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

In an on-premise platform scanner CLI should be installed from Xygeni on-premise url.

1. Install the Scanner CLI from On-Premise Url

2. Fetch your Xygeni credentials

3. Run the installation script

4. Run your first scan

5. View the scan results

1. Install the Scanner CLI from on-premise Url

An installation script is provided for automated installation.

For manual installation, the scanner can be downloaded from the https://<xygeni-on-premise-url>/scan/releases GET API endpoint, unzipped, and configured by setting the xygeni api url, your credentials and proxy details (if any is used) in the configuration file conf/xygeni.yml

The recommended, automated way to install the scanner is to use the installation script.

The Xygeni installation scripts provided by Xygeni as a way to speed up your xygeni experience by setting your scanning environment as fast as possible.

Download the script

Run one of the following commands depending on your preferences:

mac/Linux

  curl -sLO https://get.xygeni.io/latest/scanner/install.sh

Windows

2. Fetch your Xygeni account credentials or API token

Active Xygeni account credentials are mandatory to run the script, so make sure you’ve signed up first!

An Access Token, also referred to as an API token or API key, is used by applications such as the Xygeni Scanner or other integrations to access the Xygeni platform's API.

To create an access token in the Dashboard, go to the Settings >>Profile>> Access tokens, then click on the Generate new token button. Go to Generate Token for Scanner and API client for further details.

Describe what the token will be used for, choose the validity period, and select the permissions granted to the token. Click on the Generate button:

Each permission grants the key access to specific API endpoints. Typically, the scanner requires permissions to upload scan results.

Finally, the token is generated:

3. Run the installation script

The variable XYGENI_ONPREMISE_URL refers to the on-premise Xygeni api server, you can get it from api or ask customer platform admin.

The variable XYGENI_TOKEN refers to an environment variable that stores the Xygeni API token. This token will be used to authenticate with the service.

Linux/mac

./install.sh -o -v -t $XYGENI_TOKEN -s $XYGENI_ONPREMISE_URL

Windows

For a list of available options, execute ./install.sh --help on Unix-based systems or PS .\install.ps1 --help on Windows.

4. Run your first scan

Once Xygeni Scanner CLI is installed an scan can be run, 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 --repository <image>

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

When run in an on-premise configuration and scans typically run in local network with a git server (Github Enterprise, Gitlab Server), GITHUB_TOKEN and GITLAB_TOKEN should be retrive from the local git server if any of these.

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

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

5. View scan results

After the scan is done, log into the Dashboard, use the on-premise url https://-on-premise-hostname-/auth/login to access the Xygeni on-premise 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.