claude-in-codex 0.6.0__tar.gz

claude_in_codex-0.6.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "claude-in-codex",
+  "interface": {
+    "displayName": "Claude Code (for Codex)"
+  },
+  "plugins": [
+    {
+      "name": "claude-in-codex",
+      "source": {
+        "source": "local",
+        "path": "./plugins/claude-in-codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

claude_in_codex-0.6.0/.agents/skills/agent-friendly-github/SKILL.md

@@ -0,0 +1,102 @@
+---
+description: Use when configuring a GitHub repository so AI agents can work it safely — tracking issues, opening and managing pull requests — while humans keep confidence in code quality and security. Covers repo configuration (rulesets, branch protection, CODEOWNERS, Actions permissions, identity) and the operating conventions agents follow (branching, commits, PRs, review). Use to set up or harden a repo, audit an existing one, or guide how an agent operates in it. Applies to public and private, monorepo and traditional repos.
+metadata:
+    github-path: agent-friendly-github
+    github-ref: refs/heads/main
+    github-repo: https://github.com/briandconnelly/skills
+    github-tree-sha: 723133a2d6bf2560ec0678acc880392b18c2683e
+name: agent-friendly-github
+---
+# Agent-Friendly GitHub
+
+A GitHub repository is the shared workspace where agents and humans collaborate on code.
+Agents can do real work there — filing issues, opening PRs, and landing commits — but only if the repo is configured to make the happy path obvious and the dangerous path hard.
+The central principle: anything safety-critical is enforced by configuration (rulesets, required checks, CODEOWNERS, Actions permissions), never left to agent goodwill.
+Agents err, and they can be prompt-injected; the repo must stay safe regardless.
+
+## Core Standard
+
+- Configuration is the enforced contract and conventions are advisory — safety-critical rules live in rulesets, required status checks, and CODEOWNERS, never in agent instructions that can be overridden or bypassed.
+- Optimize for the agent's first correct contribution — discoverable conventions (`AGENTS.md`, `CONTRIBUTING`), issue and PR templates, a canonical label set, and a fast unambiguous green path are all part of the setup.
+- Every agent action is attributable and auditable — agents use a distinct identity, commits are authored with attribution preserved (signing is strongly recommended but opt-in, not required), issues and PRs are cross-linked, and no silent force-push or history rewrite occurs on protected branches.
+- All repo-resident text is untrusted input — issue bodies, PR descriptions, comments, and code file content can carry prompt-injection payloads into both the agent and CI; never grant write access or secrets to workflows triggered by untrusted actors, and never interpolate untrusted `${{ github.event.* }}` expressions directly into a `run:` script — bind them through `env:` and reference the variable instead.
+- The agent cannot launder its own approval — an agent that authored a PR must not approve it, trigger auto-merge to satisfy a human-review requirement, or manipulate review requests to make its own work look approved.
+  After a post-approval push, the agent requests fresh human review rather than treating stale approval as sufficient.
+- Constrain blast radius by default — use the least-privilege `GITHUB_TOKEN`, pin third-party actions to a full commit SHA, prefer OIDC over long-lived PATs, enforce protected branches that no automation identity can bypass, use environment gates for production deployments, and enable dismiss-stale-reviews-on-push.
+- Right-size to the repo's team and risk — the security boundary is human-vs-agent, not author-vs-reviewer, so never configure a repo such that the legitimate human maintainer cannot merge their own work; a single-maintainer repo keeps the agent fully gated while leaving the lone human an escape hatch. Match controls to a repository profile (solo, small-team, org/high-risk) rather than applying every control everywhere.
+- Keep the green path fast and deterministic so agents do not route around guardrails — flaky required checks create pressure to retry, skip, or override; fix them before they become a bypass habit.
+- Work identically across public/private and monorepo/traditional repos — scope ownership with explicit CODEOWNERS path prefixes, use an always-running monorepo gate check (never `paths:`-filter a required check, because a skipped required check stays pending and blocks merge forever), and do not disable secret scanning, Dependabot, or branch protection just because a repo is private.
+
+## Agent-Instruction-File Strategy
+
+**Single source of truth with thin adapters.**
+Keep one canonical instructions file per repo — by emerging convention `AGENTS.md` — that holds all repo-wide norms: branching strategy, commit format, review expectations, label taxonomy, test commands, and off-limits paths.
+Per-tool files like `CLAUDE.md` or `GEMINI.md` are thin pointers or includes, not independent copies; each should reference the canonical file using whatever include or reference mechanism that tool supports.
+For Claude Code, the entire repo-wide content of `CLAUDE.md` is a single line: `@AGENTS.md`.
+
+**What goes where.**
+Repo-wide conventions live exclusively in the canonical file.
+Tool-specific overrides — a tool's own invocation flags, permission scopes, or UI quirks — belong only in that tool's file, and only when they cannot be expressed generically.
+Reusable procedures (release workflows, audit checklists, operating playbooks) belong as committed artifacts rather than pasted into instruction files; instruction files cross-link to them instead.
+
+**Monorepo scoping.**
+In a monorepo, nest an `AGENTS.md` in each package or subtree that has meaningfully different rules; the root `AGENTS.md` covers cross-cutting norms.
+This mirrors CODEOWNERS path scoping: both files answer "who owns this path and what rules apply here?"
+
+**Drift control.**
+Keep instruction files short, authoritative, and CODEOWNERS-owned so changes go through review.
+Cross-link rather than duplicate; duplicate content drifts and creates conflicting instructions.
+Treat the canonical file as a first-class repository artifact, not an afterthought.
+
+## When To Use
+
+- Setting up a new repo for agent work, or hardening an existing one against the threat classes this skill covers.
+- Auditing an existing repo's agent-friendliness and security posture against the config checklist.
+- Guiding how an agent operates day-to-day in an already-configured repo — branching, committing, opening PRs, responding to review.
+
+## When Not To Use
+
+- Org-level settings: SSO enforcement, team membership, OAuth app policy — those live outside repo configuration.
+- CI pipeline design beyond the security surface — this skill hardens trigger permissions and injection points, not what the build actually does.
+- Self-hosted runner hardening — runner OS configuration and network isolation are out of scope.
+- At-scale repo provisioning or template instantiation — that is infrastructure-as-code territory.
+- GitHub Projects, Milestones, and Wikis except where they directly affect PR or issue traceability.
+- GitHub Enterprise Server specifics — flagged untested; the concepts likely apply but the exact field names and API paths have not been validated against GHES.
+
+## Vocabulary
+
+- **Enforced vs advisory contract**: enforced rules are implemented in rulesets, required checks, or CODEOWNERS and cannot be bypassed by agent action; advisory rules live in documentation and rely on good behavior.
+- **Protected branch**: a branch with rules applied via classic branch protection (predates rulesets) or a repository ruleset (preferred).
+- **Ruleset**: the current GitHub mechanism for branch and tag rules — supports bypass-actors lists, multiple target patterns, and org-level inheritance; prefer over classic branch protection.
+- **Required check**: a status check (CI job, code-quality gate) that must pass before a PR can merge; declared as a `required_status_checks` rule in the ruleset.
+- **CODEOWNERS path ownership**: a `CODEOWNERS` file entry that maps a glob path to one or more required reviewers; ownership is enforced when "Require review from code owners" is enabled in the ruleset.
+- **Agent identity**: how the agent is identified as the actor — a GitHub App installation (preferred: fine-grained permissions, short-lived tokens, clear audit trail), a bot PAT (broader scope, longer-lived, less auditable), or a user account (avoid for automated work).
+- **Least-privilege token**: a `GITHUB_TOKEN` or PAT scoped to only the permissions the current job requires; declared per-job in `permissions:` in the workflow file.
+- **Untrusted input / injection surface**: any repo-resident text the agent reads and acts on — issue titles, PR bodies, commit messages, code files, comments — that an adversary could craft to alter agent or CI behavior.
+- **Green path**: the end-to-end flow where the agent opens a branch, pushes commits, opens a PR, required checks pass, a human approves, and the PR merges without manual intervention.
+- **Blast radius**: the scope of damage if an agent is compromised or makes an error — limited by least-privilege tokens, pinned actions, protected branches, and environment gates.
+- **Attribution / audit trail**: the verifiable record of who authored each commit and triggered each action — preserved by a distinct agent identity, retained author and co-author metadata, linear history, and no squash-without-author-preservation; signed commits add tamper-evidence on top but are a recommended opt-in, not the load-bearing attribution control.
+- **Approval laundering**: a pattern where the agent that authored a PR also satisfies the human-review requirement, either by self-approving or by manipulating the review state.
+- **Dependency confusion / namespace hijacking**: a supply-chain attack where a public package with a higher version number shadows a private internal package; mitigated by explicit registry pinning and private package namespacing.
+- **Bypass-actors list**: the set of identities (individual users, teams, roles, or apps) that may bypass ruleset conditions on a protected branch; it must contain no automation identity the agent can act as (the agent, a bot PAT, a deploy key, or a CI app the agent uses), and is otherwise kept minimal and audited — a human maintainer may appear here in a solo/small-team repo as the documented escape hatch.
+- **Monorepo path scoping**: restricting rules, ownership, and required checks to specific directory prefixes so unrelated packages do not block each other.
+- **Canonical instructions file**: the single authoritative file (conventionally `AGENTS.md`) that all agents and per-tool adapter files defer to for repo-wide norms.
+
+## Workflow
+
+First pick the repository profile (solo, small-team, or org/high-risk) defined at the top of [config-checklist.md](references/config-checklist.md) — it determines which controls apply and, critically, keeps a single-maintainer repo from locking its lone human out of merging.
+Then classify your task and follow the matching path:
+
+- **Set up** a repo for agent work → follow [setup-workflow.md](references/setup-workflow.md).
+- **Audit** an existing repo's posture → follow [audit-workflow.md](references/audit-workflow.md).
+- **Operate** as an agent in a configured repo → follow [operating-playbook.md](references/operating-playbook.md).
+
+Both Set up and Audit walk [config-checklist.md](references/config-checklist.md) as their normative standard; Operate does not use the checklist and follows [operating-playbook.md](references/operating-playbook.md) exclusively.
+The rationale behind every checklist rule — including which threat class it mitigates — lives in [threat-model.md](references/threat-model.md).
+Concrete artifacts (ruleset JSON, CODEOWNERS snippets, workflow permission blocks, label YAML) live in [examples.md](references/examples.md).
+
+## Done Criteria
+
+- **Set up**: every item in [config-checklist.md](references/config-checklist.md) is either configured (with the specific GitHub field or setting noted) or explicitly marked N/A with a one-line justification; all emitted artifacts (ruleset JSON, CODEOWNERS file, workflow snippets) are listed.
+- **Audit**: every checklist item is recorded as a finding with severity and a `Tn` threat reference, `OK` with brief evidence, or `not-checked` with reason; the full report follows the format defined in [audit-workflow.md](references/audit-workflow.md).
+- **Operate**: the change followed every applicable rule in [operating-playbook.md](references/operating-playbook.md); the PR links its issue, all required checks pass, attribution is preserved in commit history, and no ruleset or review requirement was bypassed.

claude_in_codex-0.6.0/.agents/skills/agent-friendly-github/references/audit-workflow.md

@@ -0,0 +1,130 @@
+# Audit Workflow
+
+Use this workflow to assess an existing repository against [config-checklist.md](config-checklist.md).
+Findings must be grounded in evidence — a settings value, a file path and line, an API field, or a log excerpt — not in impressions.
+Where evidence is unavailable (e.g., you lack admin access to view ruleset bypass lists, or a feature is not applicable to the plan tier), mark the item `not-checked` and record the reason rather than guessing.
+
+**Safety:** Do not change live repository settings, rotate credentials, or trigger paid or destructive operations while auditing.
+All inspection is read-only: `gh api`, `gh ruleset view`, reading files in the repository, and reviewing Actions run logs.
+Do not run workflows, approve PRs, or write to the repository in any form during the audit.
+
+## Severity Scale
+
+- **Critical** — an active path to compromise or to an unreviewed merge reaching a protected branch.
+  Examples: an automation identity (the agent, a bot PAT, a deploy key, or a CI app the agent uses) present in the bypass-actors list of a protected-branch ruleset (§2, T4); a `pull_request_target` workflow that checks out and executes untrusted PR code with repository secrets available (§3, T2); an agent identity listed in `CODEOWNERS` for protected paths or whose approvals count toward the required-review threshold, allowing it to approve or auto-merge its own PRs (§1, §2, T3); a classic broad PAT with `repo`-wide write scope used by the agent (§4, T9); `ACTIONS_STEP_DEBUG` or `ACTIONS_RUNNER_DEBUG` enabled in a context where secrets are present (§3, T5).
+  Blocks confidence; fix before agents operate.
+
+- **High** — a guardrail is missing or easily defeated.
+  Examples: `dismiss_stale_reviews` not enabled, so a post-approval commit avoids re-review (§2, T3); third-party actions pinned to mutable tags or left unpinned (§3, T6); no dependency review or committed lockfile on a repository where agents add dependencies (§3, T7); no required reviews configured on protected branches (§2, T3); force-push or branch deletion not blocked on protected refs (§2, T4).
+
+- **Medium** — weakens auditability or team productivity without an immediate compromise path.
+  Examples: linear history is not required (§2, T8); the repo opted into signing but commits are unsigned (§2, T8); `CODEOWNERS` uses only a catch-all rule rather than explicit path prefixes (§1, T3); issue and PR templates are absent (§1, productivity); debug logging is enabled but no secret is currently exposed (§3, T5); the agent identity is a shared user account rather than a GitHub App or fine-grained PAT (§4, T8, T9).
+
+- **Low** — hygiene items.
+  Examples: `scope/<area>` labels missing in a monorepo (§1, productivity); `SECURITY.md` absent on a private repository (§1); `CONTRIBUTING.md` absent or not linked from `AGENTS.md` (§1, productivity); audit-log retention not explicitly considered (§4, T8).
+
+**Availability / operability** is a finding class orthogonal to the compromise-focused scale above: a control configured so strictly that the legitimate human maintainer cannot merge a compliant PR, ship a release, or apply an emergency fix.
+Rate it **High** normally, or **Critical** when it blocks a security fix or production recovery.
+Examples: a single-maintainer repo with required reviews and a bypass-actors list empty of any human, so the lone maintainer can never merge their own work (§2); `require_last_push_approval` or environment `prevent_self_review` enabled in a solo repo; `required_signatures` enforced where a committer has no signing path, rejecting all their pushes (§2, T8).
+Remediation is profile-aware — add the human bypass actor or relax the opt-in control to match the repository profile, not "remove all bypass actors."
+A non-empty bypass list is a finding only when it contains an automation identity the agent can act as; a human-maintainer bypass in a solo/small-team repo is expected, not a defect.
+
+## Audit Procedure
+
+1. **Establish context.**
+   Record whether the repository is public or private, monorepo or traditional, which branches are protected, and which agent identities operate here (GitHub Apps, fine-grained PATs, or shared user accounts).
+   Note stated scope (what the agent is permitted to do) and negative scope (what it must not do).
+   Record any checklist items that are not applicable to this repository type and mark them `not-checked` now, before walking the checklist.
+
+2. **Walk config-checklist.md §1 → §4, top to bottom.**
+   For each item, record exactly one of:
+   - a **finding** (severity + the Tn it implicates + evidence + remediation),
+   - **`OK`** with a one-line evidence pointer (setting value, `file:line`, or API field),
+   - **`not-checked`** with a reason (e.g., "admin access not available," "no GitHub Actions configured," "private repo — requirement does not apply").
+   A section may accumulate multiple findings; an item with both a finding and `OK` evidence on adjacent sub-items should note both.
+
+3. **Run the focused probes below** to confirm the highest-risk items rather than trusting settings labels.
+   The probes are read-only; run at least the Critical-risk ones and record the output or the reason they could not be run.
+
+4. **Synthesize into the report.**
+   Order findings Critical → Low, then by checklist section within each severity band.
+   After findings, assemble the coverage table (one row per §1–§4).
+
+## Probes
+
+Read-only checks to confirm the highest-risk controls.
+Run each with `gh api` or `gh ruleset view` unless otherwise stated.
+Mark each probe with the checklist section and threat class it targets.
+
+- **Bypass-actors list** — retrieve the default-branch ruleset and confirm `bypass_actors` contains no automation identity the agent can act as (its GitHub App / `Integration`, a bot PAT, a deploy key, or a role such as `Write` that the agent holds). A human-maintainer entry (an individual `User`, or `Maintain`/`Repository admin` the agent cannot hold) is expected in a solo/small-team repo and is not a finding; an empty list is expected in an org/high-risk repo.
+  `gh api repos/{owner}/{repo}/rulesets` then `gh ruleset view <id>`.
+  *(§2, T4)*
+
+- **`pull_request_target`, `workflow_run`, and injection surface** — list all workflow files in `.github/workflows/` and grep for `pull_request_target` or `workflow_run` as a trigger; for any `pull_request_target` match, check whether the workflow checks out or executes PR head code (`actions/checkout` with `ref: ${{ github.event.pull_request.head.sha }}` or equivalent), whether any privileged job is protected by an environment with human approval, and whether any `run:` step interpolates `${{ github.event.* }}` directly rather than binding through `env:`; for any `workflow_run` match, check whether the workflow downloads artifacts or caches from the triggering run (attacker-controlled when triggered by a fork PR) or checks out untrusted head code in a job that holds secrets or write scope.
+  *(§3, T2)*
+
+- **Agent identity listed in CODEOWNERS or counted as approver** — read the active `CODEOWNERS` file (GitHub looks for it at the repo root, in `.github/`, or in `docs/` — check all three) and check whether the agent account or app appears as an owner on any protected path; then check branch-protection or ruleset settings to confirm self-approval is not counted toward the required-review threshold.
+  *(§1, §2, T3)*
+
+- **Action pin format** — for each `uses:` line in all workflow files, confirm the pin is a full 40-character commit SHA, not a mutable tag (`@v3`, `@main`, `@latest`) and not absent.
+  *(§3, T6)*
+
+- **`dismiss_stale_reviews`** — in the branch-protection or ruleset configuration for the default branch, confirm `dismiss_stale_reviews` is `true`.
+  Legacy branch protection: `gh api repos/{owner}/{repo}/branches/{branch}/protection`.
+  Rulesets express the same control as `dismiss_stale_reviews_on_push`; if the repo uses rulesets, check via `gh ruleset view <id>` or the rulesets API instead — audit whichever path the repo actually uses.
+  *(§2, T3)*
+
+- **Debug logging flags** — check repository and environment variables for `ACTIONS_STEP_DEBUG` and `ACTIONS_RUNNER_DEBUG`; confirm neither is set to `true` in any environment used by the agent.
+  `gh api repos/{owner}/{repo}/actions/variables` and per-environment equivalents.
+  *(§3, T5)*
+
+- **`.gitignore` coverage and committed secrets** — confirm a `.gitignore` exists and covers secret-bearing paths (`.env*`, `*.pem`, `*.key`, credentials); then grep the tracked tree for already-committed secret files: `git ls-files | grep -iE '(^|/)\.env($|\.)|\.pem$|\.key$|credentials'` — any match is a finding regardless of what `.gitignore` contains, because `.gitignore` does not protect already-tracked files.
+  *(§1, T5)*
+
+- **Classic PAT scope** — if the agent uses a PAT, verify it is fine-grained, not classic.
+  A classic broad PAT used by the agent is a Critical finding.
+  You generally cannot enumerate classic PATs via the GitHub API — the org fine-grained-PAT endpoints (`/orgs/{org}/personal-access-tokens`, `/orgs/{org}/personal-access-token-requests`) list fine-grained PATs only and have no `token_type`/`classic` field.
+  Detect the risk via org policy instead: check whether the org restricts or forbids classic PAT access (Settings → Personal access tokens); review the fine-grained PAT inventory and approval policy via `gh api orgs/{org}/personal-access-tokens` (illustrative; lists fine-grained tokens only); and review the audit log for PAT-authenticated writes where available.
+  If none of these are accessible, mark the probe `not-checked` with that reason rather than asserting a clean result.
+  *(§4, T9)*
+
+## Finding Format
+
+Each finding has five labeled lines:
+
+- **Severity:** Critical | High | Medium | Low
+- **Section:** `§N` (list multiple if a finding spans sections)
+- **Threat:** `Tn`
+- **Evidence:** a concrete setting value, file path and line number, or log excerpt — never "it feels wrong."
+- **Remediation:** the exact mechanism to change (ruleset rule name, API field, file path), referencing config-checklist.md.
+
+**Worked example:**
+
+- **Severity:** Critical
+- **Section:** §2
+- **Threat:** T4
+- **Evidence:** `gh ruleset view 42` returns `"bypass_actors": [{"actor_id": 99, "actor_type": "Integration", "bypass_mode": "always"}, {"actor_id": 4, "actor_type": "RepositoryRole", "bypass_mode": "always"}]` — the agent's GitHub App and the `Maintain` role (which the agent account also holds) can both push directly to `main` without review or status checks.
+- **Remediation:** Remove every automation identity from `bypass_actors` — the agent App and any role the agent can hold (config-checklist.md §2: "no automation identity ... may appear in the bypass-actors list"). In a solo or small-team repo a human-maintainer `User` entry with `bypass_mode: pull_request` may remain as the documented escape hatch; in an org/high-risk repo the list should be empty.
+  Navigate to Settings → Rules → Rulesets → select the ruleset → Bypass list, remove the offending entries, then save.
+
+## Coverage Table
+
+One row per checklist section §1–§4.
+Each row records `finding(s)` with finding references, `OK` with a brief evidence pointer, or `not-checked` with a reason.
+The table below shows an illustrative example of a completed audit; replace values with actual findings.
+
+| Section | Status | Notes |
+| --- | --- | --- |
+| §1 Issues & PRs | finding F1; OK on remaining items | F1 (Medium): CODEOWNERS catch-all only — no explicit path prefixes; templates present at `.github/ISSUE_TEMPLATE/`; `CONTRIBUTING.md` present; `SECURITY.md` absent (private repo — Low) |
+| §2 Branch / Repo Guardrails | finding F2, F3 | F2 (Critical): agent GitHub App present in bypass-actors list on `main` ruleset — `gh ruleset view 42`; F3 (High): `dismiss_stale_reviews` is `false` — `gh api .../branches/main/protection` returns `"dismiss_stale_reviews": false` |
+| §3 Actions & Supply Chain | finding F4; OK on remaining items | F4 (High): three actions pinned to mutable tags (`actions/checkout@v4`, `actions/setup-node@v4`, `github/codeql-action@v3`) — `.github/workflows/ci.yml:12,18,34`; OIDC configured; secret scanning enabled |
+| §4 Auditability & Identity | OK | Agent uses GitHub App (App ID 1234); fine-grained tokens only; linear history required; audit-log retention set to 90 days at org level |
+
+## Done Criteria
+
+- Every §1–§4 item in config-checklist.md is accounted for in the coverage table: covered by at least one finding (with severity and a `Tn` threat reference), marked `OK` with brief evidence, or marked `not-checked` with an explicit reason.
+- Each finding carries all five labeled lines (Severity, Section, Threat, Evidence, Remediation).
+- At least the Critical-risk probes (bypass-actors list, `pull_request_target` injection surface, agent listed in `CODEOWNERS`, classic PAT scope) were run and their output or a reason they could not be run is recorded.
+- When no Critical or High findings are present, the report says so explicitly and names residual risks (e.g., "bypass-actors probe could not be run — admin access unavailable" or "no live Actions run logs were inspected for secret exposure").
+
+This mirrors the Audit Done Criteria stated in SKILL.md.

claude_in_codex-0.6.0/.agents/skills/agent-friendly-github/references/config-checklist.md

@@ -0,0 +1,107 @@
+# Configuration Checklist
+
+This is the mechanical standard walked by both the Set up and Audit workflows.
+Each item names the concrete GitHub mechanism where one exists, and otherwise states the policy to enforce; see `threat-model.md` for the rationale behind each control.
+Public/private and monorepo/traditional variations are noted inline where the requirement differs.
+Walk the sections in order; they are numbered §1–§4 and cited by that number elsewhere in the skill.
+
+## Plan & Visibility Caveats
+
+Several controls are gated by repository visibility and GitHub plan.
+Any control the repo's plan does not provide is marked N/A with the plan reason in an audit, and an external alternative is used where one exists.
+
+| Control | Public repos | Private / internal repos |
+| --- | --- | --- |
+| Rulesets / branch protection, CODEOWNERS, Dependabot | All plans | All plans |
+| Environment required reviewers & wait timers | All plans | GitHub Pro, Team, or Enterprise |
+| Code scanning (CodeQL), secret scanning + push protection, dependency review | Free | GitHub Advanced Security |
+
+## Repository Profiles
+
+Pick the profile that matches the repository, then walk §1–§4 applying the controls it calls for.
+Every profile shares a non-negotiable baseline; higher-risk profiles add controls on top.
+The baseline guarantees the property that must hold everywhere: an agent can never reach a protected branch unreviewed — and, equally, a control is never configured so the legitimate human maintainer is locked out of merging their own work.
+The security boundary is human-vs-agent, not author-vs-reviewer.
+
+**Baseline — all profiles:**
+- Agent identity is least-privilege and is NOT a bypass actor. (§2, §4; T4, T9)
+- Protected-branch ruleset: a PR is required, with >= 1 approving review, self-approval not counted, and force-push and deletion blocked — so the agent can neither self-approve nor self-merge. (§2; T3, T4)
+- Least-privilege `GITHUB_TOKEN`; no privileged `pull_request_target`/`workflow_run` on untrusted code; third-party actions pinned to a full commit SHA. (§3; T2, T5, T6)
+- `.gitignore` covers secret-bearing paths; secret scanning + push protection enabled where the plan provides it. (§1, §3; T5)
+- No classic broad PATs. (§4; T9)
+
+**solo** — one active human maintainer.
+Add a human bypass actor so the maintainer can merge their own work (see §2); CODEOWNERS is optional (single-owner) and "require review from code owners" is usually left off for the maintainer's own PRs.
+`require_last_push_approval`, merge queue, required deployments, team reviewers, and `required_signatures` are N/A unless the maintainer opts in.
+
+**small-team** — 2+ active humans, low-to-moderate risk.
+Routine changes get real human review with no bypass; CODEOWNERS by path; `dismiss_stale_reviews` on; `require_last_push_approval` recommended; signing opt-in.
+
+**org / high-risk** — production, regulated, or many contributors.
+All of the above plus merge queue, environment gates with required deployments, GitHub Advanced Security (code scanning, dependency review), `require_last_push_approval`, CODEOWNERS teams, and `required_signatures` if the org mandates it.
+
+## §1 Issues & PRs
+
+- Issue and PR templates are present and in use: `.github/ISSUE_TEMPLATE/` directory for issues and `.github/PULL_REQUEST_TEMPLATE.md` for pull requests. (productivity; closes T1 via reduced ambiguity)
+- Label taxonomy covers type and priority labels; monorepos add `scope/<area>` labels so PRs and issues are routable per subtree. (productivity)
+- `CODEOWNERS` uses explicit path prefixes, never a catch-all-only rule; owners on protected paths must be human users or teams, kept bot-free by membership hygiene — GitHub has no native "owners must be human" enforcement, so this is a repository policy you maintain.
+  The goal is that a required CODEOWNERS review can never be satisfied by an agent.
+  Monorepo: one prefix per owned subtree.
+  A human-owned last-resort catch-all is acceptable only after explicit path rules.
+  Solo: a single-user owner (`* @maintainer`) is fine, but a solo owner cannot satisfy their own required CODEOWNERS review, so either rely on the §2 human bypass to merge their own owned-path PRs or do not enable "require review from code owners" in a single-maintainer repo. (closes T3)
+- Required reviews are enabled on protected branches and enforced through CODEOWNERS. (closes T3)
+- Draft-first on owned paths is an operate convention, not a CI gate: open a protected-path change as a draft and wait for a human to promote it to ready; there is no robust required status check for "opened as draft" — a check that fails while the PR is ready-for-review blocks merge permanently, and one that only inspects the `opened` action is cleared by the next push; the enforcement for protected-path changes is the required CODEOWNERS review (§2), which requires a CODEOWNERS-listed human to approve. (closes T3)
+- Canonical instruction file (`AGENTS.md`) is present; per-tool files are thin references to it; reusable procedures live as committed artifacts, not pasted into instruction files; monorepos add a nested `AGENTS.md` per subtree. (closes T1 via clear guidance)
+- `CONTRIBUTING` is present and discoverable (`CONTRIBUTING.md` or `.github/CONTRIBUTING.md`) describing branch, PR, and review expectations that a contributor or agent must follow. (productivity; closes T1)
+- `SECURITY.md` is present (required for public repos; cross-referenced in §4 with private vulnerability reporting). (closes T1)
+- `.gitignore` is present and covers the language/framework's secret-bearing and noise paths (`.env*`, `*.pem`, `*.key`, `*.p12`, credential files, build output, caches, dependency dirs); it is the preventive layer in front of §3's secret scanning and push protection, and it keeps PR diffs reviewable; note it does NOT untrack already-committed files — a `git rm --cached` plus history rewrite is needed for those, and that rewrite is the force-push the branch guardrails otherwise warn against, which is why prevention via `.gitignore` matters. (closes T5)
+- `.gitattributes` sets `* text=auto` (with `eol=lf`, or `eol=crlf` on Windows-primary repos) to prevent line-ending churn across agent platforms, and marks true generated build output with `linguist-generated=true` to keep PR diffs reviewable.
+  Do not mark lockfiles as generated, because lockfile diffs are part of dependency review.
+  Note `linguist-generated` affects GitHub's diff display and language stats only — it does not enforce anything.
+  Adding `* text=auto` to a repo that already has mixed line endings will produce a one-time normalization commit on first add/commit. (auditability)
+- Metadata a PR template prompts for that matters for safety or correctness (a linked issue, a changelog entry, a migration note) is verified by a CI check that is marked REQUIRED in the §2 ruleset — a check enforces nothing until it is required, and a template's prose or checkboxes are never treated as evidence the property holds. (closes T3)
+
+## §2 Branch / Repo Guardrails
+
+- Rulesets (or branch protection) are applied to the default and release branches for ALL actors. No automation identity — the agent identity, a bot PAT, a deploy key, or any CI app the agent can act as — may appear in the bypass-actors list, so the agent can never push past the ruleset.
+  In a solo or small-team repo a human maintainer MAY be a bypass actor so the lone human can merge their own work — prefer an individual `User` entry with `bypass_mode: pull_request` (GitHub added user-level ruleset bypass in May 2026); where user-level bypass is unavailable (older GitHub Enterprise Server, etc.), use the `Maintain` or `Repository admin` role, but only if the agent provably cannot hold that role — never the `Write` role, which the agent does hold. This human entry is the documented escape hatch; the security boundary is human-vs-agent, not author-vs-reviewer.
+  Merge queue operates through the ruleset's normal flow and does not require a bypass-actors entry. (closes T4)
+- Required status checks are configured; in monorepos, use a single always-running gate check per relevant scope that detects changed paths internally and short-circuits (exits 0) when nothing relevant changed — do NOT use `paths:` filters on a required check, because a skipped workflow leaves the required check PENDING and blocks merge forever; there is no ruleset condition that scopes a required status check to changed file paths (branch rulesets target refs, not changed files), so the always-running aggregate gate or an external check app are the correct alternatives. (closes T4)
+- `dismiss_stale_reviews` is enabled so a post-approval push invalidates the prior approval; this is the branch-protection field (`dismiss_stale_reviews_on_push` in the rulesets API), not merely an agent convention. (closes T3)
+- `require_last_push_approval` is enabled (small-team and org profiles) so the most recent push must be approved by someone other than its author, preventing an author from pushing after approval and merging unreviewed code; this is the strongest anti-approval-laundering control because it directly closes the "approve then sneak a commit" gap.
+  It requires a second human, so it deadlocks a single-maintainer repo — in the solo profile leave it off and rely on the agent being unable to self-approve or bypass. (closes T3)
+- Linear history is required. (closes T8)
+- Signed commits are strongly recommended and enforced (`required_signatures`) only when the maintainer opts in AND every committer — humans and the agent — has a working signing path; define the accepted mechanism (GitHub App commit signing, GPG, or SSH) so audits know what evidence to check.
+  Do not enable `required_signatures` by default: it rejects every unsigned push, an agent that commits locally and pushes with a GitHub App token is NOT auto-signed, and required signing can block a non-author from squash-merging a PR through the web UI. Attribution itself rests on a distinct identity, preserved trailers, and linear history (§4), not on signing. (closes T8)
+- Merge queue is configured where serialized merges matter. (productivity; closes T4)
+- Force-push and branch deletion are blocked on protected refs. (closes T4)
+- Auto-merge safety is a combination, not a single setting: required approving review count >= 1, self-approval not counted, and a CODEOWNERS-required human review — GitHub has no native "human-only approver" flag, so you assemble it from these three settings.
+  The solo-profile human bypass actor does not weaken this: it lets the human merge their own work, while the agent (excluded from bypass) still cannot approve or merge its own PR. (closes T3)
+- Environment or deployment protection rules gate production via required reviewers or a wait timer on the environment.
+  Caveat: environment required reviewers and wait timers are available on public repos on all plans, but on private/internal repos they require GitHub Pro, Team, or Enterprise; if the plan does not provide them, use an external deployment-approval mechanism and mark this item N/A with the plan reason. (closes T5)
+
+## §3 Actions & Supply Chain
+
+- `GITHUB_TOKEN` permissions are least-privilege at both layers: the repository/org Actions "Workflow permissions" setting sets the DEFAULT `GITHUB_TOKEN` permission — set it to read-only so workflows that declare nothing start least-privilege; it is a default, not a hard ceiling, because a workflow can still elevate permissions via its own top-level or job `permissions:` block, so the per-workflow least-privilege `permissions:` declaration is the actual control — declare it in every workflow.
+  Additionally, for workflows triggered by fork PRs the `GITHUB_TOKEN` is read-only with no repository secrets by default unless explicitly enabled. (closes T5)
+- Untrusted `github.event.*` strings are never interpolated directly into `run:` steps; bind them through `env:` and reference it as a quoted shell variable (e.g. `"$PR_TITLE"`), never via `eval`. (closes T2)
+- `pull_request_target` and `workflow_run` discipline: both run privileged with repository secrets and a write-capable token even when the triggering workflow could not, so prefer plain `pull_request` for untrusted fork PRs because it is read-only with no repository secrets by default.
+  If `pull_request_target` is unavoidable, no job checks out or executes untrusted head code, and any job with secrets or write scopes is gated behind a protected environment with human approval.
+  For `workflow_run`, do not trust artifacts, caches, or other inputs downloaded from the triggering run (they are attacker-controlled when the triggering run came from a fork), and do not check out untrusted head code in any `workflow_run` job that holds secrets or write scope. (closes T2)
+- Third-party actions are pinned to a full commit SHA, not a mutable tag. (closes T6)
+- OIDC is used for cloud authentication instead of stored long-lived secrets. (closes T5, T9)
+- Secret handling: `ACTIONS_STEP_DEBUG` and `ACTIONS_RUNNER_DEBUG` are not enabled in production (debug logging can expose secrets). (closes T5)
+- Dependabot is enabled for both version updates and security updates. (closes T6)
+- Dependency-update PRs (Dependabot or version bumps) pass through the same required reviews and status checks as any other change; where auto-merge is used it is limited to non-major updates with green checks and never bypasses the required review assembled in §2. (closes T6)
+- Code scanning is enabled (CodeQL or an equivalent analyzer); on private/internal repos this requires GitHub Advanced Security (free on public repos) — configure where available, otherwise mark N/A with the plan reason. (closes T6)
+- Secret scanning is enabled with push protection; on private/internal repos this requires GitHub Advanced Security (free on public repos) — configure where available, otherwise mark N/A with the plan reason. (closes T5)
+- Dependency review is enabled on PRs; for agent-added packages, a scoped or private registry and a committed lockfile blunt dependency confusion; on private/internal repos dependency review requires GitHub Advanced Security (free on public repos) — configure where available, otherwise mark N/A with the plan reason. (closes T6, T7)
+
+## §4 Auditability & Identity
+
+- Distinct agent identity is provisioned, in preference order: GitHub App > fine-grained bot PAT > shared user account. (closes T8, T9)
+- PATs, where used at all, are fine-grained and short-lived; classic broad PATs are never used. (closes T9)
+- Commits are authored with attribution preserved through squash and rebase — when squash-merging, verify the `Co-authored-by:` trailers survive into the final squash commit message, since squash builds a new message and drops trailers not carried into it; humans are co-authored when pairing; commits are signed when the repo opts into required signing (recommended, not required by default — see §2). (closes T8)
+- Audit-log retention is configured or explicitly considered for the org or repo plan. (closes T8)
+- No mid-session privilege escalation: token scopes are provisioned up front; widening scope requires a human action. (closes T9)
+- Private vulnerability reporting is enabled and `SECURITY.md` is present for public repos (see §1). (closes T1)