Deployment: Invicti Platform on-demand, Invicti Platform on-premises
Invicti source scan
Keep your API inventory complete without writing or maintaining OpenAPI specifications by hand. Invicti source scan statically analyzes your application source code, generates OpenAPI 3.0 specifications, and uploads them to Invicti Platform for DAST scanning. It discovers API endpoints across multiple programming languages - including endpoints that are undocumented, missing from your existing specs, or added since your last spec update.
Use it when:
- Your team doesn't maintain an OpenAPI spec, or the spec's incomplete.
- You want to catch shadow APIs and undocumented endpoints before they reach production.
- You need to keep your API inventory in sync with every code change automatically.
This document explains how to set up and run Invicti source scan, authenticate it with your personal API key, upload the generated specification to Invicti Platform, and integrate it into your CI/CD pipeline.
Why this matters
Shadow APIs and undocumented endpoints pose significant security risks - they're harder to track, often miss security controls, and can become attack vectors before you even know they exist. By automatically syncing your API inventory with every code change, Invicti source scan keeps your security posture current and prevents gaps between what you think you're protecting and what's actually in production.
Because your pipeline authenticates with your personal API key instead of a short-lived registration token, it can run unattended. You only need to update the key in your CI/CD secrets when you choose to rotate it or when its optional expiration date passes.
How it works
Invicti source scan runs natively as a Docker container within your existing CI/CD pipeline or local environment:
- Scans source code for active API endpoint definitions.
- Generates a standardized OpenAPI 3.0 specification from all discovered endpoints.
- Optionally enriches the specification with AI-generated descriptions and payload examples.
- Authenticates with Invicti Platform using your personal API key, together with the configuration ID and NAD URL of your Source Scan source.
- Uploads the specification to Discovery > API discovery, where you link it to a target for continuous DAST scanning.
Supported languages
The scanner supports the following programming languages and their popular web frameworks:
Python, JavaScript, TypeScript, C#/.NET, Java, Go, Ruby, PHP, Rust, Kotlin, Swift, Scala, Crystal, Elixir, Visual Basic 6 (VB6)
It also parses existing OpenAPI/Swagger specs and GraphQL schemas.
Prerequisites
- Docker installed on your machine or CI/CD runner.
- A personal API key: Your Invicti Platform API key, which your pipeline uses as
INVICTI_API_TOKEN. Generate it under User settings > API key. You can set an optional expiration date before you generate it. For more information, refer to the Manage your API key document. - A Source Scan source in Invicti Platform: Create it as described in Create a Source Scan source. The source gives you the configuration ID and NAD URL that your pipeline needs.
- Source code accessible as a local directory or Git repository.
- Registry access: Log in to the Invicti container registry before pulling the image:
docker login registry.invicti.com
When prompted, enter your Invicti account email as the username and your license key as the password.
Your pipeline runner must be able to reach the NAD URL shown for your source, which points to your Invicti Platform instance.
Create a Source Scan source
A Source Scan source represents one pipeline in Invicti Platform. It holds the configuration ID that identifies your pipeline, and it's bound to your user account, so the pipeline authenticates with your personal API key.
- Select Discovery > API sources from the left-side menu.
- Click Add source. If you haven't added any sources yet, click Add first source.


- Enter a name for the source in the Name field.
- Keep the Exclude empty specifications toggle on to skip APIs that don't have defined operations. Switch it off to import them as well.
- Under Other, select Source Scan, then click Continue.
- On the Connection details step, copy the Configuration ID (
INVICTI_NAD_CONFIG_ID) and the NAD URL (INVICTI_NAD_URL). Use the copy button next to each field. You can't edit either value. - Select GitHub, GitLab, or Docker, depending on your CI/CD platform. Invicti Platform shows two setup steps for it:
- Store your personal API key in your CI/CD system as a secret named
INVICTI_API_TOKEN. Never write the key into the script or commit it. - Copy the generated script into the file shown. It already contains your configuration ID and NAD URL.
- Store your personal API key in your CI/CD system as a secret named


- Click Save.
The configuration ID only works after you save the source. The source stays pending until your first scan reports in.
The screen also tells you the state of your personal API key. It warns you if you don't have a key yet, if your key has expired, and if it expires within 14 days.
Step 1: Run the scan
Mount your source code at /code (read-only) and an output directory at /output. Pass your credentials by name, so your personal API key never appears on the command line. Export INVICTI_API_TOKEN from your secret store first. Set SCANNER_SERVICE_NAME to give the API a meaningful name in your catalog - without it, the spec title defaults to a timestamped name such as Discovered API - api-20260423-143022.
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_SERVICE_NAME=payment-api \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Invicti source scan always needs your Invicti Platform credentials, even to generate the specification. Copy <configuration-id> and <nad-url> from your source's Connection details step, as described in Create a Source Scan source. This run saves the specification on your machine and doesn't upload it. Step 2 shows how to upload it.
The scanner saves the generated OpenAPI spec as output/openapi.json. A typical scan takes between 30 seconds and 2 minutes depending on codebase size and scan profile.
Example output snippet (openapi.json):
{
"openapi": "3.0.3",
"info": {
"title": "Discovered API - payment-api",
"version": "1.0.0"
},
"paths": {
"/api/users/{id}": {
"get": {
"summary": "Get user by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": { "type": "integer" }
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string" }
}
}
}
}
}
}
}
}
}
}
Scan options
| Variable | Default | Description |
|---|---|---|
SCANNER_PROFILE | standard | quick (deterministic pattern matching only - fastest), standard (adds taint analysis and dataflow graphs), deep (all engines including code property graphs and LLM verification) |
SCANNER_PARALLEL | false | Enable parallel scanning for large codebases |
SCANNER_WORKERS | 4 | Number of parallel workers. Only applies when SCANNER_PARALLEL is set to true |
SCANNER_SERVICE_NAME | - | Service name prefix in the OpenAPI spec title. If not set, defaults to timestamped name (api-YYYYMMDD-HHMMSS) |
SCANNER_INCREMENTAL | false | Only scan files changed since the last run (faster for CI/CD) |
SCANNER_FAIL_ON_CRITICAL | false | Exit with code 2 if the scan reports critical findings (useful for CI/CD pipelines) |
SCANNER_EXCLUDE | - | Comma-separated directory patterns to exclude from the scan (for example, tests,vendor,node_modules) |
SCANNER_INCLUDE | - | Restrict scanning to matching directory patterns only (for example, src,app) |
The service name you set is used throughout the scan and the upload:
- Service name forwarding: The
SCANNER_SERVICE_NAMEvalue carries over from the scan stage to the upload stage - API grouping: Invicti Platform groups multiple API specs uploaded to the same catalog by service name instead of merging them into a single target
AI-enriched specification (optional)
Enable LLM-powered enrichment to improve the quality of the generated OpenAPI specification. This helps DAST scanners test your API more effectively by providing:
- Parameter definitions with types, validation rules, and examples - so the DAST scanner can send correctly formatted requests.
- Request/response schemas with property descriptions and required fields - so the DAST scanner can craft valid payloads and detect unexpected responses.
- Authentication schemes detected from decorators and middleware (Bearer, API key, OAuth 2.0) - so the DAST scanner can authenticate before testing protected endpoints.
Without enrichment, the scanner still generates a complete OpenAPI spec using deterministic analysis - enrichment refines and extends it.
Enrichment options
Set SCANNER_AI_ENRICH=true and provide an API key. If you're using Anthropic Claude, just set the API key - it's the default provider. Set LLM_PROVIDER only if you want to use a different provider.
| Variable | Default | Description |
|---|---|---|
SCANNER_AI_ENRICH | false | Set to true to enable AI enrichment |
LLM_PROVIDER | anthropic | LLM provider. Set only if not using Anthropic: openai, gemini, or bedrock |
ANTHROPIC_API_KEY | - | Anthropic Claude API key (default provider) |
OPENAI_API_KEY | - | OpenAI API key (requires LLM_PROVIDER=openai) |
GOOGLE_API_KEY | - | Google Gemini API key (requires LLM_PROVIDER=gemini) |
AWS_ACCESS_KEY_ID | - | AWS Bedrock access key (requires LLM_PROVIDER=bedrock) |
AWS_SECRET_ACCESS_KEY | - | AWS Bedrock secret key |
SCANNER_MAX_TOKENS | unlimited | Total token budget. When reached, enrichment stops gracefully |
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_AI_ENRICH=true \
-e ANTHROPIC_API_KEY=your-api-key \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
AI enrichment is optional and doesn't affect the core scan. If a provider is unavailable or the token budget is exhausted, the scanner falls back to the deterministic-only spec automatically.
Cost and performance
AI enrichment consumes tokens from your LLM provider account. The scanner minimizes costs with a hybrid approach:
- Deterministic extraction first - The scanner extracts parameters, status codes, types, and descriptions directly from source code without any LLM calls.
- LLM only where needed - The scanner calls the LLM only for endpoints where deterministic confidence is lower than 70%.
- Batch processing - The scanner groups endpoints (default: 20 per batch) to reduce API calls. A codebase with 100 endpoints typically requires ~8 LLM calls instead of 140.
- Caching - The scanner caches results per endpoint using a content hash. If the code hasn't changed, it reuses cached results with no LLM calls.
As a rough estimate, enriching 100 endpoints costs approximately $0.10–$0.50 in LLM tokens (varies by provider and model). Subsequent scans with caching enabled cost near zero for unchanged endpoints. Use SCANNER_MAX_TOKENS to set a hard budget - the scanner stops enrichment gracefully when the limit is reached and outputs the spec with whatever enrichment was completed.
Mount the cache directory as a volume to reuse enrichment results across pipeline runs and avoid repeated LLM costs:
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-v "$(pwd)/.enrichment-cache":/.cache/enrichment \
-e SCANNER_AI_ENRICH=true \
-e ANTHROPIC_API_KEY=your-api-key \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Advanced enrichment configuration
Token budget and rate limiting:
| Variable | Default | Description |
|---|---|---|
SCANNER_MAX_TOKENS | unlimited | Total token budget. When reached, the current batch completes and remaining batches are skipped |
SCANNER_RPM | 60 | Maximum LLM requests per minute |
SCANNER_TPM | 100000 | Maximum tokens per minute |
Caching:
| Variable | Default | Description |
|---|---|---|
ENRICHMENT_CACHE_DIR | /.cache/enrichment | Cache database directory. Mount a volume to persist across runs |
ENRICHMENT_CACHE_TTL | 604800 (7 days) | Cache entry time-to-live in seconds |
SCANNER_NO_CACHE | false | Set to true to skip cache and force fresh analysis |
Batch processing and hybrid analysis:
| Variable | Default | Description |
|---|---|---|
ENABLE_BATCHING | true | Group endpoints into batches to reduce API calls |
OPENAPI_BATCH_SIZE | 20 | Number of endpoints per enrichment batch |
LLM_MODEL | provider default | Override the default model for your provider |
Step 2: Upload to Invicti Platform (API discovery)
Add INVICTI_SYNC=true to the Step 1 command to send the specification to Invicti Platform. Without it, the scan only saves the specification locally.
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_SERVICE_NAME=payment-api \
-e INVICTI_SYNC=true \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Invicti Platform also generates a ready script with your configuration ID and NAD URL filled in, as described in Create a Source Scan source.
| Variable | Required | Description |
|---|---|---|
INVICTI_SYNC | Yes | Set to true to enable upload |
INVICTI_API_TOKEN | Yes, also in Step 1 | Your personal Invicti Platform API key from User settings > API key. Store it as a secret |
INVICTI_NAD_CONFIG_ID | Yes, also in Step 1 | Configuration ID of your Source Scan source, shown on the source's Connection details step |
INVICTI_NAD_URL | Yes, also in Step 1 | NAD URL shown on the source's Connection details step |
DRY_RUN | No | Set to true to validate without uploading |
INVICTI_JWT_TOKEN | No | Legacy registration token, kept for backwards compatibility. Don't use it for new setups |
Invicti source scan authenticates with your personal API key when you set INVICTI_NAD_CONFIG_ID or INVICTI_NAD_URL. A legacy pipeline that sets only INVICTI_API_TOKEN for target linking, as described in Step 3, keeps using INVICTI_JWT_TOKEN for the upload. If a required variable is missing, the scan reports which one.
For more information about the key, including expiration, rotation, and source ownership, refer to Manage the API key and source ownership.
Step 3: Link to a DAST target (optional)
After uploading the spec to API discovery, you can link it to a DAST scan target so that Invicti Platform automatically associates discovered APIs with a live scanning target.
This step uses the same INVICTI_API_TOKEN as the upload, your personal API key. It also needs the platform URL in INVICTI_API_BASE_URL.
Mode A - Find or create target (recommended)
The scanner searches for an existing target by URL. If none is found, it creates one automatically.
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_SERVICE_NAME=payment-api \
-e INVICTI_SYNC=true \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
-e INVICTI_API_BASE_URL='https://platform.invicti.com' \
-e INVICTI_TARGET_URL='https://api.example.com' \
-e INVICTI_CREATE_TARGET=true \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Mode B - Explicit target ID
Use when you already have a DAST target in Invicti Platform and want to link the spec to it directly.
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_SERVICE_NAME=payment-api \
-e INVICTI_SYNC=true \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
-e INVICTI_API_BASE_URL='https://platform.invicti.com' \
-e INVICTI_TARGET_URL='https://api.example.com' \
-e INVICTI_TARGET_ID='<target-uuid-from-platform>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Target linking options
| Variable | Required | Description |
|---|---|---|
INVICTI_API_BASE_URL | Yes | Platform base URL (for example, https://platform.invicti.com) |
INVICTI_API_TOKEN | Yes | Your personal API key from User settings > API key. The same key authenticates the upload |
INVICTI_TARGET_URL | Yes | API base URL of the target (for example, https://api.example.com) |
INVICTI_CREATE_TARGET | Mode A | Set to true to find or create the target by URL automatically |
INVICTI_TARGET_ID | Mode B | Existing DAST target UUID. Mutually exclusive with INVICTI_CREATE_TARGET |
INVICTI_REPLACE_EXISTING | No | Delete existing ApiHub entries with the same alias before re-uploading. Default: true |
The INVICTI_TARGET_URL value must be identical in both the source scan and any downstream DAST scan job.
CI/CD handoff via dotenv artifact
When target linking is configured, the scanner writes output/scan.env containing INVICTI_TARGET_ID. This file can be passed to a downstream DAST scan job as a dotenv artifact.
Step 4: View and scan imported APIs
- Select Discovery > API discovery from the left-side menu.
- Locate the uploaded specification. Click Link to link it to an existing target, or Create to create a new target for it (or use Step 3 to do this automatically). For more information, refer to Link discovered APIs to targets and Create targets from API discovery.
- Start a DAST scan to test the discovered endpoints. Once linked, the API moves to Inventory > API catalog, and the target's scans include it.
Manage the API key and source ownership
Your pipeline acts as you, so it carries your permissions and depends on your personal API key. Keep these points in mind when you manage the key and the source.
Source ownership
Invicti Platform binds a Source Scan source to the user who creates it. The source accepts only that user's personal API key as INVICTI_API_TOKEN. If you open a source that belongs to another user, Invicti Platform shows who owns it. To scan with your own key, create a new Source Scan source.
API key expiration
A personal API key never expires unless you set an expiration date before you generate it. The date picker accepts any date from tomorrow up to 365 days from today. By default, Invicti Platform also limits a key's lifetime to 365 days, but some environments use a shorter limit. If the date you choose is later than that limit, Invicti Platform sets the expiration to the limit instead, without an error. After you generate the key, the API key page shows the actual expiration date.
Invicti Platform shows a warning on the Connection details step when your key has expired or expires within 14 days. After the expiration date, the key stops working and every pipeline that uses it fails. The scan also warns you in its output, starting 14 days before the key expires. The warning turns red when less than a day is left.
Rotate, revoke, or replace the key
Rotating or revoking your personal API key takes effect immediately. The old key stops working for every pipeline and integration that uses it, so the next Source Scan run fails until you update the key.
- Generate the new key under User settings > API key. For more information, refer to the Manage your API key document.
- Update the
INVICTI_API_TOKENsecret in your CI/CD system with the new key. - Run your pipeline again.
You don't need to change the configuration ID or the NAD URL. They belong to the source, not to the key.
Migrate a pipeline from a registration token
Pipelines that use INVICTI_JWT_TOKEN keep working. To move them to your personal API key:
- Select Discovery > API sources from the left-side menu.
- Click Edit for the source your pipeline uses.
- Read the warning that the source was set up with a registration token, then click Use my API key. This binds the source to you.
- Copy the configuration ID and NAD URL, and store your personal API key as the
INVICTI_API_TOKENsecret in your CI/CD system. - In your pipeline, replace
INVICTI_JWT_TOKENwithINVICTI_API_TOKEN,INVICTI_NAD_CONFIG_ID, andINVICTI_NAD_URL. You can copy the generated script from the Connection details step.
Keep INVICTI_JWT_TOKEN out of the new pipeline. Registration tokens aren't supported for new setups.
Output formats
The primary output is the OpenAPI 3.0 specification (output/openapi.json) that gets uploaded to API discovery. The scanner also generates a detailed JSON result file with endpoint metadata and statistics.
For CI/CD pipeline visibility, you can optionally enable additional report formats:
| Variable | Output file | Description |
|---|---|---|
| (default) | output/openapi.json | OpenAPI 3.0 specification - uploaded to API discovery |
| (default) | output/result.json | Full scan results with endpoint metadata and statistics |
SCANNER_SARIF_FILE | output/results.sarif | SARIF 2.1 - for GitHub or other code analysis dashboards |
SCANNER_JUNIT_FILE | output/results.junit.xml | JUnit XML - for CI/CD test result viewers (GitLab, Jenkins, Azure DevOps) |
Tracking API changes in CI/CD
To see what API changes occurred in a given build, provide the previous OpenAPI spec. The scanner includes a diff in the JSON output (changes field) showing added, removed, and modified endpoints.
docker run --rm \
-v "/path/to/your/source/code":/code:ro \
-v "$(pwd)/output":/output \
-v "$(pwd)/previous-openapi.json":/previous/openapi.json:ro \
-e PREVIOUS_SPEC=/previous/openapi.json \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
CI/CD integration
Store your personal API key as a secret named INVICTI_API_TOKEN in your CI/CD system, and replace <configuration-id> and <nad-url> with the values from your source's Connection details step. Invicti Platform generates these scripts with your values filled in.
GitHub Actions
Add your personal API key as a repository secret named INVICTI_API_TOKEN under Settings > Secrets and variables > Actions.
name: Invicti Source Scan
on:
push:
branches: [main]
jobs:
invicti-source-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Invicti Source Scan
env:
INVICTI_API_TOKEN: ${{ secrets.INVICTI_API_TOKEN }}
run: |
mkdir -p "${{ github.workspace }}/output"
chmod a+rwx "${{ github.workspace }}/output"
docker run --rm \
-v "${{ github.workspace }}":/code:ro \
-v "${{ github.workspace }}/output":/output \
-e SCANNER_SERVICE_NAME="${{ github.event.repository.name }}" \
-e INVICTI_SYNC=true \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID="<configuration-id>" \
-e INVICTI_NAD_URL="<nad-url>" \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
GitLab CI
The following jobs assume that DOCKER_AUTH_CONFIG and INVICTI_API_TOKEN (your personal API key) are masked project-level CI/CD variables.
Upload the spec and run a DAST scan
invicti-source-scan:
stage: appsec-test
image:
name: registry.invicti.com/invicti-platform/invicti-source-scan:latest
entrypoint: [""]
tags:
- invicti-linux-t-small-amd64
needs: []
variables:
# DOCKER_AUTH_CONFIG and INVICTI_API_TOKEN (your personal API key, masked) are project-level CI/CD variables injected automatically.
TARGET_DIR: $CI_PROJECT_DIR
OUTPUT_DIR: $CI_PROJECT_DIR/source-scan-output
OPENAPI_FILE: $CI_PROJECT_DIR/source-scan-output/openapi.json
SCANNER_PROFILE: deep
SCANNER_ENABLE_TAINT: "true"
INVICTI_SYNC: "true"
INVICTI_NAD_CONFIG_ID: "<configuration-id>"
INVICTI_NAD_URL: "<nad-url>"
SCANNER_SERVICE_NAME: "test-api"
INVICTI_TARGET_URL: "https://example.com/api/v1"
INVICTI_CREATE_TARGET: "true"
SCANNER_EXCLUDE: "libs,tests,docs, utils"
script:
- /app/entrypoint.sh
artifacts:
when: always
paths:
- source-scan-output/
reports:
junit: source-scan-output/results.junit.xml
dotenv: source-scan-output/scan.env
expire_in: 7 days
allow_failure: true
rules:
- if: '$CI_PIPELINE_SOURCE != "merge_request_event"'
invicti-dast-scan:
stage: appsec-test
image: invicti/scan-cli:latest
tags:
- invicti-linux-t-large-amd64
# All required variables (INVICTI_API_BASE_URL, INVICTI_API_TOKEN, INVICTI_SCAN_PROFILE, INVICTI_SCAN_AGENT) are project-level CI variables injected automatically.
# INVICTI_TARGET_ID comes from the invicti-source-scan dotenv artifact.
script:
- /home/invicti/scancli/ScanCLI
allow_failure: true
needs:
- job: invicti-source-scan
artifacts: true
rules:
- if: '$CI_PIPELINE_SOURCE != "merge_request_event"'
For all invicti/scan-cli:latest environment variables, see CI environment variables.
Docker (generic recipe)
Export INVICTI_API_TOKEN (your personal API key) from your secret store before you run the script.
#!/bin/bash
set -e
: "${INVICTI_API_TOKEN:?Set INVICTI_API_TOKEN to your personal Invicti Platform API key}"
mkdir -p output
chmod a+rwx output
docker run --rm \
-v "$(pwd)":/code:ro \
-v "$(pwd)/output":/output \
-e SCANNER_SERVICE_NAME=my-api-service \
-e SCANNER_PROFILE=deep \
-e INVICTI_SYNC=true \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID="<configuration-id>" \
-e INVICTI_NAD_URL="<nad-url>" \
-e INVICTI_API_BASE_URL="${INVICTI_API_BASE_URL}" \
-e INVICTI_TARGET_URL="${INVICTI_TARGET_URL}" \
-e INVICTI_CREATE_TARGET=true \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Troubleshooting
If you run into issues, find the group that matches where the problem appears, then expand the relevant section.
Scan results and local runs
Use these entries when the scan finishes with unexpected results, takes too long, or can't start on your machine.
No endpoints found
- Verify the correct directory is mounted at
/code. - Confirm your project uses a supported language.
- For large route files, increase the file size limit:
-e SCANNER_MAX_FILE_SIZE=10 - If the scan finds no endpoints, nothing is uploaded, even with
INVICTI_SYNC=true.
Scan is slow
- Use
SCANNER_PROFILE=quickfor faster deterministic-only scanning. - Enable parallel mode:
-e SCANNER_PARALLEL=true -e SCANNER_WORKERS=8 - Use incremental scanning in CI/CD:
-e SCANNER_INCREMENTAL=true - Exclude test/vendor directories:
-e SCANNER_EXCLUDE=tests,vendor,node_modules
Path contains spaces (Windows)
Wrap the volume mount path in quotes:
docker run --rm \
-v "C:/Users/My Name/project":/code:ro \
-v "$(pwd)/output":/output \
-e INVICTI_API_TOKEN \
-e INVICTI_NAD_CONFIG_ID='<configuration-id>' \
-e INVICTI_NAD_URL='<nad-url>' \
registry.invicti.com/invicti-platform/invicti-source-scan:latest
Authentication and upload
Use these entries when the scan can't authenticate with Invicti Platform or the platform rejects the request. Start with the first entry, then move to the one that matches the code in the scan output.
Upload to Invicti fails
- Verify that
INVICTI_API_TOKEN,INVICTI_NAD_CONFIG_ID, andINVICTI_NAD_URLare all set. If one is missing, the scan names it. - Verify that
INVICTI_API_TOKENholds your personal API key and that the key is the current one. A key you rotated or revoked stops working immediately. - Test with dry run first:
-e DRY_RUN=true - The scan checks your connection and credentials before it starts. If that check fails, the scan stops before analyzing any code.
- If the platform rejects the request, the scan prints a red message in the job log. Its title is
Connection failed: <CODE> (HTTP <status>)orUpload failed: <CODE> (HTTP <status>). A short explanation and a How to fix it list follow. The connection check runs before the upload, so most failures showConnection failed. - Find your code in one of the entries that follow. The scan shows these codes only when it authenticates with your personal API key, that is, when
INVICTI_NAD_CONFIG_IDorINVICTI_NAD_URLis set.
API key errors: API_KEY_EXPIRED, API_KEY_INVALID, JWT_NOT_SUPPORTED_FOR_SOURCE_SCAN
| Code | What the scan says | What to do |
|---|---|---|
API_KEY_EXPIRED | The API key in INVICTI_API_TOKEN has expired. When the platform provides it, the message adds the time, for example (expired 2026-10-01 09:30 UTC). | Check the expiration date under User settings > API key, generate a new key, and update the INVICTI_API_TOKEN secret in your CI/CD system. For more information, refer to Rotate, revoke, or replace the key. |
API_KEY_INVALID | The API key in INVICTI_API_TOKEN is invalid, or it was regenerated or deleted. | Copy your current key from User settings > API key and update the INVICTI_API_TOKEN secret. Make sure the secret contains the key itself, with no extra spaces or quotes. |
JWT_NOT_SUPPORTED_FOR_SOURCE_SCAN | Registration tokens (INVICTI_JWT_TOKEN) can no longer be used to set up Invicti source scan. | Set your personal API key as the INVICTI_API_TOKEN secret, set INVICTI_NAD_CONFIG_ID and INVICTI_NAD_URL as shown on the source's Connection details step, and remove INVICTI_JWT_TOKEN. To migrate, follow Migrate a pipeline from a registration token. |
Registration tokens still work for pipelines you set up before. Invicti source scan switches to your personal API key when INVICTI_NAD_CONFIG_ID or INVICTI_NAD_URL is set.
Source and configuration ID errors: CONFIG_ID_MISSING, CONFIG_ID_INVALID, IMPORTER_NOT_FOUND, IMPORTER_TYPE_NOT_SUPPORTED, IMPORTER_NOT_BOUND, API_KEY_OWNER_MISMATCH
| Code | What the scan says | What to do |
|---|---|---|
CONFIG_ID_MISSING | INVICTI_NAD_CONFIG_ID is missing. | Copy the configuration ID and NAD URL from the source's Connection details step into your pipeline. Open the source from Discovery > API sources. |
CONFIG_ID_INVALID | INVICTI_NAD_CONFIG_ID isn't a valid configuration ID. | Copy the configuration ID again from the source's Connection details step. The configuration ID only works after you save the source. |
IMPORTER_NOT_FOUND | The Source Scan source with this INVICTI_NAD_CONFIG_ID has been deleted. | Create a new Source Scan source and use its configuration ID and script. |
IMPORTER_TYPE_NOT_SUPPORTED | INVICTI_NAD_CONFIG_ID belongs to a source that isn't an Invicti source scan source. | Open your Source Scan source and copy its configuration ID and NAD URL. IDs of other source types, such as Network Traffic Analyzer sources, aren't accepted. |
IMPORTER_NOT_BOUND | This source isn't bound to any user's API key yet. | Open the source under Discovery > API sources, select Use my API key, and set your personal API key as INVICTI_API_TOKEN. Sources created before personal API keys were introduced can be unbound. |
API_KEY_OWNER_MISMATCH | This source is bound to another user's API key. | A Source Scan source only accepts the personal API key of the user it's bound to. Open the source to see who owns it. Either use the owner's key, or create a new Source Scan source with your own account and use its configuration ID. |
Access errors: INSUFFICIENT_PERMISSIONS, IMPORTER_ACCESS_DENIED, IP_RESTRICTION_DENIED
| Code | What the scan says | What to do |
|---|---|---|
INSUFFICIENT_PERMISSIONS | The API key's user isn't allowed to add APIs to the API inventory. | Ask your administrator to grant the source owner the permission to create APIs in the inventory. |
IMPORTER_ACCESS_DENIED | INVICTI_API_TOKEN belongs to a user of a different organization than this source. | Use the key of a user in the source's organization. Check that INVICTI_NAD_CONFIG_ID and INVICTI_NAD_URL point to the right source and Invicti Platform instance. |
IP_RESTRICTION_DENIED | The API key can't be used from this runner's IP address. | Your organization restricts API key use to specific IP addresses. Ask your Invicti Platform administrator to allow the runner's address, or run from an allowed network, such as a runner with a fixed outgoing address. |
Platform errors: IDENTITY_UNAVAILABLE, SERVICE_UNAVAILABLE, INTERNAL_ERROR
The scan reports IDENTITY_UNAVAILABLE, SERVICE_UNAVAILABLE, or INTERNAL_ERROR. Your API key isn't the problem. The first two are usually temporary, so re-run the pipeline in a few minutes. If INTERNAL_ERROR or the others persist, contact Invicti support.
Network and registry
Use these entries when the CI/CD runner can't pull the Invicti source scan image or can't connect to your Invicti Platform instance.
The runner can't reach the NAD URL (on-premises)
The NAD URL points to your Invicti Platform instance. Confirm that your CI/CD runner can resolve and reach that address, including any proxy or firewall in between.
Registry authentication fails in CI/CD
In environments like Kubernetes, the image pull happens before job variables are processed. Set DOCKER_AUTH_CONFIG at the runner level, or use DinD to authenticate prior to running the image. Keep your license key masked/protected in your CI configurations.
Target linking and DAST handoff
Use these entries when the spec uploads, but the source scan job doesn't link it to the right DAST target or the DAST scan job doesn't pick up that target.
Target linking fails (HTTP 401)
Target linking uses the same INVICTI_API_TOKEN as the upload: your personal API key from User settings > API key. Verify that the key hasn't expired or been rotated, and that INVICTI_API_BASE_URL points to your Invicti Platform instance.
DAST scan job doesn't receive INVICTI_TARGET_ID
Ensure both INVICTI_API_BASE_URL and INVICTI_API_TOKEN are set, and that INVICTI_TARGET_URL matches the application URL. In GitLab, ensure the source scan job correctly exports the dotenv artifact.
DAST scan creates a new target instead of reusing the existing one
The INVICTI_TARGET_URL value must perfectly match between the source scan and DAST scan jobs, including protocols and trailing slashes.
Need help?
Invicti Support team is ready to provide you with technical help. Go to Help Center