Sequences and jobs

Choose which scanners an audit runs, in which order, and how each scanner runs.

Updated

A job is one step that Auditor runs in its own container. There are two job types:

  • a Scanner job runs a scanner and sends its report to Portal;
  • a Technical job only prepares the work, for example Code Downloader clones the repository for the scanners after it.

A sequence is the list of jobs that an audit runs on an asset, one after another. Portal comes with a sequence named Default for repositories: Code Downloader, Trufflehog3 Scan, Gitleaks Scan, Semgrep and Trivy Code Dependencies.

Make one sequence per kind of asset you scan. A sequence for repositories starts with Code Downloader; one for Docker images runs image scanners such as Trivy Image Dependencies; one for domains runs web scanners such as Nuclei Scan. See Scanners for which scanner fits which asset.

Create a sequence

  1. Open the settings, then Auditor and Sequences.
  2. Click Create Sequence, enter a Title and click Create.
  3. Add the jobs in the order they run: click the add button under the last job, choose the Job type and the Auditor job, and click Create.

Each job’s menu can Change it to another job, Move up or Move down, open its Job settings, or Remove from sequence it.

Turn on Set as Default Sequence for the sequence that Run Audit suggests. The default sequence also scans every asset that has no sequence of its own.

Choose the sequence of an asset

Set Job sequence on an asset to scan it with that sequence when an audit doesn’t choose one. Set it on assets that differ from the default sequence: Docker images, domains, hosts, cloud accounts, and repositories in languages that need other scanners. See Assets.

Shared artifacts

All jobs of a sequence share one folder, /code, and start in it. Code Downloader clones the repository there, so the scanners after it find the code.

Each job writes its own files, such as its report, into /data. With shared artifacts on, those files are also copied into /code for the jobs after it, for example when one scanner reads another one’s results. Click the shared artifacts icon of a job in the sequence to turn it on or off.

Two jobs with one importer

If two jobs in a sequence send their reports as the same scanner, the sequence shows an Importer Warning. With the Auto Closer turned on for that scanner, the findings of the first report are missing from the second one, and the Auto Closer acts on them as if they were fixed. Keep one such job per sequence, or turn the Auto Closer off for that scanner.

Job settings

Open a job from the sequence, or from its scanner’s page under Scanners. The jobs that come with Auditor have Vendor Settings, which are updated with each release. To change a job, turn off Use vendor settings and edit the User Settings:

SettingWhat it does
Job typeScanner or Technical.
Copy artifacts to next jobs from /data directoryCopies the files that the job writes into /data to /code, so the jobs after it can read them. See Shared artifacts.
Allow failureWhen off, a failed job stops the whole pipeline.
Job timeout (minutes)How long the job may run.
ImageThe Docker image the job runs in. Its registry credentials come from the Auditor settings or from a container registry.
Overwrite Container EntrypointClears the image’s entrypoint, so the container runs only the Run command. See below.
Run commandWhat the job runs. A scanner job writes its report into /data.
Environment variablesValues for the command. Scanner jobs need two of them: REPORT_FILE_NAME, the report file in /data, and SCAN_TYPE, the scanner name in Portal that reads the report. Mark secrets as Masked.

Auditor runs the Run command with sh -c. When the image has an entrypoint, Docker passes that to the entrypoint instead of running it, so the choice depends on the image:

  • Turn it on when the entrypoint is the scanner itself, as in most official scanner images, for example aquasec/trivy or zricethezav/gitleaks. Without it, the scanner receives sh -c "…" as its arguments and fails. Write the full scanner call in the run command, for example trivy fs . --format json --output /data/$REPORT_FILE_NAME.
  • Leave it off when the image has no entrypoint, or when its entrypoint prepares the container and then runs the command it’s given, for example a script that ends with exec "$@". Turning it on would skip that preparation.

Auditor fills in the variable of the asset being scanned: REPOSITORY, DOCKER_IMAGE, DOMAIN, HOST or CLOUD_ACCOUNT. A run command uses it to know what to scan.

To add a scanner that Auditor doesn’t have, see Bring your own scanner.