# 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](https://docs.xygeni.io/getting-started/quick-start-with-xygeni-gui "mention")

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](#id-1.-install-the-scanner-cli)
2. [Fetch your Xygeni credentials](#fetch_your_xygeni_account_credentials_or_api_token)
3. [Set the XYGENI\_TOKEN Variable](#id-3.-set-xygeni_token-environment-variable)
4. [(Recommended) Add the scanner folder to path](#id-3.-set-xygeni_token-environment-variable)
5. [Run your first scan](#id-5.-run-your-first-scan)
6. [View the scan results](#id-6.-view-scan-results)

## Xygeni CLI

### 1. Install the Scanner CLI

{% hint style="info" %}
Please see [Xygeni CLI Prerequisites](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/xygeni-cli-prerequisites) before installing.
{% endhint %}

#### Download the Scanner  <a href="#download_the_script" id="download_the_script"></a>

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

{% tabs %}
{% tab title="mac/Linux" %}

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

{% endtab %}

{% tab title="Windows" %}

```
 iwr https://get.xygeni.io/latest/scanner/xygeni-release.zip
```

{% endtab %}
{% endtabs %}

Or go to [https://get.xygeni.io](https://get.xygeni.io/) and dowload it manually.

#### Verify the integrity of the script <a href="#verify_the_integrity_of_the_script" id="verify_the_integrity_of_the_script"></a>

Xygeni publishes a SHA-256 checksum of published components in the [xygeni/xygeni GitHub repository](https://github.com/xygeni/xygeni#current-checksums), so you may verify the integrity of a downloaded artifact.

{% hint style="info" %}
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.
{% endhint %}

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

{% tabs %}
{% tab title="mac/Linux" %}

```shell
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](https://unix.stackexchange.com/questions/426837/no-sha256sum-in-macos) to install it,&#x20;
2. or use `shasum -a 256` instead or `sha256sum` if the `shasum` command is installed,

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

3. or use `openssl` to compute the SHA-256 checksum of the installation script and compare it with the published checksum.
   {% endtab %}

{% tab title="Windows" %}

```
(Get-FileHash '.\xygeni-release.zip' -Algorithm SHA256).Hash -eq `
  (iwr https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/xygeni-release.zip.sha256)
```

{% endtab %}
{% endtabs %}

### Unzip the scanner

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

{% tabs %}
{% tab title="mac/Linux" %}
{% hint style="info" %}
If unzip command is not available you can use:

```
sudo apt install unzip
```

{% endhint %}

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

{% endtab %}

{% tab title="Windows" %}
Open a Windows PowerShell cmd and use the following command:

```
Expand-Archive -Path "C:\path\to\xygeni-release.zip" -DestinationPath "C:\Destination\Path"
```

{% endtab %}
{% endtabs %}

### 2. Fetch your Xygeni API token <a href="#fetch_your_xygeni_account_credentials_or_api_token" id="fetch_your_xygeni_account_credentials_or_api_token"></a>

{% hint style="info" %}
Active Xygeni account credentials are mandatory to run the script, so make sure you’ve signed up first! Visit [Create a Free Trial account](https://docs.xygeni.io/getting-started/create-a-free-trial-account) or [Log in to Xygeni](https://docs.xygeni.io/getting-started/log-in-to-xygeni)&#x20;
{% endhint %}

Go your [profile pannel](https://in.xygeni.io/dashboard/configuration-panel/profile) and navigate to Organization/Personal Tokens:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2FplOAz4xfcFed57vWYHqt%2Fimage.png?alt=media&#x26;token=1ba5b166-5a4f-43ee-986f-57acaafe638c" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2F4ARe0CLsTAXOydcoO6v9%2Fimage.png?alt=media&#x26;token=818ca53a-1300-48a8-bad2-0c35acb7f598" alt=""><figcaption></figcaption></figure>

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.

{% tabs %}
{% tab title="mac/Linux" %}

```
nano ~/.bashrc
```

Add this line at the end of the file:

```
export XYGENI_TOKEN="<TOKEN>"
```

Apply the changes:

```
source ~/.bashrc
```

{% endtab %}

{% tab title="Windows" %}

```
setx XYGENI_TOKEN "<TOKEN>"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
This will create the XYGENI\_TOKEN environment variable for the current user.
{% endhint %}

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

{% hint style="info" %}
This step is optional but highly recommended to facilitate future scans.
{% endhint %}

{% tabs %}
{% tab title="mac/Linux" %}

```
nano ~/.bashrc
```

Add this line at the end of the file:

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

Apply the changes:

```
source ~/.bashrc
```

{% endtab %}

{% tab title="Windows" %}

```
setx PATH "%PATH%;C:\Path\to\Scanner"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
This will modify the Current User Path.
{% endhint %}

### 5. Run your first scan&#x20;

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.

```bash
$ cd /my/project
$ xygeni scan 
```

You can also use these commands below for other cases:

```bash
# 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. 
```

{% hint style="info" %}
IMPORTANT: In case you want the scanner performs checks against your **repository** and **organization** (See [CI/CD Misconfigurations Detection](https://docs.xygeni.io/xygeni-products/software-supply-chain-security-sscs#misconfigurations_detection)), ensure that you provide your SCM and/or CI/ CD systems tokens to the scanner.&#x20;

Usually, the preferred option is to **pass the token in an environment variable** (like **`GITHUB_TOKEN`** or **`GITLAB_TOKEN`**).&#x20;

See [SCM and CI/ CD tokens](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/scm-ci-cd-and-container-registry-tokens) to know more about this topic.
{% endhint %}

{% hint style="info" %}
See [Xygeni Scanner Reference](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/xygeni-scanner-reference) for the full scanner command-line reference.
{% endhint %}

### 6. View scan results&#x20;

After the scan is done, log into the [Dashboard](https://docs.xygeni.io/introduction-to-xygeni/xygeni-web-ui-overview/dashboard) and navigate to the **Governance tab** to access the **Security Posture Summary** screen.&#x20;

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2FJYAnifhsdfjBc9AkHCeK%2FScreenshot%202025-04-04%20105058.png?alt=media&#x26;token=95db65c1-cbce-4d77-896b-f1300c6d277e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Go to [Xygeni Web UI](https://docs.xygeni.io/introduction-to-xygeni/xygeni-web-ui-overview) for a guide to browse the dashboard.
{% endhint %}