Engagement Workflow

You can launch a pentest from the Nullify dashboard or with the Nullify CLI.

Before you start, work through Preparing for an Engagement. Engagements usually stall for one of three reasons: our source IP is not allowlisted, the test credentials do not authenticate, or there is no API specification.

Dashboard

1. Go to Assessments → Pentest → Applications.

2. Select Add Application and give it a target — a hostname and port.

3. Attach one credential per role you want tested, then validate each one. A pentest cannot start until every attached credential authenticates.

4. Optionally run a preflight check, which confirms the application is ready to test and estimates cost and duration.

5. Start the run. Progress and findings stream into the dashboard and any connected ticketing or chat integrations.

Launch a new pentest

Creating applications and credentials requires the Admin role. Starting and stopping scans requires Editor. If the Start Pentest button is not visible on your tenant, self-service pentesting has not been enabled yet — contact your Nullify representative.

Nullify discovers your API specification automatically where it can (see Supported Targets). There is no specification upload in the dashboard. To supply a specification file directly, use the CLI or send it to your Nullify contact.

CLI

Use the CLI to run a pentest from your own environment, to wire one into a pipeline, or to test a service that is not reachable from the internet.

Install the CLI and authenticate:

curl -sSfL https://raw.githubusercontent.com/Nullify-Platform/cli/main/install.sh | sh -s -- --host api.<TENANT>.nullify.ai
nullify auth login --host api.<TENANT>.nullify.ai

In CI, set NULLIFY_TOKEN to a service-account token instead of logging in. See API Configuration for how to generate one. Inside GitHub Actions you can pass the workflow's GitHub token with --github-token and the CLI exchanges it for a Nullify token — see CLI Authentication.

Run a pentest:

nullify pentest \
  --app-name      "Payments API" \
  --spec-path     "./openapi.json" \
  --target-host   "https://api.example.dev" \
  --github-owner  "my-org" \
  --github-repo   "payments-service" \
  --header        "Authorization: Bearer 1234" \
  --header        "X-Custom-Header: abcxyz"

--spec-path is required. Repeat --header once per header you want the pentester to send.

Testing more than one role

Static headers test one identity. To find authorization flaws — IDOR, broken object-level authorization, privilege escalation — the pentester needs one credential set per role. Pass a config file with --auth-config:

nullify pentest \
  --app-name    "Payments API" \
  --spec-path   "./openapi.json" \
  --target-host "https://api.example.dev" \
  --auth-config "./pentest-auth.json"

--auth-config takes a JSON file — unlike --spec-path, this file is not parsed as YAML. The top-level users array holds one entry per role:

{
  "users": [
    {
      "roleName": "admin",
      "roleDescription": "Administrator with full access",
      "authConfig": {
        "method": "bearer",
        "token": "<admin token>"
      }
    },
    {
      "roleName": "user",
      "roleDescription": "Standard user",
      "authConfig": {
        "method": "bearer",
        "token": "<user token>"
      }
    },
    {
      "roleName": "guest",
      "roleDescription": "Unauthenticated",
      "authConfig": {
        "method": "none"
      }
    }
  ]
}

The CLI does not expand ${VAR} or template this file — whatever you write into token or password is read and sent as-is. Do not commit a populated auth-config file to source control: generate it at run time from your secret store (for example, write it to a temporary path in your CI job just before the nullify pentest step, then delete it) or keep it in a path covered by .gitignore.

Running against a private network

Add --local to run the pentester inside your own network against hosts only you can reach. See Running in Private Networks.

Continuous Integration

Run the CLI in your pipeline. In GitHub Actions, pass the workflow token and the CLI handles the rest:

- name: Nullify pentest
  run: |
    nullify pentest \
      --github-token "${{ secrets.GITHUB_TOKEN }}" \
      --app-name     "Payments API" \
      --spec-path    "./openapi.json" \
      --target-host  "https://api.staging.example.dev"

Use nullify ci gate to fail a build on new findings and nullify ci report to publish results.

Pentests are slow and cost far more than a code scan, so run them on release branches or a schedule rather than on every commit.

What to expect

Typical duration	One to three hours
Maximum duration	Six hours
Concurrency	One run per application at a time
Preflight checks	Five per application per day

Findings appear in the dashboard as they are confirmed. Each confirmed finding carries the request and response that proved it, plus a reproduction script. Download the PDF report from the run page once the engagement completes.