Skip to main content
Send CodeRabbit security findings to your security tools, and triage them from scripts or agents. For what Deep Scan finds and how to read a finding, see CodeRabbit Security.

Before you start

  • See Authentication for the keys each operation accepts and Conventions for base URLs, pagination, errors, and rate limits. The Deep Scan and Bug Scan findings exports are export and user-management operations. The other Security operations are product operations.
  • The curl examples read the key from CODERABBIT_API_KEY. The upload steps read SARIF files with jq.

Choose an operation

Export Deep Scan code findings

  1. Call List or download Deep Scan code findings. By default, it returns open findings from the latest completed scan of each repository in the key’s scope. Its reference lists the filters for one repository, an earlier scan, and the finding state. With a workspace token, org_id selects one organization.
  2. While next_cursor isn’t null, request the next page with cursor set to that value and the same filters.
  3. To download the whole inventory instead, add format=csv or format=sarif. A download holds every finding that matches the filters, up to 50,000 findings and 16 MiB; larger results return 413, so narrow them with repo_id or scan_id. The CLI prints JSON only, so download CSV and SARIF with curl.
Each format carries the explanation and the reachability call stack in a different place:
  • JSON: description and the reachability_call_stack array.
  • CSV: the description column, and the call stack as a JSON-encoded array in the reachability_call_stack column.
  • SARIF: runs[].results[].message.text for the explanation and runs[].results[].properties.reachabilityCallStack for the call stack.
An empty call stack means CodeRabbit captured none, not that the finding is unreachable. For a finding’s full scan provenance, including evidence, use SARIF: CSV keeps a compact summary, and paged JSON doesn’t load evidence. This operation doesn’t start scans or change scan billing, and it doesn’t need a Security add-on or trial.

Upload Deep Scan findings to GitHub code scanning

Code scanning keeps results per repository and commit, so upload one SARIF file per repository.
  1. Get the repository IDs from List repositories on GitHub Cloud, or from List organization repositories on the Enterprise plan.
  2. Download a SARIF file for each repository with repo_id. Pause between requests; see Rate limits.
    --fail makes curl report an error response, such as 413 for an export that’s too large, instead of saving it as a SARIF file, so only successful downloads leave a file. --retry retries a 429 after the Retry-After interval. Before you upload, delete the SARIF files of earlier runs, so a failed download can’t leave an old file in place.
  3. Read the scanned commit from the file. Without scan_id, a download holds the repository’s latest completed scan, and each result names the scan in properties.scanProvenance.scanId and its commit in properties.scanProvenance.scope.primary.revision.
    If the command prints nothing, the file has no findings or the scan recorded no commit; skip it. Skipping the upload doesn’t replace the previous GitHub analysis, so earlier results can remain visible. If you take the commit from a JSON call instead, pass that row’s scan_provenance.scanId as scan_id when you download, so both describe the same scan even when a newer one completes in between.
  4. Upload each file to its repository with the github/codeql-action/upload-sarif action. Set sha to the scanned commit and ref to the full reference of the scanned branch, such as refs/heads/main. Otherwise, GitHub attaches the results to the commit of the workflow that uploads them.
Deep Scan results carry no partialFingerprints, which code scanning uses to recognize the same alert across uploads. The upload-sarif action computes them from the source files, so run it in a checkout of the scanned commit. The code scanning REST API doesn’t compute them, so uploads through it can create duplicate alerts. GitHub rejects a SARIF file larger than 10 MB after gzip compression. It accepts up to 25,000 results per run and keeps the 5,000 most severe. See SARIF support for code scanning for the other limits.

Export Bug Scan findings

  1. Call List or download Bug Scan findings with repo_id, the repository’s Git provider ID. For a Bitbucket Cloud repository, use its UUID in braces. The operation reads the latest completed scan unless you pass scan_id, and you can filter by severity.
  2. Read scan for the scan’s id, head_commit, completed_at, and partial_coverage. When the repository has no completed scan, scan is null and data is empty. Findings come in the scan’s rank order, and each has a state of open, fixed, or dismissed.
  3. While next_cursor isn’t null, request the next page with cursor set to that value. A cursor stays on the scan it came from, even after a newer scan completes. Sending a different scan_id with it returns 400 INVALID_CURSOR.
  4. To download every finding of the scan, add format=csv or format=sarif. Downloads are limited to 50,000 findings and 16 MiB; larger results return 413, so filter by severity.
state isn’t a filter, and sending it returns 400. With a workspace token, a repository ID that more than one organization holds returns 400 AMBIGUOUS_REPOSITORY; pass org_id to pick the organization. An organization without Bug Scan gets 403 BUG_SCAN_NOT_ENABLED. repo_id is required, so to cover every repository, call the operation once per repository. Take the IDs from List repositories or List organization repositories, as for Deep Scan, and pause between calls. Skip a repository whose scan is null: it has no completed scan.

Upload Bug Scan findings to GitHub code scanning

A Bug Scan SARIF file names its scan in runs[0].properties.scanId and the scanned commit in runs[0].properties.headCommit. Read the commit from the file you upload, so it always matches the findings in it:
If headCommit is null, the scan recorded no commit; skip the file. If you read scan.head_commit from a JSON call instead, pass its scan.id as scan_id when you download. Upload the file with the github/codeql-action/upload-sarif action or the code scanning REST API. Set the commit SHA of the upload to the scanned commit and its ref to the full reference of the scanned branch, such as refs/heads/main. Otherwise, GitHub attaches the results to the commit of the workflow that uploads them. Each result carries a stable fingerprint in partialFingerprints, so code scanning tracks a finding across uploads. GitHub’s size limits from the Deep Scan upload apply too.

Work with findings through the Security operations

These operations work for GitHub Cloud organizations. They use the same access rules as the CodeRabbit app: reading needs Security read access, and starting scans, requesting fixes, and changing a finding’s state follow the rules in Access and billing.

List and read findings

Export a software bill of materials

List software bill of materials components pages through components. Export a software bill of materials downloads it as CycloneDX, SPDX, or CSV. Both can be limited to specific repositories.

Start a scan

  1. Estimate the cost with Estimate an AI Deep Scan. Its fresh field tells you whether the estimate is current. An estimate doesn’t start a scan.
  2. Call Request security scans for installed repositories with the repositories, the targets to scan, and the scan mode. A scan_mode of deep with the code target runs a Deep Scan. To cap the spend, set spend_limit_cents.
  3. Check results for each repository. triggered means CodeRabbit accepted the scan, not that it finished. blocked comes with a blockedReason and can include blockedRetryAfterSeconds.
  4. Follow progress with List security scan activity or Read a security scan.
When the available Deep Scan credits can’t cover a scan, someone with Subscription write access confirms the charge: send paid_usage_confirmation with the estimate in estimateCents and the credit amount in creditCents. Only a Deep Scan can be confirmed this way. For how Deep Scan billing works, see Deep Scan estimates and billing.

Fix, dismiss, or reopen a finding

For what each action does in the product, see Triage and remediate findings.

Read runtime validation results

  1. Call Read runtime validation availability for a finding. This call doesn’t start a validation.
  2. If available is true, pass its findingIdentityId as finding_identity_id to List runtime validation attempts for a finding.
  3. Read an attempt with Read a runtime validation result.
For how CodeRabbit verifies findings at runtime, see Runtime verification.

Handle errors

For response formats and other codes, see Errors and Rate limits.

What’s next

CodeRabbit Security

Learn how Deep Scan works, what it reports, and how to triage findings in the app.

Runtime verification

Reproduce Deep Scan findings in a test environment before you fix them.

Authenticate requests

Pick the API key type each security operation accepts.