---
title: "Bring your own scanner"
description: "Add a scanner that AppSec Portal doesn't support yet: describe how to read its reports, then run it from Auditor."
url: https://whitespots.io/docs/appsec-portal/find-vulnerabilities/bring-your-own-scanner
slug: appsec-portal/find-vulnerabilities/bring-your-own-scanner
publish_date: 2026-10-30T19:42:15.000Z
last_modified: 2026-10-30T19:42:15.000Z
---

# Bring your own scanner

Any scanner that writes a JSON report can be added. You need:

- an example report of the scanner, with a few findings in it;
- a Docker image that runs the scanner, to run it from Auditor.

Portal imports a report only when it knows how to read it. For a scanner that
isn't in the [supported list](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/scanners), set up a custom importer first, whether its reports
come from Auditor, the API or an upload.

## Create the scanner

1. Open the settings, then **Scanners**, and click **Create Scanner**.
2. Enter the **Name**. Reports and Auditor jobs refer to the scanner by this name.
3. Choose the **Scanner Type**: filters and triage rules can match findings by it.
4. Click **Create**, then click the scanner's row to open it.

<video src="https://whitespots.io/api/image/d03a4960f3bf7cd5723580914ae856c3.mp4" width="1440" height="900" class="shot-light" autoplay muted loop playsinline controls></video>
<video src="https://whitespots.io/api/image/bf8399d3118b21c7e490215e3ee08d7e.mp4" width="1440" height="900" class="shot-dark" autoplay muted loop playsinline controls></video>

To change how a supported scanner's reports are read, click **Copy Scanner** on its page instead.
The copy starts with the same importer, which you can then edit.

## Set up the importer

On the scanner's page, click **Set up custom parse logic** under **Report parse logic
configuration**. The importer is set up in five steps:

1. **Report file**: upload the example report. The next step opens by itself. If the report
   follows the SARIF format, Portal offers **Apply Default Structure**, which
   fills in the next steps.
2. **Path to the list of findings**: click through the report to the list that holds one entry
   per finding: click **KEY** next to each key on the way, then **USE AS LIST** on the list.
3. **Path to rules description**: only for reports that describe their rules apart from the
   findings. Point to the list of rules and to the field that links a finding to its rule. Click
   **Skip** for simple reports.
4. **Finding fields**: choose where each field of a finding comes from: title, severity, file,
   line and so on. In a text field, click **Report Field**, then the field's **KEY** in the
   report. Write the **Description template** from the report's fields; Markdown is
   allowed. Map the scanner's severities to Portal's, and give a **CWE list** if
   the report has none.
5. **Preview**: click **Fetch Preview** to parse the example report and check the findings. Fix
   any errors it shows, then save.

<video src="https://whitespots.io/api/image/f8dbf693f243385b0470ff42481d5aa1.mp4" width="1440" height="900" class="shot-light" autoplay muted loop playsinline controls></video>
<video src="https://whitespots.io/api/image/38c35abb8eec215debf74cc1d372703f.mp4" width="1440" height="900" class="shot-dark" autoplay muted loop playsinline controls></video>

Turn on **Enable asset search** when each finding in the report names its own asset, for example a
report that covers many repositories. Portal then puts each finding into the
product that has that asset.

Not every scanner reports a CWE, a recommendation or a proper severity. That's normal: fill them in
with the importer where the report has them, and with
[triage rules](https://whitespots.io/docs/appsec-portal/triage-findings/automate-triage) where it doesn't.

Custom importers need a paid license. See [License](https://whitespots.io/docs/appsec-portal/administration/license).

## Add the Auditor job

The scanner's page lists, under **Auditor jobs**, the jobs whose `SCAN_TYPE` variable is
the scanner's name: Auditor sends their reports to this scanner. A new scanner has none
yet, so click **Create Job**. The job starts with the scanner's name and its `SCAN_TYPE` already
filled in. Set up the rest as described in [Job settings](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/audits/sequences#job-settings):

- **Job type**: **Scanner**.
- **Image**: your scanner's image. For a private registry, connect it as a
  [container registry](https://whitespots.io/docs/appsec-portal/integrations/container-registries) or enter its credentials in the
  Auditor settings.
- **Run command**: run the scanner on the asset and write the report into `/data`. Code scanners
  find the code in the current folder when the job runs after Code Downloader. The asset comes in
  its variable, such as `$REPOSITORY` or `$DOMAIN`.
- **Environment variables**: `REPORT_FILE_NAME`, the report's file name. Keep `SCAN_TYPE` as
  it is: renaming the scanner or the variable takes the job off the scanner's page. Mark the asset variable, for example `DOMAIN`, as
  **Required to run Job**: run on an asset of another type, the job then stops with "Missing
  required variables" instead of scanning nothing.

For example, a job for a code scanner:

```bash
my-scanner scan . --format json --output /data/$REPORT_FILE_NAME
```

Then add the job to a [sequence](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/audits/sequences), after Code Downloader for a code scanner,
and [run an audit](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/audits/run-an-audit) on one asset to check that the findings arrive. If they
don't, the job's logs in the audit's pipeline show whether the report was found and sent.

## After the first findings

- Add [Deduplicator](https://whitespots.io/docs/appsec-portal/triage-findings/automate-triage/deduplicator) rules for the scanner, so
  that its findings merge with the same findings of other scanners.
- Decide whether the [Auto Closer](https://whitespots.io/docs/appsec-portal/triage-findings/automate-triage/auto-closer) should act on
  the scanner's findings that disappear from its reports.

To move your scanners to another installation, use **Import Scanners** on the **Scanners** page.

---

## Navigation

- Location: [Docs](https://whitespots.io/docs) > [Application Security Portal](https://whitespots.io/docs/appsec-portal) > [Find vulnerabilities](https://whitespots.io/docs/appsec-portal/find-vulnerabilities)
- Previous: [Scanners](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/scanners)
- Next: [Import scan results](https://whitespots.io/docs/appsec-portal/find-vulnerabilities/import-scan-results)