/cloud-findings

name: cloud-findings
description: Read existing Codex Security Cloud findings, reports, recorded assignment and verification, and scan status from the connected account. Use for Cloud read requests and finding links, not local scans or requests to change Cloud data.

Cloud findings

Use the connected Codex Security Cloud tools for existing findings and scans. This workflow only reads data. Do not launch or cancel scans, close or edit findings, generate patches, run verification, upload results, or send notifications. The connector has other tools that can write; connecting it does not make those tools part of this workflow. Local security scans do not need Cloud connected.

Before using the tools and filters below, discover the relevant `defense_factory_*` tools through tool search and inspect their current schemas. Use only exposed tools and parameters. If a requested capability is unavailable, explain which part cannot be completed and continue with the supported parts of the request. A report available only through a missing evidence reader remains unread; a missing `assignee` filter cannot perform an assignee-filtered query. Do not silently drop a requested filter or describe a partial answer as complete.

Resolve the account and repository

Call `defense_factory_bootstrap` before data reads. Reuse its result within the request; check again after the user changes accounts or workspaces, completes setup, or a permission error requires renewed context. Use its `identity` and `accountId` as the selected account context. A workspace ID in a prompt or link does not override the signed-in account.

• If workflows are disabled, `requiresSecurityAccess` is true, or `billingAccess` is `unsupported`, explain the returned requirement and stop data calls.
• If `access` is `denied` and `requiresCodexCloud` is true, Cloud scanning setup is unavailable. That combined setup result does not establish whether saved findings are readable. For an explicitly selected project or supplied finding, run, or artifact ID, use the authorized read tools to resolve access. Do not infer permission from `requiresSecurityAccess: false`; stop if a read is denied. For other `access: denied` results, explain the returned requirement and stop data calls.
• GitHub setup state is advisory for direct reads. If `githubConnected` is false or `githubConnectorIds` is empty, explain that repository discovery may need a GitHub connection, but still resolve explicit finding, run, and artifact IDs through their authorized read tools. Existing access rules may allow those reads. If discovery is needed or a tool returns `no_github_connection`, explain the required setup. In an interactive session, use `open_defense_factory` if available and the client supports its UI; otherwise direct the user to Cloud's web interface and their GitHub connection settings. Refresh bootstrap after setup completes. Null connection state means discovery was unavailable; it does not prove that existing reads are denied.
• If authentication is missing or expired, direct the user to sign in and connect Cloud through Codex. Do not extract credentials or use a separate HTTP client. In `codex exec`, return the needed setup action instead of waiting for login.

Use `defense_factory_github_search`, `defense_factory_github_repositories`, or `defense_factory_github_get` to resolve repositories on the connectors returned by bootstrap. Preserve returned repository and connector IDs, including GitHub Enterprise identities. `defense_factory_workflow_repositories` can locate repositories with recorded runs. A local checkout name alone does not identify a Cloud repository. Ask the user to choose when account or repository context is ambiguous; in noninteractive use, stop with the ambiguity and required selection. An explicit request for all accessible repositories may use that broader scope.

For a finding link, accept the selected Cloud `webOrigin` with the path `/codex/cloud/security/findings/<finding-id>` or the legacy `/codex/security/findings/<finding-id>`. Decode the final path segment once and resolve it through `defense_factory_findings_get`. Preserve combined finding IDs (`commit:…`, `rf_…`, or `pro_…`) returned by Cloud. A commit-finding link under either accepted path may use a bare finding ID; pass that as `commit:<finding-id>`. Do not substitute a grouped issue, scan, or PR ID. For an unsupported origin or path, explain which finding link or ID is needed instead of guessing another record. Use returned Cloud links when available. Every direct detail or evidence read must go through its tool, even for an ID that was previously listed.

List and inspect findings

Use `defense_factory_findings_list` with the discovered repository URL in `repo` and the user's filters; `repo` accepts comma-separated URLs, not repository IDs. Workflow tools use the returned repository ID in `repo_id`. Filters may include severity (`criticality`), lifecycle `status`, `source`, `q`, `path_prefix`, `start_at`, `end_at`, `scan_id`, `review_run_id`, `validated`, `has_patch`, `author`, and `assignee`; use the tool's current schema for available filters and their accepted values. `assignee` accepts comma-separated recorded user emails and is separate from commit authorship. Do not invent an assigned-team filter.

Follow returned cursors with the same filters and sort order when a complete list or count is requested. Reset the cursor if the filters change. State when only a page or a subset was read. For repository-run findings, use `source: repository_scan` and `scan_id` equal to the run ID. Inspect selected finding IDs with `defense_factory_findings_get` before describing their evidence, assignment, patches, or verification.

Keep these records separate in the answer:

• **Assignment:** the recorded assignee, never the commit author or a suggested owner. An assignment object with empty members means unassigned; `assignment: null` means the source does not supply assign