> This is part 1 of 2 of the full documentation (pages 1–100 of 142).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.nullify.ai/llms-full.txt/1
> Page index: https://docs.nullify.ai/llms.txt

# Introduction

Nullify connects security findings to the code, applications, cloud resources, and teams behind them. It helps investigate risk, plan remediation, and prepare fixes for human review.

## Start with your environment

[Install Nullify](/getting-started/install), then complete [onboarding](/getting-started/getting-started): connect source control, enroll repositories, configure workflow destinations, and provide business context. Cloud and runtime assessments need their own connections, targets, credentials, and authorization.

The [Context Engine](/capabilities/context-engine) builds relationships from the information available to it. Missing connections or incomplete scans limit that view; connecting one repository does not establish coverage of your entire organization.

## Assess and prioritize

| Capability                                                            | What it examines                                                                                         |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Code Analysis](/capabilities/code-reviews/code-analysis)             | Supported source-code and infrastructure-as-code patterns.                                               |
| [Dependency Analysis](/capabilities/code-reviews/dependency-analysis) | Package and container vulnerabilities, with reachability where supported.                                |
| [Secrets Detection](/capabilities/code-reviews/secrets-detection)     | Exposed credentials and, when enabled, sensitive data.                                                   |
| [Supply Chain Posture](/capabilities/scpm)                            | Package policy, metadata, suspicious behavior, and known malicious packages.                             |
| [Threat Intelligence](/capabilities/threat-intelligence)              | Newly disclosed vulnerabilities and supply-chain compromises, assessed against your connected inventory. |
| [Cloud Audits](/capabilities/cloud-audits)                            | Collected cloud and Kubernetes configuration.                                                            |
| [Bug Hunts](/capabilities/bug-hunts)                                  | Authorized external attack-surface discovery and selected testing suites.                                |
| [Pentests](/capabilities/pentests)                                    | Scoped application testing with engagement evidence and coverage reporting.                              |

[Triage](/capabilities/triage) weighs reachability, exploitability, and business context to prioritize findings. [Exploit Validation](/capabilities/pentests/exploit-validation) can test selected findings against an authorized non-production target under an enabled, armed policy. An untested or inconclusive finding is not evidence that a vulnerability is absent.

## Plan and remediate

[Security Program Management](/capabilities/program-management) organizes strategies and campaigns around risk, team capacity, and your policies. [Remediations](/capabilities/remediations) can propose patches and work through CI feedback and review. Inspect the evidence and current checks before merging; a generated patch is not a guarantee of correctness.

When human input is required, Nullify raises [action items](/capabilities/working-with-nullify). Use [configuration](/configuration/configuration-general) to control PR checks, ticketing, notifications, and allowed actions.

## Integrate and automate

Browse [connectors](/connectors/connectors) for setup and availability, the [public CLI](/cli/cli) for terminal and CI workflows, and the [API reference](/api-reference/api-reference) for direct integrations. Feature availability, permissions, and deployment versions can differ between tenants; each guide calls out relevant limits.


# Install

Start at [app.nullify.ai](https://app.nullify.ai/) and sign in with your work account. The address is `app.nullify.ai`, not `app.nullify.io`.

1. If you already belong to a workspace, sign-in opens it. Continue with onboarding or **Settings**.
2. If you see **No workspace yet**, your Microsoft account is not linked to a workspace yet. That screen does not mean you missed a setup step, and **Request workspace** does not claim a workspace Nullify has already prepared. Wait for the setup invitation from your Nullify representative.
3. Open the invitation link. Enter the verification code sent to the approved work email, continue with the same Microsoft work account, and finish the checks on that page. A new Azure DevOps workspace follows [Set up a new workspace](/enterprise-tier/azure-install#set-up-a-new-workspace). You do not create an app registration or send Nullify a directory ID.
4. After activation, the onboarding wizard opens. Connect your source-control provider, select repositories, and complete [setup](/getting-started/getting-started). Activating the workspace does not install Azure DevOps or start a scan.
5. If you see **Your workspace is being prepared**, the workspace exists but is awaiting provisioning. Your Nullify representative will reach out when it is ready; **Check workspace status** checks again.

Existing workspace members sign in and continue with their configured workspace. Contact your Nullify representative or <hello@nullify.ai> if the invitation expires or the verification email does not arrive.

{% hint style="info" %}
There is no `.nullify.yml` or other in-repo config file to add. Behaviour such as the CI/PR gate (fail-build, automated PR reviews), ticket-creation thresholds, SLA policies, finding allowlists, and notification targets is configured in the Nullify dashboard in **Settings** (or via the admin API), not by committing a file to your repository.
{% endhint %}


# Onboarding

Onboarding connects your code, identifies the repositories to review first, and gives Nullify the context it needs to prioritize findings. Start from the setup page after your workspace access exists. A new Azure DevOps workspace is opened with the [setup invitation](/enterprise-tier/azure-install#set-up-a-new-workspace), not the **Request workspace** button. The setup wizard uses the stages below; enabled integrations and features determine which optional steps and connectors appear. If a named optional step is absent, use the matching connector or API guide rather than treating its absence as proof that setup failed.

![Current onboarding welcome screen with sample progress](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-7b166df81c9311d7c3325071e2b93ff89510a788%2Fonboarding.png?alt=media)

Screenshots use sample data from the current dashboard; optional steps vary by tenant.

## Before you start

Have an administrator available to authorize source-control and workflow integrations. Decide which repositories belong in the first review, which cloud accounts are in scope, and who should receive security questions. For runtime testing, prepare a non-production target and dedicated test credentials; see [Preparing for an Engagement](/capabilities/pentests/preparing-for-an-engagement).

## Setup stages

| Stage                    | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Welcome                  | Review what setup will do and continue.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Codebases                | Connect GitHub, or GitLab.com or Azure DevOps when offered for your workspace. GitLab.com is authorized by an Owner of your top-level group. Azure Boards ticketing credentials alone do not connect source code. Self-managed GitLab and Bitbucket are installed through their enterprise guides.                                                                                                                                                                                                     |
| Repositories             | Search the repository inventory, review recommendations, and select the repositories for the first review. Installation access and enrollment are separate: an accessible repository is not necessarily selected for review. Repositories Nullify has not made available, or that are not shared with the Nullify GitHub App, are listed as unavailable and cannot be selected. Trial or tenant limits can cap the selection. Where offered, choose whether repositories added later are also scanned. |
| Workflow                 | Connect Slack for threat alerts and autofix PR notifications, and Jira, Linear, or Azure DevOps Boards to file findings. The same step offers the Nullify Atlassian app for Jira and Confluence, and DX for catalog and repository ownership where available. You can add other supported connectors later in settings.                                                                                                                                                                                |
| Builds                   | Connect Buildkite, or Jenkins where offered, so Nullify can check whether autofix pull requests pass CI and use build context.                                                                                                                                                                                                                                                                                                                                                                         |
| Cloud                    | Connect AWS, Google Cloud, Azure, or Kubernetes. Authorize only the accounts and clusters you intend Nullify to assess.                                                                                                                                                                                                                                                                                                                                                                                |
| Policy, when enabled     | Review remediation SLAs. See [Ticketing and SLAs](/configuration/configuration-ticketing).                                                                                                                                                                                                                                                                                                                                                                                                             |
| Assessment               | Add applications and test credentials for runtime testing, and use **Test sign-in** to check that each credential logs in. Allowlist the listed Nullify outgoing IP addresses on any firewall, WAF or IP allowlist in front of the targets. Adding a target does not itself authorize destructive testing.                                                                                                                                                                                             |
| Bug bounty, when enabled | Review program scope and rules of engagement. Confirm an imported program before saving it.                                                                                                                                                                                                                                                                                                                                                                                                            |
| Documents                | Upload policies, runbooks, threat models, past assessment reports, and architecture or ownership documents. See [supported file types](/capabilities/context-engine#memory-vault).                                                                                                                                                                                                                                                                                                                     |
| Your business            | Describe the company, what it does, its industries, the sensitive data it holds, the compliance regimes you care about, what a bad day would look like, and who might target you. Company name, business description and at least one industry are required.                                                                                                                                                                                                                                           |
| Finish                   | Review the connections, repositories, documents and business details, then submit setup. Source control, at least one selected repository and the required business details must be in place first; the step names whatever is missing.                                                                                                                                                                                                                                                                |

![Repository selection with sample repositories](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-60e9f8739090735482e02c18efd47cda72240590%2Frepositories.png?alt=media)

Submission starts the onboarding pipeline, or records your setup until our team starts your first review. In that case the setup page reads **Thanks — we have what we need** and you can close it. While the pipeline runs, the live setup workspace shows progress, completed work, and any steps needing attention. Closing the browser does not stop it. A partial or failed run is not a completed onboarding: use the displayed recovery action or contact Nullify. Access to the product also depends on your installation's approval and readiness state.

If your account lacks permission to change workspace settings or manage a connector, the wizard says so instead of saving; ask another administrator or contact <support@nullify.ai>.

## After setup

Review your [action items](/capabilities/working-with-nullify#action-items), verify ownership, and confirm the [PR gate](/configuration/configuration-pull-requests), ticketing, and notification settings before relying on automation.

Workspace sign-in is configured separately from repository access. Follow [Microsoft Entra SSO and SCIM](/configuration/account-and-teams/entra-sso-and-scim) for directory consent, member activation/linking, provisioning and safe Entra-only cutover. For Azure DevOps, complete the [installation checklist](/enterprise-tier/azure-install) and verify the first scan; a Microsoft sign-in or Azure Boards credential alone does not connect repositories.

Self-hosted service domains, where supported by your tenant's connector settings, tell credential validation which service endpoint to use. Enter your actual service hostname rather than assuming a cloud provider's public endpoint applies.

## Revising setup

Reopening onboarding lets you revise the setup, including connections, repository selection, and questionnaire answers. Review the summary before resubmitting; this can restart context-building work. Updated context informs subsequent processing, but does not guarantee that every previously reviewed finding is automatically re-triaged. Use the relevant finding's re-triage workflow when an existing decision needs reconsideration.


# Context Engine

## Overview

The Context Engine is the knowledge layer that every other Nullify capability reads from. It continuously builds a unified model of your environment — the code you ship, the cloud you run it on, the dependencies you pull in, and how all of it connects — so that detection, triage, and remediation can reason about real-world risk instead of isolated findings.

Where a scanner sees a single misconfiguration or vulnerable package, the Context Engine sees the application it belongs to, whether it is reachable from the internet, who owns it, and what data flows through it. That shared context is what lets Code Reviews, Cloud Audits, Pentests, and Security Program Management agree on what actually matters.

The Context Engine builds and serves five major bodies of context:

* **Asset Graph** — a unified, queryable graph of every cloud, cluster, repository, and application asset, with the relationships and reachability between them.
* **SBOM & Dependency Graph** — generated software bills of materials and a tenant-wide dependency graph with exposure windows.
* **Cloud Recon** — AI-driven reconnaissance of each cloud account: topology, IAM posture, network exposure, trust boundaries, and attack-path hotspots.
* **Dependency Exposure** — point-in-time and historical answers to "where is this package, at this version, deployed across my estate?".
* **Memory Vault** — durable agent memory plus a tenant document vault that grounds every agent in your organization's specifics.

## Asset Graph

The Asset Graph merges infrastructure and repository context into one connected model of your estate. Cloud accounts, Kubernetes clusters, repositories, and application groupings become nodes, and the relationships between them — deployment, network paths, ownership — become edges.

The graph powers the platform's asset explorer and is queryable end to end:

* **Landing & summary** give per-kind node counts and entry-point cards (cloud accounts, clusters, applications, repositories) for navigating the estate, plus presigned download URLs for the combined infrastructure and repo-context graphs.
* **Search & subgraph** let you find nodes by query string and extract a bounded subgraph around any starting node.
* **Reachability** computes whether a node is reachable from the internet by walking allowed edge types from a synthetic Internet node toward the target, returning the path(s) it found. When the graph is too large to fully enumerate, the result is explicitly marked as undetermined rather than falsely reporting "not reachable" — so consumers never mistake an incomplete search for a safe asset.

Reachability and ownership from the Asset Graph are what let other capabilities prioritize. A vulnerable dependency on an internet-facing service ranks above the same dependency buried in an internal batch job, because the graph knows the difference.

### Asset Inventory

On top of the graph, the Context Engine maintains a categorized **Asset Inventory** — a flat, filterable list of assets grouped into categories such as compute, container, cluster, serverless, network, connectivity, load balancer, CDN and DNS, storage and backup, database, messaging, data pipelines, identity, security, observability, CI/CD, pipelines, AI/ML, artifacts and artifact repositories, repositories, and projects. Each asset can carry tags and flags for routing and triage, and a dedicated public-asset view surfaces everything exposed to the internet.

{% hint style="info" %}
The Asset Graph is built automatically from your connected cloud accounts and repositories. There is nothing to configure per asset — connect a source and its assets flow into the inventory and graph. See the [connector guides](/connectors/aws) for setup.
{% endhint %}

## SBOM & Dependency Graph

The Context Engine generates software bills of materials (SBOMs) for enrolled, accessible repositories and their supported projects, then assembles them into a tenant-wide dependency graph. Verify scan completion and coverage; connecting an organization alone does not establish an SBOM for every repository.

SBOM generation runs a full pipeline — clone the repository, classify each project, and resolve its dependency tree. Projects with their own lockfile are resolved precisely; projects without a lockfile fall back to the repository or workspace root, and the engine tracks which projects were resolved without a lockfile so you can see where dependency resolution is least precise. SBOMs are stored per repository, project, and commit, and the engine returns the latest SBOM for a repository, a specific repository/project SBOM, or a get-or-generate result that produces one on demand.

From the assembled graph you can:

* Browse the SBOM **tree** for the whole tenant.
* Resolve dependencies **by BOM reference** and list everything that **depends on** a given component (its dependents / parent chains).
* See which projects and repositories were **resolved without a lockfile**.

Generated SBOMs are the substrate for Dependency Analysis and the dependency-exposure queries below, and they feed the supply-chain context that Pentests and Cloud Audits draw on. SBOMs for a repository are retrievable through the Context API (`GET /context/sboms`); SCA's dependency scan resolves the same SBOM rather than generating its own.

## Cloud Recon

Cloud Recon is the Context Engine's AI-driven reconnaissance of each connected cloud account. Nullify analyzes each account's infrastructure in parallel, then synthesizes the results — including cross-account IAM trust — into a single artifact per account and an organization-wide rollup.

For each account, Cloud Recon produces a structured synthesis covering:

* **Topology & overview** — the account's resource topology and a high-level summary.
* **Security boundaries & trusted services** — where the account's trust edges sit and which external services it trusts.
* **Network exposures** — internet-facing and over-broad network paths.
* **Traffic flows** — observed and inferred flows between resources.
* **IAM posture** — effective-permission resolution and privilege-escalation paths.
* **Cross-account relationships & tenant-wide trusts** — how accounts trust one another.
* **Hotspots** — a ranked list of attack-path concentrations.
* **Graph gaps** — places where the engine could not fully resolve the picture, surfaced honestly rather than hidden.

The latest synthesis is available per account and at the organization level, alongside the latest scan metadata. Cloud Recon enriches the Asset Graph and gives Cloud Audits the infrastructure understanding it needs to separate real risk from benign configuration variation.

## Dependency Exposure

When a new CVE drops or a malicious package is disclosed, the first question is "do we use it, and where?". Dependency Exposure answers that against the dependency graph, with version-aware and time-aware precision.

* **Active dependencies** lists what is currently active across every repository and project, with an aggregate summary including counts and the oldest active dependency.
* **Exposure by version** returns the exposure windows — across the whole tenant or scoped to one repository/project — that intersect a version filter expressed as a semver range or a content hash. This is the "who is running log4j between 2.0 and 2.14.1" query.
* **Exposure history** returns the windows over which a given package (by ecosystem and name) was present, so you can answer "how long were we exposed?".
* **Point-in-time and diff** queries return the active dependencies at a specific commit, or the dependency delta between two commits, for a repository/project.

Because exposure is computed from generated SBOMs and stored as windows over commit history, answers reflect not just the present state but the full timeline of when a component entered and left your estate.

## Memory Vault

The Memory Vault is two complementary stores that keep Nullify's agents grounded in your organization.

**Agent memory** is a first-class, versioned store of what the platform has learned about your environment — durable facts, decisions, and context that agents accumulate over time. Memories are typed, can be associated with documents, retain version history, and are searched with **hybrid semantic + lexical search** so an agent can recall the most relevant prior context for the task in front of it.

**The document vault** lets you upload organization-specific files — architecture notes, runbooks, security policies, and other context — that ground agents in how your organization actually operates. Upload them from the Documents step of [Onboarding](/getting-started/getting-started) or with **Add document** on the **Vault** page. Files are uploaded through presigned URLs, listed and retrieved on demand, and the onboarding run ingests them into the knowledge base so agents can draw on them during triage, planning, and remediation.

Nullify reads PDF, Word (`.docx`), RTF, plain text, Markdown, JSON, YAML, XML, CSV and images (PNG, JPG, GIF, WebP, SVG). Archives and Office files other than `.docx` (such as `.zip`, `.doc`, `.xls` and `.xlsx`) upload and stay downloadable, but are not read. The upload dialog names any file of another type and does not add it. Files can be up to 100 MB.

Together with the **organization context** — your classification, technology profile, and risk posture — the Memory Vault is how Nullify avoids generic, context-free advice. It is also part of the same knowledge model Pentests exploit and Security Program Management reasons over when assigning and sequencing work.

## How the Pieces Connect

The Context Engine is read by every detection and remediation capability:

* **Code Reviews** use repository context, ownership, and the dependency graph to prioritize and route findings.
* **Cloud Audits** use Cloud Recon and the Asset Graph to validate whether an infrastructure issue is a real risk in context.
* **Pentests** exploit the knowledge model — endpoints, reachability, and discovered credentials — to drive deep, application-aware testing.
* **Security Program Management** reads ownership, capacity, and organizational risk to assign the right work to the right people.

## API Access

The Context Engine's model is queryable for automation and reporting. Endpoints live under the `/context/*` namespace (with asset-graph queries at `/context/asset-graph/*` and infrastructure graphs at `/context/infrastructure/*`). Representative endpoints:

| Area                | Endpoint                                                         | Purpose                                                    |
| ------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
| Asset Graph         | `GET /context/asset-graph/summary`                               | Unified summary of infrastructure and repo-context graphs. |
| Asset Graph         | `GET /context/asset-graph/reachability`                          | Compute whether a node is reachable from the internet.     |
| Asset Inventory     | `GET /context/asset-inventory/public`                            | List every asset exposed to the internet.                  |
| SBOM                | `GET /context/sboms/repository/{repositoryId}/latest`            | Latest SBOMs for a repository.                             |
| SBOM                | `GET /context/sboms/tree`                                        | Tenant-wide SBOM tree.                                     |
| Cloud Recon         | `GET /context/cloud-recon/accounts/{accountId}/synthesis/latest` | Full reconnaissance synthesis for an account.              |
| Dependency Exposure | `GET /context/deps/exposure`                                     | Tenant-wide package exposure by semver or hash.            |
| Dependency Exposure | `GET /context/deps/active`                                       | Active dependencies across all repositories/projects.      |
| Memory Vault        | `POST /context/memories/search`                                  | Hybrid semantic + lexical search over agent memory.        |
| Memory Vault        | `GET /context/vault/files`                                       | List uploaded organization documents.                      |
| Applications        | `GET /context/applications`                                      | The catalog of applications and their context.             |

All requests use a service-account token. See the [API Reference](/api-reference/api-reference) and the full [OpenAPI specification](/api-reference/api-reference/openapi-spec) for the complete contract.

## Configuration

The Context Engine builds itself from your connected sources — there is nothing to enable per asset. Connect your repositories and cloud accounts during [Onboarding](/getting-started/getting-started), and the asset graph, SBOMs, cloud recon, and dependency graph populate automatically as scans run. See the connector guides for setup: [AWS](/connectors/aws), [GCP](/connectors/gcp).

## Applications, schemas, and review scope

Applications group related repositories and projects. You can create, edit, delete, or rebuild those groupings and retrieve a merged application schema. Schema extraction can reverse an OpenAPI description from discovered entrypoints; an extracted schema should still be checked against the deployed target before a pentest.

Repository-scope analysis classifies criticality and coverage and recommends a covering set of repositories for review. Repository-context scan records retain the run status and extraction outputs, so you can distinguish “no context discovered” from “extraction has not completed.”

## Asset relationships and reports

Entrypoints, artifacts, deployments, and CI/CD pipelines are first-class inventory resources. Persisted attack paths capture discovered relationships, while reachability queries assess connectivity using available topology. Neither substitutes for missing collection permissions.

The report workflow produces asynchronous PDF outputs such as dependency/SBOM reports: create a report, poll its job, then download the completed artifact. Vault onboarding extracts organizational facts such as domains, policies, and team structure. The compliance regimes you choose in the onboarding questionnaire are carried into the organization context whether or not you upload documents. Search-index resync can recover missing or stale embeddings without asking you to upload the same document again.

See the [Context API](/api-reference/api-reference/context) for application/schema operations, inventory, repo-scope scans, run history, reports, and vault recovery.


# Code Reviews

## Overview

Nullify reviews code across three layers: application-code vulnerabilities, dependency vulnerabilities, and leaked secrets. Application-code and dependency review run on pull requests and on the default branch, while secrets are checked on every commit across every branch — keeping security issues from reaching production.

## Scanning Scope

### Application Code Analysis

* **Pull Requests**: Reviews PRs targeting the default branch
  * Reviews the changed code in the diff
  * Posts inline review comments on findings
  * Reports a **Nullify** check whose pass/fail is [configurable](/configuration/configuration-pull-requests) — informational by default, or a required gate on net-new findings
* **Default Branch Commits**: Reviews all commits pushed to the default branch
  * Full repository review on every push
  * Updates the dashboard with the complete inventory
  * Creates tickets and notifications for new findings
* **Other Branches**: Not reviewed for code vulnerabilities

### Dependency Analysis

* **Pull Requests**: Reviews dependency changes in PRs targeting the default branch
  * Reviews changed manifest and lock files (`package.json`, `pom.xml`, `Cargo.toml`, etc.)
  * Contributes to the same tenant-configurable **Nullify** check gate
  * Identifies both direct and transitive dependencies
* **Default Branch Commits**: Full dependency review on every push
  * Analyzes all package manifest and lock files
  * Updates the dashboard with the complete vulnerability inventory
  * Drafts autofix PRs for upgradeable dependencies
* **Container Images**: Reviews container images for vulnerable packages

### Secrets Detection

* **Pushes and Pull Requests**: A standalone scan inspects the event's commits
  * Diff-scoped review
  * Notifies the commit author when secrets are found
  * Actively verifies detected credentials
  * Reports newly committed secrets so they can be revoked and removed
* **Repository Inventory**: An initial full-history scan establishes the inventory. After a full-history scan has completed, later inventory scans can use shallow HEAD snapshots
  * Updates the dashboard with a repository-wide secret inventory

## What Nullify covers

* **Languages & frameworks** — a wide range of languages plus infrastructure-as-code. See [Supported Languages](/capabilities/code-reviews/code-analysis/supported-languages).
* **Dependency ecosystems** — npm, Maven, Go, PyPI, Cargo, and more, with reachability on supported languages. See [Supported Ecosystems](/capabilities/code-reviews/dependency-analysis/supported-ecosystems).
* **Weakness classes** — OWASP Top 10 and CWE Top 25 vulnerability classes, plus compound attack paths. See [Supported Weaknesses](/capabilities/code-reviews/code-analysis/supported-weaknesses).

## Reachability & Exploitability Analysis

Nullify doesn't just report what a scanner matched — it reasons about whether a finding actually matters.

### Code Analysis

* AI-driven triage analyzes how code is used in context.
* Screens out false positives before they reach you.
* Severity reflects exploitability, not just theoretical risk.

### Dependency Analysis

* **Direct vs. Transitive**: marks whether the vulnerability is in a direct dependency.
* **Reachability Analysis**: on supported languages, traces whether a vulnerable package is actually reached by your code.
* Transitive and unreachable vulnerabilities are prioritized lower by default.

### Secrets Verification

* **Active validation**: checks discovered credentials against the real provider.
* Tests API keys against actual services and validates token formats and expiration.
* Not just pattern matching — functional testing. See [Secrets Detection](/capabilities/code-reviews/secrets-detection).

Findings from all three layers are [triaged](/capabilities/triage) together, then routed and remediated through [Security Program Management](/capabilities/program-management) and [Remediations](/capabilities/remediations).


# Code Analysis

## Overview

Nullify analyzes first-party application code and infrastructure to find vulnerabilities before they reach production. It reviews every commit on your default branch and every pull request to catch issues early.

Nullify uses both top-down and bottom-up analysis to expose vulnerabilities:

* **Top-down analysis** traces user input (HTTP requests, API calls, file uploads) through your application logic to identify unsafe data flows
* **Bottom-up analysis** works backward from vulnerable operations (SQL queries, OS commands, serialization) to determine if untrusted data can reach them

This dual approach catches injection flaws, authentication bypasses, authorization failures, business logic bugs, and other code-level vulnerabilities that static patterns alone would miss.

Nullify also scans infrastructure-as-code (Terraform, CloudFormation, Kubernetes manifests, etc.) for misconfigurations that expose services, weaken access controls, or introduce compliance violations.

## Coverage

**Application Code**

* Injection flaws (SQL, NoSQL, command, LDAP, XPath, template)
* Authentication and authorization failures
* Broken access control (IDOR, privilege escalation)
* Business logic flaws (race conditions, workflow bypass, price manipulation)
* Unsafe deserialization
* SSRF and XXE vulnerabilities
* Sensitive data exposure and logging

**Infrastructure-as-Code**

* Exposed services and overly permissive network rules
* Weak IAM policies and overprivileged roles
* Misconfigured secrets management
* Compliance violations (encryption, retention, logging)

## Coverage references

Use [Supported Languages](/capabilities/code-reviews/code-analysis/supported-languages) for language and configuration formats and [Supported Weaknesses](/capabilities/code-reviews/code-analysis/supported-weaknesses) for common examples and the rule-backed CWE catalog. Static results can be enriched with code and cloud context; a CWE match is not proof of a successful runtime exploit.


# Supported Languages

## Application Languages

Nullify reviews code in the languages below. Where a finding can be safely patched, Nullify drafts an [autofix](/capabilities/remediations) pull request for it; autofix eligibility depends on the specific finding and its context, not on the language.

| Language   | Coverage Highlights                                                                |
| ---------- | ---------------------------------------------------------------------------------- |
| C          | Buffer and memory-safety issues with contextual call-tree analysis.                |
| C++        | Includes modern C++ (17/20) with templated sinks.                                  |
| C#         | ASP.NET MVC and API patterns.                                                      |
| Go         | SQL injection, SSRF, auth bypass, and command injection.                           |
| Java       | Spring/Spring Boot, Jakarta EE, and servlet stacks with dataflow reasoning.        |
| JavaScript | Node.js backends, Express, Next.js, and browser contexts.                          |
| TypeScript | Shares the JavaScript analysis engine.                                             |
| Kotlin     | JVM and Android server-side use cases.                                             |
| PHP        | Laravel, Symfony, and raw PHP entry points with sink-driven reasoning.             |
| Python     | Django, Flask, FastAPI, and data pipelines with reachability checks.               |
| Ruby       | Rails and Sinatra patterns, including mass-assignment and CSRF.                    |
| Rust       | Memory-safety, unsafe-block, and web-framework (Axum, Actix) analysis.             |
| Scala      | Play and Akka HTTP services.                                                       |
| Solidity   | Smart-contract checks (reentrancy, access control, unchecked calls).               |
| Bash       | Shell-command construction and unsafe scripting patterns.                          |
| Clojure    | Dedicated rules for supported Clojure patterns.                                    |
| OCaml      | Dedicated rules for supported OCaml patterns.                                      |
| HTML       | Browser and template security patterns, including embedded client-side JavaScript. |
| Apex       | Salesforce Apex SOQL injection, CRUD/FLS, and sharing-violation analysis.          |
| Swift      | iOS and server-side Swift entry points with sink-driven reasoning.                 |

## Infrastructure & Build Definitions

| Format                         | Assessment Coverage | Notes                                                                                      |
| ------------------------------ | ------------------- | ------------------------------------------------------------------------------------------ |
| Terraform (HCL)                | Yes                 | AWS S3, IAM, VPC, EKS, and encryption policies with blast-radius analysis.                 |
| AWS CloudFormation (YAML/JSON) | Yes                 | Reviews stack defaults, logging, encryption, and network exposure controls.                |
| Terraform (Azure)              | Yes                 | Focus on AKS, public ingress, identity, and storage hardening.                             |
| Kubernetes Manifests           | Yes                 | Detects run-as-root, privilege escalation, network policy drift, and missing telemetry.    |
| Container build files          | Yes                 | Covers `Dockerfile`/`Containerfile` hardening, multistage hygiene, and base image posture. |

Infrastructure findings link back to cloud context collected through the AWS connector so teams immediately understand affected accounts and services.

## Additional configuration coverage

| Format              | Scope                                                                    |
| ------------------- | ------------------------------------------------------------------------ |
| Terraform for GCP   | Google Cloud resource configuration, IAM, storage, and network controls. |
| GitHub Actions YAML | Workflow permissions, untrusted inputs, and unsafe execution patterns.   |
| Ansible YAML        | Security-sensitive automation and configuration.                         |
| Docker Compose YAML | Container privileges and service configuration.                          |
| OpenAPI YAML        | Security-relevant API specification patterns.                            |
| AWS IAM JSON        | Standalone IAM policy checks.                                            |
| Snowflake SQL       | Narrow SQL masking-policy checks through generic rules.                  |

Coverage is rule- and framework-specific. A supported file format does not imply every feature of that language or cloud service is analyzed. Azure infrastructure coverage here is Terraform, not a dedicated Bicep ruleset. Runtime cloud posture is covered separately by [Cloud Audits](/capabilities/cloud-audits).


# Supported Weaknesses

## Application CWE Coverage

| CWE     | Weakness                          | Coverage Highlights                                                                                                              |
| ------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| CWE-20  | Improper Input Validation         | Identifies missing validation, untrusted deserialisation, and unsafe type coercion before data reaches sensitive sinks.          |
| CWE-22  | Path Traversal                    | Tracks file-system access from HTTP handlers, CLIs, and background jobs to prevent arbitrary file reads and writes.              |
| CWE-77  | Command Injection                 | Detects unsanitised command construction in shell runners, build tooling, and deployment scripts.                                |
| CWE-78  | OS Command Injection              | Finds user-controlled data reaching operating system calls (for example `exec`, `Runtime.exec`, `subprocess`, `ProcessBuilder`). |
| CWE-79  | Cross-Site Scripting (XSS)        | Covers reflected and stored variants across templating engines and SPA frameworks.                                               |
| CWE-89  | SQL Injection                     | Supports ORM and raw-query patterns in Go, Java, JavaScript/TypeScript, Ruby, PHP, Python, and Scala.                            |
| CWE-94  | Code Injection                    | Flags dynamic evaluation, template injection, and remote code download scenarios.                                                |
| CWE-269 | Improper Privilege Management     | Verifies authorisation guards, middleware ordering, and access control annotations.                                              |
| CWE-287 | Improper Authentication           | Detects missing authentication, weak session handling, and uncontrolled login backdoors.                                         |
| CWE-352 | Cross-Site Request Forgery        | Validates CSRF mitigations for web, API, and mobile backend endpoints.                                                           |
| CWE-434 | Unrestricted File Upload          | Ensures upload handlers enforce type, size, and storage-location controls.                                                       |
| CWE-502 | Deserialisation of Untrusted Data | Flags unsafe use of native, JSON, XML, and binary deserialisers across languages.                                                |
| CWE-798 | Hard-coded Credentials            | Surfaces embedded secrets in application code alongside Secrets Detection detections.                                            |
| CWE-918 | Server-Side Request Forgery       | Detects pivot chains that reach cloud metadata services, internal control planes, or partner APIs.                               |

## Compound Attack Paths

Beyond single-CWE detections, Nullify correlates findings across layers to surface chained, real-world attack paths:

* **Cloud-to-code pivots** — links an infrastructure-as-code misconfiguration to the vulnerable application route it exposes, so an internet-facing service with a reachable injection flaw is prioritized over the same flaw buried in an internal job.
* **Network reachability** — reasons over VPC, security-group, NACL, and gateway configuration to determine whether a vulnerable asset is actually reachable from the internet, feeding Cloud Audit prioritization.
* **Container and build hardening** — catches Dockerfile and container-image misuse, image-provenance gaps, and privilege-escalation vectors. Runtime API exploration and authenticated exploit testing belong to [Bug Hunts](/capabilities/bug-hunts) and [Pentests](/capabilities/pentests), not to the static rules listed on this page.

## Rule-backed CWE catalog

The bundled static rules carry the following CWE mappings. A mapping indicates a rule exists for that weakness; it does not promise detection of every instance, language, or exploit variant. The examples above explain common classes.

| CWE      | Rule metadata label                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| CWE-20   | Improper Input Validation                                                                                              |
| CWE-22   | Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')                                         |
| CWE-74   | Improper Neutralization of Special Elements in Output Used by a Downstream Component ('Injection')                     |
| CWE-77   | Improper Neutralization of Special Elements used in a Command ('Command Injection')                                    |
| CWE-78   | Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')                             |
| CWE-79   | Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')                                   |
| CWE-88   | Improper Neutralization of Argument Delimiters in a Command ('Argument Injection')                                     |
| CWE-89   | Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')                                   |
| CWE-91   | XML Injection (aka Blind XPath Injection)                                                                              |
| CWE-94   | Improper Control of Generation of Code ('Code Injection')                                                              |
| CWE-116  | Improper Encoding or Escaping of Output                                                                                |
| CWE-119  | Improper Restriction of Operations within the Bounds of a Memory Buffer                                                |
| CWE-120  | Buffer Copy without Checking Size of Input ('Classic Buffer Overflow')                                                 |
| CWE-125  | Out-of-bounds Read                                                                                                     |
| CWE-129  | Improper Validation of Array Index                                                                                     |
| CWE-134  | Use of Externally-Controlled Format String                                                                             |
| CWE-190  | Integer Overflow or Wraparound                                                                                         |
| CWE-193  | Off-by-one Error                                                                                                       |
| CWE-200  | Exposure of Sensitive Information to an Unauthorized Actor                                                             |
| CWE-203  | Observable Discrepancy                                                                                                 |
| CWE-209  | Generation of Error Message Containing Sensitive Information                                                           |
| CWE-252  | Unchecked Return Value                                                                                                 |
| CWE-269  | Improper Privilege Management                                                                                          |
| CWE-276  | Incorrect Default Permissions                                                                                          |
| CWE-287  | Improper Authentication                                                                                                |
| CWE-290  | Authentication Bypass by Spoofing                                                                                      |
| CWE-294  | Authentication Bypass by Capture-replay                                                                                |
| CWE-295  | Improper Certificate Validation                                                                                        |
| CWE-306  | Missing Authentication for Critical Function                                                                           |
| CWE-307  | Improper Restriction of Excessive Authentication Attempts                                                              |
| CWE-311  | Missing Encryption of Sensitive Data                                                                                   |
| CWE-312  | Cleartext Storage of Sensitive Information                                                                             |
| CWE-319  | Cleartext Transmission of Sensitive Information                                                                        |
| CWE-326  | Inadequate Encryption Strength                                                                                         |
| CWE-327  | Use of a Broken or Risky Cryptographic Algorithm                                                                       |
| CWE-330  | Use of Insufficiently Random Values                                                                                    |
| CWE-335  | Incorrect Usage of Seeds in Pseudo-Random Number Generator (PRNG)                                                      |
| CWE-338  | Use of Cryptographically Weak Pseudo-Random Number Generator (PRNG)                                                    |
| CWE-345  | Insufficient Verification of Data Authenticity                                                                         |
| CWE-346  | Origin Validation Error                                                                                                |
| CWE-347  | Improper Verification of Cryptographic Signature                                                                       |
| CWE-352  | Cross-Site Request Forgery (CSRF)                                                                                      |
| CWE-354  | Improper Validation of Integrity Check Value                                                                           |
| CWE-362  | Concurrent Execution using Shared Resource with Improper Synchronization ('Race Condition')                            |
| CWE-367  | Time-of-check Time-of-use (TOCTOU) Race Condition                                                                      |
| CWE-369  | Divide By Zero                                                                                                         |
| CWE-384  | Session Fixation                                                                                                       |
| CWE-400  | Uncontrolled Resource Consumption                                                                                      |
| CWE-401  | Missing Release of Memory after Effective Lifetime                                                                     |
| CWE-404  | Improper Resource Shutdown or Release                                                                                  |
| CWE-407  | Inefficient Algorithmic Complexity                                                                                     |
| CWE-415  | Double Free                                                                                                            |
| CWE-416  | Use After Free                                                                                                         |
| CWE-427  | Uncontrolled Search Path Element                                                                                       |
| CWE-434  | Unrestricted Upload of File with Dangerous Type                                                                        |
| CWE-436  | Interpretation Conflict                                                                                                |
| CWE-444  | Inconsistent Interpretation of HTTP Requests ('HTTP Request/Response Smuggling')                                       |
| CWE-470  | Use of Externally-Controlled Input to Select Classes or Code ('Unsafe Reflection')                                     |
| CWE-476  | NULL Pointer Dereference                                                                                               |
| CWE-494  | Download of Code Without Integrity Check                                                                               |
| CWE-502  | Deserialization of Untrusted Data                                                                                      |
| CWE-521  | Weak Password Requirements                                                                                             |
| CWE-522  | Insufficiently Protected Credentials                                                                                   |
| CWE-532  | Insertion of Sensitive Information into Log File                                                                       |
| CWE-552  | Files or Directories Accessible to External Parties                                                                    |
| CWE-565  | Reliance on Cookies without Validation and Integrity Checking                                                          |
| CWE-601  | URL Redirection to Untrusted Site ('Open Redirect')                                                                    |
| CWE-610  | Externally Controlled Reference to a Resource in Another Sphere                                                        |
| CWE-611  | Improper Restriction of XML External Entity Reference                                                                  |
| CWE-613  | Insufficient Session Expiration                                                                                        |
| CWE-639  | Authorization Bypass Through User-Controlled Key                                                                       |
| CWE-665  | Improper Initialization                                                                                                |
| CWE-668  | Exposure of Resource to Wrong Sphere                                                                                   |
| CWE-669  | Incorrect Resource Transfer Between Spheres                                                                            |
| CWE-672  | Operation on a Resource after Expiration or Release                                                                    |
| CWE-674  | Uncontrolled Recursion                                                                                                 |
| CWE-681  | Incorrect Conversion between Numeric Types                                                                             |
| CWE-682  | Incorrect Calculation                                                                                                  |
| CWE-697  | Incorrect Comparison                                                                                                   |
| CWE-704  | Incorrect Type Conversion or Cast                                                                                      |
| CWE-706  | Use of Incorrectly-Resolved Name or Reference                                                                          |
| CWE-732  | Incorrect Permission Assignment for Critical Resource                                                                  |
| CWE-754  | Improper Check for Unusual or Exceptional Conditions                                                                   |
| CWE-755  | Improper Handling of Exceptional Conditions                                                                            |
| CWE-770  | Allocation of Resources Without Limits or Throttling                                                                   |
| CWE-776  | Improper Restriction of Recursive Entity References in DTDs ('XML Entity Expansion')                                   |
| CWE-787  | Out-of-bounds Write                                                                                                    |
| CWE-798  | Use of Hard-coded Credentials                                                                                          |
| CWE-829  | Inclusion of Functionality from Untrusted Control Sphere                                                               |
| CWE-843  | Access of Resource Using Incompatible Type ('Type Confusion')                                                          |
| CWE-862  | Missing Authorization                                                                                                  |
| CWE-863  | Incorrect Authorization                                                                                                |
| CWE-908  | Use of Uninitialized Resource                                                                                          |
| CWE-913  | Improper Control of Dynamically-Managed Code Resources                                                                 |
| CWE-916  | Use of Password Hash With Insufficient Computational Effort                                                            |
| CWE-917  | Improper Neutralization of Special Elements used in an Expression Language Statement ('Expression Language Injection') |
| CWE-918  | Server-Side Request Forgery (SSRF)                                                                                     |
| CWE-922  | Insecure Storage of Sensitive Information                                                                              |
| CWE-1021 | Improper Restriction of Rendered UI Layers or Frames                                                                   |
| CWE-1188 | Initialization of a Resource with an Insecure Default                                                                  |
| CWE-1236 | Improper Neutralization of Formula Elements in a CSV File                                                              |
| CWE-1321 | Improperly Controlled Modification of Object Prototype Attributes ('Prototype Pollution')                              |
| CWE-1333 | Inefficient Regular Expression Complexity                                                                              |


# Dependency Analysis

## Overview

Nullify continuously monitors every package dependency for known CVEs and determines how risky they are within the context of your application and where it runs. It reviews all packages on your default branch periodically to catch new CVEs as they emerge, and analyzes every pull request to prevent new CVEs from being introduced. This combines vulnerability detection with application context to separate noise from genuine risk.

## What It Delivers

* **Manifest discovery** across `go.mod`, `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `pom.xml`, `build.gradle`, `libs.versions.toml`, `requirements.txt`, `pyproject.toml`, `conda-lock.yml`, `Gemfile`, `.csproj`, `composer.json`, `Cargo.toml`, and more.
* **Enriched advisories** that blend NVD, OSV, CISA Known Exploited Vulnerabilities (KEV), FIRST EPSS exploit-probability scores, vendor feeds, and Nullify intelligence to calculate severity, exploitability, and affected services.
* **Reachability reasoning** analyzes how your programs use the vulnerable code in the dependency, not just whether it is called, and how exposed it is in the infrastructure.
* **Comprehensive triage** compute a risk score comprised of technical and business context
* **Automated remediation** for Go modules, npm/pnpm, Maven, Gradle, PyPI, Poetry, Composer, RubyGems/Bundler, and NuGet with changelog summaries and optional PR creation.

See [Supported Ecosystems](/capabilities/code-reviews/dependency-analysis/supported-ecosystems) for per-package manifest details and for the agent-drafted autofix tiers that cover every other ecosystem (Bun, Cargo, uv, uv-managed PyPI, Conda, Yarn, Pipenv, Swift PM, Dart/Flutter, and Elixir Mix).

## Scanners and package intelligence

The local dependency scan combines Trivy filesystem vulnerability results with OSV Scanner results and deduplicates them. GitHub Actions workflow references are also dependency inputs and are checked in the GitHub Actions ecosystem. Workflow dependency detection does not imply an SCA autofix exists for those references.

Malicious-package intelligence is distinct from a CVE: a match against the OpenSSF malicious-package feed can produce a malicious verdict without a vulnerability advisory. Missing advisory, KEV, or EPSS data is not proof a package is safe.

For dependencies hosted outside public registries, configure a [private package registry](/connectors/package-registries) with the credentials and scope required to resolve its metadata.

## Container images

Container scanning inventories image packages with Syft and checks vulnerabilities with Grype. Findings are exposed separately from source dependency findings, with image/package context, triage, tickets, and scan activity. A base-image upgrade can be proposed through container autofix when the affected image maps to a supported repository change; review the resulting build and application tests before merging.

See the [Dependency Analysis API](/api-reference/api-reference/dependency-analysis) for container findings, triage, and autofix polling. Container package presence and source-code reachability are different signals.

## Related

* [Threat Intelligence](/capabilities/threat-intelligence): newly disclosed vulnerabilities and supply-chain compromises assessed against your whole environment, not only the next scan.


# Supported Ecosystems

## Overview

Nullify discovers manifests automatically and keeps the following ecosystems up to date. “Autofix” indicates whether Nullify can draft upgrade pull requests for that manifest, and how: **Yes** first attempts an update through GitHub's Dependabot updater, with an AI-agent fallback for eligible failures; **Agent (verified)** drafts through Nullify's AI agent, which regenerates and verifies the lockfile with the ecosystem's own toolchain in a sandbox; **Agent (manifest edit)** drafts through the same agent but edits the manifest without an in-sandbox lockfile verification step. “Reachability” shows where we trace exploit paths through application code before alerting.

| Ecosystem         | Manifest Files                                                  | Autofix Support       | Reachability |
| ----------------- | --------------------------------------------------------------- | --------------------- | ------------ |
| Bun               | `bun.lock`                                                      | Agent (verified)      | No           |
| Cargo (Rust)      | `Cargo.toml`, `Cargo.lock`                                      | Agent (verified)      | Yes          |
| Composer (PHP)    | `composer.json`, `composer.lock`                                | Yes                   | No           |
| Go Modules        | `go.mod`, `go.sum`                                              | Yes                   | Yes          |
| Gradle            | `build.gradle`, `gradle.lockfile`, `libs.versions.toml`         | Yes                   | Yes          |
| Maven             | `pom.xml`                                                       | Yes                   | Yes          |
| npm / pnpm        | `package.json`, `package-lock.json`, `pnpm-lock.yaml`           | Yes                   | Yes          |
| Yarn              | `yarn.lock`                                                     | Yes                   | Yes          |
| NuGet (.NET)      | `.csproj`, `deps.json`, `packages.config`, `packages.lock.json` | Yes                   | No           |
| Pipenv            | `Pipfile`, `Pipfile.lock`                                       | Yes                   | Yes          |
| Poetry            | `poetry.lock`                                                   | Yes                   | Yes          |
| PyPI              | `requirements.txt`                                              | Yes                   | Yes          |
| PyPI (uv-managed) | `pyproject.toml`                                                | Yes                   | Yes          |
| Conda             | `environment.yml`, `conda-lock.yml`                             | Yes                   | No           |
| RubyGems          | `Gemfile`, `Gemfile.lock`                                       | Yes                   | Yes          |
| uv                | `uv.lock`                                                       | Yes                   | Yes          |
| Swift PM          | `Package.swift`, `Package.resolved`                             | Agent (manifest edit) | No           |
| Dart / Flutter    | `pubspec.yaml`, `pubspec.lock`                                  | Agent (manifest edit) | No           |
| Elixir (Mix)      | `mix.exs`, `mix.lock`                                           | Agent (manifest edit) | No           |

## Interpreting reachability

“Yes” means the manifest maps to a source-analysis ecosystem in the dependency pipeline. It is not a guarantee that a particular vulnerable function can be resolved: missing source, incomplete dependency context, or dynamic loading can leave a finding's reachability unknown. Yarn shares the Node.js pass; Gradle shares the Java pass; Poetry, Pipenv, and uv share the Python pass. Cargo and RubyGems have Rust and Ruby passes. Conda manifests do not select one of these passes.

GitHub Actions (`.github/workflows/*.yml` or `*.yaml`) are scanned as workflow dependencies. They have no SCA autofix or source-reachability pass. Container images have a separate scanning and remediation workflow described in [Dependency Analysis](/capabilities/code-reviews/dependency-analysis#container-images).


# Secrets Detection

## Overview

Nullify prevents credential leaks and sensitive data exposure from entering your repositories as a core part of Code Review. It identifies hardcoded credentials and sensitive data that should never be in version control, then validates whether those credentials are actually live and exploitable. This combines deterministic pattern matching with NLP-based detectors and real-world validation—catching not just secrets that look dangerous, but secrets that pose an actual risk.

## Detection Highlights

* **Cloud & infrastructure keys** — AWS access keys, Azure service-principal credentials, GCP API keys and service-account JSON keys, IBM COS, HashiCorp Terraform passwords, DigitalOcean and SoftLayer credentials.
* **Developer tooling** — GitHub personal access tokens, npm/yarn tokens, Slack webhooks, SendGrid API keys, Stripe, Square, Artifactory, Docker Hub, and more.
* **Authentication artefacts** — OAuth client secrets, JWTs, basic-auth credentials, and session identifiers.
* **Sensitive data** — Email addresses, phone numbers, addresses, dates of birth, US Social Security Numbers, and payment card details in English-language datasets. Available to enterprise tenants on request — see [Confidential Data Detection](/capabilities/code-reviews/secrets-detection/confidential-data-detection).

Credential findings include ownership and remediation guidance where available. Rotate or revoke a leaked credential at its provider; removing it from a commit or allowlisting it does not revoke access. Sensitive-data findings follow a separate exposure-remediation workflow.

## Live credential verification

A leaked secret that's already been rotated is noise; a leaked secret that still works is an incident. Nullify tells them apart. When it finds a credential, it checks it against the real provider — across a broad set of services including AWS, GCP, Azure, GitHub and GitLab tokens, Stripe, Slack, and many more — to determine whether it's still live, and captures evidence of what the credential can access. A verified-live secret is prioritized and escalated ahead of one that no longer works, so the most urgent leaks reach the right owner first. This is functional testing, not just pattern matching.

## Beyond cloud tokens

Coverage includes AI-provider keys, package-publishing credentials, CI tokens, and private cryptographic keys. See [Supported Secret Categories](/capabilities/code-reviews/secrets-detection/supported-secret-categories) for the distinction between live-verifiable credentials, provider patterns, and structural key classification.

## After a leak

Revoke or rotate a leaked credential at its issuing provider, then update affected applications. Removing a secret from source or suppressing its finding does not revoke the credential. Nullify's live-verification capability does not establish scheduled re-verification, automatic revocation, or a vault-management workflow.


# Supported Secret Categories

Detection, structural classification, and live verification are different stages. A provider pattern can identify a likely credential without a supported online verifier. Verification can also be inconclusive when a service is unreachable or required account context is missing.

| Category                         | Examples with live-verification tools                                                                                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloud and infrastructure         | AWS access-key pairs; Google Cloud API keys and service-account JSON keys; Azure service-principal client credentials; DigitalOcean, IBM Cloud, Heroku, Terraform Cloud, Vault, Pulumi, Vercel, Netlify, Firebase, Supabase. |
| Source control, CI, and packages | GitHub and GitLab tokens; npm, PyPI, RubyGems, CircleCI, Travis CI, Docker Hub, and Bitbucket credentials.                                                                                                                   |
| AI and model platforms           | OpenAI, Hugging Face, and Fireworks tokens.                                                                                                                                                                                  |
| Observability and data           | Datadog, Databricks, Dynatrace, Sentry, Splunk, Elasticsearch, New Relic, LaunchDarkly, Mapbox, and Algolia.                                                                                                                 |
| Identity and collaboration       | Okta, Notion, Dropbox, Postman, Slack, Discord, Telegram, Facebook, Airtable, Atlassian, Linear, and Zendesk.                                                                                                                |
| Commerce and communications      | Stripe, Square, Shopify, HubSpot, SendGrid, Mailchimp, Twilio, PagerDuty, Cloudflare, and Braintree.                                                                                                                         |

These examples describe supported verifier types, not a promise that every alert will make an online request. Required hostnames, tenant IDs, paired secrets, scopes, and provider responses determine what can be verified. Azure service-principal verification uses an OAuth client-credentials exchange; it is not a general verifier for every Storage SAS token.

## Pattern-detected credentials

Provider-specific patterns also recognize Anthropic, DeepSeek, Gemini, Groq, OpenRouter, xAI, and Replicate keys. Generic API keys, basic-auth strings, bearer tokens, and signing secrets are assessed using their format and surrounding code. Do not interpret “detected” as “confirmed live.”

## Cryptographic material

Nullify distinguishes PEM and SSH private keys from public keys, certificates, and password hashes. A structurally valid private key can be sensitive even without an API endpoint against which to verify it. A public certificate or public key is not automatically a leaked credential, and a password hash is not an API token. Triage uses the material's role and context rather than inventing provider access from its shape.

## Personal and sensitive data

Email addresses, phone numbers, postal addresses, dates of birth, US Social Security Numbers, and payment-card details are covered by [Confidential Data Detection](/capabilities/code-reviews/secrets-detection/confidential-data-detection), when enabled. These findings require exposure remediation rather than credential rotation.

Contact Nullify for a provider or credential format not listed here.


# Confidential Data Detection

When enabled, Nullify inspects diffs for sensitive personal information that should not live in source control. Findings appear in the dashboard with the relevant PII category and remediation guidance. Remove the exposed data and assess downstream copies and access; credential rotation is not a remedy for personal-data exposure.

## Categories We Classify

* Personal information: email addresses, phone numbers, postal addresses, dates of birth, and US Social Security Numbers.
* Financial information: payment card numbers.
* Location and identity data sourced from structured dumps or seed files.

All detections currently focus on English-language datasets.

## Example Workflow

1. A developer commits a seed file containing realistic user records (`create.sql`).
2. Nullify analyses the diff, labels the exposure as **Personal Information**, and posts the finding to the dashboard.
3. The reviewer can remediate, suppress with justification, or convert the event into a campaign task.

![Sample SQL seed file](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-9ea5344b34878a13da262e0236651bf6688e3fc0%2Fpii-sql-example.png?alt=media) Review detected data in the current **Findings** view, scoped to the sensitive-data category. The SQL image is an illustrative input, not a screenshot of the current dashboard.

> 💡 PII detection is available to enterprise tenants on request. Contact your Nullify representative to enable it for your environment.


# Cloud Audits

## Overview

Nullify audits your cloud infrastructure on a schedule you control — daily by default — to detect security weaknesses and misconfigurations. It understands the business context of each workload—what data it processes, who accesses it, and where it runs—then validates whether infrastructure issues pose a real risk through configuration and contextual analysis. This context-driven approach separates genuine security issues from harmless configuration variations.

## How It Works

1. **Cloud Resource Inventory**: Nullify's context engine inventories your cloud accounts
2. **Scheduled Trigger**: Once the inventory stage completes, Cloud Audits runs against that fresh picture, on your tenant's cadence
3. **Infrastructure Analysis**: All resources are evaluated for security weaknesses and misconfigurations
4. **Workload Context**: Nullify correlates resources to the applications they support, understanding business criticality and data sensitivity
5. **Risk Validation**: Configuration evidence and contextual analysis determine whether each finding represents a genuine risk or a benign configuration
6. **Notification & Remediation**: Real risks flow into Jira, Slack, and GitHub with ownership mapping and remediation guidance. Where a misconfiguration maps to an infrastructure-as-code change, Nullify can draft an [autofix](/capabilities/remediations) pull request against the code that provisioned it.

Cloud Audits run immediately after the cloud inventory stage, so each audit is evaluated against a freshly collected picture of your accounts. The cadence is configured per tenant and defaults to **once per day**; `weekly`, `fortnightly`, `monthly`, `on_change`, and `manual` are also available. A change made to your infrastructure is audited in the next scheduled run rather than within minutes of the change. On `manual`, the schedule never starts an audit and you trigger one on demand.

## Supported Cloud Providers

Nullify audits **AWS, GCP, Azure, and Kubernetes** with multi-account scanning. Coverage spans the core resource categories of each provider, including:

* **Storage & data**: object storage buckets, block volumes and snapshots, managed databases
* **Compute & network**: instances, security groups, load balancers, public exposure
* **Identity & access**: users, roles, policies, key management, password requirements
* **Logging & audit**: audit trails, log integrity, monitoring configuration
* **Kubernetes**: workload, RBAC, and cluster configuration checks

See the connector guides for setup: [AWS](/connectors/aws), [GCP](/connectors/gcp), [Azure cloud](/connectors/azure-cloud), and [Kubernetes](/connectors/kubernetes). Azure cloud inventory is separate from Azure DevOps and Microsoft workspace sign-in.

## Security Rules

Nullify ships managed rulesets per provider mapped to compliance frameworks — hundreds of rules each for AWS, GCP, and Azure, plus a dedicated **Kubernetes ruleset**. Rules are grouped by category rather than enumerated individually:

### Storage & Encryption

Detects publicly accessible storage buckets, validates server-side and at-rest encryption, prevents public snapshot exposure, and enforces managed-database encryption.

### Network Security

Identifies public-facing compute, security groups exposing sensitive ports (e.g. SSH/RDP) to the internet, overly permissive default network rules, and publicly accessible databases.

### Identity & Access

Flags root/break-glass access keys, weak password and key-rotation policies, and overly broad IAM permissions.

### Logging & Compliance

Ensures audit logging is enabled, validates log file integrity, and checks monitoring coverage.

### Backup & Recovery

Verifies adequate backup retention and recovery configuration on managed data stores.

## Code-to-Cloud Mapping

Nullify correlates cloud resources back to source code and business context:

* **Repository Links**: Maps resources to the repos that deployed them
* **Ownership Inference**: Uses CODEOWNERS and service metadata to assign findings
* **Workload Context**: Understands what data each resource processes and which applications depend on it
* **Business Impact**: Evaluates risk within the context of data sensitivity, customer exposure, and service criticality

## Compliance Mapping

Every finding includes compliance framework mapping:

* **CIS Foundations Benchmarks** (per provider)
* **PCI-DSS**
* **HIPAA** (select controls)
* **SOC2** (select controls)

## Notification Volume

Findings are announced individually to Slack, email, and PagerDuty. When one account reconcile produces more than 25 new findings of a single kind — as a first full scan of a cloud estate does — the batch is delivered as one digest summarising counts with a sample, instead of hundreds of messages. Resolutions are always delivered per finding, so an alert that was raised is still closed.

## Configuration

Configure cloud access during [Onboarding](/getting-started/getting-started#setup-stages). Setup is provider-specific — connect each AWS, GCP, or Azure account (and any Kubernetes clusters) with a least-privilege role or service account. See the connector guides for step-by-step instructions: [AWS](/connectors/aws), [GCP](/connectors/gcp).

## Cross-resource risk and controls

Rules also correlate toxic combinations across resources, such as exposure combined with permissive identity or storage configuration. Framework mappings include AWS Foundational Security Best Practices and selected OWASP and CIS EKS controls where the rule provides them. A finding's actual mappings are authoritative; not every rule maps to every framework. A control rollup is not a compliance certification.

Cloud triage evaluates collected configuration and context; it does not run the live exploit probes described under [Exploit Validation](/capabilities/pentests/exploit-validation).

## On-demand audits and finding actions

Use `POST /cspm/scans/start` for an on-demand audit of the configured scope. Findings support triage, allowlisting/unallowlisting, archiving/unarchiving, false-positive decisions, tickets, and supported autofix. Follow autofix status, state, and activity until completion; cloud autofix does not expose the same cache-diff route as SAST.

See [Cloud Configuration](/configuration/configuration-cloud) and the [Cloud Audits API](/api-reference/api-reference/cloud-audits). Connect [Azure cloud](/connectors/azure-cloud) separately from Azure DevOps, and include [Kubernetes](/connectors/kubernetes) when clusters are in scope. Ticket and chat delivery depends on configured destinations, including Jira, Linear, Slack, and Microsoft Teams.


# Supply Chain Posture Management

## Overview

Supply Chain Posture Management (SCPM) hardens the way your software is built and assembled. Where dependency analysis asks *"does this package have a known CVE?"*, SCPM asks *"is this dependency, manifest, lock file, or CI/CD workflow trustworthy in the first place?"* It reads the manifests, lock files, and pipeline definitions in each repository and flags supply-chain weaknesses — typosquatted or confusable package names, unpinned or floating dependencies, risky install scripts, missing or stale lock files, restricted licenses, and insecure CI/CD configuration — long before any of them turns into a published advisory.

SCPM scans the **default branch** to keep a continuous posture baseline and scans **pull requests** (diff-scoped to the manifests a PR touches) so new supply-chain risk is caught before it merges. Findings are triaged for real-world impact, surfaced in the dashboard and notification targets, and — where a fix can be expressed as a code change — remediated automatically with a pull request.

## How It Works

1. **Manifest & pipeline discovery**: SCPM walks the repository and parses every supported manifest, lock file, registry configuration and CI/CD definition — npm/`package.json` with `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, pnpm workspaces and `.npmrc`; Python (`requirements.txt`, `pyproject.toml`, `setup.cfg`, `Pipfile`, Conda environments, and pip index configuration); Go modules (`go.mod`, `go.sum`, `go.work`); Maven and Gradle including Gradle version catalogs; `.csproj`/NuGet; `Cargo.toml` with Cargo registry configuration; Ruby (`Gemfile`, `Gemfile.lock`, `.gemspec`); Composer (PHP); Swift Package Manager; Dart (`pubspec.yaml`); Elixir (`mix.exs`); CocoaPods; sbt; git submodules; Dockerfiles, Docker Compose and Kubernetes workload manifests; the build scripts a repository runs outside a package manager; and the pipelines themselves — GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines, CircleCI, Travis CI, Buildkite, Jenkins and Tekton — plus Dependabot and Renovate configuration.
2. **Posture detection**: A flat ruleset evaluates each parsed manifest against the supply-chain risk categories below. On a pull request the scan is diff-scoped so only the manifests the PR changed produce findings; on the default branch it runs full-repo.
3. **Triage**: Each detection is enriched with repository and business context, screened for false positives, classified for severity and exploitability, and assigned a priority. Triage combines LLM reasoning with deterministic rules so classification is reproducible.
4. **Delivery**: Real findings are written to the platform, flow into the dashboard, and fan out to Jira, Slack, Teams, and GitHub through the notification configuration, with ownership inferred from CODEOWNERS.
5. **Remediation**: For findings that map cleanly to a manifest edit (for example pinning a floating version or a CI/CD action), SCPM drafts an autofix pull request that matches the surrounding style.

SCPM is **event-driven**: it reacts to scan and finding lifecycle changes as they happen rather than running on a fixed daily or weekly cron, so posture stays in step with changes to your repositories.

## Supply-Chain Risk Coverage

SCPM ships a managed ruleset grouped by category rather than enumerated individually:

### Package Trust

* **Typosquatting** — package names that closely resemble a significantly more popular package, a common malicious-publish vector.
* **Dependency confusion** — internal/private package names that could be shadowed by a public registry package.
* **Supply-chain intelligence signals** — dependency hijacking via git-fork versions, and Go `replace` directives that redirect a required module to a fork under a different owner. A `replace` onto a local path (`./`, `../`) is how a Go monorepo wires its own packages together and is not reported.

### Dependency Pinning & Provenance

* **Unpinned / floating dependencies** — version specifiers that can resolve to different versions across builds.
* **Git/HTTP-sourced dependencies** — packages pulled from a git or HTTP URL instead of a registry, bypassing registry security controls.
* **Missing lock files** — manifests with no lock file, allowing non-deterministic resolution.
* **Unpinned Docker base images** — Dockerfiles and Compose files that reference a tag instead of a digest, exposing builds to tag mutation.
* **Dependency cooldown** — Dependabot ecosystem blocks with no cooldown, or a cooldown shorter than the configured window, that would auto-merge a freshly published (and potentially compromised) version too quickly.

### Install & Build Scripts

* **Install scripts** — packages that execute scripts during installation.
* **Unpinned installs in build scripts** — build steps that fetch or install dependencies without pinning.

### Licensing

* **Missing or restricted licenses** — the repository's own manifest declaring no license, or a project-declared license denied by org policy. With no accepted-licenses list configured, the default policy denies strong copyleft only (AGPL, GPL, SSPL, by exact SPDX id); weak and source-available licenses (LGPL, MPL, EPL, CDDL, Elastic, EUPL) are not flagged unless a tenant configures an allowlist. This evaluates the project's own declared license, not the licenses of its dependencies — see `scpm-license-dependency-restricted` for that, and `scpm-metadata-copyleft-license` for the separate rule that reports the full copyleft spectrum, weak included, on every scan.

### CI/CD Posture

A large, dedicated body of GitHub Actions / GitLab CI / Azure Pipelines checks — unpinned or unverified actions, script and YAML injection, artifact token leakage, excessive or over-provisioned permissions, dangerous triggers, cache poisoning, privileged checkout, Docker-socket exposure, self-hosted-runner risk, OIDC over-scoping, and missing build attestation, among others.

{% hint style="info" %}
Advisory-driven vulnerability matching (OSV/GHSA CVE data) is owned by [Dependency Analysis](/capabilities/code-reviews/dependency-analysis), not SCPM. SCPM does raise known malware: `scpm-known-malware` holds a repository's exactly-pinned dependencies against Nullify's malware index, which is a different source from the CVE feed and answers before any advisory exists. Everything else SCPM reports is a posture or trust signal rather than a known vulnerability.
{% endhint %}

## How SCPM Fits With Dependency Analysis

SCPM and dependency analysis (SCA) are complementary halves of dependency security:

* **Dependency Analysis (SCA)** answers *is this package version affected by a known vulnerability?* — it matches your dependency graph against enriched CVE/advisory feeds and reasons about reachability and exposure.
* **SCPM** answers *is the way you consume dependencies and run your pipelines trustworthy?* — typosquats, confusable names, unpinned versions, missing lock files, risky install scripts, license policy, and CI/CD hardening.

A package can be advisory-clean yet still be a supply-chain risk (a typosquat, an unpinned floating range, an install script, a workflow that leaks a token), which is exactly the gap SCPM covers. The two run over the same repositories and the same manifest set, so findings from both land side by side in the dashboard and route through the same triage, ticketing, and remediation flows.

## Finding Lifecycle

Every SCPM detection becomes a finding that moves through a consistent lifecycle:

1. **Detected** — a scan produces a new finding; pull-request scans flag findings the PR introduces.
2. **Triaged** — the finding is screened, classified, and prioritised, and re-triaged if a later scan changes the picture.
3. **Ticketed & notified** — findings that meet your configured thresholds create tickets and notify Slack and Teams.
4. **Remediated** — an autofix produces a fix and, where it applies, opens a pull request.
5. **Resolved or suppressed** — a finding can be allowlisted, un-allowlisted, or archived when it no longer reproduces.

When a scan that covered the whole branch no longer sees a finding, SCPM marks it fixed and closes any ticket attached to it. If a later scan finds it again, the finding is reported as reintroduced and its ticket is reopened — or, when the ticketing platform will not reopen a ticket that old, a fresh ticket is opened with a link back to the original. A finding you have allowlisted, archived, or marked a false positive is never reopened by a scan.

Triage runs on your default branch only. A pull-request scan reports what the pull request would introduce and blocks on it, but the verdict — the priority, the false-positive call, the reasoning — is produced for the finding that survives the merge, on the default branch's first scan after it lands. A pull request's findings are transient: the branch is deleted, the findings go with it, and any verdict produced against them would be discarded with them. The practical effect is that a finding a pull request introduces is blocked on its own merits immediately and carries its full triage detail from the first default-branch scan afterwards.

### When a repository or installation is removed

* **A branch is deleted** — its findings are removed, since they can never be observed again.
* **A repository is removed from the installation, or deleted** — its findings are removed.
* **The Nullify app is uninstalled** — findings are **kept**. Uninstalling stops new scans but preserves your triage verdicts, allowlist decisions, and ticket links, so reinstalling picks up where you left off. This matches how SAST and SCA findings behave.

To delete findings deliberately rather than as a side effect of uninstalling, remove the repository or ask Nullify support for a data erasure.

### Querying & acting on findings

The SCPM API mirrors the other detection services:

* `GET /scpm/findings` (plus `/scpm/findings/preview` and `/scpm/findings/detailed`) to list findings.
* `GET /scpm/findings/{findingId}`, `GET /scpm/findings/{findingId}/triage`, and `GET /scpm/findings/{findingId}/events` to inspect a single finding and its history.
* `PATCH /scpm/findings/{findingId}` to update a finding.
* `POST /scpm/findings/{findingId}/ticket` and `DELETE /scpm/findings/{findingId}/ticket` to manage tickets.
* `POST /scpm/findings/{findingId}/allowlist`, `POST /scpm/findings/{findingId}/unallowlist`, and the bulk `POST /scpm/findings/allowlist` to suppress findings.

### Allowlisting a finding

To allowlist (ignore) a finding, send an `allowlistReason` and an `allowlistType`:

```json
{
  "allowlistReason": "Internal package, not a public typosquat",
  "allowlistType": "UserFalsePositive"
}
```

`allowlistType` is one of `AI`, `UserFixed`, `UserAssumeRisk`, `UserFalsePositive`, or `UserOther`. The bulk endpoint additionally takes a `findingIds` array.

{% hint style="info" %}
Findings are allowlisted per-finding from the dashboard or API. A coordinate-based package allowlist can also suppress matching findings before they are created. A repository can additionally carry `.nullify/scpm-ignore.yml`, which sets a rule to `warn` or `off` or lowers its severity for that repository only. It can weaken enforcement and never strengthen it, and it is read from the pull request's merge base rather than the pull request's own checkout, so a pull request cannot add an entry that silences the finding it is introducing. Rules that describe an attack — see [The enforcement floor](#the-enforcement-floor) — cannot be weakened by it at all.
{% endhint %}

## Remediation (Autofix)

When a finding can be resolved by a manifest or pipeline change, SCPM drafts a fix and opens a pull request through the shared autofix pipeline:

* `POST /scpm/findings/{findingId}/autofix/fix` generates a fresh fix against the current target branch. Legacy `useCachedFix` inputs are ignored.
* Fix previews are retired. Both `POST …/autofix/cache` and `POST …/autofix/cache/create_pr` are removed; use `/autofix/fix` for fresh generation against the finding’s current branch. `GET …/autofix/cache/diff` returns 404 without reading storage.
* `GET /scpm/findings/{findingId}/autofix/status`, `…/state`, and `…/activity` track progress.

Autofix pull-request limits are platform-managed (3 open Nullify fix PRs per repository, 5 new fix PRs per remediation plan) and are not configurable per repository. See [Remediations](/capabilities/remediations) for how fixes work with developers, ownership routing, and CI feedback.

## Real-time reaction

Supply-chain posture stays in step with your repositories: as scans complete and findings move through their lifecycle, notifications, ticketing, and [Security Program Management](/capabilities/program-management) react in real time rather than waiting for a nightly batch.

## Dependency cooldowns

A freshly published package version is a supply-chain risk in its own right — worm-speed compromises spread through new releases before any advisory exists. SCPM can flag direct, dev and lockfile-resolved dependencies that are newer than a configurable recency window (7 days by default), independent of whether any CVE has been filed. A recent publish is reported at HIGH for the whole window and never escalates with how new the version is: the age is recorded on the finding, but the top severity is reserved for evidence of an attack rather than evidence of newness. What does escalate is missing coverage — a repository that ships dependencies in an ecosystem no updater cooldown covers is reported at HIGH for the gap itself.

You control this per tenant through the SCPM settings API (`GET`/`PUT /scpm/settings`): toggle the cooldown gate on or off, set the window in days, and add per-ecosystem overrides.

This complements the narrower **Dependabot cooldown** conformance rule above (which checks that your Dependabot config doesn't auto-merge freshly published versions too quickly).

## Configuration

SCPM settings live in the dashboard and admin API, not in any repository config file:

* **Ticket creation thresholds** (severity/priority per finding type): **Configure → Ticketing**.
* **CI/PR gate** (fail the build, enable PR reviews): **Configure → Pull Requests**.
* **Notification destinations**: **Configure → Connectors** (Slack, Teams, Jira).
* **Dependency cooldown window**: SCPM settings API (`PUT /scpm/settings`).
* **Enforcement floor**: fixed at `CRITICAL` — see below.

Ignore decisions are made per-finding (see [Allowlisting a finding](#allowlisting-a-finding)).

### The enforcement floor

The enforcement floor is the minimum severity a supply-chain finding must reach before it can **block a pull request**. It is **`CRITICAL`**.

That is deliberately conservative. A single repository's first SCPM scan routinely surfaces hundreds of `HIGH` findings — unpinned actions, floating version ranges, missing lock files — that are real posture issues but were already there before the pull request. Blocking on all of them the day SCPM is switched on would stop every merge in the organisation.

What the floor does and does not do:

* **It does not hide findings.** Every finding below the floor is still detected, triaged, stored, and visible in the dashboard and the API. Only merge-blocking is affected.
* **Malicious-package findings ignore it.** Typosquats, dependency confusion, known-malicious actions, known malware, phantom and AI-hallucinated packages, and rapid-publish findings block at their own severity whatever the floor is set to. These describe an attack rather than a hygiene gap, so the floor — which exists to stop the high-volume hygiene families gating a repository by surprise — is not allowed to disarm them. Setting your own policy for one of those rules replaces this default.
* **It applies to the PR gate.** A finding below the floor is reported on the pull request but does not fail the check run. When findings are excluded this way, the check run says so and names how many.
* **It applies to automatic ticketing.** Auto-created tickets use the same floor, so lowering it also starts ticketing the newly-eligible findings — including ones detected long before the change, since the floor is read when the ticket is considered, not when the finding was found.
* **An in-repo exception wins over it.** A path excluded through `.nullify/scpm-ignore.yml` is excluded regardless of severity.

{% hint style="info" %}
If your check runs are passing but you expect supply-chain findings to be blocking, the floor is the first thing to check — the check-run summary reports how many findings it excluded.
{% endhint %}

## Metadata and malware analysis

Package metadata can surface unmaintained, deprecated, or trivial dependencies in addition to manifest and pipeline weaknesses. Container configuration checks include insecure HTTP registry use. A metadata warning is a posture signal, not a confirmed malicious-package verdict.

SCPM also exposes on-demand dependency and container malware analysis and batch result lookup. See the [SCPM API](/api-reference/api-reference/scpm) for these operations and the `acceptedLicenses`, `packageAllowlist`, and `cooldownWarnOnly` settings. Coordinate-based package policy is separate from allowlisting one finding.

## Related

* [Threat Intelligence](/capabilities/threat-intelligence): shared research of new vulnerabilities and supply-chain compromises, assessed against your environment.


# Rules Reference

Every SCPM finding names the rule that raised it. This page lists each rule id, what it detects, and the section a finding's documentation link resolves to. Severity grading is described in the service's severity rubric. There is no per-tenant `off`/`warn`/`block` UI: a finding blocks a merge when its effective severity is CRITICAL or higher, and a confirmed threat — a package the malware index or a compromised-action index has verified — always blocks regardless of severity, whatever the CRITICAL floor says. A repository can lower or silence a finding for itself with `.nullify/scpm-ignore.yml`, downgrade-only, and a confirmed threat cannot be named in that file.

## Scope: what a pull request check reports

Every rule runs on every scan, and a branch scan persists everything each one finds. The **Scope** column decides only what a *pull request* check is allowed to report back on the pull request itself.

* **PR-scoped** — the finding sits on a line the file currently contains: a dependency entry, a `run:` step, a `FROM` directive. A pull request check can honestly intersect it with the lines the pull request added, so the author sees only what they introduced.
* **branch-only** — the finding's evidence is an *absence* or a whole-repository property: no lockfile beside the manifest, no updater configured, no permissions block, no attestation in the release workflow. There is no added line to anchor it to, so reporting it on a pull request would blame whoever opened it for a gap the branch already had. These appear in the repository's findings and in the branch scan, never as a pull request annotation.

Scope is not an enablement switch and not a severity. A branch-only rule is not a weaker rule; it is one whose finding belongs to the repository rather than to a change.

## CI platform: which CI systems a rule reads

The **CI platform** column names the CI systems whose configuration a rule reads. It is blank (`—`) for every rule that is not a CI/CD rule.

Coverage depends on the CI systems detected and eligible for the repository, not just where its source is hosted. **36 of the 55 CI/CD rules read GitHub Actions configuration only.** Azure Pipelines, GitLab CI and other systems have different applicable rule sets; a repository can use more than one system. Read the scan's coverage and this table before interpreting an empty result.

Two things follow:

* A `.github/workflows` directory **mirrored** onto a non-GitHub repository does not execute there, so SCPM does not run the GitHub rules over it. Nothing runs those workflows, so a finding on one would name a risk that cannot be taken.
* Every scan reports what could not apply. The coverage account lists CI/CD rules that do not apply to the detected systems, so an inapplicable rule is not mistaken for a passed check.

**2 of the 55 CI/CD rules apply on every CI system** — `scpm-cicd-unpinned-action` and `scpm-cicd-malicious-action` — because they grade a *reference* (an action, an orb, a plugin, a shared library) rather than a workflow document, so they read the same fact wherever it is declared. `scpm-cicd-self-hosted-runner` reads GitHub Actions and Bitbucket Pipelines, where the file declares a runner and can be written to clear the finding; it does not read Buildkite, which has no hosted tier at all, so a blanket finding on every Buildkite pipeline would name nothing the file could fix. `scpm-cicd-docker-socket` and `scpm-cicd-unpinned-images` each read GitHub Actions and GitLab CI.

## CI systems SCPM does not read

Seven CI systems are recognised but not graded. SCPM sees their configuration during the walk and reports it as a coverage gap rather than parsing it, so a pipeline defined in one of them is outside every CI/CD rule above:

| CI system          | Configuration the scan sees | Reported as          |
| ------------------ | --------------------------- | -------------------- |
| Drone              | `.drone.yml`                | `drone`              |
| AWS CodeBuild      | `buildspec.yml`             | `aws-codebuild`      |
| Google Cloud Build | `cloudbuild.yaml`           | `google-cloud-build` |
| AppVeyor           | `appveyor.yml`              | `appveyor`           |
| Codemagic          | `codemagic.yaml`            | `codemagic`          |
| Semaphore          | `.semaphore/semaphore.yml`  | `semaphore`          |
| Woodpecker         | `.woodpecker.yml`           | `woodpecker`         |

A scan that finds one of these names it on its coverage account, so a clean CI/CD result on a repository built by Drone or CodeBuild reads as "these pipelines were not inspected" rather than as "these pipelines are fine". CircleCI, Travis CI, Buildkite, Jenkins and Tekton are **not** in this list: SCPM parses all five, the reference rules above grade the orbs, plugins, shared libraries, bundles and images they pull in, and `scpm-cicd-ci-script-injection` grades what their shell steps interpolate.

## Overlap with SAST's GitHub Actions rules

`sast/tools/opengrep/rules/yaml/github-actions/` is a separate opengrep rule pack that also reads `.github/workflows`. It predates most of the CI/CD rules above and was not folded into them; six of its eight rules name the same construct one of these does, so a GitHub Actions workflow with, for example, a `pull_request_target` head checkout gets a finding from both SAST and SCPM. Neither rule set defers to the other today — this is recorded here rather than resolved, and no SAST rule is removed by it:

| SAST opengrep rule                            | Overlapping SCPM rule                                        |
| --------------------------------------------- | ------------------------------------------------------------ |
| `pull-request-target-code-checkout`           | `scpm-cicd-dangerous-trigger`                                |
| `workflow-run-target-code-checkout`           | `scpm-cicd-dangerous-trigger`, `scpm-cicd-workflow-run-risk` |
| `run-shell-injection`                         | `scpm-cicd-script-injection`                                 |
| `github-script-injection`                     | `scpm-cicd-github-script-injection`                          |
| `allowed-unsecure-commands`                   | `scpm-cicd-insecure-commands`                                |
| `third-party-action-not-pinned-to-commit-sha` | `scpm-cicd-unpinned-action`                                  |

`curl-eval` (an eval of curl'd data) and `unsafe-add-mask-workflow-command` (an `::add-mask::` a `::stop-commands::` payload can defeat) have no SCPM counterpart.

## License policy baseline

`scpm-license-restricted` (the repository's own declared license) and `scpm-license-dependency-restricted` (a dependency's registry-declared license) both evaluate against the org's license policy. A tenant with no accepted-licenses list configured is not "permit everything": the default baseline denies **strong (network) copyleft only**, matched by exact SPDX id — `AGPL-1.0`/`AGPL-3.0`, `GPL-2.0`/`GPL-3.0` (both the modern `-only`/`-or-later` ids and their pre-SPDX-3.0 bare spellings, which registry metadata still commonly reports) and `SSPL-1.0` — at MEDIUM severity. Weak and source-available licenses (LGPL, MPL, EPL, CDDL, Elastic, EUPL, ...) are **not** flagged by this default; matching is always exact, never by family substring, so an LGPL id is never caught by a GPL deny entry. An SPDX OR/AND expression is evaluated by its own structure — an OR is denied only when every branch is denied, an AND only when every atom is — so a dual license with an acceptable branch, or an AND with an acceptable choice nested inside an OR, is not denied just because one branch names a denied id.

A tenant that configures an accepted-licenses list switches `scpm-license-dependency-restricted` to full allowlist semantics: only the listed licenses pass, and everything else — including weak copyleft the default baseline lets through — is denied. `scpm-license-restricted` never consults that allowlist; it always evaluates the repository's own declared license against the constant copyleft baseline above, regardless of tenant configuration.

A dependency coordinate the license index could not resolve is counted and marked incomplete on the scan's own coverage, rather than reading as a license that was checked and passed.

`scpm-metadata-copyleft-license` is a separate, independently-configured rule: it reports the full copyleft spectrum (including weak copyleft, at LOW) on every scan, with no accepted-licenses concept, and is unaffected by the baseline above.

## Finding types SCPM does not raise

SCPM reads a repository's dependency **manifests** out of a git checkout, and asks the registries and the malware index about the coordinates it finds there. It never downloads a published package's own source. Three families of supply-chain signal therefore belong to other parts of the platform, and no SCPM rule will ever raise them:

* **Signals inside a published package's code** — obfuscated or minified code, encrypted payloads, hidden code, `eval` usage, embedded telemetry, native code, network, filesystem or environment-variable access, self-propagating code, high-entropy strings. These require fetching and analysing the package itself.
* **Signals that need a live feed** — a maintainer-account compromise, a CDN domain takeover. (A known-malware verdict is not one of these: `scpm-known-malware` holds every exactly-pinned dependency against the malware index. That index is a platform service, so the rule is live on a platform scan and reports itself *incomplete*, never clean, on a scan that has no index behind it — which is what a local `nullify scpm scan` has. The same is true of every `scpm-cooldown-*` rule: cooldown is evaluated against the tenant's policy, so a local scan raises none.)
* **Signals that need registry history** — whether a package's maintainer set changed between versions (`unstable_ownership`) or whether its publishing account is newly created (`new_author`). SCPM's registry lookups read one current document per package; neither is versioned and none carries an account-creation date.

What SCPM *can* see about a package's stewards it does raise: see `scpm-intelligence-steward` above.

| Rule id                                        | Name                                                        | Scope       | CI platform                             | Detects                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------- | ----------------------------------------------------------- | ----------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scpm-ansible-integrity`                       | Ansible Supply Chain Integrity                              | PR-scoped   | —                                       | An Ansible collection or role is installed from a movable git ref, a URL or an unpinned Galaxy version, a task downloads a file without a checksum (and may then execute or install it), a shell task runs code it downloads, a pip task installs from a movable git ref, a package repository or signing key is configured without signature or TLS verification, or ansible.cfg turns off SSH host key or Galaxy certificate checking                                                                                                                                                                                                                        |
| `scpm-bazel-dependency-integrity`              | Bazel External Dependency Integrity                         | PR-scoped   | —                                       | A WORKSPACE, MODULE.bazel, repository macro or .bazelrc fetches external code without a checksum (`http_archive`, `http_file`, `http_jar`, `archive_override`), only over plaintext HTTP, at a git branch or tag instead of a commit (`git_repository`, `new_git_repository`, `git_override`), as a Go module with no `sum` (`go_repository`), from a plaintext module registry, or with Bzlmod resolution no committed `MODULE.bazel.lock` pins (or `--lockfile_mode=off`)                                                                                                                                                                                    |
| `scpm-cicd-ai-risk`                            | AI/ML Action with Secret Access                             | PR-scoped   | GitHub Actions                          | AI/ML action or integration processes untrusted input (PR content, issues, comments) with access to repository secrets, enabling prompt injection attacks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cicd-artifact-token-leak`                | CI/CD Artifact Token Leak Risk                              | PR-scoped   | GitHub Actions                          | Workflow uploads artifacts that may include git credentials from checkout, enabling token exfiltration (ArtiPACKED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cicd-azure-agent-security`               | Azure Self-Hosted Agent Security                            | PR-scoped   | Azure Pipelines                         | Pipeline uses self-hosted agent pool which may expose persistent credentials, build artifacts, and internal network access                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-azure-pipeline-access-ctrl`         | Azure Pipeline Access Control                               | PR-scoped   | Azure Pipelines                         | Pipeline has excessive job authorization scope or broad variable group access, violating least privilege                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-azure-pipeline-injection`           | Azure Pipeline YAML Injection                               | PR-scoped   | Azure Pipelines                         | User-controlled input is interpolated into pipeline YAML via macro syntax or template expressions, enabling command injection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-cicd-azure-secrets-exposure`             | Azure Pipeline Secrets Exposure                             | PR-scoped   | Azure Pipelines                         | Secrets from variable groups or service connections may be exposed in pipeline scripts via echo, logging, or direct interpolation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cicd-azure-service-connections`          | Azure Pipeline Service Connection Usage                     | PR-scoped   | Azure Pipelines                         | Pipeline uses service connections that may have overly permissive access to external services (Azure, AWS, K8s, Docker registries)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-cicd-bitbucket-untrusted-privilege`      | Privileged Bitbucket Pull-Request Pipeline                  | PR-scoped   | Bitbucket Pipelines                     | A pull-requests pipeline step claims a deployment environment or an OIDC identity token, giving code from a contributor's branch the credentials of a trusted build                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cicd-bot-conditions`                     | Spoofable Bot Actor Check                                   | PR-scoped   | GitHub Actions                          | Workflow condition uses github.actor to check for bot identity, which can be spoofed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-cache-poisoning`                    | Cache Poisoning in Release Workflow                         | PR-scoped   | GitHub Actions                          | Release or publish workflow uses cached artifacts which could be poisoned by a prior malicious build                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-cache-poisoning-default-branch`     | Privileged Job Restores a Cache Pull Request Code Can Write | PR-scoped   | GitHub Actions                          | A job holding deploy credentials restores a build cache in a repository where a workflow runs pull request code in the default branch's cache scope                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cicd-ci-script-injection`                | CI Script Injection                                         | PR-scoped   | Jenkins, CircleCI, Buildkite, Travis CI | Attacker-controlled pipeline variable is interpolated into a shell body, enabling arbitrary command execution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-cicd-concurrency-limits`                 | Missing Concurrency Controls                                | branch-only | GitHub Actions                          | Workflow lacks concurrency limits, allowing unbounded parallel runs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cicd-dangerous-trigger`                  | Dangerous CI/CD Trigger Configuration                       | PR-scoped   | GitHub Actions                          | Workflow uses a trigger configuration that can execute untrusted code with elevated privileges                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `scpm-cicd-default-branch-push`                | Direct Push to Default Branch                               | PR-scoped   | GitHub Actions                          | Workflow pushes directly to the default branch, bypassing branch protection rules and code review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cicd-dispatch-toctou`                    | Dispatch TOCTOU Race Condition                              | PR-scoped   | GitHub Actions                          | workflow\_dispatch validates inputs in one step but uses them in a later step, enabling a time-of-check-time-of-use race condition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-cicd-docker-socket`                      | Docker Socket Mounting                                      | PR-scoped   | GitHub Actions, GitLab CI               | Workflow mounts the Docker daemon socket, giving containers full host Docker access enabling escape and lateral movement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-environment-bypass`                 | Environment Protection Bypass                               | branch-only | GitHub Actions                          | Workflow can circumvent GitHub Environment protection rules via dynamic environment names or missing environment declarations on deployment jobs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cicd-excessive-permissions`              | Excessive CI/CD Workflow Permissions                        | PR-scoped   | GitHub Actions                          | Workflow or job uses overly permissive token permissions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-github-env`                         | Dangerous GITHUB\_ENV/GITHUB\_PATH Write                    | PR-scoped   | GitHub Actions                          | Workflow writes to GITHUB\_ENV or GITHUB\_PATH in a context triggerable by external contributors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cicd-github-script-injection`            | GitHub Script Injection                                     | PR-scoped   | GitHub Actions                          | Untrusted input used in actions/github-script enables JavaScript injection with access to the GitHub API via octokit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-gitlab-include-injection`           | GitLab CI Remote Include Injection                          | PR-scoped   | GitLab CI                               | Pipeline includes remote configuration that could inject malicious jobs, scripts, or variable overrides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `scpm-cicd-gitlab-runner-exposure`             | GitLab Self-Managed Runner Exposure                         | PR-scoped   | GitLab CI                               | Self-managed runner is used in merge request pipelines, exposing internal infrastructure to untrusted code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-gitlab-script-injection`            | GitLab CI Script Injection                                  | PR-scoped   | GitLab CI                               | Attacker-controlled CI variable is used in a script block, enabling arbitrary command execution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-cicd-gitlab-secrets-exposure`            | GitLab MR Secrets Exposure                                  | PR-scoped   | GitLab CI                               | Merge request pipeline job accesses CI/CD variables or secrets, enabling exfiltration via malicious MRs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `scpm-cicd-gitlab-token-exposure`              | GitLab CI Token Exposure                                    | PR-scoped   | GitLab CI                               | Pipeline token (CI\_JOB\_TOKEN or deploy token) is used in a context where it may be leaked to untrusted services or logs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cicd-gitlab-unpinned-include`            | GitLab CI Unpinned Include                                  | PR-scoped   | GitLab CI                               | Remote or project include does not pin to a specific ref/SHA, enabling supply chain attacks via upstream changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cicd-gitlab-unsafe-checkout`             | GitLab MR Unsafe Checkout                                   | PR-scoped   | GitLab CI                               | Merge request pipeline checks out and executes code from the attacker-controlled source branch with access to protected variables or runners                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-cicd-insecure-commands`                  | Insecure Workflow Commands Enabled                          | PR-scoped   | GitHub Actions                          | Workflow re-enables deprecated unsafe commands that allow stdout-based environment injection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-cicd-issue-comment-auth`                 | Issue Comment Without Author Validation                     | PR-scoped   | GitHub Actions                          | Workflow triggered by comment, review, issue or discussion content executes commands without validating the author's association, allowing any user to trigger it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cicd-local-action-modification`          | Local Action Modification via PR                            | PR-scoped   | GitHub Actions                          | Workflow uses local composite actions from the checked-out repository with pull\_request\_target, allowing attackers to modify the action in their fork and execute arbitrary code with base repo permissions                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-cicd-malicious-action`                   | Known Compromised CI/CD Action                              | PR-scoped   | all CI systems                          | CI/CD action has been identified as compromised or malicious                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-cicd-missing-attestation`                | Missing Artifact Attestation in Release                     | branch-only | GitHub Actions                          | Release workflow does not generate artifact attestations or SBOMs for provenance verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-cicd-missing-permissions`                | Missing Top-Level Permissions Block                         | branch-only | GitHub Actions                          | Workflow does not declare explicit permissions, inheriting the repository's default (often read-write-all)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-mutable-image-push`                 | Pull Request Pushes a Shared Image Tag                      | PR-scoped   | GitHub Actions                          | A job a pull request reaches pushes a container image under a fixed, shared tag, so unreviewed code replaces the image other jobs pull by that tag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-cicd-obfuscation`                        | Obfuscated Workflow Pattern                                 | PR-scoped   | GitHub Actions                          | Workflow contains obfuscated expressions or paths that hinder security auditing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-cicd-oidc-overscope`                     | Shared OIDC Token Audience                                  | PR-scoped   | GitHub Actions                          | Workflow sets the same OIDC audience on more than one login, so a token minted for one relying party can be replayed against the other                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `scpm-cicd-oidc-untrusted-trigger`             | Cloud Role Assumed From Untrusted Trigger                   | PR-scoped   | GitHub Actions                          | A job assumes a cloud role through GitHub OIDC on a pull request trigger without a deployment environment, so unreviewed code can run with that role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-overprovisioned-secrets`            | Wholesale Secrets Exposure                                  | PR-scoped   | GitHub Actions                          | Workflow exposes the entire secrets context via toJSON(secrets), leaking all secrets at once                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-cicd-privileged-checkout`                | Persisted Credentials in Checkout                           | PR-scoped   | GitHub Actions                          | actions/checkout leaves GITHUB\_TOKEN in .git/config by default, accessible to all subsequent steps including third-party actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cicd-ref-version-mismatch`               | Stale Version Comment on Pinned Action                      | PR-scoped   | GitHub Actions                          | Hash-pinned action has a version comment that does not match the actual pinned commit SHA                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cicd-script-injection`                   | CI/CD Script Injection                                      | PR-scoped   | GitHub Actions                          | Untrusted input is used directly in a run block, or in an action input the action executes as code, enabling arbitrary command execution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-secrets-exposure`                   | CI/CD Secrets Exposure Risk                                 | PR-scoped   | GitHub Actions                          | Secrets may be exposed in workflow logs through echo, print, or direct use in run blocks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-secrets-inherit`                    | Blanket Secret Forwarding                                   | PR-scoped   | GitHub Actions                          | Reusable workflow call uses 'secrets: inherit' which forwards all secrets including those not needed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-self-hosted-runner`                 | Self-Hosted Runner Exposure                                 | PR-scoped   | GitHub Actions, Bitbucket Pipelines     | Workflow uses self-hosted runners which lack ephemeral isolation and may expose persistent credentials or internal network access                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cicd-step-output-injection`              | Step Output Injection in Run Block                          | PR-scoped   | GitHub Actions                          | Step or job output is interpolated directly into a run block via ${{ steps.*.outputs.* }} or ${{ needs.*.outputs.* }}, which can enable command injection if the output contains untrusted data (filenames, PR metadata)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-cicd-unpinned-action`                    | Unpinned CI/CD Action Reference                             | PR-scoped   | all CI systems                          | CI/CD action or template is referenced by a mutable tag or branch instead of a commit SHA                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cicd-unpinned-images`                    | Unpinned Container Image                                    | PR-scoped   | GitHub Actions, GitLab CI               | Container image is not pinned to a SHA256 digest, allowing supply chain attacks via tag manipulation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cicd-unprotected-deployment`             | Missing Environment Protection on Deployment                | branch-only | GitHub Actions                          | Deployment workflow does not use GitHub environment protection rules, allowing unreviewed deployments                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-cicd-unredacted-secrets`                 | Unredacted Secret Access                                    | PR-scoped   | GitHub Actions                          | Secret parsed as structured data bypasses GitHub's automatic log redaction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-unsound-condition`                  | Unsound Workflow Condition                                  | PR-scoped   | GitHub Actions                          | Workflow condition uses YAML block scalar syntax which silently makes conditions always true                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-cicd-unsound-contains`                   | Unsafe contains() Usage                                     | PR-scoped   | GitHub Actions                          | Workflow condition uses contains() for string matching, which does substring matching and may allow bypass                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-unverified-action`                  | Third-Party Action in Privileged Workflow                   | PR-scoped   | GitHub Actions                          | Workflow with elevated permissions uses a third-party action from an unverified publisher                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cicd-use-trusted-publishing`             | Missing OIDC Trusted Publishing                             | branch-only | GitHub Actions                          | Package publishing workflow uses long-lived credentials instead of OIDC trusted publishing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cicd-workflow-run-risk`                  | Workflow Run Privilege Escalation                           | PR-scoped   | GitHub Actions                          | workflow\_run triggered workflow downloads and uses artifacts from untrusted triggering run, enabling privilege escalation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-confusion-dependency`                    | Dependency Confusion                                        | PR-scoped   | —                                       | Package name suggests internal package but comes from public registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-cooldown-absolute-pin-stale`             | Absolute Cooldown Cutoff Is Stale                           | branch-only | —                                       | A native cooldown pins an absolute cutoff date so old that it freezes dependencies instead of delaying them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scpm-cooldown-dependabot-below-threshold`     | Dependabot Cooldown Below Threshold                         | branch-only | —                                       | A Dependabot block's cooldown is shorter than the configured window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cooldown-dependabot-disabled`            | Dependabot Updates Disabled                                 | branch-only | —                                       | A Dependabot block sets open-pull-requests-limit to 0, so it can never open update PRs and any cooldown is inert                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cooldown-dependabot-missing`             | Dependabot Cooldown Missing                                 | branch-only | —                                       | A Dependabot package-ecosystem block sets no cooldown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-cooldown-dependabot-partial`             | Dependabot Cooldown Partial Coverage                        | branch-only | —                                       | A Dependabot block cools only some bump types or an allowlisted subset, leaving the rest uncovered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-cooldown-ecosystem-uncovered`            | Ecosystem Missing Cooldown Coverage                         | branch-only | —                                       | The organization mandates a cooldown for an ecosystem the repository ships dependencies in, but no updater or native config covers it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-cooldown-native-below-threshold`         | Native Package-Manager Cooldown Below Threshold             | branch-only | —                                       | A native package-manager cooldown is shorter than the configured cooldown window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cooldown-native-disabled`                | Native Package-Manager Cooldown Disabled                    | branch-only | —                                       | A native package-manager cooldown is explicitly set to zero, disabling install-time protection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `scpm-cooldown-native-partial`                 | Native Package-Manager Cooldown Partial Coverage            | branch-only | —                                       | A native package-manager cooldown exempts named packages, leaving them uncovered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cooldown-no-updater`                     | No Dependency-Updater Cooldown Configured                   | branch-only | —                                       | The organization mandates a cooldown but the repository ships no Renovate or Dependabot cooldown configuration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `scpm-cooldown-pm-unsupported`                 | Package Manager Predates Cooldown Support                   | branch-only | —                                       | The repository pins a package manager version that cannot enforce the configured dependency cooldown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-cooldown-recent-publish`                 | Recently-Published Dependency                               | PR-scoped   | —                                       | Dependency version was published within the configured cooldown window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `scpm-cooldown-recent-publish-transitive`      | Recently-Published Transitive Dependency                    | PR-scoped   | —                                       | Lockfile-resolved transitive dependency version was published within the configured cooldown window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cooldown-renovate-below-threshold`       | Renovate Cooldown Below Threshold                           | branch-only | —                                       | Renovate minimumReleaseAge is shorter than the configured cooldown window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-cooldown-renovate-disabled`              | Renovate Cooldown Disabled                                  | branch-only | —                                       | Renovate neutralises its release-age cooldown (enabled:false, internalChecksFilter:none, or a blanket-neutralising packageRule)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-cooldown-renovate-missing`               | Renovate Cooldown Missing                                   | branch-only | —                                       | Renovate is configured but no minimumReleaseAge cooldown is set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-cooldown-renovate-partial`               | Renovate Cooldown Partial Coverage                          | branch-only | —                                       | Renovate sets a cooldown only for some packages (packageRules), leaving the rest uncovered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-cooldown-renovate-partial-exemption`     | Renovate Cooldown Package Exemptions                        | branch-only | —                                       | Renovate exempts named packages from the cooldown (ignoreDeps or a neutralised packageRule), leaving them uncovered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-cooldown-renovate-unparseable`           | Renovate Config Unparseable                                 | branch-only | —                                       | The package.json embedded renovate config could not be decoded, so its cooldown cannot be verified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-cooldown-renovate-unverifiable`          | Renovate Cooldown Unverifiable                              | branch-only | —                                       | Renovate cooldown is inherited from shared presets or an unparseable value and cannot be verified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scpm-cooldown-unverifiable-ecosystem`         | Cooldown Unverifiable For Ecosystem                         | branch-only | —                                       | The repository uses dependencies from an ecosystem with no registry intelligence source, so the cooldown window and the registry-backed rules cannot be verified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-cooldown-updater-automation`             | Unsafe Dependency-Updater Automation                        | branch-only | —                                       | Dependency updater merges, or executes code, without the human review every cooldown and typosquat finding depends on                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-cooldown-updater-config-unparseable`     | Updater Config Unparseable                                  | branch-only | —                                       | The organization mandates a cooldown but the repository's updater configuration could not be parsed, so it enforces nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scpm-docker-compose-unpinned`                 | Unpinned Docker Compose Image                               | PR-scoped   | —                                       | Docker Compose service uses an image without a version tag or digest, defaulting to :latest which is mutable                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-docker-insecure-registry`                | Insecure Docker Registry                                    | PR-scoped   | —                                       | Docker image references a private or insecure registry that may use HTTP or lack authentication                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-docker-unpinned-base`                    | Unpinned Docker Base Image                                  | PR-scoped   | —                                       | Dockerfile uses a base image without a digest pin, making builds non-reproducible and vulnerable to tag mutation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-git-submodule-integrity`                 | Git Submodule Integrity                                     | PR-scoped   | —                                       | .gitmodules fetches a submodule over plaintext or runs a command on every update, so the checkout is decided off-repository                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scpm-gitops-source-ref`                       | Unpinned GitOps Source                                      | PR-scoped   | —                                       | Argo CD or Flux points the cluster at a repository on a mutable revision, or over plaintext HTTP, so what the cluster runs is decided at sync time rather than in the repository                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-helm-chart-dependency`                   | Unpinned Helm Chart Dependency                              | PR-scoped   | —                                       | Helm chart declares a subchart on a mutable version constraint or fetches it from a plaintext HTTP repository, so the chart installed into the cluster is decided at build time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-intelligence-ai-hallucination`           | AI Hallucination Hijack                                     | PR-scoped   | —                                       | Dependency matches a low-popularity hallucinated package name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-intelligence-analysis`                   | Supply Chain Intelligence                                   | PR-scoped   | —                                       | Detects supply chain intelligence signals such as dependency hijacking via git-fork versions and replace directives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-intelligence-phantom-package`            | Phantom Package                                             | PR-scoped   | —                                       | Direct dependency is absent from its public registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-intelligence-phantom-package-transitive` | Phantom Transitive Package                                  | PR-scoped   | —                                       | Lockfile-resolved transitive dependency is absent from its public registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-intelligence-rapid-publish`              | Rapid Publish Pattern                                       | PR-scoped   | —                                       | Multiple package versions were published in a short window                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-intelligence-steward`                    | Package Steward                                             | PR-scoped   | —                                       | The registry or source host reports that nobody, or no verifiable party, stands behind a dependency: an archived, stale or missing source repository, no listed maintainer, or a single maintainer account behind the whole package                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-known-malware`                           | Known Malicious Package                                     | PR-scoped   | —                                       | A dependency at an exact version the malware index has confirmed malicious; direct and transitive, blocked by the platform default policy whatever the enforcement floor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-kubernetes-unpinned-image`               | Unpinned Kubernetes Image                                   | PR-scoped   | —                                       | Kubernetes workload or Helm values reference a container image by mutable tag rather than digest, so the artifact that runs is decided at deploy time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-kustomize-remote-base`                   | Unpinned Kustomize Remote Base                              | PR-scoped   | —                                       | Kustomization pulls a remote base or chart on a mutable ref, or over plaintext HTTP, so the manifests applied to the cluster are decided at build time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `scpm-license-dependency-mismatch`             | Dependency License Mismatch                                 | PR-scoped   | —                                       | Dependency metadata declares multiple licenses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `scpm-license-dependency-restricted`           | Dependency License Restricted                               | PR-scoped   | —                                       | Dependency license is denied by org policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `scpm-license-dependency-unlicensed`           | Unlicensed Dependency                                       | PR-scoped   | —                                       | Dependency metadata declares no license                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `scpm-license-local-mismatch`                  | License Mismatch                                            | branch-only | —                                       | Manifest license contradicts the shipped license file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-license-missing`                         | Missing License                                             | branch-only | —                                       | Project manifest declares no license                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-license-restricted`                      | Restricted License                                          | PR-scoped   | —                                       | Project license is denied by org policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `scpm-lockfile-missing`                        | Missing Lock File                                           | branch-only | —                                       | Lock file missing for manifest, allowing non-deterministic dependency resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-lockfile-out-of-sync`                    | Manifest And Lockfile Out Of Sync                           | branch-only | —                                       | A required direct npm dependency has no resolution in the sibling npm-shrinkwrap.json or package-lock.json (v1/v2/v3); a non-npm packageManager declaration or competing lockfile without an explicit npm declaration excludes the check                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-lockfile-patched-dependency`             | Dependency Patched At Install Time                          | PR-scoped   | —                                       | A dependency is rewritten by a patch the repository ships (pnpm `patchedDependencies`, the yarn `patch:` protocol), so the code that runs is not the code the lockfile's integrity hash verifies                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `scpm-lockfile-removed`                        | Lock File Removed                                           | PR-scoped   | —                                       | Pull request deletes a lock file whose manifest survives, returning every declared range to whatever the registry serves at install time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `scpm-lockfile-version-drift`                  | Locked Version Outside Declared Range                       | PR-scoped   | —                                       | A committed lock file resolves a dependency to a version the manifest's declared range excludes, so the manifest no longer describes what installs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `scpm-metadata-analysis`                       | Package Metadata Analysis                                   | PR-scoped   | —                                       | Detects suspicious package metadata such as unmaintained, deprecated, or trivial packages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `scpm-metadata-copyleft-license`               | Copyleft License Detection                                  | PR-scoped   | —                                       | Detects copyleft licenses (GPL, AGPL, LGPL, SSPL, EUPL) that may impose viral licensing obligations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-metadata-deprecated-upstream`            | Deprecated Upstream                                         | PR-scoped   | —                                       | Package version is marked deprecated by its registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `scpm-package-manager-integrity`               | Package Manager Integrity Setting Disabled                  | PR-scoped   | —                                       | A package-manager setting re-enables install scripts or switches off the Go checksum database or module proxy, an environment variable turns off image signature or certificate revocation checking, or a build-time fetcher outside the package managers (a Terraform module source or provider, a Terraform CLI provider override, a pre-commit hook revision or its additional\_dependencies) resolves without an immutable pin, removing an integrity control the toolchain ships on                                                                                                                                                                       |
| `scpm-registry-source-trust`                   | Untrusted Package Source                                    | PR-scoped   | —                                       | Dependencies resolve from a host, under a registry configuration, or from a package repository the build file declares for itself (a plaintext Gradle or Maven repository, an `allowInsecureProtocol` opt-out, `mavenLocal` ahead of Maven Central, a composer.json `repositories` entry off Packagist) that cannot be trusted to serve the packages the manifest names; also a committed default-registry redirect (`.npmrc registry=`, `pip.conf index-url`, `.yarnrc.yml npmRegistryServer`, a `Gemfile source`) and NuGet sources configured with no `packageSourceMapping`, and a lockfile entry verified against a broken hash algorithm (`sha1`, `md5`) |
| `scpm-scan-manifest-unreadable`                | Manifest Could Not Be Read                                  | PR-scoped   | —                                       | A dependency manifest could not be parsed or exceeded the scan size cap, so its dependencies were graded by no rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-scripts-cargo-config-exec`               | Cargo Build Executes a Configured Program                   | PR-scoped   | —                                       | A committed .cargo/config.toml names a program Cargo runs during the build (rustc-wrapper, target runner/linker, a shell alias, or a rustflags linker override)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scpm-scripts-agent-config-exec`               | Unpinned Package Launched by an MCP Server Config           | PR-scoped   | —                                       | A project MCP server configuration launches a registry package through npx, uvx or a similar launcher without an exact version, so each developer machine runs whatever the registry serves at launch                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-scripts-install`                         | Install Scripts Detected                                    | PR-scoped   | —                                       | Package has install scripts that execute during installation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `scpm-scripts-remote-add`                      | Unverified Remote ADD                                       | PR-scoped   | —                                       | Dockerfile ADD fetches a remote URL without a --checksum, so the artifact is not integrity-verified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-scripts-shell-install`                   | Unpinned Install In Build Script                            | PR-scoped   | —                                       | Build script fetches or installs dependencies without pinning, a common supply-chain injection vector                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `scpm-scripts-unmanaged-dependencies`          | Dependencies Installed Outside A Package Manager            | branch-only | —                                       | Build scripts install dependencies that no manifest or lockfile records, so no dependency scanner inventories or analyses them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `scpm-suppression-file-changed`                | SCPM Exception File                                         | PR-scoped   | —                                       | The repository carries a `.nullify/scpm-ignore.yml` that lowers or silences supply-chain rules, so a verdict was moved by a repository file rather than by the organisation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scpm-typosquat`                               | Typosquat                                                   | PR-scoped   | —                                       | Package name closely resembles a significantly more popular package, suggesting typosquatting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scpm-unpinned-floating-version`               | Floating Version Specifier                                  | PR-scoped   | —                                       | Dependency uses a floating version specifier that may resolve to different versions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scpm-unpinned-git-dependency`                 | Git/HTTP Dependency                                         | PR-scoped   | —                                       | Dependency is sourced from a git URL, an HTTP URL or any other arbitrary `https://` URL instead of a package registry, bypassing registry security controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Lockfile coverage limits

The missing-lockfile rule skips C# projects with no declared package items, project references, imports, sibling packages.config or ancestor Directory.Build.props, Directory.Build.targets or Directory.Packages.props. Dependency evidence filenames are matched without case sensitivity. This is a check of declared dependencies: SDK-implied framework packages such as NETStandard.Library and Microsoft.NETCore.App alone do not require a finding.

The npm consistency rule checks required direct resolutions, not exact range text or obsolete root metadata. Optional and local dependencies are excluded. Manifests without required direct dependencies skip lock inspection. Malformed manifests and unreadable, unsupported or empty required lock indexes mark this rule incomplete, preventing absence of a detection from retiring an existing finding. Version mismatches remain the separate HIGH version-drift rule; missing resolutions are MEDIUM.


# Threat Intelligence

Nullify researches newly disclosed vulnerabilities and software supply-chain compromises once, for all customers, and then checks each published threat against your own environment: the repositories, dependencies, containers and deployments you have connected.

## How threats are found

Nullify follows public advisory sources, including OSV, GitHub security advisories, the National Vulnerability Database, the CISA Known Exploited Vulnerabilities catalog, EPSS scores and malicious-package reports, and adds its own research. Research publishes only facts it can corroborate from public sources, and every threat keeps the advisory identifiers it is known by.

Not every published threat is announced to every customer. Threats likely to need immediate action, such as an actively exploited critical vulnerability or a fresh malicious-package compromise in an ecosystem you use, start investigations. The rest stay in the catalog, where you can investigate any of them yourself.

## The Threats page

**Threats** lists the shared catalog with your tenant's assessment of each entry:

| Status             | Meaning                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------- |
| Not assessed       | No assessment has run for your tenant                                                    |
| Queued             | An assessment is waiting to start                                                        |
| Investigating      | An assessment is running; its progress streams live                                      |
| Affected           | The latest assessment found the threat in your environment                               |
| Not affected       | The latest assessment, on complete and current inventory, found no exposure              |
| Unknown            | The inventory was incomplete or out of date, so the result is not a clean bill of health |
| Failed             | The latest assessment did not complete; you can retry it                                 |
| Not run            | An assessment was queued but never started within its window; you can retry it           |
| Automation off     | Automatic investigations are turned off for your tenant                                  |
| Advisory withdrawn | The source advisory was withdrawn                                                        |

An assessment is tied to the research it read. When the threat's facts change materially, for example a new affected package or version range, the assessment is marked outdated and investigations whose answer could change run again.

## Automatic and manual investigations

Automatic investigations are a tenant setting: **Settings → Threat Investigations → Automatically investigate new threats**. They are off by default, and changing the setting needs configuration-write access.

Manual actions are always available from the catalog: **Investigate my environment**, **Retry** after a failure, and **Re-investigate** to run a new assessment version. A confirmed exposure to a critical, known-exploited vulnerability with a fixed release opens a remediation campaign.

## Investigation results

An investigation records which repositories and packages are affected, how complete the inventory evidence was, and a report with remediation guidance. Progress streams to the page while it runs. Results can be posted to your Slack or Microsoft Teams destinations; see the [Slack](/connectors/slack) and [Microsoft Teams](/connectors/microsoft-teams) connectors.

## Advisory identifiers

* A threat with a CVE, GitHub advisory or OSV `MAL-` id is known by those ids.
* A threat with none, such as a package compromise with no advisory yet, gets a permanent Nullify id, `NULLIFY-` followed by hexadecimal characters. It keeps that id if a CVE is assigned later.
* A threat you report is identified as `NULLIFY-R-…` until it links to a published threat. See [Reporting a threat](/capabilities/threat-intelligence/reporting-a-threat).

## Related capabilities

* [Dependency Analysis](/capabilities/code-reviews/dependency-analysis) reports known vulnerabilities in your dependencies as findings on every scan.
* [Supply Chain Posture Management](/capabilities/scpm) flags dependencies at a version Nullify's malware index has confirmed malicious.
* [Security Program Management](/capabilities/program-management) turns a confirmed exposure into a campaign.

## Limits

* An incomplete inventory gives **Unknown**, never **Not affected**. A threat that has not been assessed is not evidence that you are unaffected.
* Shared research is not billed to your tenant. Assessments of your environment count against your AI budget.

## API

See [Threat intelligence API](/api-reference/api-reference/manager/threats).


# Reporting a Threat

Report a threat when you know of a public advisory, or an active campaign against software packages, that is missing from the Threats catalog. Your own tenant starts investigating straight away; the report is then checked against public sources before anything is shared.

## Report types

* **Advisory**: the URL of a public advisory (GitHub security advisories, NVD or OSV), with an optional CVE.
* **Campaign**: a title, a description, at least one public reference URL, and optionally CVEs and the affected packages and versions.

## What happens to a report

1. The report is matched to an existing threat when it names one Nullify already holds. Otherwise it gets a `NULLIFY-R-…` id that identifies it to you.
2. Nullify checks it against public sources. Only facts it can independently corroborate from public sources are ever published to other customers; a report on its own never publishes a threat.
3. The report's status shows where it is:

| Status                                                               | Meaning                                                      |
| -------------------------------------------------------------------- | ------------------------------------------------------------ |
| Queued, Researching                                                  | Accepted and being checked                                   |
| Published, Existing                                                  | Verified and in the catalog, new or already known            |
| Pending                                                              | A campaign report waiting to be matched                      |
| Matched                                                              | A campaign report matched to a public malware advisory       |
| Verification failed, No verified packages, Not found, Not verifiable | Public sources did not support it, so it was not shared      |
| Research unavailable                                                 | Research could not run; you can resubmit once                |
| Withdrawn                                                            | The matched advisory was withdrawn                           |
| Submission failed                                                    | The report never reached verification; you can resubmit once |

## Privacy

Your report's description, any repository details and any evidence are never shown to other customers, and other customers never learn who reported a threat. Do not include secrets or internal details in a report.

## Limits

* Reports are rate-limited per tenant. A report over the limit is refused with HTTP 429; wait and submit again.
* Each report can be resubmitted once after a failed submission or when research was unavailable.

## API

See [Reporting a threat](/api-reference/api-reference/manager/threats#reporting-a-threat) in the Threat intelligence API.


# Bug Hunts

## Overview

Nullify continuously watches your external attack surface the way an offensive security engineer would — discovering internet-facing assets, fingerprinting the services running on them, and probing for exposures before an attacker finds them. Bug Hunts combine passive reconnaissance, active service discovery, and protocol-aware analysis, and they lean on everything Nullify already knows about your code, dependencies, and cloud to focus on what actually matters.

Unlike a one-off scan, a Bug Hunt is a standing watch: Nullify re-runs it on a cadence, compares each run against the last, and only surfaces what has **changed**.

## How Bug Hunts run

When Bug Hunts are enabled for your tenant and a valid scope and schedule are configured, hunts can run automatically. Nullify runs each hunt on a recurring cadence and paces itself to your program's budget: as the surface stays stable, it settles into a lighter rhythm; when new exposure appears, it tightens back up. You can also trigger a hunt — or a single reconnaissance suite — on demand at any time.

### Change-only findings

Every run is diffed against the previous one. Nullify surfaces findings that are **New** or **Reopened**, and stays quiet about assets that are **Unchanged** or have been **Resolved**. This keeps a Bug Hunt from re-alerting on the same known exposure run after run, so the findings you see are always the delta since you last looked.

Your triage decisions persist across every future run. When you allowlist an asset, archive a finding, override its severity, set a priority, or leave a note, that decision travels forward — a rescan won't undo it or re-raise something you've already judged.

## What Nullify looks for

### Reconnaissance

Nullify maps your attack surface from the outside in:

* **Subdomain discovery** — passive sources such as certificate-transparency logs and DNS records, plus active discovery with adaptive wordlists.
* **Service and port discovery** — low-noise scanning across discovered hosts to find exposed services.
* **Service fingerprinting** — technology-stack and version identification, banner analysis, and HTTP inspection.

### Exposure and misconfiguration checks

Across discovered services Nullify checks for subdomain takeover, exposed or sensitive files, missing or weak transport security and certificate issues, absent security headers, exposed admin or debug interfaces, and other common internet-facing weaknesses. It performs protocol-aware analysis for web, database, infrastructure, container-orchestration, and cloud service endpoints — testing authentication, reviewing configuration, and checking for known weaknesses and weak credentials.

### Context from the rest of Nullify

Bug Hunts are sharper because they draw on the rest of the platform:

* **Code review findings** highlight likely injection points and vulnerable patterns worth probing from the outside.
* **Dependency findings** identify exploitable CVEs on exposed services and inform which exposures matter most.
* **Cloud context** contributes topology, reachability, and code-to-cloud mapping so an exposure can be tied back to the application and blast radius it affects.

## Intensity levels

Intensity controls how much tooling Nullify brings to a hunt:

1. **Low** — a reduced discovery and enumeration toolset. This is not a guarantee of zero production impact.
2. **Medium** — most of the available tooling, for a deeper assessment.
3. **High** — the full toolset, including heavier, more aggressive techniques such as brute forcing.

Choose intensity deliberately: a manual scan falls back to the saved intensity, then `medium` if no valid value is available. Intensity is not a substitute for scope, rules of engagement, or authorization. Some suites send active probes and can affect a service; agree a suitable environment and testing window.

## Controls

You stay in control of scope and noise:

* **Scope** — define in-scope assets (domains, IP ranges, CIDR blocks) and exclude assets you don't own or don't want tested (third-party services, partner networks).
* **Per-suite toggles** — enable or disable individual reconnaissance and analysis suites.
* **Severity floors** — set a minimum severity per vulnerability class so low-value classes stay quiet.
* **Per-finding triage** — allowlist, archive, override severity, set priority, or annotate any finding; decisions persist across future runs.

Nullify only tests assets you are authorized to test. Before a hunt runs against a target, ownership must be proven, and out-of-scope targets (loopback, private-network, and cloud-metadata addresses) are rejected.

## Evidence

Bug Hunt findings come with the reconnaissance evidence behind them — the discovered services and versions, open ports, technology fingerprints, and the exposure detail — plus a prioritized path to remediation. Selected authenticated and backend suites can perform active testing too. Promote a discovered application to a [Pentest](/capabilities/pentests) for a dedicated engagement with its own configuration and reporting.

## Where findings go

Bug Hunt findings flow into the same places as the rest of Nullify's work: the dashboard, Jira and other ticketing with ownership mapping, Slack and Teams notifications for critical attack-surface changes, and [Security Program Management](/capabilities/program-management) for campaign-driven attack-surface reduction. Discovered applications can be promoted directly into [Pentest](/capabilities/pentests) targets.

## Configuration

Configure Bug Hunts during [Onboarding](/getting-started/getting-started):

* Define in-scope assets (domains, IP ranges, CIDR blocks).
* Specify excluded assets (third-party services, partner networks).
* Link bug bounty program data if you run one.
* Adjust intensity, per-suite toggles, and severity floors.

## Suites, ownership, and rules of engagement

The suite catalog includes DNS enumeration, port scanning, web fingerprinting, Nuclei checks, browser exploration, authenticated walks, SPA checks, malware scanning, and lightweight or full backend pentests. Availability and dispatch depend on your deployment, enabled suites, credentials, and scope. A catalog entry does not mean every hunt runs it.

Before execution, review allowed and excluded targets, permitted techniques, rate limits, time windows, and the current rules-of-engagement version. Ownership proofs can use DNS TXT, an HTTP file, a meta tag, or a supported program-managed verification path. Confirm the specific proof and scope accepted for your tenant; redirects and resolved destinations remain subject to scope enforcement.

Importing a public HackerOne or Bugcrowd program produces a preview of scope and rules. Review the result and explicitly save it: import alone does not authorize testing or update your configuration. Third-party assets mentioned by a program are not automatically authorized.

The [Bug Hunts API](/api-reference/api-reference/bug-hunts) covers config, scans, suite runs, program imports, findings, and promotions. The suite-run history endpoint currently returns an empty list, so use scan history for execution evidence rather than treating an empty suite history as proof that nothing ran.


# Pentests

## Overview

Nullify runs on-demand penetration tests against REST and GraphQL APIs. To configure one, follow [Preparing for an Engagement](/capabilities/pentests/preparing-for-an-engagement).

## Triggering Pentests

Pentests run on demand — start one against a specific application whenever you need it, with full control over the scan parameters and results tracked in real time. Teams typically trigger a pentest on new application deployments, major feature releases, [Security Program Management](/capabilities/program-management) campaigns, or to validate a remediation.

## Supported Application Types

Nullify pentests **REST and GraphQL APIs**:

### REST APIs

* OpenAPI/Swagger schema-based testing.
* Automatic schema discovery (checks common locations such as `/openapi.json`, `/swagger.json`, `/api-docs`).
* Fuzzing of path parameters, query strings, and request bodies.
* Intelligent, schema-aware API testing that combines targeted vulnerability probing with Nullify's own reasoning agents.

### GraphQL APIs

* Introspection query analysis.
* Query testing.
* Schema-based attack generation.

## Authenticated Testing

### Authentication Methods

* **Bearer Tokens**: JWT, OAuth2 access tokens
* **Basic Auth**: Username/password pairs
* **OAuth 2.0 / OpenID Connect**: settings agreed with Nullify per engagement
* **Custom Headers**: API keys, custom authentication schemes
* **Login Flows**: POST to a login endpoint with credentials

Configure credentials as described in [Preparing for an Engagement](/capabilities/pentests/preparing-for-an-engagement#3-identities).

## Request Chaining & Multi-Stage Exploitation

Nullify can investigate vulnerabilities through multi-stage exploitation within the engagement scope:

> This section describes exploit chaining *within* a pentest engagement. It is a different thing from [Exploit Validation](/capabilities/pentests/exploit-validation), the continuous capability that validates individual code findings against your deployed service.

### Stateful Session Management

* Preserves authentication context throughout a chain.
* Tracks session state and cookies.
* Supports multi-step workflows.

### Fuzzing

* Substitutes fuzz tokens across URLs, headers, query params, and bodies.
* Analyzes responses for status, size, and timing anomalies.

### Exploit Chain Execution

An investigation can discover an endpoint, establish a test identity, probe an input, compare the result against a second identity, and capture the request/response evidence. The permitted depth depends on the engagement's scope and mutation consent. Use disposable test data where write testing is explicitly authorized.

### Response Analysis & Iteration

* Parses responses (status, headers, body).
* Extracts data from responses for subsequent requests.
* Analyzes error messages for information disclosure.
* Adapts strategy based on application behavior.

Runtimes vary with the size and complexity of the target; deep exploit chains can run for an extended period.

This is the exploitation Nullify performs *within* a single pentest. To prove or disprove an individual code-review or dependency finding on its own — driven by your own policies, without launching a full pentest — see [Exploit Validation](/capabilities/pentests/exploit-validation).

## Vulnerability Coverage

Pentests validate:

* **Injection Flaws**: SQL, NoSQL, Command, LDAP, XPath
* **Broken Authentication**: Weak passwords, session fixation, token manipulation
* **Broken Authorization**: IDOR, privilege escalation, missing access controls
* **Security Misconfiguration**: Debug mode, default credentials, verbose errors
* **Business Logic Flaws**: Price manipulation, workflow bypass, race conditions
* **SSRF**: Server-side request forgery with cloud metadata access
* **XXE**: XML external entity injection
* **File Upload**: Malicious file upload and execution

## Context from Code Review

Pentests are informed by everything Nullify has already learned:

* **Code review findings** — known injection points and vulnerable patterns are prioritized for testing, and code-level context guides payload selection.
* **Dependency findings** — exploitable CVEs (for example Log4Shell) are validated against the live application.

## Application Management

Every pentest is associated with an **Application**:

* Name and description
* Targets: host, port and protocol
* Web services: repository and path inside the repository, mapped to targets
* Credentials attached to each web service

## Evidence & Reporting

Pentest findings include:

* **Request/Response Pairs**: full HTTP traffic demonstrating the vulnerability.
* **Exploit Steps**: detailed reproduction instructions.
* **Impact Analysis**: business impact and blast radius.
* **Fix Guidance**: specific remediation recommendations.
* **Screenshots**: visual proof of exploitation where applicable.
* **Video Recordings**: a walkthrough of the exploit chain where applicable.

## Safety

A run can be stopped at any time from the dashboard.

## Where findings go

Review findings in the dashboard. Configure ticketing and notifications as described in [Configuration – General](/configuration/configuration-general).

## Configuration

Configure pentests in the Assessment step of [Onboarding](/getting-started/getting-started):

* **Applications**: define applications and their targets.
* **Test credentials**: add authentication credentials for testing, then use **Test sign-in** to check each one logs in.
* **Nullify outgoing IP addresses**: allowlist the listed addresses on any firewall, WAF or IP allowlist in front of the targets.

## Pentests vs Bug Hunts

| Aspect        | Bug Hunts                                                              | Pentests                                          |
| ------------- | ---------------------------------------------------------------------- | ------------------------------------------------- |
| **Scope**     | External attack surface (domains, IPs)                                 | Known applications (APIs)                         |
| **Discovery** | Subdomain enumeration, service discovery                               | API schema analysis, endpoint mapping             |
| **Depth**     | Selected discovery, authenticated, malware, and backend-testing suites | Application-focused testing and exploit chains    |
| **Evidence**  | Service inventory, exposure detail                                     | Request/response pairs, reproduced exploit chains |
| **Cadence**   | Continuous, change-only surfacing                                      | On-demand                                         |

## Surface discovery and authorization coverage

The pipeline can combine a supplied or discovered API contract with application crawling, JavaScript endpoint hints, and routes inferred from connected source. Inferred routes are candidates to validate, not proof that the deployed endpoint exists. Surface and stage coverage distinguish tested, excluded, unavailable, and unresolved paths.

Authorization-matrix testing compares permitted identities across endpoints and object access. Missing or invalid credentials reduce what can be established. Mutation testing requires explicit consent as well as the relevant test configuration; supplying an administrator credential alone does not authorize arbitrary writes. The public CLI and the hosted workflow expose different controls, so arrange advanced matrix and mutation settings with your Nullify contact rather than adding undocumented flags.


# 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](/capabilities/pentests/preparing-for-an-engagement).

## Dashboard

1. Go to **Applications**, select **Add application**, and enter its name and description.
2. On **Targets**, select **Add target**, enter the host, port and protocol, and select the application. Give any API path prefix to your Nullify contact. Each application resolves to one target URL.
3. Attach one credential per identity, then validate each one before starting.
4. If prompted, select **Run readiness check** before starting.
5. Start the run. Review progress and results in the dashboard. Configure ticketing and notifications as described in [Configuration – General](/configuration/configuration-general).

![Current Start assessment dialog](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-cd11ef526067563797d18321aaf5585c2be561d9%2Fstart-assessment.png?alt=media)

The current dashboard calls this action **Start assessment**. Select the registered application; readiness checks can hand the request to Nullify for manual handling. The screenshot shows the dialog before selection.

Creating applications and credentials requires the **Admin** role. Starting and stopping scans requires **Editor**. Contact your Nullify contact to arrange dashboard access.

Nullify discovers your API specification automatically where it can (see [Supported Targets](/capabilities/pentests/supported-targets)). 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:

```bash
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](/configuration/configuration-api) 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](/cli/cli/authentication).

Run a pentest:

```bash
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 identity

Static headers test one identity. For cross-identity authorization testing, provide credentials as described in [Preparing for an Engagement](/capabilities/pentests/preparing-for-an-engagement). Pass a config file with `--auth-config`:

```bash
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 identity; give each entry a distinct `roleName`:

```json
{
  "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](/capabilities/pentests/private-networks).

## Continuous Integration

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

```yaml
- 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"
```

`nullify ci gate` checks existing open findings; it does not wait for this scan or restrict results to new findings. `nullify ci report` produces Markdown which your pipeline can publish. See [CI gate limitations](/cli/cli#ci-gate-and-report).

Run pentests on release branches or a schedule.

## What to expect

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.

## Readiness, budgets, and scan states

For hosted runs, review readiness and the application estimate before submitting a scan. The [Pentests API](/api-reference/api-reference/pentester) exposes application readiness, `GET /dast/pentest/applications/{applicationId}/estimate`, and `GET /dast/pentest/budget`. An estimate is a planning input, not a promise of complete coverage or a fixed invoice.

| API status             | Meaning for the operator                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `queued`               | Accepted for later execution.                                                                                                             |
| `in progress`          | Execution is underway. The serialized value contains a space.                                                                             |
| `stopping`             | A stop request is being processed.                                                                                                        |
| `completed`            | The workflow completed; inspect findings, stages, and coverage.                                                                           |
| `cancelled`            | The run was cancelled.                                                                                                                    |
| `failed`               | The run failed; inspect the recorded error.                                                                                               |
| `aborted_config_error` | Configuration prevented execution. Correct it before retrying.                                                                            |
| `human_fallback`       | Automated execution handed off for operator attention.                                                                                    |
| `awaiting_manual`      | The request awaits manual handling, including deployments with self-service execution disabled. It does not mean an operator has started. |
| `skipped`              | The run was skipped; inspect the reason.                                                                                                  |

A terminal state alone does not establish that every endpoint or identity was tested. Use the run's activity, state, evidence, and report together. DAST autofix uses its own state/activity workflow; do not substitute the SAST/SCA cache routes.


# Preparing for an Engagement

One application is one target URL. Each service behind it, including downstream services, is a separate web service.

## Checklist

|   | Item                                             | Required             |
| - | ------------------------------------------------ | -------------------- |
| 1 | Target base URL, including the API path prefix   | Yes                  |
| 2 | API specification served by the test environment | Strongly recommended |
| 3 | Test identities                                  | Strongly recommended |
| 4 | Test records for those identities                | Strongly recommended |
| 5 | Nullify outgoing IP addresses allowlisted        | Yes                  |
| 6 | Rate limits relaxed for those IPs                | Recommended          |
| 7 | Repository and path per service                  | Recommended          |
| 8 | Authorization and test window                    | Yes                  |

## 1. Target

The full base URL of the API, including any path prefix: `https://api.staging.example.com/api/v2`, not `https://api.staging.example.com`. For GraphQL, the endpoint URL. In the dashboard the target takes the host, port and protocol; give the path prefix to your Nullify contact.

Use a disposable staging or QA environment. The pentester sends real attack traffic and may create, modify, or delete data.

If the service is not reachable from the internet, see [Running in Private Networks](/capabilities/pentests/private-networks).

## 2. API specification

Serve the specification from the test environment under the base URL at one of `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, `/api-docs`, `/v3/api-docs`, `/api/openapi.json`, `/docs/openapi.json`, or enable GraphQL introspection. On a CLI run you can also pass a file with `--spec-path`.

OpenAPI 3.x or Swagger 2.0, JSON or YAML.

## 3. Identities

Provide:

* One identity per role or permission level in the application, with a sentence on what it may and may not do in the credential's description
* For a role that owns records, two identities with distinct credential names and separate records
* For a multi-tenant application, an identity in a second tenant

Two authenticated identities is the minimum for cross-identity authorization testing.

For each identity:

* Username and password, and the login URL for form logins

Use dedicated test accounts valid for the whole engagement window, with multi-factor authentication off.

Configure username and password or HTTP basic authentication in the dashboard. Give API-key, bearer-token, OpenID Connect and OAuth 2.0 settings, a non-standard login form, or a required second factor to your Nullify contact before the engagement.

Validate each credential in the dashboard before the engagement: **Test sign-in** in the onboarding Assessment step checks every listed credential. Review any result that is not successful with Nullify before starting.

A credential with **Use in scans** switched off never logs in, in a pentest or in exploit validation. A run whose mapped credentials are all switched off stops rather than testing unauthenticated; unlink them from the application to test without logging in.

## 4. Records

Each identity needs records of the kinds the API serves, so that access can be compared across identities. Unlock any account state that endpoints depend on, such as verified contact details or completed onboarding.

## 5. Outgoing IP addresses

The dashboard lists Nullify's outgoing IP addresses, with a **Copy** button, in the Assessment step of onboarding and on each target's validation page. Allowlist them by IP address on any WAF, API gateway, or secure web gateway in front of the target, and in security groups.

If out-of-band checks are in scope, also allow the outbound callback domains your Nullify contact gives you.

## 6. Rate limits

Relax or exempt rate limits and bot mitigation for the Nullify outgoing IP addresses during the test window.

## 7. Repositories

Give your Nullify contact the repository and repository path for each service behind the target, including downstream services, and which test credentials belong to each.

## 8. Authorization and test window

Agree with your Nullify contact before the run:

* Written authorization covering the permitted targets and actions; give any exclusions to your Nullify contact before the run
* Start and end of the test window, with timezone
* A named contact on your side for the duration of the run

A run can be stopped at any time from the dashboard.

## Preflight

If prompted, select **Run readiness check** before starting.

## Confirm the testing boundary

Record allowed targets, path scope, excluded operations, test identities, and whether any mutation testing is authorized before starting. Provide disposable accounts and data for approved write tests. Do not infer permission to modify production data from the presence of administrator credentials.

[Exploit Validation](/capabilities/pentests/exploit-validation) is read-only unless write risk is [accepted](/capabilities/pentests/exploit-validation#accepting-write-risk-on-a-target) for a specific target you have confirmed as non-production, either by an administrator on your side in the dashboard or by Nullify staff recording your written approval. Include that decision in the written authorization. Production targets are never attacked.

Review [supported targets](/capabilities/pentests/supported-targets), [private connectivity](/capabilities/pentests/private-networks), and the [readiness and scan-state guide](/capabilities/pentests/engagement-workflow#readiness-budgets-and-scan-states). A discovered route or successful login does not establish complete authorization coverage; inspect the final stage and identity coverage with the findings.


# Exploit Validation

## Overview

Exploit Validation proves whether an individual finding is *actually* exploitable by attacking a running target — without launching a full [Pentest](/capabilities/pentests). When code review flags an injection point, or dependency analysis surfaces an exploitable CVE, Nullify can drive a focused exploitation agent against the deployed application, read the vulnerable source, reach the code path over real HTTP, and record the result as evidence.

Where a Pentest goes *broad* — mapping an application and hunting for anything exploitable — Exploit Validation goes *narrow*: one already-known finding, one verdict, backed by proof. It turns a theoretical "this looks reachable" into a confirmed "this was reproduced" (or a defensible "this could not be exploited").

Validation runs against the Web Services and Targets you register in your inventory, and it only runs when a **policy** you control says it should.

{% hint style="info" %}
Exploit Validation reuses the same evidence-first exploitation engine as Pentests, scoped to a single finding. A validated finding carries the same reproduction evidence you would get from a full engagement.
{% endhint %}

## How it works

1. **A finding becomes a candidate.** During [Triage](/capabilities/triage), a code-review (SAST) or dependency (SCA) finding is assessed as reachable and likely exploitable.
2. **Policies decide whether to run.** Nullify checks your Exploit Validation [policies](#policies). A policy must be both enabled and *armed* before it can start anything. If an armed policy matches the finding — by finding source and validation window — and the finding isn't inside its revalidation cooldown, validation is started against a single non-production target.
3. **A target is resolved.** The finding's repository is matched to the Web Services named in the policy. Nullify attacks exactly one target per run, and only a target you have **confirmed as non-production** — a target left unclassified is refused just like a production one, with a distinct reason recorded. Nullify records which target it was permitted to attack.
4. **The agent attempts the exploit**, within a fixed boundary (see below). A focused agent reads the vulnerable code, discovers the reaching endpoint, and sends bounded HTTP requests, using out-of-band callbacks where blind exploitation requires it. Requests are read-only unless you have accepted writes for that target (see [What validation is allowed to do](#what-validation-is-allowed-to-do)). Credentials are available only under an explicitly granted authenticated-session capability; anonymous validation does not inherit them. Captured credential material is subject to redaction.
5. **An outcome is recorded.** The agent returns a verdict with proof. The result is written back onto the finding's triage, marks a confirmed finding as **Exploit validated**, and appears as an **attempt** on the Exploit Validation page. It does not yet change the finding's exploitability, priority or severity (see [How validation feeds triage](#how-validation-feeds-triage)).

The **Exploit Validation** page holds both halves: the policies that govern validation, and the attempts that have run.

## Outcomes

Every validation run is recorded as an **attempt**. While a run is underway the attempt shows as **In progress**; when it finishes it lands on one of these outcomes:

| Outcome              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Confirmed**        | Nullify proved exploitability with a concrete HTTP response or an out-of-band callback. The finding is exploitable.                                                                                                                                                                                                                                                                                                                                                                   |
| **Not Exploitable**  | The correct reachable code path was exercised with the context it needed and the exploit still did not work — a strong negative signal. Reported only when the run actually sent requests.                                                                                                                                                                                                                                                                                            |
| **Cannot Determine** | No verdict was reached. Either validation was blocked (the target was unreachable, access was blocked, authentication was required, a rate limit or request budget was hit, or context was missing), the vulnerability could not be reached within what validation is allowed to send (see [What validation is allowed to do](#what-validation-is-allowed-to-do)), or Nullify declined to carry the agent's result forward because it could not be matched to the traffic of the run. |

A **Cannot Determine** result is never a pass or a fail on your application. The recorded reason tells you which of the three it is:

* **The run was blocked.** Unreachable target, blocked access, auth required, budget exhausted, and so on. The test setup needs attention, and a re-run can then reach a real verdict.
* **Out of scope.** The vulnerability is only reachable with a request validation is not permitted to send on this target, such as a form submission or another state-changing request on a target without write acceptance. Nullify does not attempt it, and deliberately does *not* report it as Not Exploitable, because a request that was never made is not evidence of anything. The finding keeps whatever priority triage gave it.
* **Downgraded by Nullify.** The agent reported a result its own traffic does not support: it claimed an exploit without naming a request the run actually made or a callback that actually arrived, or it reported the finding not exploitable without the run having sent a single request. The report is kept, with a note saying so, and the claim is not carried onto the finding. This is deliberately strict in both directions — an unproven Confirmed moves your team onto a vulnerability nobody has shown to be real, and an unearned Not Exploitable pushes a real one down the queue.

### Declined

An attempt shows as **Declined** when validation could not log in to your application, so it never tested the finding. The reason says which:

* **Credential login failed.** A credential configured for the target is missing, or your application rejected it. Fix the credential in the target's configuration.
* **Login agent failed.** Nullify's login step broke before it could tell whether your credentials work. This is on Nullify's side; nothing needs changing in your configuration.

A declined finding is held for 24 hours before it is validated again, because every retry is a real login attempt against your application. The finding keeps its previous verdict, shown beside the decline. Once the cause is fixed, Nullify can release the hold so the finding is validated straight away; the attempt then shows as **Released by operator** until the next validation runs.

The attempts table lists each attempt's finding, source, outcome, confidence, any exploited CVE, and when it was validated — newest first.

## What validation is allowed to do

Validation sends real traffic at a real application, so what it may send is fixed rather than left to the agent:

* **Read-scoped by default.** The baseline grants `anonymous_read` and limits exploit requests to allowed read methods and inputs. Granting `authenticated_session`, where enabled, adds the narrowly scoped login/session setup needed for authorized credentials; it does not grant general mutation testing. A nominally read-only request can still trigger poorly designed application behavior, so confirmed non-production targets remain required.
* **Writes only where you have accepted them.** On a target you have confirmed as non-production and for which you have accepted write risk, validation may send the `POST`, `PUT`, `PATCH` or `DELETE` request a finding's exploit needs. It prefers the least-destructive proof, registers each write before sending it, and the verdict lists every write it sent, including one that may have been committed without a response. Acceptance is per target and you record it yourself, or Nullify staff record it on your behalf; see [Accepting write risk on a target](#accepting-write-risk-on-a-target). It is cleared if the target's host, port or protocol changes or the target stops being confirmed non-production. A production target is never attacked, with or without acceptance.
* **One target.** Only the host and port of the target the policy authorised. A request to any other host or port, including one reached by following a redirect, is refused before it is sent.
* **Refused before the request leaves.** Both limits are enforced at the network boundary, not by asking the agent to behave. A request outside them never reaches your application.

The trade is that, on a target without write acceptance, a vulnerability only reachable through a state-changing request cannot be proven; it comes back as **Cannot Determine**, out of scope, rather than as a false negative.

## Accepting write risk on a target

Write acceptance is a decision about one target, made by a person. Without it, validation on that target stays read-only.

**Who can accept.** An administrator on your side (today, the admin role). Accepting records who accepted, when, and which version of the warning they read. Service accounts and API tokens cannot accept, because the record has to name a person. Revoking needs only the configuration write permission.

**If your administrator approves outside the dashboard.** If you tell your Nullify contact in writing (for example on Slack) that write risk is accepted for a target, a verified member of Nullify staff can record the acceptance for you. They must name the person at your company who approved and link the message or ticket that shows it. The panel then reads "Accepted (time) by (staff member) (Nullify staff) on behalf of (your contact)" with the evidence shown as a link to its host, and anyone who can open the target sees it. Nullify staff can only do this for a tenant they have been granted access to, and Nullify does not verify the link or the contact: it is Nullify's attestation of what you told it. Your own administrator can revoke it at any time.

**Before you accept.** The target must be [confirmed as non-production](#how-it-works). A production or unclassified target cannot be accepted.

**In the dashboard.** Open **Applications → Targets**, edit the target, and find **Exploit validation writes** under the classification. Select **Review and accept write risk**, read the warning, confirm the endpoint shown is the one you mean, tick the acknowledgment and select **Accept write risk**. The acceptance is bound to the saved endpoint: if you have unsaved host, port or protocol edits in the form, save them first.

**What the warning says.** In summary: validation may send state-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) to this target, including ones that create, modify or delete records, trigger downstream workflows, and payloads that are destructive or time-based. These are real writes that Nullify records before sending and lists in the verdict, but does not reverse. The acceptance covers this target only, while it stays confirmed non-production at the same host, port and protocol. Accept it only for a staging or test environment whose data you are willing to have modified. The full text is shown in the dialog and returned by the API.

**When it takes effect.** Validation runs authorized after the acceptance is recorded can send writes. A run that was already authorized stays read-only.

**Revoking.** Select **Revoke for new runs** on the same panel. Runs that have not started send no writes. A validation that is already running is not stopped and keeps the writes it started with, and revoking does not undo changes already made.

**Updated warning.** If Nullify updates the warning text, earlier acceptances stop applying (the panel shows **Warning outdated**) until someone accepts the new text.

**API.** `GET`, `PUT` and `DELETE` on `/dast/targets/{targetId}/exploit-validation-consent` read, accept and revoke the acceptance; `PUT` takes the warning version and the endpoint you reviewed. Accepting records who accepted, so it is done in the dashboard or through the API as a signed-in person with the arming permission; revoking needs only the configuration write permission. The read response says who accepted and, for an acceptance recorded by Nullify staff, the customer contact and the evidence link.

## Evidence

Every validated finding carries its exploit-validation report inline, on the finding itself: the outcome, Nullify's confidence, how long the run took, the endpoints it tested, a runnable **reproduction script**, and a written report covering the vulnerability, how it was exploited, the impact, and the fix — followed by the proof-of-exploit requests themselves.

Because the reproduction script is a plain shell script against your own environment, you can re-run Nullify's proof yourself — and re-run it after a fix to confirm the exploit no longer works.

## Policies

Policies are how you control **whether, when, and against what** Exploit Validation runs. Validation attempts are live LLM-driven exploitation runs, so nothing fires until a policy you have configured matches a finding. A finding is validated only when at least one **enabled and armed** policy matches it and its authorization is still valid.

Each policy defines:

| Setting                   | What it controls                                                                                                                                                                                                                                                     |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                  | A label for the policy.                                                                                                                                                                                                                                              |
| **Policy enabled**        | Turns the policy on or off. Disabled policies never start exploit validation.                                                                                                                                                                                        |
| **Policy armed**          | Separate from enabled, and required. Enabled means the policy is configured; armed means validation may send real traffic at your target. A policy is created unarmed, and arming is a deliberate step rather than a setting you can flip in the normal policy form. |
| **Finding sources**       | Which sources the policy applies to — **SAST** (source-code vulnerabilities), **SCA Dependencies** (vulnerable open-source dependencies), or both. At least one is required.                                                                                         |
| **Web services**          | Which registered Web Services validation may run against. At least one is required — this is how a finding's repository is mapped to a live target to attack. Pick existing services from your inventory, or create one inline.                                      |
| **Validation window**     | The days and local-time window in which new validations may *begin* — for example weekdays 09:00–17:00 in `Australia/Sydney`, or "all day" on the days you select.                                                                                                   |
| **Revalidation cooldown** | How many days before the same finding can be validated again (default 30, minimum 7). Prevents the same finding from being re-attacked on every scan.                                                                                                                |

![Current validation-policy dialog](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-16dbfa16b6fb78e5fa21e9ab0bf4dd09638383c3%2Fvalidation-policy.png?alt=media)

This sample shows the required web-service setup before the policy can be created. Policy creation and arming remain separate operations.

Two details worth knowing about the validation window: it gates when a validation may **start**, so a run already underway is allowed to finish rather than being cut off at the boundary; and an overnight window (one whose end time is earlier than its start) belongs to the day it *starts* on.

Findings are also held to a severity and exploitability floor, so low-severity or unlikely-to-be-exploitable findings aren't attacked. By default a finding must be **High** severity or above and assessed as **Likely** exploitable by [Triage](/capabilities/triage); where the controls are available you can tune both floors per policy.

When a finding is proposed for validation, Nullify keeps only the policies that are enabled, armed, and match on finding source, validation window, and those floors. If any match, it then checks the finding's most recent attempt against the cooldown, and resolves the matching web services to targets. Exactly one target is attacked, and only one you have confirmed as non-production. If nothing matches — no armed policy applies, the finding is inside its cooldown, the finding is no longer live (fixed, dismissed, superseded), no matching policy has a web service for the finding's repository, or the only targets are production or unclassified — validation is skipped and the reason is recorded (a production and an unclassified target are refused under separate reasons).

## Authorization flow

```mermaid
flowchart TD
    Finding["Eligible SAST or SCA finding"] --> Policy{"Matching policy<br/>enabled and armed?"}
    Policy -->|No| Skip["Skip and record reason"]
    Policy -->|Yes| Target{"One authorized target<br/>confirmed non-production?"}
    Target -->|No| Skip
    Target -->|Yes| Consent{"Current consent<br/>and supported capabilities?"}
    Consent -->|No| Skip
    Consent -->|Yes| Boundary["Enforce destination and request scope<br/>before target traffic"]
    Boundary --> Evidence["Capture evidence and record outcome"]
```

## How validation feeds triage

The validation result is stored on the finding's [Triage](/capabilities/triage) record with its proof. A **Confirmed** outcome marks the finding **Exploit validated**, which you can filter findings on. A verdict does not yet change the finding's exploitability, priority or severity, in either direction: a **Confirmed** finding keeps the ranking triage gave it, and so does a **Not Exploitable** one.

## Where to find it

In the current dashboard, open **Settings → Exploit validation** when enabled for your tenant. Older dashboards expose the page under **Assessments**. From there you can:

* Create, edit, enable/disable, and delete **validation policies**.
* Review every validation **attempt**, newest first, with its outcome and confidence.
* Jump from an attempt straight to the finding it validated.

Each validated finding also shows its full exploit-validation report inline, in the finding's own detail view.

## Running validation via the API

Exploit Validation is available through the [Nullify API](/api-reference/api-reference) under the `/dast/exploit-validation` namespace — list attempts, manage policies, and request validation for a specific finding.

## Exploit Validation vs Pentests

| Aspect       | Exploit Validation                                   | Pentests                                                            |
| ------------ | ---------------------------------------------------- | ------------------------------------------------------------------- |
| **Scope**    | One known finding (from code review or dependencies) | A whole application                                                 |
| **Goal**     | Prove or disprove a single finding's exploitability  | Discover and exploit anything reachable                             |
| **Trigger**  | Policy-driven, off the back of triage                | On-demand                                                           |
| **Depth**    | A focused attack on one code path                    | Endpoint mapping, fuzzing, and multi-stage exploit chains           |
| **Evidence** | Reproduction proof for one finding                   | Request/response pairs and reproduced exploit chains across the app |

## Arming and consent

Arming is a separate API operation with a dedicated permission, consent revision, and safety-contract version. The default capability is `anonymous_read`. `authenticated_session` requires safety contract version `2` and must also be enabled for your deployment. Unsupported capabilities are rejected.

Changes that invalidate the authorized scope require fresh authorization. Recheck the policy's armed state after changing its services or targets, and explicitly re-arm only after reviewing the new scope. An ordinary policy update is not consent to attack a different target. See the policy arm/disarm operations in the [API specification](/api-reference/api-reference/openapi-spec).


# Supported Targets

## Overview

The pentest workflow focuses on REST and GraphQL APIs. Surface discovery can use HTML, browser exploration, and JavaScript hints to find their deployed endpoints. [Bug Hunts](/capabilities/bug-hunts) provide broader external-surface discovery and selectable testing suites.

## Application Types

| Type                         | Supported                          | Notes                                                                                                                                        |
| ---------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **REST APIs**                | Yes                                | Serve an OpenAPI or Swagger specification as described in [Preparing for an Engagement](/capabilities/pentests/preparing-for-an-engagement). |
| **GraphQL APIs**             | Yes                                | Create the target as for REST, and give the GraphQL endpoint URL to your Nullify contact.                                                    |
| **SSR HTML Apps**            | Discovery and supported HTTP paths | HTML exploration can identify routes and authentication flows; confirm application-specific coverage before the engagement.                  |
| **SPAs**                     | Discovery and backing APIs         | JavaScript and browser discovery can inform endpoint coverage; this is not a promise to exercise every client-side state or interaction.     |
| **SOAP APIs**                | Not yet                            | Register interest with the Nullify team.                                                                                                     |
| **WebSockets**               | Not yet                            | Event-driven assessments are on the roadmap.                                                                                                 |
| **gRPC**                     | Not yet                            | Reach out if you would like to join the design partner programme.                                                                            |
| **Custom TCP/UDP Protocols** | Not yet                            | On the roadmap.                                                                                                                              |

## APIs that carry XML

The pentester classifies a target as either REST or GraphQL. It can test an HTTP API that exchanges XML payloads as REST, provided an OpenAPI specification covers its endpoints.

A SOAP service is different. We do not support SOAP's envelope, WSDL contract, or operation dispatch, and a WSDL cannot stand in for an OpenAPI specification. If you are unsure which category your service falls into, send us the specification and we will confirm before the engagement starts.

## Network reachability

| Target location             | Pentest                                                                                                    | [Exploit validation](/capabilities/pentests/exploit-validation) |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Reachable from the internet | Yes                                                                                                        | Yes                                                             |
| Private network             | Yes — via the CLI local runner, see [Running in Private Networks](/capabilities/pentests/private-networks) | No                                                              |

## Vulnerability coverage

Across supported target types the pentester tests for:

* Injection — SQL, NoSQL, command, LDAP, and XPath
* Broken authentication and broken authorization
* Insecure direct object references and broken object-level authorization
* Privilege escalation and authorization bypass across roles
* Server-side request forgery, subject to the engagement’s allowed destinations
* XML external entity processing
* Unsafe file upload
* Business logic flaws

Where an exploit succeeds within the authorized scope, the pentester attaches the requests and responses that support the result. A blocked or untested path remains a coverage limitation, not a clean verdict.


# Private Networks

Run a pentest from a machine or self-hosted CI runner that can reach the target, using the public CLI's `--local` mode. Docker executes the DAST image locally; findings and scan information still flow to your hosted Nullify tenant. Local target access does not mean the engagement is offline or that all data stays inside your network.

## Requirements

* A working Docker daemon and enough capacity for the DAST container.
* DNS and network access from the container to the target.
* Outbound access to the Nullify API and the configured image registry, plus the services required by the scanner.
* A Nullify identity permitted to run the engagement and credentials authorized for the target.

```bash
nullify pentest \
  --local \
  --app-name "Internal payments API" \
  --spec-path ./openapi.json \
  --target-host https://payments.internal.example \
  --auth-config ./pentest-auth.json
```

`--image-label` selects the DAST image tag; `--force-pull` refreshes the local image. Use `--use-host-network` only when your Docker platform supports the networking behavior your target requires. Test DNS and target connectivity from the container's network, not just the host shell.

See [Engagement Workflow](/capabilities/pentests/engagement-workflow) for authentication and safe handling of the credential file. Local runs require the same authorization and scope review as hosted engagements.

## Hosted private connectivity

PrivateLink configuration APIs are not evidence that hosted scanner traffic is routed through a working private connection. Do not assume creating an endpoint service makes an application reachable by Nullify. Agree and verify any hosted private-connectivity arrangement with your Nullify contact before relying on it; the documented self-managed path is local execution above.

[Exploit Validation](/capabilities/pentests/exploit-validation) is a separate hosted workflow. It does not inherit the public CLI's local pentest mode.


# Compliance Frameworks

The dashboard's compliance view groups security findings against framework mappings. Use it to find affected controls and prioritize remediation; it is not a certification, an audit opinion, or proof that every framework requirement has been evaluated.

## Read the status

| Status            | Meaning                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------- |
| **Not assessed**  | No assessment coverage has been recorded for the framework and there are no mapped findings. |
| **Compliant**     | Coverage is recorded and no current findings map to the framework.                           |
| **Needs review**  | Findings map to the framework, but none are critical or high severity.                       |
| **Not compliant** | At least one critical or high finding maps to the framework.                                 |

Zero findings without scan coverage must not be read as a clean assessment. The status reflects the scanned assets and available mappings, not the whole of your organization's compliance program.

## Frameworks and drill-down

Code mappings include OWASP Top 10 2021, OWASP ASVS 5.0, PCI DSS 4.0.1, NIST CSF 2.0, and Australian ISM. Cloud findings can carry SOC 2, HIPAA, PCI DSS, CIS, and other rule-provided framework/control references. Code and cloud mappings are separate sources; the same framework name can represent different coverage.

Open a supported framework drill-down to review the underlying findings and use their severity, ownership, and evidence to plan fixes. Cloud control rollups depend on the control metadata emitted by the scan; a summary card does not imply every control has a drill-down. See [Cloud Audits](/capabilities/cloud-audits), [Code Analysis](/capabilities/code-reviews/code-analysis), and [Remediations](/capabilities/remediations).

For an attestation or contractual compliance statement about Nullify itself, request the current approved material through your Nullify contact. Dashboard labels describe your finding rollups, not Nullify's certification status.


# Triage

## Overview

Finding a potential vulnerability is the easy part — deciding whether it's real, how urgent it is, and who should deal with it is where most security programs drown. Triage is what Nullify does between detection and remediation, and it's applied to **every** finding, from every capability: code review, dependency and container analysis, secrets detection, cloud audits, supply-chain posture, bug hunts, and pentests.

The goal is simple: the things in front of you should be the things that actually matter, ranked in the order you should act on them.

## What triage evaluates

For each finding, Nullify weighs:

* **Reachability** — is the vulnerable code or dependency actually reached by your application, and is the asset reachable from the internet? A vulnerable package your code never calls, or a misconfiguration on an internal-only asset, is not the same risk as one on an internet-facing path.
* **Exploitability** — can this actually be exploited, and has Nullify proven it? A pentest finding backed by a reproduced exploit outranks a theoretical one; a leaked credential that's still live outranks one that's already been rotated. Eligible code-review or dependency findings can also be submitted for policy-controlled runtime validation — see [Exploit Validation](/capabilities/pentests/exploit-validation).
* **Business context** — what does the affected service do, what data flows through it, and how critical is it? Nullify draws this from the [Context Engine](/capabilities/context-engine) and the organizational context you provide.
* **Confidence** — how sure is Nullify that this is a true positive? Low-confidence pattern matches are screened out rather than dumped on you.

Triage combines Nullify's reasoning with deterministic rules, using the evidence and context available for that run. Updated context can change a verdict.

## Severity and priority

Nullify tracks two related but distinct signals:

* **Severity** — how bad the issue is in the abstract (roughly, how much damage it could do).
* **Priority** — how urgently *you* should act on it, once reachability, exploitability, and business context are folded in. Priority is the ranking that drives ticketing thresholds, SLAs, and the order work is surfaced. Nullify's priority labels run from `URGENT` and `IMPORTANT` down through `MEDIUM`, `INFORMATIONAL`, `LOW`, and `NEGLIGIBLE`.

A critical-severity CVE in a dependency your code never loads can carry a lower priority than a high-severity issue on an internet-facing service — because priority reflects real-world risk, not just the raw score.

## False-positive screening

Before a finding ever reaches you, Nullify screens out the noise: unreachable code paths, test fixtures and example credentials, benign configuration variation, and duplicate reports of the same underlying issue. What survives is meant to be worth a human's attention.

## Re-triage

Triage isn't a one-time verdict. When something changes — new code lands, a dependency is upgraded, a fix merges, or new threat intelligence arrives — Nullify re-triages the affected findings and updates their priority. A finding that becomes reachable is escalated; one that's been fixed or is no longer exploitable is de-prioritized or resolved.

## Your decisions stick

When you make a triage decision — allowlist a finding, accept a risk, mark a false positive, or override a severity — Nullify remembers it. Those decisions persist across future scans and feed back into how Nullify triages similar findings, so you don't re-litigate the same call every time a scan runs. See the per-capability configuration pages for how to allowlist and adjust findings.

## Where triaged findings go

Triaged findings flow into [Security Program Management](/capabilities/program-management), which sequences and assigns the work, and into [Remediations](/capabilities/remediations), which drafts the fixes. When Nullify needs a human judgment call it can't make alone — an escalation decision, a clarifying question, an ownership mapping — it raises an [action item](/capabilities/working-with-nullify).

## Human answers and fix effort

Answering a finding's clarification question or supplying a relevant human comment can trigger re-triage with that answer as new evidence. Include concrete context such as exposure, intended behavior, or compensating controls.

Administrators can configure the story-point weights for easy, medium, and hard fixes through `GET`/`PUT /admin/fix-effort`. These weights inform ticket effort estimates; they do not redefine severity or priority. See [Ticketing and SLAs](/configuration/configuration-ticketing).


# Security Program Management

## Overview

Detecting and fixing vulnerabilities is only useful if the right work happens in the right order, with the right people, at the right time. Security Program Management is the part of Nullify that runs your security program the way a security engineering lead would: it maintains a prioritized backlog across every capability, monitors emerging threats, understands who owns what and how much they have on their plate, and drives work to completion through campaigns — opening PRs, filing tickets, nudging, and escalating.

## Campaigns

A **campaign** is how Nullify organizes a body of security work toward an objective — "eliminate leaked secrets," "upgrade the dependencies affected by this CVE," "harden our Terraform." Campaigns are the unit you see and steer in the dashboard and API.

### How a campaign runs

1. **Detect** — Nullify proposes campaigns from your current backlog, threat intelligence, and organizational risk, tailored to what it actually found. There's no fixed catalog of templates to pick from.
2. **Decide** — a security leader adjusts the scope and the level of automation: which findings are in, whether Nullify opens PRs, files tickets, or just notifies, and any deadlines.
3. **Execute** — Nullify assigns work to the right owners, opens fix PRs, creates and updates tickets, and escalates when progress stalls.
4. **Report** — progress is tracked in real time: findings in scope, resolved vs. remaining, time to resolution, per-team progress, and SLA compliance.

### Scoping a campaign

Campaigns can target work by finding type (specific CWEs or CVEs), repository, team, individual, severity, or a combination. Campaign targeting currently covers code, dependency, container, secret, and pentest findings.

Common campaign themes Nullify generates include eliminating credential leaks, upgrading vulnerable dependencies, hardening Terraform, closing OWASP Top 10 gaps, and meeting compliance requirements (PCI-DSS, HIPAA, SOC 2) — but every campaign is generated to fit what Nullify finds, not chosen from a fixed list.

## The Backlog

Nullify maintains a single curated backlog that combines findings from across the platform — code vulnerabilities and leaked secrets from [code review](/capabilities/code-reviews), infrastructure misconfigurations from [cloud audits](/capabilities/cloud-audits), supply-chain risks from [SCPM](/capabilities/scpm), and validated findings from [pentests](/capabilities/pentests) and [bug hunts](/capabilities/bug-hunts).

The backlog is ordered by an overall **priority score** (0–100) that weighs severity, exploitability, reachability, and business impact together — not raw CVSS alone. Resolved findings drop off automatically, and each remaining finding is linked to the PRs and tickets tracking its remediation so status stays current. See [Triage](/capabilities/triage) for how findings are scored.

## Threat Intelligence

Nullify researches newly disclosed vulnerabilities and supply-chain compromises for all customers and assesses each one against your environment as a **threat investigation**. A confirmed exposure to a critical, known-exploited vulnerability with a fixed release opens a remediation campaign. See [Threat Intelligence](/capabilities/threat-intelligence).

## Ownership and Capacity

Good routing depends on knowing who owns what and who's overloaded.

* **Ownership** comes from CODEOWNERS, commit history, service metadata, and connected sources like [Compass](/connectors/compass) and your team structure.
* **Capacity** is a lighter-weight, qualitative read: Nullify considers how many open PRs and assigned tickets a person already has, and their recent history of merging and closing work, so it can route new work to people who can actually take it on and avoid piling onto someone who's swamped.

Nullify respects team boundaries — it won't reassign work across teams without approval. When it can't determine ownership, it raises an [action item](/capabilities/working-with-nullify) asking you to assign a team.

## Assigning and driving work

When Nullify assigns and sequences work, it weighs the finding's priority (severity, exploitability, reachability, business impact), current ownership, and team capacity. It then drives each item to completion:

* Opens [autofix](/capabilities/remediations) pull requests and assigns reviewers using the ownership cascade described in Remediations.
* Creates and updates tickets in Jira and other trackers.
* Monitors open security PRs, comments with context, and escalates the ones that stall.
* Tracks each finding's status as its PR or ticket moves.

## Security Program Strategy

Beyond day-to-day work, Nullify maintains a rolling **strategy** — a set of quarterly security goals for your program. The strategy is versioned (so you can see how it's evolved), editable, and Nullify can generate a proposed strategy from your current posture and risk profile. It gives the program a direction that individual campaigns ladder up to.

## Ground Rules

You set Manager’s action boundaries with program autonomy policy, tenant and team ground rules, and blocked action types. Controls cover PRs, tickets, messages, and reviewer selection; they do not disable upstream triage. See [Manager Configuration](/configuration/configuration-manager) for the distinct controls and API paths, including settings absent from the current dashboard.

## Metrics & Reporting

Track the program's current state with:

* **Mean Time to Remediate (MTTR)** — average time from discovery to fix, plus related mean-time variants.
* **Finding counts** — current backlog totals.
* **Campaign progress** — resolved vs. remaining, per team.

Metrics reflect the latest run; Nullify does not retain a historical time series, so there are no trend, velocity, or burn-down charts.

## How it connects

Security Program Management sits at the center of Nullify: it reads triaged findings and the [Context Engine](/capabilities/context-engine), drives [Remediations](/capabilities/remediations), routes through your [ticketing](/connectors/jira) and [messaging](/connectors/slack) connectors, and raises [action items](/capabilities/working-with-nullify) when it needs a human decision.

## Automation API

The [Manager API](/api-reference/api-reference/manager) covers campaigns and run history, strategies and versions, proposals and decisions, action items, plans, state, metrics, chat audit, and escalation configuration. Strategy and campaign proposals arrive as named action items; use their decision workflow to approve or reject them.


# Remediations

## Overview

Nullify doesn't just find and rank vulnerabilities — it fixes them. For code vulnerabilities, dependency issues, cloud misconfigurations, and validated pentest findings, Nullify drafts production-ready fixes, opens pull requests that match your codebase's style, and shepherds each one until it's ready for a developer to merge. Leaked secrets are not autofixed — credential findings route to manual rotation and a tracking ticket. The bar it holds itself to: the vulnerability is genuinely closed, existing functionality is preserved, and no new vulnerability is introduced.

## How a fix is produced

Only findings that have been [triaged](/capabilities/triage) as real and worth fixing become fix candidates — Nullify doesn't open PRs for noise. From there, it works like a careful engineer rather than a find-and-replace bot:

1. **Locate and plan.** Nullify finds the code responsible and writes a minimal-change plan that targets the root cause, not just the symptom.
2. **Edit.** It applies the change, matching your surrounding error handling, logging, and style conventions.
3. **Independent review.** A separate reviewing step checks that the fix actually addresses the root cause, preserves behavior, and stays minimal. If it doesn't, the fix loops back for revision.
4. **Validate it.** Nullify attempts the scanner, build, test, and exploit checks available to that workflow. Review the recorded validation and any unavailable checks before accepting the change.

Successful workflows open a draft pull request for further CI and human review. Generated code is a proposed fix, not a guarantee that all security or functional checks passed.

## The pull request lifecycle

Opening the PR is the start of Nullify's work, not the end. It keeps iterating the way a diligent author would:

* **Reads CI and fixes it.** When CI fails, Nullify reads the actual failure logs and pushes corrective commits, within a bounded effort budget.
* **Responds to reviewers.** When a developer leaves a review comment, Nullify reads the diff and the discussion and responds inline — updating the code or explaining the change.
* **Handles conflicts.** If the branch falls behind, Nullify rebases it.
* **Promotes when green.** Once CI is passing, Nullify promotes the PR from draft to ready-for-review and assigns the right reviewer.

Nullify never merges your code — a human always makes the final call. Review the current CI result and any unresolved limitations before merging.

### Ask Nullify on the PR

Reply in the PR thread — or **`@mention`** Nullify — to ask why a change is needed, request a different approach, or get more context. Nullify reads the diff and the discussion and responds inline, which is the fastest way to get a fix review-ready and merged. On pull requests Nullify didn't open, `@mention` it so it knows the comment is for it.

## Choosing the reviewer

Nullify assigns each fix PR to the person most likely to be able to review it well, using a ranked ownership cascade:

1. **The authors of the changed code** — the people whose recent commits touched the lines being modified (automated/bot accounts excluded).
2. **Code owners** — the owners defined in your CODEOWNERS file for the affected paths.
3. **The owning team** — falling back to the team that owns the repository or finding.

Nullify selects at most **3 reviewers** for an autofix PR.

## Pull Request Limits

Manager campaign planning applies fixed selection limits:

* **3 open Nullify fix PRs per repository** at any time.
* **5 new fix PRs per remediation plan.**

Once a fix PR merges or closes, the next queued fix can open. These are campaign-plan limits, not a global throttle on ad hoc dashboard, API, or CLI requests.

## Working with developers

### Status Updates

* Posts to existing Slack threads.
* Updates Jira tickets with PR links.
* Sends notifications when a review is needed.
* Escalates stalled PRs to team leads.

### Manual Fallback

When an automated fix isn't appropriate, Nullify provides detailed fix guidance, creates a ticket with reproduction steps, tags the appropriate owner, and preserves the context for future learning.

## Where remediation fits

Remediation is driven by [Security Program Management](/capabilities/program-management), which decides what to fix and when, and reads from the [Context Engine](/capabilities/context-engine) for ownership and business context. When a fix needs a human decision Nullify can't make alone, it raises an [action item](/capabilities/working-with-nullify).

## Cached fixes and manual retries

A cached patch may be reused only when its recorded source checksums still match the current checkout. Drift can cause a fresh agent run, so a previous diff is not a guarantee of the next result. Locally supplied caches can be trusted on first use; inspect the proposed change and resulting validation evidence.

Where the dashboard offers **Force auto-fix** for a finding marked not autofixable, use it as an explicit retry request. It does not guarantee a safe patch or successful PR. Follow status and activity and review any new failure reason.

Dependency remediation includes supported container base-image updates. Pentest findings also have an autofix lifecycle. See the [Dependency Analysis](/api-reference/api-reference/dependency-analysis), [Code Review](/api-reference/api-reference/code-review), and [Pentests](/api-reference/api-reference/pentester) APIs for the available start and polling operations.


# Working with Nullify

## Overview

Nullify runs autonomously, but the best security programs are a partnership. There are moments where Nullify needs a human decision — a judgment call it shouldn't make alone, a piece of context only your team has, or an approval before it acts. This page covers how that back-and-forth works: the **action items** Nullify raises, the **chat** you can hold with it anywhere, and the **escalations** it sends when something needs attention.

## Action Items

An **action item** is a tracked unit of work that Nullify files when it genuinely cannot proceed on its own. Rather than guessing or stalling silently, it asks — and once you answer, it picks the work back up automatically. There are a few kinds:

* **Escalated finding** — Nullify wants your call on a finding before acting: approve it, reject it, or ask for changes.
* **Clarifying question** — Nullify is missing a piece of context (a policy, an environment detail, an ownership rule). Answer once, and it re-triages every finding that was waiting on that answer.
* **Unmapped user** — Nullify knows the person involved in one system (say, a GitHub handle) but needs help mapping them to another (say, their Slack account) so it can route work to them.
* **Unassigned team** — a repository or finding has no owning team. Assign one, and every unassigned finding in that scope is routed.

You resolve an action item simply by supplying the judgment it asked for — from the dashboard, or by replying in the Slack thread or ticket comment where it reached you. Nullify only marks an action item complete once the underlying work has actually happened, not because it *said* it would; and it never auto-closes one just because time passed. If the underlying problem goes away on its own, Nullify resolves the item for you.

You also have a few deliberate controls of your own: reopen a finding Nullify dismissed (with a reason), re-route ownership, or just answer in chat.

## Chat with Nullify

You can talk to Nullify wherever you already work — the dashboard, [Slack](/connectors/slack), [Microsoft Teams](/connectors/microsoft-teams), and in pull request and ticket threads. Ask it about:

* **Findings** across code, dependencies, containers, secrets, cloud posture, and pentests.
* **Remediation campaigns** and their progress.
* **Security metrics and trends.**
* [**Threat investigations**](/capabilities/threat-intelligence) and which repositories are affected.

Nullify answers in plain language and links back to the relevant place in the dashboard. From the dashboard chat it can also **act** on your behalf — reassign a pull request's reviewers, reassign, comment on, or close a ticket, rebase or promote a stalled fix PR, allowlist a finding, or create a ticket. In Slack and Teams, chat is oriented toward questions and answering Nullify's action items; for state-changing actions it points you to the dashboard.

## Escalations

When a finding needs developer action and isn't moving — a fix PR is open but unreviewed, a fix is blocked, or a secret needs rotating — Nullify sends an **escalation**. Each one carries the finding's facts, why it needs attention, the risk and SLA, and a link to the finding, delivered as a direct message to the owner, to a channel, or both. Reply in the thread to discuss, answer, or ask for more context.

See [Slack notifications & escalations](/connectors/slack/slack-notifications) for how to configure where escalations land. Escalation paths and the autonomous actions Nullify is allowed to take are part of [Security Program Management](/capabilities/program-management).

## Action-item catalog

The current dashboard places action items inside **Operator**; older dashboards may show a dedicated page.

| Kind                                           | Human input                                        |
| ---------------------------------------------- | -------------------------------------------------- |
| Escalated finding (`ESCALATEDFINDING`)         | Decide how a finding should proceed.               |
| Tacit knowledge (`TACITKNOWLEDGE`)             | Capture knowledge that is not yet recorded.        |
| Unmapped user (`UNMAPPEDUSER`)                 | Confirm identities across connected systems.       |
| Unassigned team (`UNASSIGNEDTEAM`)             | Assign ownership.                                  |
| Context clarification (`CONTEXTCLARIFICATION`) | Supply missing application or business context.    |
| Strategy proposal (`STRATEGYPROPOSAL`)         | Review and decide on a proposed security strategy. |
| Campaign proposal (`CAMPAIGNPROPOSAL`)         | Review and decide on proposed remediation work.    |

Dashboard chat can update the security-program strategy when that surface exposes the strategy write tool and the caller has access. Ask for confirmation of the saved result; an explanation or proposed draft is not a completed write. Available actions differ by surface and are constrained by [Manager configuration](/configuration/configuration-manager).


# Overview

Connect the systems Nullify needs to review code, understand runtime context, and route work. The integrations catalog in your tenant determines which connection flows are available; a provider's presence in a source repository or an API client does not by itself mean customers can connect it.

| Area                   | Guides                                                                                                                                       | Availability and purpose                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Source control         | [GitHub](/connectors/github), [GitLab](/connectors/gitlab), [Bitbucket](/connectors/bitbucket), [Azure DevOps](/connectors/azure)            | Repository access, review events, and provider-specific remediation support.                                          |
| Ticketing              | [Jira](/connectors/jira), [Linear](/connectors/linear), [GitHub Issues](/connectors/github#github-issues), [Azure DevOps](/connectors/azure) | Route and synchronize tickets with the configured destination.                                                        |
| Messaging              | [Slack](/connectors/slack), [Microsoft Teams](/connectors/microsoft-teams)                                                                   | Conversations, questions, and escalation delivery.                                                                    |
| Ownership              | [Compass](/connectors/compass)                                                                                                               | Component and team context.                                                                                           |
| Sign-in and federation | [OIDC](/connectors/oidc)                                                                                                                     | Distinct user-sign-in and cloud workload-identity trust flows.                                                        |
| Cloud                  | [AWS](/connectors/aws), [GCP](/connectors/gcp), [Azure cloud](/connectors/azure-cloud), [Kubernetes](/connectors/kubernetes)                 | Account and cluster inventory for exposure and posture analysis.                                                      |
| Scanner source         | [Wiz](/connectors/wiz)                                                                                                                       | Tenant-enabled import of Wiz cloud inventory/configuration.                                                           |
| Package registries     | [Private registries](/connectors/package-registries)                                                                                         | Resolve private npm, Maven, Python, and Go packages, including Artifactory, Nexus, CodeArtifact, and GitHub Packages. |
| Build context          | [Buildkite](/connectors/buildkite), [Jenkins](/connectors/jenkins)                                                                           | Build status/log access layered on an existing GitHub connection; Jenkins availability is tenant-controlled.          |

[CircleCI](/connectors/circleci) is a limited rollout and should not be assumed to provide the same build-log integration as Buildkite or Jenkins. Separately, [notification settings](/configuration/configuration-notifications) support Slack, email, and webhook targets; these are not additional standalone catalog connectors.

For setup not offered in your tenant, contact Nullify before provisioning credentials for an assumed integration.

## Catalog availability

Asana, Codefresh, separate SCM-backed CI connectors, and the broader SIEM/SOAR, GRC, vulnerability-export, observability, knowledgebase, and container-registry catalog entries are not currently customer-connectable through the shared catalog. Provider names in development code are not setup instructions. Identity federation and synchronization offered through **Settings → Identity** are a separate surface; do not infer that every directory provider has a catalog connection flow.


# GitHub

## Overview

Install the Nullify GitHub App to connect Nullify to your repositories. Nullify works with GitHub.com and GitHub Enterprise. Installation instructions differ for cloud and self-hosted deployments — see the [Enterprise Tier](/enterprise-tier/github-install) section for step-by-step guides.

Nullify posts updates asynchronously so developers stay inside their existing workflow.

## What Nullify does with GitHub

* **Pull request reviews.** When a pull request is opened, reopened, or updated, Nullify reviews the changed code and posts its findings back to the pull request as review comments and a **Nullify** check. When a PR is merged or closed, Nullify reconciles the state of any of its own autofix pull requests.
* **Push scanning.** Pushes are scanned, and pushes to the default branch refresh the repository's baseline so dashboards and finding counts stay current.
* **Autofix pull requests.** Nullify opens fix PRs for eligible findings, keeps them green through CI, responds to review comments, and assigns reviewers. See [Remediations](/capabilities/remediations).
* **Comment-driven discussion.** Replies on a Nullify pull request — or an `@mention` of Nullify on any PR — are routed back so it can respond in-line.

## Events handled

Nullify subscribes to the events it needs to review and remediate — including push, pull-request, pull-request-review and review-comment, issue-comment, check-run and check-suite, status, repository, and the app installation lifecycle. Settings such as the CI/PR gate, ticketing thresholds, and notification destinations are configured in the Nullify dashboard under **Configure**, not in a file in your repository.

## Support

If you encounter any issues, please contact our support team for assistance.

## GitHub Issues

GitHub Issues can be a ticketing destination as well as a source-control feature. Nullify can create, assign, close, and reopen linked issues; issue lifecycle webhooks synchronize state back to the platform. The GitHub App must have the required issue permissions and subscribe to the `issues` event as well as `issue_comment`.

Configure the destination repository and routing policy before enabling automatic ticket creation. Closing an issue does not independently prove the underlying vulnerability has been remediated.


# GitLab

## Overview

Connect Nullify to your GitLab instance to assess your projects, review merge requests, and scan every push. Nullify works with GitLab.com (SaaS) and self-managed GitLab. Installation steps are documented in the Enterprise Tier section.

Nullify posts updates asynchronously so developers stay inside their existing workflow.

## What Nullify does with GitLab

* **Merge request reviews.** When a merge request is opened, reopened, or updated, Nullify scans the changed code and posts its findings back to the merge request. When a merge request is merged or closed, Nullify reconciles the state of any of its own autofix merge requests and records the outcome.
* **Push scanning.** Every push to a branch triggers a scan. Pushes to the project's default branch additionally update the repository's baseline so dashboards and finding counts stay current. Pushes that introduce no new commits are ignored.
* **Comment-driven discussion.** Replies on a Nullify merge request thread are routed back to Nullify so it can respond in-line, keeping the review conversation in GitLab.
* **Pipeline awareness.** Nullify tracks the result of pipelines associated with a merge request, mapping success/failure back to the corresponding scan so the CI/PR gate can act on it.

## How it connects

Nullify connects to GitLab through two mechanisms set up during install (see the Enterprise Tier guide):

1. **An access token** that lets Nullify call the GitLab API — resolving the group that owns a project, posting merge-request reviews, and reading diffs. The token is stored encrypted by the Nullify platform.
2. **A project (or group) webhook** that delivers events to Nullify's ingestion endpoint at `/core/gitlab/webhook`. Each delivery carries a secret token in the `X-Gitlab-Token` header, which Nullify verifies before processing the event.

## Events handled

Nullify subscribes to the following GitLab webhook events:

| GitLab event           | Used for                                                                       |
| ---------------------- | ------------------------------------------------------------------------------ |
| Push events            | Branch push scanning; default-branch pushes refresh the baseline               |
| Merge request events   | Merge request scans on open/reopen/update; state reconciliation on merge/close |
| Comments (note events) | Routing replies on Nullify merge-request threads                               |
| Pipeline events        | Mapping merge-request pipeline results back to scans                           |

Pushes that introduce no new commits are ignored. Nullify does not currently act on tag-push, deployment, issue, or job events.

{% hint style="info" %}
Settings such as the CI/PR gate, ticketing thresholds, and notification targets are configured in the Nullify dashboard under **Configure**, not in a file in your repository.
{% endhint %}

## Support

If you encounter any issues, please contact our support team for assistance.

## Autofix merge requests

For supported findings, Nullify can create a fix branch, push changes, and open a GitLab merge request. It can update and rebase the MR as the review progresses. Reviewer selection resolves eligible GitLab users before requesting review; ownership data and project access affect who can be assigned. A human reviews and merges the change.


# Bitbucket

## Overview

Connect the Nullify Bitbucket app to review pull requests, scan pushes, and publish [repository dashboards](/connectors/bitbucket/repository-dashboards). Installation steps are documented in the [Enterprise Tier](/enterprise-tier/bitbucket-install) section.

Nullify posts updates asynchronously so developers stay inside their existing workflow.

## What Nullify does with Bitbucket

* **Pull request reviews.** When a pull request is created, updated, or commented on, Nullify reviews the changed code and posts its findings back to the pull request.
* **Push scanning.** Pushes are scanned, and pushes to the default branch refresh the repository's baseline.
* **Autofix pull requests.** Nullify opens fix PRs for eligible findings and iterates on them. See [Remediations](/capabilities/remediations).
* **Comment-driven discussion.** Replies on a Nullify pull request are routed back so it can respond in-line.

## Events handled

Nullify subscribes to repository push and pull-request events (created, updated, and comment-created). Settings such as the CI/PR gate, ticketing thresholds, and notification destinations are configured in the Nullify dashboard under **Configure**, not in a file in your repository.


# Repository Dashboards

Bitbucket repositories receive the same continuously updated dashboard as GitHub projects. It tracks outstanding findings, accepted risks, campaign assignments, and linked Jira tickets so teams have a single thread of truth.

![Repository dashboard example](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-2fef35e3d8f5ab4cb67f06654524e11043d7b9c1%2Frepo-dashboard-example.png?alt=media)


# Azure DevOps

## Overview

The Azure DevOps connector links your Azure DevOps organization to Nullify so that source-control activity drives security scanning, pull request reviews, and two-way ticket status sync — without developers leaving their existing workflow.

For a new workspace, Nullify sends a setup invitation. Open that link and finish Microsoft and Azure DevOps checks before onboarding. The **Request workspace** button on the **Your Microsoft sign-in worked** screen does not claim a prepared workspace. See [Set up a new workspace](/enterprise-tier/azure-install#set-up-a-new-workspace).

An administrator opens **Settings → Connectors → Azure DevOps**, selects **Sign in with Microsoft** as a Project Collection Administrator, completes any Microsoft administrator consent, then selects organizations. Nullify adds its service principal, grants scoped permissions across their visible projects, checks access, creates service hooks, and syncs repositories. Select repositories in Onboarding and choose **Finish setup** to request the first scan; some workspaces require Nullify to start it. There's no app registration to create and no client secret to copy into Nullify.

Setup requests delegated Azure DevOps access (`user_impersonation`) plus `openid profile email`. The delegated token lets Nullify perform the setup with the signed-in administrator's authority. Ongoing access uses Nullify's service principal and the permissions granted in Azure DevOps. Entra consent alone does not grant that principal access to your organization. The [Install guide](/enterprise-tier/azure-install#permissions) lists the permissions and revocation steps.

{% hint style="warning" %}
Azure DevOps is enabled per workspace. Contact your Nullify representative if the connector reports "Azure DevOps setup is not available for this workspace".
{% endhint %}

{% hint style="info" %}
This page describes what the integration provides. For the step-by-step connect flow, the permissions Nullify requests and why, and troubleshooting, see the [Azure DevOps Install guide](/enterprise-tier/azure-install). Azure DevOps Server and bring-your-own service principal connections are [not yet supported](/enterprise-tier/azure-install#not-yet-supported).
{% endhint %}

## What you get

### Pull request reviews

When a pull request is **created** or **updated** in a connected repository, Nullify reviews the changed code and posts its findings back as a PR review. Replies to Nullify's PR comments are also handled: when a developer comments on a Nullify review thread, the connector picks up the reply and continues the conversation in-thread.

Pull request gating and review behaviour use the dashboard's available policy controls or the admin API (older dashboards use **Configure → Pull Requests**), including whether the "Nullify" check can fail the build on net-new findings at or above your chosen priority threshold.

### Autofix pull requests

Nullify opens autofix pull requests on Azure DevOps: it creates a branch in the connected repository, commits the fix, and opens a pull request for your team to review. Re-running a fix on a branch that already exists repoints that branch, which is a non-fast-forward update — the reason the connector holds the **Force push** permission listed in the [Install guide](/enterprise-tier/azure-install#permissions).

### Push scanning

Every push to a connected repository is delivered to Nullify. The connector emits a scan event for each updated branch (tag pushes and branch deletions are ignored), and pushes to the repository's default branch additionally trigger the default-branch pipeline so your baseline security posture stays current.

### Work-item (ticketing) status sync

When Nullify files a finding as an Azure DevOps work item, **work-item updated** events flow back to Nullify. A state change on a tracked work item (for example moving it to *Resolved*, *Closed*, or *Done*) is synced to the matching Nullify finding ticket, keeping the finding's status aligned with what your team does in Azure Boards. Nullify maps Azure's out-of-the-box state vocabulary by default and honours a per-tenant status map for teams running a custom Azure Boards process.

## Events the connector subscribes to

Nullify creates Azure DevOps service-hook subscriptions for the following events on each connected organization, automatically as part of connecting:

| Event                  | Azure DevOps trigger                                                                               | Used for                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Code pushed            | `git.push`                                                                                         | Push scanning (all branches + default branch)                                                   |
| Pull request created   | `git.pullrequest.created`                                                                          | PR reviews                                                                                      |
| Pull request updated   | `git.pullrequest.updated`, filtered to source-branch pushes and status changes (two subscriptions) | PR reviews; reviewer votes are not delivered                                                    |
| Pull request commented | `ms.vss-code.git-pullrequest-comment-event`                                                        | PR review replies                                                                               |
| Pull request merged    | `git.pullrequest.merged`                                                                           | Keeping merge/close state in sync                                                               |
| Work item updated      | `workitem.updated`                                                                                 | Ticket status sync — subscribed only when you tick **File findings as Azure Boards work items** |

Webhook deliveries are authenticated: each subscription carries an HTTP Basic credential (username `nullify` plus a per-install shared secret), and Nullify rejects deliveries that don't match.

Subscriptions are project-scoped, so a repository added to a connected project is covered. A project created after you connect needs a Project Collection Administrator to connect again from Settings before Nullify can read it. Settings shows each organization's webhook health and offers **Repair webhooks** or **Reconnect** when a subscription is missing or disabled.

## Capability differences vs GitHub

* **No blame API.** Nullify falls back to the file's most recent contributor wherever it would otherwise use line-level blame.
* **No force-push detection.** Nullify does not react to a force-push on one of your branches the way it does on GitHub; each push is handled independently. (This is about *incoming* force-pushes — Nullify does force-push its own autofix branch when it repoints one.)
* **Iteration-tracked PR comments.** Azure DevOps threads review comments to a pull request *iteration* rather than a commit SHA.

See the [Install guide](/enterprise-tier/azure-install#capability-differences-vs-github) for more detail.

## Tenants

Nullify prepares the workspace before sign-in can open it. Signing in with no workspace does not create one, and **Request workspace** does not replace the setup invitation. Microsoft sign-in and the Azure DevOps connection are separate after the workspace exists. See [Microsoft sign-in](/connectors/oidc#azure).

## Setup

The full walkthrough — administrator consent, sign-in, setup checks, permissions and troubleshooting — lives in the [Azure DevOps Install guide](/enterprise-tier/azure-install).


# Slack

## Overview

The Slack connector lets Nullify reach engineers where they already work. Once connected, Nullify can:

* **Escalate findings** that need developer action — an open fix PR that hasn't been reviewed, a fix that's blocked, or a secret that needs rotating.
* **Send campaign nudges and informational updates** to keep teams aligned on remediation.
* **Take replies in-thread**, so engineers can respond without leaving Slack.

Messages are delivered asynchronously, so teams stay productive inside Slack without hopping between tools.

## Ask Nullify directly

Engineers don't have to wait for a message — they can start a conversation with Nullify any time by **`@mention`-ing** it, sending it a **direct message**, or **replying in any thread** it's part of. Ask about:

* **Findings** across code, dependencies, containers, secrets, cloud posture, and pentests.
* **Remediation campaigns** and their progress.
* **Security metrics and trends.**
* [**Threat investigations**](/capabilities/threat-intelligence) and which repositories are affected.

Nullify replies in plain language and links to the relevant place in the dashboard. From a Slack thread you can also answer and resolve the [action items](/capabilities/working-with-nullify) Nullify raises — approve or dismiss an escalation, answer a question, or assign a team. For broader state changes like allowlisting a finding, triggering a fix, or creating, closing, commenting on, or reassigning a ticket, Nullify can act autonomously on your behalf, or point you to the dashboard.

## Connect Slack

Connecting Slack is a one-time authorization — there's no app to build or token to paste.

1. Log in to the Nullify Dashboard.
2. Go to **Configure → Connectors → Slack**.
3. Click **Connect** and authorize the Nullify Slack app in your workspace via OAuth.

Once authorized, Nullify verifies the connection and marks the connector as **Enabled**. You're then ready to choose where escalations go — see [Configuring notifications & escalations](/connectors/slack/slack-notifications).

## Automation and delivery controls

[Manager ground rules](/configuration/configuration-manager) control allowed ticket, PR, and messaging actions. [Notification settings](/configuration/configuration-notifications) separately select event filters and destinations. Delivery budgets and deduplication can defer or combine repeated escalations, so a missing individual message does not mean the finding was discarded.


# Notifications & Escalations

Once Slack is connected, you can control where Nullify sends its messages — directly to the engineer who owns a finding, to a shared channel, or both.

## What an escalation is

An **escalation** is a high-priority nudge Nullify sends when a security finding needs developer action — for example, a fix PR is open but unreviewed, a fix is blocked, or a secret needs rotating.

Each escalation is a structured message containing:

* A greeting and the finding's facts (repository, and the file, package, CVE, or secret type).
* A status line describing why it needs attention.
* The risk and the SLA for resolving it.
* A link to the finding in the Nullify dashboard.

Engineers can **reply in-thread** to discuss, answer Nullify's questions, or ask it for more context.

Nullify's regular channel messages and campaign nudges are informational updates and follow the same channel configuration described below.

## Where to configure it

Go to **Configure → Connectors → Slack → Escalations** in the dashboard.

This is a single, **org-wide** policy — it applies to every escalation Nullify sends. If you don't configure anything, escalations default to **Direct message**, so existing behavior is preserved.

## Delivery modes

Choose one of:

* **Direct message** — DM the engineer who owns the finding. *(Default.)*
* **Channel** — post escalations to a Slack channel you choose.
* **Both** — DM the owner *and* post to the channel.

### Setting the channel

For **Channel** or **Both** modes, enter the destination **Slack channel ID** (for example, `C0123456789`). You can copy a channel's ID from Slack under the channel's **View channel details** menu.

The same channel is also used for the agent's regular channel messages.

## Automation and delivery controls

[Manager ground rules](/configuration/configuration-manager) control allowed ticket, PR, and messaging actions. [Notification settings](/configuration/configuration-notifications) separately select event filters and destinations. Delivery budgets and deduplication can defer or combine repeated escalations, so a missing individual message does not mean the finding was discarded.


# Microsoft Teams

## Overview

The Microsoft Teams connector lets Nullify reach engineers where they already work. Once the Nullify app is installed in your Teams tenant, Nullify can:

* **Escalate findings** that need developer action — an open fix PR that hasn't been reviewed, a fix that's blocked, or a secret that needs rotating.
* **Send campaign nudges and informational updates** to keep teams aligned on remediation.
* **Reply in-thread**, so engineers can respond and ask Nullify for more context without leaving Teams.

Messages are delivered asynchronously, so teams stay productive inside Teams without hopping between tools.

The Teams connector mirrors Slack: escalations, channel messages, and direct messages are all driven by Nullify, and the same notification configuration controls where they land.

## Ask Nullify directly

Engineers can start a conversation with Nullify at any time by **`@mention`-ing** it in a channel, sending it a **direct message**, or **replying in a thread** it's part of. Ask about:

* **Findings** across code, dependencies, containers, secrets, cloud posture, and pentests.
* **Remediation campaigns** and their progress.
* **Security metrics and trends.**
* [**Threat investigations**](/capabilities/threat-intelligence) and which repositories are affected.

Nullify replies in plain language and links to the relevant place in the dashboard. From a Teams thread you can also answer and resolve the [action items](/capabilities/working-with-nullify) Nullify raises — approve or dismiss an escalation, answer a question, or assign a team. For broader state changes like allowlisting a finding, triggering a fix, or creating, closing, commenting on, or reassigning a ticket, Nullify can act autonomously on your behalf, or point you to the dashboard.

## Connect Microsoft Teams

Connecting Teams has two parts: registering an Azure AD application that Nullify authenticates as, and installing the Nullify app package into Teams.

This customer-managed Teams registration is separate from the official Nullify application used for [Entra sign-in](/configuration/account-and-teams/entra-sso-and-scim) and [Azure DevOps](/connectors/azure). Do not replace the official application ID or add Teams' Microsoft Graph permissions to that sign-in/ADO application.

1. **Register an Azure AD application** (your Azure administrator does this in the Azure portal): create an app registration, grant it the Microsoft Graph permissions Nullify needs to list channels and users and send messages, and create a client secret.
2. **Provide the credentials to Nullify.** In the Nullify Dashboard, go to **Configure → Connectors → Microsoft Teams** and enter the application's **Client ID**, **Client Secret**, and **Tenant ID**.
3. **Install the Nullify Teams app package.** From the same connector page, download the Nullify Teams app package (a `.zip` containing the app manifest and icons) and upload it in the Teams admin center (or via **Apps → Manage your apps → Upload an app**).
4. **Add the Nullify app to the team(s)** whose channels you want it to post in.

Once Nullify verifies the connection, the connector is marked **Enabled** and you're ready to choose where escalations go.

## Channel targeting

Nullify posts to a Teams channel you select from the dashboard — pick the channel and the destination is captured for you. Nullify only posts in teams the Nullify app has been added to. If a message doesn't appear, confirm the Nullify app is installed in that specific team, not just elsewhere in the tenant.

## Configuring notifications & escalations

Escalations and channel destinations are configured the same way as Slack, under **Configure → Connectors → Microsoft Teams**.

An **escalation** is a high-priority nudge Nullify sends when a security finding needs developer action — for example, a fix PR is open but unreviewed, a fix is blocked, or a secret needs rotating. Each escalation carries the finding's facts (repository, and the file, package, CVE, or secret type), why it needs attention, the risk and SLA, and a link to the finding in the Nullify dashboard. Engineers can **reply in-thread** to discuss or ask Nullify for more context.

Delivery modes match the Slack connector:

* **Direct message** — DM the engineer who owns the finding.
* **Channel** — post escalations to a Teams channel you choose.
* **Both** — DM the owner *and* post to the channel.

Nullify's regular channel messages and campaign nudges are informational updates that follow the same channel configuration.

## Automation and delivery controls

[Manager ground rules](/configuration/configuration-manager) control allowed ticket, PR, and messaging actions. [Notification settings](/configuration/configuration-notifications) separately select event filters and destinations. Delivery budgets and deduplication can defer or combine repeated escalations, so a missing individual message does not mean the finding was discarded.


# Jira

## Overview

Nullify can be configured to integrate with Jira to automatically create and update issues based on the findings in your project.

It can also be configured to automatically assign priorities to tickets based on the severity of the ticket, and assign tickets to users.

Nullify posts updates asynchronously so developers stay inside their existing workflows.

## Webhook sync

Jira issue updates synchronize linked ticket status and assignee information back to Nullify. Sync accounts for issue moves and stale/out-of-order events; allow a delivery/retry interval before assuming the dashboard is out of sync. Preserve the issue link when moving work between projects.

For routing, settings-change previews, and explicit cleanup of tickets that fall outside new thresholds, see [Ticketing and SLAs](/configuration/configuration-ticketing).

## Automation and delivery controls

[Manager ground rules](/configuration/configuration-manager) control allowed ticket, PR, and messaging actions. [Notification settings](/configuration/configuration-notifications) separately select event filters and destinations. Delivery budgets and deduplication can defer or combine repeated escalations, so a missing individual message does not mean the finding was discarded.


# Install

Nullify uses Atlassian Forge for Jira integration. Jira Connect descriptors and developer-mode installation are retired; do not use an old Connect installation URL.

The shared Jira, Confluence and Compass setup is being prepared for Marketplace distribution. Availability depends on the production deployment and Atlassian approval. The existing Marketplace entry is private; an unpublished draft is not a customer installation destination. Nullify uses enterprise pricing under your existing agreement.

## Set up the shared app when available

1. Open **Settings → Connectors → Atlassian** in Nullify, or choose Atlassian in the Workflow step of onboarding.
2. Enter your Atlassian site URL and select **Authorize site** as a Jira administrator. Nullify rejects the authorization if the consenting user lacks Jira administration permission on that site. Authorization associates the site with your Nullify tenant; installing the Forge app is a separate action.
3. Select **Install Nullify on Atlassian** when it is offered. If the panel says self-service installation is not available, contact Nullify support; do not substitute another app or a Connect descriptor. If Nullify is already installed on the site, authorize the site and then check its installation.
4. Approve the permissions shown by Atlassian. Jira is required; Confluence and Compass are optional contexts on the same site.
5. Return to Nullify and select **Check installation**. Enable the integrations you need. For Confluence, select the numeric IDs of the spaces whose security documentation Nullify may read.

Jira declares its issue and comment subscriptions in the Forge manifest. No manually configured Jira webhook is required. Product settings control Jira processing and Confluence reads separately. Compass ownership ingestion into the shared router app is still being completed. DX connects independently using an organisation token; it is not installed through Forge.

## Issue type

By default, Nullify creates tickets using the **Task** issue type. Select a different issue type in the Jira configuration if needed; it must exist in the target project. See [Configuration](/connectors/jira/configuration).


# Configuration

Nullify creates a new issue in Jira for each finding above the configured threshold. The Jira connector is configured from the Nullify dashboard under **Configure -> Ticketing** (and the per-integration Jira settings) — there is no `.nullify.yml` file.

In the Jira integration settings you set the **Project Key** and the **Issue Type**:

* **Project Key** is the key of the target Jira project. This is the same key that appears in the URL when you are in the project.
* **Issue Type** is the type of issue Nullify creates. The default is **Task**. You can find the available issue types in your Jira project settings under Issues -> Types (the URL is of the form `https://your-team.atlassian.net/plugins/servlet/project-config/YOUR-PROJECT-KEY/issuetypes`).

You may prefer to create a dedicated issue type for Nullify's findings if you want to track tickets opened by Nullify separately. Create it in Jira first, then select it in the dashboard.

## Optional Configuration

### Severity and Priority Threshold

Automatic ticket creation is **off by default** — enable it per finding type under **Configure -> Ticketing**, where you also set the threshold at which a ticket is created.

For example, you might want the issues dashboard to include all findings of severity MEDIUM or higher, but only create a Jira ticket for findings that are URGENT. The priorities you can set a ticket threshold to are `URGENT` and `IMPORTANT` — so you might surface everything at IMPORTANT or higher on the dashboard while only ticketing URGENT findings.

{% hint style="info" %}
Nullify only auto-creates tickets for findings at **IMPORTANT** priority or above, regardless of the threshold you set. To capture a lower-priority finding, create the ticket [manually](/connectors/jira/manual_creation) from the dashboard.
{% endhint %}

### On Fix

Nullify closes the ticket in Jira when the underlying finding is fixed. By default, the ticket transitions to the last (right-most) column on your board. If you want a different target status when a finding is fixed, set the fix transition in the Jira integration settings to the status you want. The match is case-insensitive, and the target status must already exist in the project workflow.

### Scoping automatic creation

Because automatic ticket creation is enabled per finding type, you can keep it on for the finding types that matter and off for the rest. A typical use case is enabling it globally but turning it off for a specific repository — for example, an internal tool or script that is not used in production.

You can also leave automatic creation off while keeping the project key and issue type configured, so you can still *manually* create tickets from the dashboard when needed.


# Assignee Rules

You can set a default assignee for Jira tickets in the Jira integration settings in the Nullify dashboard.

A Jira Cloud user is identified by an **account ID** — an alphanumeric string such as `5b10a2844c20165700ede21g` (not a numeric id). You can find a user's account ID in their Jira profile: open the user's profile and copy the ID from the URL, or use the Jira admin user management page.

New Jira and Linear tickets require an assignee. Nullify first uses a person selected for that ticket, then the integration's default assignee, then the confirmed security owner. A security owner can be a person or a team's current lead. The account must be active and assignable in the destination project.

The default assignee setting is optional when a confirmed security owner is available. Existing tenants need to configure one of these choices before automatic ticket creation can succeed. If neither resolves to a valid account, automatic creation stops and manual creation asks you to select an assignee. Provider outages can be retried without changing the selected account.

The recommended owner in the ticket body is separate from its assignee. It identifies the author of the relevant source change when available; otherwise it says `Recommended owner: owner unknown`.

When configuring the default assignee, provide the user's account ID so Nullify assigns the ticket to exactly that user. You may also record the user's display name alongside it for readability, but the account ID is what determines the assignee.

Omitting `defaultAssigneeId` from a configuration update preserves the saved account, including when the project or team changes. An empty string clears it. Ticket creation validates the saved account against the destination project or team before using it. If it is no longer assignable there, Nullify tries the confirmed security owner and otherwise requires an explicit assignee. Provide a new default or clear the old one when changing destinations if you do not want it retained.

## Identity mapping

Nullify can suggest mappings between source-control, messaging, and ticketing identities using names and other available account information. Similarity is a suggestion, not proof two accounts belong to the same person. Review suggested mappings in the dashboard or resolve the corresponding action item before relying on ownership routing. Explicit mappings and destination account IDs avoid ambiguity.


# Priorities

Nullify maps finding priority to the destination Jira priority when it creates a ticket. The default mapping uses Jira's standard highest, high, medium, and low priorities.

There is currently no dashboard editor or public configuration write path for a custom Nullify-to-Jira priority mapping. Do not look for a mapping control in the Jira connection form. If your project uses a different priority scheme, verify the priority on a test ticket and contact Nullify if the default does not resolve correctly.

Finding priority, severity, and Jira priority are different fields. Ticket-creation thresholds are configured separately under [Ticketing and SLAs](/configuration/configuration-ticketing); changing a threshold does not create a custom Jira priority scheme.


# Manual Ticket Creation

You can create a ticket for an individual finding even when automatic ticketing is disabled. Open the finding in **Findings**, choose **Create ticket**, add an optional note, and confirm. The current dialog uses the connected ticketing destination and selects the project through configured routing; it does not expose a Jira-specific project/issue-type picker.

![Create ticket dialog with a sample finding](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-fed1efe4820ffa56b79771efcf57e121d3ed1cf5%2Fcreate-ticket.png?alt=media)

After creation, follow the ticket link on the finding to inspect its destination, assignment, and content. A failed request is not a created ticket; check the error before retrying.

## Routing and prerequisites

Connect Jira and configure its default project and issue type first. [Ticketing settings](/configuration/configuration-ticketing) describe proposal routing and explicit API destinations. Manual ticket creation is distinct from an automatically approved ticket proposal and may require its own permissions. Check [assignee mapping](/connectors/jira/assignee) if the resulting issue has no owner.

Older dashboards place the action on a triage or vulnerability detail page. The API remains available for automation; use the finding type's `/ticket` operation in the [API reference](/api-reference/api-reference).


# Linear

## Overview

Nullify can be configured to integrate with Linear to automatically create and update issues based on the findings in your project. It is Nullify's second ticketing provider after [Jira](/connectors/jira).

When a finding crosses the configured threshold, Nullify files a Linear issue in your chosen team. As work progresses, Nullify keeps the issue in sync — and as your team moves the issue through its workflow in Linear, those status changes flow back into Nullify so the finding's ticket state stays accurate on both sides.

Nullify posts updates asynchronously so developers stay inside their existing workflows.

## Installation

Nullify connects to Linear over OAuth 2.0 using a Nullify-owned Linear app — there is nothing to install from the Linear marketplace and no app descriptor to upload.

### Connect your Linear workspace

1. In the Nullify dashboard, go to **Settings -> Connectors** and start the Linear connection. A user with config-write permission must perform this step.
2. Nullify generates a Linear authorize URL and redirects your browser to Linear's consent screen. The app requests the `read` and `write` scopes so it can create issues, update their status, and read the issues it manages.
3. Approve the consent screen in Linear. Linear redirects your browser back to Nullify, which exchanges the authorization code for an access token and records the install against your tenant. You'll see a "Linear connected" confirmation page.

Webhooks need no setup on your side. Nullify's Linear app carries its own `Issue` and `Comment` webhook subscription, and Linear starts delivering your workspace's events to Nullify the moment you approve the consent screen. Nothing is created in, or requires admin rights on, your workspace. See [Webhook Sync](#webhook-sync) below.

{% hint style="info" %}
You can check whether your tenant has completed the Linear install at any time — the dashboard reflects the connection status, backed by `GET /admin/integrations/linear/oauth`.
{% endhint %}

### API reference

The OAuth flow is driven by the admin API:

* `GET /admin/integrations/linear/install` — starts the install. Returns the Linear authorize URL the browser is sent to, and persists a short-lived state token keyed to your tenant.
* `GET /admin/integrations/linear/oauth/callback` — the redirect target Linear returns to. Exchanges the code for an access token and records the install.
* `GET /admin/integrations/linear/oauth` — returns whether your tenant has a completed Linear install on record.

## What it does

Once connected, Nullify creates a Linear issue for each finding above the configured threshold and updates it over the finding's lifecycle:

* **Create** — a new finding produces a new Linear issue in your configured team.
* **Status sync** — when the finding is fixed, Nullify moves the issue toward a completed state; when the issue is reopened or moved back in Linear, that reopen is reflected on the Nullify side.

Linear issues are created with the **Task** issue type by default, consistent with the rest of Nullify's ticketing.

## Configuration

The Linear connector is configured from the Nullify dashboard under **Settings -> Ticketing** (and the per-integration Linear settings) — there is no `.nullify.yml` file.

### Team

Nullify files work items against a specific Linear **team**. Set the team in the Linear integration settings; this is what tells manual and automatic ticket creation which Linear team an issue should be created in. Until a team is set, the Linear integration stays inactive even if the OAuth install has completed — the team association is the trigger that turns ticketing on.

API: `POST /admin/integrations/linear/ticket-config` with the target `teamId`. This is stored independently of the OAuth tokens, so you can connect the workspace and choose the team in either order.

### Assignee

New Linear tickets require an active assignee in the destination team. Set a default assignee in the Linear integration settings, or confirm a security owner in Ticketing settings. Existing tenants need to complete this setup before automatic ticket creation can succeed.

API: include the Linear user's ID as `defaultAssigneeId` alongside `teamId` in `POST /admin/integrations/linear/ticket-config`. Nullify validates the account before saving it. Omit the field to preserve the current default; send an empty string to clear it.

Changing teams while omitting `defaultAssigneeId` preserves the saved account. Ticket creation revalidates that account against the destination team. If it cannot be assigned there, Nullify tries the confirmed security owner; without an eligible account, creation requires an explicit assignee. Send a new default or clear the old one when changing teams if this is not desired.

An explicit selection takes precedence over the default, followed by the confirmed security owner. If no account is available, automatic creation stops and manual creation returns a precondition error and asks you to choose an assignee. The recommended owner in the ticket body does not change assignment. See [Assignee rules](/connectors/jira/assignee).

### Severity and Priority Threshold

By default, Nullify creates tickets using the same severity and priority thresholds reported in the dashboard. You can also set thresholds specific to ticket creation under **Settings -> Ticketing**, per finding type.

For example, you might want the issues dashboard to include all findings of priority IMPORTANT or higher, but only create a Linear issue for findings that are URGENT. Nullify's full priority taxonomy is described in [Triage](/capabilities/triage), so you can surface everything at IMPORTANT or higher on the dashboard while only ticketing URGENT findings.

### Disable

You can disable automatic Linear ticket creation from the dashboard. A typical use case is when you have the Linear connector configured globally but want to turn off automatic ticket creation for a specific repository — for example, an internal tool or script that is not used in production.

You can also disable *automatic* ticket creation while keeping the team configured, so that you can still *manually* create tickets from the dashboard when needed.

## Webhook Sync

Status changes you make in Linear are synced back into Nullify automatically. The `Issue` and `Comment` subscription lives on the Nullify Linear app itself, so authorizing the app is the only step — Nullify processes the changes that matter for keeping finding tickets accurate:

* **Workflow-state changes** — when an issue moves to a new workflow state, Nullify maps Linear's state type (for example a `completed` or `cancelled` state) to the corresponding internal ticket status and updates the finding's ticket. A move into a terminal state is treated as a close; a move back out is treated as a reopen. Tenants running a custom Linear workflow can override the default state mapping per tenant.
* **Assignee changes** — assignee updates on a tracked issue are forwarded so the finding's ticket reflects who currently owns it.

Edits that don't affect workflow state or assignee (label-only changes, comment-only events, title edits) are ignored.

Each delivery is verified with an HMAC-SHA256 signature against the Nullify app's signing secret before anything in the payload is read. Deliveries whose signature does not match are rejected — Nullify never processes an unverified state change. Deliveries are also de-duplicated so a Linear retry of the same event is not applied twice.

{% hint style="info" %}
Every authorizing workspace's events arrive on one Nullify endpoint. Nullify reads your workspace's organization ID from the verified payload and resolves it to your tenant from the OAuth install record, so events are only ever applied to your own findings. No additional setup is required on your side.
{% endhint %}

## Automation and delivery controls

[Manager ground rules](/configuration/configuration-manager) control allowed ticket, PR, and messaging actions. [Notification settings](/configuration/configuration-notifications) separately select event filters and destinations. Delivery budgets and deduplication can defer or combine repeated escalations, so a missing individual message does not mean the finding was discarded.


# Compass

## Overview

Connect Nullify to [Atlassian Compass](https://www.atlassian.com/software/compass) to import your teams and the components they own (repositories, services, and other assets). Nullify uses this ownership model to route findings, fix pull requests, and escalations to the right team — so security work lands with the people who own the affected code.

Compass data syncs periodically in the background, and Nullify posts its updates asynchronously so developers stay inside their existing workflows.

## Ownership mapping

Install the [Compass app](/connectors/compass/install), then confirm the imported teams and repository ownership in [team settings](/configuration/account-and-teams). Compass/Atlassian teams are stored with an Atlassian identity even if your organization's ticket destination is another tool. Importing a team does not change the configured ticketing destination.

Repository URLs are resolved against repositories already known to Nullify. Connect and enroll a repository before expecting its Compass component ownership to apply. Unresolvable or malformed links are skipped; a successful team import does not prove every component link was mapped. Supported component links into a repository subdirectory become path-based ownership patterns for monorepos. Verify those patterns against the files the team owns.


# Install

1. Open the **Nullify Compass** listing in the [Atlassian Marketplace](https://marketplace.atlassian.com/) (or use the install link your Nullify representative provides) and click the **Get App** button.

<figure><img src="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-07137c7636e0baaf159e19417a41baeec34dcb53%2Flisting.png?alt=media" alt=""><figcaption><p>Install Listing</p></figcaption></figure>

2. Select the Compass organization you want to install the app into and click **Install**.

<figure><img src="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-8811d083ac785f4e02e0ee91219bf5471b5f542c%2Fselect.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Go to your Compass instance in the browser.
4. In the menu bar at the top of the screen, click the **Apps** dropdown, then click **Manage your apps**.
5. Find the **Nullify Compass** app and click **Configure**.

<figure><img src="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-8e58f848980d74c57c644bfb1415119fce4439f1%2Fsettings.png?alt=media" alt=""><figcaption><p>Manage Apps</p></figcaption></figure>

6. In another browser tab, go to your Nullify dashboard configure page, e.g. `https://app.<TENANT>.nullify.ai/dashboard/configure/general`.
7. Go to **Service Accounts**, create a service account, copy the token, and paste it into the Compass app configuration.
8. Copy the GitHub owner ID and paste it into the Compass app configuration.

<figure><img src="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-54d62f3269a10ee88cb49f8d24192e4653fa4fd9%2Fconfigure.png?alt=media" alt=""><figcaption><p>Configure App</p></figcaption></figure>

9. Save the Compass app settings.

After all of the steps are completed, your Compass data will be synced with Nullify periodically.


# AWS

## Overview

Connect AWS to Nullify for cloud-to-code traceability. The connector deploys a least-privilege cross-account role so the platform can ingest resource metadata, evaluate exposure, and correlate findings with the code that built those resources.

## Key Benefits

* **Cloud-to-code mapping** — Tie vulnerabilities back to specific AWS accounts, regions, and IaC definitions.
* **Blast-radius awareness** — Understand which services, identities, and networks are reachable from an exposed asset.
* **Multi-account coverage** — Operate across entire AWS Organizations with consistent policy.
* **Secure access** — Uses external IDs, scoped IAM roles, and encrypted transport.

## How It Works

1. Configure connector parameters in the Nullify console.
2. Deploy the generated CloudFormation or Terraform template into each AWS account.
3. Nullify validates the role and begins ingesting metadata for cloud exposure assessments.

Full setup instructions, parameters, and troubleshooting are documented in [Configuration](/connectors/aws/configuration).

## Support

* Implementation assistance: <support@nullify.ai>
* Feature requests: [GitHub issue tracker](https://github.com/nullify-platform/feature-requests)

Telemetry and findings flow back asynchronously into Jira, Slack, and Nullify dashboards so remediation stays aligned with cloud owners.

## Deployment choices

The [cloud connector repository](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/aws-integration-setup) provides CloudFormation, Terraform for AWS provider v5, and a separate `terraform-v6` variant. Use the variant matching your provider version. Multi-cluster EKS trust can be provisioned with the AWS integration; cluster trust and Kubernetes object collection still need their respective permissions.

For review of the granted access, see [AWS Permissions](/connectors/aws/permissions).


# Configuration

## Requirements

* An active Nullify tenant.
* AWS permissions to create IAM roles and (optionally) deploy CloudFormation StackSets.
* Access to Terraform or CloudFormation tooling.

## Setup Overview

Nullify uses cross-account IAM roles to ingest metadata from your AWS accounts. The dashboard supplies the parameters you need to deploy our CloudFormation or Terraform template.

## Information You Provide

* **IAM role name** to create within your accounts (for example `nullify-cross-account-role`).
* **Target account IDs** that Nullify should monitor.

## Parameters Supplied by Nullify

* **Nullify role ARN** for the external principal.
* **External ID** to enforce a trusted relationship.
* **S3 bucket name** for encrypted data transfer when required.

All example identifiers below are placeholders—replace them with the values displayed in your tenant.

## Setup Steps

1. **Open the Nullify console**: `Configure → Connectors → AWS`.
2. **Enter your role name** and list of account IDs.
3. **Download the deployment template** (CloudFormation or Terraform) with your tenant-specific parameters embedded.
4. **Deploy the template**:
   * *Single account*: Launch via AWS Console, CLI, or your preferred IaC workflow.
   * *Multiple accounts*: Use CloudFormation StackSets or Terraform loops. Ensure the role name is consistent across accounts.
5. **Verify the connector**: return to the Nullify console to confirm that the role can be assumed.

## Deployment Modes

### Single Account

Deploy the template directly into the account hosting your workloads. Grant the cross-account role permission to discover resources in the regions you care about.

### Multi-Account / AWS Organizations

Use StackSets or Terraform to roll out the connector across member accounts. Deploy the role to both the management and member accounts so Nullify can analyse shared services and spokes.

> The current release expects the same IAM role name in every account. Contact support if you require per-account variation.

## Validation Checklist

* Account IDs are valid 12-digit numbers.
* The IAM role exists and trusts the Nullify role ARN with the provided external ID.
* The permissions policy matches the template (least privilege for discovery only).

## Troubleshooting

* **Role not found** — Confirm the StackSet or Terraform run succeeded in each account.
* **Access denied** — Verify the trust policy includes the Nullify role ARN and external ID.
* **Stale data** — Make sure CloudTrail/Config events are flowing if you rely on change detection.

## Kubernetes (optional add-on)

To relate Kubernetes workloads back to your AWS accounts, deploy the [Nullify Kubernetes Collector](https://github.com/Nullify-Platform/nullify-cloud-connector) into your clusters. See the [Kubernetes connector guide](/connectors/kubernetes) for setup; the Helm chart includes installation instructions, configuration samples, and troubleshooting guidance.

## Multiple accounts and validation

Record each account's ID, display name, environment classification, and whether it is the default account. Verify each account independently: one successful role assumption does not validate every account in an organization. Keep production classification accurate because runtime-testing policy can depend on it.

## Installation options

Use the [AWS setup scripts](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/aws-integration-setup/scripts) for interactive installation (`setup-aws-integration.sh`) and deployment verification (`validate-deployment.sh`). Review their help and the generated permissions before running. `cleanup.sh` removes deployed integration resources; it is an uninstall operation, not a troubleshooting step.

The Terraform `k8s-resources` module can install the collector through the Kubernetes provider. Alternatively use the [Helm collector](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/helm-charts/nullify-k8s-collector). Choose one owner for the collector resources rather than installing both over the same names. The AWS provider-v6 examples also support multi-region EKS clusters; consult that variant's prerequisites before using ephemeral EKS credentials.


# AWS Permissions

Review the connector template before deployment and compare it with your organization's access policy. The integration primarily reads resource configuration, but its transport and encryption policies also permit writing collected data to the configured Nullify bucket. “Read-only integration” does not mean every IAM action is a read.

## Policy groups

| Policy                                         | Purpose                                                                                                                                                                                   |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ReadOnlyAccessPolicy and ReadOnlyAccessPolicy2 | Describe/list/get configuration across supported AWS services, including IAM, networking, compute, storage, databases, and security services. Many inventory operations use resource `*`. |
| DenyActionsPolicy                              | Explicitly deny sensitive data and access operations, including secret-value access and API Gateway key/usage-plan reads. These denials constrain the allows; inspect the full list.      |
| S3AccessPolicy                                 | Read/write transport access scoped to the configured bucket and, when provided, its access point.                                                                                         |
| KMSAccessPolicy                                | Key operations for the configured collection/encryption path, with resource and condition restrictions.                                                                                   |

[Download the complete extracted policy documents](https://github.com/Nullify-Platform/nullify/tree/main/public-docs/.gitbook/assets/aws/iam-policy-reference.json) for the action lists, resources, and conditions. This is a reference extraction, not a standalone deployable IAM policy: CloudFormation expressions such as `Ref`, `Fn::Sub`, and `Fn::If` require the template parameters.

The reference is generated from cloud-connector revision `8a524f427df4dfdb03c29fab3686e79a19df4fe8`. Check the [source CloudFormation template at that revision](https://github.com/Nullify-Platform/nullify-cloud-connector/blob/8a524f427df4dfdb03c29fab3686e79a19df4fe8/aws-integration-setup/cloudformation/nullify-cloudformation-template.json) for role attachments, trust policy, deployment conditions, and defaults. A Terraform or collector variant can differ; review the exact artifact you deploy.

## Trust and scope

Cross-account role assumption is constrained by the configured principal and external ID. Optional EKS federation adds the configured OIDC provider and collector service-account subject. Adding collection permissions is separate from configuring a principal that can assume the role.

Deploy only into the accounts and regions you intend to monitor. If you remove an action, confirm the affected inventory or rule coverage: a successful role assumption is not proof that every requested resource was collected. Use the [configuration guide](/connectors/aws/configuration) to validate the connection and the resulting inventory.


# GCP

## Overview

Connect GCP to Nullify for cloud-to-code traceability. The connector uses Workload Identity Federation (WIF) with OIDC — no long-lived service account keys, no secrets to manage.

## Key Benefits

* **Cloud-to-code mapping** — Tie vulnerabilities back to specific GCP projects, regions, and IaC definitions.
* **Blast-radius awareness** — Understand which services, identities, and networks are reachable from an exposed asset.
* **Multi-project coverage** — Operate across GCP organizations, folders, or individual projects.
* **Secure access** — Uses OIDC federation with per-tenant trust. No service account JSON keys.
* **Read-only** — Nullify cannot modify your environment, read object data, or access secret payloads.

## How It Works

1. Deploy the Nullify Terraform module in your GCP project. This creates a workload identity pool, a read-only service account, and IAM bindings.
2. Paste the `service_account_email` and `workload_identity_provider` outputs into the Nullify console.
3. Nullify validates the credentials and begins ingesting metadata for cloud exposure assessments.

Full setup instructions are documented in [Configuration](/connectors/gcp/configuration).

## Optional: Kubernetes Collector (GKE)

Deploy the Nullify k8s-collector to your GKE clusters for workload-level visibility (pods, services, deployments, ingresses).

1. Share your cluster's OIDC issuer URL with Nullify (one `gcloud` command).
2. Nullify returns a role ARN.
3. Deploy the Helm chart with the role ARN.

No GCP service account or Workload Identity binding required. See [Configuration](/connectors/gcp/configuration#kubernetes-collector-gke) for details.

## Support

* Implementation assistance: <support@nullify.ai>
* Terraform module: [nullify-cloud-connector](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/gcp-integration-setup/terraform)


# Configuration

## Requirements

* An active Nullify tenant.
* A GCP project with permissions to create workload identity pools and service accounts.
* Terraform >= 1.3 (recommended) or `gcloud` CLI.
* For organization or folder scope: org admin access.

## Setup Overview

Nullify uses Workload Identity Federation (WIF) with OIDC to access your GCP environment. The Terraform module creates a workload identity pool, a read-only service account, and the minimum IAM bindings needed for cloud scanning.

## Parameters Supplied by Nullify

Available in the Nullify console under **Configure > Connectors > GCP**:

* **OIDC Issuer URI** — `https://gcp.nullify.ai` (production)
* **Tenant ID** — Your Nullify tenant identifier

## Information You Provide

After deploying the Terraform module:

* **Workload Identity Provider** — The full resource path from the Terraform output
* **Service Account Email** — The impersonated service account email from the Terraform output
* **Project IDs** — The GCP projects Nullify should scan

## Setup Steps

1. **Clone the Terraform module**:

   ```bash
   git clone https://github.com/Nullify-Platform/nullify-cloud-connector.git
   cd nullify-cloud-connector/gcp-integration-setup/terraform
   ```
2. **Configure variables**:

   ```bash
   cp terraform.tfvars.example terraform.tfvars
   ```

   Fill in:

   * `gcp_project_id` — Your GCP project
   * `nullify_oidc_issuer_uri` — From the Nullify console
   * `nullify_tenant_id` — From the Nullify console
   * `scope` — `"organization"`, `"folder"`, or `"projects"`
   * `organization_id` — Required for org or folder scope
3. **Deploy**:

   ```bash
   terraform init
   terraform plan
   terraform apply
   ```
4. **Configure in Nullify console**:
   * Go to **Configure > Connectors > GCP**
   * Paste the `workload_identity_provider` output
   * Paste the `service_account_email` output
   * Add your GCP project IDs
   * Click **Save** — Nullify auto-verifies the credentials

## Scope Options

| Scope          | Use When                          | Requires                        |
| -------------- | --------------------------------- | ------------------------------- |
| `organization` | Scan all projects in your GCP org | `organization_id`               |
| `folder`       | Scan all projects in a folder     | `organization_id` + `folder_id` |
| `projects`     | Scan specific projects only       | `project_ids` list              |

## Permissions

Nullify requests **read-only** access. No write, no data-plane, no code execution permissions.

**Predefined roles**: `cloudasset.viewer`, `iam.securityReviewer`, `compute.viewer`, `container.clusterViewer`, `cloudsql.viewer`, `spanner.viewer`, `cloudkms.viewer`, `logging.viewer`, `run.viewer`, `cloudfunctions.viewer`, `appengine.appViewer`, `dataproc.viewer`, `dataflow.viewer`, `pubsub.viewer`

**Custom role** (`nullifyCloudConnector`): Read-only permissions for Cloud Armor, VPC Service Controls, org policies, AlloyDB, Filestore, Memorystore, Artifact Registry, Cloud DNS, and API Gateway.

Full permission justification: [permissions.md](https://github.com/Nullify-Platform/nullify-cloud-connector/blob/main/gcp-integration-setup/docs/permissions.md)

## Revoking Access

```bash
terraform destroy
```

This deletes the workload identity pool, service account, and all IAM bindings.

***

## Kubernetes Collector (GKE)

Deploy the Nullify k8s-collector to GKE clusters for workload-level visibility.

### Prerequisites

* Any GKE cluster (Standard, Autopilot, private, or public)
* Kubernetes 1.22+
* Helm v3
* No special GKE configuration required

### Setup

1. **Get your cluster's OIDC issuer URL**:

   ```bash
   gcloud container clusters describe CLUSTER --zone ZONE \
     --format='value(selfLink)'
   ```
2. **Register in Nullify console**:
   * Go to **Configure > Connectors > GCP > GKE Clusters**
   * Add the OIDC issuer URL
   * Click **Save**
   * Copy the **K8s Collector Role ARN** displayed on the card
3. **Deploy the Helm chart**:

   ```bash
   helm repo add nullify https://nullify-platform.github.io/nullify-cloud-connector/
   helm repo update

   helm install nullify-collector nullify/nullify-k8s-collector \
     --namespace nullify --create-namespace \
     --set cloudProvider=gcp \
     --set collector.clusterName=my-gke-cluster \
     --set collector.aws.region=us-east-1 \
     --set collector.s3.bucket=your-nullify-bucket \
     --set collector.kms.keyArn=arn:aws:kms:us-east-1:123456789012:key/... \
     --set collector.gke.awsRoleArn=arn:aws:iam::123456789012:role/...
   ```

   The `collector.aws.region`, `collector.s3.bucket`, `collector.kms.keyArn`, and role ARN values all come from the Nullify **Configure → Connectors** page. The collector runs on a schedule (daily by default); adjust `collector.schedule` if you need a different cadence.

### What the Collector Gathers

* Cluster metadata (version, node pools)
* Namespaces, pods, deployments, statefulsets, daemonsets
* Services, ingresses, endpoints
* RBAC (roles, role bindings, service accounts)
* Network policies
* Persistent volumes and claims

Data is uploaded to Nullify's S3 bucket encrypted in transit. No cluster modifications are made.

## Troubleshooting

| Symptom                                                    | Likely Cause                                                                             |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Verify returns red with `permission denied`                | The Nullify SA is missing IAM bindings. Re-run `terraform apply`.                        |
| Verify returns red with `invalid token`                    | `nullify_oidc_issuer_uri` doesn't match. Use `https://gcp.nullify.ai` for production.    |
| k8s-collector fails with `AssumeRoleWithWebIdentity` error | The cluster OIDC URL wasn't registered in the Nullify console, or the role ARN is wrong. |
| k8s-collector pod stuck in `Pending`                       | Insufficient CPU/memory on the node. Reduce resource requests in Helm values.            |
| Connector shows `Not Verified`                             | Click Verify in the console, or re-save the settings to trigger auto-verify.             |

## gcloud-only installation

For **organization-wide** access without Terraform, use the connector's [gcloud installer](https://github.com/Nullify-Platform/nullify-cloud-connector/blob/main/gcp-integration-setup/scripts/install.sh). Folder and project scope require the Terraform module.

```bash
export NULLIFY_HOST_PROJECT='your-security-project'
export NULLIFY_ORG_ID='your-organization-id'
export NULLIFY_OIDC_ISSUER_URI='https://gcp.nullify.ai'
export NULLIFY_TENANT_ID='your-tenant-id-from-nullify'
# From a reviewed checkout of nullify-cloud-connector:
bash gcp-integration-setup/scripts/install.sh
```

Use the exact tenant ID and issuer supplied by Nullify. The installer creates the federation and organization-level read permissions; inspect its permission list before granting access. Copy the resulting identity settings into Nullify and verify collection. Use the separate uninstall script only when deliberately removing the integration.


# Azure Cloud

Connect Azure subscriptions for infrastructure inventory and cloud posture. This is separate from [Azure DevOps](/connectors/azure) repositories and boards, and from Microsoft sign-in.

## Scope and access

The supported Terraform connector creates an Entra application and service principal with **Reader** access to either a management group or an explicit subscription list. Management-group scope includes its child subscriptions; use subscription scope when that is the intended boundary.

The default authentication mode is **Workload Identity Federation**: a federated credential trusts the Nullify issuer and tenant subject without creating a client secret. Before deploying Terraform, obtain the issuer URL and raw Nullify tenant ID from Nullify support or your Nullify representative. Azure settings cannot display these values until a configuration has already been saved. The Terraform module adds the `nullify-tenant:` subject prefix; do not add it yourself.

## Install

1. Sign in to the correct Azure tenant with `az login`.
2. Use the [Azure Terraform connector](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/azure-integration-setup/terraform). Copy its example variables and set `customer_name`, `scope`, the management-group ID or subscription IDs, `nullify_oidc_issuer_url`, and `nullify_tenant_id`.
3. Review `terraform plan` before applying. The installer needs rights to create the application/federated credential and assign Reader at the selected scope.
4. Copy the `entra_tenant_id` and `application_client_id` outputs into **Settings → Connectors → Azure**, choose **Workload Identity Federation**, and select **Save changes**.
5. After saving, validate the stored federation with `POST /admin/integrations/cloud/azure/validate` (or ask Nullify to validate it). The current settings panel does not provide a separate Verify button.
6. Check inventory and scan status for each intended subscription.

If federation cannot be used, the console also supports a service-principal client secret. The module deliberately does not generate that secret. Create and rotate it through your organization's approved Entra process.

## Optional directory coverage

`enable_directory_read` defaults to false. Enabling it adds Microsoft Graph `Directory.Read.All` and `Policy.Read.All` for directory and conditional-access analysis. These are tenant-wide permissions beyond ARM Reader and require an appropriately privileged administrator's consent. Leave the option off when resource/RBAC coverage is sufficient.

AKS collection is configured through the [Kubernetes connector](/connectors/kubernetes); connecting subscriptions alone does not imply access to Kubernetes workload objects. Revoke federation by deleting the relevant federated credential and remove role assignments when disconnecting access.


# Wiz

The Wiz connector imports cloud resource inventory and configuration so Nullify can evaluate accounts already covered by your Wiz tenant. It is an inbound scanner-source integration, not a destination for exporting Nullify findings. Availability is enabled per tenant; contact Nullify if Wiz is absent from your integration catalog.

## Connect

1. Create or select a Wiz service account with permission to read the intended inventory.
2. Copy your tenant's GraphQL API endpoint from Wiz's service-account settings.
3. In Nullify's Wiz connection form, enter `apiEndpoint`, `clientId`, and `clientSecret`.
4. Select the identity provider: `cognito` for `auth.app.wiz.io`, `auth0` for `auth.wiz.io`, or `custom` with `customTokenUrl` and, if needed, `customAudience`.
5. Select **Connect** to save the connection. Reopen its management form, then select **Test** to check the stored connection. Confirm that the expected accounts and resources appear after collection.

Choosing the wrong identity provider can return `401` even when the client credentials are correct. Verify the token service for your Wiz tenant before rotating a working secret. Keep the secret in the connector's secret field.

Wiz-sourced configuration can feed [Cloud Audits](/capabilities/cloud-audits). Incomplete upstream inventory can limit coverage; an account with no imported resources is not automatically a clean account.


# Private Package Registries

Connect a private package source so Nullify can resolve dependency metadata and supported package operations for repositories that use it. Package-registry connections are separate from container image scanning and source-control access.

## Setup

**GitHub Packages (npm)** is the only package-registry connector currently available in the Settings → Connectors user interface. Open its card, provide the scope, machine-user credentials, and test package, then select **Connect**.

Configure the other registry types through the Admin API:

1. Use `GET /admin/integrations/catalog` to identify the provider, capability, and required fields available to your tenant.
2. Create a connection with `POST /admin/integrations/{providerId}/{capability}/connections`. Put the chosen catalog entry's configuration and credential values inside a `fields` object, using its exact schema keys; `displayName` is optional alongside `fields`. Endpoint and credential keys differ by provider. Create separate connections for distinct registry origins or ecosystems.
3. List connections with `GET /admin/integrations/connections`. When the connector supports it, test a saved connection with `POST /admin/integrations/connections/{connectionId}/test`.
4. Rotate a credential with `PUT /admin/integrations/connections/{connectionId}/rotate`, wrapping the replacement field values in a `fields` object. Disconnect with `DELETE /admin/integrations/connections/{connectionId}`.
5. Re-run the affected dependency workflow and check that private packages resolve. A successful connection test does not prove every package is accessible.

| Connector             | Configuration                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Private npm           | Registry URL, read token, optional `@scope`. An optional ecosystem default covers packages without a more specific scope/origin match.                               |
| Private Maven         | Repository URL, username, and password or API token.                                                                                                                 |
| Private PyPI          | PEP 503 index URL, username, and password/token. Use the index's required token username, often `__token__`.                                                         |
| Private Go proxy      | Proxy URL, private module pattern, token, and optional basic-auth username. The private pattern identifies modules that bypass public proxy/checksum services.       |
| Artifactory packages  | Base URL, repository key, ecosystem, and the credential fields shown by the connector. Use one connection per ecosystem/repository.                                  |
| Nexus packages        | Base URL, repository name, ecosystem, and the Name Code/Pass Code pair from a Nexus user token. The Name Code is not your login username.                            |
| AWS CodeArtifact      | An existing AWS cloud connection, domain, domain-owner account ID, region, repository, and ecosystem. Nullify obtains a short-lived authorization token at use time. |
| GitHub Packages (npm) | Scope, dedicated machine-user username, classic PAT, and a real private test package. An optional package-origin override supports the configured enterprise host.   |

At most one connection per ecosystem should be the default. Prefer explicit origins or scopes where multiple registries are used. Rotating a connection should preserve its intended package scope.

## GitHub Packages credentials

{% hint style="warning" %}
This connector requires a **classic PAT with `read:packages` from a dedicated machine user**. It does not accept GitHub App installation tokens or fine-grained PATs. Your existing GitHub App connection does not supply this package credential.
{% endhint %}

Give the machine user access to the private test package and authorize it for organization SSO when required. Nullify validates the credential by reading that package on connect and rotation; failed validation does not replace a working stored credential. Use the package origin shown for your GitHub environment rather than assuming the public npm host applies.

## API lifecycle

The API lifecycle above supports multiple connection instances for a registry. See the [Admin API](/api-reference/api-reference/api-admin). Do not place credentials in repository configuration, URLs, or support screenshots.


# Kubernetes

## Overview

Connect Kubernetes to Nullify to audit your clusters for misconfiguration. Nullify evaluates a dedicated Kubernetes ruleset — workload, RBAC, network, and cluster-configuration checks — as part of its [Cloud Audits](/capabilities/cloud-audits) (CSPM) capability, then correlates findings with the accounts and code that own those clusters.

## Key Benefits

* **Cluster misconfiguration detection** — Catch insecure workloads, over-broad RBAC, missing network policy, and weak cluster controls before they are exploited.
* **Managed and on-prem coverage** — Works for cloud-managed clusters (EKS, GKE, and AKS via your Azure account) and self-hosted / on-prem clusters.
* **Refreshes as data lands** — Findings reconcile each time a cluster's inventory arrives. The in-cluster collector uploads on a schedule (daily by default, configurable), and Nullify re-audits each time new inventory lands.
* **Read-only** — The collector reads cluster metadata through the Kubernetes API and uploads it for analysis. Nullify does not modify your cluster.

## What It Scans

Nullify ships a dedicated Kubernetes ruleset (alongside the AWS, GCP, and Azure rulesets) that runs against the collected cluster inventory. Checks span:

* **Workloads** — privileged containers, host namespace sharing (host PID / IPC / network), privilege escalation, dangerous capabilities, hostPath volumes, image pinning, and pull-policy hygiene.
* **RBAC** — cluster-admin bindings, wildcard and escalation verbs, anonymous and default-service-account bindings, and stale or over-broad role grants.
* **Network & admission** — missing default-deny network policies, overly permissive ingress, and admission/webhook configuration weaknesses.
* **Cluster configuration** — etcd encryption, control-plane settings, and config-map hygiene (sensitive data, embedded credentials).

Each detection becomes a CSPM finding that is AI-triaged for false-positive likelihood and priority, the same as any AWS, GCP, or Azure cloud finding. See [Cloud Audits](/capabilities/cloud-audits) for the cross-provider view.

## How It Works

Nullify supports two scanning paths depending on cluster type:

1. **Managed clusters (EKS, GKE)** — Scanned platform-side using the underlying cloud account's credentials. Configure these alongside the cluster's cloud account ([AWS](/connectors/aws), [GCP](/connectors/gcp)). For AKS, connect your Azure account — self-service setup is available via the Azure Workload Identity Federation Terraform connector.
2. **On-prem / self-hosted clusters** — Scanned by the in-cluster Nullify Kubernetes collector, which walks the cluster API and uploads a cluster-inventory envelope to Nullify's secured upload area. An ingestor then validates the upload and stores it for scanning.

In both cases, a completed scan emits an event that drives the CSPM reconcile: new misconfigurations are stored and triaged, fixed ones are resolved, and reintroduced ones re-open — so cluster posture stays current without a fixed schedule.

## Collector Setup (On-Prem / Self-Hosted)

The Nullify Kubernetes collector ships in the `nullify-cloud-connector` Helm chart and runs inside your cluster. At a high level:

1. **Deploy the collector** into the target cluster via Helm. It runs on a schedule, authenticates to the Kubernetes API in-cluster (read-only), and collects cluster resources — nodes, namespaces, pods, services, deployments, RBAC, and related objects.
2. **Grant upload access.** The collector uploads its inventory envelope to Nullify's secured S3 upload area. Encryption in transit is enforced; the collector supports a KMS key for upload encryption.
3. **Whitelist the account(s).** Nullify must allow the uploading AWS account(s) to write to the bucket (and use the KMS key). See [Whitelisting Collector Accounts](#whitelisting-collector-accounts) below.

{% hint style="info" %}
The collector is read-only. It reads cluster metadata through the Kubernetes API and never writes to your cluster.
{% endhint %}

Cluster registration is managed through the admin API. A site administrator declares each cluster (name, type, and — for managed clusters — the cloud account ID and region) and optionally the Nullify role ARN used to reach the cluster.

## Whitelisting Collector Accounts

Collector uploads land in a Nullify-managed bucket whose access policy is allowlisted per AWS account. In the dashboard, the Kubernetes connector (**Settings → Connectors**, or the Cloud step of [Onboarding](/getting-started/getting-started)) lists the accounts allowed to upload, shows the collector S3 bucket, KMS key ARN and S3 access point ARN to configure the collector with, and lists the clusters discovered so far. The platform normally reconciles this allowlist automatically when cloud settings are saved, but a dedicated endpoint exists to (re)apply it on demand — useful during onboarding or if the bucket/KMS policy drifts:

```http
POST /admin/integrations/cloud/k8s/whitelist
```

```json
{
  "accountIds": ["123456789012"]
}
```

Behaviour:

* **`accountIds` (optional)** — The AWS account IDs allowed to upload collector data. If omitted, Nullify falls back to every account stored on the tenant's AWS cloud settings.
* The handler reconciles both the **upload bucket policy** and, when configured, the **KMS key policy**, and reports which were updated. If no KMS key ARN is configured, the response reports `"kmsSkipped": true` with `kmsPolicyUpdated: false` and no `kmsError`.
* Sending an empty request when no AWS accounts are configured is rejected as a bad request (an empty reconcile would strip the allowlist rather than extend it).

This endpoint requires config-write permission.

{% hint style="warning" %}
Whitelisting only grants upload access — it does not register a cluster or start a scan. Declare the cluster through cloud settings, then deploy the collector.
{% endhint %}

## Support

* Implementation assistance: <support@nullify.ai>
* Feature requests: [GitHub issue tracker](https://github.com/nullify-platform/feature-requests)

Findings flow asynchronously into Jira, Slack, and the Nullify dashboards so remediation stays aligned with cluster and cloud owners.

## Collector deployment choices

On EKS, AWS integration templates can establish OIDC trust for multiple clusters. Install collector resources using either the Terraform `k8s-resources` module or the [Helm chart](https://github.com/Nullify-Platform/nullify-cloud-connector/tree/main/helm-charts/nullify-k8s-collector), following that version's values and permissions. Trust configuration alone does not deploy a collector.

For AKS, start with [Azure cloud federation](/connectors/azure-cloud) and configure the cluster collection path for your tenant. Cloud subscription Reader access and Kubernetes API access are separate grants.


# Buildkite

## Overview

The Buildkite connector gives Nullify eyes on your CI. When Nullify opens an autofix pull request, your Buildkite pipeline runs against it like any other change — and if that build fails, Nullify reads the failure and fixes its own work before a human ever has to look. Once connected, Nullify can:

* **See your Buildkite builds** on the pull requests it opens, including pass/fail status.
* **Read the logs of a failed build** straight from the Buildkite API to understand *why* CI broke.
* **Iterate on the fix automatically**, feeding the real CI failure back to the autofix agent until the build is green.

The result is an autofix loop that's accountable to your actual pipeline — linting, tests, type checks, build steps and all — not just to Nullify's own checks. Teams that run Buildkite for CI alongside GitHub for source control get fixes that are already CI-clean by the time they land in review.

## How it works

Nullify never sits in the critical path of your pipeline and never changes how your builds run. It watches, reads, and iterates:

1. **Nullify pushes an autofix commit** to a pull request.
2. **Buildkite runs your pipeline** against that commit, exactly as it would for any developer push. (If your org gates *who* can trigger builds, Nullify's Buildkite user needs a seat on an allowed team first — see [Configuration → Step 5](/connectors/buildkite/configuration#build-creator-access).)
3. **Buildkite reports the result to GitHub** as a commit status (this is Buildkite's standard GitHub integration).
4. **Nullify detects the status** through its GitHub App — including when the build fails.
5. **Nullify fetches the failed job logs** from the Buildkite API using your connected token.
6. **The autofix agent iterates**, using the real failure output as context, and pushes a new commit — which kicks off the loop again until CI is green.

```
Autofix commit ─▶ Buildkite pipeline runs ─▶ Build fails
                                                  │
                          GitHub commit status ◀──┘
                                   │
                          Nullify detects failure
                                   │
                       Fetches Buildkite job logs ─▶ Agent iterates ─▶ new commit ↺
```

The connector reads build status and logs. Connecting it does not modify your pipeline configuration.

## Prerequisites

Before you start, make sure you have:

* A **Buildkite organization** with at least one pipeline that runs on your pull requests.
* The [**Buildkite GitHub App**](https://buildkite.com/docs/integrations/github#connect-your-buildkite-account-to-github) installed on your GitHub organization, with **commit statuses** enabled (this is how build results reach GitHub — and therefore Nullify).
* **GitHub already connected to Nullify.** Buildkite layers on top of the GitHub connection; it is not a standalone source-control integration.
* A **Buildkite API access token** with `read_organizations`, `read_builds`, and `read_build_logs`.
* **If your organization restricts who can trigger builds** (build-creator team gating): the ability to invite Nullify's Buildkite user to your org and add it to an allowed team — see [Configuration → Step 5](/connectors/buildkite/configuration#build-creator-access). Without this, Nullify's autofix commits never run a build in a gated org, so there's nothing for Nullify to read.

{% hint style="info" %}
**Use a dedicated service account for the API token, not a personal one.** Create a Buildkite user that exists only for Nullify (for example, `nullify-ci@yourcompany.com`), give it access to the organization, and mint the token from that account. This keeps the integration alive when people change teams or leave, scopes Nullify's access to exactly what that user can see, and makes the token easy to audit and rotate.

This token account is **separate** from Nullify's own Buildkite user (`integrations-bot@nullify.ai`) in [Configuration → Step 5](/connectors/buildkite/configuration#build-creator-access) — that user exists so Nullify's *commits* can trigger your builds in gated orgs, and is unrelated to the API token.
{% endhint %}

## Next steps

Follow the [**Configuration**](/connectors/buildkite/configuration) guide to create the token and connect your Buildkite organization.


# Configuration

Connecting Buildkite takes about five minutes and three things: a Buildkite API token, your organization slug, and a one-time GitHub permission acknowledgement. This guide walks through all three — plus an optional step for organizations that restrict who can trigger builds.

## Step 1: Create a Buildkite API token

We recommend minting the token from a **dedicated service-account user** rather than a personal account — see the [callout in the overview](/connectors/buildkite) for why. Log in to Buildkite **as that user**, then:

1. Go to **Personal Settings → API Access Tokens** (`https://buildkite.com/user/api-access-tokens`).
2. Click **New API Access Token**.
3. Give it a recognizable name, e.g. `nullify-ci-feedback`.
4. Scope it to the **single organization** Nullify should see.
5. Enable these three required scopes:
   * `read_organizations`
   * `read_builds`
   * `read_build_logs`
6. Click **Create Token** and copy the value. Buildkite API tokens are in the form `bkua_…`.

{% hint style="warning" %}
The token is shown **only once**. Copy it before you leave the page — if you lose it, you'll need to create a new one.
{% endhint %}

{% hint style="info" %}
**Required access.** Nullify uses `read_organizations` to verify organization access, `read_builds` for build status, and `read_build_logs` for autofix feedback. Setup verifies the required scopes before saving. Restrict the token to the intended organization; agent, pipeline-management, and token-management scopes are not required.
{% endhint %}

## Step 2: Connect Buildkite in Nullify

1. In the current dashboard, open **Settings → Connectors** (legacy: **Configure → Connectors**).
2. Find **Buildkite** and open its connection flow.
3. Enter the **API token**, then use **Find organizations** and select the organization it can access. The stored organization slug identifies `buildkite.com/<org-slug>`; older forms let you enter it directly.
4. Click **Save changes**.

The Buildkite card now shows **Active** with your organization name, and unlocks **Autofix CI Feedback**.

{% hint style="info" %}
**"Active" means the token was verified and saved.** Saving performs a live Buildkite API check before Nullify stores the token and organization slug. Run the end-to-end check in [Step 6](#step-6-verify) to confirm that GitHub status delivery, log retrieval, and autofix iteration are also wired up.
{% endhint %}

## Step 3: Make sure Buildkite reports to GitHub

Nullify learns about your builds through the commit status Buildkite posts to GitHub. If that status isn't being published, Nullify has nothing to react to.

1. In Buildkite, go to **Organization Settings → Repository Providers → GitHub**.
2. Confirm the **Buildkite GitHub App** is installed (not the legacy OAuth integration).
3. In each relevant **pipeline's settings**, confirm **Publish commit statuses** (under GitHub settings) is enabled.

You can sanity-check this independently of Nullify: open any recent pull request that triggered a build and confirm a `buildkite/…` status check appears on it.

## Step 4: Acknowledge the GitHub App permission <a href="#github-app-permissions" id="github-app-permissions"></a>

To receive those commit-status events, Nullify's GitHub App needs two things:

* **Repository permission:** *Commit statuses* → **Read-only**.
* **Event subscription:** the **Status** event.

These are already configured on the Nullify GitHub App. The only action on your side is a one-time acknowledgement: GitHub asks each organization owner to **accept the updated permissions**, shown as an email and a banner on your organization's installed-apps page.

{% hint style="warning" %}
Until your organization owner accepts the updated permission, GitHub won't send build-status events to Nullify — so the autofix loop won't see your Buildkite results, even though the connector shows **Active**.
{% endhint %}

## Step 5: Let Nullify's commits trigger builds <a href="#build-creator-access" id="build-creator-access"></a>

**Skip this step unless your Buildkite organization restricts who can trigger builds.** Some orgs gate builds by the creator's team — for example an agent `environment` hook or a pipeline conditional that checks [`BUILDKITE_BUILD_CREATOR_TEAMS`](https://buildkite.com/docs/pipelines/configure/environment-variables) (or `build.creator.teams`) and fails any build whose creator isn't on an allowed team. If your org runs every push regardless of who created it, jump to [Step 6](#step-6-verify).

When Nullify opens an autofix pull request, the commit is authored by Nullify's GitHub App, using the email `<id>+nullify[bot]@users.noreply.github.com`. Buildkite maps that commit author to a Buildkite user by email and fills `BUILDKITE_BUILD_CREATOR_TEAMS` from that user's teams. So in a gated org, Nullify's Buildkite user must exist in your org and sit on an allowed team — otherwise the build is blocked before it starts, no commit status is posted, and the autofix loop never sees your CI (even though the connector shows **Active**).

1. **Invite the Nullify user.** Invite `integrations-bot@nullify.ai` to your Buildkite organization. It is a Buildkite-managed service account, like Dependabot or Renovate: it auto-accepts the invite, skips billing, and cannot log in.
2. **Add it to an allowed, non-private team.** Put the user on the team(s) your build-creator gate accepts. The team must be **non-private** — `BUILDKITE_BUILD_CREATOR_TEAMS` only lists non-private team slugs, so membership of a private team won't satisfy the check.

{% hint style="info" %}
The gate matches on the commit's **author email**, which Buildkite treats as unverified — Nullify's commits do **not** need to be GPG-signed for this to work. (This is also why the account is associated with the `…+nullify[bot]@users.noreply.github.com` address rather than a regular mailbox.) This Buildkite user is **separate** from the API-token service account in Step 1: the token account authenticates Nullify's log reads; this user lets Nullify's commits run a build.
{% endhint %}

## Step 6: Verify <a href="#step-6-verify" id="step-6-verify"></a>

End-to-end, the simplest way to confirm everything works:

1. Push a commit to an open pull request so Buildkite runs a build.
2. Confirm the `buildkite/…` status appears on the GitHub PR (this proves Steps 3–4).
3. If a build fails on a Nullify autofix PR, watch Nullify pick up the failure and push a follow-up commit — that confirms log fetching and iteration are working.

## Troubleshooting

| Symptom                                                                      | Likely cause and fix                                                                                                                                                                 |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Autofix PR opened, but Buildkite never runs a build** on Nullify's commits | Your org gates build creators by team, and Nullify's Buildkite user isn't invited, isn't on an allowed team, or is on a **private** team. See [Step 5](#build-creator-access).       |
| Connector saved but autofix never reacts to Buildkite failures               | The GitHub permission acknowledgement (Step 4) is still pending, or commit statuses aren't being published (Step 3). Check both.                                                     |
| **No `buildkite/…` status on the GitHub PR**                                 | The Buildkite GitHub App isn't installed, or the pipeline doesn't have **Publish commit statuses** enabled. See Step 3.                                                              |
| **Setup rejects the token naming missing scopes**                            | Add the named scopes to the token in Buildkite (or mint a new one) and save again.                                                                                                   |
| Builds are detected but **logs aren't fetched**                              | The token is missing the `read_build_logs` scope, or it was created in the wrong organization. Re-check Step 1 and rotate the token if needed.                                       |
| **Status shows Active but nothing happens**                                  | The token and organization were verified when saved. Check the GitHub permission acknowledgement and commit-status publishing in Steps 3–4, then run the end-to-end check in Step 6. |
| Token was created by someone who has since left                              | The token stops working when their account is deactivated. Re-mint it from a dedicated service-account user (see the overview) and update it in Step 2.                              |

## Rotating the token

1. Create a new token in Buildkite (Step 1) — from the same service-account user.
2. In Nullify, open **Settings → Connectors → Buildkite**, enter the new token, and select **Save changes**.
3. Revoke the old token in Buildkite.

There's no downtime: Nullify uses the new token as soon as you save it.

## Removing the integration

1. Go to **Settings → Connectors → Buildkite**.
2. Click **Disconnect**.

This removes your stored token and organization slug from Nullify, stopping authenticated build-status reads and log retrieval through this connection. It does not delete your Buildkite pipelines.


# Jenkins

## Overview

The Jenkins connector gives Nullify eyes on your CI. When Nullify opens an autofix pull request, your Jenkins job runs against it like any other change — and if that build fails, Nullify reads the failure and fixes its own work before a human ever has to look. Once connected, Nullify can:

* **See your Jenkins builds** on the pull requests it opens, including pass/fail status.
* **Read the console output of a failed build** straight from the Jenkins API to understand *why* CI broke.
* **Iterate on the fix automatically**, feeding the real CI failure back to the autofix agent until the build is green.

The result is an autofix loop that's accountable to your actual pipeline — linting, tests, type checks, build steps and all — not just to Nullify's own checks. Teams that run Jenkins for CI alongside GitHub for source control get fixes that are already CI-clean by the time they land in review.

## How it works

Nullify never sits in the critical path of your pipeline and never changes how your builds run. It watches, reads, and iterates:

1. **Nullify pushes an autofix commit** to a pull request.
2. **Jenkins runs your job** against that commit, exactly as it would for any developer push.
3. **Jenkins reports the result to GitHub** as a commit status (this is Jenkins' standard GitHub integration — for example the GitHub Branch Source plugin, which posts a `continuous-integration/jenkins/…` status).
4. **Nullify detects the status** through its GitHub App — including when the build fails.
5. **Nullify fetches the failed build's console log** from the Jenkins API using your connected URL, username, and token. The build's console URL is taken from the status event and **pinned to your configured Jenkins host** before any request is made.
6. **The autofix agent iterates**, using the real failure output as context, and pushes a new commit — which kicks off the loop again until CI is green.

```
Autofix commit ─▶ Jenkins job runs ─▶ Build fails
                                          │
                  GitHub commit status ◀──┘
                           │
                  Nullify detects failure
                           │
               Fetches Jenkins console log ─▶ Agent iterates ─▶ new commit ↺
```

The integration is **read-only on your CI**: Nullify reads build status and console output. It does not trigger, cancel, or modify your jobs, and it does not write anything back to Jenkins.

{% hint style="info" %}
**How Nullify recognises a Jenkins build.** Nullify matches the GitHub commit-status context (`continuous-integration/jenkins…`) reported by your Jenkins GitHub integration. If your jobs publish statuses under a different context string, let your Nullify representative know so detection can be confirmed.
{% endhint %}

## Prerequisites

Before you start, make sure you have:

* A **Jenkins instance** reachable over HTTPS, running at least one job against your pull requests. The instance must be reachable from Nullify — Nullify rejects URLs that resolve to internal, loopback, or otherwise private addresses.
* Your Jenkins instance **posting commit statuses to GitHub** (for example via the GitHub Branch Source or GitHub plugin), so build results reach GitHub — and therefore Nullify.
* **GitHub already connected to Nullify.** Jenkins layers on top of the GitHub connection; it is not a standalone source-control integration.
* A **Jenkins user and API token** that can read the relevant jobs' console output. Nullify authenticates to the Jenkins API with HTTP basic auth using this username and token.

{% hint style="info" %}
**Use a dedicated service account for the API token, not a personal one.** Create a Jenkins user that exists only for Nullify, grant it read access to the relevant jobs, and mint the API token from that account (**Manage Jenkins → Users →&#x20;*****that user*****&#x20;→ Configure → API Token**). This keeps the integration alive when people change teams or leave, scopes Nullify's access to exactly what that user can see, and makes the token easy to audit and rotate.
{% endhint %}

## Configuration

Configure Jenkins through the Nullify dashboard (**Configure → Connectors → Jenkins**) or the admin API. The credentials you provide are stored encrypted; Nullify never returns the token back to you after it is saved.

### Connect via the admin API

Store the URL, username, and API token:

```http
POST /admin/integrations/jenkins/token
Content-Type: application/json

{
  "url": "https://jenkins.yourcompany.com",
  "username": "nullify-ci",
  "apiToken": "<jenkins-api-token>"
}
```

All three fields are required. The `url` must be a valid `http`/`https` URL and must not target an internal or loopback host.

Check whether a Jenkins integration is configured:

```http
GET /admin/integrations/jenkins
```

```json
{ "configured": true }
```

Remove the integration (deletes the stored URL, username, and token):

```http
DELETE /admin/integrations/jenkins
```

{% hint style="info" %}
Re-posting to `/admin/integrations/jenkins/token` overwrites the stored URL, username, and token in place — that's also how you **rotate** the API token. There's no downtime: Nullify uses the new credentials the next time it reads a build.
{% endhint %}

## What data flows

| Direction             | Data                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **GitHub → Nullify**  | Commit-status events for Jenkins builds on Nullify's pull requests (pass/fail and the build's target URL), via the Nullify GitHub App.                                   |
| **Jenkins → Nullify** | The plain-text console log of a **failed** build, fetched on demand from `…/consoleText` on your configured Jenkins host. Log reads are capped in size and time-bounded. |
| **Nullify → Jenkins** | Nothing. Nullify only issues authenticated read requests for console output; it never triggers, cancels, or configures jobs.                                             |

## Removing the integration

Delete the connector from **Configure → Connectors → Jenkins**, or call `DELETE /admin/integrations/jenkins`. This removes your stored URL, username, and token from Nullify. Your Jenkins jobs are untouched and keep running exactly as before — disconnecting only stops Nullify from reading build status and console output.

Jenkins connection availability is controlled per tenant. If its settings panel is absent, contact Nullify to confirm enablement before creating credentials. The build-log integration supplements an existing GitHub connection.


# CircleCI

Nullify can recognize CircleCI build statuses reported to GitHub on its fix pull requests. This relies on an existing GitHub connection and CircleCI publishing commit statuses with the build URL.

CircleCI is not currently enabled in the shared connector catalog, and the general autofix workflow has no CircleCI failed-build log fetcher. Do not assume storing a token enables the log-driven iteration available for [Buildkite](/connectors/buildkite) or [Jenkins](/connectors/jenkins). Confirm any tenant-specific rollout with Nullify before provisioning credentials.

## Existing credential configuration

The Admin API retains these operations for existing setups:

| Operation                                 | Effect                                       |
| ----------------------------------------- | -------------------------------------------- |
| `GET /admin/integrations/circleci`        | Reports whether a token has been configured. |
| `POST /admin/integrations/circleci/token` | Stores or replaces an `apiToken`.            |
| `DELETE /admin/integrations/circleci`     | Removes the stored token.                    |

A `configured: true` response confirms storage, not successful API access, build-log ingestion, or a working autofix feedback loop. The token is stored encrypted and is not returned by the status endpoint. If Nullify has enabled a supported use for your tenant, use a dedicated account and verify that workflow before revoking an old token during rotation.

Removing the token does not change your CircleCI pipelines or disconnect GitHub. GitHub can continue receiving and displaying CircleCI statuses independently of this stored credential.


# OIDC

## Overview

Nullify's OIDC connectors establish **keyless trust** between Nullify and your identity, version-control, and cloud providers. Instead of storing long-lived credentials, Nullify runs OpenID Connect (OIDC) issuers that mint or publish short-lived, signed tokens. The relying party (AWS Cognito for sign-in, or a cloud provider's federation service for infrastructure access) verifies those tokens against a public key, so the relying party can verify their issuer and scope. Cloud workload federation avoids exporting a long-lived cloud key; sign-in bridges still require their provider-side OAuth application configuration.

> Each connector is a small OpenID Connect provider. Some bridge a provider's OAuth2 endpoints into a standard OIDC flow used for single sign-on; one publishes only the public signing key used for cloud workload-identity federation.

## How OIDC trust works

There are two patterns across the connectors:

* **OAuth-to-OIDC sign-in bridges** (GitHub, Azure, Bitbucket, GitLab) — These bridges adapt provider sign-in and enrich its context for Nullify. The bridge wraps the OAuth2 flow, signing a standard ID token (RS256) so that AWS Cognito and similar relying parties can authenticate users and capture provider context (installations, workspaces, organizations, groups) during sign-in. Each exposes the standard endpoints `/.well-known/openid-configuration`, `/authorize`, `/token`, `/userinfo`, and `/jwks.json`. Azure is the exception: it captures only Entra sign-in identity here — Azure DevOps organization access is a separate, explicit consent (see [Azure](#azure) below).
* **Cloud workload-identity federation** (GCP and Azure cloud) — Nullify publishes only a discovery document and a JWKS endpoint. Your cloud project trusts the Nullify issuer, and a federation service exchanges a Nullify-signed token for a short-lived cloud credential scoped to your tenant — no service-account key is ever exported.

Nullify protects the private signing keys and publishes the public keys through each issuer's discovery document and JWKS endpoint.

## Supported providers

| Provider      | Issuer URL                        | Purpose                                                                                                                                                       |
| ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub**    | `https://github.nullify.ai`       | OAuth-to-OIDC bridge for sign-in; enriches claims with GitHub App installation and owner data.                                                                |
| **Azure**     | `https://entra.router.nullify.ai` | OAuth-to-OIDC bridge for Microsoft sign-in (Entra ID). Azure DevOps organization access is a separate consent, not captured here — see [Azure](#azure) below. |
| **GCP**       | `https://gcp.nullify.ai`          | Workload Identity Federation issuer; publishes the public key Google STS uses to verify Nullify-signed subject tokens.                                        |
| **GitLab**    | `https://gitlab.nullify.ai`       | OAuth-to-OIDC bridge for sign-in; enriches claims with GitLab group membership.                                                                               |
| **Bitbucket** | `https://bitbucket.nullify.ai`    | OAuth-to-OIDC bridge for sign-in; enriches claims with Bitbucket workspace and repository data.                                                               |

## Provider notes

### GitHub

GitHub exposes OAuth2 endpoints but has no native OpenID Connect support. The GitHub connector wraps GitHub OAuth2 as an OIDC provider for use with AWS Cognito. During sign-in, `/userinfo` fetches the user and their GitHub App installations concurrently and adds `github_install_ids`, `github_owner_ids`, and `github_owner_types` claims so Nullify knows which installations a user can access. GitHub Enterprise is supported by pointing the connector at a custom GitHub base URL.

### Azure

The Azure connector bridges Azure AD (Entra ID) OAuth2 into OIDC purely for **Microsoft sign-in**. It requests only OpenID Connect scopes (`openid profile email`) — never the Azure DevOps resource scope — so a customer who only wants Nullify as a Microsoft sign-in option never sees or grants Azure DevOps permissions. Connecting Azure DevOps organizations is a separate, explicit consent asked for by its own flow (**Connect Azure DevOps** in the dashboard), not by this sign-in bridge; see the [Azure DevOps connector](/connectors/azure) and its [install guide](/enterprise-tier/azure-install).

The official production **Nullify** application (`37d9fe25-ca83-49ac-a099-054de06b1aad`) handles Microsoft sign-in and Azure DevOps connect independently. Customer consent creates the same enterprise application in their directory for either flow. SSO-only setup requests `openid profile email`. Azure DevOps setup requests those identity scopes plus delegated Azure DevOps `user_impersonation` access. The **Also enable Microsoft sign-in** option configures workspace sign-in after the ADO administrator's identity is verified; it does not change the ADO setup scopes or automatically grant workspace membership.

{% hint style="info" %}
**Security review notes.** Entra consent and Azure DevOps permissions are separate parts of the connection:

* **Sign-in** — a tenant-wide delegated OIDC consent (`admin_consent=True`), which approves authentication scopes for the directory. A user still needs a linked or provisioned identity and an active role in Nullify.
* **Azure DevOps setup** — delegated `user_impersonation` consent lets the signed-in administrator perform setup through Nullify.
* **Ongoing Azure DevOps access** — the application's service principal needs organization membership, Basic access and scoped resource permissions in each connected organization. See the install guide's full permission table.

The Nullify directory binding and each Azure DevOps organization connection are managed separately. Removing or disabling the shared enterprise application in Entra affects the application itself and can stop **both** flows:

* To disconnect Nullify sign-in while retaining Azure DevOps, first disable Entra-only access with a verified Microsoft workspace administrator, then disconnect the directory in **Settings → Identity**. See [SSO setup and recovery](/configuration/account-and-teams/entra-sso-and-scim). Do not delete the shared enterprise application for an SSO-only disconnect.
* To revoke Azure DevOps access for one organisation, go to that organisation's **Organization settings → Users** and remove Nullify's service principal (see [Removing Nullify's access](/enterprise-tier/azure-install#removing-nullifys-access)).

For full offboarding, remove the Azure DevOps organization access and the enterprise application, and coordinate Nullify identity and credential removal.
{% endhint %}

### GCP

Unlike the OAuth bridges, the GCP issuer performs **no** OAuth flows (no `/authorize`, `/token`, or `/userinfo`) and signs no tokens itself. It is deployed once per environment as a shared multi-tenant platform service and publishes only the discovery document and the RSA **public** key. Your project creates a Workload Identity Pool that trusts `https://gcp.nullify.ai`, with an `attribute_condition` that pins access to your Nullify tenant id (`assertion.tenant_id == "<your tenant id>"`). A Nullify tenant lambda signs an OIDC token and passes it to Google STS, which fetches `https://gcp.nullify.ai/jwks.json` to verify the signature before returning a federated, tenant-scoped credential.

### GitLab

The GitLab connector wraps GitLab OAuth2 as an OIDC provider, enriching the signed claims with the user's GitLab group membership so Nullify can map the user to the right repositories during sign-in.

### Bitbucket

The Bitbucket connector wraps Bitbucket OAuth2 as an OIDC provider for use with AWS Cognito, enriching claims with the user's workspace IDs, names, and slugs, plus repository full names. Repository and workspace lookups are best-effort: failures are logged but do not block sign-in.

## Setup

Nullify configures the sign-in bridge. Sign in at [app.nullify.ai](https://app.nullify.ai/). A new Azure DevOps workspace uses the [setup invitation](/enterprise-tier/azure-install#set-up-a-new-workspace). **Request workspace** does not claim a workspace Nullify has already prepared. For an existing workspace, directory consent, member linking, and Microsoft-only sign-in are [Entra SSO and SCIM setup](/configuration/account-and-teams/entra-sso-and-scim). You do not create a customer SSO app registration or supply Nullify an app secret.

For GCP cloud federation, create a Workload Identity Pool that trusts the Nullify issuer using the tenant-specific attribute condition supplied by Nullify. For Azure cloud access, follow the separate [Azure cloud guide](/connectors/azure-cloud).

For related cloud-context setup, see the [AWS](/connectors/aws), [GCP](/connectors/gcp), and version-control connector guides.

## Azure workload federation

[Azure cloud](/connectors/azure-cloud) uses a federated credential on an Entra application, pinned to Nullify's issuer, audience, and tenant subject. It exchanges the signed workload assertion for Azure access without a stored client secret. This cloud-access flow is separate from Microsoft user sign-in and Azure DevOps consent. Use the issuer and tenant values displayed in your cloud settings; do not substitute a sign-in issuer merely because both use OIDC.


# Nullify API

Use the REST API to query findings, automate remediation, manage integrations, and report on your security program. Your tenant's base URL is `https://api.<TENANT>.nullify.ai`. Availability depends on your deployment, enabled capabilities, and access.

Start with [Authentication](/api-reference/api-reference/authentication), [Pagination](/api-reference/api-reference/pagination), and the [published OpenAPI specification](/api-reference/api-reference/openapi-spec). Send your bearer token and the provider or installation scope required by each operation.

For scans, use the [PR and default-branch coverage table](/api-reference/api-reference/orchestrator#scan-coverage-by-type) to select repository scanners and verify their results. [Scans with other targets](/api-reference/api-reference/orchestrator#scans-with-other-targets) cover application assessments, cloud accounts and individual package or container analysis.

| Area                             | Reference                                                                 | Typical workflow                                                                                      |
| -------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Account, teams, configuration    | [Admin](/api-reference/api-reference/api-admin)                           | Manage access, integrations, policies, and data requests.                                             |
| Code findings                    | [Code Review](/api-reference/api-reference/code-review)                   | Query findings, inspect triage, request fixes, and follow activity.                                   |
| Dependencies and containers      | [Dependency Analysis](/api-reference/api-reference/dependency-analysis)   | Query package/image risk, triage, tickets, and autofix.                                               |
| Credentials and sensitive data   | [Secrets Detection](/api-reference/api-reference/secrets-guardrails)      | Review the separate credential and sensitive-data inventories.                                        |
| Runtime assessments              | [Pentests](/api-reference/api-reference/pentester)                        | Configure targets and credentials, estimate, start, and inspect scans.                                |
| External attack surface          | [Bug Hunts](/api-reference/api-reference/bug-hunts)                       | Validate scope, import programs, run suites, and review findings.                                     |
| Supply-chain posture             | [SCPM](/api-reference/api-reference/scpm)                                 | Configure package policy and inspect posture or malware-analysis results.                             |
| Cloud configuration              | [Cloud Audits](/api-reference/api-reference/cloud-audits)                 | Start an audit and manage cloud findings.                                                             |
| Security program                 | [Manager](/api-reference/api-reference/manager)                           | Manage strategies, proposals, campaigns, action items, and chat.                                      |
| Asset and organizational context | [Context](/api-reference/api-reference/context)                           | Work with applications, inventory, schemas, SBOMs, memories, and reports.                             |
| AI usage                         | [Usage](/api-reference/api-reference/usage)                               | Read the usage ledger, aggregates, and time series.                                                   |
| Scans, reviews, remediation      | [Scans, Reviews & Remediation](/api-reference/api-reference/orchestrator) | Start repository scans and PR reviews, run batch autofix, retriage findings, and override check runs. |
| Finding feedback                 | [Finding Feedback](/api-reference/api-reference/finding-feedback)         | Record and read feedback on a finding, including the tokenized link flow.                             |

## Asynchronous operations

A successful start response means a job was accepted, not that analysis or remediation has finished. Retain its identifier and use the corresponding status, activity, or result operation. Do not assume every service implements the same suffixes or HTTP methods.

Finding allowlisting records an exception; it does not rotate a credential or fix the underlying vulnerability. Deleting a ticket, deleting a finding, archiving it, and resolving it are different operations. Follow the service-specific contract.


# Authentication

Authenticate API requests with a Nullify bearer token. Use a service account for automation, or [CLI login](/cli/cli/authentication) for an interactive session.

## Create a service account

In your tenant's settings, open **API access**, create an account, and copy its token to a secrets manager. The token is shown once. The [Admin API](/api-reference/api-reference/api-admin#service-accounts) also supports account creation.

Choose `builtin:admin`, `builtin:editor`, or `builtin:viewer` explicitly in the API. These are fixed built-in service-account roles; omitting the role in the creation API defaults to `builtin:admin`. Use a separate account for each automation.

```bash
curl --get 'https://api.<TENANT>.nullify.ai/sast/findings' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'limit=20'
```

Provider-scoped endpoints also require the installation or owner identifier described by that endpoint's schema. A bearer token does not make an arbitrary tenant or repository identifier accessible.

## Authorization and token lifetime

Missing or invalid authentication can return `401 Unauthorized`; insufficient access can return `403 Forbidden`. Role-permission enforcement is a tenant rollout setting and is **off by default**. Do not assume a viewer/editor token is a least-privilege boundary until Nullify has confirmed enforcement for your tenant. Tenant and provider access checks still apply independently.

That rollout caveat applies to ordinary SCM and service-account role enforcement. Managed SSO/Entra callers remain subject to resolved role permissions, and customer routes requiring identity administration—including directory and SCIM credential management, access activation and sign-in policy—remain permission-gated. Membership, lifecycle and network admission are separate checks. See [Microsoft Entra SSO and SCIM](/configuration/account-and-teams/entra-sso-and-scim) for setup and acceptance.

Team-scope enforcement still requires the workspace's role-enforcement rollout, including for Microsoft users. Entra authentication alone does not enable team restrictions.

{% hint style="warning" %}
Admin-created service-account tokens do not currently expire automatically. Deleting the service-account record does not invalidate its already-issued signed token. Do not use account deletion as an incident-response revocation mechanism. Contact Nullify to arrange revocation of an exposed token and confirm the affected access is disabled.
{% endhint %}

To rotate routinely, create a replacement account, update each consumer's stored token, and verify its requests. Coordinate invalidation of the old token with Nullify; creating a new account alone does not invalidate it. Interactive CLI credentials have a separate expiry and refresh flow.

## GitHub token exchange

The CLI can exchange a GitHub credential for a Nullify token when running in GitHub Actions; see [CI authentication](/cli/cli/authentication#using-a-github-token). The exchange checks the supplied GitHub credential against the owner you name. The credential must belong to that owner's user account or to an active member of that organization, or be an installation token for it, and the owner must have the Nullify GitHub app installed. The resulting token is valid for one hour and carries the built-in editor role.

### Exchange a GitHub token (POST)

New direct integrations should use `POST /auth/github_token` with `owner` (the GitHub user or organization login) and `token` (the GitHub credential) in the JSON body. A successful call returns `accessToken`, which you send as a bearer token on later API calls. It returns 400 when either field is missing or the credential does not verify for that owner. The endpoint needs no Nullify authentication, so never send GitHub credentials to an untrusted API host.

```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"owner": "<GITHUB_OWNER>", "token": "<GITHUB_TOKEN>"}' \
  'https://api.<TENANT>.nullify.ai/auth/github_token'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/auth/github\_token" method="POST" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Exchange a GitHub token (GET, deprecated)

The legacy `GET /auth/github_token?owner=...&token=...` does the same exchange but puts the GitHub credential in the query string, where proxies and access logs can capture it. It is retained for older clients only; use the POST form.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/auth/github\_token" method="GET" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Browser session endpoints

The remaining `/auth` operations support the Nullify web app's sign-in session. They use `HttpOnly` cookies (`access_token`, `refresh_token`) set on your tenant domain, not bearer tokens, and none of them needs an `Authorization` header. They are documented for completeness. Automation should use a [service account](#create-a-service-account) or the [GitHub token exchange](#github-token-exchange) instead.

### Exchange an authorization code

Browser sign-in uses `GET /auth/ui/login` and `GET /auth/ui/callback`. The backend stores state and the PKCE verifier in an HttpOnly transaction cookie, validates both on the callback, sets the session cookies, and redirects to the application. `GET /auth/whoami` returns the signed-in identity. Browser JavaScript never exchanges a code or receives the PKCE verifier.

[nullify-openapi-bundle.yaml](https://github.com/Nullify-Platform/nullify/tree/main/public-docs/.gitbook/assets/api/nullify-openapi-bundle.yaml)

### Refresh the access token

`GET /auth/refresh_token` exchanges the `refresh_token` cookie for a new `access_token` cookie and returns the same session summary as above. It takes no parameters and returns 401 when the cookie is missing, invalid or expired. The refresh cookie is left in place; how long it stays usable depends on your tenant's sign-in session settings, so be ready to sign in again when this call returns 401.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/auth/refresh\_token" method="GET" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Log out

`GET /auth/logout` clears the session cookies and returns 200 with no body. It does not revoke tokens already issued.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/auth/logout" method="GET" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Check the IP allowlist

`GET /auth/network/ip_allowed` reports the address Nullify sees for your request (`ip`) and whether it passes your tenant's IP allowlist (`allowed`). It is unauthenticated on purpose, so a caller blocked by the allowlist can still find out why: a blocked request to the rest of the API returns a bare 403. It reveals only whether your own address is allowed, never the list, and returns 503 if the allowlist cannot be evaluated. Call it on your tenant's API host (`api.<TENANT>.nullify.ai`).

```bash
curl -s 'https://api.<TENANT>.nullify.ai/auth/network/ip_allowed'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/auth/network/ip\_allowed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Platform callbacks (not for direct use)

The four Bitbucket lifecycle callbacks and the descriptor below are called by Atlassian when a workspace admin installs, enables, disables or removes the Nullify Bitbucket Connect app. They are not part of the integration surface for your own code: do not call them, and you do not need to. They exist in the API reference only because they are served on the public API host. They are available only on stacks with Bitbucket enabled. To connect Bitbucket, follow the [Bitbucket connector](/connectors/bitbucket) instructions.

### Bitbucket Connect descriptor

`GET /core/bitbucket/descriptor` returns the Connect app descriptor that Bitbucket reads when the app is installed: the app key, base URL, the lifecycle callback paths, the webhook events (`repo:push`, `pullrequest:created`, `pullrequest:updated`, `pullrequest:comment_created`), JWT authentication, and the scopes `account`, `repository` and `pullrequest`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/core/bitbucket/descriptor" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Bitbucket app installed

`POST /core/bitbucket/installed` is called by Bitbucket after the app is installed on a workspace. It records the installation (client key, shared secret and public key sent by Bitbucket) and publishes an install event.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/core/bitbucket/installed" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Bitbucket app enabled

`POST /core/bitbucket/enabled` is called when the app is re-enabled. It marks the installation as active again and publishes an unsuspend event. It returns 404 if the workspace has no recorded installation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/core/bitbucket/enabled" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Bitbucket app disabled

`POST /core/bitbucket/disabled` is called when the app is disabled. It marks the installation as suspended and publishes a suspend event. It returns 404 if the workspace has no recorded installation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/core/bitbucket/disabled" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Bitbucket app uninstalled

`POST /core/bitbucket/uninstalled` is called when the app is removed from a workspace. It marks the installation as suspended and publishes a delete event. It returns 404 if the workspace has no recorded installation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/core/bitbucket/uninstalled" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Retries

There is no published tenant-wide request quota or guaranteed `Retry-After` contract. Keep concurrency bounded, retry transient failures with exponential backoff and jitter, and honor `Retry-After` when returned. Do not automatically repeat a write that may already have succeeded: inspect the resulting resource or job before retrying.


# Pagination

List endpoints use several pagination contracts. Many finding lists accept `limit` and `nextToken`; other endpoints use `page`, `offset`, `cursor`, or `startKey`. Check the individual operation in the [OpenAPI specification](/api-reference/api-reference/openapi-spec).

## Following nextToken

1. Make the first request without `nextToken`.
2. Process the returned items and retain their stable IDs.
3. If `nextToken` is non-empty, pass it unchanged in the next request, with the same filters and ordering.
4. Stop when the token is empty or absent. A final request can return an empty page even when the previous page supplied a token.

Treat tokens as opaque and URL-encode them. Several Postgres-backed lists encode an **offset**, not a stable position in a snapshot; do not decode, construct, or reuse tokens across endpoints. Inserts, updates, or deletions while paging can produce skipped or repeated rows. Deduplicate by ID and reconcile later when exporting a changing collection.

Many finding endpoints cap `limit` at **100** and reject larger values. Defaults and caps vary by endpoint; a successful request with a smaller limit does not establish the maximum for another resource.

## Example: credential findings

Use `/secrets/credentials/findings` for credentials and `/secrets/sensitivedata/findings` for sensitive data. `/secrets/findings` is a legacy credential-findings alias, not a combined feed for both.

```bash
curl --get 'https://api.<TENANT>.nullify.ai/secrets/credentials/findings' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'limit=50'

# Copy nextToken from the response into NEXT_TOKEN, then request the next page.
curl --get 'https://api.<TENANT>.nullify.ai/secrets/credentials/findings' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'limit=50' \
  --data-urlencode "nextToken=$NEXT_TOKEN"
```

Keep the item-array field from the endpoint's response schema; not every list uses `findings`. See [Authentication](/api-reference/api-reference/authentication#retries) for retry guidance.


# Admin

General admin API endpoints for Nullify.

## Overview

The Admin API exposes tenant-wide inventory so you can keep internal systems aligned with Nullify’s view of repositories, services, and teams. It also exposes access management, configuration, ticketing, usage, and data-subject operations used by the dashboard and automation.

## Base URL

Use the tenant API URL supplied for your workspace, normally `https://api.<TENANT>.nullify.ai`. Include the appropriate authenticated bearer token; see [Authentication](/api-reference/api-reference/authentication). Do not assume every admin operation accepts a service account: identity linking, consent and Entra-only policy changes require an authorized human session and, for policy changes, a recent verified Microsoft sign-in. Use the dashboard's generated consent/link URLs rather than constructing shared-router callback URLs.

## Identity and provisioning

Follow [Entra setup and recovery](/configuration/account-and-teams/entra-sso-and-scim), [group-driven role mapping](/configuration/account-and-teams/entra-group-role-provisioning) and the [LIAM/Saviynt contract](/configuration/account-and-teams/saviynt-scim) for complete workflows. SCIM uses the tenant-specific base URL displayed in **Settings → Identity** and its own SCIM bearer credential, not a service-account token. Azure DevOps consent and organization setup are documented in the [Azure DevOps installation guide](/enterprise-tier/azure-install). The operations that manage these settings are in [Identity, Access and Service Accounts](/api-reference/api-reference/api-admin/identity-and-access).

## Common conventions

* Most operations are scoped to a provider organization with a query parameter such as `githubOwnerId`; each page notes where it is required.
* Pagination varies by operation: follow its documented cursor or offset; see [Pagination](/api-reference/api-reference/pagination).
* Requests are scoped to the tenant that issued your token.
* Write operations are authorized by role; see [Authentication](/api-reference/api-reference/authentication) for tokens and service accounts.

## Service Accounts

Service accounts issue the tokens that authenticate API automation (see [Authentication](/api-reference/api-reference/authentication)). List, create and delete them with `GET`, `POST` and `DELETE /admin/service_accounts`; see [Identity, Access and Service Accounts](/api-reference/api-reference/api-admin/identity-and-access#service-accounts).

## Data Subject Requests

`GET /admin/users/{userId}/export` and `DELETE /admin/users/{userId}/erasure` support data-subject access and erasure requests. Their scope and limits are described in [Users and Data Subject Requests](/api-reference/api-reference/api-admin/users).

## Guides in this section

* [Identity, Access and Service Accounts](/api-reference/api-reference/api-admin/identity-and-access): role assignments, Entra directory binding and sign-in policy, SCIM credentials, IP allowlist, privacy acknowledgment, service accounts.
* [Users and Data Subject Requests](/api-reference/api-reference/api-admin/users): users, identity mappings, activation, and GDPR export and erasure.
* [Teams and Ownership](/api-reference/api-reference/api-admin/teams): teams, team sync, code ownership, team findings and SLA breakdown.
* [Repositories, Pull Requests and Code](/api-reference/api-reference/api-admin/repositories-and-code): repository inventory and scan scope, pull request records, file contents and owners, context upload.
* [Findings, Events and Metrics](/api-reference/api-reference/api-admin/findings-and-metrics): cross-product finding queries, the events feed, scan coverage and metrics. AI usage metrics are on [AI Usage](/api-reference/api-reference/usage).
* [Source Control and CI Integrations](/api-reference/api-reference/api-admin/integrations-source-control-and-ci): Azure DevOps, GitHub, Buildkite, CircleCI and Jenkins.
* [Ticketing, Chat and Generic Integrations](/api-reference/api-reference/api-admin/integrations-ticketing-and-chat): Jira, Linear, Asana, Slack, Teams, notifications and the generic connection operations.
* [Cloud Integrations](/api-reference/api-reference/api-admin/integrations-cloud): AWS, Azure, GCP and Kubernetes settings.
* [Configuration and Policies](/api-reference/api-reference/api-admin/configuration): SLAs, PR gate, fix effort, routing exclusions, manager settings, UI preferences.
* [Ticketing Workbench](/api-reference/api-reference/api-admin/ticketing): ticket listing, bulk operations, saved filters and ticket settings.
* [AI Usage](/api-reference/api-reference/usage): usage ledger, aggregate and time series.

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                        | Operation                                                      |
| -------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/admin/access/me`                                          | Get Caller Access                                              |
| `GET`    | `/admin/access/preferences`                                 | Get RBAC Preferences                                           |
| `PUT`    | `/admin/access/preferences`                                 | Set RBAC Preferences                                           |
| `GET`    | `/admin/access/users`                                       | List User Roles                                                |
| `GET`    | `/admin/access/users/org-owners`                            | List Organization Owners                                       |
| `PUT`    | `/admin/access/users/roles`                                 | Set User Roles                                                 |
| `GET`    | `/admin/assessments/scan-coverage`                          | Get Scan Coverage                                              |
| `GET`    | `/admin/assessments/scan-coverage/findings`                 | Get Scan Coverage Findings                                     |
| `GET`    | `/admin/checklist`                                          | Get Checklist                                                  |
| `GET`    | `/admin/config/routing-exclusions`                          | Get Routing Exclusions                                         |
| `PUT`    | `/admin/config/routing-exclusions`                          | Set Routing Exclusions                                         |
| `GET`    | `/admin/config/security-owner`                              | Get Security Owner                                             |
| `PUT`    | `/admin/config/security-owner`                              | Set Security Owner                                             |
| `POST`   | `/admin/context/ingest`                                     | Get Context Upload Credentials                                 |
| `POST`   | `/admin/events`                                             | List Unified Events                                            |
| `GET`    | `/admin/external-writes`                                    | Read External Writes                                           |
| `PUT`    | `/admin/external-writes`                                    | Change External Writes                                         |
| `GET`    | `/admin/finding/{findingId}`                                | Get Finding                                                    |
| `POST`   | `/admin/findings`                                           | Query Findings                                                 |
| `POST`   | `/admin/findings/download`                                  | Download Findings                                              |
| `POST`   | `/admin/findings/groups`                                    | Group Findings                                                 |
| `POST`   | `/admin/findings/progress`                                  | Post Findings Progress                                         |
| `GET`    | `/admin/fix-effort`                                         | Get Fix Effort Mapping                                         |
| `PUT`    | `/admin/fix-effort`                                         | Put Fix Effort Mapping                                         |
| `GET`    | `/admin/getFileContents`                                    | Get File Contents                                              |
| `POST`   | `/admin/getFileOwners`                                      | Get File Owners                                                |
| `GET`    | `/admin/getPullRequest`                                     | Get PR State                                                   |
| `DELETE` | `/admin/identity/entra`                                     | Disconnect Microsoft Entra directory binding                   |
| `GET`    | `/admin/identity/entra`                                     | Get Microsoft Entra directory binding status                   |
| `POST`   | `/admin/identity/entra/connect`                             | Start Microsoft Entra connect                                  |
| `GET`    | `/admin/identity/entra/handoff`                             | List Microsoft Entra consent links                             |
| `POST`   | `/admin/identity/entra/handoff`                             | Delegate Microsoft Entra directory consent                     |
| `DELETE` | `/admin/identity/entra/handoff/{id}`                        | Revoke a Microsoft Entra consent link                          |
| `POST`   | `/admin/identity/entra/link`                                | Start Microsoft Entra self-service account link                |
| `GET`    | `/admin/identity/entra/policy`                              | Get Microsoft Entra sign-in policy                             |
| `PUT`    | `/admin/identity/entra/policy`                              | Check or update Microsoft Entra sign-in policy                 |
| `POST`   | `/admin/identity/entra/sign-in`                             | Record a Microsoft sign-in                                     |
| `GET`    | `/admin/identity/scim`                                      | Get SCIM Identity Settings                                     |
| `POST`   | `/admin/identity/scim/credentials`                          | Create SCIM Credential                                         |
| `DELETE` | `/admin/identity/scim/credentials/{id}`                     | Revoke SCIM Credential                                         |
| `GET`    | `/admin/installations`                                      | Get App Installations                                          |
| `GET`    | `/admin/integrations/asana/oauth`                           | Get Asana install status                                       |
| `POST`   | `/admin/integrations/asana/ticket-config`                   | Set Asana Ticket Configuration                                 |
| `GET`    | `/admin/integrations/atlassian`                             | Get Atlassian integration                                      |
| `POST`   | `/admin/integrations/atlassian`                             | Update Atlassian integration choices                           |
| `GET`    | `/admin/integrations/azure`                                 | Get Azure Configuration                                        |
| `POST`   | `/admin/integrations/azure`                                 | Repair Azure DevOps Service Hooks                              |
| `POST`   | `/admin/integrations/azure/codeowners/preview`              | Preview CODEOWNERS as Azure DevOps required-reviewer policies  |
| `DELETE` | `/admin/integrations/azure/connect`                         | Disconnect an Azure DevOps organization                        |
| `POST`   | `/admin/integrations/azure/connect`                         | Start Azure DevOps connect                                     |
| `GET`    | `/admin/integrations/azure/connect/{handle}`                | Get Azure DevOps connect status                                |
| `POST`   | `/admin/integrations/azure/connect/{handle}/confirm`        | Confirm Azure DevOps connect                                   |
| `POST`   | `/admin/integrations/azure/connect/{handle}/recheck`        | Recheck Azure DevOps permissions                               |
| `POST`   | `/admin/integrations/azure/connect/{handle}/retry`          | Retry Azure DevOps connect                                     |
| `POST`   | `/admin/integrations/azure/credentials`                     | Set Azure Credentials                                          |
| `DELETE` | `/admin/integrations/azure/installations`                   | Delete Azure DevOps webhook installation                       |
| `GET`    | `/admin/integrations/azure/installations`                   | List Azure DevOps webhook installations                        |
| `POST`   | `/admin/integrations/azure/installations`                   | Register Azure DevOps webhook installation                     |
| `POST`   | `/admin/integrations/azure/installations/suspend`           | Suspend or resume an Azure DevOps organization's installations |
| `POST`   | `/admin/integrations/azure/installations/test`              | Test an Azure DevOps organization's provisioning state         |
| `DELETE` | `/admin/integrations/buildkite`                             | Delete Buildkite Integration                                   |
| `GET`    | `/admin/integrations/buildkite`                             | Get Buildkite Integration Status                               |
| `POST`   | `/admin/integrations/buildkite/organizations`               | List Buildkite Organizations For Token                         |
| `POST`   | `/admin/integrations/buildkite/token`                       | Set Buildkite API Token                                        |
| `GET`    | `/admin/integrations/catalog`                               | Get Integrations Catalog                                       |
| `DELETE` | `/admin/integrations/circleci`                              | Delete CircleCI Integration                                    |
| `GET`    | `/admin/integrations/circleci`                              | Get CircleCI Integration Status                                |
| `POST`   | `/admin/integrations/circleci/token`                        | Set CircleCI API Token                                         |
| `DELETE` | `/admin/integrations/cloud/aws/settings`                    | Delete Cloud AWS Settings                                      |
| `GET`    | `/admin/integrations/cloud/aws/settings`                    | Get Cloud AWS Settings                                         |
| `POST`   | `/admin/integrations/cloud/aws/settings`                    | Upsert Cloud AWS Settings                                      |
| `POST`   | `/admin/integrations/cloud/aws/validate-role`               | Validate AWS Role                                              |
| `DELETE` | `/admin/integrations/cloud/azure/settings`                  | Delete Cloud Azure Settings                                    |
| `GET`    | `/admin/integrations/cloud/azure/settings`                  | Get Cloud Azure Settings                                       |
| `POST`   | `/admin/integrations/cloud/azure/settings`                  | Upsert Cloud Azure Settings                                    |
| `POST`   | `/admin/integrations/cloud/azure/validate`                  | Validate Azure Credentials                                     |
| `POST`   | `/admin/integrations/cloud/gcp/access-token`                | Mint GCP Access Token                                          |
| `DELETE` | `/admin/integrations/cloud/gcp/settings`                    | Delete Cloud GCP Settings                                      |
| `GET`    | `/admin/integrations/cloud/gcp/settings`                    | Get Cloud GCP Settings                                         |
| `POST`   | `/admin/integrations/cloud/gcp/settings`                    | Upsert Cloud GCP Settings                                      |
| `GET`    | `/admin/integrations/cloud/gcp/setup`                       | Get Cloud GCP Setup                                            |
| `POST`   | `/admin/integrations/cloud/gcp/validate`                    | Validate GCP Credentials                                       |
| `POST`   | `/admin/integrations/cloud/k8s/clusters`                    | Add or Update a K8s Cluster                                    |
| `DELETE` | `/admin/integrations/cloud/k8s/clusters/{clusterId}`        | Remove a K8s Cluster                                           |
| `DELETE` | `/admin/integrations/cloud/k8s/settings`                    | Delete Cloud K8s Settings                                      |
| `GET`    | `/admin/integrations/cloud/k8s/settings`                    | Get Cloud K8s Settings                                         |
| `POST`   | `/admin/integrations/cloud/k8s/settings`                    | Upsert Cloud K8s Settings                                      |
| `GET`    | `/admin/integrations/cloud/k8s/whitelist`                   | Read collector account access                                  |
| `POST`   | `/admin/integrations/cloud/k8s/whitelist`                   | Whitelist K8s Connector Accounts                               |
| `GET`    | `/admin/integrations/connections`                           | List Integration Connections                                   |
| `DELETE` | `/admin/integrations/connections/{connectionId}`            | Disconnect Integration Connection                              |
| `PUT`    | `/admin/integrations/connections/{connectionId}/rotate`     | Rotate Integration Connection                                  |
| `POST`   | `/admin/integrations/connections/{connectionId}/test`       | Test Integration Connection                                    |
| `POST`   | `/admin/integrations/github-packages/discover`              | Discover GitHub Packages Identity                              |
| `GET`    | `/admin/integrations/github/app-settings`                   | Get GitHub App Settings                                        |
| `POST`   | `/admin/integrations/gitlab/connect`                        | Connect GitLab                                                 |
| `POST`   | `/admin/integrations/gitlab/connect/confirm`                | Finish GitLab connection                                       |
| `GET`    | `/admin/integrations/gitlab/connect/status`                 | GitLab connection status                                       |
| `DELETE` | `/admin/integrations/jenkins`                               | Delete Jenkins Integration                                     |
| `GET`    | `/admin/integrations/jenkins`                               | Get Jenkins Integration Status                                 |
| `POST`   | `/admin/integrations/jenkins/token`                         | Set Jenkins API Token                                          |
| `GET`    | `/admin/integrations/jira`                                  | Get Jira Configuration                                         |
| `POST`   | `/admin/integrations/jira`                                  | Update Jira Configuration                                      |
| `GET`    | `/admin/integrations/jira/forge`                            | Get Jira Forge connection status                               |
| `GET`    | `/admin/integrations/jira/install`                          | Start Jira Forge OAuth connect                                 |
| `GET`    | `/admin/integrations/linear`                                | Get Linear Configuration                                       |
| `GET`    | `/admin/integrations/linear/install`                        | Start Linear OAuth install                                     |
| `GET`    | `/admin/integrations/linear/members`                        | List Linear Team Members                                       |
| `GET`    | `/admin/integrations/linear/oauth`                          | Get Linear OAuth install status                                |
| `GET`    | `/admin/integrations/linear/teams`                          | List Linear Teams                                              |
| `POST`   | `/admin/integrations/linear/ticket-config`                  | Set Linear Ticket Configuration                                |
| `GET`    | `/admin/integrations/notifications`                         | Get Notification Config                                        |
| `PUT`    | `/admin/integrations/notifications`                         | Put Notification Config                                        |
| `GET`    | `/admin/integrations/slack`                                 | Get Slack Configuration                                        |
| `GET`    | `/admin/integrations/slack/install`                         | Start Slack distributed install                                |
| `POST`   | `/admin/integrations/slack/key`                             | Set Slack API Key                                              |
| `GET`    | `/admin/integrations/teams`                                 | Get Integration Teams                                          |
| `GET`    | `/admin/integrations/threat-intel/destinations`             | Get Threat Investigation Destinations                          |
| `PUT`    | `/admin/integrations/threat-intel/destinations`             | Update Threat Investigation Destinations                       |
| `GET`    | `/admin/integrations/users`                                 | Get Integration Users                                          |
| `PUT`    | `/admin/integrations/{providerId}/{capability}/configure`   | Configure Integration                                          |
| `POST`   | `/admin/integrations/{providerId}/{capability}/connect`     | Connect Integration                                            |
| `POST`   | `/admin/integrations/{providerId}/{capability}/connections` | Create Integration Connection                                  |
| `DELETE` | `/admin/integrations/{providerId}/{capability}/disconnect`  | Disconnect Integration                                         |
| `GET`    | `/admin/integrations/{providerId}/{capability}/install`     | Start Integration OAuth install                                |
| `POST`   | `/admin/integrations/{providerId}/{capability}/test`        | Test Integration                                               |
| `GET`    | `/admin/manager/settings`                                   | Get Manager Settings                                           |
| `PUT`    | `/admin/manager/settings`                                   | Update Manager Settings                                        |
| `POST`   | `/admin/metrics/findings`                                   | Post Findings Metrics                                          |
| `POST`   | `/admin/metrics/findings/by-repository`                     | Post Findings Metrics By Repository                            |
| `POST`   | `/admin/metrics/findings/frameworks`                        | Post Findings Compliance Frameworks                            |
| `GET`    | `/admin/metrics/interactions`                               | Get Interactions                                               |
| `POST`   | `/admin/metrics/over-time`                                  | Get Metrics Over Time                                          |
| `POST`   | `/admin/metrics/overview`                                   | Query Overview                                                 |
| `POST`   | `/admin/metrics/pullrequests`                               | Post Pull Request Metrics                                      |
| `POST`   | `/admin/metrics/raw`                                        | Query Raw Metrics                                              |
| `POST`   | `/admin/metrics/tickets`                                    | Post Ticket Metrics                                            |
| `GET`    | `/admin/metrics/usage/aggregate`                            | Usage Aggregate                                                |
| `GET`    | `/admin/metrics/usage/ledger`                               | Usage Ledger                                                   |
| `GET`    | `/admin/metrics/usage/timeseries`                           | Usage Timeseries                                               |
| `GET`    | `/admin/network/ip-allowlist`                               | Get IP Allowlist                                               |
| `PUT`    | `/admin/network/ip-allowlist`                               | Replace IP Allowlist                                           |
| `POST`   | `/admin/network/ip-allowlist/preview`                       | Preview IP Allowlist                                           |
| `POST`   | `/admin/operator/external-writes/initialize`                | Initialize External Write Defaults                             |
| `POST`   | `/admin/operator/github-tenant/route`                       | Preview, write or inspect a GitHub tenant route born paused    |
| `POST`   | `/admin/operator/native-tenant/route`                       | Preview or write a native Azure workspace route                |
| `GET`    | `/admin/operator/package-feeds`                             | Read Staff Package Feeds                                       |
| `POST`   | `/admin/operator/package-feeds`                             | Control Staff Package Feed                                     |
| `GET`    | `/admin/operator/scan-entitlement`                          | Read Staff Scan Entitlement                                    |
| `PUT`    | `/admin/operator/scan-entitlement`                          | Replace Staff Scan Entitlement                                 |
| `GET`    | `/admin/operator/scan-scope/repositories`                   | Read Staff Repository Scan Scopes                              |
| `PUT`    | `/admin/operator/scan-scope/repositories`                   | Set Staff Repository Scan Limits                               |
| `GET`    | `/admin/operator/tenant-capabilities`                       | Read Staff Tenant Capabilities                                 |
| `PUT`    | `/admin/operator/tenant-capabilities`                       | Force Tenant Capability                                        |
| `POST`   | `/admin/operator/workspace-bootstrap/approve`               | Approve an exact provisioning request                          |
| `POST`   | `/admin/operator/workspace-bootstrap/invitation`            | Preview or issue a workspace bootstrap invitation              |
| `GET`    | `/admin/operator/workspace-bootstrap/operation`             | Inspect a durable workspace claim                              |
| `POST`   | `/admin/operator/workspace-bootstrap/renew`                 | Preview or renew an organization-pinned workspace invitation   |
| `GET`    | `/admin/operator/workspace-bootstrap/requests`              | List provisioning requests                                     |
| `POST`   | `/admin/operator/workspace-bootstrap/revoke`                | Preview or revoke a workspace claim without stage receipts     |
| `GET`    | `/admin/organization`                                       | Get Organization                                               |
| `GET`    | `/admin/pr-gate-settings`                                   | Get PR Gate Settings                                           |
| `PUT`    | `/admin/pr-gate-settings`                                   | Put PR Gate Settings                                           |
| `GET`    | `/admin/privacy/acknowledgment`                             | Get Privacy Acknowledgment                                     |
| `POST`   | `/admin/privacy/acknowledgment`                             | Post Privacy Acknowledgment                                    |
| `GET`    | `/admin/pullrequests`                                       | Get Pull Request Record                                        |
| `POST`   | `/admin/pullrequests`                                       | Query Pull Requests                                            |
| `POST`   | `/admin/pullrequests/refresh-ci`                            | Refresh Pull Request CI                                        |
| `GET`    | `/admin/repositories`                                       | Get Repositories                                               |
| `GET`    | `/admin/repositories/recommendations`                       | Get Repository PoV Recommendations                             |
| `PUT`    | `/admin/repositories/scan-scope`                            | Update Repository Scan Scopes                                  |
| `GET`    | `/admin/repositories/{repositoryId}/directories`            | List Repository Directories                                    |
| `DELETE` | `/admin/repository-property-team-keys`                      | Delete Repository Property Team Key                            |
| `GET`    | `/admin/repository-property-team-keys`                      | List Repository Property Team Keys                             |
| `POST`   | `/admin/repository-property-team-keys`                      | Create Repository Property Team Key                            |
| `GET`    | `/admin/runs/{kind}/{id}`                                   | Get Run Snapshot                                               |
| `GET`    | `/admin/scan-scope`                                         | Get Scan Scope                                                 |
| `PUT`    | `/admin/scan-scope`                                         | Update Scan Scope Settings                                     |
| `GET`    | `/admin/scans/orchestrator`                                 | List Orchestrator Scans                                        |
| `DELETE` | `/admin/service_accounts`                                   | Delete Service Account                                         |
| `GET`    | `/admin/service_accounts`                                   | Get Service Accounts                                           |
| `POST`   | `/admin/service_accounts`                                   | Create Service Account                                         |
| `GET`    | `/admin/settings/cspm-scan-cadence`                         | Get CSPM Scan Cadence                                          |
| `PUT`    | `/admin/settings/cspm-scan-cadence`                         | Set CSPM Scan Cadence                                          |
| `GET`    | `/admin/settings/inference-region`                          | Get Inference Region                                           |
| `PUT`    | `/admin/settings/inference-region`                          | Set Inference Region                                           |
| `GET`    | `/admin/sla`                                                | Get SLAs                                                       |
| `POST`   | `/admin/sla`                                                | Post SLA                                                       |
| `PUT`    | `/admin/sla/bulk`                                           | Put Bulk SLA                                                   |
| `PATCH`  | `/admin/sla/{slaId}`                                        | Patch SLA                                                      |
| `DELETE` | `/admin/support-access`                                     | Revoke Support Access                                          |
| `GET`    | `/admin/support-access`                                     | Get Support Access                                             |
| `POST`   | `/admin/support-access`                                     | Elevate Support Access                                         |
| `GET`    | `/admin/team-source-preferences`                            | Get Team Source Preferences                                    |
| `PUT`    | `/admin/team-source-preferences`                            | Update Team Source Preferences                                 |
| `GET`    | `/admin/team-sync-runs`                                     | List Team Sync Runs                                            |
| `POST`   | `/admin/team-sync-runs`                                     | Trigger Team Sync                                              |
| `GET`    | `/admin/team/{teamID}`                                      | Get Team                                                       |
| `GET`    | `/admin/teams`                                              | Get All Teams                                                  |
| `POST`   | `/admin/teams`                                              | Post Team                                                      |
| `GET`    | `/admin/teams/appzip`                                       | Get Teams App Zip                                              |
| `POST`   | `/admin/teams/compass`                                      | Post Compass/Atlassian Team                                    |
| `GET`    | `/admin/teams/findings`                                     | Get All Team Findings mapping                                  |
| `POST`   | `/admin/teams/findings`                                     | Manual Team Findings Assignment                                |
| `POST`   | `/admin/teams/findings/sync`                                | Sync Team Findings                                             |
| `POST`   | `/admin/teams/merge`                                        | Merge Teams                                                    |
| `POST`   | `/admin/teams/sla-breakdown`                                | Get Team SLA Breakdown                                         |
| `DELETE` | `/admin/teams/{teamID}`                                     | Delete Manual Team                                             |
| `PATCH`  | `/admin/teams/{teamID}`                                     | Patch Team                                                     |
| `POST`   | `/admin/teams/{teamID}/code-ownership`                      | Make Team The Owner Of A Repository                            |
| `POST`   | `/admin/teams/{teamID}/events`                              | List Team Unified Events                                       |
| `GET`    | `/admin/teams/{teamID}/findings`                            | Get Team Findings mapping                                      |
| `GET`    | `/admin/tenant-capabilities`                                | List Tenant Capabilities                                       |
| `PUT`    | `/admin/tenant-capabilities/{capability}`                   | Set Tenant Capability                                          |
| `GET`    | `/admin/ticketing/activity`                                 | List Ticketing Activity                                        |
| `GET`    | `/admin/ticketing/bulk-operations/{operationId}`            | Get Bulk Operation Status                                      |
| `POST`   | `/admin/ticketing/bulk-operations/{operationId}/cancel`     | Request Bulk Operation Cancellation                            |
| `GET`    | `/admin/ticketing/saved-filters`                            | List Saved Ticket Filters                                      |
| `POST`   | `/admin/ticketing/saved-filters`                            | Create Saved Ticket Filter                                     |
| `DELETE` | `/admin/ticketing/saved-filters/{id}`                       | Delete Saved Ticket Filter                                     |
| `PATCH`  | `/admin/ticketing/saved-filters/{id}`                       | Update Saved Ticket Filter                                     |
| `POST`   | `/admin/ticketing/settings/{findingType}`                   | Save Ticket Settings                                           |
| `GET`    | `/admin/ticketing/settings/{findingType}/history`           | List Ticket Settings History                                   |
| `POST`   | `/admin/ticketing/settings/{findingType}/preview`           | Preview Ticket Settings Impact                                 |
| `GET`    | `/admin/ticketing/tickets`                                  | List Tickets (Power-User Workbench)                            |
| `POST`   | `/admin/ticketing/tickets/bulk-add-comment`                 | Bulk Add Comment To Tickets                                    |
| `POST`   | `/admin/ticketing/tickets/bulk-close`                       | Bulk Close Tickets                                             |
| `POST`   | `/admin/ticketing/tickets/bulk-move`                        | Bulk Move Tickets                                              |
| `POST`   | `/admin/ticketing/tickets/bulk-reassign-assignee`           | Bulk Reassign Ticket Assignee                                  |
| `POST`   | `/admin/ticketing/tickets/bulk-reassign-team`               | Bulk Reassign Tickets to Team                                  |
| `POST`   | `/admin/ticketing/tickets/bulk-relabel`                     | Bulk Relabel Tickets                                           |
| `POST`   | `/admin/ticketing/tickets/bulk-reopen`                      | Bulk Reopen Tickets                                            |
| `POST`   | `/admin/ticketing/tickets/bulk-resync`                      | Bulk Re-Sync Tickets                                           |
| `POST`   | `/admin/ticketing/tickets/bulk-set-priority`                | Bulk Set Ticket Priority                                       |
| `GET`    | `/admin/ticketing/tickets/counts`                           | Get Ticket Facet Counts                                        |
| `GET`    | `/admin/ticketing/tickets/{ticketId}`                       | Get Ticket Drill-Down                                          |
| `POST`   | `/admin/triage/context-census`                              | Post Triage Context Census                                     |
| `DELETE` | `/admin/ui/preferences`                                     | Delete UI Preferences                                          |
| `GET`    | `/admin/ui/preferences`                                     | Get UI Preferences                                             |
| `PUT`    | `/admin/ui/preferences`                                     | Put UI Preferences                                             |
| `GET`    | `/admin/ui/savedViews`                                      | Get UI Saved Views                                             |
| `POST`   | `/admin/ui/savedViews`                                      | Post UI Saved View                                             |
| `DELETE` | `/admin/ui/savedViews/{savedViewId}`                        | Delete UI Saved View                                           |
| `PATCH`  | `/admin/ui/savedViews/{savedViewId}`                        | Patch UI Saved View                                            |
| `GET`    | `/admin/user/current`                                       | Get Current User                                               |
| `GET`    | `/admin/user/mapping`                                       | Get User Mapping                                               |
| `POST`   | `/admin/user/mapping`                                       | Post Add User Mappings                                         |
| `GET`    | `/admin/user/mapping/suggestions`                           | Get User Mapping Suggestions                                   |
| `DELETE` | `/admin/user/mapping/{userId}`                              | Delete User Mapping                                            |
| `PUT`    | `/admin/user/mapping/{userId}`                              | Edit User Mapping                                              |
| `GET`    | `/admin/user/mappings`                                      | Get User Mappings                                              |
| `GET`    | `/admin/user/{userID}`                                      | Get User                                                       |
| `GET`    | `/admin/users`                                              | Get All Users                                                  |
| `POST`   | `/admin/users`                                              | Post User                                                      |
| `POST`   | `/admin/users/activate`                                     | Activate Users                                                 |
| `POST`   | `/admin/users/bulkSearchMappings`                           | Post Bulk Get User Mappings                                    |
| `POST`   | `/admin/users/deactivate`                                   | Deactivate User                                                |
| `GET`    | `/admin/users/identity/{providerID}/{providerUserID}`       | Get User By Git Identity                                       |
| `POST`   | `/admin/users/reactivate`                                   | Reactivate User                                                |
| `GET`    | `/admin/users/{providerID}`                                 | Get Provider Users                                             |
| `GET`    | `/admin/users/{providerID}/{userID}`                        | Get User By Provider                                           |
| `DELETE` | `/admin/users/{userId}/erasure`                             | Delete User Erasure (GDPR Art. 17)                             |
| `GET`    | `/admin/users/{userId}/export`                              | Get User Data Export (GDPR Art. 15, 20)                        |


# Configuration and Policies

These endpoints read and change tenant-wide settings: who security work is routed to, how long findings may stay open (SLAs), the pull request gate, the manager agent's guardrails, CSPM scan cadence and fix-effort weights. A last group stores the calling user's UI preferences and saved views. Authenticate as described in [Authentication](/api-reference/api-reference/authentication); people and roles are covered in [Users](/api-reference/api-reference/api-admin/users) and teams in [Teams](/api-reference/api-reference/api-admin/teams).

Unless a section says otherwise, every call is scoped to a workspace with a provider query parameter such as `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`, and the call returns 400 when none resolves to a tenant. Read calls need the `ConfigRead` permission and write calls need `ConfigWrite`, except where noted. These settings are replaced or merged as documented per call; none of them starts a scan or job by itself.

## Security owner and routing

The security owner is the person or team lead Nullify falls back to when it needs someone to hand security work to. The routing exclusion list names people Nullify must never pick as a fix-PR reviewer, direct-message recipient or default ticket assignee.

### Get the security owner

Returns the confirmed selection as `teamId` and `userId` (one of them, or both empty when nothing is set), `resolvedUserId` (the active person the selection resolves to today, which follows the team lead when a team is selected) and `suggestions`, contacts Nullify has observed in saved Slack conversations with their `interactionCount`. Suggestions never change the selection. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/config/security-owner" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the security owner

Selects either a team (`teamId`, which follows its current lead) or a person (`userId`). Send both empty to clear the selection. Sending both returns 400, as does an id that is not a team or non-bot person in your tenant, or a selection that resolves to someone on the routing exclusion list. The response is the new state, in the same shape as the read call. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/config/security-owner" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get routing exclusions

Returns the people Nullify must not route to, each expanded to the identities it matches on (`currentLogin`, `userId`, `providerUserId`, `gitUserRefs`, `slackId`, `teamsId`, `linearId`, `jiraId`), plus the security-owner `fallback` that replaces them and whether it is `eligible`. `unresolved` lists the identity kinds that could not be resolved for a person (`account`, `gitAccountId`, `messaging`), each a way the exclusion can be bypassed. `source` is `curated` for entries added through this API; `service_account` entries are computed from a service-account classification, and `nullify_staff` entries are Nullify employees in your GitHub org or with a provider-verified native identity in your tenant, staff identified by their Nullify email in your live Slack or Teams directory, and operator-granted accounts, added only where Nullify has turned staff exclusion on for your tenant; both are read-only. Caller-created accounts and identity mappings do not establish membership. Identity mappings only enrich otherwise eligible Git accounts; messaging-only staff do not expose mapped Git identities. Curated entries retain their saved login and inherit computed identities for the same person. Nullify employees stay visible in your user list so you can review and revoke their access. Unlike most reads, this one requires `ConfigWrite`, so a viewer who holds only `ConfigRead` cannot see who is on the list.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/config/routing-exclusions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set routing exclusions

Replaces the whole list. Each entry needs a `providerId` (a git provider: GitHub, GitLab, Azure DevOps or Bitbucket) and a `login`; send an empty `users` array to clear it. The list holds at most 50 curated people, and duplicates are collapsed. Entries returned by the read call with a computed `source` are dropped rather than saved and do not count toward the limit. The call returns 400 for an invalid entry, for more than 50 people, or when the list would exclude the current security owner. The response is the stored list in the read call's shape. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/config/routing-exclusions" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Service level agreements (SLAs)

An SLA sets the maximum days allowed to fix a finding of a given severity or priority, and whether extensions are allowed. Valid severities are `CRITICAL`, `HIGH`, `MEDIUM` and `LOW`; valid priorities are `URGENT`, `IMPORTANT`, `MEDIUM` and `LOW`. Create upper-cases and validates these values, so lowercase is accepted there; the update and bulk-save calls do not validate them, so send the uppercase enumerations. Changes are recorded in the tenant audit log.

### List SLAs

Returns every SLA configured for the tenant in `slas`, or an empty array when none exist. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/sla" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create an SLA

Creates one SLA. `maxDaysToFix` must be greater than 0 and at least one of `severity` or `priority` must be set. The schema marks both as required, but either one on its own is accepted. If an SLA already exists for the same severity the call fails and nothing is changed; use the update or bulk-save call to change it. Returns the stored SLA, including its generated `id`. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/sla" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save several SLAs

Upserts a list of SLAs in one call, which is the usual way to set a whole policy. Each entry is matched to an existing SLA by `severity`, so saving a severity that already has an SLA updates it and keeps its original id; an entry with no `id` gets a new one. An empty `slas` list is rejected. Entries are written one by one, so a failure part way can leave earlier entries saved. Returns the ids you submitted (or generated) as `slaIds`; for a severity that already had an SLA these are not necessarily the stored ids, so list the SLAs to read them. Requires `ConfigWrite`.

```bash
curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"slas":[{"severity":"CRITICAL","priority":"URGENT","maxDaysToFix":7,"allowExtensions":false}]}' \
  'https://api.<TENANT>.nullify.ai/admin/sla/bulk?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/sla/bulk" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update an SLA

Changes one SLA by `slaId`, taken from the list call. Only the fields you send (`severity`, `priority`, `maxDaysToFix`, `allowExtensions`) change; the rest keep their stored values. Returns 404 when the id does not exist in your tenant. Unlike create, this call does not re-validate the values you send. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/sla/{slaId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Fix effort

### Get the fix effort mapping

Returns the story-point weights for easy, medium and hard fixes as `fixEffort.easy`, `medium` and `hard`. A tenant that has never saved a mapping gets the defaults 1, 3 and 8 with an empty `id`. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/fix-effort" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the fix effort mapping

Saves the weights. Send the `id` from the read call to replace the stored mapping, or an empty `id` to create it. Replacing sends the whole object, so include all three values. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/fix-effort" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Pull request gate

The PR gate decides when the Nullify pull request check fails and whether Nullify reviews pull requests. A tenant that has never configured it gets an information-only check that always passes, with PR reviews on. See [Configuration – Pull Requests](/configuration/configuration-pull-requests) for each control.

### Get PR gate settings

Returns the findings controls `findingsPolicy` (`none` or `confirmed`) and `cvssEnforcement`, and the independent scan-failure control `failOnIncompleteCoverage`; `minPriority` (`URGENT` or `IMPORTANT`); `prReviewsEnabled` and the review options `allowApprovingReviews` and `allowRequestChangesReviews` (both off by default, so a clean PR gets no approval and concerns are not merge-blocking); an optional `scaBlockCvssThreshold` that overrides the default 9.0 CVSS cutoff `cvssEnforcement` fails a pull request on without AI confirmation; and the legacy `enabled`, derived from the findings controls. The `scpm` object reports the supply-chain half of the gate; only its `gateEnabled` and `minPriority` are specific to your tenant, the rest is platform-wide. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/pr-gate-settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set PR gate settings

Replaces the whole setting, so send every field you want kept. `enabled` and `minPriority` are required, `minPriority` must be `URGENT` or `IMPORTANT`, and `scaBlockCvssThreshold` must be between 0 and 10; omitting it resets the cutoff to the default. With `findingsPolicy`, `enabled` must be true exactly when `findingsPolicy` is `confirmed` or `cvssEnforcement` is on, and any other `findingsPolicy` value (including the retired `net_new` and `triaged_confirmed`) is rejected; each is a `400`. `failOnIncompleteCoverage` is independent of the findings controls; omitting it keeps the stored value. Returns the stored values. Requires `ConfigWrite`.

```bash
curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"findingsPolicy":"confirmed","cvssEnforcement":true,"failOnIncompleteCoverage":false,"enabled":true,"minPriority":"IMPORTANT","prReviewsEnabled":true}' \
  'https://api.<TENANT>.nullify.ai/admin/pr-gate-settings?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/pr-gate-settings" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Manager agent

### Get manager settings

Returns the manager agent's stored guardrails in `settings` (`blockedActionTypes`, `groundRules`, `automatedThreatInvestigations`, which defaults to off) and, in `installed`, whether each integration class it needs is connected: `tickets`, `prCreation` and `messaging`. The agent acts on an action only when it is not blocked and its integration is installed, so check both. A tenant with no saved settings returns nothing blocked. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/manager/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update manager settings

Updates any of the three fields and leaves omitted ones unchanged. `blockedActionTypes` takes action types or the group aliases `PULL_REQUESTS`, `TICKETS` and `MESSAGING`; an empty array unblocks everything, and an unknown entry returns 400. `groundRules` is free text of at most 10,000 characters that is added to the agent's prompt; an empty string clears it. The save records configuration only and does not start or stop an agent run. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/manager/settings" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Cloud posture scan cadence

### Get the CSPM scan cadence

Returns `cspmScanCadence`. An empty string means no cadence is configured, which is scanned daily. A 5xx can be a transient database failure and is worth retrying. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/settings/cspm-scan-cadence" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the CSPM scan cadence

Sets `cspmScanCadence` to one of `daily`, `weekly`, `fortnightly`, `monthly`, `on_change` or `manual`; an empty string clears it back to daily. Any other value returns 400. The daily cloud-posture run skips a tenant already scanned inside its window, so the setting changes when scans happen and does not start one. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/settings/cspm-scan-cadence" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## UI preferences

UI preferences are a free-form JSON object that the Nullify web app stores per user. They belong to the calling user, keyed on the identity in the token, so these three calls need no permission beyond tenant access. A token that carries no user identity is rejected with 401.

### Get UI preferences

Returns the caller's `preferences` object (empty when nothing is stored) and `updatedAt`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/preferences" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update UI preferences

Merges the supplied `preferences` object into the stored one at the top level: a key you send replaces the stored value for that key, and keys you leave out are kept. The serialized object may be at most 512 KiB. Returns the merged result.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/preferences" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete UI preferences

Wipes the caller's stored preferences. It is idempotent: the response always has `deleted: true`, even when nothing was stored.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/preferences" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Saved views

A saved view stores a filter state for a page, as an opaque string in `data`. Views have a `viewPageType` of `OVERVIEW` or `TRIAGE` and a `viewOwnerType` of `ORGANIZATION` (shared across the tenant) or `USER` (private to the creator). These calls require `FindingRead` or `FindingWrite`, and take the tenant from your token, so no provider query parameter is needed. Service-account tokens have no personal identity: they see only organization views, can create only `ORGANIZATION` views (a `USER` view returns 401), and cannot reach any user's private view.

### List saved views

Returns the tenant's organization views plus the caller's own user views in `savedViews`. Requires `FindingRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/savedViews" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a saved view

Creates a view. `viewPageType`, `viewOwnerType`, `name` and `data` must all be non-empty or the call returns 400. The server sets the owner: `ORGANIZATION` views belong to the tenant, anything else is stored as a `USER` view owned by the caller, whatever `viewOwnerId` you send. Returns the stored view. Requires `FindingWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/savedViews" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a saved view

Rewrites the view named by `savedViewId`, taken from the list call, with the supplied `viewPageType`, `name` and `data`. The owner type and owner cannot be changed. Returns 404 when the id does not exist, or when it is another user's private view. Requires `FindingWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/savedViews/{savedViewId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a saved view

Soft-deletes the view named by `savedViewId` and returns its `id`. Returns 404 when the id does not exist or is another user's private view; any caller with `FindingWrite` can delete an organization view. Requires `FindingWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ui/savedViews/{savedViewId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Staff package feeds

These two operations are in the published spec but are not for customer use. `/admin/operator/package-feeds` manages the private package registry connections that Nullify staff attach to a tenant, and it is staff-only. Customer API tokens are rejected: the call needs a verified human Nullify staff identity (service identities are also refused) and an explicit tenant selector, and returns 403 otherwise. You cannot use it to manage your own feeds. It is documented here only so the reference is complete.

### Read staff package feeds

Staff only. Lists the package-registry connections for the tenant named by exactly one provider selector (for example `githubOwnerId`), with credentials redacted. The optional `connectionId` query parameter narrows it to one connection and returns 404 if it is not a package feed of that tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/operator/package-feeds" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Control a staff package feed

Staff only. Applies one change to a package-feed connection: `operation` is `create`, `rotate`, `probe` or `disconnect`, and `reason` (at most 1,024 characters) is required and recorded with the actor in the audit trail. Changes to an existing connection must send the `expectedRevision` from the read call and fail with a conflict when it is stale. `create` and `rotate` validate the supplied `fields` credentials against the provider before saving, returning 400 if validation fails. The response includes `upstreamRevocationRequired` and, if any exist, `maxOutstandingLeaseExpiry`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/operator/package-feeds" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Findings, Events and Metrics

Query findings across every scanner, export them, read the unified event feed, and pull the aggregate metrics behind the Nullify dashboard. For per-scanner finding operations, triage and autofix, use the scanner's own API page.

Every operation here is tenant-scoped. Pass the provider scope query parameter for your tenant (`githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`); see [Authentication](/api-reference/api-reference/authentication). When the caller is a team-scoped user, every findings-derived result below is restricted to the caller's teams. Team-scoped users get an empty result, never the tenant-wide data, from the pull request and ticket metrics. For team-addressed views of the same data, see [Teams and Ownership](/api-reference/api-reference/api-admin/teams).

## Findings

### Query findings

Returns a page of findings across all finding types (code, dependencies, containers, secrets, and so on) in one list. The JSON body wraps a `query` object whose filters include `type`, `repository`, `severity`, `priorityLabel`, `isResolved`, `isFalsePositive`, `isAllowlisted`, `hasTicket`, `fromDate`/`toDate`, `search`, `teamIDs` and many more; see the embedded schema for the full set. Sort with `sortPreset` (`created_at_desc`, the default, `created_at_asc`, `priority_desc` or `severity_desc`). Page with `page` and `pageSize`, or pass back the returned `scrollId`; `hasMoreData` tells you whether another page exists and `total` gives the match count. Requires the finding-list permission.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"query": {"severity": ["critical", "high"], "isResolved": false, "pageSize": 50, "sortPreset": "priority_desc"}}' \
  'https://api.<TENANT>.nullify.ai/admin/findings?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/findings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding

Returns one finding by its ID from the unified findings store, in the same shape as a list entry. Take the `findingId` from [Query findings](#query-findings). Returns 404 when the ID does not exist for your tenant, and also when the finding is outside a team-scoped caller's teams. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/finding/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Download findings as CSV

Runs the same `query` filters as [Query findings](#query-findings) and returns the matches as CSV text in the `csv` field of the JSON response. The page size is forced to 10,000, so an export is capped at 10,000 findings: narrow the filters to export more in slices. Rows are ordered by priority label, then finding type, then repository. Columns include finding ID and type, CWE, titles, category, priority and severity, assessment factors such as exploitability and impact, repository, branch, file path, resolved, allowlisted and false-positive flags, message and timestamps. Requires the finding-list permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/findings/download" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get finding progress

Returns per-finding lifecycle timestamps and duration metrics for the findings that match `query`, for measuring how long findings take to move through triage and resolution. The `query` takes the same filters as [Query findings](#query-findings). `total` is the number of rows returned in this response, and `hasMoreData` indicates whether more rows exist than were returned. Results are limited to repositories the caller may see. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/findings/progress" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Scan coverage

### Get scan coverage

Lists repositories with their scan coverage for one scanner: last commit, last scanned commit and time, and open finding counts by severity. `type` is required and is one of `sast`, `sca_dependencies`, `sca_containers`, `secrets` or `scpm`; any other value returns 400. Use `search` for a case-insensitive match on repository name or owner, `sortBy` (`name`, `lastCommitAt`, `lastScanAt`, `critical`, `high`, `medium`, `low`, `total`; default `lastCommitAt`) with `sortOrder` (`asc` or `desc`, default `desc`), and page with `limit` (default 50, maximum 500) and `offset`. Sorting applies to the whole result set before paging. The response carries `totalCount` and `scannedCount`. For team-scoped callers, only repositories with findings in the caller's teams appear, and counts reflect those findings only. Requires the finding-read permission.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/assessments/scan-coverage?githubOwnerId=1234&type=sast&sortBy=critical&limit=50'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/assessments/scan-coverage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get scan coverage findings

Drills into one repository from [Get scan coverage](#get-scan-coverage) and lists its findings for the same scanner. `type` (same five values) and `repositoryId` (the `repositoryId` from the coverage list) are both required. Page with `limit` (default 50, maximum 500) and `offset`. Each row has severity and priority labels, location, allowlist state and timestamps, plus type-specific fields: package and version for `sca_dependencies`, image name and tag for `sca_containers`, and secret type, author and a `verified` flag for `secrets`. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/assessments/scan-coverage/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Events

### List unified events

Returns the cross-service event feed, newest first: scanner, autofix, manager and other service events in one stream. All filters go in the JSON body: `services` and `excludeServices` (values are `sast`, `sca`, `secrets`, `dast`, `scpm`, `cspm`, `orchestrator`, `context`, `manager`, `webhooks`, `auth`, `notifications` or `billing`; an unknown service returns 400), `eventTypes`, `excludeEventTypes`, `findingIds`, `autofixId`, `prCanonicalId`, `runId`, `campaignId`, and a time window with `afterTimeUnix` and `beforeTimeUnix`. The feed always excludes the `auth`, `notifications`, `billing` and `orchestrator` services, pipeline lifecycle event types and internal SCPM bookkeeping events, in addition to any exclusions you send. `limit` defaults to and is capped at 1000.

Pagination is cursor-based, not `nextToken`. When `hasMore` is true, send the response's `nextCursorTime` as `beforeTimeUnix` and `nextCursorId` as `afterId` in the next request. Requires the finding-read permission.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"services": ["sast"], "limit": 100}' \
  'https://api.<TENANT>.nullify.ai/admin/events?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/events" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Metrics

### Query overview metrics

Returns the dashboard overview for the findings that match `query` (same filters as [Query findings](#query-findings)): the remediation funnel by severity, this-month versus last-month figures for findings resolved, autofix PRs merged, false positives, SLA state, triage coverage and bot interactions, breakdowns by repository, language, CWE and finding type, and the value lists used to populate filters. SLA windows come from your configured SLAs, falling back to 7 days (urgent), 14 days (important) and 28 days (informational). Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/overview" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Query raw metrics

Runs several named finding queries in one call and returns the match count for each. The `query` object maps a name you choose to a findings filter (same filters as [Query findings](#query-findings)), and the response maps each name to `{"doc_count": N}`. Send between 1 and 50 sub-queries; an empty or larger query returns 400. The tenant from your provider scope parameter overrides any tenant in a sub-query. Requires the finding-read permission.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"query": {"open_critical": {"severity": ["critical"], "isResolved": false}, "open_high": {"severity": ["high"], "isResolved": false}}}' \
  'https://api.<TENANT>.nullify.ai/admin/metrics/raw?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/raw" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get metrics over time

Returns two cumulative daily series for the findings that match `query`: `introduced` and `fixed`, each a list of `{startTimeStamp, number}` points where `number` is the running total up to that day, including everything introduced or fixed before the window starts. Set the window with `fromDate` and `toDate` in the query. Buckets are always daily and in UTC: the `resolution` query parameter (`hour`, `day`, `week`) is accepted but has no effect. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/over-time" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get findings metrics

Returns aggregate analysis metrics for the findings that match the `query` filter. Set `includeFunnel` to `true` in the body to also receive the remediation funnel block; it is omitted otherwise. Results are limited to repositories the caller may see. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/findings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get findings metrics by repository

Returns per-repository closure and time-to-resolve metrics for the findings that match `query`, one entry per repository. Use it to compare repositories or rank them by remediation speed. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/findings/by-repository" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get compliance framework metrics

Returns finding counts per compliance framework for the tenant, emphasizing critical and high severity. The request takes no filters; it always covers the whole tenant. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/findings/frameworks" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get pull request metrics

Returns aggregate metrics for pull requests that Nullify opened or tracks: current-state counts by status, a type split (`autofix`, `allowlist`, `manual_fix`), and this-month versus last-month trends. Filter with `fromDate`, `toDate`, `repository`, `repositoryOwner`, `platform`, `prType` and `findingType` in the `query` object. Team-scoped callers receive an empty result because pull requests have no team association. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/pullrequests" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get ticket metrics

Returns aggregate metrics for tickets created from findings: current-state counts by status (placeholder tickets that are still being created are excluded), a split by platform (Jira, Linear, GitHub, Azure) and this-month versus last-month trends. Filter with `fromDate`, `toDate`, `platform`, `findingType` and `source` (for example `scan_pipeline`, `manager_agent`, `reconciliation`, `rest_api`, `dashboard`) in the `query` object. Team-scoped callers receive an empty result. Requires the finding-read permission. To create or manage tickets, see [Ticketing](/api-reference/api-reference/api-admin/ticketing).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/tickets" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get bot interactions

Lists the interactions Nullify has had with your findings, such as autofix pull requests, ticket creation, pull request comments and internet searches, with a `summary` of counts per interaction type. Optionally bound the window with `fromDate` and `toDate` (RFC3339), filtered by each interaction's own event time; omit both for all-time. The response is built from up to 10,000 findings, so it can be incomplete on very large tenants. Tenant selection here honors only `githubOwnerId` and `bitbucketWorkspaceId`. Requires the config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/interactions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Onboarding

### Get setup checklist

Intended to return a checklist of post-install items. The operation currently always returns an empty `items` list, so do not rely on it to track onboarding. Requires the config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/checklist" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Identity, Access and Service Accounts

Use these operations to see who the caller is, manage workspace roles and defaults, connect a Microsoft Entra directory, issue SCIM credentials, restrict network access, and manage the service accounts that authenticate API automation. All paths are under your tenant API URL (`https://api.<TENANT>.nullify.ai`); see [Authentication](/api-reference/api-reference/authentication) for tokens.

Most operations take the provider scope query parameter for your source-control provider, for example `githubOwnerId=<OWNER_ID>`, `gitlabGroupId`, `azureOrganizationId` or `bitbucketWorkspaceId`; see each operation's schema.

Roles are the built-in values `builtin:admin`, `builtin:editor` and `builtin:viewer`. Operations that change identity settings need the identity-management permission, which only `builtin:admin` holds. Role-permission enforcement is a tenant rollout setting, as described in [Authentication](/api-reference/api-reference/authentication#authorization-and-token-lifetime).

Do not assume every operation here accepts a service-account token: Entra account linking, consent and sign-in policy changes need an authorized human session, and policy changes additionally need a recent verified Microsoft sign-in (see [Entra sign-in policy](#get-or-change-the-entra-sign-in-policy)). Follow [Entra setup and recovery](/configuration/account-and-teams/entra-sso-and-scim), [group-driven role mapping](/configuration/account-and-teams/entra-group-role-provisioning) and the [LIAM/Saviynt contract](/configuration/account-and-teams/saviynt-scim) for complete workflows, and the [Azure DevOps installation guide](/enterprise-tier/azure-install) for Azure DevOps consent and organization setup. See [Account Access and Teams](/configuration/account-and-teams) for member management in the dashboard, and [Users](/api-reference/api-reference/api-admin/users) for user records and lifecycle.

## Caller and organization

### Get caller access

Returns the calling user's resolved role, team ids, the permission keys that role grants, whether team scoping applies to the caller, and how the account is managed (`scm`, `scim` or `manual`). The dashboard calls this first to decide what to show. Any authenticated tenant member can call it. A caller who is a real organization member with no role yet is given the tenant's default invitee role on this first call. It returns 403 when the tenant's invite-activation gate is on and the caller has not been activated, and for incomplete managed-SSO identities.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/access/me" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get organization

Returns the organization (or workspace) for the provider scope you pass: its id, name, teams and members as read from the source-control provider. Requires config-read permission. If the provider cannot be reached, teams or members come back as empty lists rather than an error, so an empty list is not proof the organization has none. For the full team and member records use [Teams](/api-reference/api-reference/api-admin/teams) and [Users](/api-reference/api-reference/api-admin/users).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/organization" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Roles and access defaults

### List user roles

Lists the tenant's users with their role and activation state. Accounts that Nullify staff use for support are not listed. Requires user-management permission. `limit` defaults to 100 and is capped at 500, `search` filters case-insensitively across name, username and email, and `total` counts every match, not only the page. Page with `offset`, or pass the returned `nextKey` back as `startKey`; `nextKey` is omitted on the last page. See [Pagination](/api-reference/api-reference/pagination) for the general pattern, but note this operation uses numeric offsets.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/access/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set user roles

Assigns one role to one or more users in a single all-or-nothing write. Requires both identity-management and role-assignment permission, so it is admin-only. Each entry in `users` sets exactly one of `userId` (an existing user from [List user roles](#list-user-roles)) or `newUser` (a provider member with no Nullify account yet, identified by `username`, created under the tenant's owner provider as part of the write). A `newUser` whose username already has an account is treated as that existing user.

Two guards apply to the whole batch. You cannot include yourself, whether promoting or demoting (403), and the batch cannot leave the tenant without an administrator (403). Unknown user ids return 404, an invalid role returns 400, and every changed role is written to the audit log with the old and new role.

```bash
curl -s -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"role": "builtin:editor", "users": [{"userId": "01J..."}, {"newUser": {"username": "octocat"}}]}' \
  'https://api.<TENANT>.nullify.ai/admin/access/users/roles?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/access/users/roles" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get and set RBAC preferences

`GET` returns the tenant's default invitee role (the role newly synced users land on) and `teamScopedRoles` (roles whose members see only findings of teams they belong to). Reading requires user-management permission; a tenant that has never set preferences gets the defaults.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/access/preferences" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PUT` replaces both fields; both are required, so omitting one does not leave it unchanged. It requires identity-management and role-assignment permission. `defaultInviteeRole` must be a built-in role, and `teamScopedRoles` entries must be built-in roles other than `builtin:admin`, which cannot be team-scoped (400). Duplicates in `teamScopedRoles` are dropped.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/access/preferences" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Microsoft Entra directory

These operations manage the tenant's Microsoft Entra directory binding. The connect, link and handoff operations return a Microsoft URL for a browser to open; they do not complete anything on their own. Entra connections are only available for workspaces that Nullify can route by tenant, and a workspace that cannot returns 412 (failed precondition), as does a deployment where the shared Microsoft application is not configured.

### Get directory binding status

Returns whether the deployment has Entra configured (`configured`), whether this tenant has a directory bound (`connected`), and if so the directory id, binding `status` (`pending`, `verified` or `disabled`), verified domains and last verification time. `configured: false` means no connection can be started here. Any authenticated tenant member can call it.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start the directory connection

Requires identity-management permission. Returns `redirectUrl`, a Microsoft admin-consent URL, and sets a short-lived (10 minute), HttpOnly state cookie that binds the consent to the browser that called this operation. Send the user's browser to `redirectUrl` from that same browser session; a consent callback arriving without the matching cookie is rejected. Because of the cookie, call this from a browser session rather than a script, and use the dashboard's generated URLs instead of constructing callback URLs yourself.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra/connect" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delegate directory consent to another administrator

Requires identity-management permission. When the person who can grant Microsoft consent is not a Nullify administrator, pass that organization's Entra directory GUID as `directoryId` and send the returned `handoffUrl` to them. The link is single-use, expires 24 hours later (`expiresAt`), replaces any earlier link for the workspace, is returned with `Cache-Control: no-store`, and consenting through it does not give them any membership of your workspace. The recipient sees your workspace's name and must confirm it after signing in. A malformed `directoryId` returns 400; a workspace that already has a directory, or a sign-in policy change in progress, returns 412; a second link within a minute returns 429. Treat the link as a secret.

`GET /admin/identity/entra/handoff` lists your live links without the links themselves, and `DELETE /admin/identity/entra/handoff/{id}` revokes one; both require identity-management permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra/handoff" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start a self-service account link

Any authenticated tenant member can call this to bind their own existing Nullify account to their Microsoft identity. It returns a Microsoft sign-in URL (with account selection forced) and a 10-minute state cookie, used the same way as [Start the directory connection](#start-the-directory-connection). It cannot link anyone else's account. Callers who already authenticated through Entra get 412, a caller with no existing account gets 404, and a Microsoft account already linked to a different Nullify account gets 409.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra/link" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Disconnect the directory

Requires identity-management permission. Removes the tenant's Entra directory binding and the sign-in projection that depends on it. It is a no-op when nothing is bound. It is refused with 412 while required Microsoft sign-in is on or a policy change is still pending: turn the policy off first with [the sign-in policy operation](#get-or-change-the-entra-sign-in-policy).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get or change the Entra sign-in policy

`GET` returns the workspace's policy for a verified directory: `directoryId`, whether Microsoft sign-in is `required`, `updatedAt`, and `pending` / `pendingRequired` if a change is still being applied. Any authenticated tenant member can call it, but it returns 403 unless the workspace has exactly one verified directory binding.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra/policy" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PUT` turns required Microsoft sign-in on or off. It is deliberately strict:

* It needs identity-management permission and a Microsoft-authenticated administrator session that signed in within the last five minutes. A service-account token, or a session without that recent verified Microsoft sign-in, gets 403.
* Send the `updatedAt` you last read as `expectedUpdatedAt`. If the policy changed since, the call fails with 409; re-read and retry.
* `reason` is required, 1 to 500 characters, and is written to the audit log.
* `dryRun: true` runs the same checks, including that the acting administrator is still an active administrator, without changing anything.

A 503 means directory management is not available for the workspace right now.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/entra/policy" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## SCIM provisioning

SCIM requests use the tenant's SCIM base URL and a SCIM bearer credential, not a service-account token. These operations manage those credentials and require identity-management permission. Credentials are bound to the connected Entra directory, so a directory must be connected first.

### Get SCIM settings

Returns `baseUrl` (the tenant's SCIM endpoint) and the active credentials. Each credential shows its id, creation time and last use; secrets are never returned. Revoked credentials are not listed.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/scim" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a SCIM credential

Mints a new credential and returns its `token` once. Only a hash is stored, so copy the token immediately; it cannot be retrieved later. Returns 412 if no Entra directory is connected. Create the new credential, update your directory, then revoke the old one to rotate without a gap.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/scim/credentials" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Revoke a SCIM credential

Revokes the credential with the `id` from [Get SCIM settings](#get-scim-settings), effective on its next use. Returns 404 if the id is not an unrevoked credential of your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/identity/scim/credentials/{id}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Network access

### Get the IP allowlist

Requires identity-management permission. Returns the allowed ranges (id, `cidr`, description, who created each and when) and `callerIp`, the address the request appears to come from, so you can check it is covered before changing the list. An empty list means no restriction.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/network/ip-allowlist" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Replace the IP allowlist

Requires identity-management permission. Replaces the whole list atomically: send every range you want to keep as `entries` (up to 50, each a `cidr` and optional `description` of up to 200 characters; a bare address is stored as a single host). An empty list removes the restriction. Invalid ranges, `0.0.0.0/0` or `::/0`, duplicates and lists over the limit return 400. A list that does not include the caller's own address is rejected with 412 so you cannot lock yourself out. Send `expectedCidrs`, the ranges you last read, to have a list changed in between refused with 409. Service accounts and GitHub Actions are never restricted by the allowlist. The change is audit-logged with the previous and new ranges.

```bash
curl -s -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"entries": [{"cidr": "203.0.113.0/24", "description": "Office"}]}' \
  'https://api.<TENANT>.nullify.ai/admin/network/ip-allowlist?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/network/ip-allowlist" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Preview an IP allowlist

Requires identity-management permission. Takes the same `entries` as a replace and stores nothing. Returns `warnings` (for example no IPv6 range, a private range or a single host), `callerAllowed` (whether the list admits your own address) and `dryRun: true`. Invalid ranges and lists that match every address return 400. Treat any reply without `dryRun: true` as a failure.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/network/ip-allowlist/preview" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Service accounts

Service accounts issue the tokens that authenticate API automation (see [Authentication](/api-reference/api-reference/authentication)). Use a separate account per automation.

### List service accounts

Requires service-account list permission. Returns each account's id, name, provider platform, role and creation time for the provider scope you pass. Tokens are never returned here.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/service\_accounts" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a service account

Requires identity-management and service-account write permission. `name` and `platform` are required: `name` is at most 64 characters and `platform` is the source-control provider the account acts on (for example `GitHub`). Set `role` explicitly to `builtin:admin`, `builtin:editor` or `builtin:viewer`; omitting it defaults to `builtin:admin`, and any other value is rejected with 400. The response contains the signed `token` once; store it in a secrets manager.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-automation", "platform": "GitHub", "role": "builtin:viewer"}' \
  'https://api.<TENANT>.nullify.ai/admin/service_accounts?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/service\_accounts" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a service account

Requires service-account write permission. Pass the account's `serviceAccountId` (from [List service accounts](#list-service-accounts)) as a query parameter. An id that does not exist in your tenant returns 403. Deletion is permanent.

{% hint style="warning" %}
Deleting the record does not invalidate a token that was already issued, and service-account tokens do not expire on their own. Do not use deletion as incident-response revocation; see [Authentication](/api-reference/api-reference/authentication#authorization-and-token-lifetime).
{% endhint %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/service\_accounts" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Privacy acknowledgment

### Get a privacy acknowledgment

Reports whether the calling user has acknowledged the privacy policy version in the required `policyVersion` query parameter, and when. Any authenticated tenant member can call it; the answer is for the caller only.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/privacy/acknowledgment" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Record a privacy acknowledgment

Records that the calling user acknowledged the policy version in the `policyVersion` body field. Nullify stores the time, the client IP taken from `X-Forwarded-For` (first address) or `X-Real-IP`, and the user agent. Acknowledgments are included in a user's data export and removed by erasure; see [Users](/api-reference/api-reference/api-admin/users).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/privacy/acknowledgment" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Cloud Integrations

These operations connect your cloud accounts to Nullify for cloud security scanning and Kubernetes context: AWS (an IAM role Nullify assumes), Azure (an app registration), GCP (workload identity federation) and Kubernetes clusters. Each provider has a settings resource you read, save and delete, plus a validation call that proves Nullify can reach the account.

Reads (`GET`) require `secret-config:read`; saves, deletes, validations and the Kubernetes allowlist call require `config:write`. See [Authentication](/api-reference/api-reference/authentication) for tokens. Every call acts on the tenant of your token and takes the provider scope of the installation as a query parameter (for example `githubOwnerId`); use `GET /admin/installations` from [Source Control and CI Integrations](/api-reference/api-reference/api-admin/integrations-source-control-and-ci#list-installations) to find the value. The cloud settings are stored per tenant, so each call reads and writes one settings record per provider.

Responses never return secrets: the Azure `clientSecret` is write-only.

## AWS

Nullify scans an AWS account by assuming an IAM role in it. You save the role name and account list, create the role in each account with the `externalId` Nullify returns, then validate that the role can be assumed. Account ids in `awsAccounts` are 12-digit AWS account ids.

### Get AWS settings

Returns the saved AWS integration: `iamRoleName`, `externalId`, `awsAccounts` with a per-account `lastVerifiedStatus`, `preferredDeployment`, the Nullify-side `nullifyRoleArn`, `nullifyS3Bucket` and `nullifyKMSKeyArn`, and an `overallStatus`. When the last validation found connector permissions the role was refused, they are listed in `connectorPermissionGaps`; read `connectorPermissionProbe` alongside it, because an empty gap list only means the role is complete when the probe is `complete` (`incomplete` and `not_probed` mean the list is not a proof). Returns 404 when no AWS settings are saved. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/aws/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save AWS settings

Creates or replaces the tenant's AWS settings. `iamRoleName`, `awsAccounts` and `preferredDeployment` (`helm`, `terraform`, `cloudformation` or `cloud_connector`) are required; a missing `preferredDeployment` returns 400. `externalId` is optional in the request and is returned in the response, so create the IAM role in your accounts with that value in its trust policy. The `awsAccounts` list is the full desired set: after saving, Nullify reconciles the upload allowlists (bucket, access point and KMS key) used by the Kubernetes collector so that accounts you removed lose access and accounts you added gain it. Most allowlist failures are logged and do not fail the call; if another reconcile holds the lock the call returns 503 and you should repeat it, or use [Allow Kubernetes collector accounts](#allow-kubernetes-collector-accounts). Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/aws/settings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Validate an AWS role

Tries to assume the role in each account listed in `accountIds` (1 to 100 accounts per request; an empty list or more than 100 returns 400) and reports a per-account result keyed by account id, plus an `overallStatus` of `healthy` or `unhealthy`. `roleNameToAssume` overrides the saved role name, which lets you test a candidate role before saving it; without it the saved `iamRoleName` is used and 400 is returned if there is none. The call also runs a connector permission preflight on each role it could assume and returns `connectorPermissionGaps` and `connectorPermissionProbe`. Save settings first: with no saved Nullify role the call returns 412. When the role name and accounts match the saved settings, the result is stored (visible on the next get as `lastValidatedAt` and per-account status); validating a different role or account list stores nothing. The call is synchronous and does not change any AWS resources. Requires `config:write`.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"accountIds": ["123456789012"]}' \
  'https://api.<TENANT>.nullify.ai/admin/integrations/cloud/aws/validate-role?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/aws/validate-role" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete AWS settings

Removes the tenant's AWS settings. Before deleting, Nullify strips the saved accounts from the collector upload allowlists. If another reconcile holds the lock the call returns 503 and keeps the settings so you can repeat it; other allowlist failures are logged and the delete still goes ahead. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/aws/settings" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Azure

Azure uses an app registration in your Entra tenant. The recommended `authMode` for validation is workload identity federation, where Nullify presents a signed token instead of a stored secret.

### Get Azure settings

Returns the saved Azure integration: `tenantId`, `clientId`, `authMode`, `displayName`, `subscriptions` with per-subscription verification status, and the last validation result. For workload identity federation it also returns `wifIssuerUrl` and `wifSubject`, the issuer and subject to put in the app registration's federated credential. `overallStatus` is always `configured` here; use `lastValidationStatus` for health. Returns 404 when no Azure settings are saved. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/azure/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save Azure settings

Creates or replaces the tenant's Azure settings. `tenantId` and `authMode` are required, and `authMode` must be `service_principal`, `managed_identity` or `workload_identity_federation`. `clientId` is required for workload identity federation and service principal auth, and `clientSecret` is also required for service principal auth; the secret is write-only and never returned. A validation failure returns 400. Saving does not check the credentials; call [Validate Azure credentials](#validate-azure-credentials) next. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/azure/settings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Validate Azure credentials

Authenticates to Azure with the saved workload identity federation configuration and checks access to each subscription, returning a per-subscription result and an `overallStatus` of `healthy` or `unhealthy`. Without `subscriptionIds` it checks the saved subscriptions that are enabled; ids you pass must already be in the saved settings (otherwise 400). Returns 412 when no settings are saved, when the saved `authMode` is not `workload_identity_federation` (other modes cannot be verified here), or when there are no subscriptions to check. A credential that cannot authenticate is reported as `unhealthy` in the body, not as an HTTP error. The result is stored on the settings. `connectorPermissionProbe` is always `not_probed`: a healthy result proves the credentials work, not that the app registration has every role the collectors need. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/azure/validate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete Azure settings

Removes the tenant's Azure settings. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/azure/settings" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## GCP

GCP uses workload identity federation: you create a workload identity pool and provider in your project and a service account that Nullify impersonates, then save their identifiers.

### Get GCP setup values

Returns what you need to create the GCP side with Terraform, the installer script or any other tool: `oidcIssuerUrl`, `tenantId`, ready-to-paste `terraformVariables` and `installerEnv`, the provider attribute condition and mapping, the service account binding role and member, the required APIs, and the read-only, discovery and custom roles. Works before any settings are saved. Requires `secret-config:read`. `GET /admin/integrations/cloud/gcp/setup`.

### Get GCP settings

Returns the saved GCP integration: `workloadIdentityProvider`, `workloadIdentityServiceAccountEmail`, `displayName`, `projects` with per-project status, any `gkeClusterOidcIssuerUrls`, and the last validation result. Returns 404 when no GCP settings are saved. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/gcp/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save GCP settings

Creates or replaces the tenant's GCP settings. `workloadIdentityProvider` must match `projects/{NUMBER}/locations/global/workloadIdentityPools/{POOL}/providers/{PROVIDER}` and `workloadIdentityServiceAccountEmail` must be a `*.iam.gserviceaccount.com` address; otherwise the call returns 400. `discoveryScope` is `PROJECTS` (the default, which needs at least one entry in `projects`), `ORGANIZATION` (needs `organizationId`) or `FOLDER` (needs `folderId`). Each entry in `gkeClusterOidcIssuerUrls` must be a `https://container.googleapis.com/v1/projects/{PROJECT}/locations/{LOCATION}/clusters/{NAME}` URL (the `/zones/` form is normalised). When GKE issuer URLs are set, Nullify also updates the trust of its Kubernetes collector role; a failure there is logged and does not fail the call. Saving does not check the credentials; call [Validate GCP credentials](#validate-gcp-credentials) next. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/gcp/settings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Validate GCP credentials

Exchanges the saved workload identity for a token and checks access to projects, returning a per-project result and an `overallStatus` of `healthy` or `unhealthy`. With `PROJECTS` scope it checks the `projectIds` you pass, or the saved enabled projects. With `ORGANIZATION` or `FOLDER` scope it lists the projects under that scope (or checks the `projectIds` you pass); if the service account cannot list them the call returns 403 and the message points at the missing `roles/browser` grant. Returns 412 when no settings are saved or there are no projects to check. A credential that cannot authenticate is reported as `unhealthy` in the body. The result is stored on the settings. `connectorPermissionProbe` is always `not_probed`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/gcp/validate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Mint a GCP access token

Returns a short-lived GCP `accessToken` and its `expiresAt`, obtained with the tenant's saved workload identity settings. This is a token broker for Nullify's own agents: it accepts only credentials minted for that purpose and returns 403 for an ordinary API token, so integrators should not need it. Returns 412 when GCP settings are missing or incomplete. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/gcp/access-token" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete GCP settings

Removes the tenant's GCP settings and, when GKE trust was configured, removes the matching trust from the Kubernetes collector role (a failure there is logged and the delete still goes ahead). Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/gcp/settings" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Kubernetes

Kubernetes settings list the clusters whose workloads Nullify collects (`clusterType` is `EKS`, `AKS`, `GKE` or `ON_PREM`) and the `nullifyRoleArn` it uses for EKS. Each cluster in a response has an `id` and a `scanIdentity`, and either can address it in [Remove a Kubernetes cluster](#remove-a-kubernetes-cluster). Clusters are identified by type, account, region and name (`resourceId` for AKS). Use the cluster calls to change one cluster without resending the rest.

### Get Kubernetes settings

Returns the saved Kubernetes integration: `nullifyRoleArn`, every cluster with its latest verification status, and the last validation result. Returns 404 when none are saved. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save Kubernetes settings

Replaces the whole cluster set with the `clusters` you send; a cluster you leave out is removed. Omit `nullifyRoleArn` to keep the stored value (an empty string clears it). `collectSecrets` and `collectConfigMaps` (secret metadata and ConfigMaps) keep their stored values for matched clusters when omitted. Each cluster needs a valid `clusterType` and a `clusterName` with no surrounding whitespace; an invalid cluster returns 400. EKS clusters need a 12-digit `cloudAccountId` and a valid `region`. To change one cluster, use [Add or update a Kubernetes cluster](#add-or-update-a-kubernetes-cluster). Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/settings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Add or update a Kubernetes cluster

Adds one cluster, or updates the cluster that has the same identity, and leaves the other clusters and the role ARN alone. The response has the `cluster` and `created`, which is true when a new cluster was added. Omitted `collectSecrets` and `collectConfigMaps` keep their stored values and default to true for a new cluster. An EKS cluster must name a 12-digit AWS account that is already connected in your AWS settings, otherwise the call returns 400; connect the account with [Save AWS settings](#save-aws-settings) first. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/clusters" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Remove a Kubernetes cluster

Removes one cluster, addressed by `clusterId`, which is either the cluster `id` or its `scanIdentity` from a get or upsert response. Other clusters and the integration settings stay. Returns 404 when no cluster matches. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/clusters/{clusterId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete Kubernetes settings

Removes the tenant's Kubernetes integration and all of its clusters. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/settings" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Allow Kubernetes collector accounts

Reconciles the allowlists (bucket, access point and KMS key) that let the Kubernetes collector in your AWS accounts upload to Nullify. Pass `accountIds`, or omit them to use every account in the saved AWS settings (404 when none are saved, 400 when the saved list is empty). The list is the full desired set, so accounts that are not in it lose access. The call returns 200 even when part of the reconcile fails: check `s3PolicyUpdated`, `accessPointPolicyUpdated`, `kmsPolicyUpdated`, the `s3Error`, `accessPointError` and `kmsError` fields and `message`. `kmsSkipped` is true when no KMS key is configured for the deployment. A concurrent reconcile is reported in the error fields; retry shortly. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/cloud/k8s/whitelist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Source Control and CI Integrations

These operations list the source-control installations your token can reach, manage the Azure DevOps webhook and Boards configuration, and store credentials for the Buildkite, CircleCI and Jenkins CI integrations. Each operation lists the permission it requires: `config:read`, `config:write`, or for one Azure read, `secret-config:read`. See [Authentication](/api-reference/api-reference/authentication) for tokens.

Provider scope: Azure operations that act on an organization take it in the request body or in the `azureOrganizationId` query parameter, as noted per operation. Use [List installations](#list-installations) to discover the right scope value for each installation. For the user-facing Azure DevOps setup, see the [Azure DevOps installation guide](/enterprise-tier/azure-install).

## Installations

### List installations

Returns the app installations your caller identity can access across GitHub, Azure DevOps, Bitbucket and GitLab. Each entry carries a `provider` object, a display name, an avatar URL where the provider has one, `queryParameters` (for example `githubOwnerId` or `azureOrganizationId`) and, when it can be resolved, `nullifyBaseUrl`. Pass the `queryParameters` values as the provider scope on other admin calls and send later requests to `nullifyBaseUrl` when it is set. This endpoint has no permission requirement beyond a valid identity.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/installations'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/installations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## GitHub

### Get GitHub App settings

Reads the webhook events and permissions currently granted to the GitHub App installation for the scoped owner (`githubOwnerId`) and compares them with the set Nullify expects. The response lists `events`, `permissions`, `missingEvents`, `missingPermissions` and `incorrectPermissions`, so you can spot an installation that needs its permissions re-approved. Failures to resolve the installation do not return an HTTP error: the response carries an `error` message instead (for example when the scope is not a GitHub owner or has no installation ID). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/github/app-settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Discover GitHub Packages identity

Takes a classic GitHub personal access token in the request body and returns the token's `username`, `packageOrigin` and the npm packages it can read, so a connect form can prefill fields before any connection is created. Nothing is stored. The scope must be a GitHub owner (`githubOwnerId`), because discovery runs against that owner; a rejected token returns 400 and an upstream failure returns a retryable 5xx. The token is never echoed back. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/github-packages/discover" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Azure DevOps

Azure DevOps has two layers. The git connector (organizations, repositories, service hooks) is connected through the consent flow described in the [installation guide](/enterprise-tier/azure-install), and the operations below manage the webhooks and policies that connector uses. A separate Boards credential, stored by [Set Azure Boards credentials](#set-azure-boards-credentials), enables ticket creation in Azure DevOps Boards.

### Install service hooks

Provisions Azure DevOps service hooks for every repository the connected credentials can see. Scope it with `azureOrganizationId` (or the organization headers your identity carries). Subscriptions that are disabled or have drifted are replaced in place, and subscriptions already delivering to Nullify are skipped unless you pass `reconcile=true`, which rewrites them with the current webhook URL and per-install secret. The response reports `hooksCreated`, `hooksReplaced`, `hooksSkipped` and a `failures` list rather than failing the whole call, so check `failures` before assuming every repository is covered. Returns 400 for an organization that is not one of the caller's, and 403 for one that has no verified connection. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List webhook installations

Lists the Azure DevOps webhook installations registered for your tenant, one per organization and project, with each install's creation and update times, whether it has been suspended (`adminDisabledAt`, `adminDisabledBy`) and `webhookSecretRotatable`. The per-install webhook secret is never returned here. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/installations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Register a webhook installation

Registers, or rotates the secret of, the webhook installation for one Azure DevOps project. Send `organizationId` and `projectId` in the JSON body. The `organizationId` here is the account id that webhook deliveries carry as `resourceContainers.account.id`, which is not the collection id used by the Azure DevOps REST API and not the `azureOrganizationId` query parameter; a row registered with the wrong id never matches a delivery. The response returns the shared `webhookSecret` once, so store it immediately. Returns 403 if the organization is not connected or the install belongs to another tenant, and 412 if the organization's secret is managed by Nullify's router (reconnect the organization to rotate it) or was disabled by Nullify. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/installations" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a webhook installation

Removes the install for the `organizationId` and `projectId` query parameters (both required). Before deleting the row, Nullify tries to remove the project's service-hook subscriptions and its branch policy. That cleanup is best-effort: anything that could not be removed is listed in `failures`, and the row is deleted regardless, so remove leftovers by hand in Azure DevOps if `failures` is not empty. Returns 404 if the install does not exist. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/installations" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Suspend or resume an organization

Pass `organizationId` and `suspended` in the JSON body. With `suspended: true` Nullify disables the organization's service-hook subscriptions, makes its branch policy non-blocking and marks each install row disabled; `suspended: false` reverses all three. `installationsAffected` counts Nullify install rows only, so read `failures` to learn whether Azure DevOps itself stopped or resumed delivering: a non-empty list means the organization may still be sending events. Resuming an organization that Nullify itself disabled is refused with 412. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/installations/suspend" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Test an organization

A read-only recheck of an already-connected organization. It verifies connectivity, lists repositories and reports missing, drifted or disabled service-hook subscriptions as a `checklist`, with `ok` false when any item fails. It creates, replaces and disables nothing. Send `organizationId` in the JSON body. Returns 404 for an unknown organization. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/installations/test" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Preview CODEOWNERS as required reviewers

Reads one repository's CODEOWNERS file and reports the Azure DevOps required-reviewer policies it would translate to, plus the owners and rules that could not be carried over. Send `organizationId`, `projectId` and `repositoryId` in the JSON body. `path` must be `CODEOWNERS`, `.github/CODEOWNERS` or `docs/CODEOWNERS` (any other value returns 400); omit it to try those three in order. `ref` selects the branch and defaults to the repository's default branch. Read-only: no policy is created, changed or deleted. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/codeowners/preview" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Azure Boards configuration

Returns the Azure client ID and Entra tenant ID used for Azure DevOps Boards ticketing, whether a client secret has been stored (`clientSecretUploaded`) and a redacted form of it. When Boards settings were saved, the response also includes the organization, project name and work item type. The secret itself is never returned. This is the only operation in this page that requires `secret-config:read` rather than `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set Azure Boards credentials

Stores the client ID, tenant ID and client secret (all required in the JSON body) used to create tickets in Azure DevOps Boards. The secret is encrypted and stored for your tenant. If you also send `projectName`, Nullify first checks that the `organization` is connected to your workspace and that the project's process defines the work item type (or a default one) with states it can use to close and reopen items; a failed check returns 400 and nothing is saved. Saving a `projectName` also enables automatic ticket creation for Azure DevOps by default. The response echoes the configuration with the secret redacted. Requires `config:write`. See [ticketing.md](/api-reference/api-reference/api-admin/ticketing) for how tickets are used.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/azure/credentials" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Buildkite

### Get Buildkite status

Returns `configured` and, when it is, the stored `orgSlug`. Configured means an organization slug is stored; the token is never returned. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/buildkite" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List Buildkite organizations for a token

Takes a Buildkite API token in the body and returns the organizations (`slug` and `name`) it can access, so you can choose a slug before saving. The token must start with `bkua_` followed by alphanumeric characters, otherwise the call returns 400, as it does when Buildkite rejects the token. Nothing is stored. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/buildkite/organizations" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the Buildkite token

Verifies the token against Buildkite, then stores it with the organization slug. `apiToken` is required and must start with `bkua_`. `orgSlug` is optional: if you omit it Nullify selects the organization the token can access, and it needs you to supply one when the token sees more than one. A slug must be alphanumeric with hyphens. The stored slug uses the casing Buildkite reports and is returned as `orgSlug`. Bad credentials return 400, upstream failures a retryable 5xx. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/buildkite/token" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete the Buildkite integration

Removes the stored Buildkite token and organization slug. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/buildkite" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## CircleCI

### Get CircleCI status

Returns whether a CircleCI token is stored (`configured`). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/circleci" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the CircleCI token

Stores the CircleCI API token. `apiToken` is required in the body; unlike Buildkite, the token is not verified against CircleCI before it is saved. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/circleci/token" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete the CircleCI integration

Removes the stored CircleCI token. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/circleci" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Jenkins

### Get Jenkins status

Returns whether a Jenkins integration is configured (`configured`, true when a Jenkins URL is stored). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jenkins" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the Jenkins token

Stores the Jenkins URL, username and API token; all three are required in the body. The URL must be a valid `http` or `https` URL and must not point at loopback, link-local or private addresses (including hostnames that resolve to them), otherwise the call returns 400. The credentials are not tested against Jenkins before they are saved. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jenkins/token" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete the Jenkins integration

Removes the stored Jenkins URL, username and API token. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jenkins" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Ticketing, Chat and Generic Integrations

These endpoints connect and configure the ticketing systems (Jira, Linear, Asana) and chat platforms (Slack, Microsoft Teams) that Nullify files tickets and sends notifications to, list the users and teams of an integrated platform, and expose the generic connector catalog and connection lifecycle that is shared by every credential-based integration. Authenticate as described in [Authentication](/api-reference/api-reference/authentication). Source control and CI connections are on [Source control and CI integrations](/api-reference/api-reference/api-admin/integrations-source-control-and-ci), cloud connections on [Cloud integrations](/api-reference/api-reference/api-admin/integrations-cloud), and ticket creation and listing on [Ticketing](/api-reference/api-reference/api-admin/ticketing).

Every call is scoped to a workspace with a provider query parameter such as `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`. Which one you pass depends on how your tenant is connected. Reads require the `config:read` permission and changes require `config:write`, except the user and team lookups, which require `secret-config:read`.

## Connector catalog and generic lifecycle

Nullify keeps a registry of connectors, each identified by a `providerId` (for example `Slack`, `Jira`, `Wiz`) and a `capability` (for example `ticket`, `message`, `ci`, `package_registry`). The catalog tells you what exists and what each connector supports; the lifecycle operations below act on one `{providerId}/{capability}` pair. Which operations a connector supports is declared per connector in the catalog `lifecycle` object, and the API returns 501 for an operation the connector does not declare.

How a connector is connected depends on its `auth` value in the catalog:

* `api_token` connectors (for example GitLab with an access token, Wiz, Buildkite, Jenkins) are connected with the generic `connect` call.
* `oauth2` and `app_install` connectors have their own start-install or install flows. In the current registry the Jira, Linear, Slack and Teams ticketing and chat connectors fall here, so use the dedicated endpoints in the sections below rather than `connect`, which returns 400 for them.
* Connectors flagged `multiInstance` (for example private package registries and Azure DevOps organizations) can have several connections at once and are managed through the connection id endpoints rather than the `{providerId}/{capability}` ones, which return 400 for them.

### Get the integrations catalog

Returns every connector definition visible to your tenant, each annotated with this tenant's connection `status` (`not_connected` when nothing is connected), `externalId`, `lastVerifiedAt`, `lastError`, and, for multi-instance connectors, an `instanceCount` of connections that are not disconnected. The entry also carries the connector's `configSchema` (the field keys accepted by `connect`, `configure` and the connection calls, with `secret` fields marked) and its `lifecycle` flags. Connectors gated behind a feature flag appear only if the flag is enabled for your tenant, except that a connector you already connected is always listed. When a multi-instance connector has several connections the card reports the best one: connected first, then needs-attention, error, pending and disconnected. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/catalog" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Connect an integration

Connects a credential-based connector. Send `fields`, a map keyed by the connector's `configSchema` keys; unknown keys and missing required fields return 400, secret fields are encrypted and never returned, and non-secret fields are stored as the connection config. Calling it again for the same pair replaces the stored connection. The call stores the credential and marks the connection `connected` without probing the provider, so follow it with [Test an integration](#test-an-integration). Returns 404 for an unknown pair, 501 if the connector does not declare `connect`, and 400 for a multi-instance connector or one whose `auth` is not `api_token`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/connect" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% code overflow="wrap" %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"fields": {"apiToken": "<BUILDKITE_API_TOKEN>", "orgSlug": "my-org"}}' \
  'https://api.<TENANT>.nullify.ai/admin/integrations/Buildkite/ci/connect?githubOwnerId=1234'
```

{% endcode %}

### Configure an integration

Updates a connected integration. Only the keys you send in `fields` change: absent or blank values keep what is stored, including blank secret fields, so you can change a non-secret setting without re-sending the credential. Returns 400 if the pair is not connected, a key is unknown, or the connector is multi-instance, 404 for an unknown pair, 501 if the connector does not declare `configure`, and 409 if the connection changed while the update was being applied (read it again and retry). Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/configure" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Test an integration

Runs a connectivity check against the stored credential and returns `status`, `healthy` and `lastError`. A successful probe sets the connection to `connected` and records the verification time; a failed probe sets it to `needs_attention` and stores the error message. If nothing is connected the response is `not_connected` with `healthy` false, and a disconnected connection reports `disconnected`. Connectors that have no live check return the stored status unchanged without recording a verification. Returns 501 if the connector does not declare `test`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/test" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Disconnect an integration

Deletes the stored connection for the pair, including its stored secrets, and returns `disconnected: true`. It does not revoke the token at the provider, so revoke it there as well. Returns 501 if the connector does not declare `disconnect`, and 400 for a multi-instance connector (use [Disconnect a connection](#disconnect-a-connection)). Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/disconnect" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start a generic OAuth install

Returns an `authorizeUrl` for connectors that use the generic redirect OAuth flow; send the user's browser to it. Nullify stores a short-lived state token bound to your tenant and the pair, and finishes the connection on the provider callback. It returns 400 for connectors that do not use this flow (`api_token`, `app_install` and `cloud_role` connectors, and the Slack, Linear and Jira connectors, which have their own start endpoints below), and 412 until the OAuth app for that provider is configured for your deployment. No connector in the current registry uses this generic flow, so expect 400 today. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/install" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Multi-instance connections

Some connectors, such as private package registries, allow several connections at once. Create names the connector; every later operation names the connection by its `connectionId`, which is the `id` returned by create or [List connections](#list-connections). None of these calls ever return secret values.

### Create a connection

Creates an additional connection for a multi-instance connector. Send `fields` keyed by the connector's `configSchema` and an optional `displayName` to tell instances apart. Nullify validates the credential before storing it: a rejected credential returns 400 and nothing is stored, and a connector without live validation stores the connection as `pending` with no verification time. Returns 400 for a single-instance connector (use [Connect an integration](#connect-an-integration)) and 404 for an unknown pair. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/{providerId}/{capability}/connections" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List connections

Lists connection instances for your tenant, each with its `id`, status, non-secret config and `hasCredentials`. Use the `capability` query parameter (for example `package_registry`) to restrict the list. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/connections" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Test a connection

Runs a connectivity check on one connection and records the result. It returns `status`, `healthy` and `lastError` as for [Test an integration](#test-an-integration); a disconnected connection reports `disconnected` without probing. Returns 404 for an unknown or other tenant's `connectionId`, 409 if the connection changed during the test, and 501 if the connector does not declare `test`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/connections/{connectionId}/test" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Rotate a connection

Replaces the credential or config of one connection. As with configure, absent or blank `fields` keep their stored value. The merged result is validated first, and a failed validation returns 400 and leaves the stored credential untouched. Pass `expectedAuthorityRevision` (the `authorityRevision` you last read) to reject the rotation with 409 if the connection changed since; a disconnected connection returns 400 and must be replaced by creating a new connection. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/connections/{connectionId}/rotate" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Disconnect a connection

Disconnects one connection: Nullify blocks new credential use and destroys its stored secret but keeps non-secret metadata. The call is idempotent. The response reports `newLeasesBlocked`, `storedSecretDeleted`, `upstreamRevocationRequired` (whether you must still revoke the credential at the provider) and, for package registries, `maxOutstandingLeaseExpiry`, the time after which no already issued short-lived credential remains valid. Returns 404 for an unknown or other tenant's `connectionId`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/connections/{connectionId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Jira

Jira is connected through the Nullify Jira app (Atlassian Forge). Start the connection with [Start the Jira connect flow](#start-the-jira-connect-flow), check it with [Get Jira Forge connection status](#get-jira-forge-connection-status), then set the ticket defaults. To create and list tickets once connected, see [Ticketing](/api-reference/api-reference/api-admin/ticketing).

### Start the Jira connect flow

Returns an Atlassian authorization URL as `authorizeUrl`; send the user's browser to it to link their Jira site to your tenant. The state for the flow is bound to your tenant on the server, so the tenant is never taken from the callback. Returns 412 if Jira OAuth is not configured for your deployment. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jira/install" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Jira Forge connection status

Reports whether your tenant has a linked Jira Forge installation (`linked`) and, when linked, the Atlassian `cloudId` and `siteUrl`. Call it after the user returns from the connect flow. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jira/forge" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Jira configuration

Returns the saved Jira ticket defaults (project key, issue type, priority threshold, auto-create flag, enabled finding types and default assignee) under `configuration`. `enabled` is false, with no `configuration`, when Jira is not set up for the deployment or tenant, or when no defaults have been saved. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jira" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update Jira configuration

Creates or replaces the Jira ticket defaults. `projectKey`, `priorityThreshold`, `issueType`, `autoCreate` and `enabledFindingTypes` are required by the schema; `priorityThreshold` must be one of `URGENT`, `IMPORTANT`, `MEDIUM` or `LOW`, and `enabledFindingTypes` may contain only `sast`, `sca_dependencies`, `sca_containers`, `secrets_credentials`, `secrets_sensitive_data`, `cspm`, `scpm`, `dast_bughunt` and `dast_pentest` (an empty list means all of them). Invalid values return 400. `defaultAssigneeId` is a Jira account id: omit it to keep the saved value, send an empty string to clear it, and a non-empty id requires `projectKey` and is checked against the Jira project (bots are rejected). The call also updates your tenant's ticket auto-creation settings for Jira, and returns 404 if Jira is not configured for the deployment. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/jira" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Linear

Linear is connected with an OAuth install, after which you pick the team that tickets are filed in. A typical sequence is [Start the Linear install](#start-the-linear-install), poll [Get Linear install status](#get-linear-install-status), [List Linear teams](#list-linear-teams), then [Set Linear ticket configuration](#set-linear-ticket-configuration).

### Start the Linear install

Returns the Linear OAuth `authorizeUrl` for the Nullify Linear app; send the user's browser to it. A short-lived state token ties the callback to your tenant and the installing user. Returns 412 when the Linear app is not configured for the deployment. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear/install" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Linear install status

Reports whether the OAuth install is complete. `state` is one of `unavailable` (this deployment cannot run the install), `not_installed`, `installed`, `reconnect_required` (the stored authorization was revoked or expired, so run the install again) or `credentials_rejected`. `installed`, `installedAt`, `reconnectRequired`, `configured` and a human-readable `message` accompany it. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear/oauth" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Linear configuration

Returns the saved Linear ticket settings under `configuration` (`teamId`, `defaultAssigneeId`, `autoCreate`, `enabledFindingTypes`, `priorityThreshold`), plus `configUploaded` (true once a team is set). The response is empty when nothing has been saved. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List Linear teams

Lists the Linear teams (`id`, `name`, `key`) available to your tenant's Linear install, to choose the value for `teamId`. Returns 412 if Linear is not connected. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear/teams" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List Linear team members

Lists active members of a Linear team for assignee selection. `teamId` defaults to the configured team. Without `q` it returns the first page and sets `hasMore` if there are more members; with `q` (at most 100 characters) it searches name, display name and email. Returns 400 for an overlong `q` and 412 if Linear is not connected, no team is configured, or Linear rejected the install token (reconnect Linear). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear/members" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set Linear ticket configuration

Saves the Linear team and ticket defaults. `teamId` is required (400 if empty). `priorityThreshold` accepts `URGENT`, `IMPORTANT`, `MEDIUM` or `LOW`, and `enabledFindingTypes` uses the same finding type values as [Update Jira configuration](#update-jira-configuration), where an empty list means all types. `autoCreate` defaults to false, so automatic ticketing stays off until you set it. `defaultAssigneeId` (a Linear user id) follows the same omit, clear and validate rules as the Jira field. Also updates your tenant's ticket auto-creation settings for Linear and returns the saved `configuration`. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/linear/ticket-config" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Asana

### Get Asana install status

Returns `installed` and `installedAt` (the time the Asana configuration was last updated). Asana uses a personal access token rather than an OAuth flow despite the `/oauth` path, so `installed` is true once a token has been saved with [Set Asana ticket configuration](#set-asana-ticket-configuration). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/asana/oauth" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set Asana ticket configuration

Saves the Asana personal access token and the workspace and project that tickets are filed in. `accessToken`, `workspaceId` and `projectGid` are required (400 if any is empty); `workspaceName` is optional. The token is encrypted at rest and never returned; the response `configuration` lists only the workspace and project. The call also turns on Asana in your tenant's ticket auto-creation settings and, when the deployment has an Asana webhook address, attempts to register a task-completion webhook on the project. Webhook registration is best effort and does not fail the call. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/asana/ticket-config" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Slack

Slack is connected through the distributed Nullify Slack app: start the install, the user approves it in Slack, and Nullify links the workspace to your tenant. [Set the Slack API key](#set-the-slack-api-key) is the alternative for deployments that use their own Slack app token.

### Start the Slack install

Returns an `authorizeUrl` for the Nullify Slack app (OAuth v2); send the user's browser to it. A short-lived state token ties the callback to your tenant and the installing user. Returns 412 when the Slack app is not configured for the deployment. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/slack/install" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get Slack configuration

Reports whether Slack is set up (`enabled`) and whether the credential is healthy (`healthy`), with a `message` when it is not. Nullify checks the Slack app for the permissions it needs (reading users and listing channels), and if any is missing the message tells you to reinstall the app to grant them. The permission check is cached briefly, so a reinstall may take a short while to show as healthy. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/slack" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the Slack API key

Stores a Slack API key for the deployment and links the key's Slack workspace to your installation. `apiKey` is required (400 if empty). The key is saved first; the response `message` then says whether the key was verified and the workspace linked, and a verification failure still returns 200 with a message saying so, so read `message` rather than relying on the status code. The key is never returned. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/slack/key" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Notification routing

### Get notification configuration

Returns the notification rules for your tenant under `notifications`, each pairing event filters (for example severity, CWEs, CVEs and finding categories) with delivery targets. `centralSecurityChannel` is the fallback Slack or Teams channel for items routed to central security, and is absent if none is set. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/notifications" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Replace notification configuration

Replaces the whole notification rule list with the `notifications` you send, so include every rule you want to keep. `centralSecurityChannel` is optional: omit it to leave the saved channel unchanged. If supplied it must be a Slack channel with a channel id or a Teams channel with both `teamId` and channel id, otherwise the call returns 400. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/notifications" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Users and teams of an integrated platform

### List integration users

Lists the users of an integrated platform, selected with the required `provider` query parameter. Supported values are `GitHub`, `GitLab`, `Azure`, `Bitbucket`, `Jira`, `Slack`, `Teams`, `Okta`, `GoogleWorkspace` and `AzureEntra`; any other value returns 400. Use it to find the ids you need when mapping people to identities or choosing assignees. Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List integration teams

Lists the teams or groups of an integrated platform, selected with the required `provider` query parameter. Supported values are `GitHub`, `GitLab`, `Azure`, `Bitbucket`, `Okta`, `GoogleWorkspace` and `AzureEntra`; any other value returns 400. For source control providers, if the live lookup fails the call falls back to the teams Nullify has already synced (up to 1000) instead of failing. For the directory your own Nullify teams and members are managed in, see [Teams](/api-reference/api-reference/api-admin/teams) and [Users](/api-reference/api-reference/api-admin/users). Requires `secret-config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/integrations/teams" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Repositories, Pull Requests and Code

Operations for the repositories Nullify knows about, which of them are enrolled for scanning, pull request records, file contents from source control, and scan runs grouped by push or pull request. All calls use the tenant API URL and bearer token described in [Authentication](/api-reference/api-reference/authentication).

Unless noted otherwise, every operation on this page takes the provider scope query parameter that identifies your tenant, such as `githubOwnerId`, `azureOrganizationId`, `bitbucketWorkspaceId`, `gitlabGroupId` or `installationId`. Use whichever one matches your connected source control provider. For the other admin areas see [Users](/api-reference/api-reference/api-admin/users), [Teams](/api-reference/api-reference/api-admin/teams) and [Findings and metrics](/api-reference/api-reference/api-admin/findings-and-metrics).

## Repositories

### List repositories

Returns the repositories Nullify has synced for your tenant, decorated with finding counts, last scan time and languages. Use `search` to filter by repository name, `teamIDs` to restrict to repositories owned by given teams, and `includeArchived=true` to include repositories archived on the source platform (hidden by default). Page with `limit` and `nextToken` (or `offset`, which overrides `nextToken`); see [Pagination](/api-reference/api-reference/pagination). Requires the `config:read` permission. Callers whose access is limited to specific teams only see repositories for those teams.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% code overflow="wrap" %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/repositories?githubOwnerId=1234&limit=50'
```

{% endcode %}

## Scan scope

Scan scope controls which repositories, and which directories within them, Nullify scans. By default scoping is off and every repository is scanned. When scoping is on, only repositories enrolled for a scan family (code or secrets) are scanned for it. Repositories are identified by their canonical repository ID, the `id` returned by [List repositories](#list-repositories).

The code and secrets repository caps are set by Nullify per commercial agreement and are read-only through the API; contact Nullify to change them. The earlier enrollment routes (`PUT /admin/repositories/enrollment`, `POST /admin/repositories/enrollment/enroll-all`, `GET`/`PUT /admin/repositories/enrollment/limit`, `GET`/`PUT /admin/repositories/enrollment/scoping`, `POST /admin/repositories/initialize` and `POST /admin/repositories/uninitialize`) have been removed; use the operations below.

### Get scan scope

`GET /admin/scan-scope` returns the caps (`codeRepositoryCap`, `secretsRepositoryCap`; `null` means unlimited), how many repositories each family has enrolled, `scopingEnabled` and `secretsMode`. Requires `config:read`.

{% code overflow="wrap" %}

```bash
curl -s \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/scan-scope?githubOwnerId=1234'
```

{% endcode %}

### Update scan scope settings

`PUT /admin/scan-scope` takes `scopingEnabled: true` to turn scoping on (it cannot be turned off through the API) and/or `secretsMode`: `follow_code` (secrets scope equals code scope) or `independent` (repositories are enrolled for secrets separately). A change that would exceed a cap is refused with 412. Requires `config:write`.

### Update repository scan scopes

`PUT /admin/repositories/scan-scope` applies a delta of up to 100 repositories in `repositories`. Each entry names a `repositoryId` and any of `codeEnrolled`, `secretsEnrolled` (independent mode only), `codePaths` (`include`/`exclude` directory lists) and `secretsExcludes`. Repositories not listed are left untouched. Only repositories newly entering a family are charged against its cap; a breach returns 412 and nothing is written. An unknown repository ID returns 400. Repositories newly in scope get a default-branch scan. Requires `config:write`.

{% code overflow="wrap" %}

```bash
curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"repositories": [{"repositoryId": "<REPOSITORY_ID>", "codeEnrolled": true}]}' \
  'https://api.<TENANT>.nullify.ai/admin/repositories/scan-scope?githubOwnerId=1234'
```

{% endcode %}

### List repository directories

`GET /admin/repositories/{repositoryId}/directories?path=<dir>` lists the subdirectories one level below `path` (empty for the root) on the repository's default branch, for choosing directory rules. Requires `config:read`.

### Get repository proof-of-value recommendations

Returns the recommended set of repositories from the latest repo-scope scan: the smallest set that together demonstrates each Nullify capability (SAST, SCA, secrets, DAST, code-to-cloud, campaigns). Each entry carries per-capability fit scores, whether it is already enrolled (`isEnrolled`), and `uncoveredCaps` lists capabilities no repository could demonstrate. `scanId` and `generatedAt` are empty until a scan has run. This is read-only; enroll the repositories you accept with [Update repository scan scopes](#update-repository-scan-scopes). Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/repositories/recommendations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Pull requests

Pull request records are the pull requests Nullify opened or tracks for findings (for example autofix pull requests). The record `id` is Nullify's internal ID and is different from the pull request number on the provider.

### Query pull requests

Searches pull request records for your tenant. The JSON body takes a `query` object with optional filters `statuses`, `prTypes`, `findingIds`, `repositoryOwners`, `repositoryNames` and `prIdentifiers`, plus `page` and `pageSize`. Requires `finding:read`. Pull requests are not associated with teams, so callers whose access is limited to specific teams always receive an empty list.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/pullrequests" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a pull request record

Returns one record by its internal `id` (query parameter, required), usually taken from [Query pull requests](#query-pull-requests). Returns 404 when no record with that ID exists in your tenant. Requires `finding:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/pullrequests" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Refresh pull request CI

Re-reads CI check state from the source control provider for open or draft autofix pull requests and updates the stored records. Send up to 100 record IDs in `ids`. The response splits them into `refreshedIds`, `failedIds` (the provider call failed) and `rejectedIds` (unknown to your tenant, not open or draft, or missing repository details). Duplicate IDs are collapsed. The call is synchronous and does not change the pull request itself. Requires `finding:read`; more than 100 IDs returns 400.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/pullrequests/refresh-ci" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get pull request state

Fetches the live state of a pull request from the source control provider, including its changed files and hunks. Both `repositoryId` and `prId` are required query parameters (the provider repository ID and pull request number or ID, not a Nullify record ID). Returns 404 when the provider reports the pull request does not exist. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/getPullRequest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Files and ownership

### Get file contents

Reads a file from source control. `repositoryId`, `reference` (branch, tag or commit) and `filePath` are required; `projectId` applies to providers that need it. Add `startLine` (1-based) and optionally `endLine` to return only a line range; line endings are normalised to `\n`. `endLine` below `startLine` or a `startLine` past the end of the file returns 400, and a missing file returns 404. Requires `config:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/getFileContents" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get file owners

Resolves owners for file paths from the CODEOWNERS data Nullify has already cached for each repository and branch. The body is `{"files": [...]}` where each entry needs `id`, `repositoryName`, `branchName` and `filePath`. It reads cached data and does not fetch from your provider. Requires `config:read`. This endpoint may be deprecated, so avoid new dependencies on it.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/getFileOwners" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Scans

### List orchestrator scans

Lists scan runs grouped by orchestrator run: the per-scanner runs triggered by one push or pull request (repository, branch, commit and trigger) collapse into a single row with scanner counts, finding deltas (`newFindingsCount`, `fixedFindingsCount`, `reintroducedFindingsCount`, `liveFindingsCount`) and a `coverageStatus` of `complete`, `partial` or `unknown`. Filter with repeated `scanType` (`sast`, `sca_dependencies`, `sca_containers`, `secrets`), repeated `status` (`running_scan`, `running_results`, `completed`, `skipped`, `scan_failed`, `results_failed`, `stuck_failed`), and `from` and `to` as RFC3339 start times. Paginate with `limit` (default and maximum 100) and `offset`; the response returns `totalCount` rather than a `nextToken`. Invalid filter values return 400. Requires `finding:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/scans/orchestrator" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Context upload and triage census

### Get context upload credentials

Returns short-lived (one hour) AWS credentials scoped to write only under one storage prefix, for uploading infrastructure and delivery context for a repository, such as Terraform plans or CI logs. The body needs `contextType` (`terraform`, `ci_logs`, `config`, `deploy` or `api_spec`), `repository` in `org/repo` form and `name`; optional fields are `branch`, `environment` (`development`, `staging`, `production`, `unknown`; default `unknown`), `prNumber`, `fromPR` and `commitSha`. The response contains `credentials`, `bucket`, `keyPrefix` and `region`; upload objects under `keyPrefix` with those credentials, then they expire. Requests are rejected with 400 when a value is invalid or context ingestion is not configured for your deployment. This is mainly used by the Nullify CLI. Requires `config:write`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/context/ingest" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Post triage context census

Reports which of a set of findings were last triaged without organisation or repository context. Send up to 1000 IDs in `findingIds` (more returns 400). The response lists the `blind` subset with which context was missing, `requested` (how many IDs you sent) and `tenantSummary`, the tenant-wide per-finding-type shortfall. IDs that are absent from `blind` either had context or have no triage report. It is a read-only call despite using POST, and a transient database failure is reported as a retryable error. Requires `finding:read`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/triage/context-census" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Teams and Ownership

A team groups people and the repositories they own, and drives who findings are assigned to. These endpoints manage teams, control which sources create teams automatically, and map findings to teams. Authenticate as described in [Authentication](/api-reference/api-reference/authentication); people and roles are covered in [Users](/api-reference/api-reference/api-admin/users) and [Identity and Access](/api-reference/api-reference/api-admin/identity-and-access).

Every call is scoped to a workspace with a provider query parameter such as `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`. Which one you pass depends on how your tenant is connected; the call returns 400 when none resolves to a tenant.

Teams have a `source`: `github_teams`, `repository_property`, `atlassian_compass`, `identity_provider` or `manual`. Only manual teams can be created, edited freely and deleted through this API; teams from the other sources are maintained by their sync.

## Teams

### List teams

Returns a page of teams from every source, with lead and member details filled in. Filter with `search` (case-insensitive match on the team name) or `repositoryId` (only teams that own that repository). Page with `limit` (default 200, at most 1,000) and `nextToken`, or jump to a position with `offset`, which wins over `nextToken` when both are sent; see [Pagination](/api-reference/api-reference/pagination). A page is also cut short if it would exceed about 4 MiB serialized, so follow `nextToken` until it is empty rather than assuming a full page. `numItems` is the total number of matching teams. Requires `ConfigRead`.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/teams?githubOwnerId=1234&search=platform&limit=50'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a team

Returns one team by `teamID`, the `id` of a team from [List teams](#list-teams), with members, leads, repositories and code owner glob patterns filled in. Note the path is `/admin/team/{teamID}` (singular `team`). Returns 404 if the team does not exist in your workspace. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/team/{teamID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a manual team

Creates a team with source `manual`. `name`, `slug`, `privacy`, `messageChannelProvider` and `ticketProjectProvider` are required by the schema and `name` must be non-empty. A new team id is generated on every call, so repeating the call creates another team. `leadId` must be a Nullify user id from [Users](/api-reference/api-reference/api-admin/users) (400 otherwise); `memberIds` are not checked on create, so set members with [Update a team](#update-a-team), which validates them. Every `codeOwnerships[].dataSource` must be `manual`. `groundRules` need a non-empty `title` (up to 200 characters) and a `description` of up to 2,000 characters. Internal automation (agents) cannot send `codeOwnerships` and receives 403; a person's token can. Requires `TeamManage`.

Use `"messageChannelProvider":{"id":""}` when the team has no message channel.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"name":"Payments","slug":"payments","privacy":"private","messageChannelProvider":{"id":""},"ticketProjectProvider":{}}' \
  'https://api.<TENANT>.nullify.ai/admin/teams?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a team

Partially updates a team: only fields you send are changed, and an omitted field keeps its stored value. `groundRules` replaces the stored list, and an empty array clears it. `memberIds` is the complete member list: users you add become manual members that the provider sync keeps, users you leave out are removed and the sync does not add them back, an empty list removes everyone, and omitting `memberIds` leaves membership alone. `codeOwnerships` entries must have `dataSource` `manual`. The `github`, `gitlab` and `jira` objects are merged field by field. `leadId` and added members must be Nullify user ids (400 otherwise); an unknown `teamID` returns 404. Internal automation (agents) cannot send `memberIds` or `codeOwnerships` and receives 403. Changing members or code ownerships queues a background re-sync of finding-to-team mappings. Member and ownership edits are recorded in the audit log. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/{teamID}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a manual team

Soft-deletes a team whose source is `manual`. Teams from any other source return 400, because their sync owns them; to stop a synced source, turn it off with [Update team source preferences](#update-team-source-preferences). Deleting a team that is already deleted succeeds. An unknown `teamID` currently returns 500 rather than 404. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/{teamID}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Merge teams

Combines two or more provider teams into one. Send `sources` (at least two entries, each a `providerId` and `teamId`) and, optionally, `targetTeamId` to merge into an existing team; without it a new manual team is created. Member ids are unioned, code ownerships are appended, ground rules are unioned, and provider ids and message and ticket settings are copied where the target has none. A source that cannot be found is skipped rather than failing the call, and source teams are left in place. The merged team is returned. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/merge" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create or update a Compass team

Imports a team from Atlassian Compass. `displayName` is required, and `teamKey` (the Compass team key) and `providerId` are also required even though the schema does not mark them so; missing values return 400. `lead` and `members` are stored as users under the Jira provider using the strings you send as their name and username, and `repositories` accepts `owner/repo`, `owner/repo.git`, GitHub `tree` or `blob` URLs (the sub-path becomes a glob pattern) and `git@host:owner/repo` SSH forms. Repositories that are malformed or not installed in your connected GitHub app are skipped. A team with the same name under Jira is updated in place, otherwise `teamKey` becomes the team id; its Compass code ownerships are replaced with the ones you send. If you send no lead, members or repositories, nothing is created and the call returns 200 with no team. When the call changes the team's code ownerships or members, a background re-sync of finding mappings is started on a best-effort basis; re-sending an unchanged team starts none. Internal automation (agents) cannot send a lead, members or repositories and receives 403. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/compass" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Make a team the owner of a repository

Makes the team the only manual code owner of an entire repository. Send `repositoryId` in the body; it is a repository id from [Repositories and Code](/api-reference/api-reference/api-admin/repositories-and-code). Other teams' manual ownership of that repository is replaced in one transaction, ownership produced by a provider sync or a code owners file is untouched, and the manual ownership survives later syncs. Returns 404 if the team or repository does not exist in your workspace, and 403 for internal automation, which cannot make this change. A background re-sync of finding-to-team mappings is queued and the change is audit logged. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/{teamID}/code-ownership" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Download the Microsoft Teams app package

Despite its path, this is not part of team ownership: it builds the Microsoft Teams chat app package (manifest and icons) for your Nullify Teams bot, uploads it, and returns a time-limited `presignedUrl` for downloading the zip. Use it when installing the Nullify app in Microsoft Teams. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/appzip" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Team sources and sync

Teams are created automatically from GitHub Teams and from repository custom properties. These operations switch each source on or off, choose which repository properties define teams, and start or inspect sync runs.

### Get team source preferences

Returns whether the `github_teams` and `repository_property` sources are enabled. If preferences were never saved, both are enabled. Manual teams are always available and have no toggle. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/team-source-preferences" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update team source preferences

Sets `githubTeamsEnabled` and `repositoryPropertyEnabled`; both are required, so send the full state. Turning a source off hides every team from that source, and turning it back on restores them and starts a sync for that source. The response includes `syncQueued`, which is `false` when a sync was needed but could not be started; the daily sync then catches up. Concurrent updates for a tenant are serialized. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/team-source-preferences" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List repository property team keys

Lists the repository custom property names that this tenant uses to derive teams, one team per distinct property value. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/repository-property-team-keys" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a repository property team key

Adds a property name that defines teams. `providerId` and `propertyKey` are required (the key is trimmed and at most 256 characters). A key already configured for the provider returns 409. A repository-property sync is started in the background; poll [List team sync runs](#list-team-sync-runs) to follow it. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/repository-property-team-keys" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a repository property team key

Removes a property key, identified by the `keyId` query parameter (the `id` from [List repository property team keys](#list-repository-property-team-keys)). Returns 404 if it does not exist. Teams derived from that property that no longer own anything are cleaned up by the sync run this call starts. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/repository-property-team-keys" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List team sync runs

Returns recent team sync runs for your workspace, newest first. Filter with `source` (`github_teams`, `repository_property`, `manual`, `atlassian_compass` or `identity_provider`; anything else returns 400). `limit` defaults to 10 and is capped at 100. Each run has a `status`, `startedAt`, optional `completedAt` and `errorMessage`, and `triggeredBy`. Use it to see whether a sync you started is still running. Requires `TeamManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/team-sync-runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Trigger a team sync

Asks for a team sync run. Omit `source` to cover both `github_teams` and `repository_property`, or set it to one of those two; other sources return 400 because they cannot be synced on demand. If a run for that source is already pending or running, nothing new starts. The response lists the latest run for each requested source, so a success means a run was requested, not that it finished; poll [List team sync runs](#list-team-sync-runs). Requires `TeamManage`.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"source":"github_teams"}' \
  'https://api.<TENANT>.nullify.ai/admin/team-sync-runs?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/team-sync-runs" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Team findings

Findings are mapped to teams by matching repository ownership, code owners files and team membership, or by a manual assignment. Viewers who are limited to their own teams only see mappings and counts for teams they belong to.

### List findings mapped to every team

Returns each team with its mapped findings. The response is not paginated: it loads up to 1,000 teams and every mapping for each, so it can be large. Prefer [Get findings for a team](#get-findings-for-a-team). Requires `FindingRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get findings for a team

Returns one team and every finding mapped to it. For a team a team-scoped viewer does not belong to, you get the team with an empty findings list. An unknown `teamID` currently returns 500 rather than 404. Requires `FindingRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/{teamID}/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Assign findings to teams manually

Assigns findings to teams by hand. Send `mappings`, between 1 and 1,000 entries, each with `findingId`, `teamId` and `findingType`. A finding id may appear only once per request, every team must exist in your workspace, and finding types that cannot be assigned to teams are rejected with 400. The response reports `upserted`. Manual assignments are recorded as manual and audit logged. Requires `FindingWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/findings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Re-run finding-to-team matching

Runs the matcher that maps findings to teams. With no filters it covers the whole workspace; narrow it with `repositoryIds`, `repositoryNames`, `findingIds` or `findingTypes`. By default it runs inline and returns `matched` and `unmatched` counts; a very large tenant can get a partial result with a `message` explaining the cutoff. Set `async` to `true` to hand it to a background worker: the call returns immediately with `async: true` and `matched` and `unmatched` of `-1`, and there is no run id to poll, so check results with [Get findings for a team](#get-findings-for-a-team). Requires `FindingWrite`.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"async":true}' \
  'https://api.<TENANT>.nullify.ai/admin/teams/findings/sync?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/findings/sync" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get SLA breakdown by team

Given `findingIDs` (note the capitalization), returns for each team the number of those findings that are in SLA (`inSLA`) and out of SLA (`outOfSLA`). Teams with none of the findings, teams deleted since the mapping, and teams a team-scoped viewer cannot read are omitted; an empty list returns an empty result. This is a read-only operation sent as POST because of the body. Requires `FindingRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/sla-breakdown" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List events for a team

Returns the unified activity feed for one team. All body fields are optional filters: `services`, `excludeServices`, `findingIds`, `eventTypes`, `excludeEventTypes`, `autofixId`, `prCanonicalId`, `runId` and `campaignId`, plus a time window with `beforeTimeUnix` and `afterTimeUnix`. An unknown service name returns 400. `limit` defaults to 50 and is capped at 200. When `hasMore` is true the response includes `nextCursorTime` and `nextCursorId` for the next request; some internal services and event types are excluded by default. A team-scoped viewer asking for another team gets an empty list. Requires `FindingRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/teams/{teamID}/events" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Ticketing Workbench

These endpoints list and inspect the tickets Nullify has created or tracked in your ticketing platform, run bulk actions over them, save filter presets, and manage the per-finding-type settings that control automatic ticket creation. For connecting Jira, Linear or Asana in the first place, see [Ticketing, Chat and Generic Integrations](/api-reference/api-reference/api-admin/integrations-ticketing-and-chat). Authenticate as described in [Authentication](/api-reference/api-reference/authentication).

Every call is scoped to a workspace with a provider query parameter such as `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`. Which one you pass depends on how your tenant is connected. Every read and write is limited to your own tenant, and an id that belongs to another tenant returns 404.

Several operations record who acted from the caller's user identity (the `user-canonical-id` the platform derives from the credential). Where a section says "needs a user identity", a credential with no resolvable user is rejected with 400.

## Listing and inspecting tickets

### List tickets

Returns a page of tickets with a `total` count of everything matching the filter. Requires the `FindingRead` permission. All filters are optional query parameters; repeat a parameter to pass several values:

* `source`, `status`, `findingType` and `platform` take enum values. An unrecognized value returns 400.
* `boardId` matches the board or project a ticket lives on.
* `createdAfter`, `createdBefore`, `closedAfter`, `closedBefore`, `lastSyncedBefore` and `outOfEligibilitySinceAfter` take RFC 3339 timestamps.
* `hasSyncError` is `true`, `false` or empty.
* `q` is a case-insensitive substring match on the ticket title or the finding id.
* `limit` defaults to 50 and is capped at 200; `offset` defaults to 0. This endpoint pages with `limit` and `offset`, not `nextToken`; see [Pagination](/api-reference/api-reference/pagination).

Pass `savedFilterId` to load a filter you saved earlier (see [Saved filters](#saved-filters)). The saved filter replaces the individual filter parameters; any others on the same request are not applied on top. It needs a user identity, and a saved filter that belongs to another user returns 400 as not found.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/ticketing/tickets?githubOwnerId=1234&status=open&findingType=sast&limit=50'
```

### Get ticket facet counts

Returns counts for each of `source`, `platform`, `status` and `findingType` in one response, for building filter sidebars. Requires `FindingRead`. Only `source`, `status`, `findingType` and `platform` are accepted as filters. Each breakdown is computed with the other three filters applied but not its own, so a breakdown always shows the full spread of values for its dimension within the rest of the selection.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/counts" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a ticket

Returns one ticket by its internal ticket `id` (from [List tickets](#list-tickets)) together with its audit history, newest first, capped at 200 events. Requires `FindingRead`. Returns 404 if the id is not one of your tickets. The linked finding is not included; fetch it from the relevant findings endpoint using the ticket's `findingId` and `findingType`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/{ticketId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List ticketing activity

Returns the tenant-wide feed of ticket audit events: creations, closes, reopens, moves, bulk actions, settings changes and syncs. Filter with `eventType`, `actor` (`system`, `user`, `reconciler`, `webhook` or `manager_agent`), and `fromTime` and `toTime` (RFC 3339). Invalid values return 400. Pages with `limit` (default 50, maximum 200) and `offset`. Each entry carries `findingTicketId` when it relates to a specific ticket.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Saved filters

Saved filters are private presets. Each belongs to the user who created it, and every operation in this section needs a user identity. You can only list, change or delete your own.

### List saved filters

Returns the caller's saved filters, each with its `id`, `name` and the stored filter snapshot.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/saved-filters" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a saved filter

Saves a filter under a `name`. The `filter` has the same shape used by bulk actions (see [Bulk actions](#bulk-actions)). `name` must be non-empty. Returns the saved filter, including the `id` to use as `savedFilterId` on [List tickets](#list-tickets).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/saved-filters" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a saved filter

Renames a saved filter, replaces its filter, or both. At least one of `name` or `filter` must be supplied, otherwise the call returns 400. Returns 404 if the id is not one of your saved filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/saved-filters/{id}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a saved filter

Permanently deletes one of your saved filters and returns `deleted: true`. Returns 404 if it does not exist or is not yours. Deleting is not reversible.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/saved-filters/{id}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Bulk actions

Bulk actions change many tickets at once. They are asynchronous and always run in two steps, so nothing changes until you confirm.

1. **Dry run.** Send the action with `dryRun: true`. Nothing is changed. The response contains `dryRun.count` (how many tickets match), `dryRun.sample` (up to 25 of them) and `dryRun.confirmationToken`.
2. **Confirm.** Send the same action again with `dryRun` false (or omitted), the same `filter` and `params`, and the token in `confirmationToken`. The response contains `start.operationId` and returns immediately; the work continues in the background.

All bulk endpoints share one request body:

| Field               | Meaning                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter`            | Required. Which tickets to act on. All fields are optional: `sources`, `statuses`, `findingTypes`, `platforms`, `boardId`, `createdAfter`, `createdBefore`, `closedAfter`, `closedBefore`, `lastSyncedBefore`, `outOfEligibilitySinceAfter`, `hasSyncError`, `textSearch` and `ids` (specific ticket ids, to act on exactly the rows you picked). Timestamps are RFC 3339. |
| `dryRun`            | `true` to preview and obtain a confirmation token.                                                                                                                                                                                                                                                                                                                         |
| `confirmationToken` | The token from the dry run. Required to confirm.                                                                                                                                                                                                                                                                                                                           |
| `params`            | Action-specific parameters, listed under each action.                                                                                                                                                                                                                                                                                                                      |

Things to know before you confirm:

* The confirmation token is bound to the exact `filter` and `params` of the dry run. If either differs on confirm, the call returns 400. An unknown, already used, or other-action token also returns 400. A token can be confirmed only once.
* The filter is evaluated again when the work runs, not frozen at dry-run time. The previewed `count` is an estimate; tickets that start or stop matching in between are included or skipped accordingly.
* Required `params` are checked on confirm only, so a dry run succeeds without them.
* Confirming needs a user identity, which is recorded as the actor. Without one the call returns 400.
* Tickets are processed in pages of 100. Tickets an action cannot apply to (for example closing a ticket that is already closed) are skipped and are not counted as affected.
* A background job removes unconfirmed dry runs older than 24 hours; this is cleanup, not an exact expiry checked when you confirm. Once removed, the token returns 400 and you need a new dry run.
* Use the `operationId` with [Get bulk operation status](#get-bulk-operation-status) to follow progress.

### Close tickets

Closes every matching ticket that is not already closed or `wont_fix`. By default only automatically created tickets are included (sources `scan_pipeline`, `reconciliation` and `manager_agent`); set `params.includeManualSource` to `true` to include `rest_api` and `dashboard` tickets as well. `params.comment` is an optional comment. Tickets closed this way are recorded as closed by a user, which stops Nullify from automatically recreating them. `params.settingsOutOfScopeFindingType` is used by the settings-change cleanup: it closes only the auto-created tickets that the saved settings for that finding type now consider out of scope, and forces `includeManualSource` off. See [Save ticket settings](#save-ticket-settings).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-close" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Example dry run:

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"filter":{"findingTypes":["sast"],"statuses":["open"],"createdBefore":"2026-01-01T00:00:00Z"},"dryRun":true,"params":{}}' \
  'https://api.<TENANT>.nullify.ai/admin/ticketing/tickets/bulk-close?githubOwnerId=1234'
```

To confirm, repeat the call with `"dryRun":false` and `"confirmationToken":"<confirmationToken from the dry run>"`:

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"filter":{"findingTypes":["sast"],"statuses":["open"],"createdBefore":"2026-01-01T00:00:00Z"},"dryRun":false,"confirmationToken":"01J...","params":{}}' \
  'https://api.<TENANT>.nullify.ai/admin/ticketing/tickets/bulk-close?githubOwnerId=1234'
```

### Reopen tickets

Reopens closed or `wont_fix` tickets whose underlying finding is still unresolved. The filter's `statuses` is overridden to those two states. Tickets whose finding is already fixed, allowlisted, archived, a false positive, superseded or deleted are skipped. `params` is an empty object.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-reopen" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Move tickets to another board

Records a new board id on every matching ticket in Nullify. `params.targetBoardId` is required on confirm. This operation does not move tickets in the ticketing platform, and background reconciliation does not apply this board id there. Move the external tickets through the ticketing platform separately.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-move" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Re-sync tickets

Marks every matching ticket as stale so the next background drift sync refreshes it from the ticketing platform. It does not call the platform inline, so the refresh happens after the bulk operation reports `done`. `params` is an empty object.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-resync" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Reassign tickets to a team

Reassigns the underlying findings of matching tickets to `params.targetTeamId` as a manual team assignment, which later automatic team inference does not overwrite. Future automatically created tickets for those findings route to the new team's board. Requires the `FindingWrite` permission, and automated (service) callers are refused with 403, including on the dry run. `params.targetTeamId` is required on confirm and must be a team in your tenant; otherwise each ticket fails and is counted in `errorCount`. Get team ids from [Teams](/api-reference/api-reference/api-admin/teams).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-reassign-team" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Reassign ticket assignee

Stores `params.targetAssigneeEmail` (required on confirm) as the assignee on every matching ticket in Nullify. This operation does not update the assignee in the ticketing platform, and the daily drift sync does not push this field. Change the external assignee through the ticketing platform separately.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-reassign-assignee" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Add a comment to tickets

Writes the text in `params.comment` (required on confirm) to each matching ticket's audit record in Nullify. This operation does not post the comment to the ticketing platform, and no background sync delivers it. A ticket counts as affected once its audit record is written; if that write fails the ticket is counted in `errorCount`. Post external comments through the ticketing platform separately.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-add-comment" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Relabel tickets

Records requested label changes in each matching ticket's audit record in Nullify: `params.addLabels` and `params.removeLabels` are lists of label names, and at least one must be non-empty on confirm. This operation does not change labels in the ticketing platform, and no background sync delivers these changes. Update external labels through the ticketing platform separately.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-relabel" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set ticket priority

Stores `params.targetPriority` as the priority on every matching ticket in Nullify. It must be one of `URGENT`, `IMPORTANT`, `MEDIUM`, `LOW`, `INFORMATIONAL` or `NEGLIGIBLE` (checked on confirm; others return 400). This operation does not update priority in the ticketing platform, and background reconciliation does not push this field. Change external priority through the ticketing platform separately.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/tickets/bulk-set-priority" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Following and cancelling bulk operations

A confirmed bulk action returns `start.operationId` as soon as the work is accepted. It does not mean the work has finished. Poll the operation to follow it, and cancel it if you need to stop it. These two calls take the `operationId` as a path parameter and return `404` for an id that is not one of your tenant's operations.

### Get bulk operation status

Returns the operation: its `actionType`, `status`, `affectedCount`, `errorCount`, `startedAt`, `completedAt`, `cancellationRequestedAt`, and the filter and params snapshots it was started with. Poll this endpoint until `status` is terminal.

| `status`    | Meaning                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`   | A dry run created it and it has not been confirmed. This is the state of a confirmation token.                                                             |
| `running`   | Confirmed and being applied. `affectedCount` and `errorCount` are only final once the operation completes.                                                 |
| `done`      | Finished. `affectedCount` tickets were changed and `errorCount` failed. Skipped tickets are in neither count.                                              |
| `failed`    | Stopped early. Tickets changed before the failure stay changed. An operation whose worker shows no progress for more than an hour is also marked `failed`. |
| `cancelled` | Stopped after a cancel request.                                                                                                                            |

`done`, `failed` and `cancelled` are final; `completedAt` is set when the operation reaches one of them. Counts are written when the operation ends, so expect `affectedCount` and `errorCount` to read 0 until then. A `done` status with a non-zero `errorCount` means the run finished but some tickets failed; see [List ticketing activity](#list-ticketing-activity) for the per-ticket audit events, which carry the `bulk_operation_id` in their details. Per-ticket errors are not returned by this endpoint.

A sensible polling loop checks every few seconds and stops on `done`, `failed` or `cancelled`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/bulk-operations/{operationId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/ticketing/bulk-operations/01J...?githubOwnerId=1234'
```

### Request bulk operation cancellation

Asks a `pending` or `running` operation to stop. The call only records the request (`cancellationRequestedAt`) and returns the operation as it stands, usually still `running`. The worker checks for cancellation between pages of 100 tickets, then ends with status `cancelled`. Cancellation is therefore not immediate, and tickets already changed are not rolled back. If the worker reaches the last page before it notices, the operation can still finish as `done`, so keep polling until a final status appears. Cancelling an operation that is already `done`, `failed` or `cancelled` returns 404. The request is idempotent while the operation is active.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/bulk-operations/{operationId}/cancel" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Ticket settings

Ticket settings control, per finding type, whether Nullify creates tickets automatically and above what threshold. The `findingType` path parameter must be one of `sast`, `sca_dependencies`, `sca_containers`, `secrets_credentials`, `secrets_sensitive_data`, `cspm`, `scpm`, `dast_bughunt` or `dast_pentest`; anything else returns 400. See also [Configuration](/api-reference/api-reference/api-admin/configuration) and the [ticketing configuration guide](/configuration/configuration-ticketing).

### Preview ticket settings impact

Evaluates a proposed settings change against your current findings and tickets without saving anything. The body has a required `proposal` (see the embed for its fields, including `priorityThreshold`, `severityThreshold`, `defaultBoardId`, `teamRoutingEnabled` and the repository and CWE allow and block lists). The response gives the number of tickets that would be created, the number of existing tickets that would fall out of scope, breakdowns by board and source, and a sample of affected tickets. An invalid `priorityThreshold` returns 400.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/settings/{findingType}/preview" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Save ticket settings

Saves the settings for one finding type and writes a history entry with the previous and new values. Requires the `ConfigWrite` permission. `proposal.priorityThreshold` is required and must be valid. `proposal.unroutedBehavior` is `create_unrouted` (the default) or `skip`. `migrationAction` is `none` (default), `close_auto_created`, `close_all_out_of_scope` or `migrate_board`, and `userCanonicalId` in the body is recorded as who applied the change. Saving does not touch existing tickets: the `migrationAction` is only recorded. To clean up, run the matching [bulk action](#bulk-actions) afterwards, for example [Close tickets](#close-tickets) with `settingsOutOfScopeFindingType`. A `userCanonicalId` beginning with the prefix reserved for connector writes returns 400.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/settings/{findingType}" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List ticket settings history

Returns the saves for one finding type, most recent first, each with the old and new settings, `appliedBy`, `appliedAt` and `migrationAction`. Pages with `limit` (default 50, maximum 200) and `offset`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/ticketing/settings/{findingType}/history" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Users and Data Subject Requests

These endpoints list and look up the people known to your workspace, manage how each person maps to their Slack, Teams, Jira and Linear identities, control who has platform access, and handle GDPR data export and erasure for a user. Authenticate as described in [Authentication](/api-reference/api-reference/authentication); roles and teams are covered in [Identity and Access](/api-reference/api-reference/api-admin/identity-and-access) and [Teams](/api-reference/api-reference/api-admin/teams).

Every call is scoped to a workspace with a provider query parameter such as `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId` or `installationId`. Which one you pass depends on how your tenant is connected.

## Users

### Get the current user

Returns the identity mapping and username for the caller, resolved from the credential on the request. If the credential carries no resolvable user, or no mapping exists, the response contains only the username. Requires the `UserManage` permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/current" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List all users

Returns a merged directory of users across your Nullify accounts and the live git provider, Slack, Jira and Teams members. Each entry has a `source` (`nullify`, `git_provider`, `slack`, `jira` or `teams`) and, for synced Nullify accounts, a `role`. Only entries with source `nullify` have a stable Nullify user id and can be targeted by the role and activation endpoints. If the Slack, Jira or Teams lookup fails, the other sources are still returned. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create or update a user

Creates or updates a user record under the given provider. `user.provider.id`, `user.name`, `user.slug`, `user.username` and `user.isBot` are required by the schema and the call returns 400 if the provider id or name is empty or the user is otherwise invalid. A new Nullify user id is generated on every call, and the stored user is returned. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a user by Nullify user id

Returns one user by the Nullify user id (the `id` field returned by [List all users](#list-all-users)). Returns 404 if no such user exists in your workspace. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/{userID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List users for a provider

Returns users stored for one provider, for example `GitHub`. `providerID` is a path parameter. The response is a single page of up to 1,000 users with no `nextToken`, so very large directories are truncated. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/{providerID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a user by provider and provider user id

Returns one user by provider and the provider's own user id. Returns 404 if the user is unknown. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/{providerID}/{userID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a user by git identity

Resolves exactly one live account in your workspace from a native git provider user id (`providerID` and `providerUserID` path parameters). Returns 404 if none matches, 409 if the identity is ambiguous across legacy accounts, and 400 for an invalid identity. Operator-granted staff accounts are excluded. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/identity/{providerID}/{providerUserID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Activation and lifecycle

### Activate users

Grants platform access to users that are already synced into your workspace. Each entry in `users` needs a `userId` (a Nullify user id from [List all users](#list-all-users)), a `role`, and optional `teamIds`. Activation never creates accounts: if any target is not a synced user, nothing is changed and the call returns 404. The batch is applied atomically, and an invalid role returns 400. Requires `IdentityManage`, `UserManage` and `UserRoleAssign`. Changes are audit logged.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/activate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Deactivate a user

Marks a git-provider user who has left your company, but is still in the git organization, as deactivated. A deactivated user is skipped by routing and the unmapped-user sweep and cannot sign in. Send `userId` in the body. It must be called by a person with administrator permissions (`UserManage` and `UserRoleAssign`), not by an agent, and returns 409 if the user's lifecycle is managed by SCIM, so change it in your directory instead. Deactivating the last active administrator is refused with 400. The response returns `lifecycleState`. Reverse it with [Reactivate a user](#reactivate-a-user).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/deactivate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Reactivate a user

Restores a deactivated git-provider user to the active state. Takes the same body, permissions and error conditions as deactivation, and returns `lifecycleState` of `active`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/reactivate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## User mappings

A user mapping links one person's git account to their Slack, Microsoft Teams, Jira and Linear identities so that notifications, assignments and tickets reach the right person. Mapping ids are separate from Nullify user ids.

### List user mappings

Returns every user mapping in your workspace. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mappings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a user mapping

Returns the mapping for one identity. Pass `providerId` and `userId` as query parameters. If the identity is invalid or no mapping exists, the response is empty rather than an error. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mapping" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get mapping suggestions

Computes suggested mappings by matching users across your connected platforms. A platform that cannot be queried does not fail the call. It is listed in `unavailable`, so an empty suggestion list is distinguishable from a platform being down. Platforms not configured for your workspace are not reported. Nothing is saved. To persist suggestions, call [Create or update user mappings](#create-or-update-user-mappings) with `useSuggestions` set to true. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mapping/suggestions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create or update user mappings

Upserts mappings keyed on the git identity. Send `userMappings` and `useSuggestions` (both required by the schema). With `useSuggestions` true, the server computes and saves suggestions instead of using the supplied list. The response lists `userMappings` written, `skippedMappings` with reasons (for example an identity already mapped to another git user), and `unavailable` platforms. A person or the operator CLI overwrites identities already stored. Automated callers can only fill identities the mapping lacks, and never restore a chat account previously rejected for that git user. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mapping" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Edit a user mapping

Merges identities from the body into an existing mapping. `userId` in the path is the mapping id (the `id` field of a mapping), not a Nullify user id. An identity that is absent or sent with an empty id is left unchanged. Set `clearSlack` or `clearTeams` to clear those identities, which also records the cleared id as rejected so the daily automatic mapping does not restore it. The git account of a mapping cannot be changed (400). Returns 404 for an unknown mapping, 409 if an identity is already held by another mapping, and 403 if an automated caller attempts a clear. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mapping/{userId}" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a user mapping

Removes a wrong mapping. `userId` is the mapping id. By default the row is kept with its git identity, its Slack and Teams identities are emptied and the cleared ids are remembered as rejected. With `hard=true` the row is deleted outright, which is the right choice for offboarding or erasure, and the response then carries no mapping. Automated callers can only clear without rejecting, and `hard=true` is refused with 403. Requires `UserManage`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/user/mapping/{userId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Look up mappings in bulk

Read-only POST that returns, for a list of git canonical user ids, the mapped Slack, Jira and Teams canonical ids. Send ids in `gitCanonicalUserIds` (for example `GitHub#123`); `githubCanonicalUserIds` is deprecated. The response `users` object is keyed by the canonical id you sent. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/bulkSearchMappings" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Data subject requests

These endpoints support GDPR access, portability and erasure requests for one workspace user. Both require `UserManage` and write an audit log entry.

### Export a user's data

`GET /admin/users/{userId}/export?format=json` exports the user profile, team memberships, privacy acknowledgments, and audit-log entry count. Review the returned sections; this response is not a full export of every tenant finding, document, or external provider account. `userId` is the Nullify user id, and `json` is the only format. Returns 404 for an unknown user.

```bash
curl --get 'https://api.<TENANT>.nullify.ai/admin/users/<USER_ID>/export' \
  --header "Authorization: Bearer $NULLIFY_TOKEN" \
  --data-urlencode 'githubOwnerId=<OWNER_ID>' \
  --data-urlencode 'format=json'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/{userId}/export" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Erase a user

`DELETE /admin/users/{userId}/erasure` deletes the supported user records and memberships, removes privacy acknowledgments, and anonymizes supported audit references. It returns a report with counts of what was deleted and anonymized. This is destructive and runs in a single transaction: confirm the exact user and scope before invoking it. It is not tenant deletion, service-account token revocation, or deletion of data held by a connected provider. Erasure is refused with 400 if it would remove the last active administrator of a directory that requires Microsoft sign-in, and an unknown user returns 404. Identity-mapping cleanup runs after the transaction and is best-effort, so a failure there does not fail the request; contact support to verify a complete request where additional retained data or mappings are involved.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/users/{userId}/erasure" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Usage API

The customer-facing usage API lives under `/admin/metrics/usage`. It supports the dashboard's AI usage view. All three operations are read-only, are scoped to your tenant, and require the configuration read permission. Other admin metrics (findings, pull requests, tickets) are in [Findings, Events and Metrics](/api-reference/api-reference/api-admin/findings-and-metrics); the rest of the Admin API is indexed on [Admin](/api-reference/api-reference/api-admin).

| Endpoint                              | Use                                                               |
| ------------------------------------- | ----------------------------------------------------------------- |
| `GET /admin/metrics/usage/ledger`     | Inspect paginated per-run usage records.                          |
| `GET /admin/metrics/usage/aggregate`  | Aggregate cost and token totals by agent and class over a window. |
| `GET /admin/metrics/usage/timeseries` | Read daily or hourly cost and token buckets.                      |

Time parameters (`from`, `to`) are RFC 3339 timestamps; the aggregate and time series return `400` for an unparsable value. Keep the time range and the `agent` and `class` filters identical when comparing an aggregate with a time series. Recorded model usage is not necessarily the final invoice or your remaining entitlement; contact Nullify for billing terms.

## Usage ledger

Returns the per-run ledger entries for your tenant, one row per recorded agent run. Filter with `from`, `to`, `agent`, `class`, `branchType`, `runId`, and repeated `findingId` parameters to find the runs that spent usage on specific findings. Results are paginated: when the response includes `nextToken`, pass that value back as the `cursor` query parameter to fetch the next page. `limit` defaults to 50 when omitted. The request parameter is named `cursor` while the response field is `nextToken`; see [Pagination](/api-reference/api-reference/pagination) for the general pattern.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/usage/ledger" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/metrics/usage/ledger?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&limit=50'
```

## Usage aggregate

Returns cost (USD), run count, and input and output token totals grouped by agent and class. `window` is `DAY`, `WEEK`, `MONTH` (default), or `YEAR`, case-insensitive; any other value returns `400`. If you omit `to` it is the current time, and if you omit `from` it is 30 days before `to`. Optional `agent` and `class` filters narrow the groups. The response includes the `window` used and an `asOf` timestamp.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/usage/aggregate" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/admin/metrics/usage/aggregate?window=MONTH'
```

## Usage time series

Returns cost and token buckets over time. `granularity` is `day` (default) or `hour`; any other value returns `400`. As with the aggregate, `to` defaults to now and `from` defaults to 30 days before `to`. Optional `agent` and `class` filters apply. The response echoes the resolved `granularity`, `from`, and `to` along with the `buckets`. Hourly queries over long ranges return many buckets, so narrow the range for hourly data.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/admin/metrics/usage/timeseries" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Context API

The `/context` API connects code, cloud assets, application boundaries, dependencies, and organizational knowledge. See [Context Engine](/capabilities/context-engine) for how this data informs findings.

Authenticate as described in [Authentication](/api-reference/api-reference/authentication). Reads generally need the `ConfigRead` permission and anything that changes state or starts a job needs `ConfigWrite`; a few routes (some dependency routes, cloud scan status and cloud connector PR status) only require a valid tenant token. Operations that start work (scans, SBOM runs, report jobs, schema reversing) are asynchronous: a start response means the job was accepted, not that it finished, so poll the matching status call. Most list calls page with `nextToken` (see [Pagination](/api-reference/api-reference/pagination)); the dependency routes use `cursor`, and some cloud recon and SBOM routes use `limit`/`offset` or `page`/`pageSize`. Each guide states which applies.

## Guides in this section

* [Applications, repositories, and schemas](/api-reference/api-reference/context/applications-and-repositories): logical applications and their rebuilds, entrypoints, artifacts and deployments, CI/CD pipelines, repositories and projects, execution recipes, API schemas, and repository context and repo-scope scans.
* [Asset inventory](/api-reference/api-reference/context/asset-inventory): the unified and per-category inventory of cloud and code assets, plus deleting assets and editing their tags and flags.
* [Asset graph and infrastructure graphs](/api-reference/api-reference/context/asset-graph): graph search, subgraphs, reachability, attack paths, and versioned infrastructure graphs per cloud account.
* [Cloud scans and cloud recon](/api-reference/api-reference/context/cloud-recon): start cloud scans, run the cloud connector agent, and read cloud recon analysis (overview, hotspots, IAM posture, exposures, trust relationships).
* [Dependencies and SBOMs](/api-reference/api-reference/context/dependencies-and-sboms): active and historical dependency inventory, package exposure, commit diffs, and SBOM generation, replay and deletion.
* [Documents, memories, and reports](/api-reference/api-reference/context/documents-memories-and-reports): the document vault, memories, organization context, RAG resync, and asynchronous reports.

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                                                     | Operation                                                   |
| -------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `GET`    | `/context/applications`                                                                  | Get Applications                                            |
| `POST`   | `/context/applications`                                                                  | Create Application                                          |
| `POST`   | `/context/applications/rebuild`                                                          | Rebuild Applications                                        |
| `GET`    | `/context/applications/rebuilds/{runId}`                                                 | Get Application Rebuild                                     |
| `DELETE` | `/context/applications/{applicationId}`                                                  | Delete Application                                          |
| `GET`    | `/context/applications/{applicationId}`                                                  | Get Application                                             |
| `PATCH`  | `/context/applications/{applicationId}`                                                  | Update Application                                          |
| `GET`    | `/context/applications/{applicationId}/execution-recipe`                                 | Get Application Execution Recipe                            |
| `GET`    | `/context/applications/{applicationId}/schema`                                           | Get Application Schema                                      |
| `GET`    | `/context/artifact-deployments`                                                          | List Artifact Deployments                                   |
| `GET`    | `/context/artifact-deployments/{deploymentId}`                                           | Get Artifact Deployment                                     |
| `GET`    | `/context/artifacts`                                                                     | List Artifacts                                              |
| `DELETE` | `/context/artifacts/{artifactId}`                                                        | Delete Artifact                                             |
| `GET`    | `/context/artifacts/{artifactId}`                                                        | Get Artifact                                                |
| `GET`    | `/context/asset-graph/attack-paths`                                                      | List Asset Graph Attack Paths                               |
| `GET`    | `/context/asset-graph/landing`                                                           | Get Asset Graph Landing                                     |
| `GET`    | `/context/asset-graph/node`                                                              | Get Asset Graph Node                                        |
| `GET`    | `/context/asset-graph/nodes`                                                             | List Asset Graph Nodes                                      |
| `GET`    | `/context/asset-graph/reachability`                                                      | Get Asset Graph Reachability                                |
| `GET`    | `/context/asset-graph/retrieve`                                                          | Retrieve Asset Graph Nodes                                  |
| `GET`    | `/context/asset-graph/search`                                                            | Search Asset Graph                                          |
| `GET`    | `/context/asset-graph/subgraph`                                                          | Get Asset Graph Subgraph                                    |
| `GET`    | `/context/asset-graph/summary`                                                           | Get Asset Graph Summary                                     |
| `GET`    | `/context/asset-inventory`                                                               | List Asset Inventory                                        |
| `GET`    | `/context/asset-inventory/ai-ml`                                                         | List AI/ML Assets                                           |
| `GET`    | `/context/asset-inventory/ai-ml/{id}`                                                    | Get AI/ML Asset                                             |
| `GET`    | `/context/asset-inventory/artifact-repositories`                                         | List Artifact Repositories Assets                           |
| `GET`    | `/context/asset-inventory/artifact-repositories/{id}`                                    | Get Artifact Repositories Asset                             |
| `GET`    | `/context/asset-inventory/artifacts`                                                     | List Artifacts Assets                                       |
| `GET`    | `/context/asset-inventory/artifacts/{id}`                                                | Get Artifacts Asset                                         |
| `GET`    | `/context/asset-inventory/cdn-and-dns`                                                   | List CDN and DNS Assets                                     |
| `GET`    | `/context/asset-inventory/cdn-and-dns/{id}`                                              | Get CDN and DNS Asset                                       |
| `GET`    | `/context/asset-inventory/ci-cd`                                                         | List CI/CD Assets                                           |
| `GET`    | `/context/asset-inventory/ci-cd/{id}`                                                    | Get CI/CD Asset                                             |
| `GET`    | `/context/asset-inventory/cluster`                                                       | List Cluster Assets                                         |
| `GET`    | `/context/asset-inventory/cluster/{id}`                                                  | Get Cluster Asset                                           |
| `GET`    | `/context/asset-inventory/compute`                                                       | List Compute Assets                                         |
| `GET`    | `/context/asset-inventory/compute/{id}`                                                  | Get Compute Asset                                           |
| `GET`    | `/context/asset-inventory/connectivity`                                                  | List Connectivity Assets                                    |
| `GET`    | `/context/asset-inventory/connectivity/{id}`                                             | Get Connectivity Asset                                      |
| `GET`    | `/context/asset-inventory/container`                                                     | List Container Assets                                       |
| `GET`    | `/context/asset-inventory/container/{id}`                                                | Get Container Asset                                         |
| `GET`    | `/context/asset-inventory/data-pipeline`                                                 | List Data Pipeline Assets                                   |
| `GET`    | `/context/asset-inventory/data-pipeline/{id}`                                            | Get Data Pipeline Asset                                     |
| `GET`    | `/context/asset-inventory/database`                                                      | List Database Assets                                        |
| `GET`    | `/context/asset-inventory/database/{id}`                                                 | Get Database Asset                                          |
| `GET`    | `/context/asset-inventory/endpoints`                                                     | List Asset Inventory Endpoints                              |
| `GET`    | `/context/asset-inventory/endpoints/{id}`                                                | Get Asset Inventory Endpoint                                |
| `GET`    | `/context/asset-inventory/identity`                                                      | List Identity Assets                                        |
| `GET`    | `/context/asset-inventory/identity/{id}`                                                 | Get Identity Asset                                          |
| `GET`    | `/context/asset-inventory/load-balancer`                                                 | List Load Balancer Assets                                   |
| `GET`    | `/context/asset-inventory/load-balancer/{id}`                                            | Get Load Balancer Asset                                     |
| `GET`    | `/context/asset-inventory/messaging`                                                     | List Messaging Assets                                       |
| `GET`    | `/context/asset-inventory/messaging/{id}`                                                | Get Messaging Asset                                         |
| `GET`    | `/context/asset-inventory/network`                                                       | List Network Assets                                         |
| `GET`    | `/context/asset-inventory/network/{id}`                                                  | Get Network Asset                                           |
| `GET`    | `/context/asset-inventory/observability`                                                 | List Observability Assets                                   |
| `GET`    | `/context/asset-inventory/observability/{id}`                                            | Get Observability Asset                                     |
| `GET`    | `/context/asset-inventory/pipelines`                                                     | List Pipelines Assets                                       |
| `GET`    | `/context/asset-inventory/pipelines/{id}`                                                | Get Pipelines Asset                                         |
| `GET`    | `/context/asset-inventory/projects`                                                      | List Projects Assets                                        |
| `GET`    | `/context/asset-inventory/projects/{id}`                                                 | Get Projects Asset                                          |
| `GET`    | `/context/asset-inventory/public`                                                        | List Public Asset Inventory                                 |
| `GET`    | `/context/asset-inventory/repos`                                                         | List Repos Assets                                           |
| `GET`    | `/context/asset-inventory/repos/{id}`                                                    | Get Repos Asset                                             |
| `GET`    | `/context/asset-inventory/security`                                                      | List Security Assets                                        |
| `GET`    | `/context/asset-inventory/security/{id}`                                                 | Get Security Asset                                          |
| `GET`    | `/context/asset-inventory/serverless`                                                    | List Serverless Assets                                      |
| `GET`    | `/context/asset-inventory/serverless/{id}`                                               | Get Serverless Asset                                        |
| `GET`    | `/context/asset-inventory/storage-and-backup`                                            | List Storage and Backup Assets                              |
| `GET`    | `/context/asset-inventory/storage-and-backup/{id}`                                       | Get Storage and Backup Asset                                |
| `DELETE` | `/context/asset-inventory/{category}/{id}`                                               | Delete Asset                                                |
| `PATCH`  | `/context/asset-inventory/{category}/{id}/flags`                                         | Patch Asset Flags                                           |
| `PATCH`  | `/context/asset-inventory/{category}/{id}/tags`                                          | Patch Asset Tags                                            |
| `GET`    | `/context/cicd-pipelines`                                                                | List CI/CD Pipelines                                        |
| `DELETE` | `/context/cicd-pipelines/{pipelineId}`                                                   | Delete CI/CD Pipeline                                       |
| `GET`    | `/context/cicd-pipelines/{pipelineId}`                                                   | Get CI/CD Pipeline                                          |
| `POST`   | `/context/cloud-connector-pr/runs`                                                       | Start Cloud Connector PR Run                                |
| `GET`    | `/context/cloud-connector-pr/runs/{runId}`                                               | Get Cloud Connector PR Run                                  |
| `POST`   | `/context/cloud-connector-pr/runs/{runId}/approve`                                       | Create approved AWS connector draft PR                      |
| `GET`    | `/context/cloud-connector-pr/runs/{runId}/proposal`                                      | Review AWS connector proposal                               |
| `POST`   | `/context/cloud-connector-pr/runs/{runId}/recover`                                       | Recover unresolved connector publication                    |
| `GET`    | `/context/cloud-connector-pr/status`                                                     | Get Cloud Connector PR Status                               |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/cross-account-relationships`                  | Get Cloud Recon Cross-Account Relationships                 |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/discovered-nodes`                             | Get Cloud Recon Discovered Nodes                            |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/graph-gaps`                                   | Get Cloud Recon Graph Gaps                                  |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/hotspots`                                     | Get Cloud Recon Hotspots                                    |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/iam-posture`                                  | Get Cloud Recon IAM Posture                                 |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/network-exposures`                            | Get Cloud Recon Network Exposures                           |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/overview`                                     | Get Cloud Recon Account Overview                            |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/scans/latest`                                 | Get Latest Cloud Recon Scan                                 |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/security-boundaries`                          | Get Cloud Recon Security Boundaries                         |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/synthesis/latest`                             | Get Latest Cloud Recon Account Synthesis                    |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/topology`                                     | Get Cloud Recon Topology                                    |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/traffic-flows`                                | Get Cloud Recon Traffic Flows                               |
| `GET`    | `/context/cloud-recon/accounts/{accountId}/trusted-services`                             | Get Cloud Recon Trusted Services                            |
| `GET`    | `/context/cloud-recon/organization/synthesis/latest`                                     | Get Latest Cloud Recon Org Synthesis                        |
| `POST`   | `/context/cloud-recon/scans`                                                             | Persist Cloud Recon Scan                                    |
| `GET`    | `/context/cloud-recon/tenants/cross-account-trusts`                                      | Get Tenant Cloud Recon Cross-Account Trusts                 |
| `POST`   | `/context/cloud-scan/start`                                                              | Start Cloud Scan                                            |
| `GET`    | `/context/cloud-scan/{scanId}/status`                                                    | Get Cloud Scan Status                                       |
| `DELETE` | `/context/deps`                                                                          | Delete dependency data                                      |
| `GET`    | `/context/deps`                                                                          | List Tenant Wide Dependencies (Historical)                  |
| `GET`    | `/context/deps/active`                                                                   | List Tenant Wide Active Dependencies                        |
| `GET`    | `/context/deps/active/summary`                                                           | Tenant Wide Active Dependency Summary                       |
| `GET`    | `/context/deps/by-ref/{bomRef}`                                                          | Get Dependencies by Bom Ref                                 |
| `GET`    | `/context/deps/dependents/{bomRef}`                                                      | List Dependents of a Bom Ref                                |
| `GET`    | `/context/deps/exposure`                                                                 | Global package exposure by version filter (semver or hash)  |
| `GET`    | `/context/deps/repository/{repositoryId}/project/{projectId}/active`                     | List Active Dependencies                                    |
| `GET`    | `/context/deps/repository/{repositoryId}/project/{projectId}/at/{commit}`                | Dependencies at commit                                      |
| `GET`    | `/context/deps/repository/{repositoryId}/project/{projectId}/diff`                       | Dependency diff between two commits                         |
| `GET`    | `/context/deps/repository/{repositoryId}/project/{projectId}/exposure`                   | Project package exposure by version filter (semver or hash) |
| `GET`    | `/context/deps/repository/{repositoryId}/project/{projectId}/history`                    | Package exposure history (windows)                          |
| `GET`    | `/context/deps/without-lockfile`                                                         | List projects/repos without lockfiles                       |
| `GET`    | `/context/entrypoints`                                                                   | List Entrypoints                                            |
| `DELETE` | `/context/entrypoints/{entrypointId}`                                                    | Delete Entrypoint                                           |
| `GET`    | `/context/entrypoints/{entrypointId}`                                                    | Get Entrypoint                                              |
| `GET`    | `/context/infrastructure/graphs`                                                         | List Infrastructure Graphs                                  |
| `GET`    | `/context/infrastructure/graphs/info`                                                    | Get Infrastructure Graph Info                               |
| `GET`    | `/context/infrastructure/graphs/summary`                                                 | Get Infrastructure Graph Summary                            |
| `GET`    | `/context/infrastructure/graphs/{accountId}`                                             | Get Infrastructure Graph                                    |
| `GET`    | `/context/infrastructure/graphs/{accountId}/download`                                    | Get Infrastructure Graph Download URL                       |
| `GET`    | `/context/infrastructure/graphs/{accountId}/versions`                                    | List Infrastructure Graph Versions                          |
| `GET`    | `/context/infrastructure/graphs/{accountId}/versions/{version}`                          | Get Infrastructure Graph Version                            |
| `GET`    | `/context/k8s/collector-clusters`                                                        | List K8s Collector Clusters                                 |
| `GET`    | `/context/memories`                                                                      | Get Memories                                                |
| `POST`   | `/context/memories`                                                                      | Create Memory                                               |
| `GET`    | `/context/memories/document/{documentId}`                                                | Get Memories By Document                                    |
| `GET`    | `/context/memories/document/{documentId}/type`                                           | Get Memories By Document And Type                           |
| `POST`   | `/context/memories/grep`                                                                 | Grep Memories                                               |
| `POST`   | `/context/memories/search`                                                               | Search Memories                                             |
| `GET`    | `/context/memories/type`                                                                 | Get Memories By Type                                        |
| `DELETE` | `/context/memories/{memoryId}`                                                           | Delete Memory                                               |
| `GET`    | `/context/memories/{memoryId}`                                                           | Get Memory                                                  |
| `PATCH`  | `/context/memories/{memoryId}`                                                           | Update Memory                                               |
| `GET`    | `/context/memories/{memoryId}/findings`                                                  | Get Memory Findings                                         |
| `POST`   | `/context/memories/{memoryId}/retract`                                                   | Retract Memory                                              |
| `GET`    | `/context/memories/{memoryId}/versions`                                                  | Get Memory Versions                                         |
| `GET`    | `/context/organization`                                                                  | Get Organization Context                                    |
| `PATCH`  | `/context/organization`                                                                  | Update Classification of the Organization                   |
| `PUT`    | `/context/organization`                                                                  | Upsert Classification of the Organization                   |
| `GET`    | `/context/organization/runs/{runId}`                                                     | Get Organization Context Run                                |
| `POST`   | `/context/rag/resync`                                                                    | Resync RAG Vector Store                                     |
| `GET`    | `/context/repo-scans`                                                                    | List Repo Context Scans                                     |
| `POST`   | `/context/repo-scans`                                                                    | Create Repo Context Scan                                    |
| `GET`    | `/context/repo-scans/{scanId}`                                                           | Get Repo Context Scan                                       |
| `PATCH`  | `/context/repo-scans/{scanId}`                                                           | Update Repo Context Scan                                    |
| `POST`   | `/context/repo-scope/scans`                                                              | Start Repo-Scope Scan                                       |
| `GET`    | `/context/repo-scope/scans/{scanId}`                                                     | Get Repo-Scope Scan                                         |
| `POST`   | `/context/reports`                                                                       | Create Report Generation Job                                |
| `GET`    | `/context/reports/{jobId}`                                                               | Get Report Status                                           |
| `GET`    | `/context/repositories`                                                                  | Get Contexts of Repositories                                |
| `DELETE` | `/context/repositories/{repositoryId}`                                                   | Delete Repository                                           |
| `GET`    | `/context/repositories/{repositoryId}`                                                   | Get Repository                                              |
| `PATCH`  | `/context/repositories/{repositoryId}`                                                   | Update Repository                                           |
| `POST`   | `/context/repositories/{repositoryId}/execution-recipes/discover`                        | Start Repository Execution Recipe Discovery                 |
| `GET`    | `/context/repositories/{repositoryId}/projects`                                          | List Projects                                               |
| `DELETE` | `/context/repositories/{repositoryId}/projects/{projectId}`                              | Delete Project                                              |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}`                              | Get Project                                                 |
| `PATCH`  | `/context/repositories/{repositoryId}/projects/{projectId}`                              | Update Project                                              |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe`             | Get Project Execution Recipe                                |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe/validations` | List Project Execution Recipe Validations                   |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe/versions`    | List Project Execution Recipe Versions                      |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/schema`                       | Get Project Schema                                          |
| `POST`   | `/context/repositories/{repositoryId}/projects/{projectId}/schema`                       | Upload Project Schema                                       |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/schema/metadata`              | Get Project Schema Metadata                                 |
| `GET`    | `/context/repositories/{repositoryId}/projects/{projectId}/schema/raw`                   | Get Project Schema Raw File                                 |
| `POST`   | `/context/repositories/{repositoryId}/projects/{projectId}/schema/trigger`               | Trigger Project Schema Reversing                            |
| `POST`   | `/context/repositories/{repositoryId}/repo-context/trigger`                              | Trigger Repository Context                                  |
| `POST`   | `/context/sbomingestor/replay`                                                           | Compute Dependencies Repository/Project SBOM Ingest Replay  |
| `DELETE` | `/context/sboms`                                                                         | Delete SBOMs for tenant                                     |
| `POST`   | `/context/sboms/generate`                                                                | Generate SBOM                                               |
| `GET`    | `/context/sboms/repository/{repositoryId}/latest`                                        | Get Latest SBOMs for Repository                             |
| `GET`    | `/context/sboms/repository/{repositoryId}/project/{projectId}`                           | Get Repository/Project SBOMs                                |
| `POST`   | `/context/sboms/resolve`                                                                 | Get or generate SBOM                                        |
| `POST`   | `/context/sboms/runs`                                                                    | Start SBOM Run                                              |
| `POST`   | `/context/sboms/scan`                                                                    | Scan SBOM (get-or-generate)                                 |
| `GET`    | `/context/sboms/tree`                                                                    | Get SBOM key tree for tenant                                |
| `GET`    | `/context/schemas`                                                                       | List Schemas                                                |
| `GET`    | `/context/setup-recommendations/pentest-assessments`                                     | List assessment setup proposals                             |
| `POST`   | `/context/setup-recommendations/pentest-assessments/refresh`                             | Refresh assessment setup proposals                          |
| `POST`   | `/context/setup-recommendations/pentest-assessments/{recommendationId}/accept`           | Accept assessment setup proposal                            |
| `POST`   | `/context/setup-recommendations/pentest-assessments/{recommendationId}/dismiss`          | Dismiss assessment setup proposal                           |
| `GET`    | `/context/setup-recommendations/pentest-targets`                                         | List pentest target recommendations                         |
| `POST`   | `/context/setup-recommendations/pentest-targets/refresh`                                 | Refresh pentest target recommendations                      |
| `POST`   | `/context/setup-recommendations/pentest-targets/{recommendationId}/accept`               | Accept pentest target recommendation                        |
| `POST`   | `/context/setup-recommendations/pentest-targets/{recommendationId}/dismiss`              | Dismiss pentest target recommendation                       |
| `GET`    | `/context/spec-artifacts/{artifactId}`                                                   | Get Spec Artifact                                           |
| `GET`    | `/context/vault/document/{documentId}/text`                                              | Get Vault Document Text                                     |
| `POST`   | `/context/vault/file`                                                                    | Post Vault File                                             |
| `DELETE` | `/context/vault/file/{fileId}`                                                           | Delete Vault File                                           |
| `GET`    | `/context/vault/file/{fileId}`                                                           | Get Vault File                                              |
| `PATCH`  | `/context/vault/file/{fileName}`                                                         | Patch Vault File                                            |
| `GET`    | `/context/vault/files`                                                                   | Get Vault Files                                             |
| `GET`    | `/context/vault/files/list`                                                              | Get Vault Files List                                        |
| `POST`   | `/context/vault/index`                                                                   | Index Vault Files                                           |
| `POST`   | `/context/vault/onboard`                                                                 | Trigger Vault Onboarding                                    |
| `POST`   | `/context/vault/search`                                                                  | Search Vault Documents                                      |
| `POST`   | `/context/waf-allowlist-pr/runs`                                                         | Start WAF Allowlist PR Run                                  |
| `GET`    | `/context/waf-allowlist-pr/runs/{runId}`                                                 | Get WAF Allowlist PR Run                                    |
| `POST`   | `/context/waf-allowlist-pr/runs/{runId}/approve`                                         | Create approved WAF allowlist draft PR                      |
| `GET`    | `/context/waf-allowlist-pr/runs/{runId}/proposal`                                        | Review WAF allowlist proposal                               |
| `POST`   | `/context/waf-allowlist-pr/runs/{runId}/recover`                                         | Recover unresolved WAF allowlist publication                |
| `GET`    | `/context/waf-allowlist-pr/status`                                                       | Get WAF Allowlist PR Status                                 |


# Applications and repositories

Read and manage the code-side context Nullify builds for your tenant: logical applications, repositories, their projects, entrypoints, build artifacts and their cloud deployments, CI/CD pipelines, API schemas, and the repo-context scans that produce them. This page also covers execution recipes (proven build, test and run commands) and the repo-scope scan that recommends which repositories to scan. For the rest of the Context API see the [Context API overview](/api-reference/api-reference/context).

Every operation takes the provider scope query parameter for your integration (for example `githubOwnerId`), as described in [Authentication](/api-reference/api-reference/authentication). Reads need the `config:read` permission, which admin, editor and viewer roles have. Writes, deletes and anything that starts a run need `config:write`, which only the admin role has. Calls use that workspace's provider scope; take repository and project ids from its list operations. Missing-record responses are described per operation.

List calls use different paging contracts: `nextToken`, `offset`, or `page`. The paragraph for each operation says which one applies; see [Pagination](/api-reference/api-reference/pagination) for how to follow `nextToken`.

## Applications

An application is a logical grouping of components (projects) discovered by Nullify or created by you. Applications have an `origin`: those you create through the API are user-owned, and the rebuild below regenerates the discovered ones.

### List applications

Returns a page of your tenant's applications with `totalCount` for all pages. Page with `limit` (default and maximum 1000; out-of-range values are clamped, not rejected) and `offset`, and filter with `search`, a case-insensitive substring match on name and description.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create an application

Creates a user-owned application. `name` and `description` are required (a blank name or missing description returns `400`); `tags` are optional. The new application starts with no components and is returned with a generated id. It is stored immediately, with no background work.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get, update, and delete an application

`GET` returns one application by the `applicationId` from the list call, or `404` if it does not exist for your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/{applicationId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PATCH` changes only `name`, `description`, and `tags`; send at least one or you get `400`. Your edits are stored as user overrides separate from the Nullify-generated fields, so a later rebuild does not overwrite them. The response is the reloaded application.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/{applicationId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` is a soft delete. The application disappears from reads, and the row is kept as a tombstone so a later rebuild does not recreate it. Deleting an unknown id returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/{applicationId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Rebuild applications

Queues a regeneration of your tenant's discovered applications and returns `status: "started"` with a `runId` immediately; a response means the job was queued, not that it finished. Set `force` to `true` to run even when the worker would otherwise skip the rebuild (no input changed since the last one, the last rebuild finished within the minimum interval, or no organization context exists yet; the reason appears in `run.error` of the rebuild read). Poll the run with the next operation. A `503` means the rebuild queue is not available on your deployment.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/rebuild" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"providerOwnerId": "1234", "force": false}' \
  'https://api.<TENANT>.nullify.ai/context/applications/rebuild?githubOwnerId=1234'
```

### Get an application rebuild

Reports a rebuild started by the call above, using its `runId`. The `run` object carries `state` (`PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `SKIPPED`, and so on) and `terminal`; stop polling when `terminal` is true. `run.error` says why a skipped rebuild did nothing or a failed one ended. When the run has succeeded, `applications` lists what it stored. A rebuild that records no outcome within 30 minutes reads as `FAILED` ("rebuild never reported an outcome") unless its applications were stored. An unknown `runId` returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/rebuilds/{runId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an application schema

Returns one OpenAPI document (YAML) built by merging the OpenAPI schemas of the projects the application's components map to. Components of one project share its schema. Projects without a stored schema, or whose schema is GraphQL or gRPC, are skipped. When a project's schema could not be read, the document's `x-nullify-provenance` block sets `transientShortfall: true`, marking it as a partial read. Returns `404` if the application has no components or none of them has an OpenAPI schema. To get or supply the schema of a single project instead, see [Project schemas](#project-schemas).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/{applicationId}/schema" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Entrypoints

Entrypoints are the executable starting points Nullify discovers in a repository, such as a service main or a handler. They are inventory records and carry no credentials or test permissions.

### List entrypoints

Lists entrypoints for one repository. `repositoryId` is required (omitting it returns `400`). Optionally filter by `projectId` and `kind`, set `includeDeleted=true` to include soft-deleted rows, and page with `limit` (default and maximum 1000) and `nextToken`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/entrypoints" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get and delete an entrypoint

`GET` returns one entrypoint by `entrypointId` from the list call, or `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/entrypoints/{entrypointId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` soft-deletes the entrypoint; it then shows up only with `includeDeleted=true`. Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/entrypoints/{entrypointId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Artifacts and deployments

An artifact is a build output such as a container image or package that a project produces. A deployment links an artifact to the cloud resource that runs it, with a match method and confidence.

### List artifacts

Lists build artifacts. Filter by `repositoryId`, `projectId`, `type`, or `search`, include soft-deleted rows with `includeDeleted=true`, and page with `limit` (default 1000) and `nextToken` or `offset`. The response includes `totalCount`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/artifacts" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get and delete an artifact

`GET` returns one artifact by `artifactId`, or `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/artifacts/{artifactId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` soft-deletes the artifact and returns `404` for an unknown id.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/artifacts/{artifactId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List artifact deployments

Lists where artifacts run. Filter by `artifactId`, `repositoryId`, `cloudResourceId`, or `computeType`, include soft-deleted rows with `includeDeleted=true`, and page with `nextToken` and `limit` (maximum and default 1000). A malformed `nextToken` returns `400`. Each item carries the cloud provider, account, region, `isInternetFacing`, and how the match was made (`matchMethod`, `matchConfidence`), so treat low-confidence matches as hints.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/artifact-deployments" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an artifact deployment

Returns one deployment by `deploymentId` from the list call, or `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/artifact-deployments/{deploymentId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## CI/CD pipelines

Pipelines are the CI/CD workflow definitions found in your repositories. The list and read calls share the asset inventory store, so ids returned by the list work on the read and delete calls. Trigger, job, and step details are not populated on these summaries.

### List CI/CD pipelines

Lists pipelines. Filter by `repositoryId`, `projectId`, or `platform` (case-insensitive; an unrecognized platform returns `400`), include inactive pipelines with `includeDeleted=true`, and page with `limit` (default 1000) and `nextToken`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cicd-pipelines" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get and delete a CI/CD pipeline

`GET` returns one pipeline by `pipelineId`, or `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cicd-pipelines/{pipelineId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` soft-deletes the pipeline (it becomes inactive and is hidden unless `includeDeleted=true`). Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cicd-pipelines/{pipelineId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Repositories

A repository record holds the classification and context Nullify derived for one source repository. Where a path takes `repositoryId`, use the id from the list call. The read and trigger calls below also accept an `owner/repo` name, which is resolved through your git integration; a malformed name returns `400`, and a repository the platform does not have returns `404`.

### List repository contexts

Returns the context of each repository for your tenant, with `numItems` and `nextToken`. Page with `limit` and `nextToken`. The `sortBy` and `sort` parameters are accepted but the service lists in a fixed order, so do not rely on them.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/repositories?githubOwnerId=1234&limit=50'
```

### Get, update, and delete a repository

`GET` returns one repository's context, or `404`. Repository contexts can exceed the 6 MB synchronous response limit, so pass `preferUrl=true` to receive a presigned `url` to download the context from instead of an inline body; when no downloadable copy exists the inline record is returned. If the presigned URL cannot be generated the call fails with a retryable error rather than returning an empty result.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PATCH` updates the repository record; the only field it applies is `name`. It returns an empty body on success and `404` for an unknown id.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` permanently removes the repository's stored context record for your tenant (a hard delete, not a tombstone). It does not touch the repository in your git provider, and a later repo-context run can create the record again. Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Trigger repository context

Starts a repo-context run for one repository against the head of `branch` (the default branch when omitted) and returns a `runId` with the resolved `commitSha`. This starts a job; poll [Get a repo context scan](#get-and-update-a-repo-context-scan) with the `runId` as `scanId`. Optional body fields: `force` regenerates context even if the stored one is current; `pathPrefixes` and `subagents` restrict the run, are only valid on the default branch, and require a stored full context first (otherwise `400`). A full run needs your organization context to exist, otherwise the call fails with `412`. An unresolvable branch head also fails with `412`, and `404` means the repository is not visible to your installation. A `503` means the run could not be started on your deployment.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/repo-context/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"branch": "main", "force": false}' \
  'https://api.<TENANT>.nullify.ai/context/repositories/<REPOSITORY_ID>/repo-context/trigger?githubOwnerId=1234'

curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/repo-scans/<RUN_ID>?githubOwnerId=1234'
```

## Projects

A project is a buildable unit inside a repository, such as a service or package. Project routes live under a repository id.

### List projects

Lists the projects of one repository, with `limit`, `nextToken`, and `includeDeleted=true` to include soft-deleted projects.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get, update, and delete a project

`GET` returns one project, or `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PATCH` updates a project's `description`, `tags`, `metadata`, and the `isDeleted`/`deletedAt` markers. Invalid description, tags, or metadata return `400`; an unknown project returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`DELETE` soft-deletes the project and returns `404` for an unknown project.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Project schemas

A project schema is the API description (OpenAPI, Proto, or GraphQL) Nullify extracted for a project, or one you uploaded.

### List schemas

Lists the stored schemas for every project in your tenant, with type, format, size, and a presigned `downloadUrl` for each. There is no paging or filtering, the listing covers at most 10,000 non-deleted projects, and projects without a stored schema are omitted.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/schemas" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a project schema

Returns the schema body for one project with its `type` and `format`, or `404` when none has been stored yet.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/schema" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Upload a project schema

Stores a schema under the repository and project ids, replacing any existing one. The body requires `type`, `format`, and `content` (the schema text). Use ids from the list operations: upload does not verify that the project exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/schema" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get project schema metadata

Returns the schema's type, format, size in bytes, provenance, and a presigned `downloadUrl` without the body. `numEndpoints` is the number of operations the document declares: OpenAPI and Swagger operations, GraphQL SDL root fields, or gRPC methods. It is `0` for other schema types and for a document that cannot be counted; `provenance` says whether code confirmed them. Returns `404` when no schema is stored.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/schema/metadata" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the raw project schema file

Returns a presigned `downloadUrl`, `contentType`, and suggested `fileName` for the original spec file, ready to import into a viewer. Returns `404` when no schema is stored.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/schema/raw" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Trigger project schema reversing

Starts a schema-reversing run for one project against the repository's stored repo context and returns a `runId`, `commitSha`, and `branch` (optional body field, default branch when omitted). It starts a job; poll [Get a repo context scan](#get-and-update-a-repo-context-scan) with the `runId`. The call has the same `404`, `412` (head unresolved) and `503` outcomes as repo-context trigger, and `404` if the project is not in that repository.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/schema/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Execution recipes

An execution recipe is a set of setup, build, test, and run commands that Nullify proved inside a sandbox with no credentials. Recipes are only ever safe to run in a sandbox. Reading a recipe is always available; starting discovery depends on the feature being enabled for your tenant.

### Start repository execution recipe discovery

Queues a validation run for each project of the repository (limit it with `projectIds`) and starts the sandbox pipeline at the head commit of `branch` (default branch when omitted). The response gives `runId`, `commitSha`, `mode`, `queued` targets, and `refused` targets with reasons. Asking again for the same projects at the same commit attaches to the run already in progress (`alreadyStarted: true`). `503` is returned when execution recipes are not enabled for your tenant or the pipeline is unavailable, and `412` when the branch head cannot be resolved.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/execution-recipes/discover" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a project execution recipe

Resolves what to run to stand a project up at a commit, or why nothing can be served. Pass `commitSha`, or an `inputHash` of your own checkout when Nullify has never seen the commit. Describe your sandbox with `docker=true` and `capabilities` (comma separated, for example `docker_compose,network,service_postgres`), and set `allowEdits=false` if you will not apply file edits a recipe carries (it then returns `incompatible` instead of such a recipe). The `resolution.status` is one of `valid`, `stale_with_last_known_good`, `incompatible`, or `unavailable`; an unknown capability name returns `400`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/repositories/<REPOSITORY_ID>/projects/<PROJECT_ID>/execution-recipe?githubOwnerId=1234&commitSha=<COMMIT_SHA>&docker=true'
```

### List project execution recipe versions

Lists a project's recipe versions, newest first, without their commands. Page with `limit` (default 50, maximum 200) and `offset`. To read the commands of a version, use the resolve call above.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe/versions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List project execution recipe validations

Lists the discovery and revalidation runs for a project's recipe, newest first, including their cost and failure reasons. Page with `limit` (default 50, maximum 200) and `offset`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repositories/{repositoryId}/projects/{projectId}/execution-recipe/validations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an application execution recipe

Resolves a recipe for a whole application, with the same query parameters and response as the project call. An application whose components span more than one repository has no single recipe target and returns `400`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/applications/{applicationId}/execution-recipe" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Repo context scans

A repo context scan records one context run against a repository at a commit. The platform writes these when you trigger a run; the create and update calls let a client that runs the analysis itself record the same lifecycle.

### List repo context scans

Lists scans, newest first, with `page` and `pageSize`. Filter by `repositoryId`, `commitSha` (requires `repositoryId`; returns that commit's latest scan only), and `status` (not combinable with `commitSha`). `versionsOnly=true` (requires `repositoryId`, no `status` or `page`) returns the repository's context version history, capped by `pageSize`. Invalid combinations return `400`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scans" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a repo context scan

Records the start of a run: `repositoryId` and `commitSha` are required, and `branch`, `status`, `subagentsRun`, `projectsTouched`, and `sbomsGenerated` are optional. It creates a record only; it does not start analysis (use the trigger calls to start one). The persisted scan, with its generated id, is returned.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scans" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get and update a repo context scan

`GET` returns the scan and its lifecycle as a run (`run.state`, `run.terminal`), so it is the call to poll after a trigger. A triggered run whose execution ended without recording an outcome is reported as failed. Returns `404` for an unknown id.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scans/{scanId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

`PATCH` updates `status`, `completedAt`, `subagentsRun`, `projectsTouched`, `sbomsGenerated`, and `errorMessage` on an existing scan; an invalid status returns `400`, long error messages are truncated, and an unknown id returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scans/{scanId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Repo-scope scans

A repo-scope scan classifies the repositories your integration has granted for scan scope and recommends which to include. It is advisory: it changes no enrollment, and the result is for a person to confirm.

### Start a repo-scope scan

Starts an asynchronous scan and returns `scanId`, `executionArn`, and `statusCode: 202` right away. Set `includeArchived=true` to include archived repositories (default is active only). Keep both `scanId` and `executionArn` for polling.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scope/scans" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a repo-scope scan

Reports a scan by `scanId`. Pass the `executionArn` from the start call as a query parameter so a failed execution is reported as `FAILED` rather than staying `RUNNING`; an `executionArn` that does not belong to this scan returns `400`. Once its recommendations are current, the response adds `recommendedCount`, `uncovered`, and `generatedAt`. `supersededBy` names the later scan that replaced this one's recommendations.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/repo-scope/scans/{scanId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Asset graph and infrastructure graphs

The asset graph is the merged, tenant-wide graph of cloud resources, Kubernetes objects, applications, and repositories that Nullify builds from its context collection. Use these operations to explore it, check network reachability, read stored attack paths, and download the per-account infrastructure graphs behind it. All operations are read-only `GET` calls and require the config-read permission. Authenticate as described in [Authentication](/api-reference/api-reference/authentication); the list-style operations below use `limit`/`offset` or `maxResults` rather than `nextToken` (see [Pagination](/api-reference/api-reference/pagination) for the rest of the API).

A missing node or relationship can mean incomplete collection, not isolation. Node IDs are opaque strings: get them from the landing, nodes, search, or retrieve operations and pass them back unchanged.

## Explore the graph

### Get the graph summary

Returns one summary of everything the asset graph is built from: the per-account infrastructure graphs (with presigned download URLs), the per-repository context graphs, node and edge totals for the merged graph, accounts that failed to collect, and a presigned URL for the merged graph export once it has been written. Infrastructure counts and accounts are limited to cloud accounts your tenant owns, and the combined infrastructure URL is not returned. Presigned URLs expire; each carries an expiry timestamp, so fetch the summary again instead of caching links.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/summary" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the landing page data

Returns the data behind the explorer landing view: per-kind node counts, entry-point cards for cloud accounts, Kubernetes clusters, applications (applications, products, and projects), and repositories, the ID of the internet node when one exists, and total node and edge counts. `perCategory` sets how many cards come back for each category (default 12, maximum 50). A category that fails to load is returned empty rather than failing the call.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/landing" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List nodes by kind

Returns a name-ordered page of nodes for one or more kinds. `kinds` is required and every value must be a valid node kind; an unknown kind, or no kind at all, returns 400. Page with `limit` (default 50, maximum 200) and `offset`; `total` in the response is the overall match count. Set `childCounts=true` to include each node's direct child counts, which is slower.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/nodes" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a node

Returns one node with its direct child counts by kind and its full stored payload. `nodeId` is required and comes from a nodes, search, or retrieve call. Returns 404 when the node is not in your tenant's graph.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/node" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Search the graph

Finds nodes whose name matches a text query. `q` is required and must be at least 3 characters. `objectTypes` narrows the search to node kinds (an unknown kind returns 400) and `maxResults` caps the result count (default 20, maximum 100). Each result gives the node ID, kind, name, subtitle, account, and region; follow up with the node or subgraph operations.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/search" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Retrieve nodes by meaning

Runs a hybrid semantic and keyword search and returns ranked nodes with a score and a compact text rendering of each. Use it for natural-language questions such as "public buckets in the payments account", where [Search the graph](#search-the-graph) needs a name. `q` must be at least 3 characters after trimming, and `maxResults` defaults to 10 with a maximum of 50.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -G 'https://api.<TENANT>.nullify.ai/context/asset-graph/retrieve' \
  --data-urlencode 'q=internet-facing databases' \
  --data-urlencode 'maxResults=10'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/retrieve" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a subgraph

Extracts the neighborhood around a root node. `rootNodeId` is required. `depth` defaults to 1 and is clamped to 5; `maxNodes` defaults to 150 and is clamped to 1000. Optional `objectTypes` and `edgeTypes` filter what is traversed (unknown values return 400). The response separates hierarchy edges (containment) from lateral edges (connectivity), reports total children overall and by type, and sets `truncated` when `maxNodes` clipped the result. A negative `depth` or a non-positive `maxNodes` returns 400.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/asset-graph/subgraph?rootNodeId=<NODE_ID>&depth=2&maxNodes=200'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/subgraph" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Exposure analysis

Attack paths and reachability answer different questions. An attack path is stored evidence from the last graph rebuild; reachability is computed on request over the current graph.

### List attack paths

Returns the internet-to-target attack paths stored by the last graph rebuild, with the node IDs and edge types along each path, the highest finding severity on it, and when it was computed. Filter with `terminalNodeKind` (a valid node kind; otherwise 400) and `hasCriticalFinding` (`true` or `false`). Page with `limit` (default 50, maximum 200) and `offset`. `truncated` is true when the rebuild hit its path limit, so the list may be incomplete. Paths are only as fresh as the last rebuild.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/attack-paths" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get network reachability

Computes whether the Internet can reach a target node, using the node's neighborhood in the graph and evaluating security groups, network ACLs, route tables, and load-balancer listeners, with CloudFront and API Gateway handled at the distribution layer. `nodeId` is required. `port` defaults to 443 when omitted or `0` and must be 0 to 65535; `protocol` is `TCP` (default), `UDP`, `ICMP`, or `ALL`, case-insensitive. A node that is not in the graph returns 200 with `targetNodeFound` set to false rather than 404. The response lists each path found and sets `truncated` when the search was cut short, in which case treat a negative answer as unproven.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-graph/reachability" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Infrastructure graphs

Infrastructure graphs are the per-AWS-account resource graphs that feed the asset graph. Each account has a latest graph plus stored versions. Operations that take `{accountId}` return 404 for an account that does not belong to your tenant, so an ID you cannot see looks the same as one that does not exist. Get account IDs from [List infrastructure graphs](#list-infrastructure-graphs).

### List infrastructure graphs

Lists the latest graph for each of your tenant's cloud accounts, with graph ID, version, node and edge counts, region, graph type, who generated it and when, tags, and last-modified time. Graphs for accounts outside your tenant are filtered out.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the infrastructure graph summary

Returns per-account graph entries with presigned download URLs, totals, failed accounts, and an `integrationStatus` of `ready` once at least one graph exists or `pending` otherwise. Pending is a normal state before the first cloud collection finishes, not an error. Totals and entries are limited to your tenant's accounts and the combined-graph URL is not returned; use the per-account URLs.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/summary" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get infrastructure graph info

Returns metadata for your tenant's infrastructure graphs: per-account node and edge counts and graph metadata. Tenant-wide node, edge, and cross-account statistics are intentionally returned empty. Returns 404 when none of your tenant's accounts have a graph yet.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/info" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an infrastructure graph

Returns the full latest graph for one AWS account as JSON. These documents can be large; for big accounts prefer [Get an infrastructure graph download URL](#get-an-infrastructure-graph-download-url). Returns 404 when the account is not yours or has no graph.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/{accountId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an infrastructure graph download URL

Returns a presigned `downloadUrl` and its `expiresAt` for the account's latest graph. Download it before expiry; request a new URL if it has lapsed. Returns 404 when the account is not yours or no graph exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/{accountId}/download" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List infrastructure graph versions

Lists the stored version identifiers for an account's graph, with a count. Use a returned identifier with the next operation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/{accountId}/versions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an infrastructure graph version

Returns the full graph for one stored version, for comparing how an account changed over time. Returns 404 when the account is not yours or the version does not exist.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/infrastructure/graphs/{accountId}/versions/{version}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Kubernetes collectors

### List Kubernetes collector clusters

Lists in-cluster Kubernetes collectors that are feeding your asset inventory but have no cluster registered through the admin API. Only collectors that completed a scan in the last 7 days are included. Each entry gives the cluster name (empty when no node names it), the collector's scan identity, the latest completed scan ID and its completion time, and record counts by category when available. Use it to find clusters sending data that you have not registered.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/k8s/collector-clusters" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Asset inventory

The asset inventory is the tenant-wide catalogue of cloud resources and repository-derived assets that Nullify has discovered: hosts, databases, identities, repositories, build artifacts and so on. These routes list and read assets, show the internet-exposed subset, and let you correct an asset's tags, exposure flags or active state.

All routes are under `/context/asset-inventory`. Reads need the config-read permission and writes need config-write. Every query is scoped to your tenant.

## How the inventory is organised

Assets are grouped into 22 categories. Each category has its own list route (`/context/asset-inventory/<category>`) and detail route (`/context/asset-inventory/<category>/{id}`). The category in a URL path is the kebab-case form shown below. The unified routes and the `{category}` path parameter on write routes accept either the kebab-case form (`cdn-and-dns`) or the snake\_case form (`cdn_and_dns`); the `category` query parameter on the unified list is documented in the spec as snake\_case.

| Category path           | What it holds                                                                                                                          | Extra list filters                                           |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `compute`               | EC2, GCE, Azure VMs, Kubernetes nodes and similar hosts                                                                                | none                                                         |
| `container`             | ECS services and tasks, Kubernetes Deployments, Pods, StatefulSets and DaemonSets, Cloud Run, Azure ACI and App Service                | none                                                         |
| `cluster`               | EKS and ECS clusters, GKE, AKS                                                                                                         | none                                                         |
| `serverless`            | Lambda, Step Functions, App Runner, Cloud Functions, Azure Functions                                                                   | none                                                         |
| `network`               | VPCs, subnets, gateways, route tables, Elastic IPs, VPC endpoints                                                                      | none                                                         |
| `connectivity`          | VPN connections, Direct Connect, ExpressRoute, PrivateLink, Transit Gateway attachments                                                | none                                                         |
| `load-balancer`         | ALB/NLB/CLB, target groups, Kubernetes Services and Ingresses, Azure Application Gateway, GCP load balancers                           | none                                                         |
| `cdn-and-dns`           | CloudFront, Route 53, API Gateway, GCP and Azure CDN and DNS, Front Door                                                               | none                                                         |
| `storage-and-backup`    | S3, EBS, EFS, Backup vaults, Storage Gateway and the GCP and Azure equivalents                                                         | none                                                         |
| `database`              | RDS, DynamoDB, Redshift, Neptune, ElastiCache, OpenSearch, GCP Spanner, BigQuery and Firestore, Azure SQL and Cosmos DB                | none                                                         |
| `messaging`             | SQS, SNS, Kinesis, EventBridge, SES, GCP Pub/Sub, Azure Service Bus and Event Hubs                                                     | none                                                         |
| `data-pipeline`         | Glue, EMR, Athena, Dataflow, Dataproc, Data Factory, Databricks                                                                        | none                                                         |
| `identity`              | IAM users, roles, groups and policies, Cognito user pools, Kubernetes service accounts and roles                                       | none                                                         |
| `security`              | security groups, NACLs, WAF, KMS, Secrets Manager, ACM, GuardDuty, Config, CloudTrail                                                  | none                                                         |
| `observability`         | CloudWatch log groups, alarms and dashboards, X-Ray, Stackdriver, Azure Monitor                                                        | none                                                         |
| `ci-cd`                 | CodeBuild, CodePipeline, CodeCommit, CodeDeploy, GCP Cloud Build, Azure DevOps Pipelines                                               | none                                                         |
| `ai-ml`                 | SageMaker endpoints, Bedrock models, Vertex AI endpoints, Azure OpenAI deployments, Azure ML workspaces                                | none                                                         |
| `repos`                 | source-code repositories (GitHub, GitLab, Bitbucket, Azure Repos)                                                                      | `accountId` and `region` are rejected                        |
| `projects`              | per-path application units inside a repository                                                                                         | `repoId`; `accountId` and `region` are rejected              |
| `artifacts`             | build artifacts (Docker images, JARs, wheels, npm packages, executables)                                                               | `projectId`; `accountId` and `region` are rejected           |
| `pipelines`             | CI/CD pipelines defined in repositories (GitHub Actions, GitLab CI, Jenkins, CircleCI, Buildkite, Azure Pipelines)                     | `repoId`, `projectId`; `accountId` and `region` are rejected |
| `artifact-repositories` | container and package registries; the same category holds cloud-scan records (for example ECR) and repository-derived registry records | none                                                         |
| `endpoints`             | HTTP and RPC endpoints discovered on hosts (a sub-resource, not one of the 22 categories)                                              | `hostCategory`, `hostId`, `awsService`, `sourceType`, `q`    |

### Shared list behaviour

* **Filters.** Every per-category list accepts `subType`, `provider`, `accountId`, `region`, `active`, `publicFacing`, `internetReachable`, `limit` and `nextToken`, plus the tenant-scope parameters shown in the spec. An invalid `subType` or `provider` value returns `400`. `subType` values differ per category; take them from the embedded spec for that route. If you omit `active`, no active-state filter is applied, so soft-deleted assets are included. Pass `active=true` for live assets only.
* **Repository categories.** `repos`, `projects`, `artifacts` and `pipelines` are derived from repository scans, not cloud accounts, so they carry no account or region. Passing `accountId` or `region` to these routes returns `400` rather than an empty list.
* **Pagination.** Responses carry `assets`, `total` and `nextToken`. Pass `nextToken` unchanged with the same filters to get the next page (see [Pagination](/api-reference/api-reference/pagination)). Omitted or non-positive `limit` falls back to the repository default; values above 500 are clamped to 500 on the per-category lists. The unified lists default to 50 and also clamp at 500. An invalid `nextToken` on the unified or public list returns `400`.
* **List rows versus detail.** List routes return table-view rows with the common columns (ID, name, sub-type, provider, account, region, source type, active and exposure flags, state, tags, first and last seen) plus a few promoted columns per category. They never include per-sub-type details. The detail route returns the same row plus a `details` object whose populated member depends on the asset's sub-type.
* **Detail errors.** An unknown ID, or an ID belonging to another tenant, returns `404`.

## Unified views

### List asset inventory

Returns assets from every category in one paginated list, with only the columns common to all categories. Use it for a complete export or an incremental sync: filter by `category`, `subType` (which requires `category`, otherwise `400`), `provider`, `accountId`, `region`, `active`, `publicFacing`, `internetReachable`, `q` (name search) and `updatedAfter` (an RFC 3339 timestamp; only assets updated strictly after it are returned). `accountId` and `region` combined with a repository category return `400`. Each row has a `_links` block you can follow to the category detail route.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/asset-inventory?githubOwnerId=1234&category=database&active=true&limit=100'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List public asset inventory

Returns active assets, across all categories, that are intentionally public-facing or reachable from the internet. Use it to enumerate the external attack surface. `policy` narrows the result: `intentional` (public-facing flag only), `reachable` (internet-reachable flag only) or `either` (the default). It also accepts `category`, `provider` and `accountId`, plus `limit` and `nextToken`. An unknown `policy`, category or provider returns `400`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/public" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Per-category lists and detail

Each category has one list route and one detail route, covered in the sections below. The detail routes take the `id` from the matching list response.

### Compute

The list route returns EC2, GCE, Azure VMs, Kubernetes nodes and similar hosts.

**List Compute assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/compute" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Compute asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/compute/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container

The list route returns ECS services and tasks, Kubernetes Deployments, Pods, StatefulSets and DaemonSets, Cloud Run, Azure ACI and App Service.

**List Container assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/container" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Container asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/container/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Cluster

The list route returns EKS and ECS clusters, GKE, AKS.

**List Cluster assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/cluster" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Cluster asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/cluster/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Serverless

The list route returns Lambda, Step Functions, App Runner, Cloud Functions, Azure Functions.

**List Serverless assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/serverless" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Serverless asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/serverless/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Network

The list route returns VPCs, subnets, gateways, route tables, Elastic IPs, VPC endpoints.

**List Network assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/network" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Network asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/network/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Connectivity

The list route returns VPN connections, Direct Connect, ExpressRoute, PrivateLink, Transit Gateway attachments.

**List Connectivity assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/connectivity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Connectivity asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/connectivity/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Load Balancer

The list route returns ALB/NLB/CLB, target groups, Kubernetes Services and Ingresses, Azure Application Gateway, GCP load balancers.

**List Load Balancer assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/load-balancer" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Load Balancer asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/load-balancer/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### CDN and DNS

The list route returns CloudFront, Route 53, API Gateway, GCP and Azure CDN and DNS, Front Door.

**List CDN and DNS assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/cdn-and-dns" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get CDN and DNS asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/cdn-and-dns/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Storage and Backup

The list route returns S3, EBS, EFS, Backup vaults, Storage Gateway and the GCP and Azure equivalents.

**List Storage and Backup assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/storage-and-backup" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Storage and Backup asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/storage-and-backup/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Database

The list route returns RDS, DynamoDB, Redshift, Neptune, ElastiCache, OpenSearch, GCP Spanner, BigQuery and Firestore, Azure SQL and Cosmos DB.

**List Database assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/database" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Database asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/database/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Messaging

The list route returns SQS, SNS, Kinesis, EventBridge, SES, GCP Pub/Sub, Azure Service Bus and Event Hubs.

**List Messaging assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/messaging" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Messaging asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/messaging/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Data Pipeline

The list route returns Glue, EMR, Athena, Dataflow, Dataproc, Data Factory, Databricks.

**List Data Pipeline assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/data-pipeline" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Data Pipeline asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/data-pipeline/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Identity

The list route returns IAM users, roles, groups and policies, Cognito user pools, Kubernetes service accounts and roles.

**List Identity assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/identity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Identity asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/identity/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Security

The list route returns security groups, NACLs, WAF, KMS, Secrets Manager, ACM, GuardDuty, Config, CloudTrail.

**List Security assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/security" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Security asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/security/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Observability

The list route returns CloudWatch log groups, alarms and dashboards, X-Ray, Stackdriver, Azure Monitor.

**List Observability assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/observability" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Observability asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/observability/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### CI/CD

The list route returns CodeBuild, CodePipeline, CodeCommit, CodeDeploy, GCP Cloud Build, Azure DevOps Pipelines.

**List CI/CD assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/ci-cd" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get CI/CD asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/ci-cd/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### AI/ML

The list route returns SageMaker endpoints, Bedrock models, Vertex AI endpoints, Azure OpenAI deployments, Azure ML workspaces.

**List AI/ML assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/ai-ml" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get AI/ML asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/ai-ml/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Repos

The list route returns source-code repositories (GitHub, GitLab, Bitbucket, Azure Repos). `accountId` and `region` return `400` on this category.

**List Repos assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/repos" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Repos asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/repos/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Projects

The list route returns per-path application units inside a repository. It also accepts `repoId`. `accountId` and `region` return `400` on this category.

**List Projects assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/projects" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Projects asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/projects/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Artifacts

The list route returns build artifacts (Docker images, JARs, wheels, npm packages, executables). It also accepts `projectId`. `accountId` and `region` return `400` on this category.

**List Artifacts assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/artifacts" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Artifacts asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/artifacts/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Pipelines

The list route returns CI/CD pipelines defined in repositories (GitHub Actions, GitLab CI, Jenkins, CircleCI, Buildkite, Azure Pipelines). It also accepts `repoId` and `projectId`. `accountId` and `region` return `400` on this category.

**List Pipelines assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/pipelines" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Pipelines asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/pipelines/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Artifact Repositories

The list route returns container and package registries; the same category holds cloud-scan records (for example ECR) and repository-derived registry records. Unlike the other repository-derived categories it carries account and region for cloud rows, so `accountId` and `region` are accepted.

**List Artifact Repositories assets.** Table-view rows with the shared filters.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/artifact-repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get Artifact Repositories asset.** Returns one asset by `id`, with the sub-type specific `details`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/artifact-repositories/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Endpoints

Endpoints are the HTTP and RPC endpoints discovered on hosts, kept as a sub-resource of the inventory rather than a category.

**List endpoints.** Filter by `hostCategory` (a category name, kebab-case or snake\_case), `hostId`, `awsService`, `sourceType`, `active` and `q` (substring match on the path), with `limit` and `nextToken`. An unrecognised `hostCategory`, `awsService` or `sourceType` returns `400`. The response lists `endpoints` rather than `assets`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/endpoints" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

**Get endpoint.** Returns one discovered endpoint by `id`; `404` if it is not in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/endpoints/{id}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Correcting assets

These three routes take a `{category}` (any of the 22 category names, kebab-case or snake\_case) and an asset `id` from a list response. They require the config-write permission. A bad category or empty ID returns `400`, and an ID that is not in your tenant returns `404` (these routes do not silently succeed for missing assets). Success returns `{"success": true, "version": "..."}`. Discovered endpoints are not a category, so these routes do not apply to them.

Scans keep rewriting inventory rows. Manual tag and flag changes are not protected from the next scan, so treat them as corrections that may need re-applying.

### Delete an asset

Soft-deletes the asset: it sets `isActive` to false and records the deletion time, but the row is kept. `deletedAtScanId` is set to `manual:` followed by your tenant ID, which distinguishes a manual delete from one made by a scan. Deleted assets still appear in lists unless you filter with `active=true`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/{category}/{id}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Patch asset flags

Overrides `isPublicFacing` and `isInternetReachable` on one asset. Both booleans are required, so send the full pair even if you are changing only one. The next scan recomputes the flags and can overwrite your values.

```bash
curl -s -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"isPublicFacing": false, "isInternetReachable": false}' \
  'https://api.<TENANT>.nullify.ai/context/asset-inventory/compute/01J...EXAMPLE/flags?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/{category}/{id}/flags" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Patch asset tags

Replaces the whole `tags` map on one asset with the map you send, so include any existing tags you want to keep. Tags are string-to-string. Like flags, tags are rewritten by the next scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/asset-inventory/{category}/{id}/tags" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Cloud scans and cloud recon

Start cloud scans, run the cloud connector agent, and read cloud recon analysis of your cloud accounts.

## Cloud scans

A cloud scan collects configuration from the cloud integrations your tenant has installed (AWS, Azure, GCP, Kubernetes). Cloud recon, the infrastructure graph, and the asset inventory are built from stored scan data; none of the read operations in this section contact your cloud accounts.

### Start a cloud scan

Starts an asynchronous scan of every cloud integration your tenant has installed and returns a `scanId` immediately (`runId` carries the same value; the body also carries `statusCode: 202`). Pass `provider` (`AWS`, `AZURE`, `GCP` or `K8S`) to scan a single integration; `accountIds` (accounts, subscriptions, projects or cluster ids, repeated per value) narrows the scan further and is rejected unless `provider` is set. `clusterIds` selects managed Kubernetes clusters and requires provider `K8S`. Set `rebuildInfraGraph=true` to rebuild the infrastructure graph once the scan completes. Requires the `ConfigWrite` permission. Each call starts a new scan; poll [Get cloud scan status](#get-cloud-scan-status) with the returned id.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/cloud-scan/start?provider=AWS&rebuildInfraGraph=true'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-scan/start" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get cloud scan status

Returns the aggregated state of a scan across every provider it covered. `overallStatus` is `in_progress` while any provider is queued or running, `completed` when every provider that ran completed, `failed` when every provider that ran failed, and `partial` when providers are a mix of completed and failed or a single provider finished partially. Providers the tenant has not configured are absent from `providers`, not reported as failed. An unknown `scanId` does not return `404`; it reads as `in_progress` with an empty `providers` list. Poll this until `overallStatus` leaves `in_progress`. It needs only a valid tenant token, not a specific permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-scan/{scanId}/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Cloud connector pull request

The cloud connector agent assesses your infrastructure-as-code repository and opens a draft pull request that configures the Nullify cloud connector. You review and merge the pull request yourself.

### Start a cloud connector PR run

Starts the asynchronous agent run and returns a `runId` and `executionArn` immediately (the body also carries `statusCode: 202`). Requires the `ConfigWrite` permission and the cloud connector PR feature to be enabled for your tenant (otherwise `412`). It currently supports GitHub organizations on github.com only (GitHub Enterprise returns `412`), and your AWS integration settings must already be configured (`412` otherwise). If a run is already queued or in progress you get `409` naming that run; a run that has been in flight for more than two hours no longer blocks a new start.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-connector-pr/runs" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a cloud connector PR run

Returns the state of one run started by the call above, including start and completion times, an error message if it failed, and, once the agent has opened it, the pull request (URL, number, repository, branch, and whether it is a draft). `runId` is the value returned when you started the run; an unknown id returns `404`. Requires the `ConfigRead` permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-connector-pr/runs/{runId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get cloud connector PR status

Returns your tenant's latest run and, separately, the latest saved pull-request record. They are independent, so a saved pull request stays visible alongside a newer failed run. Use this when you do not have a run id. It needs only a valid tenant token, not a specific permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-connector-pr/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Cloud recon

Cloud recon is an analysis of a cloud account built from the account's stored scan data. Account-scoped reads use `accountId` (the cloud account identifier, for example the AWS account number) and return data from the latest completed recon scan for that account. The document-style reads (synthesis, overview and the section reads) return `404` when the account has no completed scan. Absence of an item is not evidence that it does not exist: it can mean collection was incomplete, so check [graph gaps](#get-graph-gaps) before treating an area as clean. Requires the `ConfigRead` permission.

### Get latest cloud recon scan

Returns the metadata of the latest completed recon scan for an account: scan id, provider, status, timestamps, schema version, node, edge, hotspot and discovered-node counts, and the model used. Pass `scanId` (a UUID) to read a specific recorded scan instead of the latest.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/scans/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get account synthesis

Returns the full recon artifact for the account from the latest scan: summary, infrastructure summary, security boundaries, trusted services, traffic flows, a Mermaid diagram, hotspots, and graph gaps. It is a large document; the section reads below return one part each. Pass `scanId` to read a recorded scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/synthesis/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get account overview

Returns the per-account summary, coverage status, and infrastructure rollup, including hotspot counts by severity.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/overview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List hotspots

Returns the hotspots (areas flagged as risky, each with title, severity, category, confidence and the graph nodes involved) from the latest scan. Filter with `severity` (`critical`, `high`, `medium`, `low`) and page with `limit` and `offset`; this route uses offset paging, not `nextToken`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/hotspots" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List discovered nodes

Returns graph nodes from the latest scan, with their object type, source, port range, public flag and properties. Filter with `objectType` (for example `securityGroupRule`) and `source`; `source=cloudrecon` returns only the nodes the recon analysis added on top of the base scan. Page with `limit` and `offset`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/discovered-nodes" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get security boundaries

Returns the security boundaries identified in the latest scan for the account.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/security-boundaries" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get trusted services

Returns the trusted services (data stores and managed services) identified in the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/trusted-services" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get traffic flows

Returns the major traffic flows identified in the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/traffic-flows" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get network exposures

Returns network exposures such as open ports and permissive CIDR ranges identified in the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/network-exposures" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get cross-account relationships

Returns the cross-account trust relationships recorded for this account in the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/cross-account-relationships" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get graph gaps

Returns the discovery gaps (unresolved or unobserved areas) recorded in the latest scan. Read this to judge how complete the other sections are.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/graph-gaps" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get IAM posture

Returns the IAM posture rollup from the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/iam-posture" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get topology

Returns the per-account Mermaid topology diagram and the counts of discovered nodes and edges from the latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/accounts/{accountId}/topology" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get organization synthesis

Returns the latest completed organization-level synthesis across the tenant's accounts: a combined summary, a combined Mermaid diagram, cross-account correlations, the source account ids, and a per-account summary table. Pass `scanRunId` to read a specific run; it returns `404` if that run is unknown.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/organization/synthesis/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List cross-account trusts

Returns every external principal that is trusted by two or more accounts in your tenant, with the trusting accounts, based on each account's latest scan.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/tenants/cross-account-trusts" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Persist a cloud recon scan

Stores a completed recon scan produced by the Nullify cloud recon agent and indexes its nodes and hotspots. The body needs `accountId`, `provider`, `startedAt`, `schemaVersion` and the opaque `payload`; `scanId` is optional. The account must be one your tenant owns (otherwise the request is rejected) and a malformed payload returns an error. Most integrators never call this: recon scans are produced for you by the platform. Requires the `ConfigWrite` permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/cloud-recon/scans" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Dependencies and SBOMs

Read the dependency inventory that Context builds from SBOMs, and generate, replay or delete the SBOMs behind it.

## How dependency data is organised

Context stores a dependency inventory per repository and project. Each dependency is recorded as an occurrence with an exposure window: when it entered the project and, if it has been removed, when it left. Three views are available. Active calls return what is in the project now (at its latest commit). The at-commit and diff calls evaluate a project at a commit's timestamp. History and exposure calls return the windows during which a package version was present. Always keep the `repositoryId`, `projectId` and commit with any result you compare; take `repositoryId` and `projectId` from [List projects](/api-reference/api-reference/context/applications-and-repositories#list-projects). The `/deps` list calls page with `cursor` and `pageSize` and return `nextCursor`; pass it back as `cursor` to continue (this is not the `nextToken` scheme in [Pagination](/api-reference/api-reference/pagination)). Except where noted, these reads need a valid tenant token and no extra permission.

## Tenant-wide dependencies

### List active dependencies

Returns the dependencies currently active across every repository and project in your tenant, with optional filters: `search` (free text), `ecosystem`, `name`, `direct` (true for direct dependencies only), `repositoryId`, `projectId`, and `range` (a version filter, semver range or hash). Page with `cursor` and `pageSize`.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/deps/active?ecosystem=npm&name=lodash&pageSize=50'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/active" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Summarize active dependencies

Returns aggregate counts and the oldest active dependency across the tenant. It accepts the same filters as the active list (`search`, `ecosystem`, `name`, `direct`, `repositoryId`, `projectId`, `range`), so the counts match the rows the same filters return.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/active/summary" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List dependency history

Returns dependency occurrences, including ones that have since been removed, across all repositories and projects, with their exposure windows. Requires the `ConfigRead` permission. Page with `cursor` and `pageSize`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Find package exposure across the tenant

Returns the exposure windows for one package across all repositories and projects that intersect a version filter. `ecosystem`, `name` and `range` are all required; `range` is a semver range such as `>=1.2.0 <2.0.0` or a hash. Use it to answer which projects have used an affected version and when.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/deps/exposure?ecosystem=npm&name=lodash&range=%3C4.17.21'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/exposure" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List dependencies without a lockfile

Returns projects, or repositories with `level=repository`, whose dependencies were resolved without a committed lockfile. `level` defaults to `project`. These are exposed to version drift during supply chain incidents because the resolved versions are not pinned. Requires the `ConfigRead` permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/without-lockfile" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Walking the dependency graph

Each occurrence carries the SBOM `bom-ref` of its component. A bom-ref is unique within a project but can repeat across projects, so these reads return lists and page with `cursor` and `pageSize`.

### Get dependencies by bom-ref

Returns the active occurrences whose SBOM bom-ref matches `bomRef`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/by-ref/{bomRef}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List dependents of a bom-ref

Returns the active occurrences whose parents include `bomRef`, which are its immediate dependents. Call it recursively on each result to walk the downstream subtree.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/dependents/{bomRef}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Per-project dependencies

### List a project's active dependencies

Returns the dependencies active at the project's latest commit. Filter with `search`, `ecosystem` and `direct`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/repository/{repositoryId}/project/{projectId}/active" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get dependencies at a commit

Returns the dependencies that were present at the given commit. The commit must have a stored SBOM for the project: its commit timestamp is read from that SBOM and used to evaluate the inventory at that moment, and the response includes `commitTime`. A commit without a stored SBOM is an error.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/repository/{repositoryId}/project/{projectId}/at/{commit}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Diff dependencies between commits

Returns packages added, removed and upgraded between `fromCommit` and `toCommit`, both of which need stored SBOMs. If `fromCommit` is omitted the project's earliest stored SBOM is used; if `toCommit` is omitted the latest is used, and in that case the packages that were present at the start are also reported as added. A `toCommit` that is older than `fromCommit` is rejected as an invalid argument.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/repository/{repositoryId}/project/{projectId}/diff" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get package history in a project

Returns the exposure windows for one package, grouped by version, within the project. `ecosystem` and `name` are required.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/repository/{repositoryId}/project/{projectId}/history" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Find package exposure in a project

Like the tenant-wide exposure call but limited to one project: returns windows for the package that intersect `range`. `ecosystem`, `name` and `range` are required.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/repository/{repositoryId}/project/{projectId}/exposure" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete dependency data

Permanently deletes dependency occurrence records. The scope depends on which query parameters you send. Supply `repositoryId`, `projectId`, `ecosystem`, `name`, `version` and `introducedAt` (RFC 3339) to delete one entry; supply only `repositoryId` and `projectId` to delete everything for a project; supply no selectors and `global=true` to delete every dependency record in the tenant. Any other combination, or a tenant-wide delete without `global=true`, returns `400`. The response reports the `scope` (`entry`, `project` or `tenant`) and `deletedCount`. This call needs only a valid tenant token, not `ConfigWrite`. Deletion cannot be undone here; the inventory is rebuilt only when SBOMs are ingested again (see [Replay SBOM ingestion](#replay-sbom-ingestion)).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## SBOMs

A software bill of materials (SBOM) is the CycloneDX document that records a project's components at a commit. SBOMs are stored per tenant, repository, project and commit. The reads below list what is stored; the write operations start generation as background work.

### Get the SBOM tree

Returns a tree of the tenant's stored SBOMs by repository, project and commit. Pass `verbose=true` to include repository and project names. Requires the `ConfigRead` permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/tree" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the latest SBOMs for a repository

Returns the most recent SBOM of each project in the repository. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/repository/{repositoryId}/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List SBOMs for a project

Returns SBOMs for a repository and project, newest first. Page with `page` and `pageSize` (default: the 100 most recent), or select a range with `fromCommit`/`untilCommit` or `fromTime`/`untilTime`; a commit range cannot be combined with a time range. Setting `fromCommit` and `untilCommit` to the same commit returns that one SBOM, or `404` if none is stored.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/repository/{repositoryId}/project/{projectId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Run commit pipelines

`POST /context/sboms/generate` is the compatibility route for manually starting repository context (including schema reversing) and whole-repository SBOM generation in parallel, followed by the per-project split and dependency ingest. Use `nullify context commit-pipelines run --repo <id>` from the CLI. For an SBOM run alone, use [Start an SBOM run](#start-an-sbom-run).

The platform resolves the repository's clone URL, default branch and current head. Optional `cloneUrl`, `defaultBranch` and `commitSha` values must match those values; a mismatch returns `400`. An active commit pipeline run is reused; a closed run is retried immediately. The response includes `status` and `executionArn`. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/generate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start an SBOM run

Generates, splits per project and ingests one SBOM for the repository's default branch head, and starts nothing else: no repository context, schema reversing or scan. If you pass `commitSha` it must be the current head. Returns `runId` and `executionArn`; once stored, the SBOM is readable from [Get the latest SBOMs for a repository](#get-the-latest-sboms-for-a-repository). Requires `ConfigWrite`.

```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"repositoryId": "1234"}' \
  'https://api.<TENANT>.nullify.ai/context/sboms/runs'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/runs" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Scan an SBOM

Returns the stored SBOM for `repositoryId`, `projectId` and `commitSha` (all required) with `status` `ready` and `cached` true; if none exists, or `forceRegenerate` is true, it queues generation and returns `status` `generating`, and you poll [List SBOMs for a project](#list-sboms-for-a-project) with the same commit. The project must already be known to SBOM storage and the commit must exist in the repository. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/scan" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Resolve an SBOM

Returns the storage key of the SBOM for a repository and commit, generating it on demand if it is not cached. The request is a detailed object (lockfile-set hash, scanner version, CycloneDX generator major version, clone URL, owner and repository provider) that the dependency scanning pipeline builds, so most integrators use the other SBOM calls instead. The response gives the `sbomS3Key`, a `source` that names which cache tier served it, the component count, and a presigned `sbomUrl` with its SHA-256 and size; `incomplete` is true when generation did not cover every manifest. Requires `ConfigRead`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms/resolve" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Replay SBOM ingestion

Enqueues a replay of dependency ingestion from stored SBOMs, which rebuilds the dependency inventory without regenerating SBOMs. Send `repositoryID` and `projectID` to replay one project up to its head commit, or `globalReplay: true` to replay every repository in the tenant. Without `globalReplay`, both ids are required or the call returns `400`. The call returns once messages are queued, not when ingestion finishes. Requires `ConfigWrite`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sbomingestor/replay" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete SBOMs

Permanently deletes stored SBOMs for the tenant. Narrow the scope with `repositoryId` (and `projectId`, which requires `repositoryId`), restrict it to invalid SBOM objects with `invalidOnly=true`, and use `dryRun=true` first to list what would be deleted without removing anything. With no selectors it covers every SBOM in the tenant. The response lists `deletedKeys` and the resulting tree. Requires `ConfigWrite`.

```bash
curl -s -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/sboms?repositoryId=1234&dryRun=true'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/sboms" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Documents, memories, and reports

Manage the organization knowledge your tenant gives Nullify: vault documents you upload, the memories that agents and users record, the organization classification, and generated package reports. All calls need an `Authorization: Bearer <TOKEN>` header; see [Authentication](/api-reference/api-reference/authentication). Read calls require the `ConfigRead` permission and write calls require `ConfigWrite`.

## Vault files

The vault holds documents you upload (architecture notes, policies, runbooks). Files are only searchable once they are indexed. Allowed extensions are `.txt`, `.json`, `.yaml`, `.yml`, `.xml`, `.csv`, `.md`, `.pdf`, `.docx`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` and `.svg` (indexed), plus `.doc`, `.xls`, `.xlsx`, `.zip`, `.tar`, `.gz` and `.7z`, which upload and download but are skipped by the indexer.

### Upload a vault file

Returns a presigned upload URL; the file bytes never go through this call. Send `fileName` (required, at most 256 characters, no `/`, `\` or `..`, and an allowed extension) and optionally `description` (at most 4096 characters) and `size` in bytes. When `size` is positive (maximum 100 MB) the URL is pinned to that exact `Content-Length`, so an upload of a different size is rejected. The response carries `fileId` and `documentId`. `PUT` the file to `presignedUploadURL`, then call [Index vault files](#index-vault-files) with the `fileId` so the document becomes searchable.

```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"fileName": "architecture.pdf", "description": "Service architecture overview", "size": 482113}' \
  'https://api.<TENANT>.nullify.ai/context/vault/file'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/file" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List vault files

Returns a page of files with a presigned download URL, `fileId`, `fileName`, uploader, `createdAt`, `documentId` and `contentType`, plus `totalCount` across all pages. Use `limit` (1 to 1000; larger values are clamped to 1000) and `offset` to page, and `search` for a case-insensitive substring match on the file name. With no `limit`, every file is returned. Each file with a `documentId` carries an `indexed` flag showing whether its document is in the search index; the flag is omitted if the index could not be read. A tenant with too many files to enumerate gets a resource-exhausted error and should narrow with `search`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/files" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List vault file names

Returns a lightweight list of `fileName`, `description` and `documentId` for every file, without presigned URLs, paging or an indexed marker. Use it to build a picker or check which names already exist.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/files/list" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a vault file

Returns the metadata and a fresh presigned download URL for one file. `fileId` comes from [List vault files](#list-vault-files) or [Upload a vault file](#upload-a-vault-file). An unknown id returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/file/{fileId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update vault file metadata

Updates the stored metadata of the file identified by its file name (not its id) in the path. The body accepts `metadata` (a free-form object), `documentId` and `processedAt`. The response is a success flag and message only.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/file/{fileName}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a vault file

Deletes the file from the vault, removes its indexed chunks from the search index, and forgets the memories derived from its document. The memories keep their audit history. Deletion cannot be undone. Index cleanup is best effort: if it fails the file is still deleted and the next [RAG resync](#resync-the-knowledge-base) removes the orphaned chunks. If the file's document id cannot be read because of a transient storage fault the call returns `503` (or `504` on timeout) and nothing is deleted, so retry. A successful delete returns an empty body.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/file/{fileId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Indexing and search

Indexing chunks a vault document and embeds it so it can be searched. Both indexing calls queue work and return before it finishes.

### Index vault files

Queues chunking and embedding of the listed `fileIDs` (at least one, none blank) into the knowledge base. It is additive, never deletes anything, and does not run organization-context extraction. A success response means the request was queued, not that indexing finished; there is no status endpoint for this call, so confirm completion by checking the `indexed` flag from [List vault files](#list-vault-files). Call it after each upload. Use [Trigger vault onboarding](#trigger-vault-onboarding) for the setup wizard flow and [Resync the knowledge base](#resync-the-knowledge-base) for tenant-wide reconciliation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/index" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Search vault documents

Hybrid semantic and keyword search over indexed vault documents. `query` is required. `limit` is 1 to 50, `documentIds` restricts the search to specific documents and `docTypes` to document types. Each result is a passage with `documentId`, `fileName`, page or line range, `text` and a relevance `score`. If the embedding service is unavailable the search falls back to keyword matching only, which is not visible in the response. Files that are not yet indexed are not searched.

```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"query": "how are production secrets rotated", "limit": 5}' \
  'https://api.<TENANT>.nullify.ai/context/vault/search'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/search" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get vault document text

Returns the extracted text of an indexed document by `documentId` (from the file list). Narrow with `startPage` and `endPage` (1-based, inclusive, end not before start). `maxChars` defaults to and is capped at 60000. A document too large to read whole returns `400` with advice to set `maxChars` and page, narrow the pages, or use search; when `maxChars` is set, a response with `truncated: true` carries a `nextToken` to pass back for the next slice. A document that is not indexed returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/document/{documentId}/text" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Trigger vault onboarding

Records an asynchronous onboarding run over the listed vault `fileIDs` (at most 50, nonblank and unique); an onboarding agent then extracts organization context from them. The response carries a `runId`; poll [Get an organization context run](#get-an-organization-context-run) with it. Pass your own `runId` (a ULID) to make a retry idempotent: reuse it with the same `fileIDs` and the run is not queued twice, while reusing it with different files is rejected with `400`. If queue delivery is unconfirmed the call still returns the `runId` with `success: false`; retry with the same `runId` and files.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/vault/onboard" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Resync the knowledge base

Queues a full reconciliation of your tenant's knowledge base against the vault: every vault file is listed and re-indexed, and indexed content with no matching vault file is removed. Use it for the first backfill or to recover from drift. It takes no body, returns as soon as the request is queued, and has no status endpoint. It can be expensive for a large vault, so do not call it per upload.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/rag/resync" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Organization context

The organization context is Nullify's classification of your company and what software it builds, built from onboarding and the vault.

### Get the organization context

Returns the current organization classification and a `version` for the stored copy.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/organization" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Replace the organization context

Creates or fully replaces the organization context with the `organization` object in the body; each call stores a new version. A `null` organization or an invalid questionnaire is rejected with `400`, and an organization marked `onboarded` must pass the onboarded-context validation. Because it replaces everything, read the current context first and send back what you want to keep.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/organization" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Rename the organization

Changes only the organization `name` (1 to 256 bytes, no control characters) without replacing the collected context. `notes` is not accepted here and returns `400`; manage notes through the memory endpoints. Returns `404` if no organization context exists and `412` if the stored context changed during the update, in which case retry.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/organization" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an organization context run

Returns the state of an onboarding run started by [Trigger vault onboarding](#trigger-vault-onboarding): `PENDING` (queued), `RUNNING`, `SUCCEEDED` or `FAILED`, with a `message` and the context `version` it produced. Set `includeResult=true` to include the resulting `organization` once the run has succeeded. `runId` must be a ULID; an unknown run for your tenant returns `404`.

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/organization/runs/01J...?includeResult=true'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/organization/runs/{runId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Memories

A memory is a durable note about a resource (a finding, repository, document, the organization) that Nullify's agents and your team can write and later recall. Memories are versioned and never edited in place: every change appends an immutable version, and deleting or retracting leaves a tombstone. Each memory has a `memoryType` (for example `KNOWLEDGE`, `TRIAGE`, `REMEDIATION`, `FOLLOW_UP`), a `priority`, an optional cognitive `memoryClass`, and a `trustTier` from 0 (ingested) to 3 (human decision). Memories can be superseded by a newer memory; only live memories (active and not superseded) can be edited. Some writes are reserved for Nullify services: setting trust tier 3, using the `actionitem:` source event, using ids that start with `tacitans:` or `ctxclar:`, or overwriting a customer answer returns `403` for other callers.

### List memories

Filters memories by `resourceId`, `resourceType`, `memoryType`, `priority`, `isLatest`, `memoryClass`, `status`, `minTrustTier` (0 to 3), and `createdBy`. `limit` is 1 to 1000 (default 50). Page with `offset`, or pass the `nextToken` from the previous response (an offset as a string; `offset` wins if both are set); `nextToken` is absent on the last page and `totalCount` gives the total. See [Pagination](/api-reference/api-reference/pagination).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a memory

Creates a memory. `memoryType` and `content` are required; `confidence` must be 0 to 1 and every `anchors` entry must be `<kind>:<id>`. Without `resourceId` the memory attaches to its `metadata.documentMetadata.documentId` or to itself. Supply your own `memoryId` to make the write an idempotent upsert: repeating the call updates the same memory instead of adding another, but a memory that is retracted or superseded returns `412`. Set `supersedesMemoryId` to a live memory of your tenant to replace it in the same transaction; a missing or non-live target is rejected. A memory scoped to a document becomes the latest for that document and supersedes the earlier ones. Returns the stored memory.

```bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"memoryType": "KNOWLEDGE", "content": "Payments service is internet-facing behind the public ALB.", "resourceType": "REPO_CONTEXT", "resourceId": "repo-1234", "anchors": ["repo:1234"]}' \
  'https://api.<TENANT>.nullify.ai/context/memories'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a memory

Returns one memory by `memoryId`, including retracted ones, which come back with their status. Any failure to find it, including another tenant's id, returns `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a memory

Changes the supplied fields (`content`, `title`, `priority`, `confidence`, `tags`, `citations`, `crossReferences`, `metadata`, `parentNoteId`) and appends a new version. Omitted fields keep their values. A superseded, retracted or otherwise non-active memory cannot be edited and returns `412`; write a new memory with `supersedesMemoryId` instead. Setting `supersedesMemoryId` here makes the updated memory replace another live memory.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a memory

Retracts the memory rather than erasing it: the row stays as a tombstone with status `cancelled` and reason `deleted` (or the `reason` query parameter), disappears from searches and latest-only lists, and can still be read by id. The call returns `success: true`. Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Retract a memory

Withdraws a memory as wrong or no longer wanted. `reason` is required and `retractedBy` is optional; for non-service callers retraction of a customer answer is attributed to the authenticated user instead of the supplied name. Same tombstone behavior as delete, but the updated memory is returned in the response and the reason is mandatory. Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}/retract" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get memory versions

Returns the immutable version history of a memory, newest first, with each version's `status`, `changeReason`, `changedBy`, `createdAt` and full memory snapshot. `limit` defaults to 50 and is capped at 1000. Writes, supersedes and retractions each append a version.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}/versions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get memory findings

Lists the live findings associated with a memory, most severe first: findings whose triage cited the vault document the memory was distilled from (`cited: true`), and findings the memory names in its anchors (`cited: false`). Each finding carries a `status` of `open`, `resolved`, `allowlisted` or `closed` (archived, false positive, duplicate or superseded); deleted findings are not returned. Requires `ConfigRead` and `FindingRead`. `limit` defaults to 20 and is capped at 100; `totalCount` is the whole set, including findings past `limit`. Only code findings record vault-document citations today. Unknown ids return `404`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/{memoryId}/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List memories by type

Like [List memories](#list-memories) but keyed on the required `memoryType` query parameter, with optional `createdBy`, `resourceId`, `isLatest`, `limit` (1 to 1000, default 50), `offset`, and `paginationToken` (the offset of the next page as a string from the previous response).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/type" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List memories by document

Returns the latest live memories scoped to a document, finding, repository or project id given as `documentId`. `limit` is 1 to 1000 (default 50) and caps the list; the response is not paginated, so `paginationToken` has no effect here.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/document/{documentId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List memories by document and type

Same as [List memories by document](#list-memories-by-document), restricted to the required `memoryType` query parameter. `limit` is 1 to 1000 (default 50); no pagination.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/document/{documentId}/type" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Search memories

Hybrid semantic and keyword search over memories. `query` is required (non-blank). Narrow with `memoryTypes`, `resourceType`, `scope`, `memoryClass`, `minTrustTier` (0 to 3) and `anchors`; with `anchors`, set `includeOrgWide` to also return organization-wide memories after the anchored matches. `limit` is 1 to 100. Each result has the `memory` and a `score` (higher is better). Retracted and superseded memories are not returned.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/search" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Grep memories

Exact, case-insensitive substring match over memory titles and content, the literal counterpart to [Search memories](#search-memories). `pattern` is required and non-blank. Optional filters are `memoryTypes`, `resourceType`, `scope`, `memoryClass` and `minTrustTier`; `limit` is 1 to 1000. Returns `memories` and `count`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/memories/grep" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Reports

Generate a report of where specific packages are used across your repositories.

### Create a report job

Queues generation of a package-usage report. `packages` is required and non-empty; each entry has `ecosystem`, `package` and `version`. `repositories` optionally restricts the report to repository ids; empty means all repositories. Every call creates a new job and returns its `jobId` immediately; poll [Get report status](#get-report-status).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/reports" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get report status

Returns `status` (`queued`, `in_progress`, `failed` or `success`), an `error` message when failed, and, once `success`, a presigned `url` to download the PDF. The URL is generated on each call and expires, so fetch a fresh one rather than storing it. If the URL cannot be generated the call still succeeds without `url`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/reports/{jobId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Manager API

Use `/manager` to work with [strategies, campaigns, and human decisions](/capabilities/program-management). Start with the existing program and current proposals before creating work that may already be planned.

Every operation is scoped to one tenant provider, so pass the same provider scope you use elsewhere, such as `githubOwnerId`. Operations that read need read access and operations that change state need write access for the area they touch. Where one differs from what you would expect, the guide for that area says so. A 403 on a team-scoped role is expected for action items, chat and the campaign event feeds.

## Approvals and decisions

Manager separates proposing from deciding. Read this before automating anything that accepts or starts work.

* **Generating a proposal is not approval.** `POST /manager/strategy/trigger` and the proposal-producing run modes write a proposed strategy version or proposed campaigns. A proposal must be accepted before it takes effect. Strategy acceptance is always explicit, whatever autonomy the [security program](/api-reference/api-reference/manager/program-and-strategy#security-program) sets. Autonomy governs what Manager may do afterwards, such as creating successor campaigns inside the accepted goals.
* **A decision names the exact thing it decides.** [Decide the proposed strategy](/api-reference/api-reference/manager/program-and-strategy#decide-the-proposed-strategy) takes the `strategyId` of a specific strategy version, and [Decide a proposed campaign](/api-reference/api-reference/manager/proposals-and-runs#decide-a-proposed-campaign) takes a `proposalId`. If that version or proposal is no longer the one awaiting a decision, the call returns 412 and changes nothing. It does not redirect to the newer one. Re-read the proposal and decide again against what you are looking at.
* **Decisions are final.** Accepting or rejecting cannot be repeated or reversed through the same endpoint, and a repeat call returns 412. An accepted strategy version retires the other pending versions.
* **The caller is recorded.** The deciding identity comes from your credentials, not from the request body.
* **Some operations are direct writes, not proposals.** `PATCH /manager/strategy` puts a new strategy version in force as soon as it succeeds. `POST /manager/campaigns` creates a campaign directly. The `activate` action on a threat investigation creates and starts a remediation campaign. These calls apply changes directly, so do not call them as a way to "propose".

## Runs are asynchronous

Operations that start Manager work, such as `POST /manager/trigger`, `POST /manager/strategy/trigger` and `POST /manager/campaigns/default/generate`, return when the run is accepted, with a `runId`. They do not wait for it. Poll `GET /manager/runs/{runId}` until `terminal` is `true`, and read what the run wrote from the response. A `SKIPPED` run succeeded and wrote nothing. See [Proposals, runs and state](/api-reference/api-reference/manager/proposals-and-runs#following-a-run). A start call returns 429 while another run holds the tenant lock, which is safe to retry later.

## Guides in this section

* [Program and strategy](/api-reference/api-reference/manager/program-and-strategy): the security program, the active strategy, strategy versions, and strategy proposals and decisions.
* [Proposals, runs and state](/api-reference/api-reference/manager/proposals-and-runs): campaign proposals and decisions, starting and following runs, state, plans and metrics.
* [Campaigns, runs and events](/api-reference/api-reference/manager/campaigns): creating and editing campaigns, previews, findings, campaign runs, and Manager events.
* [Action items and escalations](/api-reference/api-reference/manager/action-items): resolving, dismissing and reopening action items, nudges, and git identity classifications.
* [Operator chat](/api-reference/api-reference/manager/chat): chat sessions, history, actions and audit records.
* [Configuration, ground rules and escalations](/api-reference/api-reference/manager/escalations-and-config): preview mode, ground rules, escalation routing and onboarding.
* [Threat intelligence](/api-reference/api-reference/manager/threats): the published threat catalog, threat reports and threat investigations.

## Related

[Manager configuration](/configuration/configuration-manager) explains program autonomy, tenant and team ground rules, and blocked action types. Legacy Manager credits are not a supported API; use [AI usage](/api-reference/api-reference/usage).

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                              | Operation                                         |
| -------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| `GET`    | `/manager/action-items`                                           | List Action Items                                 |
| `GET`    | `/manager/action-items/summary`                                   | Action Items Summary                              |
| `DELETE` | `/manager/action-items/{actionItemId}`                            | Soft-Delete Action Item                           |
| `GET`    | `/manager/action-items/{actionItemId}`                            | Get Action Item                                   |
| `PATCH`  | `/manager/action-items/{actionItemId}`                            | Patch Action Item Team                            |
| `POST`   | `/manager/action-items/{actionItemId}/answer`                     | Answer Action Item                                |
| `POST`   | `/manager/action-items/{actionItemId}/assign-repo`                | Assign Repository Owner To Action Item            |
| `POST`   | `/manager/action-items/{actionItemId}/assign-team`                | Assign Team To Action Item                        |
| `PUT`    | `/manager/action-items/{actionItemId}/chat`                       | Get or create action item chat                    |
| `POST`   | `/manager/action-items/{actionItemId}/dismiss`                    | Dismiss Action Item                               |
| `POST`   | `/manager/action-items/{actionItemId}/edit`                       | Edit Action Item                                  |
| `GET`    | `/manager/action-items/{actionItemId}/links`                      | Get Action Item Links                             |
| `POST`   | `/manager/action-items/{actionItemId}/map-user`                   | Map User For Action Item                          |
| `GET`    | `/manager/action-items/{actionItemId}/messages`                   | Get Action Item Messages                          |
| `POST`   | `/manager/action-items/{actionItemId}/nudge`                      | Nudge Escalation Action Item                      |
| `POST`   | `/manager/action-items/{actionItemId}/reopen`                     | Reopen Action Item                                |
| `POST`   | `/manager/action-items/{actionItemId}/snooze`                     | Snooze Action Item                                |
| `GET`    | `/manager/campaigns`                                              | List Campaigns                                    |
| `POST`   | `/manager/campaigns`                                              | Post Campaign                                     |
| `GET`    | `/manager/campaigns/default`                                      | Get Default Campaigns                             |
| `POST`   | `/manager/campaigns/default/generate`                             | Generate Default Campaigns                        |
| `GET`    | `/manager/campaigns/findings`                                     | Get All Campaigns Findings                        |
| `GET`    | `/manager/campaigns/metrics/refresh`                              | Refresh Campaign Metrics                          |
| `GET`    | `/manager/campaigns/previews`                                     | Get Campaign Previews                             |
| `GET`    | `/manager/campaigns/summaries`                                    | Get Campaign Summaries                            |
| `DELETE` | `/manager/campaigns/{campaignId}`                                 | Delete Campaign                                   |
| `GET`    | `/manager/campaigns/{campaignId}`                                 | Get Campaign by ID                                |
| `PATCH`  | `/manager/campaigns/{campaignId}`                                 | Patch Campaign                                    |
| `GET`    | `/manager/campaigns/{campaignId}/events`                          | Get Campaign Events                               |
| `GET`    | `/manager/campaigns/{campaignId}/findings`                        | Get (Triaged) Findings Associated with a campaign |
| `GET`    | `/manager/campaigns/{campaignId}/preview`                         | Get Campaign Preview Details                      |
| `GET`    | `/manager/campaigns/{campaignId}/runs`                            | List Campaign Runs                                |
| `GET`    | `/manager/campaigns/{campaignId}/runs/{runId}`                    | Get Campaign Run                                  |
| `PUT`    | `/manager/chat/general`                                           | Get or create Operator General chat               |
| `GET`    | `/manager/chat/sessions`                                          | List Chat Sessions                                |
| `DELETE` | `/manager/chat/sessions/{chatID}`                                 | Delete Chat Session                               |
| `GET`    | `/manager/chat/sessions/{chatID}`                                 | Get Chat Session                                  |
| `PATCH`  | `/manager/chat/sessions/{chatID}`                                 | Patch Chat Session                                |
| `GET`    | `/manager/chat/sessions/{chatID}/actions`                         | Get Chat Session Actions                          |
| `GET`    | `/manager/chat/sessions/{chatID}/audit`                           | Get chat session audit trail                      |
| `GET`    | `/manager/chat/sessions/{chatID}/history`                         | Get Chat Session History                          |
| `GET`    | `/manager/config`                                                 | Get Manager config                                |
| `POST`   | `/manager/config`                                                 | Update Manager config                             |
| `POST`   | `/manager/daily-summary/trigger`                                  | Start a daily summary run                         |
| `GET`    | `/manager/engagement/users`                                       | Get Developer Engagement                          |
| `GET`    | `/manager/escalation-recipients`                                  | Get Escalation Recipients                         |
| `GET`    | `/manager/escalations/config`                                     | Get Escalation Config                             |
| `PUT`    | `/manager/escalations/config`                                     | Put Escalation Config                             |
| `GET`    | `/manager/events`                                                 | Get Events                                        |
| `POST`   | `/manager/events/deduplicate`                                     | Deduplicate Events                                |
| `DELETE` | `/manager/events/{eventId}`                                       | Delete Event                                      |
| `GET`    | `/manager/findings/{findingId}/events`                            | Get Finding Events                                |
| `GET`    | `/manager/fix-prs/{recordId}/nudge`                               | Preview Fix PR Nudge                              |
| `POST`   | `/manager/fix-prs/{recordId}/nudge`                               | Nudge Fix PR Reviewers                            |
| `GET`    | `/manager/groundrules`                                            | Get Manager ground rules                          |
| `PATCH`  | `/manager/groundrules`                                            | Patch a GroundRules object                        |
| `POST`   | `/manager/groundrules`                                            | Post a GroundRules object                         |
| `GET`    | `/manager/identity-classifications`                               | List Git Identity Classifications                 |
| `POST`   | `/manager/identity-classifications`                               | Classify Git Identity                             |
| `DELETE` | `/manager/identity-classifications/{provider}/{providerUserId}`   | Revoke Git Identity Classification                |
| `GET`    | `/manager/metrics`                                                | Get Metrics                                       |
| `POST`   | `/manager/onboarding/wizard-progress`                             | Onboarding Wizard Progress                        |
| `GET`    | `/manager/plans`                                                  | Get Plans                                         |
| `GET`    | `/manager/program`                                                | Get Security Program                              |
| `PATCH`  | `/manager/program`                                                | State Security Program                            |
| `GET`    | `/manager/proposals`                                              | List Open Proposals                               |
| `POST`   | `/manager/proposals/decision`                                     | Decide Proposed Campaign                          |
| `GET`    | `/manager/runs/{runId}`                                           | Get Manager Run                                   |
| `GET`    | `/manager/state`                                                  | Get Manager State                                 |
| `GET`    | `/manager/state/latest`                                           | Get Manager State (Legacy)                        |
| `GET`    | `/manager/states`                                                 | Get Manager States                                |
| `GET`    | `/manager/strategy`                                               | Get Active Strategy                               |
| `PATCH`  | `/manager/strategy`                                               | Patch Active Strategy                             |
| `GET`    | `/manager/strategy/proposal`                                      | Get Proposed Strategy                             |
| `POST`   | `/manager/strategy/proposal/decision`                             | Decide Proposed Strategy                          |
| `POST`   | `/manager/strategy/trigger`                                       | Trigger Strategy Generation                       |
| `GET`    | `/manager/strategy/versions`                                      | List Strategy Versions                            |
| `POST`   | `/manager/tacit-knowledge/trigger`                                | Trigger TacitKnowledge                            |
| `GET`    | `/manager/threat-investigations`                                  | Get Threat Investigations                         |
| `POST`   | `/manager/threat-investigations`                                  | Post Threat Investigation                         |
| `GET`    | `/manager/threat-investigations/{threatInvestigationId}`          | Get Threat Investigation                          |
| `PATCH`  | `/manager/threat-investigations/{threatInvestigationId}`          | Patch Threat Investigation                        |
| `GET`    | `/manager/threat-investigations/{threatInvestigationId}/progress` | Get Threat Investigation Progress                 |
| `GET`    | `/manager/threat-reports`                                         | List My Reported Threats                          |
| `POST`   | `/manager/threat-reports`                                         | Report a Threat                                   |
| `GET`    | `/manager/threat-reports/{requestId}`                             | Get Threat Report Status                          |
| `POST`   | `/manager/threat-reports/{requestId}/resubmit`                    | Resubmit a Reported Threat                        |
| `POST`   | `/manager/threat-reports/{requestId}/withdraw`                    | Withdraw a Reported Threat                        |
| `GET`    | `/manager/threats`                                                | Get Threat Catalog                                |
| `POST`   | `/manager/threats/{threatId}/investigate`                         | Investigate Threat in My Environment              |
| `POST`   | `/manager/trigger`                                                | Start a Manager run                               |


# Action items and escalations

Action items are the questions and decisions Manager hands to people: assigning an owner to a repository, mapping a git identity to a chat account, escalating a finding, or answering a question about your environment. This page covers listing and resolving them, nudging people, and the classifications that stop Manager asking about the same identity again.

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`.

Action items are tenant-wide operator data. When role-based access control is enforced for the tenant, callers whose role is limited to specific teams receive 403 ("operator access is unavailable for team-scoped roles") from these operations and from [Chat](/api-reference/api-reference/manager/chat).

Action items have a `kind` (`ESCALATED_FINDING`, `TACIT_KNOWLEDGE`, `UNMAPPED_USER`, `UNASSIGNED_TEAM`, `CONTEXT_CLARIFICATION`, `STRATEGY_PROPOSAL`, `CAMPAIGN_PROPOSAL`) and a `status` (`OPEN`, `RESOLVING`, `COMPLETED`, `DISMISSED`). The `resolutionMode` says how an item can be resolved: `CHAT` means only the Operator conversation, while `WIDGET_TEAM_PICKER` and `WIDGET_USER_MAPPING` have the structured endpoints below. The proposal kinds are notifications that a decision is waiting. Resolving or dismissing them here does not decide the strategy or campaign. Use the [decision endpoints](/api-reference/api-reference/manager#approvals-and-decisions).

## Reading action items

### List action items

Returns action items, filtered by `status`, `kind`, `teamId`, `unassignedOnly` (only items routed to central security) or a linked finding. `findingId` must be paired with `findingType`. An invalid filter value returns 400. Pages use `page` and `pageSize` (default 20).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Summarize action items

Returns counts by status, kind and team, plus `total`, `totalOpen`, `totalStalled` and `unrouted`. An unrouted item is one the follow-up pass found no route for, such as no connected chat platform and no central channel. Zero unrouted is not the same as zero open.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/summary" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an action item

Returns one item with its linked findings, any still-open linked pull requests, the resolved git identity for user-mapping items, and the connected chat platform. Returns 404 for an unknown id or another tenant's item.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get action item messages

Returns the conversation history for an item's chat, newest window first, in chronological order, with `page` and `pageSize` (default 100). `hasMore` says whether older messages exist. An item with no conversation yet returns an empty list, not 404. New messages arrive over the chat WebSocket rather than by polling this call.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/messages" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get or create an action item chat

Returns the item's Operator chat session id, creating the binding on the first call, so it is safe to repeat. The call needs a user identity, and returns 400 for an item that is already completed or dismissed. Use the returned `chatId` with the [Chat](/api-reference/api-reference/manager/chat) operations. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/chat" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Routing and cleanup

### Change an action item's team

Reassigns the item's team with `teamId`. An empty string is rejected; send `null` to route the item to central security. Returns 400 for an unknown team or an item that is already completed or dismissed. The only field you can change this way is the team; status changes go through the operations below. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete an action item

Soft-deletes an item. It is housekeeping and is different from a dismissal. A dismissal that was recorded as decided cannot be deleted; reopen the item or revoke the classification instead. Requires team management permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Resolving action items

These operations resolve an item and record who did so. Status changes made by automation cannot override a person's decision: automation cannot make a decided dismissal, and cannot reopen an item that a person decided. Where an item is mid-resolution the call returns 409 and you should retry shortly.

### Assign a team to an item

Resolves an `UNASSIGNED_TEAM` item by assigning `teamId` as the owning team of every finding linked to the item, then completes it. Returns 400 unless the item's resolution mode is `WIDGET_TEAM_PICKER` or if the item has no linked findings. Repeating the call on an item a person already completed returns that item; an item Nullify resolved automatically returns 409. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/assign-team" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Assign a team to a repository

Resolves an `UNASSIGNED_TEAM` item by making `teamId` the owner of the item's whole repository. The team becomes the repository's only manual code owner and survives every sync. The item completes as decided. Only a dashboard user or the operator may call it; automation is refused with 403. Returns 400 unless the resolution mode is `WIDGET_TEAM_PICKER`. Requires team management permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/assign-repo" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Map a user

Resolves an `UNMAPPED_USER` item. Send exactly one of `messageUserId` (the chat user to map the git identity to; the provider is taken from the tenant's chat platform) or `serviceAccount: true`; sending both or neither returns 400. Returns 400 unless the item is a user-mapping item. Returns 409 and leaves the item open when the chat account was not stored: it was rejected earlier for this git user, the mapping already holds a different one, or another git user holds it. Requires the finding write permission. Marking a service account or replacing a stored chat account also requires user management.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/map-user" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Dismiss an action item

Moves an `OPEN` item to `DISMISSED`. `reason` is required (up to 500 characters). `disposition` is `not_now` (the default, and Manager asks again after a cooldown) or `decided` (Manager does not ask again about the same subject until someone reopens it). Only a person or the operator can record `decided`; automation gets 403. On an `UNMAPPED_USER` item, `classify` (`service_account` or `no_chat_account`) also records the identity's classification, and both that and a `decided` dismissal of such an item need user management permission. Dismissal is recoverable with [Reopen an action item](#reopen-an-action-item).

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"reason": "Owned by the platform team, tracked elsewhere", "disposition": "decided"}' \
  'https://api.<TENANT>.nullify.ai/manager/action-items/01J.../dismiss?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/dismiss" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Reopen an action item

Returns an item to `OPEN` with a required `reason`. It accepts a dismissed item, or a completed item that Nullify resolved automatically. A person or the operator can also reopen a completed, decided repository assignment; other human completions are final. An `UNMAPPED_USER` item whose identity is classified is refused with 400, and you [revoke the classification](#revoke-an-identity-classification) instead. Automation cannot reopen an item a person decided, and reopening a decided user-mapping item needs user management permission. Returns 409 when an active duplicate of the item already exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/reopen" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Nudges

### List escalation recipients

Returns the chat accounts in the tenant that are mapped to people and eligible to receive a manual nudge. Use their `id` as `recipientUserId` below. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/escalation-recipients" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Nudge an escalation

Sends another direct message for an open escalation. Optionally set `recipientUserId` and a custom `message` of up to 4,000 characters. The response has `sent` to say whether a message went out. Returns 400 when the item is not open, when no active chat account is mapped, when direct messages are disabled for the tenant (see [ground rules](/api-reference/api-reference/manager/escalations-and-config#ground-rules)), or when no Slack or Teams connection exists. Returns 409 if the escalation was nudged recently, or is being resolved; wait and try again. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/action-items/{actionItemId}/nudge" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Preview a fix pull request nudge

Shows who a reviewer nudge on a fix pull request would reach and the exact message, before you send it. The response lists candidates with whether each is `available`, the message `variant`, `sendsLeft` (the direct messages the pull request can still receive in the 30-day window across all nudges) and, when sending is not possible, a `disabledReason` such as `not_open` or `cap_reached`. `recordId` is the fix pull request record's id. Only open GitHub pull requests can be nudged. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/fix-prs/{recordId}/nudge" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Nudge fix pull request reviewers

Sends a governed direct message asking a fix pull request's reviewers to review it. Without a body it goes to the default reviewers; set `recipientUserIds` (up to 10 chat user ids) to send to specific people. The response gives an outcome per recipient: `sent`, `already_nudged`, `held_weekly_limit`, `failed` or `cap_reached`, so check each rather than the status code. Returns 429 once the pull request has used its nudges for the 30-day window and 409 if a nudge is already being sent. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/fix-prs/{recordId}/nudge" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Git identity classifications

A classification is a durable decision that a git identity is a service account or has no chat account, so Manager stops asking who it is. Classifying and revoking need an administrator, or the operator.

### List identity classifications

Returns classifications, newest first. Filter with `decision` (`service_account` or `no_chat_account`); omit it to list both.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/identity-classifications" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Classify an identity

Records `decision` for an identity given by `provider` (GitHub, GitLab, Azure or Bitbucket) and `providerUserId`, which is the provider's id for the user and not the login. An optional `reason` up to 500 characters is stored. It closes the identity's live `UNMAPPED_USER` item as decided, so the question is not asked again. Undo it with [Revoke an identity classification](#revoke-an-identity-classification).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/identity-classifications" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Revoke an identity classification

Removes the classification identified by the `provider` and `providerUserId` in the path, with an optional `reason` query parameter for the audit record. It reopens the identity's latest `UNMAPPED_USER` item and returns its id as `reopenedActionItemId`; when nothing needed reopening that field is absent, and Manager resumes asking in its daily sweep either way. Returns 404 when there is no such classification.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/identity-classifications/{provider}/{providerUserId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Campaigns, runs and events

A campaign selects a set of findings and gives Manager a goal and a time window to work through them. This page covers creating and editing campaigns, reading what they matched, following their runs, and reading or cleaning up the events Manager records. Proposed campaigns are decided on [Proposals, runs and state](/api-reference/api-reference/manager/proposals-and-runs#campaign-proposals).

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`. Page parameters are `page` and `pageSize` unless the operation says otherwise; see [Pagination](/api-reference/api-reference/pagination).

## Campaigns

### List campaigns

Returns campaigns with full details, with `page` and `pageSize`. For a lighter payload use [List campaign previews](#list-campaign-previews).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create a campaign

Registers a campaign. The body selects findings by explicit `findingIds`, by filters (`types`, `priorityLabels`, `repositoryNames`, `teamIDs`, `vulnerabilityCVEIds`, `createdAfter` and others), or both, and sets the title, description, owner, dates and limits such as `prBudgetPerWeek`. Check the embed for every field.

The campaign is created directly by the caller. It is not a proposal and does not wait for a decision. Before it is stored, the scope is evaluated against your findings: invalid input returns 400, an explicit finding id that is not eligible for Manager campaigns returns 400 and names the ids, and a failed scope query returns an error rather than a campaign that silently matches nothing. The response includes `mappedFindingCount`. A value of 0 means the campaign was stored but its criteria currently select no findings, so it will act on nothing until findings match. Requires finding write access.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"title": "Fix urgent SCA findings", "types": ["SCA"], "priorityLabels": ["URGENT"], "noEndDate": true}' \
  'https://api.<TENANT>.nullify.ai/manager/campaigns?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a campaign

Returns one campaign with its mapped finding ids and finding progress, plus a touch ledger that accounts for the campaign's autofix pull requests where available. Returns 404 for an id that does not exist for the tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a campaign

Changes only the fields you send. Empty arrays are treated as "set to empty", not "unchanged", so send only what you mean to change.

* Changing the scope, or activating a campaign that was inactive, re-evaluates which findings it maps.
* An update that would leave a previously narrowed campaign with no pinned findings and no filters would widen it to the tenant's entire backlog on the next daily run. It is refused with 400 unless you send `confirmWholeBacklog: true`.
* An omitted `exploitValidated` means unchanged. Send `clearExploitValidated: true` to remove that filter.
* `prBudgetPerWeek` of 0 removes an existing cap.
* Returns 412 if the campaign's lifecycle state has moved past what the edit assumes, and 404 if it does not exist.

Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a campaign

Permanently deletes a campaign and its preview. A proposal still open for the campaign is superseded by the delete. The call returns 429 while a singleton Manager run holds the tenant lock, so retry after the run finishes, and 404 for an unknown id. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Refresh campaign metrics

Despite being a `GET`, this recomputes and stores the counts and finding progress for the tenant's campaigns. It runs synchronously. By default expired campaigns are excluded; pass `includeExpired=true` to include them.

A 200 does not mean the counts moved. If a singleton Manager process holds the tenant lock, the call declines the work and returns `refreshed: false` with `response: "SKIPPED"` and a `skipReason`; the stored counts are still the previous run's. Check `refreshed` before treating the numbers as current.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/metrics/refresh" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Default campaigns

### Generate default campaigns

Starts the campaign generator and returns immediately with a `runId`. The generated campaigns are not in the response. Poll [Get a Manager run](/api-reference/api-reference/manager/proposals-and-runs#get-a-manager-run) until it is terminal; the finished run lists the `campaignIds` it wrote. When the call is made as a user, that user is stamped as the owner of the generated campaigns; otherwise they route to central security. Returns 429 while another generator run holds the lock. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/default/generate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List default campaigns

Returns every campaign the generator produced for the tenant, across all pages, in one response.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/default" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Previews and summaries

### List campaign previews

Returns lightweight previews with title, description and mapped finding ids, plus the tenant's finding progress. Use `limit` and `offset` to page by offset, which overrides `page` and `pageSize` when set. `total` is the number of campaign previews the tenant has. The findings list is not paginated and always returns the tenant's whole set, and `numItems` is a legacy mixed count, so use `total` for campaigns.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/previews" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a campaign preview

Returns the preview for one campaign: title, description and mapped finding ids. For the full campaign use [Get a campaign](#get-a-campaign).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List campaign summaries

Returns campaign summaries derived from plans, with `page` and `pageSize`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/summaries" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Findings in campaigns

### List a campaign's findings

Returns the ids of current and historical findings within the campaign's scope. Fetch finding detail from the owning service's findings API.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List findings across all campaigns

Returns the finding progress records for every finding across the tenant's campaigns.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Campaign runs

A campaign run is one execution of a campaign. These ids are different from the `runId` of a Manager run, though a Manager run lists the campaign runs it created in `campaignRunIds`.

### List campaign runs

Returns a campaign's run history, newest first. Page with `limit` and either `offset` or an opaque `cursor`, but not both: sending both returns 400. The response has a `total` and, when more remain, a `nextCursor`. An offset past the end returns an empty page, not an error.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}/runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a campaign run

Returns one run with its state, timing, error summary, token and tool-event counts, and the resolved plan. Returns 404 if the run does not exist or does not belong to the campaign in the path.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}/runs/{runId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Events

Events are Manager's record of what it did or attempted: opening or closing pull requests, tickets, comments and messages.

### List events

Returns one page of events across all campaigns, with `page` and `pageSize`. Exact duplicates within the page are removed from the response, so a page can be shorter than `pageSize`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List a campaign's events

Returns one campaign's events, newest first. Filter with repeated `actionTypes` (for example `PR_CREATE`, `TICKET_CREATE`) and `statuses` (for example `PENDING`, `SUCCESSFUL`, `ERROR`). `page` starts at 1 and `pageSize` defaults to 1000. `hasNextPage` says whether to continue. For the events on the returned page, `pullRequestTitles` maps pull request ids to titles, `pullRequests` maps pull request URLs to their current state (status, first recorded review, merge time), and `people` maps messaging user ids to display names.

When role-based access control is enforced for the tenant, callers whose role is limited to specific teams receive 403 ("operator access is unavailable for team-scoped roles") from this operation and from [List events](#list-events).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/campaigns/{campaignId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List a finding's events

Returns the events recorded against one finding, using `limit` (default 100, maximum 1000) and an opaque `cursor` from the previous response's `nextCursor`. The same `actionTypes` and `statuses` filters apply. Use it to answer what Manager has done about a particular finding.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete an event

Deletes one event by id. Returns 404 for an unknown id. An event that the campaign pace ledger is derived from is protected and returns 412; it cannot be deleted. Requires finding write access, and deletion is permanent.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/events/{eventId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Deduplicate events

Removes duplicate events and reports counts. This deletes data, so run it first with `"dryRun": true` and check `totalDupes`. `keep` is `latest` or `earliest`, and anything else keeps the earliest. `from`, `to` and `statuses` narrow the scan, and `timeoutSeconds` is capped at 60. A timeout is not an error: you get the partial counts and a message saying it timed out, and you can call again. Duplicates that the pace ledger derives from are counted as `totalProtected` and are never deleted, so they will be found again on every run. Requires finding write access.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"dryRun": true, "keep": "earliest"}' \
  'https://api.<TENANT>.nullify.ai/manager/events/deduplicate?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/events/deduplicate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Operator chat

Operator chat is the conversation surface for working with Manager: a general chat per user, and one chat bound to each action item. These operations manage sessions and read what happened in them. Messages are exchanged over the chat WebSocket in the Nullify app, not through this API, so there is no operation here that posts a message.

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`, and requires a signed-in user identity. A token with no user behind it receives 400 ("user ID is required"). Sessions belong to the user who created them: listing returns only the caller's sessions, and changing or deleting a session requires being its owner. When role-based access control is enforced for the tenant, callers with team-limited roles receive 403, as for [action items](/api-reference/api-reference/manager/action-items).

## Starting a chat

### Get or create the general chat

Returns the caller's single Operator General chat, creating it on the first call. It is idempotent, so you can call it every time you need the id. The response has only `chatId`; the server mints the id.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/general" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

For a chat tied to an action item, use [Get or create an action item chat](/api-reference/api-reference/manager/action-items#get-or-create-an-action-item-chat).

## Sessions

### List chat sessions

Returns the caller's chat sessions. Page with `limit` (default 50) and the `nextToken` returned by the previous page; see [Pagination](/api-reference/api-reference/pagination).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a chat session

Returns one session by `chatID`. Reads are scoped to the tenant. An unknown id, or one from another tenant, returns 404.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Rename a chat session

Updates the session's `title`, which is required and cannot be empty. Only the session's owner can do this; for anyone else the session is reported as not found (404).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a chat session

Deletes the session and its chat history. This is permanent and only the owner can do it (404 for anyone else). A session that an open action item is using returns 412; resolve or dismiss the action item first.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Reading a session

### Get chat history

Returns the session's messages with `page` (from 1) and `pageSize` (default 100) and a `hasMore` flag.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}/history" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get chat actions

Returns the actions the chat proposed to take on your behalf and their current state: `toolName`, `description`, `params`, `severity`, `status`, `result`, whether it is still `executable`, and who resolved it. Read `status` and `result` to find out whether a requested action happened. A message in the conversation saying that it did is not proof.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}/actions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the chat audit trail

Returns the audit records of tool calls made in the session, with `limit` (default 100) and `nextToken` for the next page.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/chat/sessions/{chatID}/audit" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Configuration, ground rules and escalations

These operations control how much Manager does on its own and where it sends escalations. For what each setting means for your program, see [Manager configuration](/configuration/configuration-manager). The standing policy for autonomy and capacity is the [security program](/api-reference/api-reference/manager/program-and-strategy#security-program).

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`. Reads require configuration read access and writes require configuration write access.

## Manager configuration

### Get the Manager configuration

Returns the tenant's Manager configuration. `enableActions: false` means preview mode, where Manager works out what it would do without taking those actions. A tenant that has never stored a configuration gets an empty object, which has `enableActions: false` and `initialized: false`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/config" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update the Manager configuration

Stores the configuration. Despite being a `POST`, it replaces the stored values from the body: send both `enableActions` and `initialized`, because an omitted `enableActions` is stored as `false` and turns Manager back to preview mode. The call creates the configuration if none exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/config" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Ground rules

Ground rules switch off specific kinds of action. Each flag set to `true` stops Manager doing that thing for the tenant: opening, closing or commenting on pull requests, creating, closing or commenting on tickets, posting channel messages, sending direct messages, and selecting reviewer candidates.

### Get the ground rules

Returns the tenant's ground rules, or `null` when none have been stored. There is a single ground rules document per tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/groundrules" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create or replace the ground rules

Stores the ground rules. If a document already exists it is overwritten with the body, keeping its id and creation time. Send every `disable*` flag, because omitted booleans are stored as `false`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/groundrules" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update the ground rules

Updates the existing ground rules with `PATCH`, returning 404 if none have been stored yet. The body replaces the whole stored document and is not a field-by-field merge, so a flag you omit is reset to `false`. Read the current rules, change the flags you want, and send them all back.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/groundrules" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Escalation routing

Escalations are what Manager raises when a finding needs a person. Routing decides whether they arrive as a direct message, a channel post, or both.

### Get the escalation configuration

Returns the routing, with `mode` of `dm`, `channel` or `both` and, for channel delivery, the `channelId` and `channelName` on your connected chat platform. A tenant that has not set one gets `dm`. There is no operation that lists individual escalations; use [List action items](/api-reference/api-reference/manager/action-items#list-action-items).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/escalations/config" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set the escalation configuration

Replaces the routing. `mode` must be `dm`, `channel` or `both`, and an empty mode means `dm`. A mode that includes a channel requires `channelId`; otherwise the call returns 400. The response carries no routing body, so read it back with the `GET` call if you need to confirm it.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/escalations/config" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Onboarding

### Report onboarding wizard progress

Tells Nullify that your team completed an onboarding wizard step. It is used by the Nullify onboarding wizard and does not change your configuration. `step` is one of `connect-codebases`, `select-repositories`, `connect-workflows`, `configure-cloud`, `questionnaire` or `ready-to-start`, and an optional `detail` adds context. The call fails open: `posted` is `false` with a `skipReason` when the message could not be sent, and a failed post never returns an error. An unknown step returns 400. Requires configuration write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/onboarding/wizard-progress" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Program and strategy

The security program is the standing policy for how Manager operates. A strategy is a four-quarter plan that Manager's campaigns serve. Read both before you change either, and read [Approvals and decisions](/api-reference/api-reference/manager#approvals-and-decisions) first if you intend to accept or reject a proposal.

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`. Requests without one are rejected with 400.

## Security program

The program records the autonomy policy, capacity limits and review cadence. It is separate from [ground rules](/api-reference/api-reference/manager/escalations-and-config#ground-rules), which switch individual action types on and off.

### Get the security program

Returns the tenant's program. A tenant that has never stated one gets the default, which delegates nothing, so the call always returns a program. Requires configuration read access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/program" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### State the security program

Sets or replaces the program with `PATCH`. Despite the method, every field is required: `autonomy` (`explicit`, `announce_with_window` or `auto_within_boundaries`), `announceWindowDays`, `minCoveragePerGoal`, `maxConcurrentCampaigns`, `defaultCampaignDays` and `reviewCadenceDays`, each at least 1. `capacityPerWeek` is optional and omitting it means unknown. A partial body is rejected with 400 rather than merged. Requires configuration write access; the change is recorded against the calling user.

`autonomy` controls what Manager may do after you accept a strategy. It never lets Manager accept a strategy for you: strategy acceptance is always an explicit decision.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/program" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Active strategy

### Get the active strategy

Returns the strategy currently in force, which is the latest accepted version. Returns 404 when the tenant has no accepted strategy. A proposed version is not returned here; read it with [Get the proposed strategy](#get-the-proposed-strategy).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Edit the active strategy

`PATCH /manager/strategy` replaces the strategy's quarters and writes the result as a new version. The body's `quarters` must hold exactly four entries, each with a label, and at least one quarter must have non-empty goals; otherwise the call returns 400.

This is a direct edit, not a proposal. The new version is accepted and in force as soon as the call succeeds, attributed to the caller, and it does not go through the decision endpoint. It also does not repoint the security program at the new version. Only one strategy write can run at a time: if a generation run or another edit holds the strategy lock, the call returns 429 and you can retry. Requires configuration write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List strategy versions

Returns historical versions, newest first, with `page` (from 1) and `pageSize` (default 20). Each version has an `id`, a `version` number and a `status` such as `PROPOSED`, `ACCEPTED`, `REJECTED` or `SUPERSEDED`, plus who wrote and accepted it. Use it to find the `id` of a version rather than guessing from the version number.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy/versions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Strategy proposals

### Generate a strategy proposal

Starts the strategy agent and returns immediately with a `runId`. A run that is accepted by this call has not produced anything yet. Poll [Get a Manager run](/api-reference/api-reference/manager/proposals-and-runs#get-a-manager-run) until `terminal` is true; the finished run reports the `strategyId` and `strategyVersion` it wrote. A version written by an agent starts as `PROPOSED` and has no effect until it is explicitly accepted.

The call returns 429 if another Manager run holds the tenant lock; wait and retry. Requires finding write access.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/manager/strategy/trigger?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the proposed strategy

Returns the strategy version waiting on a decision, or a response with no `proposal` when nothing is pending. Pending is not an error. Requires configuration read access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy/proposal" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Decide the proposed strategy

Accepts or rejects a proposed version. The body names the version being decided (`strategyId`) and a `decision` of `accept` or `reject`.

* `strategyId` must be the version that is currently proposed. If it is already decided, superseded, unknown, or belongs to another tenant, the call returns 412 and changes nothing. All of those cases return the same error on purpose, so re-read the proposal with [Get the proposed strategy](#get-the-proposed-strategy) rather than retrying with the same id.
* Accepting puts the version in force, retires any other pending version, and records it on the security program as the version its autonomy was agreed against. It also closes the matching strategy-proposal action item.
* Rejecting leaves the previous strategy in force.
* The decision cannot be repeated. A second call with the same id returns 412.

The decision is recorded against the caller. Requires configuration write access, which is stricter than the campaign decision.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"strategyId": "01J...", "decision": "accept"}' \
  'https://api.<TENANT>.nullify.ai/manager/strategy/proposal/decision?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/strategy/proposal/decision" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Proposals, runs and state

Manager proposes campaigns, waits for a decision, and does its work in asynchronous runs. This page covers listing and deciding campaign proposals, starting runs and following them to completion, and reading Manager's state, plans and metrics. Strategy proposals are decided on [Program and strategy](/api-reference/api-reference/manager/program-and-strategy#strategy-proposals).

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`.

## Campaign proposals

### List open proposals

Returns campaign proposals that are still waiting on a decision (status `PROPOSED` or `REVISED`), newest round first. Each item carries the proposal itself, the quarter goal it serves and a summary of the campaign it points at. A proposed strategy version is not listed here. Requires configuration read access.

The `id` of each item's `proposal` is the `proposalId` the decision call expects.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/proposals" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Decide a proposed campaign

Accepts or rejects one proposed campaign. The body has `proposalId` and a `decision` of `accept` or `reject`.

The campaign already exists in the `PROPOSED` lifecycle state while it waits, claiming nothing. Accepting moves it to `ACTIVE`, and rejecting moves it to `CANCELLED`. Neither call creates a new campaign, and generating the proposal was never approval to run it.

* A proposal that is already decided, unknown, or belongs to another tenant returns 412. These cases are indistinguishable on purpose.
* A proposal whose campaign has since been deleted, started, or cancelled also returns 412 and the open proposals that can no longer be decided are retired. Re-read [List open proposals](#list-open-proposals) before retrying.
* A proposal of another kind, such as a strategy proposal, returns 400. Use [Decide the proposed strategy](/api-reference/api-reference/manager/program-and-strategy#decide-the-proposed-strategy) for those.
* A decision cannot be repeated or reversed through this endpoint.

The decision is recorded against the caller. Requires finding write access.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"proposalId": "01J...", "decision": "accept"}' \
  'https://api.<TENANT>.nullify.ai/manager/proposals/decision?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/proposals/decision" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Starting runs

Every start operation returns as soon as the run is accepted, with a `runId` and an `executionArn`. The run has not finished and may still write nothing. Follow it with [Get a Manager run](#get-a-manager-run).

All of them refuse to start, with 429, while a singleton Manager process holds the tenant lock for that kind of run, and `POST /manager/trigger` also refuses while the ticket reconciler is working on the tenant. Wait and retry. They require finding write access.

### Start a Manager run

Starts a Manager run for the tenant. `mode` selects the workflow: `full` (the tenant-wide sweep), `campaigns`, `tacit_knowledge`, `threat_intel`, `strategy`, `strategy_explore`, `action_items` or `plan_preview`. Any other value returns 400. Omitting `mode` runs the full sweep, or a single-campaign run when `campaignId` is set. `strategy_explore` proposes the campaigns that would deliver the strategy already in force, and it is the only mode that does so.

`evaluationTime` overrides the instant Manager treats as now when judging staleness for escalations and nudges. It must be within 90 days of the current time. Leave it unset unless you are replaying a scenario.

Whether a run takes outward actions such as opening pull requests or messaging people is governed by [Manager configuration and ground rules](/api-reference/api-reference/manager/escalations-and-config), not by this call.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{"mode": "strategy_explore"}' \
  'https://api.<TENANT>.nullify.ai/manager/trigger?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start a daily summary run

Starts a run that writes the tenant's daily summary for an `audience` (`internal` or `customer`, required) and posts it to the channel configured for that audience. Returns 412 if the tenant has nowhere to deliver that audience's summary or the audience is switched off, and 503 if delivery fails.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/daily-summary/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start a tacit knowledge run

Starts a run that processes findings and generates questions for your team, which appear as action items. Unlike the other start operations, this one returns only a message: there is no `runId` to poll, so watch [List action items](/api-reference/api-reference/manager/action-items#list-action-items) for new items instead.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/tacit-knowledge/trigger" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Following a run

### Get a Manager run

Returns the state of a strategy, campaign-generation or campaign run started by one of the operations above or by [Generate default campaigns](/api-reference/api-reference/manager/campaigns#generate-default-campaigns), and what it wrote: `strategyId`, `strategyVersion`, `campaignIds` and `campaignRunIds`.

Poll until `terminal` is `true`. `state` is one of `PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `SKIPPED`, `TIMED_OUT` or `ABORTED`; `FAILED`, `TIMED_OUT` and `ABORTED` carry an `error` where one is known. A run that succeeded without writing what its mode produces is reported as `SKIPPED`, with the reason in `detail`, so treat `SKIPPED` as a successful run that did nothing. An unrecognized execution status is reported as `PENDING` rather than terminal, so keep polling.

`runId` must be a ULID; anything else returns 400. A run another tenant started returns 404. The `campaignRunIds` can be read with [Get a campaign run](/api-reference/api-reference/manager/campaigns#get-a-campaign-run).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/runs/{runId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## State, plans and metrics

### Get the Manager state

Returns the current state of Manager for the tenant. Returns 404 when no plan summary exists yet, which is the normal answer before the first run completes.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/state" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the Manager state (legacy)

A deprecated alias for [Get the Manager state](#get-the-manager-state) at the older `/manager/state/latest` path with the same behavior. Use `/manager/state` in new integrations.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/state/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List Manager state history

Returns earlier Manager states, with `page` (from 1) and `pageSize` (default 10).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/states" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List plans

Returns Manager's plans, optionally limited to one campaign with `campaignId`, with `page` and `pageSize`. A plan is the scheduled work Manager resolved for a run; campaign summaries and previews are derived from it.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/plans" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get metrics

Returns cumulative Manager metrics for the tenant: event aggregates, merged pull request and resolved ticket counts, findings in backlog, in progress and resolved, and mean and median remediation timings. Treat the response schema as authoritative for field meanings.

By default the figures are current. Pass `asOf` (an RFC 3339 timestamp) to compute them as of that instant. `asOf` bounds when work counts as resolved, not when a finding was created, so findings that appeared after the cutoff stay unresolved in the result instead of being excluded. `prMergedCount` is measured from real pull request state while `prCreateCount` is an event counter, so the merged count can exceed the created count; the response does not clamp it. An invalid `asOf` returns 400. `timeSaved` is deprecated and equals `totalRemediationDuration`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/metrics" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Threat intelligence

Threat intelligence lets Manager assess whether a newly published threat affects your environment. There are two related surfaces: a shared catalog of published threats that each tenant can assess for itself, and threat investigations, which are your tenant's own records of an assessment and any remediation.

Every operation takes the tenant's provider scope as query parameters, such as `githubOwnerId`.

## Published threat catalog

### List catalog threats

Returns a page of the shared threat catalog joined with your tenant's assessment. `page` starts at 1 and `pageSize` defaults to 20 with a maximum of 100; larger values return 400. Filter by `cveId`, `ecosystem` (any case) or `severity`; by `verdict` (`affected` for threats your assessment found affecting a repository); by `kind` (`malware`, `vulnerability` or `campaign`); and by the advisory's publication date with `publishedAfter` (inclusive) and `publishedBefore` (exclusive), each `YYYY-MM-DD` or RFC 3339. `sort` is `published` (the default, newest advisory first) or `researched`. `total` is the filtered count; past `pageableTotal`, the deepest the catalog pages, it is a floor. `appliedFilters` names the `verdict`, `kind` and date filters the response applied, and `sort` the order it used. A 412 means the shared threat database cannot apply a requested filter yet.

Each entry's `status` is `NOT_ASSESSED`, `QUEUED`, `INVESTIGATING`, `FAILED`, `AFFECTED`, `NOT_AFFECTED`, `UNKNOWN`, `DISABLED` (automatic investigations are off for your tenant), `NOT_RUN` (an assessment was queued but never started within its window; you can retry it) or `WITHDRAWN` (the source advisory was withdrawn). `UNKNOWN` is what you get when the inventory was incomplete or out of date, so missing evidence is never reported as clean; check `inventoryFreshness` and `isOutdated` before treating `NOT_AFFECTED` as final. The `investigationId`, when present, is the id to read with [Get a threat investigation](#get-a-threat-investigation).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threats" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Investigate a catalog threat

Requests an assessment of a published threat in your environment. `threatId` is the catalog entry's id and `action` is required: `investigate`, `retry` or `reinvestigate`.

* The call queues the assessment and returns the tenant's investigation straight away. The assessment is not complete yet. Poll [List catalog threats](#list-catalog-threats) for the entry's `status`, or [Get a threat investigation](#get-a-threat-investigation).
* `investigate` on a threat already assessed at the current research version returns the existing investigation without a new run. If an assessment is already running, the existing investigation is returned as well.
* `retry` only applies to a failed assessment and returns 400 otherwise.
* `reinvestigate` runs again, for example after a research update.

Only a signed-in user or the operator can call it; other callers receive 403. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threats/{threatId}/investigate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Reporting a threat

A report submits public facts about a threat for shared verification. Do not send tenant evidence. See [Reporting a Threat](/capabilities/threat-intelligence/reporting-a-threat) for what happens to a report.

A report is identified by its `advisoryId`: the threat's own id when it matches a threat Nullify holds, otherwise `NULLIFY-R-` followed by 16 hexadecimal characters until it links to a published threat. `status` is the report's progress and `verification` (`pending`, `verified`, `known`, `unverified` or `withdrawn`) says whether public sources supported it; `verificationReason` explains an unverified result.

### Report a threat

Submits a public advisory or a campaign. `requestId` (a UUID you generate) is always required. An advisory report needs `advisoryUrl`. A campaign report sends `campaign` instead, with a `title` (up to 200 characters), a `description` (up to 4,000), one to five public `referenceUrls`, and optionally up to 10 `cveIds` and up to 20 `packages`; it moves from `pending` to `matched`, `not_found` or `not_verifiable`. For an advisory report, `cveId`, `packageName` and `ecosystem` are optional and limited to 32, 200 and 40 characters, and the URL to 2,048. Keep the `requestId` to look the report up later. `existing` in the response says whether the report matched a threat that was already recorded. The response gives the `threatId`, `researchVersion` and verification `status`. A rejected report returns 400, and exceeding the report quota returns 429. Only a signed-in user or the operator can call it. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-reports" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a threat report

Returns the verification status of one of your tenant's submissions by `requestId`. Returns 404 for an unknown id or another tenant's submission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-reports/{requestId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Resubmit a threat report

Resubmits a report once, when `resubmittable` is true: its submission failed, or research was unavailable. A report that cannot be resubmitted returns 412.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-reports/{requestId}/resubmit" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List reported threats

Returns your tenant's submissions with `page` and `pageSize` and the full `totalCount`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-reports" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Threat investigations

An investigation moves through `PENDING`, `INVESTIGATING`, `INVESTIGATED`, `REMEDIATING` and `RESOLVED`, or `FAILED`. Its client impact lists the repositories and findings that are exposed.

### Create a threat investigation

Creates an investigation and queues the research. Provide a `title` (required) and optionally `cveIds`, `severity`, `cvss`, `ecosystem`, `affectedPackages`, `articleLinks`, `advice` and `keywords`. Links and package source URLs must be absolute http or https URLs, otherwise the call returns 400. Without `keywords` or `affectedPackages` the title is used as the keywords. With `affectedPackages` and no `keywords`, Manager runs the deterministic exposure check on exactly those packages without web research.

The response returns the new investigation, which is still pending its research. Poll [Get a threat investigation](#get-a-threat-investigation). If an equivalent investigation already exists the call returns it with `existing: true` rather than creating a duplicate. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-investigations" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List threat investigations

Returns your tenant's investigations with `page` and `pageSize`, or `limit` and `offset`, which override them when set. Filter with `search` (a case-insensitive match on title, CVE, package or ecosystem), `severity`, `ecosystem` and `status`. `total` is the whole count regardless of the window.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-investigations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a threat investigation

Returns one investigation with its events. Set `includeVersions=true` to also return earlier assessment versions, paged with `versionLimit` (default 20) and `versionOffset`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-investigations/{threatInvestigationId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Act on a threat investigation

Performs an `action` on an investigation:

* `reinvestigate` (or `refresh_research`) re-runs the research and `refresh_impact` re-checks which repositories are affected. Both are asynchronous: they queue a run and return the investigation. They return 409 if a run is already in progress.
* `activate` starts remediation. It only works on an `INVESTIGATED` investigation that has affected repositories and findings eligible for Manager campaigns; otherwise it returns 400, with a hint to run `refresh_impact` when scanner findings are still pending. It creates an active campaign titled "Remediate: ..." with no end date for those findings, sets the investigation to `REMEDIATING`, and tries to start a Manager run for the campaign straight away. This is a direct action by the caller and does not create a proposal. If the immediate run cannot be started, the campaign is picked up by the next scheduled run.
* `notify` approves posting the held Slack notifications for an investigation in `INVESTIGATED`, `REMEDIATING` or `RESOLVED` status, and starts a notify-only run.

Any other action returns 400, and an unknown investigation returns 404. Requires finding write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/manager/threat-investigations/{threatInvestigationId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Code Review API

Query code review findings and events via the Nullify API

For PR and default-branch scanning, see [scan coverage, start operations and completion checks](/api-reference/api-reference/orchestrator#scan-coverage-by-type).

> Existing endpoints retain the `/sast` prefix for backwards compatibility. New wrappers will be introduced over time without breaking the current contract.

## Base URL

All endpoints share the base URL: `https://api.<TENANT>.nullify.ai`. Replace `<TENANT>` with your tenant slug (for example `https://api.acme.nullify.ai`).

## Conventions

* **Provider scope.** Every call identifies the connected provider account with one scope query parameter: `githubOwnerId` for GitHub, or `azureOrganizationId`, `bitbucketWorkspaceId`, `gitlabGroupId` or `installationId` for the other providers. The examples use `githubOwnerId=1234`.
* **Repository scope.** To narrow a list to specific repositories, add `githubRepositoryId` (repeatable) or `githubTeamId` (all repositories the team can access) to the scope parameters. For `/sast/findings` and `/sast/findings/preview` the `repositoryIds` parameter in the specification is not read by the handler, so use these scope parameters instead. `/sast/findings/detailed` takes a single `repositoryId`.
* **Pagination.** List calls accept `limit` and `nextToken` (see [Pagination](/api-reference/api-reference/pagination)). `limit` defaults to 100 and a value above 100 returns 400. `sort` is `asc` or `desc` (default `desc`).
* **Permissions.** Reads need finding read access. Updates, allowlisting, tickets and autofix need finding write access.
* **Finding IDs.** Take `findingId` from `GET /sast/findings`. An ID that does not exist in your tenant returns 404.

## Events

### List events

Receive a stream of notable code-review activity (new findings, fixes, suppressions, branch summaries). Pass `fromTime` as a UTC timestamp such as `2025-01-31T00:00:00Z`, and filter with `eventType`, `findingId` and `fileOwnerName`. A page holds at most 100 events, so keep following `nextToken` to read on. `fileOwnerName` is applied after a page is fetched, so a filtered page can hold fewer events than `limit` while `nextToken` is still set.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/events?githubOwnerId=1234'
```

## Findings

### List findings

List findings with filtering by branch, severity, priority, state and file owner. The list returns previews; call [Get a finding](#get-a-finding) for the full record. Only push-workflow findings are returned unless you set `workflow`, and findings in deactivated repositories are left out. `sortBy` is `priority` (default) or `time`. State filters include `isResolved`, `isFixed`, `isFalsePositive`, `isAllowlisted`, `isArchived`, `aiGenerated` and `autoFixState`; `isLatest` defaults from `isFixed`. `fileOwnerName` is applied after a page is fetched, so a filtered page can be shorter than `limit`. `GET /sast/findings/preview` is a deprecated alias of this operation.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings?githubOwnerId=1234&severity=high'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List findings with full detail

Returns complete finding records rather than previews, for exports and integrations that need every field in one pass. It takes a single `repositoryId`, most of the list call's state and severity filters, and a `language` filter; `sortBy` is `priority` (default) or `time` and the workflow defaults to push. Unlike the list call, it does not hide findings in deactivated repositories.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding

Retrieve full context for a single finding, including reachability evidence and ownership metadata. The response also carries a `presignedUrl` for the stored triage document when one exists. Unknown or other-tenant IDs return 404.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Update a finding

Override a finding's priority or severity. The request accepts `priorityOverride` (`URGENT`, `IMPORTANT`, `MEDIUM`, `INFORMATIONAL`, `LOW`, `NEGLIGIBLE`, `FALSE_POSITIVE`, `UNKNOWN`) and `severityOverride` (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `NONE`, `INFORMATIONAL`, `UNKNOWN`). An invalid value returns 400. The response is the updated finding.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"severityOverride": "HIGH"}' \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Get triage details

Retrieve the AI triage reasoning and reachability assessment for a finding. The response carries `triageStatus` (`pending`, `completed` or `failed`). While triage has not completed, `finding` is empty. Poll with a bounded timeout while the status is `pending`; this can also mean triage has never run. Stop on `failed` and inspect `stopReason`. This GET does not start or retry triage; use [Retriage findings](/api-reference/api-reference/orchestrator#retriage-findings) to request another attempt. A completed response also includes a `presignedUrl` and mapped vulnerability-management frameworks.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/triage?githubOwnerId=1234'
```

### List users associated with a finding

Returns up to three candidate people for routing the finding, ranked from git blame on the finding's lines, then other editors of the same file, then repository contributors, each with a `reason`. Providers that cannot supply blame data fall back to repository contributors.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List finding events

Review every decision applied to a finding (status changes, tickets, suppressions). The response is not paginated.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/events?githubOwnerId=1234'
```

## Triage and allowlisting

### Allowlist a finding

Apply a policy exception when you accept the risk for a finding. Supply an `allowlistReason` (required) and an `allowlistType` (`AI`, `UserFixed`, `UserAssumeRisk`, `UserFalsePositive`, or `UserOther`). Allowlisting marks the finding resolved, discards any cached autofix for it, emits an allowlist event, and best-effort closes an open ticket for the finding. A ticket-close failure does not fail the call.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"allowlistReason": "Risk accepted for legacy service", "allowlistType": "UserAssumeRisk"}' \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/allowlist?githubOwnerId=1234'
```

### Allowlist findings in bulk

Allowlist multiple findings in a single call. The body adds a `findingIds` array alongside `allowlistReason` and `allowlistType`; an empty array or empty reason returns 400. The findings are processed concurrently and the call is not atomic: if one ID is unknown the call returns 404, but findings processed before the failure stay allowlisted. A success returns 204 with no body.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"findingIds": ["01J6EEXK3NKYKWW9XTPQYAF41N", "01J6EFVQN34BCEAHDJTE4F9Y22"], "allowlistReason": "Risk accepted for legacy service", "allowlistType": "UserAssumeRisk"}' \
  'https://api.<TENANT>.nullify.ai/sast/findings/allowlist?githubOwnerId=1234'
```

### Remove a finding from the allowlist

Re-activate alerting for a previously allowlisted finding. Supply an `unallowlistReason` (required). The finding is resolved again only if it is also archived, a false positive or no longer the latest version. A ticket that was closed by the allowlist is reopened, or a new linked ticket is created if the old one cannot be reopened. Success returns 204.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"unallowlistReason": "Risk needs renewed review"}' \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/unallowlist?githubOwnerId=1234'
```

## Tickets

### Create a ticket

Create a ticket for the finding on the tenant's configured ticket integration. The body is optional and accepts `message`, `assignees`, `project`, `campaignId` and `campaignTitle`. A finding that already has a ticket on that provider returns 400. Errors to expect: 501 when no ticket integration is configured, 412 when the integration is disabled, needs reconnecting, or requires an assignee you did not supply, and 503 or 504 when the ticket provider is temporarily unavailable. The response is the created `ticket`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a ticket

Close the finding's ticket on the ticket integration and clear Nullify's link to it. The call is idempotent: a finding with no ticket returns 200 and does nothing. It returns 501 when no ticket integration is configured.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Autofix

Autofix generates a fix for a finding and opens a pull request. It runs asynchronously: the trigger call returns once the run is accepted, and you follow progress with the status, state and activity calls below.

### Trigger autofix

Starts autofix for the finding and returns `autoFixState` (normally `in_progress_requested`) and a `runId`. Optional body fields are `message` (guidance for the agent), `force` and `originCampaignId`. Refusals: 409 when a run is already in flight, a pull request is already open, or the finding is resolved; 400 when the agent previously judged the finding not fixable and you did not set `force`, or set `force` without a `message`; and 412 when the repository is archived.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/autofix/fix" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/autofix/fix?githubOwnerId=1234'
```

### Get autofix status

Lightweight lifecycle status for polling, including `state`, `terminal` (true once the run has stopped progressing), whether the finding is auto-fixable, the autofix pull requests, and available actions. It also rescues runs stuck in an in-progress state. Poll this every few seconds until `terminal` is true.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/autofix/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/findings/01J6EEXK3NKYKWW9XTPQYAF41N/autofix/status?githubOwnerId=1234'
```

### Get autofix state

The authoritative autofix state. In addition to the status checks it reconciles recorded pull requests with the git platform, so it is slower; poll it on a long interval (the dashboard uses about 30 seconds) rather than in a tight loop.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/autofix/state" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List autofix activity

Cursor-paginated log of what the autofix run did, for progress displays. `limit` defaults to 50 and is clamped to 1 to 200. Pass the `nextCursor` from the previous response as `since_id` to fetch only newer entries. The list is empty when no run exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/autofix/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the proposed fix diff

Returns the cached fix as file diffs, with the pull request title and body, explanation and base commit. It returns 400 when no cached fix exists, so check the autofix status first.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/findings/{findingId}/autofix/cache/diff" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Repositories and scan runs

### List repositories

Enumerate the repositories Code Review is scanning, along with their stats. Results are returned as a map keyed by repository ID. `limit` defaults to 10 and the maximum is 10 (larger values return 400), so follow `nextToken` to read on.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/repositories?githubOwnerId=1234'
```

### Get repository stats

Returns the stats for one repository. Take `repositoryId` from the list call; an unknown ID returns 404.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/repositories/{repositoryId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List scan runs

Lists scan runs for one repository, with status, trigger, branch, commit and counts of live, new, fixed, reintroduced and allowlisted findings plus severity totals. `repositoryId` is required. This list uses offset paging: `limit` defaults to 10 and is capped at 50, `offset` skips rows, `sort` is `newest` (default) or `oldest`, and `from` and `to` are RFC 3339 bounds on the start time. The response includes `totalCount`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sast/scan-runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sast/scan-runs?githubOwnerId=1234&repositoryId=5678&limit=10'
```

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                            | Operation                         |
| -------- | ----------------------------------------------- | --------------------------------- |
| `GET`    | `/sast/events`                                  | Get SAST Events                   |
| `GET`    | `/sast/findings`                                | Get SAST Findings                 |
| `POST`   | `/sast/findings/allowlist`                      | Allowlist Batch of SAST Findings  |
| `GET`    | `/sast/findings/detailed`                       | Get Findings Detailed             |
| `GET`    | `/sast/findings/preview`                        | Get SAST Findings                 |
| `GET`    | `/sast/findings/{findingId}`                    | Get Finding                       |
| `PATCH`  | `/sast/findings/{findingId}`                    | Update Finding                    |
| `POST`   | `/sast/findings/{findingId}/allowlist`          | Allowlist Finding                 |
| `GET`    | `/sast/findings/{findingId}/autofix/activity`   | Get SAST Finding Autofix Activity |
| `GET`    | `/sast/findings/{findingId}/autofix/cache/diff` | Get Finding Autofix Diff          |
| `POST`   | `/sast/findings/{findingId}/autofix/fix`        | Post Finding AutoFix              |
| `GET`    | `/sast/findings/{findingId}/autofix/state`      | Get SAST Finding Autofix State    |
| `GET`    | `/sast/findings/{findingId}/autofix/status`     | Get SAST Finding Autofix Status   |
| `GET`    | `/sast/findings/{findingId}/events`             | Get Finding Events                |
| `DELETE` | `/sast/findings/{findingId}/ticket`             | Delete Ticket                     |
| `POST`   | `/sast/findings/{findingId}/ticket`             | Create Ticket                     |
| `GET`    | `/sast/findings/{findingId}/triage`             | Get Triaged Finding               |
| `POST`   | `/sast/findings/{findingId}/unallowlist`        | Unallowlist Finding               |
| `GET`    | `/sast/findings/{findingId}/users`              | Get Finding Users                 |
| `GET`    | `/sast/repositories`                            | Get Repositories                  |
| `GET`    | `/sast/repositories/{repositoryId}`             | Get Repository Stats              |
| `GET`    | `/sast/scan-runs`                               | List Scan Runs                    |


# Dependency Analysis API

Query dependency analysis events and findings via the Nullify API

For PR and default-branch scanning, see [scan coverage, start operations and completion checks](/api-reference/api-reference/orchestrator#scan-coverage-by-type).

> Current endpoints use both the `/sca` and `/context/deps` prefixes. The `/sca` endpoints cover detailed findings, triage, remediation, CVE exposure and threat intelligence, while the `/context/deps` endpoints cover dependency exposure and source history.

## Base URL

`https://api.<TENANT>.nullify.ai`

## Conventions

* **Provider scope.** Calls are scoped to one source-control account. Pass the query parameter for your provider: `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId`, or `installationId`. List calls also accept repository filters such as `githubRepositoryId` and `githubTeamId`.
* **Permissions.** List and read operations need finding read access. Operations that change a finding (update, allowlist, tickets, autofix) need finding write access and return 403 without it.
* **Finding IDs.** `{findingId}` comes from the finding list calls. A finding that does not exist in your tenant returns 404.
* **Pagination.** Finding lists and `/sca/events` use `nextToken` and `limit` (maximum 100, see [Pagination](/api-reference/api-reference/pagination)). The CVE, threat-feed and scan-run lists use `offset` instead, and `/sca/repositories` allows a `limit` of at most 10.
* **Dependency and container findings.** Every finding operation exists twice: `/sca/dependencies/findings/...` for package findings and `/sca/containers/findings/...` for container image findings. The container variants behave like the dependency ones unless noted.

## Active dependencies and history

### List active dependencies

List org wide active package dependencies (paginated), available under the `/context/deps` namespace:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/active" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/deps/active?githubOwnerId=1234'
```

### List dependency history

List org wide dependency occurrence windows (paginated):

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/deps?githubOwnerId=1234'
```

### Get package exposure

List projects with dependency exposure (active and historical) matching the ecosystem/package & semver range query:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/context/deps/exposure" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/context/deps/exposure?githubOwnerId=123&ecosystem=npm&name=react&range=>=0.0.0'
```

## Dependency findings

### List findings

Fetch the current dependency findings. The response contains finding previews, so call [Get a finding](#get-a-finding) for the full record. Filters are `package`, `branch`, `workflow`, `isFalsePositive`, `isFixed`, `isAllowlisted`, `isResolved` (fixed, false positive or allowlisted), `hasMultipleVersions`, `autoFixState` (for example `none` to find findings with no cached fix) and repeatable `fileOwnerName`. Sort with `sortBy` (`time` or `priority`) and `sort` (`asc` or `desc`, default `desc`). `limit` defaults to and is capped at 100; follow `nextToken` for further pages. Findings in repositories that are no longer active are left out.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings?githubOwnerId=1234'
```

### List findings (preview alias)

`GET /sca/dependencies/findings/preview` is a deprecated alias that runs the same handler and accepts the same parameters as the list call above. Use `/sca/dependencies/findings` in new integrations.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List findings in full (deprecated)

`GET /sca/dependencies/findings/detailed` returns complete finding records instead of previews, with the same filters and pagination, plus a `repositoryId` filter for a single repository. Its title marks it as deprecated and scheduled for removal, so list previews and fetch individual findings instead.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding

Retrieve the full record for one finding, including the affected package, versions, and fix information:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Update a finding

Override a dependency finding's priority or severity. The request accepts `priorityOverride` (for example `URGENT`, `IMPORTANT`, `MEDIUM`, `LOW`) and `severityOverride` (for example `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`); the embed lists every accepted value, and an unrecognized value returns 400. The updated finding is returned.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"severityOverride": "HIGH"}' \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Finding events

Retrieve the decision history for a specific finding. The response is the complete list of events for the finding and is not paginated:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/events?githubOwnerId=1234'
```

### Get related users

Suggests up to three people to involve: authors of recent edits to the file that contains the dependency, topped up with repository contributors (or contributors alone on providers without blame support). Set `sourceOwnerOnly=true` to instead return only the author of the latest manifest change at the scan revision (`sourceOwner`), with `sourceOwnerStatus` of `available` or `unavailable`. A temporary git-provider failure on that path returns 503 or 504, which are safe to retry.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Triage

Triage is Nullify's automated review of a finding: severity, priority and reasoning. A finding can have no triage result yet.

### Get triage details

Fetch how Nullify triaged a finding, including its severity, priority, and reasoning. If the finding has no triage result yet, the call still returns 200 with `triageStatus` set to `pending` (running, queued or never run) or `failed` (the last attempt stopped, with `stopReason` when known) instead of a finding, so bound any polling. When triage is complete, `triageStatus` is `completed` and a `presignedUrl` for the stored report may be included.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/triage?githubOwnerId=1234'
```

### Get triage status

A lightweight status for polling a finding's triage run. `terminal` becomes true once the run has completed or failed, and `status` is empty when no triage run exists yet:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/triage/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get triage activity

Returns the triage run's activity log. Page with `since_id` set to the `nextCursor` of the previous response; `limit` defaults to 50 and is clamped to 1 to 200. The list is empty when no triage run exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/triage/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Allowlisting

### Allowlist a finding

Pause alerting when you accept the risk for a dependency finding. Supply an `allowlistReason` and an `allowlistType` (`AI`, `UserFixed`, `UserAssumeRisk`, `UserFalsePositive`, or `UserOther`); both are required by the schema. Allowlisting resolves the finding, discards any cached autofix for it, records an event, and closes the finding's ticket on a best-effort basis. It returns no body.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"allowlistReason": "Risk accepted for legacy service", "allowlistType": "UserAssumeRisk"}' \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/allowlist?githubOwnerId=1234'
```

### Remove a finding from the allowlist

Reverse an allowlist decision and return the finding to the active backlog. Supply an `unallowlistReason`. A ticket that was closed when the finding was allowlisted is reopened, or a new one is created if the original is past its reopen window, on a best-effort basis:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"unallowlistReason": "Risk needs renewed review"}' \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/unallowlist?githubOwnerId=1234'
```

## Tickets

Ticket operations use the ticketing integration your tenant has configured.

### Create a ticket

Creates a ticket for the finding on your configured ticket integration and returns the ticket details. The optional body takes `message`, `assignees`, `project` (project name or key), `campaignId` and `campaignTitle`. Failure modes: 400 if the finding already has a ticket or the Jira configuration is incomplete, 412 if ticketing is disabled, the integration needs reconnecting or an assignee is required, 501 if no ticket integration is configured, and 503 for a temporary failure resolving the assignee.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/ticket?githubOwnerId=1234'
```

### Delete a ticket

Closes the finding's ticket on the integration and clears Nullify's tracking of it. The call is idempotent: deleting a finding that has no ticket still succeeds.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Autofix

Autofix raises a pull request that upgrades the vulnerable package. It runs asynchronously, so a successful start response means the request was accepted, not that a pull request exists.

### Start autofix

Starts a fix run for the finding. The response returns the new `autoFixState` and a `runId`. The optional body takes `message`, `assignees`, `originCampaignId` and `force`. The request is only valid for findings from push scans of the default branch; findings from pull-request scans return 400. If a run is already generating, a repeat request without `force` is accepted as the same run. Other refusals: 409 when the finding is resolved, a pull request is already open, or `force` was used while a run is in flight, 412 when the repository is archived, and 400 when the agent previously found the finding not fixable and you did not send `force=true` with a non-empty `message`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/autofix/fix" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/dependencies/findings/01J6EEXK3NKYKWW9XTPQYAF41N/autofix/fix?githubOwnerId=1234'
```

### Get autofix status

A lightweight per-finding autofix lifecycle status intended for frequent polling after you start a run (every few seconds). It does not check the git provider:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/autofix/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get autofix state

The authoritative autofix state. It also reconciles recorded pull requests with the git provider, so it is slower than the status call; poll it on a slower cadence (about every 30 seconds) rather than instead of the status call:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/autofix/state" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get autofix activity

Cursor-paginated log of what the autofix run did. Page with `since_id` set to the `nextCursor` of the previous response; `limit` defaults to 50 and is clamped to 1 to 200. The list is empty when no run exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/autofix/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the proposed fix diff

Returns the diff, pull request title and body, and explanation for a fix that Nullify has already prepared and cached. It returns 400 with "no cached fix found" when the finding has no cached fix, so check `autoFixState` first.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/dependencies/findings/{findingId}/autofix/cache/diff" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Container findings

Dependency Analysis also evaluates container images. The container operations mirror the dependency ones.

### List container findings

Same filters, sorting and pagination as the dependency list, except there is no `hasMultipleVersions` filter:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/containers/findings?githubOwnerId=1234'
```

### List container findings (preview alias)

A deprecated alias for the container list; it runs the same handler. Use `/sca/containers/findings`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List container findings in full (deprecated)

Returns complete container finding records, with an optional `repositoryId` filter. Marked deprecated and scheduled for removal.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a container finding

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a container finding

Update a container finding's priority or severity with `priorityOverride` and `severityOverride`, validated the same way as the dependency update:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container finding events

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container finding related users

Suggests up to three people from the git history of the file that contains the finding, falling back to repository contributors on providers without blame support:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container finding triage

The same behavior as the dependency triage calls, including the `pending` and `failed` states in place of a finding when there is no result:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/triage/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/triage/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Allowlist and unallowlist a container finding

Allowlist a container finding with the same `allowlistReason` + `allowlistType` body as a dependency finding. Unallowlist takes an `unallowlistReason`.

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"allowlistReason": "Base image patched upstream", "allowlistType": "UserFixed"}' \
  'https://api.<TENANT>.nullify.ai/sca/containers/findings/01J6EEXK3NKYKWW9XTPQYAF41N/allowlist?githubOwnerId=1234'
```

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container finding tickets

Create a ticket with the same body and error codes as the dependency call, or delete it (idempotent):

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Container finding autofix

Start a fix run for a container finding. It follows the same rules as dependency autofix, except that a repeat request while a run is generating returns 409 rather than being adopted as the same run:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/autofix/fix" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Poll the run with the status (frequent, lightweight), state (authoritative, slower) and activity (cursor-paginated log) calls:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/autofix/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/autofix/state" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/containers/findings/{findingId}/autofix/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Events

Track dependency alerts, suppressions, and auto-remediation updates across the account. Filter with `fromTime` (a UTC timestamp such as `2026-01-31T00:00:00Z`), repeatable `eventType`, `findingId` (a single dependency or container finding) and repeatable `fileOwnerName`. Sort with `sort` (`asc` or `desc`, default `desc`). `limit` defaults to and is capped at 100; follow `nextToken` for more.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/events?githubOwnerId=1234'
```

## Repositories and scan runs

### List repositories

Enumerate the repositories Dependency Analysis is reviewing, with their scan status. The response is a map keyed by repository ID. `limit` is at most 10 here; follow `nextToken` for more.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/repositories?githubOwnerId=1234'
```

### Get a repository

Returns the stats for one repository by its ID, from the list call above. Returns 404 if no such repository exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/repositories/{repositoryId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List scan runs

Lists the scan runs for one repository. `repositoryId` and `scanType` (`sca_dependencies` or `sca_containers`) are required. Page with `limit` (default 10, maximum 50) and `offset`, sort with `sort` (`newest` or `oldest` by start time), and bound the window with RFC 3339 `from` and `to`. Each run reports finding counts by outcome and severity, and an `scaOutcome` describing SBOM source, coverage gaps and whether the run was degraded, so check it before treating a run's absence of findings as clean.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/scan-runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/scan-runs?githubOwnerId=1234&repositoryId=5678&scanType=sca_dependencies&limit=10'
```

## CVE exposure and threat intelligence

The CVE endpoints answer "are we affected by this CVE?" across your repositories. Their counts cover push-scan findings on the default workflow. Scores in exposure results are snapshots from each finding's last review.

### List CVE exposure across the fleet

Returns one row per distinct CVE in your findings with aggregates such as finding, repository and package counts, maximum CVSS and EPSS, whether a fix exists, and reachable-finding counts. By default only CVEs with at least one unresolved finding are included (`openOnly=true`); `kevOnly=true` keeps CISA Known Exploited Vulnerabilities. Sort with `sortBy` (`severity`, `repositories` (default), `findings`, `epss`, `cvss` or `firstSeen`). Page with `limit` (default 25, maximum 100) and `offset` (maximum 1000; past that, narrow the filters), and follow `nextOffset`. Results are cached for about a minute. Check `reviewedRepositoryCount` and `evaluatedAt` to see how much of your estate the answer covers.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/vulnerabilities" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/sca/vulnerabilities?githubOwnerId=1234&kevOnly=true&sortBy=severity'
```

### Get CVE intelligence

Returns current vulnerability intelligence for one CVE together with your own exposure to it. `{cveId}` must look like `CVE-2024-12345`; anything else returns 400. `exposure.verdict` is `affected` (an open finding exists), `remediated` (only resolved findings), `no_exposure_found` (no findings in the repositories that have been reviewed) or `unknown` (nothing has been reviewed). `no_exposure_found` is bounded by `reviewedRepositoryCount`, not a guarantee. `intel` is null when the vulnerability source has no record or is unavailable; the exposure result is still valid.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/vulnerabilities/{cveId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List findings for a CVE

Returns your findings that reference the CVE, ordered by priority. `type` selects `dependency` (default) or `container`; only the matching list is populated. Filters are `branch`, `isResolved` and repeatable `fileOwnerName`. Without `branch`, only push-workflow findings are returned. Page with `limit` (default and maximum 100) and `offset`, and follow `nextOffset`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/vulnerabilities/{cveId}/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List packages affected by a CVE

Returns the packages and container artifacts through which the CVE reaches your repositories, with the versions in use, the fixed versions, and finding and repository counts. The ecosystem is derived from lockfile paths or package URLs and can be empty. The list is not paginated.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/vulnerabilities/{cveId}/packages" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List the threat intelligence feed

{% hint style="warning" %}
Deprecated. Use `GET /manager/threats` (see [Threats](/api-reference/api-reference/manager/threats)), which lists the same research with your tenant's assessment of each threat. Both threat-feed operations stay available, and their responses carry a `Deprecation` header and a `Link` header with `rel="successor-version"`.
{% endhint %}

Returns Nullify's threat-research feed, newest first. It is global research and contains no data about your tenant or repositories. Filter with `cveId`, `ecosystem` and `severity` (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `NONE` or `UNKNOWN`; other values return 400). Page with `limit` (default 50, capped at 100) and `offset` (maximum 1000), and follow `nextOffset`. Returns 503 when the feed backend is unreachable rather than an empty list.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/threat-feed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a threat

Deprecated with the feed listing above; use `GET /manager/threats`.

Returns one threat from the feed by its `threatId`, with its description, article links and affected packages. Returns 404 for an unknown ID and 503 when the feed backend is unreachable.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/sca/threat-feed/{threatId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                        | Operation                                                                  |
| -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------- |
| `GET`    | `/sca/containers/findings`                                  | Get SCA Container Findings                                                 |
| `GET`    | `/sca/containers/findings/detailed`                         | Get SCA Container Findings \[DEPRECATED - TO BE REMOVED BY 2025]           |
| `GET`    | `/sca/containers/findings/preview`                          | Get SCA Container Findings Preview                                         |
| `GET`    | `/sca/containers/findings/{findingId}`                      | Get Container Finding                                                      |
| `PATCH`  | `/sca/containers/findings/{findingId}`                      | Update Container Finding                                                   |
| `POST`   | `/sca/containers/findings/{findingId}/allowlist`            | Allowlist Container Finding                                                |
| `GET`    | `/sca/containers/findings/{findingId}/autofix/activity`     | Get SCA Container Finding Autofix Activity                                 |
| `POST`   | `/sca/containers/findings/{findingId}/autofix/fix`          | Fix Container Findings                                                     |
| `GET`    | `/sca/containers/findings/{findingId}/autofix/state`        | Get Container Finding Autofix State                                        |
| `GET`    | `/sca/containers/findings/{findingId}/autofix/status`       | Get Container Finding Autofix Status                                       |
| `GET`    | `/sca/containers/findings/{findingId}/events`               | Get SCA Container Finding Events                                           |
| `DELETE` | `/sca/containers/findings/{findingId}/ticket`               | Delete Ticket for Container Finding                                        |
| `POST`   | `/sca/containers/findings/{findingId}/ticket`               | Create Ticket                                                              |
| `GET`    | `/sca/containers/findings/{findingId}/triage`               | Get Triaged Finding                                                        |
| `GET`    | `/sca/containers/findings/{findingId}/triage/activity`      | Get SCA Container Finding Triage Activity                                  |
| `GET`    | `/sca/containers/findings/{findingId}/triage/status`        | Get SCA Container Finding Triage Status                                    |
| `POST`   | `/sca/containers/findings/{findingId}/unallowlist`          | Unallowlist Container Finding                                              |
| `GET`    | `/sca/containers/findings/{findingId}/users`                | Get Finding Related Users                                                  |
| `GET`    | `/sca/dependencies/findings`                                | Get SCA Dependency Findings                                                |
| `GET`    | `/sca/dependencies/findings/detailed`                       | Get SCA Dependency Findings Detailed \[DEPRECATED - TO BE REMOVED BY 2025] |
| `GET`    | `/sca/dependencies/findings/preview`                        | Get SCA Dependency Findings Preview                                        |
| `GET`    | `/sca/dependencies/findings/{findingId}`                    | Get Finding                                                                |
| `PATCH`  | `/sca/dependencies/findings/{findingId}`                    | Update Dependencies Finding                                                |
| `POST`   | `/sca/dependencies/findings/{findingId}/allowlist`          | Allowlist Dependency Finding                                               |
| `GET`    | `/sca/dependencies/findings/{findingId}/autofix/activity`   | Get SCA Dependency Finding Autofix Activity                                |
| `GET`    | `/sca/dependencies/findings/{findingId}/autofix/cache/diff` | Get SCA Dependency Finding Fix                                             |
| `POST`   | `/sca/dependencies/findings/{findingId}/autofix/fix`        | Fix Dependency Finding                                                     |
| `GET`    | `/sca/dependencies/findings/{findingId}/autofix/state`      | Get Dependency Finding Autofix State                                       |
| `GET`    | `/sca/dependencies/findings/{findingId}/autofix/status`     | Get Dependency Finding Autofix Status                                      |
| `GET`    | `/sca/dependencies/findings/{findingId}/events`             | Get SCA Dependency Finding Events                                          |
| `DELETE` | `/sca/dependencies/findings/{findingId}/ticket`             | Delete Ticket for Dependency Finding                                       |
| `POST`   | `/sca/dependencies/findings/{findingId}/ticket`             | Create Ticket                                                              |
| `GET`    | `/sca/dependencies/findings/{findingId}/triage`             | Get Triaged Finding                                                        |
| `GET`    | `/sca/dependencies/findings/{findingId}/triage/activity`    | Get SCA Dependency Finding Triage Activity                                 |
| `GET`    | `/sca/dependencies/findings/{findingId}/triage/status`      | Get SCA Dependency Finding Triage Status                                   |
| `POST`   | `/sca/dependencies/findings/{findingId}/unallowlist`        | Unallowlist Dependency Finding                                             |
| `GET`    | `/sca/dependencies/findings/{findingId}/users`              | Get Finding Related Users                                                  |
| `GET`    | `/sca/events`                                               | Get SCA Events                                                             |
| `GET`    | `/sca/repositories`                                         | Get Repository Stats                                                       |
| `GET`    | `/sca/repositories/{repositoryId}`                          | Get Repository Stats                                                       |
| `GET`    | `/sca/scan-runs`                                            | List Scan Runs                                                             |
| `GET`    | `/sca/threat-feed`                                          | List Threat Intelligence Feed                                              |
| `GET`    | `/sca/threat-feed/{threatId}`                               | Get Threat Intelligence Detail                                             |
| `GET`    | `/sca/vulnerabilities`                                      | List CVE Exposure Across The Fleet                                         |
| `GET`    | `/sca/vulnerabilities/{cveId}`                              | Get CVE Intelligence                                                       |
| `GET`    | `/sca/vulnerabilities/{cveId}/findings`                     | List Findings For A CVE                                                    |
| `GET`    | `/sca/vulnerabilities/{cveId}/packages`                     | List Packages Affected By A CVE                                            |


# Secrets & Data API

Query secrets, credential, and sensitive-data findings via the Nullify API

For PR and default-branch scanning, see [scan coverage, start operations and completion checks](/api-reference/api-reference/orchestrator#scan-coverage-by-type).

Secret and sensitive-data findings are available under separate namespaces:

* `/secrets/credentials/*` — detected secrets and credentials. `/secrets/findings/*` is a deprecated legacy alias for this namespace and returns the same data.
* `/secrets/sensitivedata/*` — sensitive data / PII.

Every namespace supports `GET .../findings`, `GET` and `PATCH .../findings/{findingId}`, `GET .../findings/{findingId}/triage`, `GET .../findings/{findingId}/users`, `POST .../findings/{findingId}/allowlist`, `POST .../findings/{findingId}/unallowlist`, `POST` and `DELETE .../findings/{findingId}/ticket`, and the bulk `POST .../findings/allowlist/batch`. Finding-event history is available for credentials and the legacy alias, not sensitive-data findings. Each operation below is embedded once per path.

## Base URL

`https://api.<TENANT>.nullify.ai`

## Conventions

* **Provider scope.** Every call identifies the connected provider account with one scope query parameter: `githubOwnerId` for GitHub, or `azureOrganizationId`, `bitbucketWorkspaceId`, `gitlabGroupId` or `installationId` for the other providers. The examples use `githubOwnerId=1234`.
* **Repository scope.** To narrow a list to specific repositories, add `githubRepositoryId` (repeatable) or `githubTeamId` to the scope parameters. The `detailed` lists take a single `repositoryId` instead.
* **Pagination.** Finding lists accept `limit` and `nextToken` (see [Pagination](/api-reference/api-reference/pagination)). `limit` defaults to 100 and a value above 100 returns 400. `sort` is `asc` or `desc` (default `desc`) and `sortBy` is `priority` (default) or `time`.
* **Permissions.** Reads need finding read access (lists need finding list access). Updates, allowlisting and tickets need finding write access.
* **Finding IDs.** Take `findingId` from the matching list call. An ID that does not exist in your tenant returns 404.
* **Secret values.** Events and finding-event history carry a masked value, never the raw secret.

## Events

### List events

Stream events for new secrets, allowlisting and unallowlisting. Pass `fromTime` as a UTC timestamp such as `2025-01-31T00:00:00Z`, and filter with `eventType`, `findingId` and `fileOwnerName`. A page holds at most 100 events: `limit` defaults to 100, and a `numItems` above 100 returns 400. Follow `nextToken` to read on. The `branch` parameter in the specification is not applied by the handler. When you filter by `fileOwnerName` and file-owner lookup is unavailable, the call fails instead of returning unfiltered events.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/events?githubOwnerId=1234'
```

## Findings

### List findings

Enumerate findings, one per unique secret hash per repository, filtered by `branch`, `secretType` (the detector rule), `isResolved`, `isAllowlisted`, `isFalsePositive` and `fileOwnerName`. The list returns previews, and duplicate and deleted credential findings are excluded. `fileOwnerName` is applied after a page is fetched, so a filtered page can be shorter than `limit`. The sensitive-data list applies `branch`, `isResolved`, `isAllowlisted` and `isFalsePositive`; it accepts `secretType` and `fileOwnerName` in the specification but does not apply them.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias (deprecated):

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Deprecated alias that returns the same list:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data / PII:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/findings?githubOwnerId=1234'
```

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/credentials/findings?githubOwnerId=1234'
```

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/sensitivedata/findings?githubOwnerId=1234'
```

### List credential findings with full detail

Returns complete credential finding records instead of previews, with a `repositoryId` filter alongside the list filters. The `/secrets/findings/detailed` path is deprecated; use the credentials path.

Current path:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Deprecated path:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding

Fetch full details for one finding. Credential responses also include a `presignedUrl`. Unknown or other-tenant IDs return 404.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Update a finding

Override priority or attach notes. Credential findings accept `priorityOverride` (`URGENT`, `IMPORTANT`, `MEDIUM`, `INFORMATIONAL`, `LOW`, `NEGLIGIBLE`, `FALSE_POSITIVE`, `UNKNOWN`), `severityOverride` (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `NONE`, `INFORMATIONAL`, `UNKNOWN`) and `userNotes`. Sensitive-data findings accept only `priorityOverride` and `userNotes`; they have no severity override. An invalid value returns 400. The response is the updated finding.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"severityOverride": "HIGH"}' \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Get triage details

Fetch how Nullify triaged a finding: its severity, priority and reasoning. Triage is not instant: for a finding that exists but has no triage yet the call returns 404 (triage not yet available), so retry later rather than treating it as a missing finding. Credential findings fall back to a validation-only result when the credential was checked against its provider but no full report is readable.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N/triage?githubOwnerId=1234'
```

### List users related to a finding

Returns up to three candidate people for routing the finding, based on git blame for the finding location and repository contributions, each with a reason.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List finding events

Retrieve the decision history for a credential finding. Use the credentials path; the legacy path remains as an alias. Sensitive-data findings do not expose this resource. The response is not paginated.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N/events?githubOwnerId=1234'
```

## Allowlisting

### Allowlist a finding

Suppress an individual finding with an audit trail. Supply an `allowlistReason` and an `allowlistType` (`AI`, `UserFixed`, `UserAssumeRisk`, `UserFalsePositive`, or `UserOther`). The finding is marked resolved, an allowlist event is recorded, and an open ticket is closed on a best-effort basis; a ticket-close failure does not fail the call. Success returns 204.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"allowlistReason": "Credential rotated", "allowlistType": "UserFixed"}' \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N/allowlist?githubOwnerId=1234'
```

### Allowlist findings in bulk

Allowlist multiple findings in a single call. The body adds a `findingIds` array alongside `allowlistReason` and `allowlistType`; an empty array returns 400. Findings are processed concurrently and the call is not atomic: an unknown ID returns 404 but findings already processed stay allowlisted. For credentials, the bulk call records the allowlist type but does not store `allowlistReason` on the finding, so use the single-finding call when you need the reason kept. Success returns 204.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/allowlist/batch" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/allowlist/batch" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/allowlist/batch" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"findingIds": ["01J6EEXK3NKYKWW9XTPQYAF41N", "01J6EFVQN34BCEAHDJTE4F9Y22"], "allowlistReason": "Credentials rotated", "allowlistType": "UserFixed"}' \
  'https://api.<TENANT>.nullify.ai/secrets/credentials/findings/allowlist/batch?githubOwnerId=1234'
```

### Remove a finding from the allowlist

Reverse an allowlist decision and return the finding to the active backlog. Supply `unallowlistReason` and `unallowlistType`. A ticket closed by the allowlist is reopened unless the finding is also archived, a false positive or a duplicate. If the old ticket cannot be reopened a new linked ticket is created. Success returns 204.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"unallowlistReason": "Credential needs renewed review", "unallowlistType": "UserOther"}' \
  'https://api.<TENANT>.nullify.ai/secrets/findings/01J6EEXK3NKYKWW9XTPQYAF41N/unallowlist?githubOwnerId=1234'
```

## Tickets

### Create a ticket

Create a ticket for the finding on the tenant's configured ticket integration. The body is optional and accepts `message`, `assignees`, `project`, `campaignId` and `campaignTitle`. A finding that already has a ticket on that provider returns 400. Errors to expect: 501 when no ticket integration is configured, 412 when the integration is disabled, needs reconnecting, or requires an assignee you did not supply, and 503 or 504 when the ticket provider is temporarily unavailable. The response is the created `ticket`.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a ticket

Close the finding's ticket on the ticket integration and clear Nullify's link to it. The call is idempotent: a finding with no ticket returns 200 and does nothing. It returns 501 when no ticket integration is configured.

Credentials:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/credentials/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Legacy alias:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

Sensitive data:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/sensitivedata/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Scan runs

### List scan runs

Lists secrets scan runs for one repository, with status, trigger, branch, commit, live, new and allowlisted finding counts and severity totals. `repositoryId` is required. This list uses offset paging: `limit` defaults to 10 and is capped at 50, `offset` skips rows, `sort` is `newest` (default) or `oldest`, and `from` and `to` are RFC 3339 bounds on the start time. The response includes `totalCount`. Fixed and reintroduced counts are always 0 for secrets scans.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/secrets/scan-runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/secrets/scan-runs?githubOwnerId=1234&repositoryId=5678'
```

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                      | Operation                                                                        |
| -------- | --------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET`    | `/secrets/credentials/findings`                           | Get Secrets Credential Findings                                                  |
| `POST`   | `/secrets/credentials/findings/allowlist/batch`           | Allowlist Batch of Credential Findings                                           |
| `GET`    | `/secrets/credentials/findings/detailed`                  | Get Secrets Credential Findings Detailed                                         |
| `GET`    | `/secrets/credentials/findings/{findingId}`               | Get Credential Finding                                                           |
| `PATCH`  | `/secrets/credentials/findings/{findingId}`               | Update Credential Finding                                                        |
| `POST`   | `/secrets/credentials/findings/{findingId}/allowlist`     | Allowlist Credential Finding                                                     |
| `GET`    | `/secrets/credentials/findings/{findingId}/events`        | Get Finding Events                                                               |
| `DELETE` | `/secrets/credentials/findings/{findingId}/ticket`        | Delete Ticket for Credential Finding                                             |
| `POST`   | `/secrets/credentials/findings/{findingId}/ticket`        | Create Ticket for Credential Finding                                             |
| `GET`    | `/secrets/credentials/findings/{findingId}/triage`        | Get Triaged Credential Finding                                                   |
| `POST`   | `/secrets/credentials/findings/{findingId}/unallowlist`   | Unallowlist Credential Finding                                                   |
| `GET`    | `/secrets/credentials/findings/{findingId}/users`         | Get Credential Finding Related Users                                             |
| `GET`    | `/secrets/events`                                         | Get Secret Events                                                                |
| `GET`    | `/secrets/findings`                                       | Get Secrets Credential Findings                                                  |
| `POST`   | `/secrets/findings/allowlist/batch`                       | Allowlist Batch of Credential Findings                                           |
| `GET`    | `/secrets/findings/detailed`                              | Get Secrets Credential Findings Detailed - \[DEPRECATED - TO BE REMOVED BY 2025] |
| `GET`    | `/secrets/findings/preview`                               | Get Secrets Credential Findings                                                  |
| `GET`    | `/secrets/findings/{findingId}`                           | Get Credential Finding                                                           |
| `PATCH`  | `/secrets/findings/{findingId}`                           | Update Credential Finding                                                        |
| `POST`   | `/secrets/findings/{findingId}/allowlist`                 | Allowlist Credential Finding                                                     |
| `GET`    | `/secrets/findings/{findingId}/events`                    | Get Finding Events                                                               |
| `DELETE` | `/secrets/findings/{findingId}/ticket`                    | Delete Ticket for Credential Finding                                             |
| `POST`   | `/secrets/findings/{findingId}/ticket`                    | Create Ticket for Credential Finding                                             |
| `GET`    | `/secrets/findings/{findingId}/triage`                    | Get Triaged Credential Finding                                                   |
| `POST`   | `/secrets/findings/{findingId}/unallowlist`               | Unallowlist Credential Finding                                                   |
| `GET`    | `/secrets/findings/{findingId}/users`                     | Get Credential Finding Related Users                                             |
| `GET`    | `/secrets/scan-runs`                                      | List Scan Runs                                                                   |
| `GET`    | `/secrets/sensitivedata/findings`                         | Get Sensitive Data Findings                                                      |
| `POST`   | `/secrets/sensitivedata/findings/allowlist/batch`         | Allowlist Batch of Sensitive Data Findings                                       |
| `GET`    | `/secrets/sensitivedata/findings/{findingId}`             | Get Sensitive Data Finding                                                       |
| `PATCH`  | `/secrets/sensitivedata/findings/{findingId}`             | Update Sensitive Data Finding                                                    |
| `POST`   | `/secrets/sensitivedata/findings/{findingId}/allowlist`   | Allowlist Sensitive Data Finding                                                 |
| `DELETE` | `/secrets/sensitivedata/findings/{findingId}/ticket`      | Delete Ticket for Sensitive Data Finding                                         |
| `POST`   | `/secrets/sensitivedata/findings/{findingId}/ticket`      | Create Ticket for Sensitive Data Finding                                         |
| `GET`    | `/secrets/sensitivedata/findings/{findingId}/triage`      | Get Triaged Sensitive Data Finding                                               |
| `POST`   | `/secrets/sensitivedata/findings/{findingId}/unallowlist` | Unallowlist Sensitive Data Finding                                               |
| `GET`    | `/secrets/sensitivedata/findings/{findingId}/users`       | Get Sensitive Data Finding Related Users                                         |


# SCPM API

For PR and default-branch scanning, see [scan coverage, start operations and completion checks](/api-reference/api-reference/orchestrator#scan-coverage-by-type).

The `/scpm` API manages supply-chain findings and package policy. See [Supply Chain Posture Management](/capabilities/scpm) for the difference between package hygiene, suspicious behavior, and confirmed threats.

## Base URL

`https://api.<TENANT>.nullify.ai`

## Conventions

* **Provider scope.** Calls are scoped to one source-control account. Pass the query parameter for your provider: `githubOwnerId`, `gitlabGroupId`, `azureOrganizationId`, `bitbucketWorkspaceId`, or `installationId`.
* **Permissions.** Findings reads need finding read or list access, finding changes (update, allowlist, tickets, autofix) need finding write access, and settings and malware analysis need configuration read or write access. Missing access returns 403.
* **Finding IDs.** `{findingId}` comes from the finding list calls. An unknown ID returns 404. An ID that belongs to another tenant returns 403.
* **Pagination.** Lists use `nextToken` and `limit`, capped at 100 (see [Pagination](/api-reference/api-reference/pagination)). Scan runs use `offset` instead.

## Findings

### List findings

Lists SCPM findings as previews. Filters are `priorityLabel`, `severity`, `branch`, `workflow`, `ruleId`, `hasPullRequest`, `isResolved`, `isFixed`, `isFalsePositive`, `isAllowlisted`, `isArchived`, and the repeatable `repositoryIds`, `findingType` (for example `known_malware` or `cicd_unpinned_action`), `language` and `fileOwnerName`. Sort with `sortBy` (`time` or `priority`) and `sort` (`asc` or `desc`, default `desc`). `limit` defaults to and is capped at 100. Follow `nextToken` for more.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/scpm/findings?githubOwnerId=1234&findingType=known_malware&isResolved=false'
```

### List findings (preview alias)

`GET /scpm/findings/preview` is a deprecated alias that runs the same handler with the same parameters. Use `/scpm/findings` in new integrations.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/preview" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List findings in full

Returns complete finding records instead of previews, with the same filters. The repository filter here is the single-valued `repositoryId` rather than `repositoryIds`. The `gateBase` parameter is used by Nullify's pull-request gate to fetch its comparison baseline, including allowlisted and false-positive rows. When it is set, the response also reports `cooldownWarnOnly`, and `scannedBaseline` if you also send `repositoryId` and `branch`. Ordinary integrations should leave it unset.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/detailed" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding

Returns the finding with its explanation and impact, a `presignedUrl` for the stored finding detail, and `movements`, the history of locations where the finding has been seen, newest first.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a finding

Sets overrides on a finding. `severityOverride` and `priorityOverride` are validated against the allowed values (400 if not), `userNotes` stores your free-text note, and `isFalsePositive` can only be set to `false`, which reverses a false-positive verdict and reopens the finding's ticket. Setting it to `true` returns 400, because a dismissal is a triage verdict with a reason; use [allowlisting](#allowlist-a-finding) to suppress a finding. Omitted fields are left unchanged, and the updated finding is returned.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"severityOverride": "HIGH", "userNotes": "Confirmed with the platform team"}' \
  'https://api.<TENANT>.nullify.ai/scpm/findings/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

### Get triage details

Returns the triaged view of the finding, with the triage verdict and, when one exists, a `presignedUrl` for the stored triage report. A finding that has not been triaged still returns 200, with no verdict.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/triage" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get related users

Returns the people associated with the finding, as candidates to notify or assign.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/users" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a finding's events

Returns every event recorded against the finding, newest first. The list is not paginated.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get events

Returns the tenant's SCPM events, newest first. Filter with `fromTime` (a UTC timestamp such as `2026-01-31T00:00:00Z`), repeatable `eventType`, and `findingId` for one finding, which also returns 404 or 403 for an ID that is not yours. Sort with `sort` (`asc` or `desc`). `limit` is 1 to 100 (default 100); follow `nextToken`. Returns 503 when the event store is temporarily unavailable, which is safe to retry.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Allowlisting

### Allowlist a finding

Suppresses a finding you have accepted. `allowlistReason` and `allowlistType` (for example `UserFixed`, `UserAssumeRisk`, `UserFalsePositive` or `UserOther`) are required by the schema, and a missing reason returns 400. Allowlisting resolves the finding, records an event, and closes its ticket on a best-effort basis. It returns no finding body.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"allowlistReason": "Pinned by internal mirror", "allowlistType": "UserAssumeRisk"}' \
  'https://api.<TENANT>.nullify.ai/scpm/findings/01J6EEXK3NKYKWW9XTPQYAF41N/allowlist?githubOwnerId=1234'
```

### Allowlist findings in a batch

Allowlists up to 500 findings with one `allowlistReason` and `allowlistType`, listed in `findingIds`. The batch is all or nothing: if any ID is not found or belongs to another tenant, the call fails and no finding in the batch is changed. Events and ticket closing then run for each finding.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/allowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Remove a finding from the allowlist

Reverses an allowlist decision. `unallowlistReason` is required. If nothing else keeps the finding resolved, it returns to the active backlog and a ticket that was closed is reopened, or a new one is created if it is past its reopen window, on a best-effort basis.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/unallowlist" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Tickets

Ticket operations use the ticketing integration your tenant has configured.

### Create a ticket

Creates a ticket for the finding and returns its details. The optional body takes `message`, `assignees`, `project` (project name or key), `campaignId` and `campaignTitle`. Failure modes: 400 if the finding already has a ticket or the Jira configuration is incomplete, 412 if ticketing is disabled, the integration needs reconnecting or an assignee is required, 501 if no ticket integration is configured, and 503 for a temporary failure resolving the assignee.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/ticket" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a ticket

Closes the finding's ticket on the integration and clears Nullify's tracking. Idempotent: a finding with no ticket still returns success.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/ticket" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Autofix

Autofix generates a fix and opens a pull request. It runs asynchronously, so a successful start response means the request was accepted, not that a pull request exists.

### Start autofix

Starts a fresh fix against the current target branch. The response returns the new `autoFixState` and a `runId`. The optional body takes `message`, `assignees`, `originCampaignId` and `force`; the legacy `useCachedFix` field is ignored. Only findings from push scans can be fixed: others return 400. A request while a run is already in flight returns 409 (as does a finding that is resolved or already has an open pull request), an archived repository returns 412, and a finding the agent previously judged not fixable returns 400 unless you send `force=true` with a non-empty `message`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/autofix/fix" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/scpm/findings/01J6EEXK3NKYKWW9XTPQYAF41N/autofix/fix?githubOwnerId=1234'
```

### Get autofix status

A lightweight lifecycle status for frequent polling after you start a run. It does not contact the git provider:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/autofix/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get autofix state

The authoritative state. It also reconciles recorded pull requests with the git provider, so it is slower; poll it about every 30 seconds alongside the status call:

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/autofix/state" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get autofix activity

Cursor-paginated log of what the run did. Page with `since_id` set to the `nextCursor` of the previous response; `limit` defaults to 50 and is clamped to 1 to 200. The list is empty when no run exists.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/{findingId}/autofix/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the autofix diff (retired)

Fix previews are retired for SCPM. After confirming the finding exists, this call always returns 404, so do not rely on it. Start a fresh fix with [Start autofix](#start-autofix) and read the resulting pull request.

## Findings upload

### Get an upload URL

This operation is not available: it always returns 500, so it cannot be used to upload findings.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/findings/upload" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Repositories and scan runs

### List repositories

Returns the repositories that carry SCPM findings as a map keyed by repository ID, each with its severity histogram and the timestamp of its most recent finding. `limit` defaults to 25 and is capped at 100; follow `nextToken`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/repositories" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List scan runs

Lists SCPM scan runs, newest first by default. `repositoryId` is optional: omit it to list runs across the tenant. Page with `limit` (default 10, maximum 50) and `offset`, sort with `sort` (`newest` or `oldest`), and bound the window with RFC 3339 `from` and `to` (a `to` before `from` returns 400). Each run reports finding counts by outcome and severity.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/scan-runs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Package policy

`GET /scpm/settings` reads the policy and `PUT /scpm/settings` updates it. A tenant that has never saved settings gets the platform defaults (cooldown enabled, 7-day window).

### Get settings

Returns the cooldown settings (`cooldownEnabled`, `cooldownDays`, per-ecosystem `cooldownOverrides` and `cooldownWarnOnly`), the accepted-license list and the package allowlist.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/settings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update settings

Upserts the policy. `cooldownEnabled` and `cooldownDays` (0 to 365) are required on every call, so read the current settings first and send them back unchanged if you only mean to change something else. `cooldownWarnOnly` is the pull-request gate switch: when true, cooldown findings appear on the check run but do not fail the merge gate. Every optional field that you omit keeps its stored value. When you include `cooldownOverrides` (ecosystem to days, 0 to 365), `acceptedLicenses` (SPDX identifiers, at most 500) or `packageAllowlist` (at most 1000 entries), it replaces the complete stored value, so read, modify and send the whole list to add an entry, and send an empty list only to clear it. Unknown ecosystems, blank package names and an `expiresAt` in the past return 400. An allowlist entry identifies an ecosystem and package, optionally a namespace and `versionRange`; a blank `versionRange` exempts every version, so scope it deliberately. The response echoes the saved settings.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/settings" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"cooldownEnabled": true, "cooldownDays": 7, "cooldownWarnOnly": false}' \
  'https://api.<TENANT>.nullify.ai/scpm/settings?githubOwnerId=1234'
```

## Malware analysis

Malware analysis covers a specific package version or container image. It is separate from looking up known CVEs in [Dependency Analysis](/api-reference/api-reference/dependency-analysis). A missing analysis result is not a clean verdict.

### Request dependency analysis

Queues a package version for malware analysis. `ecosystem`, `name` and `version` are required (400 otherwise); `previousVersion` supplies a diff baseline. Requests are idempotent for 24 hours on the same coordinate, or on your own `idempotencyKey` if you send one. The response gives a `jobId`, `status`, `cacheHit` and a `verdict` when one is already known. There is no job-lookup operation in this API: to follow progress, send the same request again or query the package with [Batch query dependencies](#batch-query-dependencies) and read `analysisStatus`. Requires configuration write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/dependencies/analyze" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"ecosystem": "npm", "name": "left-pad", "version": "1.3.0"}' \
  'https://api.<TENANT>.nullify.ai/scpm/dependencies/analyze?githubOwnerId=1234'
```

### Request container analysis

Queues an OCI image for malware analysis. `registry`, `repository` and `reference` (a tag or a `sha256:` digest) are required; `previousReference` supplies a diff baseline. It is idempotent for 24 hours in the same way as dependency analysis and returns the same `jobId`, `status`, `cacheHit` and `verdict` fields. Requires configuration write access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/containers/analyze" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Batch query dependencies

Looks up known vulnerabilities and the malware verdict for up to 1000 package coordinates (`ecosystem`, `name`, `version`) in one call; an empty list or more than 1000 returns 400. Optional `registryHost`, `resolvedUrl`, `integrity` and `provenance` from your lockfile let the index check the artifact identity, and a mismatch is reported as `identityMismatch`. Each result carries `analysisStatus` (`complete`, `queued`, `tier2_running`, `none` or `unknown`) and `found`. Only `complete` is a verdict: a coordinate the index has never seen comes back as `unknown` with `found: false`, which is absence of evidence, not a pass, so a gate should treat anything other than `complete` as unverified. Results also report whether your package allowlist covers the coordinate (`allowlisted`, with reason and expiry), but the verdict fields are not changed by it. `integrityBudgetExhausted` means some rows were never digest-compared. Requires configuration read access.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/scpm/dependencies/query/batch" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"packages": [{"ecosystem": "npm", "name": "left-pad", "version": "1.3.0"}]}' \
  'https://api.<TENANT>.nullify.ai/scpm/dependencies/query/batch?githubOwnerId=1234'
```

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                               | Operation                                                      |
| -------- | -------------------------------------------------- | -------------------------------------------------------------- |
| `POST`   | `/scpm/containers/analyze`                         | Request malware analysis for an OCI container image            |
| `POST`   | `/scpm/dependencies/analyze`                       | Request malware analysis for a dependency                      |
| `POST`   | `/scpm/dependencies/query/batch`                   | Batch query vulnerabilities + malware verdict for dependencies |
| `GET`    | `/scpm/events`                                     | Get SCPM Events                                                |
| `GET`    | `/scpm/findings`                                   | Get SCPM Findings                                              |
| `POST`   | `/scpm/findings/allowlist`                         | Allowlist Batch of SCPM Findings                               |
| `GET`    | `/scpm/findings/detailed`                          | Get Findings Detailed                                          |
| `GET`    | `/scpm/findings/preview`                           | Get SCPM Findings                                              |
| `POST`   | `/scpm/findings/upload`                            | Get Presigned URL to Upload SCPM Findings                      |
| `GET`    | `/scpm/findings/{findingId}`                       | Get Finding                                                    |
| `PATCH`  | `/scpm/findings/{findingId}`                       | Update Finding                                                 |
| `POST`   | `/scpm/findings/{findingId}/allowlist`             | Allowlist Finding                                              |
| `GET`    | `/scpm/findings/{findingId}/autofix/activity`      | Get SCPM Finding Autofix Activity                              |
| `POST`   | `/scpm/findings/{findingId}/autofix/fix`           | Autofix Finding                                                |
| `GET`    | `/scpm/findings/{findingId}/autofix/state`         | Get SCPM Finding Autofix State                                 |
| `GET`    | `/scpm/findings/{findingId}/autofix/status`        | Get SCPM Finding Autofix Status                                |
| `GET`    | `/scpm/findings/{findingId}/events`                | Get Finding Events                                             |
| `DELETE` | `/scpm/findings/{findingId}/ticket`                | Delete Ticket for SCPM Finding                                 |
| `POST`   | `/scpm/findings/{findingId}/ticket`                | Create Ticket for SCPM Finding                                 |
| `GET`    | `/scpm/findings/{findingId}/triage`                | Get Triaged Finding                                            |
| `POST`   | `/scpm/findings/{findingId}/unallowlist`           | Unallowlist Finding                                            |
| `POST`   | `/scpm/findings/{findingId}/unmark-false-positive` | Unmark SCPM Finding as False Positive                          |
| `GET`    | `/scpm/findings/{findingId}/users`                 | Get Finding Users                                              |
| `GET`    | `/scpm/repositories`                               | Get Repositories                                               |
| `GET`    | `/scpm/scan-runs`                                  | List Scan Runs                                                 |
| `GET`    | `/scpm/settings`                                   | Get SCPM Settings                                              |
| `PUT`    | `/scpm/settings`                                   | Put SCPM Settings                                              |


# Pentests API

Manage hands-off pentester engagements via the Nullify API

Endpoints live under the `/dast` namespace of `https://api.<TENANT>.nullify.ai`. This page is the overview; each area has its own guide with every operation.

## Workflow

1. Onboard what you want tested: an application with its targets and web services, and the credentials the pentester should log in with. See [Applications and preflight](/api-reference/api-reference/pentester/applications), [Targets and web services](/api-reference/api-reference/pentester/targets-and-web-services) and [Credentials](/api-reference/api-reference/pentester/credentials).
2. Optionally run a preflight and get a cost estimate for the application before spending budget.
3. Start an engagement with `POST /dast/pentest/start` and poll its status. See [Engagements](/api-reference/api-reference/pentester/engagements).
4. Review findings, triage, allowlist them, open tickets and request fixes. See [Findings](/api-reference/api-reference/pentester/findings).
5. Optionally validate exploitability of a finding under an armed policy. See [Exploit validation](/api-reference/api-reference/pentester/exploit-validation).

A start response means a job was accepted, not that testing finished: engagements are asynchronous and you poll the scan status and findings operations.

## Guides in this section

* [Applications and preflight](/api-reference/api-reference/pentester/applications): applications, pentest application configs, cost estimates, preflight checks, budget and source IPs.
* [Targets and web services](/api-reference/api-reference/pentester/targets-and-web-services): targets, web services, validations and exploit-validation consent.
* [Credentials](/api-reference/api-reference/pentester/credentials): stored credentials and credential validation.
* [Engagements](/api-reference/api-reference/pentester/engagements): starting, monitoring, stopping and reading reports for engagements.
* [Findings](/api-reference/api-reference/pentester/findings): pentest findings, triage, allowlisting, tickets and autofix.
* [Exploit validation](/api-reference/api-reference/pentester/exploit-validation): policies, arming, validation runs and attempts.

## Bug Hunt

Bug Hunt, the lighter-weight assessment of an external attack surface, has its own page: see [Bug Hunts API](/api-reference/api-reference/bug-hunts) for the `/dast/bughunt` operations.

## Published operation index

This index comes from the [published specification](/api-reference/api-reference/openapi-spec). Check its request and response schemas before calling an operation; deployment versions and feature availability can differ.

| Method   | Path                                                                  | Operation                                        |
| -------- | --------------------------------------------------------------------- | ------------------------------------------------ |
| `GET`    | `/dast/applications`                                                  | List Applications                                |
| `POST`   | `/dast/applications`                                                  | Create Application                               |
| `POST`   | `/dast/applications/from-context`                                     | Create Assessment Setup From Context Application |
| `POST`   | `/dast/applications/readiness`                                        | Get Application Assessment Readiness             |
| `DELETE` | `/dast/applications/{applicationId}`                                  | Delete Application                               |
| `GET`    | `/dast/applications/{applicationId}`                                  | Get Application                                  |
| `PUT`    | `/dast/applications/{applicationId}`                                  | Update Application                               |
| `GET`    | `/dast/credentials`                                                   | Get All Credentials                              |
| `POST`   | `/dast/credentials`                                                   | Create Credential                                |
| `POST`   | `/dast/credentials/login-definition`                                  | Create Credential From Login Definition          |
| `POST`   | `/dast/credentials/validate`                                          | Validate Credentials                             |
| `DELETE` | `/dast/credentials/{credentialId}`                                    | Delete Credential                                |
| `GET`    | `/dast/credentials/{credentialId}`                                    | Get Credential                                   |
| `PUT`    | `/dast/credentials/{credentialId}`                                    | Update Credential                                |
| `PUT`    | `/dast/credentials/{credentialId}/active`                             | Switch Credential On or Off                      |
| `POST`   | `/dast/credentials/{credentialId}/login-assist/answer`                | Answer Credential Login Question                 |
| `POST`   | `/dast/credentials/{credentialId}/login-assist/retry`                 | Retry Credential Login                           |
| `PUT`    | `/dast/credentials/{credentialId}/login-definition`                   | Update Credential Login Definition               |
| `POST`   | `/dast/credentials/{credentialId}/login-reset`                        | Reset Credential Login                           |
| `GET`    | `/dast/credentials/{credentialId}/login-runs`                         | Credential Login Runs                            |
| `GET`    | `/dast/credentials/{credentialId}/login-runs/{runId}`                 | Credential Login Run                             |
| `GET`    | `/dast/credentials/{credentialId}/login-status`                       | Credential Login Status                          |
| `POST`   | `/dast/credentials/{credentialId}/session-lease`                      | Lease Credential Session                         |
| `POST`   | `/dast/credentials/{credentialId}/validate`                           | Validate Credential                              |
| `GET`    | `/dast/credentials/{credentialId}/validations`                        | Credential Validation History                    |
| `POST`   | `/dast/credentials/{credentialId}/validations`                        | Start Credential Validation                      |
| `GET`    | `/dast/credentials/{credentialId}/validations/status`                 | Credential Validation Status                     |
| `GET`    | `/dast/exploit-validation/attempts`                                   | List Exploit Validation Attempts                 |
| `GET`    | `/dast/exploit-validation/findings/{findingId}/evidence/{evidenceId}` | Get an Exploit Validation Evidence File          |
| `POST`   | `/dast/exploit-validation/findings/{findingId}/validate`              | Start Exploit Validation for a Finding           |
| `GET`    | `/dast/exploit-validation/policies`                                   | List Exploit Validation Policies                 |
| `POST`   | `/dast/exploit-validation/policies`                                   | Create Exploit Validation Policy                 |
| `DELETE` | `/dast/exploit-validation/policies/{policyId}`                        | Delete Exploit Validation Policy                 |
| `PUT`    | `/dast/exploit-validation/policies/{policyId}`                        | Update Exploit Validation Policy                 |
| `POST`   | `/dast/exploit-validation/policies/{policyId}/arm`                    | Arm an Exploit Validation Policy                 |
| `POST`   | `/dast/exploit-validation/policies/{policyId}/disarm`                 | Disarm an Exploit Validation Policy              |
| `GET`    | `/dast/exploit-validation/runs/{runId}`                               | Get Exploit Validation Run                       |
| `GET`    | `/dast/pentest/applications`                                          | Get Pentest App Configs                          |
| `POST`   | `/dast/pentest/applications`                                          | Create Application                               |
| `DELETE` | `/dast/pentest/applications/{applicationId}`                          | Delete Pentest App Config                        |
| `GET`    | `/dast/pentest/applications/{applicationId}`                          | Get Pentest App Config                           |
| `PATCH`  | `/dast/pentest/applications/{applicationId}`                          | Partially Update Application                     |
| `PUT`    | `/dast/pentest/applications/{applicationId}`                          | Update Application                               |
| `GET`    | `/dast/pentest/applications/{applicationId}/estimate`                 | Get Pentest Cost Estimate                        |
| `PUT`    | `/dast/pentest/applications/{applicationId}/mutation-consent`         | Create Interactor \[]                            |
| `POST`   | `/dast/pentest/applications/{applicationId}/preflight`                | Start Pentest Preflight                          |
| `GET`    | `/dast/pentest/applications/{applicationId}/preflight/latest`         | Get Latest Pentest Preflight for Application     |
| `GET`    | `/dast/pentest/applications/{applicationId}/preflight/quota`          | Get Pentest Preflight Quota                      |
| `GET`    | `/dast/pentest/budget`                                                | Get Pentest Budget                               |
| `GET`    | `/dast/pentest/findings`                                              | Get Pentest Findings                             |
| `GET`    | `/dast/pentest/findings/{findingId}`                                  | Get Pentest Finding                              |
| `POST`   | `/dast/pentest/findings/{findingId}/allowlist`                        | Allowlist Pentest Finding                        |
| `GET`    | `/dast/pentest/findings/{findingId}/autofix/activity`                 | Get DAST Pentest Finding Autofix Activity        |
| `POST`   | `/dast/pentest/findings/{findingId}/autofix/fix`                      | Post DAST Pentest Finding AutoFix                |
| `GET`    | `/dast/pentest/findings/{findingId}/autofix/state`                    | Get DAST Pentest Finding Autofix State           |
| `GET`    | `/dast/pentest/findings/{findingId}/autofix/status`                   | Get DAST Pentest Finding Autofix Status          |
| `GET`    | `/dast/pentest/findings/{findingId}/events`                           | Get Pentest Finding Events                       |
| `GET`    | `/dast/pentest/findings/{findingId}/full`                             | Get Pentest Finding Full                         |
| `DELETE` | `/dast/pentest/findings/{findingId}/ticket`                           | Delete Ticket for Pentest Finding                |
| `POST`   | `/dast/pentest/findings/{findingId}/ticket`                           | Create Ticket for Pentest Finding                |
| `GET`    | `/dast/pentest/findings/{findingId}/triage`                           | Get Pentest Finding Full                         |
| `POST`   | `/dast/pentest/findings/{findingId}/unallowlist`                      | Unallowlist Pentest Finding                      |
| `GET`    | `/dast/pentest/mutation-warning`                                      | Create Interactor \[]                            |
| `GET`    | `/dast/pentest/preflights/{preflightId}`                              | Get Pentest Preflight                            |
| `GET`    | `/dast/pentest/preflights/{preflightId}/events`                       | Get Pentest Preflight Events                     |
| `GET`    | `/dast/pentest/scans`                                                 | Get Pentest Scans                                |
| `GET`    | `/dast/pentest/scans/{scanId}`                                        | Get Pentest Scan                                 |
| `GET`    | `/dast/pentest/scans/{scanId}/activity`                               | Get Pentest Scan Activity                        |
| `POST`   | `/dast/pentest/scans/{scanId}/archive`                                | Archive Pentest Scan                             |
| `GET`    | `/dast/pentest/scans/{scanId}/auth-matrix/cases`                      | List pentest auth-matrix cases                   |
| `GET`    | `/dast/pentest/scans/{scanId}/auth-matrix/evidence`                   | Get retained pentest attempt evidence            |
| `GET`    | `/dast/pentest/scans/{scanId}/events`                                 | Get Pentest Scan Events                          |
| `GET`    | `/dast/pentest/scans/{scanId}/findings`                               | Get Pentest Scan Findings                        |
| `GET`    | `/dast/pentest/scans/{scanId}/findings/links`                         | Get Pentest Scan Finding Links                   |
| `GET`    | `/dast/pentest/scans/{scanId}/hypotheses`                             | Get Auth Matrix Hypotheses                       |
| `GET`    | `/dast/pentest/scans/{scanId}/logs`                                   | Get Sub-Agent Network Log                        |
| `GET`    | `/dast/pentest/scans/{scanId}/logs/transactions`                      | Get filtered pentest capture transactions        |
| `GET`    | `/dast/pentest/scans/{scanId}/report`                                 | Get Pentest Scan Report                          |
| `GET`    | `/dast/pentest/scans/{scanId}/report/download`                        | Get Pentest Scan Report Download URL             |
| `GET`    | `/dast/pentest/scans/{scanId}/report/external/pdf`                    | Get Pentest Scan External Report PDF             |
| `GET`    | `/dast/pentest/scans/{scanId}/report/pdf`                             | Get Pentest Scan Report PDF                      |
| `GET`    | `/dast/pentest/scans/{scanId}/status`                                 | Get Pentest Scan Progress Status                 |
| `POST`   | `/dast/pentest/scans/{scanId}/stop`                                   | Stop Pentest Scan                                |
| `POST`   | `/dast/pentest/start`                                                 | Request Pentest Assessment                       |
| `GET`    | `/dast/scans/status/last`                                             | Get Pentest Last Scan Status                     |
| `GET`    | `/dast/sourceips`                                                     | Get Source IPs                                   |
| `GET`    | `/dast/targets`                                                       | List Targets                                     |
| `POST`   | `/dast/targets`                                                       | Create Target                                    |
| `POST`   | `/dast/targets/validate`                                              | Validate Targets                                 |
| `DELETE` | `/dast/targets/{targetId}`                                            | Delete Target                                    |
| `GET`    | `/dast/targets/{targetId}`                                            | Get Target                                       |
| `PUT`    | `/dast/targets/{targetId}`                                            | Update Target                                    |
| `PUT`    | `/dast/targets/{targetId}/classification`                             | Create Interactor \[]                            |
| `DELETE` | `/dast/targets/{targetId}/exploit-validation-consent`                 | Revoke Exploit Validation Write Risk             |
| `GET`    | `/dast/targets/{targetId}/exploit-validation-consent`                 | Get Exploit Validation Consent                   |
| `PUT`    | `/dast/targets/{targetId}/exploit-validation-consent`                 | Accept Exploit Validation Write Risk             |
| `POST`   | `/dast/targets/{targetId}/validate`                                   | Validate Target                                  |
| `GET`    | `/dast/targets/{targetId}/validations`                                | Target Validation History                        |
| `GET`    | `/dast/web-services`                                                  | List Web Services                                |
| `POST`   | `/dast/web-services`                                                  | Create Web Service                               |
| `DELETE` | `/dast/web-services/{webServiceId}`                                   | Delete Web Service                               |
| `GET`    | `/dast/web-services/{webServiceId}`                                   | Get Web Service                                  |
| `PUT`    | `/dast/web-services/{webServiceId}`                                   | Update Web Service                               |
| `POST`   | `/dast/web-services/{webServiceId}/access-validation`                 | Validate Web Service Access                      |
| `GET`    | `/dast/web-services/{webServiceId}/access-validations`                | Web Service Access Validation History            |
| `GET`    | `/dast/web-services/{webServiceId}/credentials`                       | List Web Service Credentials                     |
| `POST`   | `/dast/web-services/{webServiceId}/credentials`                       | Map Credential to Web Service                    |
| `DELETE` | `/dast/web-services/{webServiceId}/credentials/{credentialId}`        | Unmap Credential from Web Service                |
| `POST`   | `/dast/web-services/{webServiceId}/status-validation`                 | Validate Web Service Status                      |
| `GET`    | `/dast/web-services/{webServiceId}/status-validations`                | Web Service Status Validation History            |


# Pentest Applications, Preflight and Budget

Applications, their targets and web services, the preflight readiness check, cost estimates, budget headroom, mutation-testing consent, and the source IP addresses to allowlist. Start a run with [`POST /dast/pentest/start`](/api-reference/api-reference/pentester) once an application is configured.

All requests are scoped to your tenant by the same provider scope parameter (for example `githubOwnerId`) used across the API, and every id is resolved within that tenant. Page through lists with `nextToken` as described in [pagination](/api-reference/api-reference/pagination).

## Two views of an application

Two route families manage the same applications, one application id and one stored record, through different shapes.

* `/dast/applications` is the full model. An application is a named set of web services (created under `/dast/web-services`, which carry the targets and credential mappings) plus an optional deny list of paths that must not be tested. It requires at least one existing web service.
* `/dast/pentest/applications` is the flattened pentest configuration for the same application id: a list of targets (host and port) and a list of credential ids, plus the mutation-testing consent state. An application created or deleted through one family appears in or disappears from the other.

Use `/dast/applications` to describe what an application is made of, and `/dast/pentest/applications` when all you need is targets and credentials for a run. An `id` you supply on a pentest configuration target that matches a target of your tenant at the same host and port means that target. Any other target is matched by host and port, reusing a stored target at that endpoint, so an id that names nothing is not preserved and reads report the stored or generated id. An entry with no matching id is refused with 409 when two linked targets share its host and port. The `/dast/pentest/applications` create call takes the application `id` from you, and it must be the id of an existing application in your context application inventory: an unknown id is refused with 404 and nothing is stored. The `/dast/applications` create call can also resolve the id from that inventory, as described below.

## Applications

### List applications

Returns the tenant's applications from `/dast/applications`, paginated with `nextToken` and `limit`. Use the returned ids as `applicationId` in the other routes.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/applications" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Create an application

Creates an application from `webServiceIds` (at least one, deduplicated, each of which must already exist in your tenant, otherwise the call returns 404). The application's id is its context application id: pass `contextApplicationId` to choose one (404 if it does not exist), or omit it and Nullify resolves it from the repositories your web services are mapped to. The call fails with 400 if no web service is mapped to a repository or if they span more than one context application, and with 412 if no context application covers them, so connect the repository to an application in context first. A duplicate id returns 409. `scopeExcludePatterns` are case-insensitive `[METHOD ]<path>` deny rules that include subtrees; a rule that cannot be compiled is rejected with 400. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/applications" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get an application

Returns one application by `applicationId`. Returns 404 if it does not exist in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/applications/{applicationId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update an application

Replaces the application's web services, name, description and `scopeExcludePatterns` with the request body. It is a full replacement, not a merge, so send the complete list of `webServiceIds` (at least one) and the same validation as create applies. Returns 404 for an unknown id. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/applications/{applicationId}" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete an application

Soft-deletes the application and records the caller as the deleter. Returns 404 if it does not exist. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/applications/{applicationId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Pentest application configuration

### List pentest application configs

Lists every application's pentest configuration (targets, credential ids, creation and update times), paginated with `nextToken` and `limit`. Requires the config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/applications?githubOwnerId=1234'
```

### Create a pentest application

Creates a pentest configuration under the `id` you supply (required). `targets` are objects with `name`, `host` and `port`; a target without an `id` gets a generated one (see the note above on target ids). Hosts and ports are validated, and the number of targets and credentials is capped. `credentialIds` must refer to existing credentials, otherwise the call returns 400. A live duplicate id returns 409; re-creating a previously deleted id is accepted and applies the new configuration. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a pentest application

Returns one pentest configuration by `applicationId`, or 404. Requires the config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a pentest application

Replaces the configuration. If `targets` is present it replaces the whole target list (and is validated as in create); if it is omitted the targets are left unchanged. If `credentialIds` is present it replaces the credential list, and an empty array clears it; if it is omitted the credentials are left unchanged. An empty `targets` array removes the targets and keeps the application's web service, its credentials and its source mapping, and a run then reports that the web service has no targets. Returns 404 for an unknown id and 400 for an unknown credential. Returns 409 and writes nothing when the application changed since it was read, or when the change needs a web service edit: a target change on an application with a mounted, shared or more than one web service, or a new credential on a shared or more than one web service.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Partially update a pentest application

Changes only the fields you send: a present `targets` replaces the target list, and an empty array removes the targets under the same rules as PUT. A present `credentialIds` replaces the credential list (send an empty array to clear it). Target hosts must be bare hostnames or IPs without a scheme or path. This route applies the target-count and port validation, and a target already stored for your tenant keeps its stored host and port without re-validation. It does not generate ids for targets sent without one, so include each target's `id` to keep that target. The response carries the current `mutationConsent` state.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}" method="patch" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Move a target or credential to another application

`POST /dast/pentest/applications/{applicationId}/move` moves one item from this application to `toApplicationId`, in one transaction. Send `targetId` or `credentialId`, not both. The rules of the update apply to both applications, and a refusal from either returns 409 and writes nothing to both. A destination with no pentest configuration is created in the same transaction when it is a live context application. Returns 400 when the destination already holds the maximum number of targets or credentials, 404 for an unknown application, and 409 when this application no longer holds the item. A target change revokes the exploit-validation consent of policies linking the web services it changes. Requires the config-write permission.

### Delete a pentest application

Deletes the pentest configuration and records the caller as the deleter. Returns 404 if it does not exist. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Estimate, preflight and budget

### Estimate pentest cost

Predicts the duration and LLM cost of a pentest for the application without running anything and without calling an LLM. The result is a heuristic. When the application has a stored preflight with a resolved application context, the estimate is sized from it and `source` is `preflight`; otherwise `source` is `heuristic` and the figures are coarser. In both cases the estimate is blended with the median duration of the application's own completed pentests when there are any (`basedOnHistoricalRuns` is the count of runs used). Compare the cost with [Get pentest budget](#get-pentest-budget).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}/estimate" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/applications/01J6EEXK3N6A1Q4JH1JHT0TK5X/estimate?githubOwnerId=1234'
```

### Start a preflight

Starts a readiness check for the application ahead of a pentest. It validates credentials, retrieves application context, enumerates network-reachable findings, and produces a summary and an estimate. The response is the new preflight with a `runStatus` of in progress: the check is asynchronous, so poll [Get a preflight](#get-a-preflight) or [Get preflight events](#get-preflight-events). Errors: 404 if the application is unknown, 400 if it has no target, 409 if a preflight is already running for that application, and 429 once five non-failed preflights have been started for the application in the last 24 hours. Requires the finding-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}/preflight" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/applications/01J6EEXK3N6A1Q4JH1JHT0TK5X/preflight?githubOwnerId=1234'
```

### Get the latest preflight for an application

Returns the application's most recent preflight, or null if none has ever been run.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}/preflight/latest" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get preflight quota

Returns `used`, `limit` (5) and `windowResetAt` for the application's rolling 24-hour preflight window, from the same count the start route enforces.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}/preflight/quota" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get a preflight

Returns one preflight by `preflightId` (from the start response or the latest route), including the readiness summary once the run completes. Poll until `runStatus` is terminal. Returns 404 for an unknown id.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/preflights/{preflightId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get preflight events

Returns the progress events of a preflight run for incremental polling. Pass `afterSeq=0` on the first call, then pass the `highestSeq` from the previous response; `limit` bounds the page.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/preflights/{preflightId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get pentest budget

Returns the tenant's remaining pentest budget for the tightest applicable calendar window: `limitUsd`, `consumedUsd`, `heldUsd`, `remainingUsd`, `timeWindow` and `windowEnd`. `unlimited` means no budget caps pentests (ignore the dollar figures), and `frozen` means a configured limit of zero, which denies all runs. It reads billing on your behalf and can return a transient error if billing is unavailable. Requires the finding-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/budget" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Mutation testing consent

Mutation testing sends state-changing requests to your application as each configured identity, to test who may create, modify and delete data. It is off until someone with write access acknowledges the current warning.

### Get the mutation warning

Returns the `text` of the warning and its `version`. Show the text to the person enabling the feature, then send the `version` back when enabling.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/mutation-warning" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Set mutation consent

Enables or disables mutation testing for the application. Body: `enabled` (required) and `warningVersion`. When enabling, `warningVersion` must equal the current version from the warning route, otherwise the call fails with 400, so the acknowledgment always matches the text shown. The acknowledging user is recorded from the authenticated caller, and the caller needs the config-write permission (403 otherwise). Returns 404 for an unknown application. Disabling stops new mutation requests but does not undo changes already made.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/applications/{applicationId}/mutation-consent" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Source IP addresses

### Get source IPs

Returns the public IP addresses that pentest traffic originates from, in `ips` (sorted, deduplicated) with the `region`. The list combines the addresses used for operator-driven runs and the addresses that hosted runs leave through, so allowlist all of them on your WAF or firewall. If the hosted-run addresses cannot be looked up, the response falls back to the operator-driven addresses only. Results are cached for 24 hours. Requires the config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/sourceips" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

\`\`\`bash curl -s \ -H "Accept: application/json" \ -H "Authorization: Bearer " \ '<https://api..nullify.ai/dast/sourceips?githubOwnerId=1234>' \`\`\`


# Pentest Credentials

Credentials are the logins and API keys a pentest uses to test your application as an authenticated user. They live in the tenant vault, are shared across applications and web services, and are attached to an application through [`credentialIds`](/api-reference/api-reference/pentester/applications#create-a-pentest-application) or to a web service through its credential mapping.

Secrets are write-only: every response that returns a credential masks password, token, API key, client secret, refresh token and TOTP secret values. Use `{credentialId}` from the list or create response. Requests are scoped to your tenant by the provider scope parameter (for example `githubOwnerId`).

## Manage credentials

### List credentials

Returns the tenant's credentials with a `totalCount`. With no `limit`, `offset` or `search` it returns every credential; otherwise it returns a page using `offset` and `limit` (default 50, maximum 1000) and a case-insensitive `search` over name, description and type. Note this route pages with `offset`, not `nextToken`. Requires the secret-config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/credentials?githubOwnerId=1234&limit=50&search=staging'
```

### Create a credential

Creates a credential from `name`, `type` and `config` (a `description` is also accepted). Supported types are `username_password`, `api_key`, `basic_auth`, `oidc` and `oauth2`; legacy names such as `basic`, `bearer`, `browser`, `custom`, `application_login`, `application_login_mfa` and `sso` are accepted and normalized to one of those, and other values return 400. The save is checked for the fields the type needs and for a valid auth policy (400 otherwise), but whether the login actually works is only tested by validation. Any `discovered` block in `config` is ignored: Nullify writes it during validation. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging admin", "description": "Admin login for staging", "type": "username_password", "config": {"username": "admin@example.com", "password": "<PASSWORD>"}}' \
  'https://api.<TENANT>.nullify.ai/dast/credentials?githubOwnerId=1234'
```

### Get a credential

Returns one credential with secrets masked, or 404 if the id does not exist in your tenant. Requires the secret-config-read permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Update a credential

Replaces the credential's `name`, `description`, `type` and `config`; `name` and `type` are required and the same type normalization and checks as create apply. It is a full replacement, so send the whole configuration. The server-written `discovered` block is preserved rather than taken from the request. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}" method="put" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Delete a credential

Deletes the credential and records the caller as the deleter. Returns 404 if it does not exist in your tenant. Requires the config-write permission.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}" method="delete" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Validate credentials

Validation tests that Nullify can authenticate with a credential, using the safest supported check. Simple credentials are settled inline. Interactive logins (for example a browser form login) are queued, and the response then has `outcome` `inconclusive`, an empty `validatedAt` and a `validationId`: poll [Credential validation status](#credential-validation-status) until the run finishes. All validation routes require the config-write permission except the two read routes.

Errors on the single-credential routes: 404 for an unknown credential, 409 when a validation is already running for it, 429 once the tenant has used its daily allowance of 20 interactive validation runs, and 409 (aborted) when the credential was changed while the check ran, in which case retry.

### Validate a credential

Validates one credential and records the attempt in its history. Optional `testUrl` overrides the URL to authenticate against; without it the server uses the credential's login or token URL, or the application's target. The response carries `valid`, `outcome`, `reasonCode`, `validationId` and evidence. Only a verdict produced by your target updates the credential's own validation state, so a timeout or a WAF block is recorded as an attempt without marking the credential broken.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}/validate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"testUrl": "https://app.example.com/login"}' \
  'https://api.<TENANT>.nullify.ai/dast/credentials/01J6EEXK3N6A1Q4JH1JHT0TK5X/validate?githubOwnerId=1234'
```

### Validate several credentials

Validates up to 50 credentials in one request, sequentially, using `credentialIds` and an optional `testUrl` applied to all. The response has one entry per id in `results`. A credential that is missing or fails to validate does not fail the batch; its entry reports the error with an `inconclusive` outcome. Queued interactive checks appear as inconclusive with an empty `validatedAt`; poll their status individually. More than 50 ids returns 400.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/validate" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Start a credential validation

Starts a validation for one credential, running an interactive login where an inline check cannot settle it. The body takes an optional `testUrl`. The response is the run: `runStatus`, `runId`, `startedAt`, `expiresAt`, `retryAt`, `outcome`, `reasonCode` and the validation evidence. An attempt expires after 15 minutes. This is the newer equivalent of the single-credential validate route and uses the same service call.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}/validations" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Credential validation status

Reports the credential's current validation run in the same shape as the start response. It is a plain read that does not expose secret material, so poll it while a queued validation is running and stop when `runStatus` is no longer live.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}/validations/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Credential validation history

Lists past validation attempts for the credential, paginated with `nextToken` and `limit`.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/credentials/{credentialId}/validations" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}


# Pentest Engagements

An engagement is one pentest run against an onboarded application. Start one with `POST /dast/pentest/start`, follow it through its status, events and activity feeds, then read its findings and reports once it reaches a terminal status. All paths are relative to `https://api.<TENANT>.nullify.ai`, and all accept the provider scope parameter used elsewhere in the API (for example `githubOwnerId`).

A scan's `status` is one of `queued`, `in progress`, `stopping`, `completed`, `cancelled`, `failed`, `aborted_config_error`, `human_fallback`, `awaiting_manual` or `skipped`. `completed`, `cancelled`, `failed`, `aborted_config_error` and `skipped` are terminal; the other states can still change.

## Start and list engagements

### Start an engagement

Starts a pentest for the application in `applicationId` (from [List applications](/api-reference/api-reference/pentester/applications#list-applications)). Omit `configOverrides` to use the default run configuration. If you supply this optional object, include all three required booleans: `enablePentestTools`, `enableAuthMatrix` and `enableExploitAnalysis`. The target URL, scope exclusions and credentials come from the stored application. Requires write permission on findings, and the tenant must have completed onboarding, otherwise the call returns a failed-precondition error.

The response carries the new scan and a `mode`: `self_serve_started` means the pentest workflow was launched and the scan is `in progress`; `manual_requested` means self-serve pentesting is not enabled for your tenant, so the scan was queued as `awaiting_manual` for a Nullify operator to run. A start response means a job was accepted, not that testing has finished; poll the status operations below.

Only one pentest can run per application at a time, so a second start for the same application returns an already-exists error until the first scan finishes or is stopped. Other errors to expect: not found for an unknown `applicationId`, invalid argument when the application has no usable target or the target is blocked (internal addresses are rejected) or unreachable, and resource exhausted when the tenant's pentest budget is spent (see [Get pentest budget](/api-reference/api-reference/pentester/applications#get-pentest-budget)).

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/start" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "applicationId": "01J6EEXK3N6A1Q4JH1JHT0TK5X"
      }' \
  'https://api.<TENANT>.nullify.ai/dast/pentest/start?githubOwnerId=1234'
```

### List engagements

Lists the tenant's pentest scans. Paginate with `limit` and `nextToken` (see [Pagination](/api-reference/api-reference/pagination)); `offset` is also accepted and, when greater than zero, overrides `nextToken`. `search` filters server-side by application id or status text. The response includes a `totalCount`. An undecodable `nextToken` returns an invalid-argument error.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/scans?githubOwnerId=1234'
```

### Get an engagement

Returns the full record of one scan by `scanId` (from List engagements or the start response). Returns not found for a scan that does not exist in your tenant.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/scans/01J6EEXK3NKYKWW9XTPQYAF41N?githubOwnerId=1234'
```

## Follow a running engagement

### Poll live status

A lightweight poll for a scan's lifecycle status, coarse progress and the latest phase and activity the agent reported. The `terminal` field is true once the scan has stopped progressing, so you can stop polling. Prefer this over repeatedly calling Get an engagement.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/status" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Read the activity log

Returns the scan's activity feed, oldest first, as a cursor-paginated list. `limit` defaults to 50 and is clamped to 1 to 200. Pass the `nextCursor` from the previous response as `since_id` to fetch only newer entries. The list is empty until the scan has produced activity.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/activity" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Read lifecycle events

Returns the scan's lifecycle events (state transitions and similar milestones). For incremental polling, pass the previous response's `highestSeq` as `afterSeq`; `limit` caps the page. An empty list means the scan has no events yet.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/events" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the last scan status

Returns the most recent scan status for the tenant (scan id, status, start and end time, and a findings count when available). Despite the `/dast/scans` path and the "Pentest" title in the specification, the handler reads the latest Bug Hunt scan, not a pentest, so use [Poll live status](#poll-live-status) for pentests and the Bug Hunt operations in [Bug Hunts API](/api-reference/api-reference/bug-hunts) for this value. The field is omitted when the tenant has no Bug Hunt scans.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/scans/status/last" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Stop an engagement

Requests cancellation of a scan; requires write permission on findings. A scan that is `queued` or `in progress` moves to `stopping` and the agent finishes its own cleanup, so poll the status operation to see when it reaches a terminal status. A scan that is `awaiting_manual`, `human_fallback` or already `stopping` moves straight to `cancelled`, which also frees the application for a new run. Scans in any other state (for example already completed) return a failed-precondition error, so the call is not a general "make sure it is stopped" operation. The response contains the scan as it stands after the request.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/stop" method="post" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/scans/01J6EEXK3NKYKWW9XTPQYAF41N/stop?githubOwnerId=1234'
```

## Findings of an engagement

### List engagement findings

Returns every pentest finding raised by the scan. The scan must exist in your tenant (otherwise not found). To filter, sort or paginate across scans, use [List findings](/api-reference/api-reference/pentester/findings#list-findings) with its `scanId` query parameter instead.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/findings" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/scans/01J6EEXK3NKYKWW9XTPQYAF41N/findings?githubOwnerId=1234'
```

### List finding links

Returns the findings mapped to the scan, including natively discovered findings, findings attached manually and findings validated by exploit analysis. Use it when the set of findings associated with a run is wider than the findings the run itself created.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/findings/links" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Authorization testing evidence

These operations expose the authorization-matrix testing a scan performed when the application has credentials for more than one identity.

### List auth-matrix hypotheses

Returns the authorization-matrix hypotheses for the scan with their full evidence. Returns not found when the scan does not exist or has no hypotheses stored.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/hypotheses" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List auth-matrix cases

Returns one page of the scan's frozen auth-matrix cases, ordered by case key; each case carries its `outcome`, `reason` and a derived `lifecycle` (`not_started`, `policy_skipped`, `resolved`, `inconclusive` or `unrecognised`). Filters combine with AND: `outcome` (`accepted`, `authz_denied`, `schema_rejected`, `policy_skipped`, `not_found`, `conflict`, `server_error` or `unknown`), `identity` (a credential id), and `hideNotRun` to drop cases the run never attempted. Page with `limit` (default 50, maximum 200) and `offset`; `total` counts the filtered set. An unrecognised filter value returns invalid argument.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/auth-matrix/cases" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get retained attempt evidence

Returns durable attempt metadata and scrubbed request and response body links for the scan, independent of the proxy capture. The scan must be in a terminal status and you must supply an `evidenceRef` (taken from an auth-matrix case's `evidenceRefs`) or an `attemptId`; otherwise the call fails with a failed-precondition or invalid-argument error. Optional filters (`stage`, `since`, `until`, `identityId`, `method`, `path`) combine with AND, and `cursor` continues a previous page. Download links expire after 15 minutes and must be fetched with the conditional headers the response returns.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/auth-matrix/evidence" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Network capture

### Get the network log

Returns a short-lived presigned URL for downloading the pentest sub-agent network log. Fetch the URL promptly rather than storing it. Returns not found when the scan does not exist in your tenant or no log was stored for it.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/logs" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### List capture transactions

Returns bounded pages of the scan's recorded HTTP transactions with attempt correlation, as an alternative to downloading the whole log. Filter with `stage`, `since`, `until`, `method`, `path`, `identityId` and `evidenceRef`, and continue with `cursor`. Stage filters correspond to recorded time windows, which can overlap, so a transaction can match more than one stage. The call returns failed precondition when the capture is unavailable, changed while you were paging, or exceeds size limits, and invalid argument for a malformed filter or cursor.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/logs/transactions" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

## Reports

Every report operation requires the scan to be in a terminal status; before that they return a failed-precondition error. When the scan ended in any terminal status other than `completed`, the response sets `partial` to true, meaning the report reflects an incomplete run. A missing report artifact returns not found.

### Get the report

Returns the scan's report as JSON. Use the repeatable `exclude` query parameter to leave out heavy parts: `cases` (empties the auth-matrix case rows while keeping the counts; page the rows with [List auth-matrix cases](#list-auth-matrix-cases)), `exploitAnalysisResult` and `appendices`. Any other value returns invalid argument.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/report" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

```bash
curl -s \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  'https://api.<TENANT>.nullify.ai/dast/pentest/scans/01J6EEXK3NKYKWW9XTPQYAF41N/report?githubOwnerId=1234'
```

### Get the report download URL

Returns a presigned URL for the stored report file rather than its contents, for when you want to hand the artifact to another system. Treat the URL as short-lived.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/report/download" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the report PDF

Returns a presigned URL for the PDF report. If the summary edition has been published for the scan, the URL points to it; otherwise it points to the full PDF with findings, evidence and remediation. Use [Get the summary PDF](#get-the-summary-pdf) when you specifically need the summary edition.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/report/pdf" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}

### Get the summary PDF

Returns a presigned URL for the summary PDF: findings, severities and statuses without the captured evidence behind them, suitable for sharing outside the security team. Scans published before this edition existed have none and return not found.

{% openapi src="/files/1NgvLK12PRq7RFdn97yd" path="/dast/pentest/scans/{scanId}/report/external/pdf" method="get" %}
[nullify-openapi-bundle.yaml](https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-bb82381e6a6277c824c1f4817e3172c990a1fed2%2Fnullify-openapi-bundle.yaml?alt=media)
{% endopenapi %}




---

[Next Page](https://docs.nullify.ai/llms-full.txt/1)

