Bring your own scanner

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

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.

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 where it doesn’t.

Custom importers need a paid license. See 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:

• Job type: Scanner.
• Image: your scanner’s image. For a private registry, connect it as a container registry 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:

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

Then add the job to a sequence, after Code Downloader for a code scanner, and 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 rules for the scanner, so that its findings merge with the same findings of other scanners.
• Decide whether the 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.