Saltar a contenido

Scan in your CI/CD pipeline

Running Ostorlab in a pipeline starts a scan from your CI job and can fail the job when the scan risk rating exceeds your threshold. You need an API key stored as a secret and a scan profile. To fail the job on risk, also set a failure threshold.

How a CI scan works

A CI step calls Ostorlab with your API key, a scan profile and the asset to scan. The CLI does not run the scan itself. It asks the platform to create the scan.

  1. Start. The step uploads the app file, or sends the URLs, and asks the platform to create the scan. It logs the scan ID.
  2. Wait. The step waits only if you set a failure threshold. It checks the scan every 10 seconds, up to the maximum wait. Without a threshold, the step ends as soon as the scan is created.
  3. Fail on threshold. When the scan finishes, the step compares the scan risk rating with your threshold. If the rating is higher, the step exits with code 2 and the pipeline fails.
  4. Time out. If the scan does not finish within the maximum wait, the step also exits with code 2.

The results stay in the platform. Use the scan ID to open the scan. The GitHub guide builds the link as https://report.ostorlab.co/scan/<scan_id>/.

Choose a native integration or the CLI

Ostorlab provides a ready-made step for some CI tools. For the others, you install the CLI and run one command in a script step. The CLI also gives you every option listed in CI scan options. The table lists 10 active tools, then App Center, which Microsoft has retired.

Tool How you connect Guide
GitHub Actions The Ostorlab GitHub Action. An optional GitHub App comments on pull requests. GitHub
GitLab CI/CD The ostorlab/gitlab-ci image, configured with environment variables. GitLab
Jenkins The Ostorlab plugin, as a freestyle build step or a pipeline step. Jenkins
Azure DevOps The Ostorlab extension from the Azure DevOps Marketplace. Azure DevOps
CircleCI The Ostorlab orb. CircleCI
Bitbucket Pipelines A script step that installs and runs the CLI. Bitbucket
GoCD A command line task that runs the CLI. GoCD
TeamCity A command line step that runs the CLI in the ostorlab/oxo:latest container. TeamCity
Bitrise A script step that installs and runs the CLI. Bitrise
Harness A run step that installs and runs the CLI. Harness
App Center (retired by Microsoft) A webhook, set up from a configuration you create in Ostorlab. It needs no pipeline script. App Center

Microsoft retired Visual Studio App Center on 31 March 2025. See the Microsoft retirement notice. The App Center guide stays for existing configurations.

If your tool is not in the list, run the CLI in any step that can run a shell command:

pip install ostorlab
ostorlab --api-key "$OSTORLAB_API_KEY" ci-scan run \
  --scan-profile fast_scan \
  --title "CI scan" \
  --break-on-risk-rating high \
  android-apk app-release.apk

With --break-on-risk-rating high, the step fails on a Critical rating. It also fails if the scan does not finish within 30 minutes, the default maximum wait. You can also create scans from a script through the API.

Choose a scan profile

A CI scan accepts three scan profiles. Pass the lowercase value, not the name shown in the platform.

Value Platform name What it runs
fast_scan Fast Scan Static analysis.
full_scan Full Scan Static, dynamic and backend analysis.
full_web_scan Full Web Scan A web application scan.

The CLI does not accept other profiles, such as a Deep Agentic Scan. For what each profile covers and how long it takes, see Supported Scan Profiles and Scan Types Comparison.

Keep the API key safe

Treat the API key like a password. The CLI sends it with every request the step makes.

  • Create the key in the platform. See API keys. You can set a name and an expiry date.
  • Store the key in the secret store of your CI tool, so the tool can mask it in job logs. Do not commit it and do not write it in the pipeline file.
  • Reference the secret in the step. The CLI reads no environment variable for the key, so pass it with --api-key before ci-scan.
  • Do not echo the key and do not turn on shell tracing in the step.

Each guide shows where to put the key:

  • GitHub: GitHub secrets.
  • GitLab: CI/CD variables.
  • Jenkins: a Secret text credential.
  • Azure DevOps: entered in the Ostorlab extension step.
  • CircleCI: entered in the Ostorlab orb configuration.
  • Bitbucket: Bitbucket variables.
  • GoCD: a secure variable.
  • TeamCity: the environment variable OSTORLAB_API_KEY.
  • Bitrise: a Bitrise secret.
  • Harness: a secret.

The Azure DevOps and CircleCI guides enter the key in the step itself, and the TeamCity guide does not say to mark the variable as secret. Where your tool lets you mark the value as secret or reference a secret variable, do that so the tool masks it. API keys lists the names the guides use.

App Center needs no Ostorlab API key. Its configuration holds an App Center API token instead.

Store test credentials the same way. The CLI hides only the password of a login credential in its own log line. It prints the values of custom credentials, the email 2FA password and the TOTP seed in the job log. A masked secret lets your CI tool hide those values in the log.

What the failure threshold means

The failure threshold is the --break-on-risk-rating option. The step fails when the scan risk rating is strictly higher than the threshold. A scan with the same rating as the threshold passes.

Threshold The step fails when the scan risk rating is
critical Never. No rating is higher than Critical.
high Critical.
medium Critical or High.
low Critical, High or Medium.

The value is not case-sensitive. Without a threshold, or with an empty value, the step does not wait and does not check the rating. See Risk rating thresholds for the full order.

The Jenkins plugin is the exception. It does not run the CLI, and its guide says the build fails when the risk equals or exceeds the threshold. Follow the Jenkins guide for that tool.

Asset types you can scan from CI

The ci-scan run command has four asset sub-commands:

  • Android APK: android-apk, with the path to the .apk file.
  • Android AAB: android-aab, with the path to the .aab file.
  • iOS IPA: ios-ipa, with the path to the .ipa file.
  • Web application: link, with one or more --url options.

Other asset types, such as store apps, network ranges or code repositories, have no CI sub-command.

Next steps