CI scan options

The ostorlab ci-scan run command needs an API key, a scan profile and a scan title, followed by an asset sub-command. Every other option is optional.

This page lists each option, its default and its accepted values. For how a CI scan works, see Scan in your CI/CD pipeline.

Command syntax

Put --api-key before ci-scan. Put the scan options after run and before the asset sub-command. Put the asset arguments after the asset sub-command.

ostorlab --api-key "$OSTORLAB_API_KEY" ci-scan run \
  --scan-profile PROFILE \
  [OPTIONS] \
  ASSET_SUBCOMMAND [ASSET_ARGUMENTS]

The oxo command is an alias of ostorlab. Install it with pip install ostorlab.

A mobile scan:

ostorlab --api-key "$OSTORLAB_API_KEY" ci-scan run \
  --scan-profile full_scan \
  --title "Release build" \
  --break-on-risk-rating medium \
  --max-wait-minutes 45 \
  ios-ipa build/app.ipa

A web scan:

ostorlab --api-key "$OSTORLAB_API_KEY" ci-scan run \
  --scan-profile full_web_scan \
  --title "Staging web scan" \
  --break-on-risk-rating high \
  link --url https://staging.example.com --url https://api.staging.example.com

The command exits with code 2 when it rejects an option or cannot create the scan. It also exits with code 2 when the risk is above the threshold or the wait times out. Otherwise it exits with code 0.

Global option

Option	What it does	Default	Required	Accepted values
`--api-key`	The API key that authenticates the command. The CLI reads no environment variable for it, so pass the value yourself.	None	Yes. Without it the command exits with code 2.	An API key from the platform.

Scan options

These options apply to every asset type.

Option	What it does	Default	Required	Accepted values
`--scan-profile`	The scan profile to run.	None	Yes	`fast_scan`, `full_scan`, `full_web_scan`, or the aliases `fast`, `full`, `full_web`. Lowercase only. Any other value exits with code 2.
`--title`	The title of the scan in the platform.	None	Yes in practice. The CLI accepts the command without it, but the scan creation request declares the title as mandatory. The platform rejects the request, the CLI prints `Could not start the scan.` and exits with code 2. The CLI has by then already created any test credentials.	Text.
`--break-on-risk-rating`	Waits for the scan to finish, then fails if the scan risk rating is higher than this value.	None. Without it, the command does not wait. An empty value counts as not set.	No	A risk rating name, in any letter case. See Risk rating thresholds.
`--max-wait-minutes`	The longest time to wait for the scan. It applies only with `--break-on-risk-rating`. The command exits with code 2 when the time runs out.	`30`	No	A whole number of minutes.
`--log-flavor`	The output format for your CI tool.	`console`	No	`console`, `github`, `circleci`. Any other value exits with code 2.

The scan profile values map to these names in the platform:

Value	Alias	Platform name
`fast_scan`	`fast`	Fast Scan
`full_scan`	`full`	Full Scan
`full_web_scan`	`full_web`	Full Web Scan

The CLI creates the scan first and then checks the value of --break-on-risk-rating. An invalid value still leaves a scan in the platform and exits with code 2.

Each log flavor prints the scan ID in its own way:

Log flavor	Output for the scan ID
`console`	The line `Output: scan_id:<id>`.
`github`	The line `::set-output name=scan_id::<id>`. See the note below.
`circleci`	Sets the environment variable `SCAN_ID` inside the CLI process.

The github flavor still prints the set-output workflow command. GitHub deprecated that command in favor of the GITHUB_OUTPUT file, and in July 2023 it postponed the removal. See the GitHub notice. The CLI does not write to GITHUB_OUTPUT. Every flavor also logs the line Scan created with id <id>.

Options by asset type

The command accepts every option with every asset sub-command. It ignores, without a warning, the options that do not apply to the asset type.

Options	Mobile: `android-apk`, `android-aab`, `ios-ipa`	Web: `link`
Scan options, `--sbom`, test credentials, 2FA credentials, UI prompts	Used	Used
`--scope-urls-regexes`, `--source`, `--repository`, `--pr-number`, `--branch`	Used	Ignored
`--api-schema`, `--filtered-url-regexes`, `--proxy`, `--qps`	Ignored	Used

Asset sub-commands

Choose one asset sub-command at the end of the command.

Sub-command	What it scans	Argument	Required
`android-apk`	An Android APK package.	The path to the `.apk` file. It must exist.	Yes
`android-aab`	An Android AAB package.	The path to the `.aab` file. It must exist.	Yes
`ios-ipa`	An iOS IPA package.	The path to the `.ipa` file. It must exist.	Yes
`link`	A web application, by URL.	`--url <URL>`. Repeat the option for several URLs.	Yes, at least one `--url`

Mobile options

These options apply to android-apk, android-aab and ios-ipa.

Option	What it does	Default	Required	Accepted values
`--scope-urls-regexes`	URLs in scope, as regular expressions. Repeat the option for several values.	None	No	A regular expression.
`--source`	The CI source of the scan. The GitHub Action sets it to `github`.	None	No	Text.
`--repository`	The repository name. The CLI sends it only when `--source` is set.	None	No	Text.
`--pr-number`	The pull request number. The CLI sends it only when `--source` is set.	None	No	Text.
`--branch`	The branch name. The CLI sends it only when `--source` is set.	None	No	Text.

Web options

These options apply to link.

Option	What it does	Default	Required	Accepted values
`--api-schema`	An API schema file sent with the scan.	None	No	The path to an existing file.
`--filtered-url-regexes`	URLs to exclude from the scan, as regular expressions. Repeat the option for several values.	None	No	A regular expression.
`--proxy`	The proxy to use, if you set one.	None	No	Text, sent to the platform as is.
`--qps`	The maximum number of queries per second, if you set one.	None	No	A whole number. The CLI does not check the value.

Test credentials

Test credentials let the scan sign in to your app. Each option can be repeated. For the concepts, see Test credentials. For 2FA, see Two-Factor Authentication (2FA) for Automated Scans.

Option	What it does	Default	Required	Accepted values
`--test-credentials-login`	The login of a credential.	None	No	Text.
`--test-credentials-password`	The password of a credential.	None	Yes for each `--test-credentials-login`	Text.
`--test-credentials-role`	The optional role of a login credential.	None	No	Text.
`--test-credentials-url`	The optional URL of a login credential.	None	No	Text.
`--test-credentials-name`	The name of a custom credential field.	None	No	Text.
`--test-credentials-value`	The value of a custom credential field.	None	Yes for each `--test-credentials-name`	Text.
`--email-2fa-sender-email-address`	The sender address of the email that carries the 2FA code.	None	No	An email address.
`--email-2fa-email-address`	The mailbox that receives the 2FA code.	None	Yes for each sender address	An email address.
`--email-2fa-password`	The password of that mailbox.	None	Yes for each sender address	Text.
`--sms-2fa-sender`	The sender phone number of the SMS that carries the 2FA code.	None	No	Text.
`--totp-2fa-seed`	The shared secret (seed) for TOTP 2FA codes.	None	No	A Base32 seed.

How the CLI groups the values:

The command exits with code 2 if the number of --test-credentials-login options differs from the number of --test-credentials-password options.
The CLI matches --test-credentials-role and --test-credentials-url to logins by position. The first role belongs to the first login. To set a role on the second login, also set one on the first. The same rule applies to URLs.
The command exits with code 2 if the number of --test-credentials-name options differs from the number of --test-credentials-value options. The CLI combines all name and value pairs into one custom credential.
The three email 2FA options must appear the same number of times, or the command exits with code 2. Each set of three makes one credential.
Each --sms-2fa-sender and each --totp-2fa-seed makes one credential.

The CLI creates the credentials in the platform before it creates the scan. It prints them in the job log. It hides only the password of a login credential, so store the other values as masked secrets.

SBOM files

Option	What it does	Default	Required	Accepted values
`--sbom`	An SBOM or lock file to send with the scan. Repeat the option for several files.	None	No	The path to an existing file.

The CLI does not check the file type. The Bitbucket guide lists the SBOM and lock file types that the platform supports.

UI prompts

UI prompts tell the scanner how to move through your app. See UI Prompts.

Option	What it does	Default	Required	Accepted values
`--ui-prompt-id`	The ID of an existing UI prompt to use in the scan. Repeat the option for several IDs.	None	No	A whole number.
`--ui-prompt-name`	The name of a new UI prompt to create for the scan.	None	Yes for each `--ui-prompt-action`	Text.
`--ui-prompt-action`	The instruction of a new UI prompt.	None	Yes for each `--ui-prompt-name`	Text.

The command exits with code 2 if the number of --ui-prompt-name options differs from the number of --ui-prompt-action options. The two options pair by position. You can use IDs and new prompts in the same command.

--ui-prompt-name accept-terms --ui-prompt-action "Scroll down and tap the 'Accept Terms' checkbox." \
--ui-prompt-name submit --ui-prompt-action "Tap the 'Submit' button to complete the login." \
--ui-prompt-id 123

Names in the GitHub Action and the GitLab pipeline

The GitHub Action and the GitLab image run the CLI for you. Their inputs map to the options above.

GitHub Action inputs

The action is Ostorlab/ostorlab_actions.

Action input	CLI option or argument
`ostorlab_api_key`	`--api-key`
`scan_profile`	`--scan-profile`
`scan_title`	`--title`
`break_on_risk_rating`	`--break-on-risk-rating`
`max_wait_minutes`	`--max-wait-minutes`
`asset_type`	The asset sub-command: `android-apk`, `android-aab`, `ios-ipa`, or `link --url` for web.
`target`	The file path, or the URLs of a web scan.
`extra`	Any other CLI options, such as test credentials, `--sbom` or web options.

The action sets --log-flavor github, --source github, --repository and --pr-number itself.

The action has its own default for max_wait_minutes: 20 minutes. The CLI default is 30 minutes.

GitLab variables

The image is ostorlab/gitlab-ci.

GitLab variable	CLI option or argument
`OSTORLAB_API_KEY`	`--api-key`
`OSTORLAB_SCAN_PROFILE`	`--scan-profile`. The values `Fast Scan`, `Full Scan` and `Full Web Scan` map to `fast_scan`, `full_scan` and `full_web_scan`. The default is Fast Scan.
`OSTORLAB_TITLE`	`--title`. The default is `Gitlab scan`.
`OSTORLAB_RISK_THRESHOLD`	`--break-on-risk-rating`
`OSTORLAB_MAX_WAIT_MINUTES`	`--max-wait-minutes`. The default is the CLI default, 30.
`OSTORLAB_PLATFORM`	The asset sub-command. `android` selects `android-apk`, `ios` selects `ios-ipa`, and `link` selects `link`.
`OSTORLAB_FILE_PATH`	The file path of a mobile scan.
`OSTORLAB_URLS`	One `--url` option for each URL.
`OSTORLAB_SBOM_FILES`	One `--sbom` option for each file.
`OSTORLAB_CREDENTIALS`	`--test-credentials-login`, `--test-credentials-password`, `--test-credentials-role` and `--test-credentials-url`.
`OSTORLAB_CUSTOM_CREDENTIALS`	`--test-credentials-name` and `--test-credentials-value`.
`OSTORLAB_API_SCHEMA`	`--api-schema`
`OSTORLAB_FILTERED_URL_REGEXES`	`--filtered-url-regexes`, in theory. The guide lists it, but the image script does not forward it. See the note below the table.
`OSTORLAB_PROXY`	`--proxy`
`OSTORLAB_QPS`	`--qps`
`OSTORLAB_UI_PROMPT_NAMES`, `OSTORLAB_UI_PROMPT_ACTIONS`, `OSTORLAB_UI_PROMPT_IDS`	`--ui-prompt-name`, `--ui-prompt-action` and `--ui-prompt-id`.

The GitLab image does not set --log-flavor, --scope-urls-regexes, --source, --repository, --pr-number, --branch or the 2FA options.

The GitLab guide lists OSTORLAB_FILTERED_URL_REGEXES, but the image does not pass it to the CLI. In the image script (bin/run.sh in Ostorlab/gitlabci), the loop that builds the options uses filtered-url as its variable name. Bash rejects that name with not a valid identifier, so the script sends no --filtered-url-regexes option. To exclude URLs, run the CLI yourself, as in Scan in your CI/CD pipeline.

Risk rating thresholds

--break-on-risk-rating accepts these ratings. They run from the most severe to the least severe. The names are not case-sensitive.

critical
high
medium
low
potentially
hardening
secure
important
info

The command fails when the scan risk rating comes before the threshold in this list. A scan with the same rating as the threshold passes. With critical, no rating comes before the threshold, so the command never fails on risk.

For the meaning of each rating, see Risk Rating.