Skip to content

fix(security): bind /approve plan execution to verified comment and prune excess MCP tools - #540

Closed
elberthc-byte wants to merge 1 commit into
google-github-actions:mainfrom
elberthc-byte:b-584422505
Closed

elberthc-byte wants to merge 1 commit into
google-github-actions:mainfrom
elberthc-byte:b-584422505

Conversation

@elberthc-byte

Copy link
Copy Markdown

Summary

Hardens the @gemini-cli /approve plan-execution flow against Time-of-Check to Time-of-Use (TOCTOU) comment substitution, post-plan issue-body injection, shell-interpolation hazards, and over-privileged MCP tool grants:

  1. Deterministic Pre-Execution Plan Verification (action.yml + scripts/resolve-approved-plan.mjs): Replaces LLM-driven "find a latest plan titled 'AI Assistant: Plan of Action'" comment lookup with a deterministic verification step in action.yml before gemini --yolo starts. Approval now requires binding to a specific plan comment ID or URL (@gemini-cli /approve <comment-url-or-id> [sha256:<prefix>]), verifies approver association (OWNER, MEMBER, COLLABORATOR), verifies plan authorship, rejects un-hashed pre-approval edits and all post-approval edits, fetches the target comment in $O(1)$ (GET /repos/{owner}/{repo}/issues/comments/{comment_id}), and writes a verified .gemini/approved_plan.json artifact (failing closed before Gemini CLI runs if any check fails).
  2. Eliminate Post-Plan Issue-Body Injection & !{echo $...} Interpolation: Excludes mutable title and description (issue.body) from .gemini/context.json during gemini-plan-execute (retaining routing fields event_name, is_pull_request, issue_number, and repository only), migrates shipped .github/commands/gemini-{invoke,plan-execute}.toml templates from !{echo $...} shell execution to @{.gemini/context.json} / @{.gemini/approved_plan.json}, and updates .geminiignore (plus .git/info/exclude when untracked) so .gitignore's .gemini/ entry does not cause Gemini CLI's AtFileProcessor to skip .gemini/*.json artifacts.
  3. Least-Privilege MCP Tool Allowlist: Removes push_files, delete_file, fork_repository, issue_read, list_issues, and search_issues from mcpServers.github.includeTools in gemini-plan-execute.yml (both .github/workflows/ and examples/workflows/), and automatically prunes those tools from .gemini/settings.json at action runtime so existing @v0 consumers receive least-privilege enforcement automatically.

Implementation Details

  • Approval Binding & TOCTOU Protection (scripts/resolve-approved-plan.mjs, scripts/resolve-approved-plan.d.mts, action.yml):
    • Fail-Closed Action Gate: action.yml deletes any pre-existing .gemini/approved_plan.json prior to running resolve-approved-plan.mjs --verify and verifies [[ -s ".gemini/approved_plan.json" ]] afterward, resolving symlinks via realpathSync in isExecutedAsMainScript() so macOS (/var -> /private/var) and symlinked self-hosted runners never skip verification.
    • Webhook & Directive Validation: Validates event.action (created for issue_comment and pull_request_review_comment, submitted for pull_request_review), verifies sender.type === 'User' and author_association in ['OWNER', 'MEMBER', 'COLLABORATOR'], detects PR conversation comments via event.issue.pull_request, rejects duplicate/malformed binding tokens, and verifies full comment URLs match the current <owner>/<repo> and issue/PR number.
    • Bot Provenance & @v0 Compatibility: Enforces EXPECTED_PLAN_AUTHOR (<app-slug>[bot] when minted via actions/create-github-app-token, or github-actions[bot]). When EXPECTED_PLAN_AUTHOR is unset (existing @v0 workflows), probes GET /user for custom PATs and accepts repository-installed GitHub App bots (user.type === 'Bot', login.endsWith('[bot]'), and performed_via_github_app present) while rejecting external User commenters.
    • Timestamp, Monotonic ID, & Digest Integrity: Rejects bare @gemini-cli /approve without a target comment ID/URL; rejects comments with id >= approvalId (on issue_comment) or timestamps after approval; rejects plans edited in-place prior to approval (updated_at !== created_at) unless the approver explicitly pins sha256:<prefix> (CRLF-normalized, printing the 12-char digest hint in logs); and verifies comment.issue_url matches the target repository and issue number.
    • Workspace & Symlink Guards: Rejects symlinked .gemini paths or path traversal outside the workspace root (lstatSync + realpathSync), appends the ordered .geminiignore negation stanza at EOF, and adds /.geminiignore to .git/info/exclude when untracked so git add . workflows never stage .geminiignore.
  • Workflow, Prompt, Eval, & Documentation Updates:
    • Synchronized .github/commands/gemini-{invoke,plan-execute}.toml and .github/workflows/gemini-{invoke,plan-execute}.yml with examples/workflows/gemini-assistant/ and examples/workflows/gemini-dispatch/gemini-dispatch.yml.
    • Updated evals/gemini-assistant.eval.ts, evals/gemini-plan-execute.eval.ts, and evals/data/gemini-plan-execute.json for .gemini/context.json and .gemini/approved_plan.json.
    • Added .github/workflows/ci.yml (permissions: contents: 'read', SHA-pinned actions) and wired npm test to evals/vitest.security.config.ts (pool: 'forks'), plus allowJs/checkJs strict typechecking in tsconfig.json.
    • Updated examples/workflows/gemini-assistant/README.md, examples/workflows/gemini-dispatch/README.md, and examples/workflows/CONFIGURATION.md.

Breaking Changes & Compatibility

  • Explicit Comment Binding Required on /approve: Bare @gemini-cli /approve without a comment URL or ID now fails closed with an actionable error message instructing maintainers to reply with @gemini-cli /approve <comment-url-or-id>. gemini-invoke.toml has been updated to print this exact instruction in new plan comments.
  • Existing @v0 Workflows: Existing consumers pinned to google-github-actions/run-gemini-cli@v0 remain compatible across github.token, Custom GitHub Apps (vars.APP_ID), and custom PATs (secrets.GITHUB_TOKEN) without requiring immediate workflow YAML re-copying, and automatically receive .gemini/context.json and .gemini/settings.json sanitization.

Verification

1. Automated Unit, Integration, & Linter Checks

  • Vitest (npm test, pool: 'forks'): 29 passed (29) in evals/gemini-plan-execute.security.test.ts covering static YAML/TOML security invariants, generate-examples.sh parity, directive/URL/SHA-256 parsing, PR review vs. issue comment ID namespaces, TOCTOU race and edit rejection, cross-repo/cross-issue URL spoofing, symlinked action runner execution, .gemini/settings.json tool pruning, .geminiignore ordering + .git/info/exclude, and live local HTTP server subprocess execution.
  • Static & CI Linters: Passed strict TypeScript + JS checking (tsc --allowJs --checkJs --strict --noEmit), eslint --max-warnings 0, actionlint, shellcheck --enable=all, yamllint, prettier --check, and npm run build.

2. End-to-End Manual Shell & HTTP Verification Matrix

Executed the composite action bash pipeline (Prepare prompt context -> Install Custom Commands -> Verify approved plan) against a local HTTP GitHub API mock server across temporary git workspaces containing .gitignore (.gemini/):

# Scenario Input / State Observed Result
1 Valid comment-URL approval + .gitignore/.geminiignore Bot plan #100 (created_at == updated_at), OWNER posts @gemini-cli /approve ...#issuecomment-100 exit 0; writes .gemini/approved_plan.json, strips title/description from .gemini/context.json, prunes disallowed MCP tools from .gemini/settings.json, un-ignores context/plan files
2 Bare @gemini-cli /approve (no comment ID/URL) Bot plan #100 exists, OWNER posts bare @gemini-cli /approve exit 1 (fail-closed; rejects unbound latest-comment selection)
3 [T_read, T_approve] race (newer comment before /approve) Bot plan #100 (18:00Z), newer comment #150 (18:04Z) before MEMBER posts /approve #issuecomment-100 (18:10Z) exit 0; binds strictly to #100 via $O(1)$ comment fetch
4 Untrusted public commenter plan targeted by ID External User posts #150, OWNER posts /approve 150 exit 1 (author "public-user" is not an authorized plan bot)
5 Pre-approval in-place comment edit without sha256: pin Bot plan #100 (created_at: 18:00Z, updated_at: 18:03Z), OWNER posts /approve 100 exit 1 (prints sha256:<12-char> digest hint for inspection)
6 Pre-approval in-place edit with matching sha256: pin Same as #5, COLLABORATOR posts /approve 100 sha256:<matching-prefix> exit 0 (explicitly authorized digest verified)
7 Post-approval edit (updated_at > approvalTimestamp) Bot plan #100 edited at 18:11Z after 18:10Z /approve, even with hash exit 1 (created or modified after approval)
8 Unauthorized approver (CONTRIBUTOR) / edited webhook action CONTRIBUTOR posts /approve 100 or issue_comment.edited event exit 1 (rejected before LLM execution)
9 Symlinked GITHUB_ACTION_PATH (macOS /var -> /private/var) Invoked via symlinked directory both with valid and invalid events Valid -> exit 0 & writes artifact; invalid -> exit 1 (never fails open)

Checklist

  • Validated action.yml and workflow YAML manifests (actionlint, yamllint)
  • Synchronized .github/ and examples/workflows/ templates
  • Added comprehensive unit and end-to-end tests (npm test)
  • Updated documentation (examples/workflows/gemini-assistant/README.md, examples/workflows/gemini-dispatch/README.md, examples/workflows/CONFIGURATION.md)
  • Formatted code with Prettier

…rune excess MCP tools

- Verify @gemini-cli /approve comments deterministically in action.yml
  (scripts/resolve-approved-plan.mjs) before launching Gemini CLI with
  contents: write, requiring explicit comment ID/URL binding, verifying
  approver association and bot authorship, rejecting un-hashed edits and
  post-approval mutations, and writing .gemini/approved_plan.json.
- Exclude mutable issue title/description from plan-execute context.json,
  migrate shipped .github/commands/gemini-{invoke,plan-execute}.toml from
  !{echo $VAR} shell interpolation to @{.gemini/...}, and configure
  .geminiignore + .git/info/exclude so AtFileProcessor reads .gemini/*.json.
- Remove push_files, delete_file, fork_repository, issue_read, list_issues,
  and search_issues from plan-execute MCP includeTools (and prune existing
  @v0 .gemini/settings.json files automatically).
- Add CI workflow, strict JS/TS typechecking, documentation updates, and
  29 Vitest security/unit/integration tests.
@elberthc-byte

Copy link
Copy Markdown
Author

/gemini review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant