First steps

#1. Connect Auditor

Auditor runs the scanners. It clones your repositories, pulls your images, runs a sequence of scan jobs and sends the results back. Without it, Portal can only store results that you upload yourself.

Install Auditor on its own server, then connect it: enter its URL and access token in the Auditor settings. The Connection status under them shows at once whether Auditor is reachable and the token is accepted. To scan private repositories, also add the SSH key that Auditor clones them with.

#2. Connect version control and sort repositories into products

Connect GitLab, GitHub, Bitbucket or Azure DevOps with an access token, turn on Enable scan on commit push and add the webhook to your version control. See Version control.

From then on, repositories come in by themselves: the first push to a repository adds it to the default product, Unsorted, which Portal creates on install, and scans it. To bring in repositories that nobody pushes to, import them by hand: open Assets and click Import Repositories.

Split repositories into products that match your applications or teams. Risk, SLA and reports are counted per product, and a product full of unrelated repositories tells you little. Choose a product for each repository when you import them by hand, or select repositories in the asset list and move them all to a product at once. See Products and Move an asset to another product.

#3. Load the triage rules

Rules decide what happens to findings when they arrive:

• the Auto Validator verifies or rejects findings;
• the Deduplicator merges the same finding reported by different scanners;
• CVSS rules set the CVSS vector of findings.

There are ready-made rule sets for all three. On each of the three pages, click Import Rules and upload the rule set file. Then add your own rules.

Load the rules before the first scan. The rules act on findings as they are imported, and a first scan of all your repositories brings in many findings at once: without rules, you triage all of them by hand. The rules also run on a schedule, so a rule you add later applies to the findings that are already there: set how often on each of the three pages.

#4. Choose what to scan with

A sequence is the list of scan jobs that an audit runs. Portal comes with a Default sequence for repositories: it downloads the code and runs secret, code and dependency scanners.

Check that the default sequence fits your languages and frameworks, and create sequences for the other asset types you scan: Docker images, domains, hosts and cloud accounts. Set a sequence on an asset, or choose one when you run or schedule an audit. See Sequences and Scanners.

#5. Start scanning

1. Run a first audit by hand on a few repositories and check that findings arrive. See Run an audit.
2. Scan on a schedule. Open Schedule under Auditor, choose which products or assets to scan, a sequence and a schedule. Assets added to those products later are scanned too. See Schedule audits.
3. Scan every push. With the webhook from step 2, each push scans the pushed branch.
4. Check pull requests. Assign a quality gate to the version control integration: it comments the findings on merge requests and pull requests and sets the commit status, so developers see them before merging.
5. Scan images. Connect your container registry: Portal scans each new image tag, on a schedule or when the registry sends a webhook. New images go to Unsorted. See Container registries.
6. Add the rest of what you run: domains, hosts and cloud accounts. Add them to their products by hand. A domain sequence with Subfinder adds the subdomains it finds as new domain assets in the same product. See Assets.

If you already run scanners in your own CI pipelines, they can send their reports too (see Import scan results), but we recommend Auditor audits. They are set up once and cover every asset, while scanners in CI have to be added to the pipeline of each repository, and a full set of scanners often makes a pipeline too slow.

Look into Unsorted from time to time and move new assets to their products.

#6. Bring in the team

When findings arrive and the rules triage them, invite the people who fix them:

• Sign-in. Connect SSO so people sign in with their company accounts, and give them roles. See SSO and Users and roles.
• Task tracker. Connect Jira or YouTrack to create tasks for verified findings in each product team’s project. See Task trackers.
• Notifications about new findings and missed deadlines. See Notifications.

#7. Watch the metrics

With regular scans and triage, the metrics start to mean something: how much risk each product carries, whether it goes down, and which findings miss their deadlines. Set the business criticality of each product first, then see Track risk.

Auditor, version control, container registries, the Auto Validator, the Deduplicator, SSO and notifications need a paid license. See License for what each plan includes.