Import scan results
Send scanner reports over the API, upload a report file, or add a finding by hand.
Audits are the main way to get findings: Auditor runs the scanners and sends the reports itself. Use the ways below when a report comes from somewhere else.
In all of them, the scanner must be one that Portal can read: see Scanners. For another scanner, set up its importer first: Bring your own scanner.
Send reports over the API
Use the API when your scanners run in your own CI pipelines. We recommend moving them to Auditor over time: there the scanners are set up once and cover every asset. In CI, they have to be added to the pipeline of each repository, which is hard to keep up with many repositories, and a full set of scanners often makes a pipeline too slow.
You need:
- A token. Open your profile: the Auth API Token is shown there. Requests act as you, so use the token of a user whose role can edit findings in the products you import into. Store it as a secret variable of your CI.
- The address. The profile shows the External Portal URL to send API requests to.
Send each report to /api/v1/scan/import/:
bashcurl -X POST "https://portal.example.com/api/v1/scan/import/" \ -H "Authorization: Token $PORTAL_TOKEN" \ -F "file=@gitleaks.json" \ -F "scanner_name=Gitleaks Scan" \ -F "repository=git@gitlab.com:whitespots-public/appsec-portal.git" \ -F "branch=main"
| Field | Value |
|---|---|
file | The report file. Or send its content as text in report. |
scanner_name | The scanner name exactly as in Scanners. |
repository, docker_image, domain, host or cloud_account | The asset that was scanned. Send one, in the same format as the asset in Portal: for a repository, its SSH clone URL. |
branch | For a repository: the branch that was scanned. |
docker_image_tag | For a Docker image: the tag that was scanned. |
product_name and product_type | Optional. The product to import into. Both are needed; the product and the product type are created if they don’t exist. |
custom_field | Optional. Any text up to 300 characters to keep with the findings. |
Always send the asset. The findings are tied to it, and only then does the import appear in Audits with its statistics.
Without product_name, Portal finds the product by the asset: the product that
already has it, or Unsorted for a new asset. So you don’t need to keep product names in your
pipelines: move the asset to its product once, and later reports follow it. When Enable Unique
Assets is on in Workflow Settings, product_name and product_type are ignored and the
asset always decides.
The response is 202 Accepted: the report is queued and imported in the background. A wrong
scanner_name is refused at once with 400. To see what came in, open the audit in Audits.
All API endpoints are described in Swagger, at /api/v1/docs/ of your installation.
Upload a report
Upload a report when you got a file from somewhere: a one-off scan, a vendor, a tool outside your pipelines. For a scanner you will run again, add it to Auditor instead.
- Click Import Findings: on the Products list, on a product’s or an asset’s page, or above the findings.
- Choose the Report file and the Scanner.
- Choose the Product. Started from a product or an asset, it’s set already.
- Choose the asset that was scanned, and its Branch or Image tag if it has one. You can type a new asset: it’s added to the product.
- Click Submit.
As with the API, choose the asset: without it, the import doesn’t appear in Audits.
Add a finding by hand
For a vulnerability that no scanner reports, for example one found in a manual review or a penetration test, click Create Finding above the findings or on a product’s page. Fill in at least the product, the title and the severity. You can also set the asset, the file and line, the CWE, the CVSS vector, the description and the triage status.