SCM, CI/ CD and Container Registry tokens

Why are these tokens required?

Our scanner performs checks against your SCM, CI/ CD systems and container registries to recover information about your repository and organization, as part of the scanning process to validate if there are misconfigurations affecting them.

For image scanning, authentication with the container registry for pulling the image may require credentials, often in the form of access tokens.

For that, it is important to provide tokens with the permissions allowing the scanner to collect the data needed for analyses.

Required token permissions

For GitHub , these are the required token permissions/ scopes:

enterprise: read
org: admin
packages: read
project: read
repo: full
repo_hook: read
user: read

See Creating a GH PAT if you have doubts about setting up a Personal Access Token.

Providing the token

Navigate to your scanner folder and look at the file conf/xygeni.yml. Under the scm, cicd and containerRegistry elements you are going to discover the currently available systems and how to provide their tokens to the scanner. This is done in entries under tokenSources. Each token source is tested until a valid token is found. Token sources could be an environment variable, a local file, or a hardcoded value (not recommended).

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

For example, in the case of GitHub, you can make the GitHub PAT available for Xygeni Scanner either by setting GITHUB_TOKEN or GITHUB_PAT environment variables, or storing it into a file named ${user.home}/.github.token or ${XYGENI_DIR}/conf/.github.token (in this latter case, XYGENI_DIR env var should be set)

kind: github
    # Which projects are held in this SCM?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given scm kind)
    usedBy: ${GITHUB_USED_BY}
    # The (optional) default username to connect to the SCM API.
    # If not given it could be extracted from the repository URL, when available.
    user: ${GITHUB_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${GITHUB_TOKEN}
      - ${GITHUB_PAT}
      - file:${user.home}/.github.token
      - file:${XYGENI_DIR}/conf/.github.token

You can find a full reference of conf/xygeni.yml here

In the case of Jenkins, you must set some additional env variables:

JENKINS_URL (your Jenkins base URL)
JENKINS_USER (the Jenkins username to connect to the Jenkins API)

Full reference of `conf/xygeni.yml`

# List of different Source Code Management (SCM) systems
# supporting projects for the organization
scm:
  # One of: github, azure_devops, bitbucket, gitlab.
  -
    kind: github
    # Which projects are held in this SCM?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given scm kind)
    usedBy: ${GITHUB_USED_BY}
    # The (optional) default username to connect to the SCM API.
    # If not given it could be extracted from the repository URL, when available.
    user: ${GITHUB_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${GITHUB_TOKEN}
      - ${GITHUB_PAT}
      - file:${user.home}/.github.token
      - file:${XYGENI_DIR}/conf/.github.token
  -
    kind: azure_devops
    # Which projects are held in this SCM?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given scm kind)
    usedBy: ${AZURE_USED_BY}
    # The (optional) default username to connect to the SCM API.
    # If not given it could be extracted from the repository URL, when available.
    user: ${AZURE_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${AZURE_TOKEN}
      - ${AZURE_PAT}
      - file:${user.home}/.azure.token
      - file:${XYGENI_DIR}/conf/.azure.token
  -
    kind: bitbucket
    # Which projects are held in this SCM?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given scm kind)
    usedBy: ${BITBUCKET_USED_BY}
    # The (optional) default username to connect to the SCM API.
    # If not given it could be extracted from the repository URL, when available.
    user: ${BITBUCKET_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${BITBUCKET_TOKEN}
      - ${BITBUCKET_PAT}
      - file:${user.home}/.bitbucket.token
      - file:${XYGENI_DIR}/conf/.bitbucket.token
  -
    kind: gitlab
    # Which projects are held in this SCM?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given scm kind)
    usedBy: ${GITLAB_USED_BY}
    # The (optional) default username to connect to the SCM API.
    # If not given it could be extracted from the repository URL, when available.
    user: ${GITLAB_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${GITLAB_TOKEN}
      - ${GITLAB_PAT}
      - file:${user.home}/.gitlab.token
      - file:${XYGENI_DIR}/conf/.gitlab.token


# CI/CD tools used, if you not configure this, the system will assume that the SCM is used as CI/CD tool.
cicd:
  -
    kind: jenkins
    # Jenkins base URL
    url: ${JENKINS_URL}
    # Which projects use this CI/CD system?
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching any project for the given jenkins kind
    usedBy: ${JENKINS_USED_BY}
    # The username to connect to the CI/CD API.
    user: ${JENKINS_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${JENKINS_TOKEN}
      - file:${user.home}/.jenkins.token
      - file:${XYGENI_DIR}/conf/.jenkins.token
  -
    kind: circle_ci
    # CircleCI base URL
    url: '${CIRCLECI_URL:-https://circleci.com/api/}'
    tokenSources:
      - ${CIRCLECI_TOKEN}
      - file:${user.home}/.circleci.token


# Container (OCI) Registries
containerRegistry:
  -
    # Docker Hub
    # The hostname to match in the image name. This is the default when no hostname provided.
    hostname: '${DOCKER_HOST:-docker.io}'
    # Docker registry official URL
    url: '${DOCKER_URL:-https://registry-1.docker.io}'
    # Which projects use this registry? A hostname is often given in the image name.
    # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*'
    # Leave empty for matching by hostname.
    usedBy: ${DOCKER_USED_BY}
    # The username to connect to the registry api.
    user: ${DOCKER_USER}
    # How the access token should be fetched:
    # From environment/system property (env:),
    # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME),
    # or encode directly (use encryption to protect the token against casual readers)
    tokenSources:
      - ${DOCKER_TOKEN}
      - file:${user.home}/.docker.token

  #... Additional popular registries follow ...

PreviousCLI authentication with Xygeni NextXygeni CLI operation modes

Last updated 1 month ago

kind: github # Which projects are held in this SCM? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given scm kind) usedBy: ${GITHUB_USED_BY} # The (optional) default username to connect to the SCM API. # If not given it could be extracted from the repository URL, when available. user: ${GITHUB_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${GITHUB_TOKEN} - ${GITHUB_PAT} - file:${user.home}/.github.token - file:${XYGENI_DIR}/conf/.github.token

# List of different Source Code Management (SCM) systems # supporting projects for the organization scm: # One of: github, azure_devops, bitbucket, gitlab. - kind: github # Which projects are held in this SCM? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given scm kind) usedBy: ${GITHUB_USED_BY} # The (optional) default username to connect to the SCM API. # If not given it could be extracted from the repository URL, when available. user: ${GITHUB_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${GITHUB_TOKEN} - ${GITHUB_PAT} - file:${user.home}/.github.token - file:${XYGENI_DIR}/conf/.github.token - kind: azure_devops # Which projects are held in this SCM? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given scm kind) usedBy: ${AZURE_USED_BY} # The (optional) default username to connect to the SCM API. # If not given it could be extracted from the repository URL, when available. user: ${AZURE_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${AZURE_TOKEN} - ${AZURE_PAT} - file:${user.home}/.azure.token - file:${XYGENI_DIR}/conf/.azure.token - kind: bitbucket # Which projects are held in this SCM? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given scm kind) usedBy: ${BITBUCKET_USED_BY} # The (optional) default username to connect to the SCM API. # If not given it could be extracted from the repository URL, when available. user: ${BITBUCKET_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${BITBUCKET_TOKEN} - ${BITBUCKET_PAT} - file:${user.home}/.bitbucket.token - file:${XYGENI_DIR}/conf/.bitbucket.token - kind: gitlab # Which projects are held in this SCM? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given scm kind) usedBy: ${GITLAB_USED_BY} # The (optional) default username to connect to the SCM API. # If not given it could be extracted from the repository URL, when available. user: ${GITLAB_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${GITLAB_TOKEN} - ${GITLAB_PAT} - file:${user.home}/.gitlab.token - file:${XYGENI_DIR}/conf/.gitlab.token # CI/CD tools used, if you not configure this, the system will assume that the SCM is used as CI/CD tool. cicd: - kind: jenkins # Jenkins base URL url: ${JENKINS_URL} # Which projects use this CI/CD system? # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching any project for the given jenkins kind usedBy: ${JENKINS_USED_BY} # The username to connect to the CI/CD API. user: ${JENKINS_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${JENKINS_TOKEN} - file:${user.home}/.jenkins.token - file:${XYGENI_DIR}/conf/.jenkins.token - kind: circle_ci # CircleCI base URL url: '${CIRCLECI_URL:-https://circleci.com/api/}' tokenSources: - ${CIRCLECI_TOKEN} - file:${user.home}/.circleci.token # Container (OCI) Registries containerRegistry: - # Docker Hub # The hostname to match in the image name. This is the default when no hostname provided. hostname: '${DOCKER_HOST:-docker.io}' # Docker registry official URL url: '${DOCKER_URL:-https://registry-1.docker.io}' # Which projects use this registry? A hostname is often given in the image name. # Use a regex pattern, like 'project1|project2|project3' or 'prefix_.*' # Leave empty for matching by hostname. usedBy: ${DOCKER_USED_BY} # The username to connect to the registry api. user: ${DOCKER_USER} # How the access token should be fetched: # From environment/system property (env:), # From file (use ${scanned.dir} for scanned directory, ${XYGENI_DIR} for scanner directory, ${user.home} for $HOME), # or encode directly (use encryption to protect the token against casual readers) tokenSources: - ${DOCKER_TOKEN} - file:${user.home}/.docker.token #... Additional popular registries follow ...

Why are these tokens required?

Required token permissions

Providing the token

Full reference of conf/xygeni.yml

Why are these tokens required?

Required token permissions

Providing the token

Full reference of conf/xygeni.yml

Full reference of `conf/xygeni.yml`

Full reference of `conf/xygeni.yml`