> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/vulnerability-management/bring-your-own-scanner.md).

# Bring Your Own Scanner

Import vulnerability findings from external scanners into Cortex vulnerability management. Use these endpoints to submit asset and CVE data from third-party scanners and to poll the status of async import jobs.

## Submit assets and vulnerabilities from an external scanner

> Imports asset and vulnerability data from a third-party scanner into Cortex vulnerability management.\
> \
> Each request must include at least one asset. Each asset can carry multiple CVE findings. The platform validates all input on receipt — if validation fails, a \`422 Unprocessable Entity\` response is returned with field-level error details.\
> \
> Successful requests are processed asynchronously. The response includes a \`job\_id\` that can be polled using the \[Get BYOS import job status]\(#operation/getByosImportJobStatus) endpoint, plus counts of accepted assets and vulnerabilities.\
> \
> \*\*RBAC permission required:\*\* \`manage\_vulnerabilities\_action\`\
> \
> \*\*Required licenses:\*\* Exposure Management; and either Cortex XSIAM Premium or any Cortex XSIAM product with the Cloud Runtime Security or Cloud Posture Security add-ons\
> \
> Within a single asset, each vulnerability\_id must be unique. If duplicate vulnerability\_id values are submitted for the same asset, the API returns 422 Unprocessable Entity with an error describing the duplicate.\
> \
> \*\*Viewing imported findings:\*\* After successful import, findings appear in the Cortex Cloud vulnerability management console under Vulnerability Findings, filtered by finding\_sources = Third Party Scanner. The number of findings shown may be lower than the vulnerabilities\_count returned by the import response, because the platform deduplicates findings by asset and CVE ID.\
> \
> \*\*Rate limits:\*\*\
> \- Maximum 10 requests per hour to this endpoint.\
> \- Maximum 10 jobs in PROCESSING state in any given hour. Additional submissions are rejected until active jobs complete.

```json
{"openapi":"3.1.0","info":{"title":"Vulnerability Management APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"Bring Your Own Scanner","description":"Import vulnerability findings from external scanners into Cortex vulnerability management. Use these endpoints to submit asset and CVE data from third-party scanners and to poll the status of async import jobs."}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/vulnerability-management/v1/external-scans/assets":{"post":{"summary":"Submit assets and vulnerabilities from an external scanner","description":"Imports asset and vulnerability data from a third-party scanner into Cortex vulnerability management.\n\nEach request must include at least one asset. Each asset can carry multiple CVE findings. The platform validates all input on receipt — if validation fails, a `422 Unprocessable Entity` response is returned with field-level error details.\n\nSuccessful requests are processed asynchronously. The response includes a `job_id` that can be polled using the [Get BYOS import job status](#operation/getByosImportJobStatus) endpoint, plus counts of accepted assets and vulnerabilities.\n\n**RBAC permission required:** `manage_vulnerabilities_action`\n\n**Required licenses:** Exposure Management; and either Cortex XSIAM Premium or any Cortex XSIAM product with the Cloud Runtime Security or Cloud Posture Security add-ons\n\nWithin a single asset, each vulnerability_id must be unique. If duplicate vulnerability_id values are submitted for the same asset, the API returns 422 Unprocessable Entity with an error describing the duplicate.\n\n**Viewing imported findings:** After successful import, findings appear in the Cortex Cloud vulnerability management console under Vulnerability Findings, filtered by finding_sources = Third Party Scanner. The number of findings shown may be lower than the vulnerabilities_count returned by the import response, because the platform deduplicates findings by asset and CVE ID.\n\n**Rate limits:**\n- Maximum 10 requests per hour to this endpoint.\n- Maximum 10 jobs in PROCESSING state in any given hour. Additional submissions are rejected until active jobs complete.","tags":["Bring Your Own Scanner"],"operationId":"importVulnerableAssets","parameters":[{"name":"x-xdr-auth-id","in":"header","required":true,"schema":{"anyOf":[{"type":"integer"},{"type":"string"}],"default":"","title":"X-Xdr-Auth-Id"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","default":"","title":"Authorization"}}],"requestBody":{"description":"Request payload containing scanner metadata and the list of assets with their vulnerability findings.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VulnerableAssetImportRequest"}}}},"responses":{"201":{"description":"Assets accepted for asynchronous processing. The response includes import counts and the `job_id` for status polling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VulnerableAssetImportResponse"}}}},"422":{"description":"Validation Error — one or more request fields failed schema validation. Check the `detail` array for field-level error messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"VulnerableAssetImportRequest":{"type":"object","title":"VulnerableAssetImportRequest","description":"Request body for importing vulnerable assets from an external scanner.","required":["vendor","product","assets"],"properties":{"vendor":{"type":"string","title":"Vendor","description":"Vulnerability scanner vendor. Examples: `TENABLE`, `QUALYS`, `RAPID7_VM`, `RAPID7_CLOUD`."},"product":{"type":"string","title":"Product","description":"Product name associated with the vulnerabilities."},"version":{"type":"string","title":"Version","description":"Product version, used for `(vendor, product, version)` CVE mapping."},"assets":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AssetInfo"},"title":"Assets","description":"List of assets with their vulnerability findings. Must contain at least one asset."}}},"AssetInfo":{"type":"object","title":"AssetInfo","description":"Information about an asset with vulnerabilities.","required":["vulnerabilities","last_seen"],"properties":{"ipv4":{"type":"array","items":{"type":"string","format":"ipv4"},"title":"IPv4","description":"IPv4 addresses used to identify this asset in the source system."},"vulnerabilities":{"type":"array","items":{"$ref":"#/components/schemas/VulnerabilityInfo"},"title":"Vulnerabilities","description":"All vulnerabilities related to this asset."},"origin_asset_id":{"type":"string","title":"Origin Asset ID","description":"Unique ID generated by the source system. Used as a uniqueness constraint for future matching."},"asset_name":{"type":"string","title":"Asset Name","description":"Friendly name of the asset. If omitted, the platform may auto-generate a name from the FQDN, IPv4, or IPv6 address."},"ipv6":{"type":"array","items":{"type":"string","format":"ipv6"},"title":"IPv6","description":"IPv6 addresses used to identify this asset in the source system."},"fqdn":{"type":"array","items":{"type":"string"},"title":"FQDN","description":"FQDNs used to identify this asset in the source system."},"mac_address":{"type":"string","title":"MAC Address","description":"MAC address assigned to the asset in the source system."},"origin_tags":{"type":"array","items":{"type":"string"},"title":"Origin Tags","description":"Tags from the origin system. Stored in the platform tags field to allow ingesting additional asset context. Parsed as key/value pairs separated by colons."},"last_seen":{"type":"integer","title":"Last Seen","description":"Timestamp in milliseconds since epoch time (Unix time). Must be within the last 30 days from the current time. Older or future timestamps are rejected with HTTP 422."},"os_name":{"type":"string","title":"OS Name","description":"Operating system name of the asset."},"product":{"type":"string","title":"Product","description":"Product name installed on the asset."},"vendor":{"type":"string","title":"Vendor","description":"Vendor of the product installed on the asset."},"version":{"type":"string","title":"Version","description":"Version of the product installed on the asset."}}},"VulnerabilityInfo":{"type":"object","title":"VulnerabilityInfo","description":"Information about a vulnerability attached to an asset.","required":["vulnerability_id","last_seen"],"properties":{"vulnerability_id":{"type":"string","title":"Vulnerability ID","description":"CVE ID for the vulnerability. Typically follows the canonical CVE format (for example, `CVE-2024-12345`), but the API does not enforce this format and accepts any non-empty string identifier."},"last_seen":{"type":"integer","title":"Last Seen","description":"Timestamp in milliseconds since epoch time (Unix time). Must be within the last 30 days from the current time. Older or future timestamps are rejected with HTTP 422."},"port":{"type":"integer","title":"Port","description":"Port used for remote scanning. Must be a positive integer less than 65,535.","minimum":1,"maximum":65534},"protocol":{"type":"string","enum":["TCP","UDP"],"title":"Protocol","description":"Network protocol used during scanning."},"raw_output":{"type":"string","maxLength":2000,"title":"Raw Output","description":"Additional output from the scanner. Maximum 2,000 characters."},"confidence":{"type":"string","enum":["Potential","Confirmed"],"title":"Confidence","description":"Confidence level of the vulnerability finding."},"description":{"type":"string","title":"Description","description":"Description of the vulnerability."},"evidence":{"type":"string","title":"Evidence","description":"Evidence supporting the vulnerability finding."},"scan_name":{"type":"string","title":"Scan Name","description":"Name of the scan that detected this vulnerability."},"cve_id":{"type":"array","items":{"type":"string"},"title":"CVE ID","description":"List of CVE IDs associated with this vulnerability."}}},"VulnerableAssetImportResponse":{"type":"object","title":"VulnerableAssetImportResponse","description":"Response for a successful vulnerable asset import. Returns counts and the async job identifier needed to poll for completion.","required":["assets_count","vulnerabilities_count","job_id","job_status"],"properties":{"assets_count":{"type":"integer","title":"Assets Count","description":"Total number of assets accepted in the import request."},"vulnerabilities_count":{"type":"integer","title":"Vulnerabilities Count","description":"Total number of vulnerabilities accepted across all assets in the import request."},"job_id":{"type":"string","format":"uuid","title":"Job ID","description":"Unique identifier for the async import job. Use this value with the Get BYOS Import Job Status endpoint to poll for completion."},"job_status":{"description":"Initial status of the import job. Will be `INITIATED` immediately after a successful POST.","allOf":[{"$ref":"#/components/schemas/ImportJobStatus"}]}}},"ImportJobStatus":{"type":"string","title":"ImportJobStatus","description":"Possible status values for a BYOS import job.","enum":["INITIATED","PROCESSING","COMPLETED","COMPLETED_WITH_ERRORS","FAILED"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Poll the status of a BYOS import job

> Returns the current status of an asynchronous BYOS import job.\
> \
> After submitting assets via the \[Submit assets and vulnerabilities from an external scanner]\(#operation/importVulnerableAssets) endpoint, use the returned \`job\_id\` to poll this endpoint until the job reaches a terminal state (\`COMPLETED\`, \`FAILED\`, or \`COMPLETED\_WITH\_ERRORS\`).\
> \
> Possible \`job\_status\` values:\
> \- \`INITIATED\` — job received, not yet queued\
> \- \`PROCESSING\` — job is actively being processed\
> \- \`COMPLETED\` — all assets imported successfully\
> \- \`COMPLETED\_WITH\_ERRORS\` — import finished but some assets failed; check \`error\_log\`\
> \- \`FAILED\` — job failed entirely; check \`error\_log\` for details\
> \
> \*\*Response codes:\*\*\
> \- \`200\` — Job status retrieved successfully. The HTTP status reflects only the poll request itself; the \*job's\* outcome is in \`job\_status\` (including the terminal \`FAILED\` and \`COMPLETED\_WITH\_ERRORS\` states).\
> \- \`404\` — \`job\_id\` was not found.\
> \
> \`422 Unprocessable Entity\` is only returned by the upstream \[Submit assets and vulnerabilities from an external scanner]\(#operation/importVulnerableAssets) endpoint when the request payload fails schema validation. A \`422\` therefore means the job was never created; a \`FAILED\` \`job\_status\` returned in a \`200\` response means the job ran but could not complete — see \`error\_log\` for details.\
> \
> \*\*RBAC permission required:\*\* \`manage\_vulnerabilities\_action\`\
> \
> \*\*Required licenses:\*\* Exposure Management; and either Cortex XSIAM Premium or any Cortex XSIAM product with the Cloud Runtime Security or Cloud Posture Security add-ons\
> \
> \*\*SLA timeout:\*\* Jobs in PROCESSING state have a 24-hour SLA. After 24 hours, any job still in PROCESSING is guaranteed to transition to COMPLETED\_WITH\_ERRORS, which is a terminal state.\
> \
> \*\*Rate limits:\*\* Maximum 10 requests per minute.

```json
{"openapi":"3.1.0","info":{"title":"Vulnerability Management APIs","version":"Cortex XSIAM 3.5"},"tags":[{"name":"Bring Your Own Scanner","description":"Import vulnerability findings from external scanners into Cortex vulnerability management. Use these endpoints to submit asset and CVE data from third-party scanners and to poll the status of async import jobs."}],"servers":[{"url":"https://api-yourfqdn","description":""}],"paths":{"/public_api/vulnerability-management/v1/external-scans/assets/jobs/{job_id}":{"get":{"summary":"Poll the status of a BYOS import job","description":"Returns the current status of an asynchronous BYOS import job.\n\nAfter submitting assets via the [Submit assets and vulnerabilities from an external scanner](#operation/importVulnerableAssets) endpoint, use the returned `job_id` to poll this endpoint until the job reaches a terminal state (`COMPLETED`, `FAILED`, or `COMPLETED_WITH_ERRORS`).\n\nPossible `job_status` values:\n- `INITIATED` — job received, not yet queued\n- `PROCESSING` — job is actively being processed\n- `COMPLETED` — all assets imported successfully\n- `COMPLETED_WITH_ERRORS` — import finished but some assets failed; check `error_log`\n- `FAILED` — job failed entirely; check `error_log` for details\n\n**Response codes:**\n- `200` — Job status retrieved successfully. The HTTP status reflects only the poll request itself; the *job's* outcome is in `job_status` (including the terminal `FAILED` and `COMPLETED_WITH_ERRORS` states).\n- `404` — `job_id` was not found.\n\n`422 Unprocessable Entity` is only returned by the upstream [Submit assets and vulnerabilities from an external scanner](#operation/importVulnerableAssets) endpoint when the request payload fails schema validation. A `422` therefore means the job was never created; a `FAILED` `job_status` returned in a `200` response means the job ran but could not complete — see `error_log` for details.\n\n**RBAC permission required:** `manage_vulnerabilities_action`\n\n**Required licenses:** Exposure Management; and either Cortex XSIAM Premium or any Cortex XSIAM product with the Cloud Runtime Security or Cloud Posture Security add-ons\n\n**SLA timeout:** Jobs in PROCESSING state have a 24-hour SLA. After 24 hours, any job still in PROCESSING is guaranteed to transition to COMPLETED_WITH_ERRORS, which is a terminal state.\n\n**Rate limits:** Maximum 10 requests per minute.","tags":["Bring Your Own Scanner"],"operationId":"getByosImportJobStatus","parameters":[{"name":"x-xdr-auth-id","in":"header","required":true,"schema":{"anyOf":[{"type":"integer"},{"type":"string"}],"default":"","title":"X-Xdr-Auth-Id"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","default":"","title":"Authorization"}},{"name":"job_id","in":"path","required":true,"description":"The unique identifier of the BYOS import job, returned by the [Submit assets and vulnerabilities from an external scanner](#operation/importVulnerableAssets) endpoint.","schema":{"type":"string","title":"Job ID"}}],"responses":{"200":{"description":"Job status retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportJobResponse"}}}},"404":{"description":"Job not found — the specified `job_id` does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"422":{"description":"Validation Error — the `job_id` path parameter failed schema validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ImportJobResponse":{"type":"object","title":"ImportJobResponse","description":"Status and metadata for a BYOS import job.","required":["job_id","created_timestamp","job_status"],"properties":{"job_id":{"type":"string","title":"Job ID","description":"Unique job ID. Use this value with the Get BYOS Import Job Status endpoint to poll for completion."},"created_timestamp":{"type":"string","format":"date-time","title":"Created Timestamp","description":"ISO 8601 timestamp of when the job was received."},"job_status":{"description":"Current status of the import job.","allOf":[{"$ref":"#/components/schemas/ImportJobStatus"}]},"last_updated":{"type":"string","format":"date-time","title":"Last Updated","description":"ISO 8601 timestamp of when the job was last updated."},"error_log":{"type":["string","null"],"title":"Error Log","description":"Error details if the job failed or completed with errors. May be `null` when there is no error."}}},"ImportJobStatus":{"type":"string","title":"ImportJobStatus","description":"Possible status values for a BYOS import job.","enum":["INITIATED","PROCESSING","COMPLETED","COMPLETED_WITH_ERRORS","FAILED"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xsiam-api/vulnerability-management/bring-your-own-scanner.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.