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"}| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Example
- pairs mode
curl -X POST 'https://api.picussecurity.com/v1/exposures/instances/scores' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"filters": {
"host_exposure_pairs": [
{
"exposure_id": "CVE-2022-21903",
"hostname": "asset-001"
}
]
}
}'{
"instance_scores": [
{
"cve_id": "CVE-2016-2183",
"asset_id": "asset-001",
"asset_criticality": 3.9,
"contextual_cvss": 4.9,
"exploitability": 99.9,
"security_control_effectiveness": "70.0",
"picus_exposure_score": 5.9
}
]
}- chunk mode - first chunk
curl -X POST 'https://api.picussecurity.com/v1/exposures/instances/scores' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"chunk": 1
}'{
"snapshot_version": "b2444179-b8bb-4abc-adbb-e7cbb33755cb",
"chunk": 1,
"total_chunks": 5,
"chunk_size": 1000,
"is_last": false,
"instance_scores": [
{
"cve_id": "CVE-2016-2183",
"asset_id": "asset-001",
"asset_criticality": 3.9,
"contextual_cvss": 4.9,
"exploitability": 99.9,
"security_control_effectiveness": "70.0",
"picus_exposure_score": 5.9
},
{
"cve_id": "CVE-2016-2183",
"asset_id": "asset-002",
"asset_criticality": 3.2,
"contextual_cvss": 5.0,
"exploitability": 69.0,
"security_control_effectiveness": "No Result",
"picus_exposure_score": 5.6
},
...
]
}- chunk mode - later chunks
curl -X POST 'https://api.picussecurity.com/v1/exposures/instances/scores' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"chunk": 2,
"snapshot_version": "b2444179-b8bb-4abc-adbb-e7cbb33755cb"
}'{
"snapshot_version": "b2444179-b8bb-4abc-adbb-e7cbb33755cb",
"chunk": 2,
"total_chunks": 5,
"chunk_size": 1000,
"is_last": false,
"instance_scores": [
{
"cve_id": "CVE-2016-2111",
"asset_id": "asset-111",
"asset_criticality": 3.2,
"contextual_cvss": 4.4,
"exploitability": 76.2,
"security_control_effectiveness": "75.0",
"picus_exposure_score": 6.1
},
{
"cve_id": "CVE-2016-2112",
"asset_id": "asset-111",
"asset_criticality": 6.5,
"contextual_cvss": 7.1,
"exploitability": 54.0,
"security_control_effectiveness": "45.0",
"picus_exposure_score": 8.2
},
...
]
}