Reporting¶
Generate ready-made audit reports from your scans and inventory — vulnerability summaries, host summaries, vulnerability lists, scan histories, and per-host vulnerability listings. All report endpoints support pagination (limit / offset or size / skip), filtering (filter object), and sorting (sort).
Open interactive specs
Overview¶
Use POST /api/v3/reports/vulnsreport/ (API v3) to fetch server-generated reports. Each request includes a reporttype field that instructs the server which report to build. Responses are JSON arrays or objects depending on the report.
Auth: X-Api-Key header required.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
reporttype |
body | string | yes | Requested report type. Examples: vulnssummary, ipssummary, vulnslist, scanlist, hostvulns. |
filter |
body | object | no | Filtering object, e.g. {"OS":"Centos","OSVersion":"7"} or {"agentip":"10.2.2.2"}. |
sort |
body | string | v | Sort expression, e.g. -published (minus = descending). |
skip/offset |
body | integer | no | Pagination offset (zero-based). |
size / limit |
body | integer | no | Number of records to return. |
Tip
Use filter to narrow by OS, host IP, scan id, dates or any fields that appear in the example responses.
Vulnerability summary report¶
Aggregated list of vulnerabilities with counts and scores - good for dashboards and prioritized remediation.
Usage:
Query:
POST /api/v3/reports/vulnsreport/
Query example:
curl -XPOST https://vulners.com/api/v3/reports/vulnsreport/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"reporttype": "vulnssummary"
}'
report = vulners_api.vulnssummary_report()
[
{
"vulnID": "CVE-2019-8457",
"title": "CVE-2019-8457",
"family": "cve",
"severity": 4,
"severityText": "high",
"count": 2,
"score": 7.5
},
{
"vulnID": "CVE-2022-32774",
"title": "CVE-2022-32774",
"family": "cve",
"severity": 2,
"severityText": "low",
"count": 2,
"score": 0.0
}, ...
]
Host summary report¶
Per-host risk summary: CVSS-based score, vulnerability counts by severity, OS info and totals.
Usage:
Query:
POST /api/v3/reports/vulnsreport/
Query example:
curl -XPOST https://vulners.com/api/v3/reports/vulnsreport/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"reporttype": "ipssummary",
"skip": 2,
"size": 4
}'
report = vulners_api.ipsummary_report(limit=2, offset=4)
[
{
"agentid": "30TS<...>LKLE",
"agentip": "10.1.1.1",
"agentfqdn": "somehost1",
"osname": "windows",
"osversion": "10.0.19045",
"score": 16.4,
"total": 10,
"vulnerabilities": {
"low": 9,
"high": 1
}
},
{
"agentid": "MVEB<...>3HCC",
"agentip": "10.2.2.2",
"agentfqdn": "somehost2",
"osname": "debian",
"osversion": "10",
"score": 12.3,
"total": 5,
"vulnerabilities": {
"low": 5
}
}]
List of detected vulnerabilities¶
Return a flat list of discovered vulnerabilities; supports host-based filtering.
Usage:
Query:
POST /api/v3/reports/vulnsreport/
Query example:
curl -XPOST https://vulners.com/api/v3/reports/vulnsreport/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"reporttype":"vulnslist",
"filter":{"agentip": "10.2.2.2"}
}'
report = vulners_api.report.vulns_list(filter={"agentip": "10.2.2.2"})
[{
"vulnID": "DEBIAN:DSA-5235-1:A2B24",
"title": "[SECURITY] [DSA 5235-1] bind9 security update",
"family": "debian",
"severity": 2,
"severityText": "low",
"agentip": "10.2.2.2",
"agentfqdn": "somehost2",
"cumulativeFix": "sudo apt-get --assume-yes install --only-upgrade bind9-host",
"scanid": "Q13T<...>IQU9"
},
{
"vulnID": "DEBIAN:DSA-5105-1:A867B",
"title": "[SECURITY] [DSA 5105-1] bind9 security update",
"family": "debian",
"severity": 2,
"severityText": "low",
"agentip": "10.2.2.2",
"agentfqdn": "somehost2",
"cumulativeFix": "sudo apt-get --assume-yes install --only-upgrade bind9-host",
"scanid": "Q13T<...>IQU9"
},]
List of performed scans¶
Retrieve scan metadata (when scans were performed, OS, host, scan id, aggregated CVSS).
Usage:
Query:
POST /api/v3/reports/vulnsreport/
Query example:
curl -XPOST https://vulners.com/api/v3/reports/vulnsreport/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"reporttype":"scanlist",
"sort":"-modified"
}'
report = vulners_api.report.scan_list(sort='-modified')
[
{
"ipaddress": "10.3.3.3",
"OS": "redhat",
"fqdn": "somehost3",
"OSVersion": "8.7",
"modified": "2023-02-01T10:44:21",
"id": "F8YD<...>IHFC",
"cvss": {
"score": 9.0,
"vector": "AV:N/AC:L/Au:S/C:C/I:C/A:C"
}
},
{
"ipaddress": "10.1.1.1",
"OS": "windows",
"fqdn": "somehost1",
"OSVersion": "10.0.19045",
"modified": "2023-01-13T10:06:49",
"id": "QJN1<...>TAIH",
"cvss": {
"score": 0.0,
"vector": "NONE"
}
}
]
List of vulnerabilities on a host¶
Host-centric report that returns an array of vulnerability IDs, summary fix command, and host metadata.
Usage:
Query:
POST /api/v3/reports/vulnsreport/
Query example:
curl -XPOST https://vulners.com/api/v3/reports/vulnsreport/ -H "X-Api-Key: YOUR_API_KEY" -H 'Content-Type: application/json' -d '{
"reporttype":"hostvulns"
}'
report5 = vulners_api.report.host_vulns()
[
{
"agentip": "10.2.2.2",
"agentfqdn": "somehost2",
"osname": "debian",
"osversion": "10",
"cumulativeFix": "sudo apt-get --assume-yes install --only-upgrade bind9-host",
"vulnerabilities": [
"DEBIAN:DSA-5105-1:A867B",
"DEBIAN:DSA-5235-1:A2B24",
"DEBIAN:DLA-2955-1:40374",
"DEBIAN:DLA-3138-1:2F5A9",
"DEBIAN:DLA-2955-2:CDB18"
],
"published": "2023-02-23T10:55:41"
},
{
"agentip": "10.1.1.1",
"agentfqdn": "somehost1",
"osname": "windows",
"osversion": "10.0.19045",
"cumulativeFix": "",
"vulnerabilities": [
"CVE-2022-32774",
"OSV:CVE-2021-20227",
"CVE-2022-37332",
"CVE-2019-16168",
"CVE-2022-42919",
"CVE-2016-6153",
"CVE-2019-8457",
"CVE-2022-35737",
"CVE-2022-40129",
"CVE-2022-38097"
],
"published": "2022-12-30T13:08:59"
}
]