Cerbi.Scanner 1.0.0

Cerbi Scanner

Static logging governance scanner for C#, Go, Java, Node/TypeScript, and Python repositories.
Read-only by default — the scanner never modifies your source code or uploads any data without an explicit opt-in.

Installation

dotnet tool install -g Cerbi.Scanner

Requires .NET 8 SDK or later. After install, the cerbi-scanner command is available globally.

To update:

dotnet tool update -g Cerbi.Scanner

Projects

CLI Usage

cerbi audit <path> [options]

Options

Examples

# Scan current directory, print JSON to stdout
cerbi audit .

# Scan with a governance profile
cerbi audit ./src --profile cerbi_governance.json

# Write a SARIF report
cerbi audit ./src --format sarif --output cerbi-scan.sarif

# Fail CI on any critical finding
cerbi audit ./src --fail-on critical

# Generate a starter profile
cerbi audit ./src --generate-profile --output cerbi_governance.json

# Use a custom config file
cerbi audit ./src --config path/to/cerbi-scanner.json

# Upload results (explicit opt-in, requires CERBI_API_KEY env var)
CERBI_API_KEY=<key> cerbi audit ./src --format json --output out.json --upload

Configuration — cerbi-scanner.json

Place a cerbi-scanner.json in your repository root (or pass --config <path>) to control scanner behaviour without modifying CI scripts.

{
  // Glob patterns excluded from every scan (in addition to --exclude flags)
  "defaultExcludes": ["**/obj/**", "**/bin/**", "**/node_modules/**", "**/*.g.cs"],

  // Files larger than this are skipped (0 = no limit)
  "maxFileSizeKb": 512,

  // Abort scan after this many seconds (0 = no timeout)
  "scanTimeoutSeconds": 120,

  // Equivalent to --fail-on: info | low | medium | high | critical
  "failThreshold": "high",

  // Per-rule severity overrides  (rule ID → new severity)
  "severityOverrides": {
    "CERBI-004": "medium"
  },

  // Config-based suppressions (inline suppression via comments is a future feature)
  "suppressions": [
    {
      "ruleId": "CERBI-001",           // required
      "filePath": "tests/Fixtures",    // optional substring match (/ or \ normalised)
      "fieldName": "password",         // optional field name match
      "reason": "Test fixture — intentional disallowed field",
      "expiresOn": "2026-12-31"        // optional ISO-8601; suppression ignored after this date
    }
  ]
}

Suppression matching rules

A finding is suppressed when all non-empty fields of a suppression entry match:

Suppressed findings are excluded from all reports and do not trigger CI failure.

Building

dotnet build Cerbi.Scanner/Cerbi.Scanner.slnx

Running Tests

dotnet test Cerbi.Scanner/Cerbi.Scanner.slnx

Note: Cerbi.Scanner.Cli.Tests runs the compiled cerbi-scanner binary as a child process.
Build the solution before running tests so the binary exists.

Core Contracts

Models (Cerbi.Scanner.Core.Model)

Interfaces (Cerbi.Scanner.Core.Abstractions)

JSON Output Shape

{
  "schemaVersion": "1.0",
  "scannerVersion": "0.1.0-alpha",
  "repositoryPath": "/path/to/repo",
  "scannedAt": "2024-01-01T00:00:00+00:00",
  "elapsedMs": 42,
  "scannedFileCount": 3,
  "totalLoggingCallsFound": 12,
  "ciThresholdBreached": false,
  "findingCount": 2,
  "findings": [
	{
	  "ruleId": "CERBI-001",
	  "ruleName": "DisallowedField",
	  "severity": "High",
	  "confidence": "High",
	  "explanation": "Field 'password' is disallowed by the active profile.",
	  "remediation": "Remove 'password' from the log call.",
	  "filePath": "/path/to/repo/Service.cs",
	  "lineNumber": 42,
	  "column": 12,
	  "sourceSnippet": "_logger.LogInformation(\"User {password} logged in\", password);",
	  "loggerFramework": "Mel"
	}
  ]
}

The schemaVersion field is stable. Consumers should read it and reject versions they do not support.

Enterprise Security Posture

What is and is not included in reports

Every report format (JSON, SARIF, HTML, console) is governed by the same data-minimisation rules:

Data collection

Report redaction

Before any finding explanation is written to a JSON, SARIF, or HTML report the text is passed through ReportRedactor.Redact() which replaces:

• Password assignments — password="...", pwd='...', secret="...", token="...", etc.
• Connection-string password fields — Password=abc123; → Password=[REDACTED]
• Long Base64-like tokens (≥ 32 chars) after key=, token=, bearer=, etc.

Redaction is best-effort. Do not treat reports as safe for public sharing without a manual review.

Safe handling of file paths and message templates

The scanner touches the filesystem in three places; each is hardened as follows:

1. Scan root — passed on the CLI and resolved to an absolute, normalised path. The scanner never traverses symlinks that resolve outside the scan root.
2. Output path — the --output target is written using FileStream with explicit FileMode.Create. Parent directories are created atomically before the file is opened. The path is not interpreted as a format string or shell command.
3. Message templates in findings — the raw template string (e.g. "User {UserId} logged in") is copied verbatim into the finding MessageTemplate field and then passed through ReportRedactor before serialisation. Template strings are never string.Format-evaluated by the scanner, so there is no format-injection risk.

Upload opt-in

The --upload flag is an explicit opt-in. It will not transmit any data unless:

1. --upload is present on the command line, and
2. The CERBI_API_KEY environment variable is set.

Omitting either causes the CLI to exit with an error rather than silently skipping the upload.

Telemetry

The scanner has no telemetry of any kind:

• DOTNET_CLI_TELEMETRY_OPTOUT=1 is declared in Directory.Build.props for all child processes.
• No HTTP client, analytics SDK, or background task is wired into the scanner or reporting pipeline.
• The CerbiShieldUploadClient stub is the only network-capable component; it is a no-op unless explicitly enabled.

Suppression audit trail

When a finding is suppressed via cerbi-scanner.json, the suppression is recorded in the JSON report alongside the finding:

{
  "ruleId": "CERBI-001",
  "suppressed": true,
  "suppressionReason": "legacy auth service, tracked in JIRA-123"
}

Suppressions with a past expiresOn date are ignored at scan time and emit a console warning. This ensures suppressions are reviewed periodically rather than silently accumulating forever. The CI workflow treats expired-suppression warnings as advisory (non-blocking) so that teams have time to renew or remove them.

File path safety

• Report output paths are validated and their parent directories are created atomically.
• --output is required when --format is sarif or html (stdout is JSON-only) to prevent binary content from accidentally polluting shell pipes.
• The scanner never follows symlinks outside the scan root.

Binary file protection

Files are checked for null bytes before Roslyn parsing. Any file that appears binary is skipped silently — it will not appear in findings or error output. This prevents false positives from compiled artifacts accidentally included in source trees.

Max file size guard

maxFileSizeKb (default: unlimited) skips files larger than the configured threshold before loading them into memory. Set this to a reasonable value (e.g. 512) in production CI to prevent a single large generated file from causing memory pressure.

Build reproducibility

All projects are built with <Deterministic>true</Deterministic> and <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild> (when GITHUB_ACTIONS=true), producing byte-for-byte identical output across machines for the same inputs.

Suppression expiry

Config-based suppressions with a past expiresOn date are ignored and emit a console warning at scan time. This ensures suppressions are reviewed periodically rather than silently accumulating forever.

Current Scope

Supported languages: C# (.NET), Go, Java, Node/TypeScript, Python
Supported frameworks: MEL, Serilog, NLog, log4net, Cerbi, zap, zerolog, Log4j2, SLF4J, Winston, Pino, stdlib logging, structlog
Rules implemented: disallowed fields, sensitive fields, missing required fields
Output formats: JSON (deterministic), SARIF 2.1.0, HTML, console summary

Non-Goals (this release)

• No live connection to the CerbiShield platform (CerbiShieldClient requires explicit --upload + API key).
• No Roslyn semantic analysis (syntax-only; no full compilation).
• No IDE extension or editor integration.
• No persistent storage or result history.
• Inline suppression comments (// cerbi:suppress) — planned for a future release; use cerbi-scanner.json suppressions today.

Architecture Notes

cerbi-scanner audit <path>
  └── MultiLanguageRepositoryScanner
		├── DotNetRepositoryScanner  (.cs  — Roslyn syntax tree)
		├── GoRepositoryScanner      (.go  — regex / AST heuristic)
		├── JavaRepositoryScanner    (.java — regex)
		├── NodeRepositoryScanner    (.js .ts .mjs .cjs — regex)
		└── PythonRepositoryScanner  (.py  — regex)
  └── RuleEngine                ← applies IScannerRule[] to each LoggingCall
  └── IReportWriter             ← JSON | SARIF | HTML | console
  └── IScanResultUploader       ← no-op unless --upload + CERBI_API_KEY

The Core library has no external dependencies beyond the .NET 8 BCL.
DotNet depends on Microsoft.CodeAnalysis.CSharp (source-only, no compilation).

CI

The included GitHub Actions workflow (.github/workflows/ci.yml) runs on every push and pull request:

1. restore — dotnet restore
2. build — dotnet build --no-restore -c Release (warnings-as-errors enabled)
3. test — dotnet test --no-build -c Release with TRX result publication
4. pack — dotnet pack --no-build -c Release
5. self-scan — cerbi audit against tests/fixtures/SampleDotNetApp (smoke test)
6. SARIF upload — uploaded to GitHub Code Scanning when CERBI_SARIF_UPLOAD=true is set on the default branch