CI/CD Integration
Overview
Pensar provides a CLI tool and API for integrating automated pentesting directly into your CI/CD pipeline. Run pentests on every commit or deployment to catch vulnerabilities before they reach production.
CI-triggered pentests consume credits from your workspace balance. See Billing & Usage for details on credit management and usage tracking.
Installation
Install the Pensar CI package globally:
Or add it as a dev dependency:
View the source code and additional examples on GitHub.
Configuration
Required Environment Variables
Optional Environment Variables
You can configure CI/CD integration directly from the Pensar Console. Navigate to Settings → Automation → CI/CD in your workspace for guided setup and one-click workflow creation.
CLI Usage
Run a Pentest
Options:
Examples:
How the CI diff is calculated
By default:
- Compare: Your requested commit (
--commit) is compared with the latest qualifying completed pentest for the same repository in your workspace. This baseline is shared across branches and environments; it is not the previous deployment. - Filter: Files such as
package.jsonand lockfiles are excluded. If no changes remain, testing is skipped; large changes can trigger broader coverage. - Test: The agent uses the diff to create security objectives for the affected applications.
- Results: A launched scan returns an ID and status, with findings after testing completes. Buffered runs can defer launch; a queued scan is not a passing result.
Without a baseline, or if a force-push removed it, Pensar runs without diff narrowing. Other comparison errors fail the run. For an explicit comparison, the API accepts baseSha with commitSha; both commits must exist.
Invalid domain URLs
Workspace-wide and CI-derived scopes skip applications with unparseable domain URLs and continue with the applications that are ready. An explicitly selected scope fails if any selected application is blocked; any scope fails when none are ready.
If a pentest cannot start because an application’s domain URL is invalid, CI returns
400 with the affected application and correction steps. Testing has not started.
In Attack surface → Domains, open the linked domain’s menu, choose Edit,
and correct Domain URL, for example https://app.acme.example. Then retry the pentest.
Valid bare hostnames are automatically read as HTTPS; explicit HTTP URLs and ports
are preserved.
Testing guidance
Pensar’s planner decides what to test by analyzing the commit diff. Testing guidance adds your own context to that analysis, so the planner knows which parts of your application matter most.
Save it under Settings → CI/CD → Testing guidance (workspace admins only).
It applies to commit pentests and pull-request reviews, in both custom and
endpoint-selection modes. Leave it empty to use Pensar’s defaults.
What guidance does and does not do:
- It adds priorities, it does not replace the diff analysis. Pensar still reads the diff on every run and only tests what the change actually affects.
- It cannot widen scope. Guidance is advisory context, not a target list. Pensar only tests the applications, endpoints, domains, and hosts your workspace has already authorized, so guidance cannot reach anything else — in your workspace or any other.
- It is advisory, not a hard rule. Write it as priorities (“prioritize authentication changes”), not as absolute include/exclude rules. To pin a run to an exact set of endpoints, scope the launch instead — see Launch a pentest.
- The planner explains its effect. Each run records the reasoning behind its selection, so you can see how your guidance shaped it.
To override the saved guidance for one run — for example, to pass the output of
your own risk classifier — send testingGuidance to
POST /ci/dispatch. The value used by a run is recorded on
that pentest, so a retry plans against the same text. Guidance is capped at
4,000 characters.
Compare two explicit commits
To test exactly what changed between two deployed versions, pass the previously deployed commit as --base (or PENSAR_BASE_SHA) along with the new commit. Requires @pensar/ci 2.7.0 or later.
In GitHub Actions the repository is detected automatically; elsewhere, pass --repo-id. The CLI sends these as baseSha and commitSha to POST /ci/dispatch, which you can also call directly.
- Both values must be full 40-character SHAs, and the repository must be known (
--repo-id, orrepoId/repositoryIdon the API). - Both commits must exist in that repository. A missing commit returns
400; Pensar does not fall back to the last pentest or a full scan. - The two commit trees are compared directly, so rollbacks and diverged histories work. The commit buffer is bypassed.
- If the two commits are the same, there is nothing to test and the run is skipped.
- The range is kept if the scan is queued, deduplicated, or retried.
Run Only on Labelled Changes
When only some changes are worth pentesting, label the pull request and gate the workflow on that label. This is done in the workflow, not in the CLI.
On a pull-request-triggered workflow the labels are in the event payload, so a job-level condition is all you need and nothing extra runs:
On a push or a post-deploy run there is no pull request in the payload, so the pull request the commit came from has to be looked up. Add a small job that does the lookup and make the pentest job depend on it:
Because the pentest job depends on the gate, an unlabelled change never starts it: no runner, no checkout, no install.
Keep the label in LABEL rather than inlining it into the command. A label is
free text, so an apostrophe would break the quoting and a . or * would make
grep match a different label; -F compares it literally.
After a deploy, use ${{ github.event.workflow_run.head_sha }} rather than
${{ github.sha }}. On a workflow_run event github.sha is the tip of the
default branch, not the commit that was deployed, so the gate would check
whichever change landed most recently.
The Console generates both of these for you: enter a label under Settings → CI/CD and the workflow snippets on that page include the gate, with the right SHA for each trigger.
Check Scan Status
Example:
CI/CD Examples
GitHub Actions
On Push
On Pull Request
After Deployment
Compare With Last Deploy
Run a pentest when commits are pushed to main branches:
GitLab CI
Add to your .gitlab-ci.yml:
Bitbucket Pipelines
Add to your bitbucket-pipelines.yml:
Exit Codes
The CLI exits with code 1 when it finds an issue at or above --severity (critical by default). Use this to block deployments when vulnerabilities are detected.
API Reference
Dispatch Scan
Headers:
Authorization: Bearer <api_key>orx-api-key: <api_key>Content-Type: application/json
Request Body:
Provide a repository so the pentest is scoped to that repository’s
applications. Supply either repoId (GitHub’s numeric repository id — the
CLI auto-detects this from GITHUB_REPOSITORY_ID) or repositoryId (the
internal repository UUID). When neither is supplied, application scope remains
workspace-wide. Exactly one connected repository still supplies attribution and
a baseline; multiple repositories leave the scan unattributed without diff narrowing.
The repository must already be connected to the workspace. If it isn’t found,
the API responds 404; if it belongs to another workspace, 403; if it has
no discovered applications yet (run reconnaissance first), 422.
With baseSha, CI compares exactly that commit to commitSha in the selected repository and bypasses the commit buffer. Both commits must exist there; a missing commit returns 400 instead of recovering to a full scan. Omit baseSha to keep the default last-pentest baseline.
pullRequest records the scan as a pull-request review (eventType: pull-request). A number is resolved to https://github.com/{owner}/{name}/pull/{n} when a repository is selected. A review skips the commit buffer and the branch guard, and plans its own scope from the diff: the affected endpoints, including new routes, each with its own objectives, in place of testType. targetUrl is the host the live test hits; it must be a verified domain or sit under one, or the API responds 403. errorSeverityThreshold is the CLI’s --severity (sent with --pull-request), and the review’s GitHub check concludes with it; only pull-request reviews get a check.
testType: custom derives application-level objectives from the diff;
endpoint-selection selects affected discovered endpoints. Both use the same
repository baseline and recovery rules above. A supplied branch must match the
repository’s configured target branch unless pullRequest is set;
it does not select a different branch for one run.
testingGuidance replaces your workspace’s saved testing guidance for this one
run — see Testing guidance below. Omit it to use the saved
value; a blank string is rejected with a 400 rather than silently dropping the
saved guidance.
Response:
Get Scan Status
Headers:
Authorization: Bearer <api_key>orx-api-key: <api_key>
Response: