PIpicussecurity
Instances

# List Instance Scores

Changed on

Returns exposure instance scores in one of two mutually exclusive modes.

Pairs mode — supply filters.host_exposure_pairs to score specific host-exposure pairs. Duplicate pairs are deduplicated server-side. Unmatched pairs are omitted from the response.

Chunk mode — supply chunk to walk a tenant's entire score set as a numbered sequence. Request chunk 1 with no snapshot_version; the response reports snapshot_version, total_chunks, chunk_size and is_last. Drive every later chunk from those values, passing the returned snapshot_version so the walk stays on one snapshot. Chunk size is server-controlled and is never accepted from the request — read chunk_size from the response rather than assuming a value.

Supplying both modes, or neither, returns 422. A request body carries either filters.host_exposure_pairs or chunk, never both.

Pairs mode request:

{"filters": {"host_exposure_pairs": [{"hostname": "asset-001", "exposure_id": "CVE-2022-21903"}]}}

Chunk mode request, first chunk — no snapshot_version, the response reports the one it resolved:

{"chunk": 1}

Chunk mode request, every later chunk — snapshot_version as returned by chunk 1:

{"chunk": 2, "snapshot_version": "0f0c8e1a-9b4c-4d2e-8f1a-2b3c4d5e6f70"}
post/v1/exposures/instances/scores

Request

Request body

chunkinteger

Chunk mode. The 1-based index of the chunk to retrieve, for walking an entire score set. Mutually exclusive with filters.host_exposure_pairs.

Start at chunk 1 with no snapshot_version: the response reports the resolved snapshot_version, total_chunks and chunk_size. Drive every later chunk from those values. Chunk size is server-controlled and is never accepted from the request — read it from the response.

snapshot_versionstring

The snapshot to walk, as reported by the chunk 1 response. Required from chunk 2 onwards so a walk cannot silently cross a snapshot boundary; supplying chunk >= 2 without it returns 422.

Example request

{
  "chunk": 1,
  "filters": {
    "host_exposure_pairs": [
      {
        "exposure_id": "CVE-2022-21903",
        "hostname": "asset-001"
      }
    ]
  },
  "snapshot_version": "0f0c8e1a-9b4c-4d2e-8f1a-2b3c4d5e6f70"
}

Response

ScoresResponse contains the requested instance scores.

In pairs mode the body carries only instance_scores. In chunk mode the envelope fields are present alongside it.

chunkinteger

The 1-based index of this chunk. Chunk mode only.

chunk_sizeinteger

Server-controlled rows per chunk. Read this from the first response and reuse it for the rest of the walk. Chunk mode only.

is_lastboolean

True when this is the final chunk of the snapshot. Chunk mode only.

snapshot_versionstring

The snapshot this chunk was read from. Chunk mode only.

total_chunksinteger

Total number of chunks in this snapshot. Chunk mode only.

Example response

{
  "chunk": 2,
  "chunk_size": 1000,
  "instance_scores": [
    {
      "asset_criticality": 3.9,
      "asset_id": "asset-001",
      "contextual_cvss": 7.6,
      "cve_id": "CVE-2022-21903",
      "exploitability": 71,
      "picus_exposure_score": 7.2,
      "security_control_effectiveness": "75.0"
    }
  ],
  "snapshot_version": "0f0c8e1a-9b4c-4d2e-8f1a-2b3c4d5e6f70",
  "total_chunks": 3
}

Changes

  • cb0fa3dcf51fRevision changes
    • info

      added the non-success response with the status

    • info

      added the non-success response with the status