CI/CD Audit Analysis

Xygeni scanner provides a command to check for the results of project analysis uploaded to Xygeni server, by generating an audit output that indicates if the software is ready to be deployed to production without vulnerabilities.

Guardrails normally operate at the scanner’s side, often to break the build when certain issues are found. The scan can be configured even on a pre-commit hook for example to avoid leaking a secret.

But certain issues, for example vulnerabilities in open-source dependencies, need to be processed server-side for context. In that case it is possible to upload and register a guardrail to run server-side over the results uploaded by the scanner.

Such server-side guardrail (CI/CD Audit) could be linked with projects, so when the scan results are uploaded the guardrail is executed and the scanner can query for the audit results for deciding if the build can progress or not.

Result of audit guardrail are represented with an icon (green/red) in the project page:

Guardrails at Server Side

Guardrails at the server side (Audit Analysis) can be managed from the Xygeni Scanner command util guardrail.

By uploading guardrails files to Xygeni server, guardrails can be associated with projects using project filter expressions.

The EDIT_POLICIES permission should be granted to the Xygeni API token for running this command.

Xygeni Guardrail Command

Usage: xygeni util guardrail

Server side Operations:
    -g, --get                Download a guardrail (by name).
    -l, --list               List available guardrails.
    -u, --upload             Upload a guardrail.
    -r, --remove             Remove a guardrail.
    -e                       Enable a guardrail.
    -d                       Disable a guardrail.
        --associate-filter=<associateProjects>
        Associate projects to guardrail by filter. Use '*' as a wildcard and '|' as or operator.
        --associate-remove   Remove associate project filter for guardrail.
        --associate-list     List associated projects to guardrail.
        --audit-project, --validate-project=<auditProjectByName>
                           Retrieve server-side guardrails compliance audit for the specified project. Blocks until analysis completion and returns the guardrail exit code (or 0 if guardrails weren't triggered).
        --audit-timeout, --validate-timeout=<auditTimeout>
                            Maximum time in seconds to wait for server-side analysis completion (default: 120).

    Parameters:
    -n, --name=<name>        Guardrail name.
    -f, --file=<file>        Guardrail file (for upload).
    --override           Override when uploading if exists.

    Commands:
    check  Validate a guardrail against a report file.

Configuring a CI/CD Audit Guardrail

The following steps may be followed for setting a CI/CD Audit Guardrail:

1. Create and test the guardrail. Create a file with a sample guardrail file that , for example, will fail if a critical secret is detected. For example, secrets-policy.xyflow:

  guardrail secrets-policy
      on secrets
      when severity = critical
      then @fail()

Read Guardrail Specification for more details on the syntax.

2. Test the guardrail locally. You may test the guardrail before upload, by running a scan with --fail-on option passing the .xyflow file. For example:

xygeni secrets --name ... --dir ... \
  --fail-on 'file:secrets-policy.xyflow'

Alternatively, you may use a JSON report from a previous scan, and run the command in 'sandbox' mode with actions in 'dry-run':

xygeni util guardrail check --verbose \
  --guardrail 'file:secrets-policy.xyflow' \
  --report xygeni_secrets_report.json

This command provides a way to check guardrail syntax, expression filtering over report items and action calls without effectively executing the actions.

Valid guardrail syntax and total items matched are logged to the console; additionally, each item matched and action calls are logged also if --verbose is enabled.

3. Upload the guardrail file to Xygeni server:

xygeni util guardrail --upload \
       --file secrets-policy.xyflow \
       --name secrets-policy

4. Associate the guardrail to projects using a filter:

  xygeni util guardrail \
    --name secrets-policy \
    --associate-filter "front*|backend*"

5. Get the list of guardrails with their associate project filters:

  xygeni util guardrail  --associate-list
    ┌──────────────────┬─────────┬─────────────────┐
    │       name       │ enabled │  projectFilter  │
    ├──────────────────┼─────────┼─────────────────┤
    │  secrets-policy  │  true   │ front*|backend* │
    └──────────────────┴─────────┴─────────────────┘

Once the guardrail is registered and mapped to projects, any scan in a pipeline for a matching project will run the audit automatically. To let the pipeline know the result of the audit, the `util guardrail --validate `

6. Check the result of CI/CD Audit from Xygeni server after analysis is executed locally:

  xygeni util guardrail --audit-project <project-name>

This command will block until analysis completion and return the guardrail exit code (or 0 if guardrails weren't triggered), or the `--audit-timeout` is reached.

Use the `--audit-timeout` option to set the maximum time in seconds to wait for server-side analysis completion (default: 120).