> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Export and manage security findings

> Export Deep Scan code findings and Bug Scan findings as JSON, CSV, or SARIF, and list, scan, fix, dismiss, and reopen findings with the CodeRabbit Security operations.

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](https://docs.coderabbit.ai/security.md).

## Before you start

* See [Authentication](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts) for the keys each operation accepts and [Conventions](https://docs.coderabbit.ai/api/conventions.md) 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

| Task | Operation | Availability |
| - | - | - |
| Download Deep Scan code findings as JSON, CSV, or SARIF | [Deep Scan code findings](https://docs.coderabbit.ai/api/reference/security-scans-code-list.md) | Every plan and supported Git provider. Needs Security read access. |
| Download one repository's Bug Scan findings as JSON, CSV, or SARIF | [Bug Scan findings](https://docs.coderabbit.ai/api/reference/bug-scan-findings-list.md) | Organizations with Bug Scan enabled. Needs the `bug_scan:read` permission. |
| List findings, secrets, dependencies, and SBOMs; start scans; request fixes; dismiss and reopen findings | The Security operations under `/v1/security` | GitHub Cloud organizations |

## Export Deep Scan code findings

1. Call [List or download Deep Scan code findings](https://docs.coderabbit.ai/api/reference/security-scans-code-list.md). 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.

   ```bash theme={null}
   curl --get "https://api.coderabbit.ai/v1/security/scans/code" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "repo_id=123456789" \
     --data-urlencode "state=all"
   ```

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.

   ```bash theme={null}
   curl --get "https://api.coderabbit.ai/v1/security/scans/code" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "repo_id=123456789" \
     --data-urlencode "format=sarif" \
     --fail --silent --show-error \
     --output deep-scan.sarif
   ```

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](https://docs.coderabbit.ai/api/reference/list-repositories.md) on GitHub Cloud, or from [List organization repositories](https://docs.coderabbit.ai/api/reference/organization-repositories-list.md) on the Enterprise plan.

2. Download a SARIF file for each repository with `repo_id`. Pause between requests; see [Rate limits](https://docs.coderabbit.ai/api/conventions.md#rate-limits).

   ```bash theme={null}
   for repo_id in 123456789 987654321; do
     curl --get "https://api.coderabbit.ai/v1/security/scans/code" \
       --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
       --data-urlencode "repo_id=$repo_id" \
       --data-urlencode "format=sarif" \
       --fail --silent --show-error --retry 5 \
       --output "deep-scan-$repo_id.sarif" \
       || echo "Download failed for repository $repo_id" >&2
     sleep 6
   done
   ```

   `--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`.

   ```bash theme={null}
   jq -r '.runs[0].results[0].properties.scanProvenance.scope.primary.revision // empty' deep-scan-123456789.sarif
   ```

   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](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) for the other limits.

## Export Bug Scan findings

1. Call [List or download Bug Scan findings](https://docs.coderabbit.ai/api/reference/bug-scan-findings-list.md) 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.

   ```bash theme={null}
   curl --get "https://api.coderabbit.ai/v1/bug-scan/findings" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "repo_id=123456789" \
     --data-urlencode "severity=critical"
   ```

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](https://docs.coderabbit.ai/api/reference/list-repositories.md) or [List organization repositories](https://docs.coderabbit.ai/api/reference/organization-repositories-list.md), 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:

```bash theme={null}
jq -r '.runs[0].properties.headCommit // empty' bug-scan-123456789.sarif
```

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](#upload-deep-scan-findings-to-github-code-scanning) 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](https://docs.coderabbit.ai/security.md#access-and-billing).

### List and read findings

* [List code and secret findings](https://docs.coderabbit.ai/api/reference/list-security-findings.md) returns vulnerabilities and secrets together. Set `finding_kind` to get only one kind.
* [List secret scanner findings](https://docs.coderabbit.ai/api/reference/list-security-secret-findings.md) returns secrets only, with filters for confidence and verification status.
* [List vulnerable dependencies](https://docs.coderabbit.ai/api/reference/list-security-dependencies.md) lists dependencies with known advisories.
* [Read a code security finding](https://docs.coderabbit.ai/api/reference/get-security-finding.md), [Read a secret finding](https://docs.coderabbit.ai/api/reference/get-security-secret-finding.md), and [Read a dependency and its advisories](https://docs.coderabbit.ai/api/reference/get-security-dependency.md) return one item each.

### Export a software bill of materials

[List software bill of materials components](https://docs.coderabbit.ai/api/reference/list-security-sbom.md) pages through components. [Export a software bill of materials](https://docs.coderabbit.ai/api/reference/export-security-sbom.md) 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](https://docs.coderabbit.ai/api/reference/get-security-scan-quote.md). 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](https://docs.coderabbit.ai/api/reference/start-security-scans.md) 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](https://docs.coderabbit.ai/api/reference/list-security-scans.md) or [Read a security scan](https://docs.coderabbit.ai/api/reference/get-security-scan.md).

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](https://docs.coderabbit.ai/security.md#deep-scan-estimates-and-billing).

### Fix, dismiss, or reopen a finding

* [Request an AI fix for a security finding](https://docs.coderabbit.ai/api/reference/fix-security-finding.md) with the finding's kind in `finding_kind`. A `202` response means CodeRabbit accepted the request, not that the fix is done. To follow the fix and find the resulting task or pull request, read the finding with the reader for its kind: [Read a code security finding](https://docs.coderabbit.ai/api/reference/get-security-finding.md) for a vulnerability, [Read a secret finding](https://docs.coderabbit.ai/api/reference/get-security-secret-finding.md) for a secret, or [Read a dependency and its advisories](https://docs.coderabbit.ai/api/reference/get-security-dependency.md) for a dependency. If you aren't sure whether a fix request went through, read the finding before you send it again.
* [Dismiss a security finding](https://docs.coderabbit.ai/api/reference/dismiss-security-finding.md) with the same `finding_kind` values.
* [Reopen a code security finding](https://docs.coderabbit.ai/api/reference/reopen-security-finding.md) returns a code finding to the open state. It doesn't apply to secrets or dependencies.

For what each action does in the product, see [Triage and remediate findings](https://docs.coderabbit.ai/security.md#triage-and-remediate-findings).

### Read runtime validation results

1. Call [Read runtime validation availability for a finding](https://docs.coderabbit.ai/api/reference/get-security-runtime-validation-capability.md). 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](https://docs.coderabbit.ai/api/reference/list-security-runtime-validations.md).
3. Read an attempt with [Read a runtime validation result](https://docs.coderabbit.ai/api/reference/get-security-runtime-validation.md).

For how CodeRabbit verifies findings at runtime, see [Runtime verification](https://docs.coderabbit.ai/security/runtime-verification.md).

## Handle errors

| Response | What to do |
| - | - |
| `403 KEY_TYPE_FORBIDDEN` | Use a key type the export accepts; see [Which keys each operation accepts](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts). |
| `403` when reading findings | Give the key owner Security read access for Deep Scan findings or the `bug_scan:read` permission for Bug Scan findings, and check that the repository is in the key's scope. |
| `410` | Replace the key marked **Legacy** with a new API key; those keys can't read findings. |
| `413` | Narrow the request with `repo_id`, `scan_id`, or `severity`. |

For response formats and other codes, see [Errors](https://docs.coderabbit.ai/api/conventions.md#errors) and [Rate limits](https://docs.coderabbit.ai/api/conventions.md#rate-limits).

## What's next

> [card] [CodeRabbit Security](https://docs.coderabbit.ai/security.md)
>
> Learn how Deep Scan works, what it reports, and how to triage findings in the app.

> [card] [Runtime verification](https://docs.coderabbit.ai/security/runtime-verification.md)
>
> Reproduce Deep Scan findings in a test environment before you fix them.

> [card] [Authenticate requests](https://docs.coderabbit.ai/api/authentication.md)
>
> Pick the API key type each security operation accepts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.