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

> ## Agent Instructions
> IronBee (ironbee.ai) is an AI QA engineer: it verifies code changes against the running app and keeps the evidence. It is not related to the IronBee open-source web application firewall.
> The console is at https://console.ironbee.ai.
> Install the CLI with `npm install -g @ironbee-ai/cli`, sign in with `ironbee login`, and set up a project with `ironbee install`.
> In GitHub workflows, use the action as `ironbee-ai/ironbee-action@v1` and pass the `IRONBEE_API_KEY` secret as the `ironbee_api_key` input.
> In GitLab pipelines, include the component `gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1`; it reads the `IRONBEE_API_KEY` CI/CD variable by default.
> In Bitbucket Pipelines, run the pipe `docker://ghcr.io/ironbee-ai/ironbee-bitbucket:v1` and pass `IRONBEE_API_KEY: $IRONBEE_API_KEY` and `BITBUCKET_OAUTH_TOKEN: $BITBUCKET_OAUTH_TOKEN` under its `variables:`.
> Console scenarios (https://docs.ironbee.ai/console/scenarios) and CLI saved scenarios (https://docs.ironbee.ai/cli/guides/scenarios) are separate features.
> Code security (https://docs.ironbee.ai/code-security/overview) scans a repository's default branch on a schedule. It is off until an owner or admin turns it on for a repository, and only owners and admins see it.
> The self-hosted runner (https://docs.ironbee.ai/code-review/self-hosted-runner/overview) runs IronBee code review in your own GitHub Actions, GitLab CI/CD or Bitbucket Pipelines, with your own model provider; set it up with `ironbee runner setup`.
> For plans and prices, link to https://ironbee.ai/pricing; the website is the source of truth for them.

# Code security of your repositories

> IronBee scans the default branch of your GitHub, GitLab and Bitbucket repositories for security problems on a schedule, and can run the code to prove them.

Code security scans the default branch of a repository for security problems, on a schedule you choose. Each problem a scan finds is kept as a record: where it is in the code, the path to it from an entry point, how it could be used and how to fix it. With **Execution** on, a scan also installs the repository's dependencies and runs its code in a sandbox, and a finding it reproduces there is confirmed and gets a severity.

* **In the console:** each project's **Code security** tab shows the scans, the records and the runs, and the settings pages choose how a scan runs. See [Code security scans of a repository](https://docs.ironbee.ai/console/code-security.md).
* **Through the API:** read the records and runs, set your team's decisions, start a scan and change the settings. See [Code security API](https://docs.ironbee.ai/code-security/api.md).

Code security is off until an owner or an admin turns it on for a repository. A scan uses [credits](#credits), and only owners and admins see code security.

***

## What it is, and what it isn't

Code security and [code review](https://docs.ironbee.ai/code-review/overview.md) read the same repositories through the same connection, but they do different jobs:

| | Code security | Code review |
| - | - | - |
| **What it reads** | The default branch, as it stands | Each pull request or merge request, before it merges |
| **When** | On a schedule, or when an owner or admin starts a scan | When a pull request opens or gets a push, or when someone asks |
| **Where the results go** | The console and the API only | The pull request, and the console |

Code security posts nothing on a pull request or merge request: no comment, no check, no pipeline status, no build status. It doesn't start from a push and doesn't scan other branches. It never changes the repository: a record's fix is shown for you to apply. The code it runs stays in its sandbox, so it never reaches your deployments or any other live service. To test a running app, use [verification](https://docs.ironbee.ai/console/verifications.md).

***

## Where it runs

Code security scans repositories on every Git host IronBee connects to:

| Host | How the repository is connected |
| - | - |
| GitHub: github.com, including organizations of a GitHub Enterprise Cloud enterprise | The [IronBee GitHub App](https://docs.ironbee.ai/integrations/github.md) |
| GitHub: a GHE.com tenant, or a GitHub Enterprise Server of your own | A [registered tenant or server](https://docs.ironbee.ai/integrations/github-enterprise.md) |
| GitLab: gitlab.com | A [connected group](https://docs.ironbee.ai/integrations/gitlab.md) |
| GitLab: a GitLab Self-Managed server, or a GitLab Dedicated tenant | A [registered instance](https://docs.ironbee.ai/integrations/gitlab-self-managed.md) |
| Bitbucket Cloud (bitbucket.org) | A [connected workspace](https://docs.ironbee.ai/integrations/bitbucket.md) |

It works the same on each host. A scan clones the repository through the connection IronBee already has, reads only the code, and writes nothing to the host. On a registered tenant, server or instance, the clone comes from IronBee's one address, like every other call IronBee makes there.

Scans run on IronBee's infrastructure:

* **Each scan runs on a machine of its own.**
* **The code it runs has no network access.** With **Execution** on, only the dependency install reaches the public package registries.
* **The scan is given no secrets:** none of the project's secrets, variables or environments, and the code it runs can't reach the token used for the clone or any IronBee credential.

See [Where it runs](https://docs.ironbee.ai/code-security/how-a-scan-works.md#where-it-runs) and [What a scan is given](https://docs.ironbee.ai/code-security/how-a-scan-works.md#what-a-scan-is-given).

The [self-hosted runner](https://docs.ironbee.ai/code-review/self-hosted-runner/overview.md) reviews pull requests in your own CI and doesn't run code security, so a host that IronBee can't reach from the internet has no code security.

Vercel, Netlify and CLI projects have no code security. Connect the project's repository through one of the hosts above to scan it.

***

## Turn it on

Code security is turned on one repository at a time. An owner or an admin does one of these:

* clicks **Turn on** on the project's **Code security** tab. See [Turn it on](https://docs.ironbee.ai/console/code-security.md#turn-it-on).
* turns on **Scan this repository** in the project's **Settings > Code security**. See [Repository settings](https://docs.ironbee.ai/console/code-security-settings.md#repository-settings).
* sets `enabled` to `true` through the API. See [Change a repository's settings](https://docs.ironbee.ai/code-security/api.md#change-a-repositorys-settings).

There's no account setting that turns it on for every repository. The account's settings hold the defaults each repository follows: the profile, execution and how often a scan comes.

A repository that has never been scanned is due at once, so its first scan, a full scan, comes within minutes of turning code security on, once no other code security scan of your account is waiting or running and the team has credits left. See [When a scan runs](https://docs.ironbee.ai/code-security/how-a-scan-works.md#when-a-scan-runs).

Once code security is off for a repository, no scan of it starts. Its records are kept, and its runs within your plan's retention. They aren't shown, and come back when you turn it on again.

***

## What a scan does

A scan reads the default branch and writes a record for each problem it finds. Three settings shape it, at the account and for each repository:

* **Profile:** how far a scan follows what it finds. **Auto** (the default) picks **Standard** for smaller repositories and **Quick** for larger ones, and never **Deep**. See [Profile](https://docs.ironbee.ai/console/code-security-settings.md#profile).
* **Execution:** whether a scan may run the repository's code to prove what it finds. Off by default. See [Running your code](https://docs.ironbee.ai/code-security/how-a-scan-works.md#running-your-code).
* **Scheduled scan:** how often a scan comes: **Daily**, **Weekly** (the default), **Every two weeks** or **Monthly**.

Each repository also has **Paths to ignore**: files left out of every scan and of the repository's size.

The first scan of a repository is a **Full** scan of the whole branch. After that, a scheduled scan is **Incremental**: it reads what changed since the last scan. A scan that couldn't read everything in one run puts the rest off to a **Follow-up** run, which is free. A period in which the branch didn't move scans nothing. See [How a scan works](https://docs.ironbee.ai/code-security/how-a-scan-works.md).

***

## Records, verdicts and decisions

A **record** is one problem a scan found. A later scan that sees the same problem again updates its record instead of adding another. Every record has a verdict:

* **Confirmed:** the scan reproduced the problem by running the code. Only a confirmed finding has a severity: **Critical**, **High**, **Medium**, **Low** or **Informational**.
* **Lead to validate:** the scan couldn't prove it yet. The record says what blocks a verdict and how to validate it yourself. With **Execution** off, everything a scan finds stays a lead.
* **Rejected:** a scan found that it doesn't hold.

Your team's **decision** says what you do with a record: **Open**, **Accepted**, **Fixed elsewhere** or **Not an issue**. A decision holds while the record's verdict and severity stay the same. When you fix a problem in the code, leave its record **Open**: a later scan that reads the changed code checks the record again, and can reject it once the problem is gone. A scan changes only the records it reports, so until one does, the record stays as it was.

To read a record, set a decision and see every scan that ran, see [Security records and runs](https://docs.ironbee.ai/console/code-security-records.md).

***

## Credits

Code security uses the team's credits, as code review and verification do. A scan is priced when it starts, before it reads anything, by the repository's size outside the paths to ignore, the profile and whether **Execution** is on. It's charged when it finishes.

What uses credits:

* a full scan: the first scan, one you ask for with **Run full scan** or through the API, and the next scan after **Paths to ignore** changed
* a scheduled or API scan of a period in which the default branch moved
* **Execution**, which makes a scan cost more

What's free:

* a follow-up run, which finishes a scan already paid for
* a period in which the default branch didn't move, or changed only in ignored paths
* a scan that fails, or that's refused before it reads the code, such as when the credits left don't cover it
* reading records and runs, setting decisions and changing settings, in the console or through the API

When the team has no credits left, no scheduled scan starts and **Run full scan** is unavailable until the credits reset or the team gets more. A repository larger than the rate card covers is scanned by contract with IronBee.

The rates are under **What a job costs** on [Credit usage](https://docs.ironbee.ai/console/usage.md#what-a-job-costs). Each plan's credits are on [Pricing](https://docs.ironbee.ai/console/pricing.md).

***

## Who can see it

Only owners and admins see code security: the **Code security** tab, its records and runs, and its settings at both levels. Only they turn it on, start a scan, set a decision and change the settings. Members and billing admins don't see the tab or the settings pages. See [Roles and permissions](https://docs.ironbee.ai/console/roles.md).

Through the API, the account API key acts as an owner, and a personal OAuth token acts with its user's role, so it works for owners and admins only. See [Authentication](https://docs.ironbee.ai/code-security/api.md#authentication).

***

## What's next?

> [card] [How a scan works](https://docs.ironbee.ai/code-security/how-a-scan-works.md)
>
> What a scan reads, when it runs, follow-up runs, and what running your code means.

> [card] [Code security API](https://docs.ironbee.ai/code-security/api.md)
>
> Read records and runs, set decisions, start a scan and change the settings.

> [card] [Code security in the console](https://docs.ironbee.ai/console/code-security.md)
>
> The project's tab: where a scan stands, the scan summary and Run full scan.

> [card] [Security records and runs](https://docs.ironbee.ai/console/code-security-records.md)
>
> Read a record, decide on it, and see every scan that ran.

> [card] [Code security settings](https://docs.ironbee.ai/console/code-security-settings.md)
>
> Choose the profile, the schedule, execution and the paths a scan leaves out.

> [card] [Code review](https://docs.ironbee.ai/code-review/overview.md)
>
> Reviews of every pull request and merge request, before they merge.


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