Cerbi Scanner - Azure DevOps Extension

Run Cerbi's local scanner in Azure DevOps to catch risky, sensitive, and costly logging patterns before production, including metadata-only AI integration signals from supported scanner versions. The extension is intentionally a Marketplace/pipeline wrapper: it installs or resolves the Cerbi.Scanner .NET tool, lets teams choose the scan path and policy file, publishes JSON, SARIF, and markdown reports, and fails the build from scanner exit codes. It does not implement detection logic itself, so CI/CD findings stay aligned with local scanner behavior.

Current implementation note: this repository contains the Azure DevOps wrapper only. Scanner rules and language support live in Cerbi.Scanner. Do not assume language support beyond what the installed scanner version documents.

Marketplace package metadata

This extension publishes as Cerbi.cerbi-scanner in the Azure DevOps Marketplace. The Marketplace publisher must remain the Cerbi organizational publisher (Cerbi); do not publish this package under a personal publisher ID or a production pipeline may fail Marketplace validation and governance review.

Current package version: 1.2.6 (extension and task).

Marketplace links are intentionally pointed at Cerbi-owned resources for scanner onboarding, support, and privacy information. The source repository remains linked for task implementation review and issue traceability.

Scanner contract

Cerbi findings are expected to use stable rule IDs and include automation-friendly metadata: rule ID, title, message, severity, file path, line, column when available, excerpt when available, recommendation, confidence, and detected field or pattern category when available.

Scanner 1.2.0 and later reports AI integration signals from dependency and configuration manifests inside the explicit scan root. These findings are intended to reduce adoption friction and point teams toward Pro++ AI Logging Governance when runtime instrumentation may be needed; they do not prove full runtime AI execution governance by themselves.

Policy-as-code

The scanner should discover policy files named:

• cerbi-policy.yml
• cerbi-policy.yaml
• cerbi.logging.yml

You can also pass an explicit policy path with the task policyPath input. If no policy file exists, the scanner should use safe default rules. See samples/cerbi-policy.yml for the recommended schema covering rule enablement, severity overrides, fail threshold, allowed/disallowed structured fields, sensitive data patterns, and production overrides.

Local scanner installation (.NET 10 LTS)

Cerbi Scanner is distributed as the Cerbi.Scanner .NET global tool. For current LTS agents and workstations, install the .NET 10 LTS SDK/runtime and then install the scanner locally or globally:

dotnet --version # should report 10.0.x
dotnet tool install -g Cerbi.Scanner
cerbi-scanner --help

For reproducible enterprise builds, pin scannerVersion to the first Cerbi.Scanner release that declares .NET 10 LTS support. Do not use .NET 9 for this task: it is not an LTS target and is intentionally skipped in Cerbi Scanner pipeline examples.

.NET 10 LTS upgrade notes

• This Azure DevOps repository is a wrapper around the scanner global tool; it does not contain the scanner's .csproj files or detection rules. The actual net8.0 to net10.0 target-framework change belongs in the Cerbi.Scanner repository.
• Wrapper behavior is unchanged: the task still installs Cerbi.Scanner, resolves cerbi-scanner, runs cerbi-scanner scan, publishes reports, and interprets scanner exit codes.
• Expected breaking change: hosted and self-hosted agents must provide the .NET 10 LTS SDK/runtime before installing or running the scanner. Pipelines using only .NET 8 SDK images must add UseDotNet@2 with version: 10.0.x, enable the task installDotNet fallback, or preinstall .NET 10 in the agent image.
• The task now verifies dotnet --list-sdks / dotnet --list-runtimes before installing Cerbi.Scanner. If .NET 10 is missing and installDotNet: true, it installs the .NET 10 SDK into $(Agent.ToolsDirectory)/dotnet10 for the current task.
• No control-plane dependency is introduced; scanning remains local to the build agent and reports are published only as pipeline artifacts/summaries.

Data handling and network behavior

The Azure DevOps task runs the scanner on the build agent and does not upload source code, logs, findings, or report files to a Cerbi service. By default, outputs are written to the pipeline artifact staging directory and can be attached to the Azure DevOps build summary/artifacts when publishArtifacts is enabled. The task controls scanner snippet output explicitly. By default it passes --no-snippets to avoid copying source excerpts into shared CI artifacts; set includeSnippets: true only when the pipeline artifact audience is approved for source excerpts.

The task may make two outbound network calls only when configured to install prerequisites: dotnet-install downloads the requested .NET SDK if the agent is missing .NET 10, and dotnet tool install/update Cerbi.Scanner restores the scanner from the configured NuGet feeds. AI dependency detection is metadata-only and does not collect prompts, responses, MCP server values, provider keys, source snippets, or file contents. Set installDotNet: false and/or installScanner: false on locked-down self-hosted agents where these tools are preinstalled from approved internal images or feeds.

Pipeline usage

Install .NET 10 explicitly with UseDotNet@2 when possible. The task also has an installDotNet fallback for self-contained Marketplace usage on agents that do not already have .NET 10.

Demo/report mode (--fail-on none)

- task: UseDotNet@2
  displayName: Install .NET 10 SDK
  inputs:
    packageType: sdk
    version: 10.0.x

- task: CerbiScan@1
  displayName: Cerbi logging governance scan
  inputs:
    scanPath: $(Build.SourcesDirectory)
    failOn: none

CI/CD gate mode (--fail-on error)

- task: UseDotNet@2
  displayName: Install .NET 10 SDK
  inputs:
    packageType: sdk
    version: 10.0.x

- task: CerbiScan@1
  displayName: Cerbi logging governance scan
  inputs:
    scanPath: $(Build.SourcesDirectory)
    policyPath: $(Build.SourcesDirectory)/cerbi-policy.yml
    failOn: high
    jsonOutput: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-results.json
    sarifOutput: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-results.sarif
    markdownSummary: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-report.md
    publishArtifacts: true

Publish a readable Markdown build summary

- task: CerbiScan@1
  displayName: Cerbi markdown summary
  condition: always()
  inputs:
    scanPath: $(Build.SourcesDirectory)
    failOn: none
    markdownSummary: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-report.md

See samples/azure-pipelines.yml for a complete example.

Reporting and CI output

The reports input requests standard report outputs without using legacy --report flags. The wrapper maps markdown to --summary, json to --format json --output, and sarif to --sarif. By default the wrapper writes reports under $(Build.ArtifactStagingDirectory) using enterprise-friendly filenames:

• cerbi-report.md for Azure DevOps build summaries, artifacts, and human review.
• cerbi-results.json for stable automation and future ingestion workflows.
• cerbi-results.sarif for code scanning ingestion.

Publish the report directory as a single artifact when you want all outputs available after the job:

- task: CerbiScan@1
  displayName: Run Cerbi logging governance scanner
  inputs:
    scanPath: $(Build.SourcesDirectory)
    policyPath: $(Build.SourcesDirectory)/cerbi-policy.yml
    failOn: high
    jsonOutput: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-results.json
    sarifOutput: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-results.sarif
    markdownSummary: $(Build.ArtifactStagingDirectory)/cerbi/cerbi-report.md
    publishArtifacts: true

- publish: $(Build.ArtifactStagingDirectory)/cerbi
  artifact: cerbi-governance-report
  displayName: Publish Cerbi governance report

Output modes

• Demo/report mode uses failOn: none, which maps to cerbi-scanner scan --fail-on none; it generates reports without blocking the pipeline.
• CI/CD gate mode uses failOn: error, which maps to cerbi-scanner scan --fail-on error; it fails the task when scanner findings meet the error threshold.
• JSON output (--format json --output) is for automation, downstream parsing, metrics, and archival.
• SARIF output (--sarif) is for code scanning and security scanning workflows that ingest standardized static-analysis results.
• Markdown summary output (--summary) is for human-readable Azure DevOps build summaries.

Inputs

Legacy inputs (policyFile, failThreshold, outputFile, sarifOutputFile, markdownSummaryFile, and failOnSeverity) are still read as aliases where practical, but new pipelines should use the scanner-first inputs above.

CLI behavior invoked by the task

The wrapper verifies that the installed scanner supports scan. If cerbi-scanner scan --help is unavailable, the task fails clearly instead of silently falling back to legacy audit behavior:

Cerbi Scanner version X does not support the scan command. Upgrade to Cerbi.Scanner >= 1.1.0.

The wrapper then runs one scanner-first command:

cerbi-scanner scan --path <scanPath> --policy <policyPath> --fail-on <failOn> --format json --output <jsonOutput> --sarif <sarifOutput> --summary <markdownSummary> --no-snippets

--policy is omitted when policyPath is empty; --profile is included only when profilePath is set. --policy and --profile are mutually exclusive because the scanner does not allow the scanner-first YAML/JSON configuration path and the legacy governance-profile path together. Baseline/new-finding inputs and verbose: true are rejected because the current scanner contract used by this task does not expose --baseline, --create-baseline, --fail-on-new, or --verbose. ci is accepted as a deprecated no-op and never emits --ci. outputDir is translated into explicit report file paths and is never passed as --output-dir.

Exit codes are interpreted as:

Implementation plan for scanner changes

Smallest safe plan for the scanner repository:

1. Keep detection in the local Cerbi.Scanner CLI and expose one shared finding contract for console, JSON, SARIF, markdown, and Azure DevOps.
2. Add policy loading for the three supported names plus --policy, with safe defaults when absent.
3. Normalize severities to warning, error, and blocker; apply rule enablement and overrides before output/fail decisions.
4. Implement or verify CERBI001-CERBI006 in the existing supported analyzer path only. If only .NET/Roslyn is currently implemented, document that clearly and keep future language scanners behind the same contract.
5. Add focused fixtures and tests for each rule, policy overrides, fail threshold, JSON, SARIF, markdown, and this Azure DevOps wrapper argument/report-publishing mapping.

Unsupported legacy baseline inputs

The current Cerbi.Scanner CLI does not implement baseline creation, baseline comparison, or new-finding-only failure thresholds. Pipelines that set baseline, createBaseline, or failOnNew to anything except none fail fast with a validation error instead of pretending to enforce unsupported governance behavior. Baseline support must be added in the scanner repository before this task can forward those inputs.

Additional argument guardrails

additionalArguments is only for supplemental scanner metadata/filtering options. The task rejects attempts to override managed options (--path, --profile, --policy, --format, --output, --sarif, --summary, --fail-on, --snippets, and --no-snippets) so Azure DevOps inputs remain the source of truth for scan target, policy/profile, reports, thresholds, and snippet behavior.

Enterprise agent configuration

Recommended Marketplace defaults are safe for hosted agents: install the scanner into $(Agent.ToolsDirectory)/cerbi-scanner, scan $(Build.SourcesDirectory), publish JSON/SARIF/Markdown reports, suppress snippets with --no-snippets, and only fail when failOn is configured. For regulated or offline environments:

- task: CerbiScan@1
  inputs:
    scannerVersion: 1.2.0
    installScanner: true
    scannerInstallDirectory: $(Agent.ToolsDirectory)/cerbi-scanner
    packageSource: https://pkgs.dev.azure.com/your-org/_packaging/security/nuget/v3/index.json
    installDotNet: true
    dotNetVersion: 10.0.x
    dotNetInstallDirectory: $(Agent.ToolsDirectory)/dotnet10
    scanPath: $(Build.SourcesDirectory)
    policyPath: $(Build.SourcesDirectory)/cerbi-policy.yml
    failOn: error
    reports: markdown,json,sarif
    outputDir: $(Build.ArtifactStagingDirectory)/cerbi
    includeSnippets: false
    publishArtifacts: true
    uploadToCerbiShield: false

outputDir is a task-level compatibility input only; the task expands it to explicit scanner output files and does not pass --output-dir. If your self-hosted image already contains an approved scanner, set installScanner: false. The task will resolve the scanner from scannerInstallDirectory, PATH, or the .NET user tools directory without contacting a package feed.

Privacy & security

• The extension delegates to a local scanner process; it does not upload source or findings to a Cerbi service.
• Keep includeSnippets: false for shared reports unless source excerpts are explicitly approved for the pipeline artifact audience.
• Pin scannerVersion in enterprise pipelines for reproducible governance behavior.
• Use packageSource for private Azure Artifacts/NuGet feeds or mirrored scanner packages; configure feed credentials through Azure Pipelines service connections or agent NuGet configuration.
• Do not route application logs through this extension or any public control-plane service. The scanner is a local CI governance gate only.

Troubleshooting

Missing .NET runtime or SDK

Symptoms usually look like dotnet was not found, You must install or update .NET, or a scanner launch failure after Cerbi.Scanner installs successfully. Fix this in one of three supported ways:

1. Preferred for Microsoft-hosted agents: add UseDotNet@2 before CerbiScan@1 with version: 10.0.x.
2. Marketplace fallback: leave installDotNet: true so the task installs the .NET 10 SDK into $(Agent.ToolsDirectory)/dotnet10 when .NET 10 is missing.
3. Self-hosted regulated agents: preinstall a pinned .NET 10 SDK/runtime and set installDotNet: false only after dotnet --list-sdks or dotnet --list-runtimes shows a 10.0.* entry.

If installScanner: true is enabled, the task needs a .NET SDK, not only a runtime, because dotnet tool install is an SDK command. If installScanner: false and the scanner is preinstalled, a compatible .NET 10 runtime is sufficient to run the tool.

Scanner install failures

• Check scannerVersion first. Use latest only when your pipeline accepts new scanner versions at job time; pin an explicit version for regulated builds.
• Check packageSource and NuGet credentials when using private feeds.
• On self-hosted agents without outbound NuGet access, preinstall the scanner and set installScanner: false.

Unsupported input failures

The task fails fast for inputs that the current scanner does not support, including baseline creation/comparison and new-finding-only thresholds. Remove baseline, createBaseline, and failOnNew values other than none until the scanner implements those capabilities. Do not put task-managed flags in additionalArguments; use the dedicated task inputs instead.

Exact sample YAML

Copy this baseline for the .NET 10 Cerbi.Scanner release:

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - task: UseDotNet@2
    displayName: Install .NET 10 SDK
    inputs:
      packageType: sdk
      version: 10.0.x

  - task: CerbiScan@1
    displayName: Cerbi logging governance scan
    inputs:
      scanPath: $(Build.SourcesDirectory)
      policyPath: $(Build.SourcesDirectory)/cerbi-policy.yml
      failOn: error
      reports: markdown,json,sarif
      outputDir: $(Build.ArtifactStagingDirectory)/cerbi
      scannerVersion: latest
      installScanner: true
      scannerInstallDirectory: $(Agent.ToolsDirectory)/cerbi-scanner
      installDotNet: true
      dotNetVersion: 10.0.x
      dotNetInstallDirectory: $(Agent.ToolsDirectory)/dotnet10
      includeSnippets: false
      publishArtifacts: true
      uploadToCerbiShield: false

Requirements

• Azure DevOps agent with the .NET 10 LTS SDK installed (for example UseDotNet@2 with version: 10.0.x) or task installDotNet: true so the task can install it locally.
• Network access to the configured NuGet source when installScanner: true, unless the agent already has the tool installed and installScanner: false is used.
• Self-hosted enterprise agents can pin scannerVersion, set packageSource to an internal feed, or disable install and pre-provision the scanner in the agent image.