# Azure Pipelines Integration

## Introduction <a href="#introduction" id="introduction"></a>

`Azure Pipelines` combines continuous integration (CI) and continuous delivery (CD) to test, build and ship your code to any target.

{% hint style="info" %}
The following configuration examples show how to install & run the scanner using an API Token stored as a secret named `XYGENI_TOKEN`. See [Generate Xygeni API Token for Scanner](https://docs.xygeni.io/xygeni-administration/profile#generate_token_for_scanner-1) or ask your Xygeni administrator to generate it.

For registering a new secret in Azure DevOps, see [Secret variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops\&tabs=yaml%2Cbatch#secret-variables).
{% endhint %}

## Using the Xygeni Task for Azure Pipelines

The simplest way to run the scanner in Azure Pipelines is to use the [Xygeni Task](https://marketplace.visualstudio.com/items?itemName=xygeni-security.xygeni-scanner). The tasks uses the Xygeni CLI to scan the software for vulnerabilities, malware and misconfigurations.

The API token should be registered safely as a (secret) pipeline variable. If you name the variable `XYGENI_TOKEN`, the task will look for it automatically. Otherwise, you can pass it in an environment variable such as `XYGENI_TOKEN` and set the input property `xygeniToken = 'env:XYGENI_TOKEN'`.

### Installation

From the [Xygeni Task](https://marketplace.visualstudio.com/items?itemName=xygeni-security.xygeni-scanner) in the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/azuredevops), you can install for an Azure DevOps organization by clicking the **Get it free** button. There you select the Azure DevOps organizations where you want to install the task.

For Azure DevOps Server, the task can be downloaded as a `.vsix` file and installed in your Azure DevOps Server Extensions page (For example, `http://someserver/_gallery/manage`). Click upload new extension, select the downloaded `.vsix` file, click Install and select the Team Project Collection to install into.

### Adding the task as a pipeline step

Edit your pipeline and add the Xygeni task as a pipeline step, using the Task Assistant filter by Xygeni and click Xygeni Security Scanner:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-873965fe6d8fce9b7bc6f89ec8db01ec9e480e21%2Fazure_task_01.png?alt=media" alt=""><figcaption></figcaption></figure>

Edit the scan properties (1) by choosing the scan operations, the directory to scan. Then click **Add** button to add the YAML to the pipeline.

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-90a0556c578a2a96cfb3a37bbe2f33da6c76e00c%2Fazure_task_02.png?alt=media" alt=""><figcaption></figcaption></figure>

By default the XYGENI\_TOKEN pipeline (secret) variable will be used if the `Xygeni API Token` field is not specified.

You can also edit the YAML source directly (2) in the Pipeline Editor. Autocomplete will work to help you fill in the task properties.

{% hint style="info" %}
To make the scan findings available for inspection or for use by other pipeline steps, you may want to publish the findings as an artifact. Use the **Publish Build Artifacts** task to do so, as shown in (3) in the screenshot.
{% endhint %}

### Task properties

The following is an example of the Xygeni task, including the most relevant parameters.

```yaml
steps:
# ...Other build steps here...  
  
- task: xygeni-scanner@1
  displayName: 'Run Xygeni Scanner'
  env:
    XYGENI_TOKEN: $(XYGENI_TOKEN)
    # Token for checking Azure DevOps configuration for misconfigurations
    AZURE_TOKEN: $(AZURE_TOKEN)
  inputs:
    scanDirectory: '$(Build.Repository.LocalPath)'
    xygeniToken: 'env:XYGENI_TOKEN'
    deps: true
    inventory: true
    secrets: true
    misconfig: true
    suspectdeps: true
    iac: true
    outputFile: '$(Build.ArtifactStagingDirectory)/xygeni/findings.json'
    outputFormat: json

- task: PublishBuildArtifacts@1
  displayName: 'Publish xygeni findings as artifacts'
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)/xygeni'
    ArtifactName: 'Xygeni_findings'
```

## Using scanner download

Another option is to download and unzip the scanner and run the CLI. Suppose that the secret `xygeniToken` stores the Xygeni API token. In a Linux runner, you may use the [Bash](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/bash-v3?view=azure-pipelines) task:

```yaml
steps:
- task: Bash@3
  displayName: 'Install xygeni scanner'
  inputs:
    targetType: 'inline'
    script: |
      curl -s -L "https://get.xygeni.io/latest/scanner/xygeni-release.zip" -o xygeni_scanner.zip
      unzip -qq xygeni_scanner.zip -d "$(Pipeline.Workspace)"
      rm xygeni_scanner.zip

- task: Bash@3
  displayName: 'Scan for issues'
  inputs:
    targetType: 'inline'
    # Change the command arguments to match your needs
    script: |
      set -x # Activate debug mode to print commands inside the script
      echo "Starting Xygeni scan for $PROJECT_NAME"
      $(Pipeline.Workspace)/xygeni_scanner/xygeni scan -n "$PROJECT_NAME" --dir "$PROJECT_HOME"
  env:
    PROJECT_NAME: $(System.TeamProject)
    PROJECT_HOME: $(Build.SourcesDirectory)
    XYGENI_TOKEN: $(XYGENI_TOKEN)

```

Under Windows, you may use the [PowerShell](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/powershell-v2?view=azure-pipelines) task instead of the Bash task, and run the `xygeni.ps1` instead:

```yaml
steps:
  - task: PowerShell@2
    displayName: 'Install xygeni scanner'
    inputs:
      targetType: 'inline'
      script: |
        $zipPath = "xygeni_scanner.zip"
        $extractPath = "$(Pipeline.Workspace)"
        Write-Host "Downloading Xygeni scanner..."
        Invoke-WebRequest -Uri "https://get.xygeni.io/latest/scanner/xygeni-release.zip" -OutFile "$zipPath"
        Expand-Archive -Path "$zipPath" -DestinationPath "$extractPath" -Force
        Remove-Item $zipPath -Force

  - task: PowerShell@2
    displayName: 'Scan for issues'
    inputs:
      targetType: 'inline'
      # Change the command arguments to match your needs
      script: |
        Write-Host "Starting Xygeni scan for $env:PROJECT_NAME"
        $scannerScript = "$(Pipeline.Workspace)\xygeni_scanner\xygeni.ps1"
        & $scannerScript scan -n "$env:PROJECT_NAME" --dir "$env:PROJECT_HOME"

    env:
      PROJECT_NAME: $(System.TeamProject)
      PROJECT_HOME: $(Build.SourcesDirectory)
      XYGENI_TOKEN: $(XYGENI_TOKEN)
```

{% hint style="info" %}
We recommend using the task, as it keeps the scanner cached between runs and makes configuration easier using the Azure Pipelines UI instead of manually editing the pipeline YAML.

Please refer to the [scanner documentation](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview) for full details on the scanner command line options and configuration. The command above runs full scan with default options. Probably you can use options such as `--run` to specify the analyses to perform, `--never-fail` to never break the pipeline, or `--fail-on` to terminate the pipeline when a guardrail does not pass.
{% endhint %}