Fork

fork

Stand up a private staging repo for one scanned upstream. The staging repo is a plain clone of the upstream tree (no GitHub fork relationship), lives in fork_org, and is the working surface for everything that follows: finding issues, PoC files, patch diffs, and validation reports all live here. Scrutineer's metadata sits at the repo root in the directory named by scrutineer.metadata_dir (default .scrutineer/). Run after a scan has produced findings; idempotent on re-runs.

Below, the placeholder {metadata_dir} stands for the value of scrutineer.metadata_dir from ./context.json. Substitute it verbatim before issuing any git or shell command.

Workspace

• ./src — the upstream clone at the commit that was scanned
• ./context.json — has repository.url, repository.full_name, repository.default_branch, scrutineer.api_base, scrutineer.token, scrutineer.repository_id, scrutineer.scan_id, scrutineer.fork_org, and scrutineer.metadata_dir
• ./report.json — write what you did

Use the gh CLI for every GitHub call. Do not use curl against api.github.com.

Preconditions

Read ./context.json. Refuse to continue (write {"error": "..."} to report.json and exit 0) if:

• scrutineer.fork_org is missing or empty — the operator has not configured fork_org in scrutineer.yaml
• repository.url does not have host github.com — other hosts get the same treatment but the host-prefix mapping (below) is hard-coded to gh for now
• gh auth status fails — the runner has no GitHub credentials

Derive {owner}/{repo} from repository.full_name (fall back to parsing the path of repository.url, stripping a trailing .git).

1. Resolve the staging repo name

The staging repo lives at {fork_org}/{host}__{owner}__{repo}, lowercased:

• host is gh for github.com
• owner and repo come straight from the upstream URL

So https://github.com/madler/zlib becomes {fork_org}/gh__madler__zlib. Deterministic and collision-free across hosts, so no probing for free slots.

If scrutineer already knows the staging repo (GET {api_base}/repositories/{repository_id} has a non-empty fork), use it as {staging} and skip to step 3. The field is named fork for legacy reasons; semantically it is the staging repo URL.

2. Create and seed the staging repo

Check whether it already exists:

gh repo view {fork_org}/{host}__{owner}__{repo}

If view succeeds, record "created": "exists" and skip to step 3.

Otherwise create it:

gh repo create {fork_org}/{host}__{owner}__{repo} --private \
  --description "scrutineer staging for {owner}/{repo}"

Then seed it from ./src. The goal is a default branch on the staging repo that contains the upstream tree at its full history (so VIDs, fingerprints, locations, and patches all resolve the same way they do on the upstream):

cd ./src
# Make sure history is complete enough to push. Shallow clones cannot be pushed.
git fetch --unshallow origin || true
git remote add scrutineer-staging https://github.com/{fork_org}/{host}__{owner}__{repo}.git
git push scrutineer-staging HEAD:{repository.default_branch}

If git fetch --unshallow fails (the clone was already complete) ignore it. If the push fails because of unshallow, record "error": "could not push full history" and exit 0 — half-seeded repos cause more confusion than they fix.

Record "created": "created" and persist the resolved name back to scrutineer so the next run skips the probe:

PATCH {api_base}/repositories/{repository_id}
Authorization: Bearer {token}
{"fork": "{fork_org}/{host}__{owner}__{repo}"}

3. Write the repo-level metadata

Build the per-repo metadata block:

# {metadata_dir}/metadata.yaml
upstream:
  url: {repository.url}
  host: github.com
  owner: {owner}
  repo: {repo}
seeded_at: {ISO-8601 timestamp, UTC}
seeded_commit: {git -C ./src rev-parse HEAD}
last_scan_at: {same timestamp, refreshed on every run}
last_scan_id: {scan_id}
last_scan_commit: {same as seeded_commit on first run; refresh on re-runs}

On re-runs only the last_scan_* fields change.

The simplest write path is one commit per skill run carrying every file under {metadata_dir} that changed in this run. Clone the staging repo into a temp working tree, write the files, commit, push:

TMP=$(mktemp -d)
git clone --depth 1 https://github.com/{fork_org}/{host}__{owner}__{repo}.git "$TMP/staging"
cd "$TMP/staging"
mkdir -p {metadata_dir}
# write {metadata_dir}/metadata.yaml and per-finding files (see step 4) here
git add {metadata_dir}
git -c user.email=scrutineer@local -c user.name=scrutineer \
  commit -m "scrutineer: scan {scan_id} at {short-commit}" -m "Updated {metadata_dir} from scrutineer run."
git push origin {repository.default_branch}

The commit author is local; the push uses the gh CLI's credentials. One commit per run keeps the history readable.

4. Per-finding metadata files

Fetch the repository's findings: GET {api_base}/repositories/{repository_id}/findings with Authorization: Bearer {token}. Include findings whose status is one of new, enriched, triaged, ready, reported, acknowledged, fixed. Skip rejected, duplicate, and published — those do not have a staging-side life. Record skipped ones under "skipped" with the status as reason.

For each remaining finding fetch the full record (GET {api_base}/findings/{id}) so you have its prose, severity, status, CVSS, CWE, disclosure_draft, and suggested_fix.

In the staging working tree, write the following files under {metadata_dir}/findings/{finding_id}/:

• metadata.yaml:

  finding_id: {id}
  title: {title}
  severity: {severity}
  status: {status}
  cwe: {cwe}
  cvss_vector: {cvss_vector}
  location: {location}
  opened_at: {ISO-8601, set on first appearance; do not overwrite on re-runs}
  last_updated_at: {ISO-8601, refreshed every run}
  issue_url: {will be set in step 5 once the issue is filed; leave empty for now}

• disclosure-draft.md: contents of the finding's disclosure_draft field. Omit if empty.
• patch.diff: contents of suggested_fix. Omit if empty.

If a finding directory already exists in the clone, preserve the opened_at field from the existing metadata.yaml; everything else is overwritten by the new run's values. Validation reports and PoC files written by other skills (fix-validation, future PoC writer) live in the same directory and are also preserved across re-runs.