xygeni-action

GitHub Action for Xygeni Scanner.

• Introduction
• Usage
  • Setting API token as encrypted secret in GitHub
  • Add a step calling the action to a workflow
  • Parameters

Introduction

GitHub Actions are a platform for continuous integration in GitHub repositories. An action encodes a reusable task with configurable parameters.

Xygeni provides a xygeni-action for downloading and running the scanner as a step in a GitHub workflow.

Usage

The xygeni-action downloads, configures and executes the Xygeni Scanner on the repository where the action is invoked.

Setting API token as encrypted secret in GitHub

The scanner needs an API token to communicate with the Xygeni platform. To register in the Xygeni platform, please register in the xygeni.io.

Such API token is a secret that could be registered safely at the appropriate scope (organization, repository or environment) using GitHub Encrypted Secrets.

For example, to register the API token as a secret named XYGENI_TOKEN, for the repository in the current working directory, you may use the GitHub gh command:

# The command will prompt you to enter the secret value
gh secret set XYGENI_TOKEN

# Alternatively you may read the value of the API token from a local file
gh secret set XYGENI_TOKEN < /path/to/xygeni_token.txt

(You must be the repository owner for creating repository secrets.)

For creating encryption secret at environment scope in a personal account repository (you need to be the repository owner), add --env ENV_NAME:

# Set the secret available to private repositories only
gh secret set --env ENV_NAME XYGENI_TOKEN

For creating encryption secret at organization scope (so the secret is available to all or a subset of the organization repositories), add --org ORG_NAME:

# GitHub CLI does not have admin:org permission by default
gh auth login --scopes "admin:org"

# Set the secret available to private repositories only
gh secret set --org ORG_NAME XYGENI_TOKEN

# Or set the secret available to all organization repositories
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility all

# Or limit visibility of the secret to the selected repos
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility selected --repos repo1,repo2

You may use the corresponding GitHub webpages for setting the api token as a secret named XYGENI_TOKEN at the appropriate scope.

Add a step calling the action to a workflow

In a GitHub workflow (.github/workflows/*.yml) the Xygeni scanner could be run on the repository files, typically after actions/checkout to retrieve the branch sources. The GITHUB_WORKSPACE environment variable will contain the default location of the repository when using the checkout action.

You can configure a GitHub action with the form:

on:
  workflow_dispatch:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  xygeni-scan:
    runs-on: ubuntu-latest
    name: xygeni-github-action
    steps:
      # Checkout the repository sources (GITHUB_WORKSPACE)
      - name: Checkout
        # You may instead pin to an action SHA
        uses: actions/checkout@v6
        with:
          # The default depth of 1 commit is not enough for some scans
          fetch-depth: 0

      - name: Xygeni-Scanner
        uses: xygeni/xygeni-action@v5
        id: Xygeni-Scanner
        with:
          token: ${{ secrets.XYGENI_TOKEN }}

Where XYGENI_TOKEN is the name of the encrypted secret where the API token was saved.

TIP: There is a starter workflow for Xygeni, which provides assistance for creating a scan job with Xygeni. Just go to Actions tab, click on New Workflow button, and write xygeni in the Search workflows field.

Parameters

Only the API token is required.

The default values for some parameters can be changed. For example, you may specify a specific name for the project instead of the GitHub repository name (GITHUB_REPOSITORY). Also, you may want to scan a particular source subdirectory instead of the default. You can see more information about default GitHub environment variables here.

The available parameters for the action are:

Parameter	Description	Mandatory	Default value
token	API token for authentication with Xygeni platform.	true
command	Command to execute by the scanner.	false	scan --never-fail
gh_token	GitHub token to retrieve repository information for misconfigurations and compliance.	false	$GITHUB_TOKEN
xygeni_url	Base URL of the Xygeni API.	false	https://api.xygeni.io
xygeni_dashboard_url	Base URL of the Xygeni Dashboard.	false	https://in.xygeni.io/dashboard

Tip: Use --never-fail to avoid breaking the build if the scan finds issues or fails. You may also use --fail-on=critical to terminate the build only when critical issues are found.

Tip: Use --run=secrets,iac if you want to scan only for secrets and IaC flaws, for example.

Tip: If you want to analyze a subdirectory, you can configure the command with -d parameter. For example, use -d app if the directory to scan is the app directory in your repository.

Example for scanning only hard-coded secrets and IaC flaws in the app subdirectory, and failing the build only when critical issues are found:

  - name: Xygeni-Scanner
    # Recommended: use commit SHA instead
    uses: xygeni/xygeni-action@v5
    id: Xygeni-Scanner
    with:
      token: ${{ secrets.XYGENI_TOKEN }}
      command: scan -n ${{ github.repository }} -d app --run=secrets,iac --fail-on=critical

See Xygeni scan command for full information on the command options available.

Security

Xygeni-action follows good security practices, but 100% security cannot be assured. Xygeni-action is provided "as is" without any warranty. Use at your own risk.

For more information about to report security issues, please refer to our security documentation.