# Perpensa

> Risk-first dependency update prioritization, auditable vulnerability scoring, Perpensa Rank, CycloneDX and SPDX SBOM exports, CI gates, and a read-only Streamable HTTP MCP server for coding agents.

Perpensa scans dependency manifests and lockfiles across your repositories, groups overlapping advisories into actionable package updates, and orders your remediation queue by real exploitation risk before volume.

## Core capabilities

- **Risk-first triage categories**: Every dependency update and vulnerability finding is classified into one of three categories by deterministic rules:
  - `Fix now` (`fix_now`): production exposure (or assumed production when context is unknown) combined with known active exploitation (**CISA KEV**) or high exploitation probability (**FIRST EPSS >= 10%**). When no verified corrective version is available, immediate mitigation is flagged.
  - `Plan` (`plan`): active exploitation signals (**CISA KEV** or **EPSS >= 10%**) outside runtime production (dev/test or declared non-production), disputed CVEs with an unknown KEV signal, or findings and updates where neither the immediate-exploitation rule nor a verified `Monitor` rule applies (including critical or high severity findings without KEV or EPSS >= 10%).
  - `Monitor` (`monitor`): verified low-exposure backlog items (explicit VEX `not_affected`, rejected CVEs, disputed CVEs with verified `KEV = false`, dev/test or non-production items with verified `KEV = false` and `EPSS < 10%`, or production items with verified `KEV = false` and `EPSS < 1%` in the low severity band or medium transitive findings with no known fix).
- **Auditable 0-100 risk score**: Deterministic scoring combining CVSS base severity, FIRST EPSS 30-day exploitation probability, CISA KEV known-exploited status, reachability signal (unknown by default unless an explicit signal is supplied; Perpensa does not perform call-graph reachability analysis), direct vs. transitive dependency status, and fixed baseline weights for blast radius and update lag.
- **Perpensa Rank (Pro and Team)**: Rules always set the category (`Fix now`, `Plan`, `Monitor`). On Pro and Team plans, Perpensa Rank refines the priority order within that category by up to +/-30 points using vulnerability and application/environment exposure context, with cited explanations.
- **Supported ecosystems and manifests**: npm (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `package.json`), PyPI (`poetry.lock`, `Pipfile.lock`, `uv.lock`, pinned `requirements.txt`), Go (`go.mod`, `go.sum`), Maven and Gradle (`pom.xml`, `gradle.lockfile`), Cargo (`Cargo.lock`), Composer (`composer.lock`), NuGet (`packages.lock.json`), RubyGems (`Gemfile.lock`), `*.rockspec` / `luarocks.lock` (LuaRocks inventory only; vulnerability coverage unavailable), and `Dockerfile` base-image lifecycle and digest-pinning checks.
- **Advisory and threat intelligence sources**:
  - **OSV** (`https://osv.dev`) for ecosystem package-range matching.
  - **GitHub Advisory Database** (`GHSA-*`) and **NVD / CVE** (`CVE-*`) records.
  - **ENISA European Union Vulnerability Database (EUVD)** (`EUVD-YYYY-NNNN` at `https://euvd.enisa.europa.eu`) cross-references and aliases preserved from upstream advisories for European NIS2 / CRA compliance workflows.
  - **FIRST EPSS** (Exploit Prediction Scoring System) and **CISA KEV** (Known Exploited Vulnerabilities catalog).
- **SBOM and compliance exports**: Asynchronous generation of **CycloneDX 1.6 JSON** (`sbom_cdx_json`), **SPDX 2.3 JSON** (`sbom_spdx_json`), findings CSV (`findings_csv`), prioritized updates CSV (`updates_csv`), and structured compliance reports (`compliance_report`).
- **CI gate**: Evaluate a repository source or deployment environment against organization policy via HTTP (`POST https://perpensa.app/api/v1/orgs/{org_id}/ci/check`), the repository helper (`node scripts/machine-ci-check.mjs`), or the MCP `check_ci` tool. Returns `compliant`, `non_compliant`, or `indeterminate`.
- **Strict read-only repository guarantee**: Perpensa connects to GitHub, GitLab, Forgejo, and Bitbucket in read-only mode. Perpensa never opens pull requests, never pushes commits, and never applies automated dependency bumps to your repositories.

## Perpensa MCP server (`/mcp`)

Coding agents and AI assistants can query published Perpensa results directly over the Model Context Protocol (MCP).

- **Endpoint**: `https://perpensa.app/mcp`
- **Transport and protocol**: Streamable HTTP (`POST`, `GET`, `DELETE`), MCP protocol version `2026-07-28`.
- **Plan availability**: Available on **Pro** (5 machine access slots per organization) and **Team** (25 slots per organization), shared across OAuth MCP connections and API tokens.
- **Authentication**:
  - **OAuth 2.1 with PKCE** (recommended for interactive coding agents): supports Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR). A user can grant access to selected organizations and applications (or all eligible organizations and applications), while each tool request targets one organization at a time. Consents expire after **90 days** and can be revoked at any time in **Settings → API & MCP**.
  - **Bearer API token**: Pass `Authorization: Bearer sp_api_...` for headless automation or CI workflows using a scoped token created in **Settings → API & MCP**.
- **Permissions and safety boundary**:
  - `results:read` (enabled by default): read published organizations, applications, environments, sources, dependency inventory, prioritized updates, coverage, finding explanations, update explanations, and scan status.
  - `ci:check` (enabled by default): evaluate CI gate compliance for a source or environment.
  - `exports:create` (optional): queue and download CycloneDX 1.6 / SPDX 2.3 SBOMs, CSV exports, and compliance reports.
  - `feedback:send` (optional): submit product feedback.
  - **Read-only posture guarantee**: MCP tools only read published scan results, evaluate CI gates, or request exports. They cannot start scans, modify findings, accept risks, or write to repositories.

### Quick connect snippets

#### 1. Prompt

Paste into a coding agent that supports Streamable HTTP MCP with OAuth 2.1 and PKCE:

```text
Set up the Perpensa MCP server (Streamable HTTP with OAuth):
- Server name: perpensa
- URL: https://perpensa.app/mcp
Once connected, use list_organizations and list_priorities to list our Fix now priorities for Production, then explain the first item with explain_finding or explain_update depending on its kind (skip if the queue is empty).
```

Uses Streamable HTTP (protocol 2026-07-28) with OAuth 2.1 and PKCE.

#### 2. Codex CLI

Register the Perpensa MCP server in Codex and complete the browser OAuth consent:

```sh
codex mcp add perpensa --url https://perpensa.app/mcp
codex mcp login perpensa
```

Uses Streamable HTTP (protocol 2026-07-28). Pass --oauth-client-registration cimd to codex mcp login to select CIMD explicitly, or rely on DCR fallback.

#### 3. Claude Code

Register the Perpensa MCP server in Claude Code, then complete the browser OAuth consent with claude mcp login, or run /mcp in a Claude Code session:

```sh
claude mcp add --transport http perpensa https://perpensa.app/mcp
claude mcp login perpensa
```

Headless or CI: add --header "Authorization: Bearer YOUR_API_TOKEN" with a scoped API token instead of the OAuth login. Check the connection with claude mcp list or /mcp.

#### 4. Grok Build

Register the Perpensa MCP server in Grok Build; the browser OAuth consent opens on first use:

```sh
grok mcp add --transport http perpensa https://perpensa.app/mcp
grok mcp doctor perpensa
```

Headless or CI: add --header "Authorization: Bearer YOUR_API_TOKEN" with a scoped API token. If the consent does not open, run /mcps in Grok Build, select perpensa and press i.

#### 5. ChatGPT

In ChatGPT: Plugins → + → Add custom MCP server → https://perpensa.app/mcp (OAuth), then run this prompt:

```text
Use Perpensa to list my organizations, then list the priorities for Production. Explain the first finding.
```

Choose CIMD client identification when offered; DCR is the fallback. Select @Perpensa in a conversation after authorization.

### Available MCP tools

- **Discovery and scope**:
  - `get_access`: inspect the active connection, organization scope, application scope, and granted permissions (no permission required).
  - `list_organizations`: list organizations accessible to the current token (no permission required).
  - `list_scopes`: list the organization and application scope of the current token (no permission required).
  - `list_applications`: list applications within an organization (`results:read`).
  - `list_environments`: list deployment environments for an application (`results:read`).
  - `list_sources`: list tracked repository sources and manifest paths (`results:read`).
- **Priorities, explanations, and inventory (read-only)**:
  - `list_priorities`: list the prioritized remediation queue (`kind: "finding"` and `kind: "update"` entries) for an organization, filterable by `application_id`, `environment_id`, and `category` (`fix_now`, `plan`, `monitor`) (`results:read`).
  - `explain_update`: return the update DTO (`id`, `package_name`, `ecosystem`, `from_version`, `to_version`, `channel`, `state`, `related_finding_ids`, `rank`, `category`, `explanation`, and `provenance`) for an `update_id` (`results:read`).
  - `explain_finding`: return the finding DTO (CVE, aliases such as `CVE-*`, `GHSA-*`, `EUVD-*`, summary, severity, CVSS/EPSS/KEV signals, fixed version, and provenance with Perpensa Rank context) for a `finding_id` (`results:read`).
  - `list_inventory`: list detected packages, versions, ecosystems, and manifest provenance (`results:read`).
  - `list_coverage`: inspect manifest coverage and skipped or unsupported paths (`results:read`).
  - `get_scan_status`: return the status and timestamps for a specific `scan_id` without triggering a scan (`results:read`).
- **CI gate**:
  - `check_ci`: evaluate an application environment or repository source against organization CI policy and return `compliant`, `non_compliant`, or `indeterminate` (`ci:check`).
- **Exports (opt-in permission)**:
  - `request_export`: request an asynchronous export (`sbom_cdx_json`, `sbom_spdx_json`, `findings_csv`, `updates_csv`, or `compliance_report`) (`exports:create`).
  - `get_export_status`: check the status of a requested export job (`exports:create`).
  - `read_export`: read the generated export payload once ready (`exports:create`).
- **Feedback (opt-in permission)**:
  - `send_feedback`: send structured product feedback from an assistant session (`feedback:send`).
  - `get_feedback_status`: check the status of a submitted feedback item (`feedback:send`).

## Documentation and specifications

- [Perpensa User Guide](https://docs.perpensa.app/): overview of Perpensa concepts, workflows, and plans.
- [Your first scan (Getting started)](https://docs.perpensa.app/guides/first-scan/): connect a repository in read-only mode, select a branch, and publish your first dependency scan.
- [Manage applications](https://docs.perpensa.app/guides/applications/): organize repository sources into applications and environments (such as Production or Staging) to weight risk scores.
- [Understand results and scores](https://docs.perpensa.app/guides/understanding-results/): how `Fix now`, `Plan`, and `Monitor` categories, the 0-100 deterministic risk score, Perpensa Rank, and advisory sources (OSV, GHSA, NVD/CVE, ENISA EUVD, FIRST EPSS, CISA KEV) work.
- [Remediate a vulnerability](https://docs.perpensa.app/guides/remediating-vulnerabilities/): review grouped dependency updates, verify fixed versions, and track remediation across scans.
- [Connect an assistant with MCP](https://docs.perpensa.app/guides/machine-mcp/): set up OAuth 2.1 PKCE or Bearer token access to `https://perpensa.app/mcp` for coding agents and ChatGPT.
- [Use the API and a CI gate](https://docs.perpensa.app/guides/machine-api/): integrate the `/api/v1` HTTP endpoints and CI gate into automated pipelines.
- [Exporting results (SBOM & reports)](https://docs.perpensa.app/guides/exporting-results/): generate CycloneDX 1.6 and SPDX 2.3 JSON SBOMs, CSV exports, and compliance reports.
- [Choose your email notifications](https://docs.perpensa.app/guides/email-notifications/): configure immediate alerts and scheduled vulnerability digests.
- [OpenAPI 3.1 specification](https://perpensa.app/api/v1/openapi.json): machine-readable HTTP API contract for `/api/v1`.