> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ox-code/scanning/ox-ide-integrations/background-scan.md).

# Background scan

## About background scan

Background scanning automatically scans code changes in your IDE without requiring you to start a scan manually. This capability helps identify security issues while you work, even if you forget to run a manual scan.

While your IDE is open, OX periodically scans changes in the Git repositories in your workspace. When security issues are detected, you can review them in the same OX interface used for manual scans.

Background scanning is supported in the following IDE integrations:

* [Visual Studio Code](https://docs.ox.security/ox-code/scanning/ox-ide-integrations/ox-ide-extension.md)
* [JetBrains IDEs](https://docs.ox.security/ox-code/scanning/ox-ide-integrations/ox-ide-plugin.md)

## Enabling background scanning

Background scanning is managed at the organization level by OX Security.

To enable or disable background scanning, contact OX Support.

Once enabled, background scanning runs automatically for all developers connected to the organization. Individual developers do not need to enable it or start scans manually.

## How background scanning works

Background scanning runs automatically while your IDE is open, based on the following behavior:

| Behavior        | Description                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scan interval   | Background scans run every 15 minutes by default. The interval can be increased but cannot be shorter than 15 minutes.                                |
| User activity   | Before starting a scan, OX waits until there has been no IDE activity for at least one minute, including typing, saving files, or switching branches. |
| Scan scope      | OX scans only local changes in Git repositories, using the same change-based scanning approach as manual scans.                                       |
| Unchanged files | Files that have not changed since the previous scan are not scanned again. Previous results remain available.                                         |
| Manual scans    | Manual scans are included when calculating the next background scan interval. Running a manual scan delays the next background scan.                  |
| Scan categories | Background scans use the scan categories configured in the IDE integration settings.                                                                  |
| Scan processing | OX packages local changes into an archive and sends them to the OX platform for analysis.                                                             |

## Viewing background scan results

Background scans run automatically without requiring user interaction. Scan progress and results appear in the IDE integration.

| Event                    | What you see                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Scan in progress         | An `OX: Background scan...` progress message.                                                                       |
| Security issues detected | A notification showing the number of issues found, with an option to open the results in the OX interface.          |
| Scan completed           | Results appear in the same OX views used for manual scans, including issue details and remediation recommendations. |
| Scan error               | Errors are recorded in the logs without interrupting your work.                                                     |

Background scans do not require user input or confirmation.

## When background scans are skipped

Background scanning may be skipped or delayed under the following conditions:

| Condition                    | Behavior                                                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Daily scan limit reached     | Background scanning stops until the next day (UTC), when scanning resumes automatically.                                                         |
| OX platform unavailable      | If the platform cannot be reached because of network connectivity or authentication issues, the scan is skipped and retried at a later interval. |
| Repository has no remote URL | Repositories without a configured remote URL are skipped. You can scan these repositories manually.                                              |
| No changes detected          | If no changes have occurred since the previous scan, OX does not start another scan.                                                             |
| Developer activity detected  | OX waits until the IDE has been idle for at least one minute before starting the scan.                                                           |

You can continue running manual scans at any time, regardless of whether background scanning is enabled.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/ox-code/scanning/ox-ide-integrations/background-scan.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
