Skip to content
Picket

Reports

Picket has two reporting surfaces: Gitleaks-compatible reports for replacement workflows and Picket-native reports for richer triage.

Gitleaks-Compatible Reports

Section titled “Gitleaks-Compatible Reports”

Compatibility commands support:

  • JSON
  • CSV
  • JUnit XML
  • SARIF
  • template output

Compatibility writers preserve the Gitleaks-shaped fields, names, ordering, and behavior that downstream tools depend on. They do not add Picket-native validation, severity, confidence, provenance, or secret-hash fields.

Picket-Native Reports

Section titled “Picket-Native Reports”

Native commands support:

  • JSON
  • JSON Lines
  • SARIF
  • CSV
  • JUnit XML
  • HTML
  • TOON
  • GitLab code-quality JSON

Gitleaks-compatible git, filesystem, and stdin commands can opt into this native report surface with --profile picket. Without that explicit profile, picket git, picket dir, picket file, picket directory, and picket stdin keep Gitleaks-compatible report selection and reject native-only formats such as JSON Lines, HTML, TOON, and GitLab code-quality.

Native finding records use schema picket.finding.v1. Rich JSON reports use schema picket.report.v1. Its scan.complete field is false when an operational error or interruption prevented Picket from scanning every requested input. Native SARIF reports carry the same state in runs[].invocations[].executionSuccessful and include a tool-execution notification when incomplete.

Row-oriented native formats such as JSON Lines, CSV, and GitLab code quality do not have a run-level envelope. Consumers of those formats must treat Picket’s nonzero process exit as incomplete coverage even when a partial report was retained.

Native reports can include:

  • rule ID and description,
  • file and symlink path,
  • line and column range,
  • position coordinate kind,
  • match and secret text according to redaction settings,
  • secret, match, and source blob SHA-256 hashes,
  • source line,
  • commit and author metadata when available,
  • entropy,
  • deterministic randomness model, score, classification, component features, and explanatory signals when native scoring ran,
  • tags,
  • stable Picket fingerprint,
  • validation state,
  • severity and confidence,
  • rule pack, provider, rule documentation URL, validation templates, revocation templates, and rule deprecation state when available,
  • provenance,
  • decode path,
  • baseline status,
  • ignore reason,
  • remediation links.

Source-line evidence is bounded for pathological filesystem lines that exceed the scanner’s fragment limit. In that case, location fields still identify the complete source position, and native scans check gitleaks:allow against the complete logical line without materializing that unbounded line in memory.

Native findings use positionKind to make their coordinates unambiguous. UnicodeCodePointsExclusive means one-based Unicode code-point columns with an exclusive end position. GitleaksUtf8BytesInclusive means one-based UTF-8 byte columns with an inclusive end position and is used for findings produced under the compatibility contract.

SARIF 2.1.0 permits only unicodeCodePoints and utf16CodeUnits for run.columnKind; it has no UTF-8 byte-column value. Native SARIF writes native coordinates with columnKind: unicodeCodePoints. For compatibility-origin findings it preserves line ranges and the Picket positionKind property but omits columns rather than mislabeling byte offsets. Reports containing both coordinate systems use separate runs. Strict Gitleaks-compatible SARIF output remains governed by the pinned Gitleaks oracle.

Native CSV reports prefix finding-controlled cells that begin with =, +, -, @, tab, or carriage return with a single quote so spreadsheet tools do not interpret them as formulas. Gitleaks-compatible CSV keeps the pinned Gitleaks byte contract and does not apply this native-only neutralization.

Native fingerprints are versioned as picket:v1:<sha256>. The hash input includes the normalized logical path, rule ID, secret or match hash, and decode path. It intentionally excludes line, column, commit, author, and message metadata so native triage IDs remain stable when a finding moves inside the same file or appears across multiple commits. Gitleaks-compatible reports keep Gitleaks fingerprints.

Baseline comparison is exact by default. Native commands can select --baseline-mode portable to treat LF, CRLF, and CR evidence as equivalent while requiring all other baseline fields and source coordinates to match. Strict compatibility always uses exact comparison.

picket analyze writes incident-response reports as JSON, JSON Lines, or text. Analysis records include provider, credential type, stable fingerprint, secret hash, validation state, risk, identity, scopes, reachable resources, risk summary, recommended actions, revocation availability, revocation command templates, revocation guidance, and non-secret evidence. Offline analysis recognizes AWS access keys, Azure Storage connection strings, database connection URLs, GCP API keys, GCP service account keys, GitHub token families, GitLab token families, and Sourcegraph access tokens. picket analyze --live can enrich analysis with provider metadata from guarded live validation; offline analysis keeps identity, scopes, and resources as explicit offline placeholders.

Revocation command templates never include raw secret values. Picket emits concrete provider commands when the finding includes enough non-secret identifiers, such as an AWS access key ID, Azure Storage account name, or GCP service-account key ID. GitHub token reports emit picket revoke github --credential-env PICKET_GITHUB_CREDENTIAL --confirm-revocation; the operator must place the credential in that environment variable before explicitly running the guarded command. GitLab token reports include placeholder-based API or runner commands only for token families that have a safe owning-record workflow, such as personal access tokens, deploy tokens, pipeline triggers, and runner authentication tokens. When the provider supports revocation but the report cannot safely or accurately produce an exact command, revocationAvailable remains true, revocationCommands is empty or placeholder-based, and revocationGuidance explains the provider workflow. picket revoke uses typed provider clients and does not execute report command strings.

Report Selection

Section titled “Report Selection”

When --report-format is provided, it controls the writer. The canonical format values do not include a leading dot: json, jsonl, csv, junit, html, gitlab, sarif, toon, and template where supported. Native commands also accept extension aliases such as .html, .htm, .jsonl, and .sarif for convenience.

Without --report-format, Picket infers the writer from --report-path:

  • .csv selects CSV.
  • .json selects JSON.
  • .sarif selects SARIF.
  • .jsonl selects JSON Lines for native commands.
  • .html or .htm selects HTML for native commands.
  • .toon selects TOON for native commands.
  • .junit.xml selects JUnit for native commands.
  • gl-code-quality-report.json or *.gitlab-code-quality.json selects GitLab code-quality for native commands.

Native commands write JSON to standard output when no path or format is supplied. Gitleaks-compatible commands do not write a report unless --report-path is supplied; use --report-path - to write the report to standard output.

For Gitleaks-compatible commands, --verbose writes human-readable finding records to standard output. The banner and scan summary are written to standard error. These console records are independent of --report-path; selecting a report does not suppress them. --no-banner, --no-color, and --log-level control the compatibility console without changing report bytes.

Native commands create missing parent directories for file report paths and print report written: <path> to standard error after saving a report file. Standard output remains reserved for report content when no report path is supplied or when --report-path - is used.

Report Input

Section titled “Report Input”

picket verify <path> and picket analyze <path> accept either a scan target or a supported finding report. Supported report inputs are Picket JSON, Picket JSON Lines, and Gitleaks JSON because those formats can preserve the raw secret field needed for offline and live validation.

Report input follows the same native triage pipeline as freshly scanned findings: .gitleaksignore, baseline filtering, offline validation, optional live validation, validation-result filters, redaction, and report writing. In native report modes, redaction also replaces original evidence hashes with hashes of the redacted values so low-entropy secrets are not recoverable through offline hash guessing. Redacted reports can still be read, but validation accuracy is limited to whatever secret text remains in the report.

SARIF, HTML, GitLab code-quality JSON, and third-party reports that do not carry raw secret material are summary inputs for picket view, not verification inputs.

Triage View

Section titled “Triage View”

picket view <report> reads Picket JSON, Picket JSONL, Gitleaks JSON, TruffleHog JSON/JSONL, GitLab code-quality JSON, SARIF, and HTML summaries. It prints non-secret counts and up to ten finding summaries. --open launches only an existing regular local report file with a report extension (.csv, .htm, .html, .json, .jsonl, .sarif, .toon, or .xml) after the summary is written. Picket HTML reports include embedded non-secret rule ID, location, fingerprint, severity, confidence, validation state, commit and author attribution, and randomness summary metadata so picket view and the TUI can triage findings without scraping visible secret or match cells. Arbitrary HTML reports keep the generic html fallback with unknown counts.

picket tui <report> opens the same non-secret report summary in an interactive scanner console through the picket-tui companion executable. --flow renders inline interactive steps in the normal terminal buffer before optionally opening the full-screen console. The TUI uses the same report readers as picket view and does not load raw secret, match, or source-line evidence into the initial console.

Report readers must not print raw secrets. They extract rule IDs, detector names, paths, line numbers, fingerprints, severity, confidence, validation state, optional commit and author attribution, counts, and format names for triage. Imported TruffleHog reports synthesize fingerprints from the detector, path, and line when the report does not provide one, and never use Raw, RawV2, or Redacted in terminal output.