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

# Security scan

> Use Upsun Dispatch Security scan to scan a GitHub, GitLab, or Bitbucket repository for vulnerable dependencies and review the latest results.

The **Security scan** workflow scans one GitHub, GitLab, or Bitbucket repository for vulnerable dependencies. Use Security scan when you want Upsun Dispatch to review a repository, show the latest findings, and keep one tracker issue current for follow-up work.

Security scan results appear in two places:

* A single issue in the repository's configured issue tracker. This issue is the main dashboard for the workflow and stays up to date as scans run.
* The repository's **Security** section in the [Upsun Dispatch console](https://developer.upsun.com/dispatch/docs/dashboard.md#view-repository-security), which shows the latest scan result for that repository.

For where Security scan fits with the other built-in workflows, see [Built-in workflows](https://developer.upsun.com/dispatch/docs/workflows/builtin).

## Before you scan

Connect the relevant VCS integration before running a scan:

* [Set up GitHub](https://developer.upsun.com/dispatch/docs/integrations/github.md) for GitHub repositories.
* [Set up GitLab](https://developer.upsun.com/dispatch/docs/integrations/gitlab.md) for GitLab repositories.
* [Set up Bitbucket](https://developer.upsun.com/dispatch/docs/integrations/bitbucket.md) for Bitbucket repositories.

Set the repository's issue tracker on **Repository > Workflows > Security scan**. The issue tracker is configured separately from the VCS integration, so a repository's tracker can be GitHub issues, GitLab issues, Linear, or Jira depending on your repository settings and connected [integrations](https://developer.upsun.com/dispatch/docs/integrations.md).

For Bitbucket repositories, choose Linear or Jira as the tracker in the repository Security scan settings. The **Run scan now** button is disabled until a tracker is selected.

For Jira, the service account needs these permissions:

* Browse projects
* Create issues
* Edit issues
* Transition issues

## Run an on-demand scan

Start Security scan from the repository workflow page in the [Upsun Dispatch console](https://developer.upsun.com/dispatch/docs/dashboard.md):

1. Open **Repositories**.
2. Select the GitHub, GitLab, or Bitbucket repository that you want to scan.
3. Open **Repository > Workflows > Security scan**.
4. Select **Run scan now**.

The scan runs for the selected repository, which is the repository whose page you opened. You do not need to re-enter a repository identifier in this console flow.

The repository's **Security** section shows the results of the latest scan. It does not start a new scan.

## Turn on daily scans for one repository

An organization owner or admin can enable a daily Security scan for each repository that needs scheduled scanning.

From the repository page:

1. Open **Repositories**.
2. Select the GitHub, GitLab, or Bitbucket repository that you want to scan daily.
3. Open **Repository > Workflows > Security scan**.
4. Turn on **Daily scan**.

**Daily scan** is a per-repository setting. Turning on **Daily scan** for one repository does not schedule scans for every connected repository in the organization. Scheduled scans cover only repositories where **Daily scan** is on.

To see which repositories have **Daily scan** on, open **Workflows > Security scan** from the top-level menu of the Upsun Dispatch console.

You can still [run an on-demand scan](https://developer.upsun.com/dispatch/docs/workflows/security-scan.md#run-an-on-demand-scan) with **Run scan now** when you need a current result for one repository.

## Track scan results in one issue

Security scan creates or updates one issue for each repository in the repository's configured tracker. This issue acts as a dashboard for vulnerable dependencies and is updated in place.

Each scan rewrites the same issue with the current vulnerable dependencies. Upsun Dispatch does not open a new issue on each scan. If you change the repository's tracker, the next scan opens a new issue in the newly configured tracker.

Use the issue when you want to plan or track remediation work with the rest of your repository work.

## Review the latest scan in Security

Open the repository's **Security** section in the [Upsun Dispatch console](https://developer.upsun.com/dispatch/docs/dashboard.md#view-repository-security) to review the latest scan result.

The **Security** section can show:

* Filters by severity and location.
* Search by package or advisory.
* Locations marked **Partly audited** or **Not audited** when Upsun Dispatch cannot fully audit a location. For Go, see [Private Go modules](#private-go-modules).
* Go advisories whose vulnerable functions your code does not call.
* Accepted advisories from repository scan configuration, including rules that have expired or that expire in the next 7 days.
* A link to the tracker issue that Security scan creates and maintains.

The **Security** section is a result view. To start a new scan, open **Repository > Workflows > Security scan** and select **Run scan now**.

## Accept an advisory

Some advisories come back on every scan after your team has already decided about them, for example an advisory with no fixed version in code that your repository never calls. Record that decision in an `osv-scanner.toml` file. The Security scan then lists the advisory as accepted, with its rule, and not as a finding.

`osv-scanner.toml` is the configuration file of osv-scanner. The scan applies it as osv-scanner does: an advisory that osv-scanner ignores is accepted. For every field of the file, see the [osv-scanner configuration docs](https://google.github.io/osv-scanner/configuration/).

### Where to put the file

Put `osv-scanner.toml` in the directory of each project, next to its lockfile (`package-lock.json`, `uv.lock`, `go.mod`, `composer.lock`, and so on). The file applies to that directory only:

* A file at the repository root covers only the project at the root.
* The scan does not look in parent directories or sub-directories. A project in `web/` needs its own `web/osv-scanner.toml`.
* Projects in the same directory share one file.
* A workspace member that the scan reads through its parent's lockfile uses the file in the parent's directory.
* The scan does not follow a symlinked `osv-scanner.toml`, and reports it as invalid.

### Accept one advisory

Add an `[[IgnoredVulns]]` entry for each advisory:

```toml app/osv-scanner.toml theme={null}
[[IgnoredVulns]]
id = "GO-2026-5932"
ignoreUntil = 2027-01-01
reason = "The code never calls x/crypto/openpgp, and no fixed version exists."
```

* `id` is the advisory ID. An advisory often has several IDs (CVE, GHSA, GO), and the scan accepts it only when osv-scanner drops every record of it. If the advisory stays a finding after the next scan, add an entry for each of its IDs.
* `ignoreUntil` is the end date of the rule. Write it with no quotes.
* `reason` records why your team accepts the advisory. The report shows it next to the advisory.

`ignoreUntil` and `reason` are optional, but the report adds a warning when one is missing. Without `ignoreUntil`, the rule never ends.

Give each advisory one entry. osv-scanner reads only the first entry for an ID, even when that entry has expired.

### Accept all advisories of a package

Add a `[[PackageOverrides]]` entry to accept the advisories of a whole package:

```toml app/osv-scanner.toml theme={null}
[[PackageOverrides]]
name = "lodash"
ecosystem = "npm"
vulnerability.ignore = true
effectiveUntil = 2027-01-01
reason = "Used by build scripts only. No user input reaches it."
```

* `vulnerability.ignore = true` accepts every advisory of the matching packages.
* `ignore = true` removes the matching packages from the scan.
* `effectiveUntil` is the end date, with the same rules as `ignoreUntil`.

An advisory that a package rule accepts shows "Excluded by a package rule in `osv-scanner.toml`.", with no reason and no end date. A package rule with no `name` matches every package that its other fields allow. With no other field, it accepts every advisory in that directory.

### Do not quote the date

> [!WARNING]
>
> `ignoreUntil = "2027-01-01"` makes the whole file invalid. With quotes, the value is a string, and osv-scanner rejects
> the file.

When a file is invalid, the scan accepts nothing from it. It keeps every finding, lists the file under **Invalid `osv-scanner.toml`** with osv-scanner's message, and brings back the advisories that the file accepted before. A TOML syntax error or an unknown key has the same effect. Fix the file, and the next scan applies it again.

### When a rule ends

The scan compares the end date with the time it runs:

* A date with no time, such as `2027-01-01`, ends at midnight at the start of that day, in the scan's local time.
* A date-time with no offset, such as `2027-01-01T12:00:00`, is also in the scan's local time.
* A date-time with an offset, such as `2027-01-01T00:00:00Z`, is an exact moment.

On its end date, the rule stops. The next scan reports the advisory as a finding again.

### What the scan shows

The tracker issue and the repository's **Security** section show the same information:

| Block | What it shows |
| - | - |
| **Accepted in `osv-scanner.toml`** | Each accepted advisory with its package, version, and rule: the rule's ID, its end date, and its reason. A warning follows a rule with no end date or no reason. |
| **Expired rules** | Each rule whose end date has passed, even when its advisory is no longer in the scan, so you can remove it. Its advisory is a finding again. |
| **Rules that end within 7 days** | Each rule whose end date is within 7 days after the scan. Review the decision, then extend the date or remove the rule. |
| **Invalid `osv-scanner.toml`** | Each file that the scan ignored, with the reason. |

Accepted advisories are in no count and do not send a console notification. When a scan has no finding but has accepted advisories, the headline gives their number. An advisory that comes back after its rule ends or after its file becomes invalid counts as a new finding, and sends a console notification when it is critical or high.

When a tracker issue is too long for the tracker, the scan removes the accepted advisories first, then the rules that end soon, then the expired rules. A notice says what is missing and links to the full report in the **Security** section.

## Private Go modules

A Go repository can require a module that your organization keeps private. To scan it, Go must fetch that module. List each private module and the connected repository that holds it, and Upsun Dispatch fetches the module during the scan.

The Security scan and [Issue to code](https://developer.upsun.com/dispatch/docs/workflows/issue-to-code.md) use the same list, so the agent can also build and test code that requires a private module.

### Add a private Go module

The module must live in a repository that your organization already connected to Upsun Dispatch. Only an organization owner can change the list. Other members can view it.

1. Open **Settings > Private Go modules**.
2. Select **Add module**.
3. Enter the **Module prefix**, the start of the module path, like `go.example.com/auth/authlib`.
4. Choose the **Repository** that holds the module.
5. Enter the **Import host (optional)** when the module path does not start with the repository's git host. See [Import host](#import-host).
6. Select **Add module** to save the module.

A list holds up to 20 modules.

### Use a different list for one repository

By default, every repository uses the organization list. To give one repository its own list:

1. Open **Repositories** and select the repository.
2. Open **Repository > Private Go modules**.
3. Select **Customize for this repository**.

The repository list replaces the organization list for that repository. The two lists do not merge. An empty repository list gives that repository no private module. To go back, select **Use organization list**. This deletes the repository list.

### How the module is fetched

Each listed repository gets its own read-only credential from the connection that holds it. The credential never enters the scan environment, and it can read only that repository.

A `go.mod` or a `go-import` page can point to the module with an `https://`, `ssh://git@` or `git@host:path` URL. Upsun Dispatch fetches all of them over HTTPS.

### Import host

Go first asks the host at the start of the module path where the code lives. When that host is not the repository's git host, enter it as the import host. For example, `go.example.com/auth/authlib` can live on `gitlab.example.com`.

The import host must serve its `go-import` page with no sign-in. Upsun Dispatch sends no credential to it.

### Limits

* The git host and the import host must answer on port 443, at a public address. You can save a repository on a self-managed GitLab that uses another port, but each run skips it.
* A run skips a module, and shows a warning that starts with "Skipped private Go module" on the run detail, when its repository is no longer connected, when its git host uses a port other than 443, when its connection is not active, or when its credential is missing, refused, expired, or revoked.

### When the scan cannot fetch a module

When Go cannot fetch a module, the location shows **Partly audited** in the tracker issue and in **Security**. The versions then come from `go.mod` only, with no dependency tree, so findings can be missing or wrong. The tracker issue names each module that Go could not fetch.

When the `go.mod` declares a Go version older than 1.17, the location shows **Not audited** instead, because that `go.mod` does not list the modules that the dependencies require.

### Private packages in other languages

For other languages, the scan reads the lockfile and does not install dependencies. A private Composer, npm, or Python package does not stop the scan, and its dependencies are scanned. The scan cannot report a vulnerability in the private package itself, because public advisory databases do not list it.

## If a scan fails

A Security scan can fail if the repository is empty, if Upsun Dispatch cannot read the repository, or if the scan cannot complete. Open the run detail in the [Upsun Dispatch console](https://developer.upsun.com/dispatch/docs/dashboard.md#open-run-details) to see the reported error and where the scan stopped.


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