Triage

triage

Scrutineer automatically queues reflect after a successful root default-branch triage invocation and waits for this invocation's child scans before running it. Do not enqueue reflect yourself or wait for it. It records operational lessons only and does not change scan selection or finding dispositions.

Kick off the standard set of scans against a freshly-added repository.

Workspace

• ./context.json — has scrutineer.api_base, scrutineer.token, and scrutineer.repository_id. Required.
• ./report.json — write a short summary of what you enqueued.

Classify the repository

Run brief --json ./src and read its JSON. These fields decide which scans are worth queueing:

• languages — programming languages detected; null or empty means no source
• package_managers — manifest/lockfile ecosystems detected; null or empty means nothing publishes or consumes packages here

From those, set two flags:

• has_packages = package_managers is present and non-empty
• has_code = languages is present and non-empty

A docs repo (markdown only) has neither. Anything with detected source gets the code scans, whether it is an application, a library, infra scripts, or a flat-layout package. The cost of running semgrep on a stray shell script is far lower than missing a real library because brief failed to populate layout.source_dirs. Do not gate on layout.source_dirs; it is a heuristic and routinely empty for legitimate codebases.

Set has_embedded_native when Brief reports any of these signals:

• tools.native_extension is non-empty
• tools.dependency_bot contains Git Submodules
• the detected languages include at least one of C, C++, Objective-C, Objective-C++, Rust, Go, Fortran, Zig, Assembly, or CUDA, and either another language or a CMake, Meson, or Autotools build tool is also present

This covers native extensions and mixed-language repositories without assuming that native code means C or C++. If brief is not on PATH or exits non-zero, set has_code, has_packages, and has_embedded_native true and carry on so the follow-up scan can retry Brief after source preparation.

languages also decides one language-specific scanner:

• has_python = languages contains Python, matched case-insensitively

This gates bandit, which reads Python and nothing else. It follows has_code: when brief is unavailable it is true too, since a missed Python codebase costs more than a scan that finds nothing.

brief does not report CI configuration, so set a fourth flag from a direct filesystem check:

• has_workflows = ./src/.github/workflows exists and is a directory

This gates zizmor, which only audits GitHub Actions workflows; with no workflows directory its scan immediately no-ops, so skipping it at triage avoids enqueueing a scan that can do nothing. Unlike the code/package flags this is a definitive check, not a heuristic, so do not default it true on error — if the directory is absent, has_workflows is false.

The scan set

Read references/modes.md in this skill's directory and check each listed repository type against the source. Record matching modes and their file-level evidence in modes. Several modes can apply to one repository. Mode detection is independent of Brief's language and dependency detection, including when Brief fails.

Add each matching mode's skills to the scan set below. Put skills belonging only to unmatched modes in gated. Apply the same skip set, request scope, and error handling to mode skills as to the standard scans, and enqueue each skill at most once. Mode scans are additive: keep the standard scans and the threat-model-driven deep dives.

Before enqueueing anything, check what already ran so a re-trigger does not double-enqueue work that is already current.

Get the commit you are running at: git -C ./src rev-parse HEAD. Then fetch GET {api_base}/repositories/{repository_id}/scans, which returns every scan on this repository with skill_name, status, commit, ref and sub_path. If that fetch fails, treat the skip set as empty and carry on. Consider only scans whose ref and sub_path match the current scrutineer.scan_ref and scrutineer.scan_subpath, treating absent fields as empty. Otherwise a scan of a sibling subproject could suppress this scope's audit. Build a set of skill names to skip: a skill goes in the skip set if it has a compatible scan with status in {queued, running}, or a compatible scan with status="done" whose commit equals the current HEAD. A done scan at any other commit does not count; the repository has moved since then and the skill should run again. failed scans are re-enqueued.

Classify each skill in the list below into exactly one bucket, checking in this order and stopping at the first match: gated (its has_code/has_packages/has_python/has_workflows/has_embedded_native flag is false), already_done (it is in the skip set), triggered (enqueue it). Enqueue with POST {api_base}/repositories/{id}/skills/{name}/run and an Authorization: Bearer {token} header. Order does not matter; the scrutineer worker runs them as they come in. A 404 response moves the skill from triggered to skipped.

If scrutineer.scan_ref is set in context.json, include it in the POST body as {"ref": "<value>"} so child scans clone the same branch. If scrutineer.scan_subpath is set, also include "sub_path": "<value>" in the same body so every child stays scoped to the same monorepo sub-package — a scan submitted as repo#sub/dir (or a /tree/<branch>/<sub/dir> URL) sets this, and without forwarding it the pipeline would silently widen back to the whole repository. Combine them when both are present, e.g. {"ref": "main", "sub_path": "activesupport"}. When both are empty, send an empty JSON body or omit it. Verify runs (below) always send {}; they are finding-scoped and take neither.

Always:

• metadata
• repo-overview
• packages
• advisories

Only when has_workflows:

• zizmor

Only when has_python:

• bandit

Only when has_packages:

• dependencies
• sbom

packages and advisories query ecosyste.ms by repository URL rather than reading local manifests, so they run unconditionally even though they sound package-related.

Only when has_code:

• subprojects
• recon
• history
• threat-model
• semgrep
• betterleaks

Only when has_embedded_native:

• embedded-native

After threat-model finishes, Scrutineer reads its durable scan_config and enqueues one security-deep-dive per focus area. Do not enqueue security-deep-dive here: starting it before the threat model is complete would create an unscoped repository-wide audit and defeat the partition.

For one third of eligible triage runs, Scrutineer also schedules at most one exploratory security-deep-dive after a successful threat model has queued a planned audit. Do not request this extra scan yourself. When the threat model names a usable out-of-scope source directory, half of selected root scans challenge that exclusion with an adversarial sweep; other selected scans use a context-free random dig. Both keep explicit path exclusions and subproject scope. Repeated completion notifications do not select another extra audit.

If a skill name comes back 404 skill not found or inactive, skip it and note which one in your report; the operator may have disabled it on purpose.