Scan changes against a reference branch

Bridge CLI Guide

Version
latest

Run an AI-driven security assessment of changes in the current branch relative to a reference branch within a Git project directory using Bridge CLI and Signal.

Signal provides a reference scan mode that compares the current branch against a specified reference branch in the project's Git directory. The Signal adapter uses a diff-based analysis to evaluate the changes relative to the chosen reference branch. Only the latest changes in tracked files are scanned. Scans can be run using either the Black Duck LLM or an organization-hosted LLM provider (BYOLLM).

This task is for Bridge CLI users. For more details, see Bridge CLI Overview.

Prerequisites

The following prerequisites are required when using Black Duck LLM and Bring Your Own Large Language Model (BYOLLM):

  • Bridge CLI is installed and available on the system PATH.
  • Access to a Git project directory.
  • The reference branch to compare against exists and is resolvable by Git.
  • A Signal Enterprise or Developer subscription.

Depending on the LLM, the following additional prerequisites apply:

  • Black Duck LLM:
    • A valid API key for the Black Duck LLM.
  • BYOLLM:
    • Credentials for the configured BYOLLM provider, stored securely in environment variables or CI/CD secrets.
    • Refer to the Signal compatibility matrix to identify the recommended models for each Signal agent across supported LLM providers.

Run reference branch scan with Black Duck LLM

Follow the steps to run a reference branch scan using the Black Duck LLM:

  1. Download the latest version of Bridge, if not already installed. To download, see Bridge Binaries Download.

  2. Add Bridge to your $PATH variable.

  3. Set the following environment variables for the Black Duck LLM in the shell or CI/CD environment where the scan will execute:

    export BRIDGE_LLM_PROVIDER_BLACKDUCK_KEY=<LLM_API_KEY>
    export BRIDGE_LLM_PROVIDER_BLACKDUCK_DEFAULT=true

    See Configure Black Duck LLM for more details on configuring the Black Duck LLM.

  4. Run the Bridge CLI Signal workflow at the root level of the project.

    bridge-cli --stage signal \
      signal.mode=REFERENCE \
      signal.git.ref="origin/main"

    Bridge starts Signal to perform an AI assessment of the code changes relative to the specified reference branch. When the scan completes, the following outputs are provided:

    • A SARIF report file is generated at .bridge/signal-controller/results.sarif within the current working directory where Bridge CLI was called.

    • An exit code of 0 indicates success.

Run reference branch scan with BYOLLM

Follow the steps to run a reference branch scan using a BYOLLM configuration:

  1. Download the latest version of Bridge, if not already installed. To download, see Bridge Binaries Download.

  2. Add Bridge to your $PATH variable.

  3. Create a Bridge JSON configuration file (input.json) that defines the signal scan parameters alongside the llm provider configuration:

    {
      "data": {
        "signal": {
          "mode": "REFERENCE",
          "git": {
            "ref": "origin/main"
          }
        },
        "llm": {
          /* Populate with your BYO LLM provider, tier, and agent settings */
        }
      }
    }

    For instructions on populating the llm block with provider endpoints, model tiers, and agent settings, see Configure Bring Your Own Large Language Model (BYOLLM).

  4. Run the Bridge CLI Signal workflow, passing the configuration file with the --input argument:

    bridge-cli --stage signal --input input.json

    Bridge validates the BYOLLM configuration and invokes Signal that then performs preflight checks against the configured LLM endpoints before starting the scan. When the scan completes, the following outputs are provided:

    • A SARIF report file is generated at .bridge/signal-controller/results.sarif within the current working directory where Bridge CLI was called.

    • An exit code of 0 indicates success.