From fa1451aae4a101cd680c81bf92693c0eb94a2292 Mon Sep 17 00:00:00 2001 From: MisterMcHoward Date: Fri, 14 Apr 2023 18:15:31 -0700 Subject: [PATCH 1/8] Added GET Pre-Defined EDL New API --- .../threat-vault/ThreatPrevention.yaml | 251 +++++++++++++++++- 1 file changed, 246 insertions(+), 5 deletions(-) diff --git a/openapi-specs/threat-vault/ThreatPrevention.yaml b/openapi-specs/threat-vault/ThreatPrevention.yaml index 575e78a27..5ff284795 100644 --- a/openapi-specs/threat-vault/ThreatPrevention.yaml +++ b/openapi-specs/threat-vault/ThreatPrevention.yaml @@ -109,6 +109,47 @@ components: type: string description: "The release time when the threat signature was last released with WildFire package." example: "2022-06-14T16:56:15Z" + EdlDataList: + type: object + properties: + version: + type: string + description: "The version of the release." + example: "4030" + name: + type: string + description: "The name of the predefined EDL." + example: "panw-known-ip-list" + ipaddr: + type: string + description: "The IP address." + example: "45.154.14.235" + GetEdlSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 1 + data: + type: array + description: "The data of the response." + items: + $ref: '#/components/schemas/EdlDataList' + message: + type: string + description: "Generic response message." + example: "Successful" + Pagination: type: object properties: @@ -403,11 +444,22 @@ paths: schema: enum: [content] type: string - - description: - "The release version (ex. 8446) or content version (ex. 8446-6886)\ - \ of the release notes.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n\ - \ 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=8446-6886'\n\ - ```\n" + - description: " + The release version (ex. 8446) or content version (ex. 8446-6886) of the release notes. + + \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=8446-6886'\n\ + ```\n + + Use latest for latest release version: + + \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=latest'\n\ + ```\n + " + + + + + in: query name: version required: true @@ -1133,6 +1185,195 @@ paths: - X-API-KEY: [] summary: Request Threat Signature Release History tags: [Threat Prevention] + + + /edl: + get: + operationId: edl + description: | + A GET request to retrieve the predefined external dynamic lists by name and version. + parameters: + - name: name + in: query + required: false + schema: + type: string + enum: + - panw-known-ip-list + - panw-highrisk-ip-list + - panw-torexit-ip-list + - panw-bulletproof-ip-list + description: | + Provides the EDL by the name. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest' + ``` + + - name: ipaddr + in: query + required: false + schema: + type: string + description: | + Provides the EDL of the IP address. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=185.130.5.207' + ``` + + - name: version + in: query + required: false + schema: + type: string + description: | + Provides the EDL by the specific AV package version. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-highrisk-ip-list&version=4024' + ``` + + Use "latest" for latest release version: + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=185.130.5.207&version=latest' + ``` + + - name: listformat + in: query + required: false + schema: + type: string + enum: + - array + description: | + Optional field to provide more convenient way to ingest the EDL. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&listformat=array' + ``` + + - name: limit + in: query + required: false + schema: + type: string + description: | + Optional parameter. The maximum number of results to return in each page. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&limit=5' + ``` + + - name: offset + in: query + required: false + schema: + type: string + description: | + Optional parameter. The starting position of the query in relation to the complete set of the unpaginated results. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-torexit-ip-list&version=latest&limit=5&offset=5' + ``` + responses: + "200": + description: Request succeeded + content: + application/json: + schema: + type: object + properties: + data: + type: object + items: + $ref: "#/components/schemas/GetEdlSuccessResponse" + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Pre-Defined EDL List Content + tags: [Threat Prevention] + + servers: - { url: "https://api.threatvault.paloaltonetworks.com/service/v1" } tags: From 5d466a949ffed905e1d9cb9bb0966c66cbdbb993 Mon Sep 17 00:00:00 2001 From: MisterMcHoward Date: Tue, 18 Apr 2023 19:11:04 -0700 Subject: [PATCH 2/8] Added examples and additional content --- products/cdss/docs/release-notes/changelog.md | 3 +- products/cdss/sidebars.js | 4 + .../examples/get-predefined-edl-content.mdx | 107 ++++++++++++++++++ .../threat-vault-response-fields.mdx | 17 +++ 4 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 products/threat-vault/docs/examples/get-predefined-edl-content.mdx diff --git a/products/cdss/docs/release-notes/changelog.md b/products/cdss/docs/release-notes/changelog.md index f24694292..b2a619ce5 100644 --- a/products/cdss/docs/release-notes/changelog.md +++ b/products/cdss/docs/release-notes/changelog.md @@ -13,4 +13,5 @@ keywords: | Date | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | | August 08, 2022 | First public release of the Threat Vault API for Threat Prevention and Advanced Threat Prevention subscription holders. | -| August 23, 2022 | First public `BETA` release of the DNS Security API for DNS Security subscription holders. | +| August 23, 2022 | First public `BETA` release of the DNS Security API for DNS Security subscription holders. | +| April 23, 2023 | The Threat Vault API now supports retrieval of [predefined EDL](https://docs.paloaltonetworks.com/pan-os/11-0/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/built-in-edls.html) ([external dynamic list](https://docs.paloaltonetworks.com/pan-os/11-0/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/external-dynamic-list.html)) content. | diff --git a/products/cdss/sidebars.js b/products/cdss/sidebars.js index 98e9d4e5a..cc9886cb6 100644 --- a/products/cdss/sidebars.js +++ b/products/cdss/sidebars.js @@ -82,6 +82,10 @@ module.exports = { type: "doc", id: "threat-vault/docs/examples/get-atp-report", }, + { + type: "doc", + id: "threat-vault/docs/examples/get-predefined-EDL-content", + }, { type: "doc", id: "threat-vault/docs/examples/get-atp-report-pcap", diff --git a/products/threat-vault/docs/examples/get-predefined-edl-content.mdx b/products/threat-vault/docs/examples/get-predefined-edl-content.mdx new file mode 100644 index 000000000..5c838af66 --- /dev/null +++ b/products/threat-vault/docs/examples/get-predefined-edl-content.mdx @@ -0,0 +1,107 @@ +--- +id: get-predefined-edl-content +title: Request Predefined EDL Content +description: Threat Vault API example showing how to request the content contained within a predefined EDL (external dynamic list). +hide_title: false +hide_table_of_contents: false +keywords: + - security subscription +--- + +The API Reference information for retrieving the contents contained within a Palo Alto Networks predefined EDL can be found [here](/threat-vault/api/edl/). + +## Overview + +The Threat Vault API can be used to request the EDL (external dynamic list) based on the specified name, IP address, and version. Consider the following examples: + +Keep a few things in mind when formatting your API query: + +1. All the query strings in Get requests must be a URL-Encoded parameter string. If you use a space in the URL-Encoded request, you must include either a plus sign (+) or %20 to replace the space. +2. You can specify the content type of the request body and response by specifying the Content-Type header. Some responses generate an HTTP response in addition to a JSON object. +3. Do not embed API keys in code or application source tree files. This can inadvertently expose the API key. Instead, consider storing the API key in environmental variables or files that are excluded from your application source tree files. + +## Example 1: Request information about the predefined EDL by referencing the name and release version. + +This example specifies the predefined EDL `Palo Alto Networks High-Risk IP Addresses` based on the AV release version of 4024. + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-highrisk-ip-list&version=4024' +``` + +A successful API call returns, within the contents section, status="success" along with a JSON object containing the predefined EDL IP address entries for version 4024. + +```{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 3476, + "data": [ + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "45.90.59.131" + }, + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "49.12.212.231" + }, + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "51.210.176.76" + }, + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "62.210.13.20" + }, + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "137.184.152.41" + }, + { + "version": "4024", + "name": "panw-highrisk-ip-list", + "ipaddr": "194.32.107.243" + } + ], + "message": "Successful" +} +``` + +## Example 2: Request the latest information about the specifed predefined EDL in an array format: + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&listformat=array' +``` + +A successful API call returns, within the contents section, status="success" along with a JSON object containing the predefined EDL contents. + +```{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 4701, + "data": { + "version": "4030", + "name": "panw-known-ip-list", + "ipaddr": [ + "45.154.14.235", + "103.30.246.121", + "103.75.201.4", + "103.107.104.19", + "176.56.128.118" + ] + }, + "message": "Successful" +} +``` + + + diff --git a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx index 861ee0287..1a524d782 100644 --- a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx +++ b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx @@ -114,6 +114,23 @@ The following JSON response fields are found in [Request Threat Signature Releas | `data.release_time` | The time when the package was released externally. | | `data.message` | Generic response message. | +## Predefined EDL Content Response Fields + +The following JSON response fields are found in [Request Predefined EDL Content](/threat-vault/api/threat-prevention#operation/edl): + +| Field | Description | +| ------------------- | -------------------------------------------------- | +| `success` | The response status. | +| `link` | The pagination information of the results. | +| `link.previous` | The URL of the previous page with results. | +| `link.next` | The URL of the next page with results. | +| `count` | The total number of entries found. | +| `data` | The data of the response. | +| `data.version` | The version of the release. | +| `data.name` | The predefined EDL name. | +| `data.ipaddr` | The IP address. | +| `message` | Generic response message. | + ## Advanced Threat Prevention Report Response Fields The following JSON response fields are found in [Request ATP Report in Batch Mode](/threat-vault/api/advanced-threat-prevention#operation/postatpreportsbatchmode): From b4eb6539bcef564506fcf6d414f152ce175e601a Mon Sep 17 00:00:00 2001 From: MisterMcHoward Date: Tue, 18 Apr 2023 19:37:48 -0700 Subject: [PATCH 3/8] Bug fix --- products/cdss/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/products/cdss/sidebars.js b/products/cdss/sidebars.js index cc9886cb6..f8145c504 100644 --- a/products/cdss/sidebars.js +++ b/products/cdss/sidebars.js @@ -84,7 +84,7 @@ module.exports = { }, { type: "doc", - id: "threat-vault/docs/examples/get-predefined-EDL-content", + id: "threat-vault/docs/examples/get-predefined-edl-content", }, { type: "doc", From 8d73dc2c5df9df2a745103394c63e4bee3e07cb3 Mon Sep 17 00:00:00 2001 From: MisterMcHoward Date: Tue, 25 Apr 2023 11:46:53 -0700 Subject: [PATCH 4/8] Review updates --- openapi-specs/threat-vault/ThreatPrevention.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi-specs/threat-vault/ThreatPrevention.yaml b/openapi-specs/threat-vault/ThreatPrevention.yaml index 5ff284795..60f64434d 100644 --- a/openapi-specs/threat-vault/ThreatPrevention.yaml +++ b/openapi-specs/threat-vault/ThreatPrevention.yaml @@ -123,7 +123,7 @@ components: ipaddr: type: string description: "The IP address." - example: "45.154.14.235" + example: "192.0.2.0" GetEdlSuccessResponse: type: object properties: @@ -1218,12 +1218,12 @@ paths: schema: type: string description: | - Provides the EDL of the IP address. + Provides the EDLs containing the IP address. --- ``` curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=185.130.5.207' + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0' ``` - name: version @@ -1245,7 +1245,7 @@ paths: --- ``` curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=185.130.5.207&version=latest' + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0&version=latest' ``` - name: listformat @@ -1370,7 +1370,7 @@ paths: description: Server related error response security: - X-API-KEY: [] - summary: Request Pre-Defined EDL List Content + summary: Request Predefined EDL Content tags: [Threat Prevention] From bd39bbe18b95322b88c3c02b551bcfee34a7b9dd Mon Sep 17 00:00:00 2001 From: MisterMcHoward <92402975+MisterMcHoward@users.noreply.github.com> Date: Tue, 14 Nov 2023 11:46:17 -0800 Subject: [PATCH 5/8] Add files via upload Added ip-feed and ip-feed-batch --- .../AdvancedThreatPrevention.yaml | 1750 ++++----- .../threat-vault/ThreatPrevention.yaml | 3162 ++++++++++------- 2 files changed, 2691 insertions(+), 2221 deletions(-) diff --git a/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml b/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml index b4e23f7a8..a16c23ac7 100644 --- a/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml +++ b/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml @@ -1,842 +1,910 @@ -components: - securitySchemes: - X-API-KEY: - description: API key to query https://api.threatvault.paloaltonetworks.com/service/v1 - in: header - name: X-API-KEY - type: apiKey - schemas: - GetThreatSuccessResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - link: - type: array - description: "The pagination information of the results." - items: - $ref: "#/components/schemas/Pagination" - count: - type: integer - description: "The total number of entries found." - example: 6 - data: - type: array - description: "The data of the response." - items: - $ref: "#/components/schemas/ThreatDataList" - message: - type: string - description: "Generic response message." - example: "Successful" - GetThreatBatchSuccessResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - link: - type: array - description: "The pagination information of the results." - items: - $ref: "#/components/schemas/Pagination" - count: - type: integer - description: "The total number of entries found." - example: 1 - data: - type: array - description: | - The data of the response. - items: - $ref: "#/components/schemas/GetThreatBatchList" - message: - type: string - description: "Generic response message." - example: "Successful" - GetThreatHistorySuccessResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - link: - type: array - description: "The pagination information of the results." - items: - $ref: "#/components/schemas/Pagination" - count: - type: integer - description: "The total number of entries found." - example: 3 - data: - type: array - description: | - The data of the response. - items: - $ref: "#/components/schemas/ThreatHistoryDataList" - message: - type: string - description: "Generic response message." - example: "Successful" - GetReleaseNotesSuccessResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - link: - type: array - description: "The pagination information of the results." - items: - $ref: "#/components/schemas/Pagination" - count: - type: integer - description: "The total number of entries found." - example: 2 - data: - type: array - description: "The data of the response." - items: - $ref: "#/components/schemas/ReleaseNotesDataList" - message: - type: string - description: "Generic response message." - example: "Successful" - Pagination: - type: object - properties: - next: - type: string - description: "The URL of previous page with results." - previous: - type: string - description: "The URL of next page with results." - ThreatDataList: - type: object - properties: - fileformat: - type: array - description: "List of File-Format signatures." - spyware: - type: array - description: "List of Anti-Spyware signatures." - vulnerability: - type: array - description: "List of Vulnerability Protection signatures." - items: - type: object - properties: - id: - type: string - description: "The unique id of the signature." - example: "30135" - name: - type: string - description: "The name of the signature." - example: "Name of the threat" - description: - type: string - description: "The description of the signature." - example: "Description of the threat ..." - category: - type: string - description: "The threat category of the signature." - example: "code-execution" - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "11.1.0" - severity: - type: string - description: "The severity of the threat." - example: "high" - default_action: - type: string - description: "The default action when the signature is triggered." - example: "alert" - cve: - type: array - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: ["CVE-2007-1204", "CVE-2021-35393"] - vendor: - type: array - description: "The vulnerability identifier issued by vendor on advisories." - example: ["MS07-019"] - reference: - type: array - description: "The public reference of the threat." - example: ["Url1", "Url2"] - status: - type: string - description: "The status of the signature." - example: "released" - details: - type: object - description: "Any additional details of the signature." - example: {} - ori_release_version: - type: string - description: "The original release version of the signature." - example: "8451" - latest_release_version: - type: string - description: "The latest release version of the signature." - example: "8451" - ori_release_time: - type: string - description: "The original release time of the signature." - example: "2021-08-31 01:25:04" - latest_release_time: - type: string - description: "The latest release time of the signature." - example: "2021-08-31 01:25:04" - ThreatHistoryDataList: - type: object - properties: - version: - type: string - description: "The version of the release." - example: "4020-4531" - build_time: - type: string - description: "The time when the package was built." - example: "2022-03-12T22:23:38Z" - release_time: - type: string - description: "The time when the package was released externally." - example: "2022-03-13T03:02:24Z" - ReleaseNotesDataList: - type: object - properties: - release_version: - type: integer - description: "The release version of the update." - example: 8446 - content_version: - type: string - description: "The content version of the update." - example: "8446-6886" - type: - type: string - description: "The type of the release notes." - example: "content" - json_data: - type: array - description: "The release notes information." - items: - type: object - properties: - notes: - type: array - description: "General notices and reminders." - applications: - type: array - description: "The APP-ID updates in the release notes." - decoders: - type: array - description: "The decoder updates in the release notes." - example: ["improved ..."] - data_correlation: - type: array - description: "The Data Correlation Object updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - modified: - type: array - description: "List of modified entries." - deleted: - type: array - description: "List of deleted entries." - file_type: - type: array - description: "The File-Format updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - modified: - type: array - description: "List of modified entries." - disabled: - type: array - description: "List of disabled entries." - spyware: - type: array - description: "The Anti-Spyware updates in the release notes." - vulnerability: - type: array - description: "The Vulnerability Protection updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - items: - type: object - properties: - severity: - type: string - description: "The severity of the threat." - example: "high" - pan_id: - type: integer - description: "The unique id of the signature." - example: 30515 - attack_name: - type: string - description: "The name of the signature." - example: "File Loading" - cve: - type: string - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: "CVE-2007-1204" - vendor: - type: string - description: "The vulnerability identifier issued by vendor on advisories." - example: "MS07-019" - action: - type: string - description: "The default action when the signature is triggered." - example: "reset-both" - change_data: - type: string - description: "Additional information about the updated signature." - example: "updated action to ...." - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "9.1.0" - modified: - type: array - items: - type: object - properties: - severity: - type: string - description: "The severity of the threat." - example: "high" - pan_id: - type: integer - description: "The unique id of the signature." - example: 30077 - attack_name: - type: string - description: "The name of the signature." - example: "Vulnerability" - cve: - type: string - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: "CVE-2006-3942, CVE-2006-1314" - vendor: - type: string - description: "The vulnerability identifier issued by vendor on advisories." - example: "MS06-063" - action: - type: string - description: "The default action when the signature is triggered." - example: "reset-server" - change_data: - type: string - description: "Additional information about the updated signature." - example: "updated action to ...." - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "11.1.0" - disabled: - type: array - description: "List of disabled entries." - release_time: - type: string - description: "The time of the release." - example: "2021-08-27T03:10:03Z" - GetThreatBatchList: - type: object - properties: - antivirus: - type: array - description: "List of Antivirus signatures." - items: - type: object - properties: - id: - type: string - description: "The unique threat signature id." - example: "280392504" - name: - type: string - description: "The threat signature name." - example: "trojan/Win32 DLL.razy.slo" - severity: - type: string - description: | - The threat signature severity. - *List: low, informative, medium, high or critical* - example: "medium" - type: - type: string - description: "A numerical value describing the type of the threat signature." - example: "0" - subtype: - type: string - description: "The threat signature subtype." - example: "virus" - action: - type: string - description: "The threat signature default action. This is generally empty for Antivirus signatures." - example: "" - description: - type: string - description: "The threat signature description." - example: "This signature detected trojan/Win32 DLL.razy.slo" - create_time: - type: string - description: "The threat signature creation time." - example: "2019-06-19T17:06:12Z" - status: - type: string - description: | - The threat signature creation time. - *List: active or inactive* - example: "active" - related_sha256_hashes: - type: array - description: "The list of related sha256 hashes for the threat signature." - items: - type: string - example: - [ - "47e3da7e179b755a1ccc8fe8fc506a2fb15baff2c124b15cf2f5e29038f3d1ac", - "5cd3e058f6049a31a42c292ebb091a1b5ea4bd9c7bc6fed5ac8a33c5fc89924a", - ] - release: - type: object - description: "The threat signature release information." - properties: - antivirus: - type: object - description: "The threat signature information related to Antivirus package updates." - properties: - first_release_version: - type: string - description: "The release version when the threat signature was first released with Antivirus package." - example: "3017" - first_release_time: - type: string - description: "The release time when the threat signature was first released with Antivirus package." - example: "2018-03-02T11:06:51Z" - last_release_version: - type: string - description: "The release version when the threat signature was last released with Antivirus package." - example: "4115" - last_release_time: - type: string - description: "The release time when the threat signature was last released with Antivirus package." - example: "2022-06-14T13:35:54Z" - wildfire: - type: object - description: "The threat signature information related to WildFire package updates." - properties: - first_release_version: - type: string - description: "The release version when the threat signature was first released with WildFire package." - example: "359199" - first_release_time: - type: string - description: "The release time when the threat signature was first released with WildFire package." - example: "2019-06-19T17:06:35Z" - last_release_version: - type: string - description: "The release version when the threat signature was last released with WildFire package." - example: "672412" - last_release_time: - type: string - description: "The release time when the threat signature was last released with WildFire package." - example: "2022-06-14T16:56:15Z" - GetFailResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: false - message: - type: string - description: "Generic response message." - example: "Error message." - ATPReportList: - type: object - properties: - report_id: - type: string - description: "The id of the ATP report." - example: "c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50" - err_msg: - type: string - description: "Any error message related to the report." - example: "Error" - panos_info: - type: object - description: "All related PAN-OS information." - properties: - fw_hostname: - type: string - description: "Firewall Hostname." - example: fw-1 - fw_addr_v4: - type: string - description: "Firewall MP interface IPv4." - example: 10.0.0.0 - fw_addr_v6: - type: string - description: "Firewall MP interface IPv6. (Can be empty)" - example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 - fw_app_version: - type: string - description: "Firewall Content package version." - example: 8527-12345 - fw_sw_version: - type: string - description: "Firewall PANOS version." - example: 10.2.1 - fw_serial: - type: string - description: "Firewall Serial Number." - example: "000000000000001" - fw_model: - type: string - description: "Firewall model." - example: "PA-VM" - session_info: - type: object - description: "All related session information." - properties: - session_id: - type: string - description: "Session ID." - example: "123456" - session_timestamp: - type: string - description: "Session timestamp." - example: 2022-04-11T10:00:00.740261097-07:00 - flow_info: - type: object - properties: - saddr: - type: string - description: "Session source IP address." - example: 1.1.1.1 - daddr: - type: string - description: "Session destination IP address." - example: 1.1.1.2 - sport: - type: string - description: "Session source IP port." - example: "49234" - dport: - type: string - description: "Session destination IP port." - example: "80" - data_type: - type: string - enum: - - http - - ssl - - unknown-tcp - - unknown-udp - description: "The payload type." - example: "http" - transaction_data: - type: object - description: "The list of transactions of the session. One session may have one or many transactions." - properties: - transaction_id: - type: string - description: "The transaction id." - example: "0" - payload_sha256: - type: string - description: "The SHA256 hash value of the payload." - example: a15e20ddc3a0850b64cdc87a23230b51466f9879345435973ce360e80e1f670e - reports: - type: array - description: "The list of detection service reports." - items: - type: object - properties: - ds_name: - type: string - description: "The detection service name." - example: mlc2-http-ids - ds_report: - type: object - description: "The list of detection service reports." - properties: - payload_info: - type: object - description: "Optional payload information." - example: {} - malware_families: - type: object - description: "The list of malware families." - properties: - malware_family_type: - type: string - description: "The name/type of the malware family." - example: "" - confidence: - type: string - description: "The confidence value." - example: "0.85" - example: {} - status: - type: string - description: "A flag to indicate the report is ready or not." - example: ok -info: - version: "1.0" - contact: {} - description: " - The Advanced Threat Prevention API endpoints require an active subscription to the Advanced Threat Prevention security service. These endpoints can only be accessed using the API key associated with the account that holds the subscription. Attempting to view an unauthorized report ID will not return any results. - List of Advanced Threat Prevention API endpoints: - 1. Link to [Request Advanced Threat Prevention cloud analysis report](/threat-vault/api/postatpreportsbatchmode) - 2. Link to [Request Advanced Threat Prevention cloud analysis report PCAP](/threat-vault/api/getatppcaps) - " - title: Advanced Threat Prevention - -openapi: 3.0.1 - -paths: - /atp/reports: - post: - description: - "A POST request to retrieve the ATP report by report id in batch - mode. Batch limit is 100 entries. - Get one or more ATP reports. - User must provide **one or more** report IDs in request body. - " - operationId: postatpreportsbatchmode - requestBody: - content: - application/json: - schema: - example: - id: - [ - c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50, - a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50, - ] - properties: - id: - description: - "Provides the ATP report by matching the report id\ - \ of the customer.\n\n---\n```\ncurl -v -X POST -H 'X-API-KEY:\ - \ API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d\ - \ '{\"id\": [\"c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50\"\ - , \"a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50\"\ - ]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports'\n\ - ```\n" - items: { type: string } - type: array - type: object - required: true - responses: - "200": - description: Request succeeded - content: - application/json: - schema: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - data: - type: array - description: | - The data of the response. - items: - $ref: "#/components/schemas/ATPReportList" - message: - type: string - description: "Generic response message." - example: "Successful" - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Advanced Threat Prevention Report in Batch Mode - tags: [Advanced Threat Prevention] - /atp/reports/pcaps: - get: - description: - "A GET request to retrieve the ATP report sample (packet capture) - by report id. - " - operationId: getatppcaps - parameters: - - description: - "Retrieve the ATP report sample (packet capture) by report id.\n\ - \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports/pcaps?id=c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50'\n\ - ```" - in: query - name: id - required: true - schema: { type: string } - responses: - "200": - content: - application/octet-stream: - schema: { format: binary, type: string } - description: Request succeeded - headers: - X-Day-RateLimit-Limit: - description: The maximum number of requests that the user is permitted to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: The number of requests remaining in the current rate limit window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: The epoch timestamp at which the current rate limit window (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: The maximum number of requests that the user is permitted to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: The number of requests remaining in the current rate limit window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: The epoch timestamp at which the current rate limit window (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Certificate related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Advanced Threat Prevention Report PCAP - tags: [Advanced Threat Prevention] -servers: - - { url: "https://api.threatvault.paloaltonetworks.com/service/v1" } -tags: +components: + securitySchemes: + X-API-KEY: + description: API key to query https://api.threatvault.paloaltonetworks.com/service/v1 + in: header + name: X-API-KEY + type: apiKey + schemas: + GetThreatSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 6 + data: + type: array + description: "The data of the response." + items: + $ref: "#/components/schemas/ThreatDataList" + message: + type: string + description: "Generic response message." + example: "Successful" + GetThreatBatchSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 1 + data: + type: array + description: | + The data of the response. + items: + $ref: "#/components/schemas/GetThreatBatchList" + message: + type: string + description: "Generic response message." + example: "Successful" + GetThreatHistorySuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 3 + data: + type: array + description: | + The data of the response. + items: + $ref: "#/components/schemas/ThreatHistoryDataList" + message: + type: string + description: "Generic response message." + example: "Successful" + GetReleaseNotesSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 2 + data: + type: array + description: "The data of the response." + items: + $ref: "#/components/schemas/ReleaseNotesDataList" + message: + type: string + description: "Generic response message." + example: "Successful" + Pagination: + type: object + properties: + next: + type: string + description: "The URL of previous page with results." + previous: + type: string + description: "The URL of next page with results." + ThreatDataList: + type: object + properties: + fileformat: + type: array + description: "List of File-Format signatures." + spyware: + type: array + description: "List of Anti-Spyware signatures." + vulnerability: + type: array + description: "List of Vulnerability Protection signatures." + items: + type: object + properties: + id: + type: string + description: "The unique id of the signature." + example: "30135" + name: + type: string + description: "The name of the signature." + example: "Name of the threat" + description: + type: string + description: "The description of the signature." + example: "Description of the threat ..." + category: + type: string + description: "The threat category of the signature." + example: "code-execution" + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "11.1.0" + severity: + type: string + description: "The severity of the threat." + example: "high" + default_action: + type: string + description: "The default action when the signature is triggered." + example: "alert" + cve: + type: array + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: ["CVE-2007-1204", "CVE-2021-35393"] + vendor: + type: array + description: "The vulnerability identifier issued by vendor on advisories." + example: ["MS07-019"] + reference: + type: array + description: "The public reference of the threat." + example: ["Url1", "Url2"] + status: + type: string + description: "The status of the signature." + example: "released" + details: + type: object + description: "Any additional details of the signature." + example: {} + ori_release_version: + type: string + description: "The original release version of the signature." + example: "8451" + latest_release_version: + type: string + description: "The latest release version of the signature." + example: "8451" + ori_release_time: + type: string + description: "The original release time of the signature." + example: "2021-08-31 01:25:04" + latest_release_time: + type: string + description: "The latest release time of the signature." + example: "2021-08-31 01:25:04" + ThreatHistoryDataList: + type: object + properties: + version: + type: string + description: "The version of the release." + example: "4020-4531" + build_time: + type: string + description: "The time when the package was built." + example: "2022-03-12T22:23:38Z" + release_time: + type: string + description: "The time when the package was released externally." + example: "2022-03-13T03:02:24Z" + ReleaseNotesDataList: + type: object + properties: + release_version: + type: integer + description: "The release version of the update." + example: 8446 + content_version: + type: string + description: "The content version of the update." + example: "8446-6886" + type: + type: string + description: "The type of the release notes." + example: "content" + json_data: + type: array + description: "The release notes information." + items: + type: object + properties: + notes: + type: array + description: "General notices and reminders." + applications: + type: array + description: "The APP-ID updates in the release notes." + decoders: + type: array + description: "The decoder updates in the release notes." + example: ["improved ..."] + data_correlation: + type: array + description: "The Data Correlation Object updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + modified: + type: array + description: "List of modified entries." + deleted: + type: array + description: "List of deleted entries." + file_type: + type: array + description: "The File-Format updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + modified: + type: array + description: "List of modified entries." + disabled: + type: array + description: "List of disabled entries." + spyware: + type: array + description: "The Anti-Spyware updates in the release notes." + vulnerability: + type: array + description: "The Vulnerability Protection updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + items: + type: object + properties: + severity: + type: string + description: "The severity of the threat." + example: "high" + pan_id: + type: integer + description: "The unique id of the signature." + example: 30515 + attack_name: + type: string + description: "The name of the signature." + example: "File Loading" + cve: + type: string + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: "CVE-2007-1204" + vendor: + type: string + description: "The vulnerability identifier issued by vendor on advisories." + example: "MS07-019" + action: + type: string + description: "The default action when the signature is triggered." + example: "reset-both" + change_data: + type: string + description: "Additional information about the updated signature." + example: "updated action to ...." + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "9.1.0" + modified: + type: array + items: + type: object + properties: + severity: + type: string + description: "The severity of the threat." + example: "high" + pan_id: + type: integer + description: "The unique id of the signature." + example: 30077 + attack_name: + type: string + description: "The name of the signature." + example: "Vulnerability" + cve: + type: string + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: "CVE-2006-3942, CVE-2006-1314" + vendor: + type: string + description: "The vulnerability identifier issued by vendor on advisories." + example: "MS06-063" + action: + type: string + description: "The default action when the signature is triggered." + example: "reset-server" + change_data: + type: string + description: "Additional information about the updated signature." + example: "updated action to ...." + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "11.1.0" + disabled: + type: array + description: "List of disabled entries." + release_time: + type: string + description: "The time of the release." + example: "2021-08-27T03:10:03Z" + GetThreatBatchList: + type: object + properties: + antivirus: + type: array + description: "List of Antivirus signatures." + items: + type: object + properties: + id: + type: string + description: "The unique threat signature id." + example: "280392504" + name: + type: string + description: "The threat signature name." + example: "trojan/Win32 DLL.razy.slo" + severity: + type: string + description: | + The threat signature severity. + *List: low, informative, medium, high or critical* + example: "medium" + type: + type: string + description: "A numerical value describing the type of the threat signature." + example: "0" + subtype: + type: string + description: "The threat signature subtype." + example: "virus" + action: + type: string + description: "The threat signature default action. This is generally empty for Antivirus signatures." + example: "" + description: + type: string + description: "The threat signature description." + example: "This signature detected trojan/Win32 DLL.razy.slo" + create_time: + type: string + description: "The threat signature creation time." + example: "2019-06-19T17:06:12Z" + status: + type: string + description: | + The threat signature creation time. + *List: active or inactive* + example: "active" + related_sha256_hashes: + type: array + description: "The list of related sha256 hashes for the threat signature." + items: + type: string + example: + [ + "47e3da7e179b755a1ccc8fe8fc506a2fb15baff2c124b15cf2f5e29038f3d1ac", + "5cd3e058f6049a31a42c292ebb091a1b5ea4bd9c7bc6fed5ac8a33c5fc89924a", + ] + release: + type: object + description: "The threat signature release information." + properties: + antivirus: + type: object + description: "The threat signature information related to Antivirus package updates." + properties: + first_release_version: + type: string + description: "The release version when the threat signature was first released with Antivirus package." + example: "3017" + first_release_time: + type: string + description: "The release time when the threat signature was first released with Antivirus package." + example: "2018-03-02T11:06:51Z" + last_release_version: + type: string + description: "The release version when the threat signature was last released with Antivirus package." + example: "4115" + last_release_time: + type: string + description: "The release time when the threat signature was last released with Antivirus package." + example: "2022-06-14T13:35:54Z" + wildfire: + type: object + description: "The threat signature information related to WildFire package updates." + properties: + first_release_version: + type: string + description: "The release version when the threat signature was first released with WildFire package." + example: "359199" + first_release_time: + type: string + description: "The release time when the threat signature was first released with WildFire package." + example: "2019-06-19T17:06:35Z" + last_release_version: + type: string + description: "The release version when the threat signature was last released with WildFire package." + example: "672412" + last_release_time: + type: string + description: "The release time when the threat signature was last released with WildFire package." + example: "2022-06-14T16:56:15Z" + GetFailResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: false + message: + type: string + description: "Generic response message." + example: "Error message." + ATPReportList: + type: object + properties: + report_id: + type: string + description: "The id of the ATP report." + example: "c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50" + err_msg: + type: string + description: "Any error message related to the report." + example: "Error" + panos_info: + type: object + description: "All related PAN-OS information." + properties: + fw_hostname: + type: string + description: "Firewall Hostname." + example: fw-1 + fw_addr_v4: + type: string + description: "Firewall MP interface IPv4." + example: 10.0.0.0 + fw_addr_v6: + type: string + description: "Firewall MP interface IPv6. (Can be empty)" + example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334 + fw_app_version: + type: string + description: "Firewall Content package version." + example: 8527-12345 + fw_sw_version: + type: string + description: "Firewall PANOS version." + example: 10.2.1 + fw_serial: + type: string + description: "Firewall Serial Number." + example: "000000000000001" + fw_model: + type: string + description: "Firewall model." + example: "PA-VM" + session_info: + type: object + description: "All related session information." + properties: + session_id: + type: string + description: "Session ID." + example: "123456" + session_timestamp: + type: string + description: "Session timestamp." + example: 2022-04-11T10:00:00.740261097-07:00 + flow_info: + type: object + properties: + saddr: + type: string + description: "Session source IP address." + example: 1.1.1.1 + daddr: + type: string + description: "Session destination IP address." + example: 1.1.1.2 + sport: + type: string + description: "Session source IP port." + example: "49234" + dport: + type: string + description: "Session destination IP port." + example: "80" + data_type: + type: string + enum: + - http + - ssl + - unknown-tcp + - unknown-udp + description: "The payload type." + example: "http" + transaction_data: + type: object + description: "The list of transactions of the session. One session may have one or many transactions." + properties: + transaction_id: + type: string + description: "The transaction id." + example: "0" + payload_sha256: + type: string + description: "The SHA256 hash value of the payload." + example: a15e20ddc3a0850b64cdc87a23230b51466f9879345435973ce360e80e1f670e + detection_results: + type: object + description: "The detection results information." + properties: + detection_service: + type: string + description: "The detection service." + example: "Empire C2" + details: + type: object + description: "Details information." + properties: + attack_analysis: + type: object + description: "The attack analysis information." + properties: + Attack Description: + type: string + description: "The attack description." + example: "Your system is under an early Empire C2 attack stage. The malware in your system is trying to set up the connection channel with a C2 server 192.168.10.4." + Attack Details: + type: string + description: "The attack details." + example: "It is at the Empire C2 staging phase. The potential Empire C2 server is 192.168.10.4, and it is trying to install payloads in your system for future attacks." + Attack Evidences: + type: string + description: "The attack evidence." + example: "The session key is encoded with netbiosu." + payload_info: + type: object + description: "The request payload information." + properties: + Connection: + type: string + description: "A general header controls whether the network connection stays open after the current transaction finishes." + example: "Keep-Alive" + Cookie: + type: string + description: "A header that contains stored HTTP cookies associated with the server." + example: "session=/YMjhqiUqqLLm7Lt8PXbLiMtD3Q%3D" + Host: + type: string + description: "A header that specifies the host and port number of the server to which the request is being sent." + example: "192.168.10.4:1813" + Method: + type: string + description: "A header that defines the desired action to be performed for a given resource." + example: "GET" + URI: + type: string + description: "A header that defines the resource." + example: "/daeedrxc/" + User-Agent: + type: string + description: "A header that identifies the requesting user agent." + example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9" + Version: + type: string + description: "A header that specifies the HTTP version." + example: "HTTP/1.1" + verdict: + type: integer + description: "The verdict value." + example: 1 + + + + + reports: + type: array + description: "The list of detection service reports." + items: + type: object + properties: + ds_name: + type: string + description: "The detection service name." + example: mlc2-http-ids + ds_report: + type: object + description: "The list of detection service reports." + properties: + payload_info: + type: object + description: "Optional payload information." + example: {} + malware_families: + type: object + description: "The list of malware families." + properties: + malware_family_type: + type: string + description: "The name/type of the malware family." + example: "" + confidence: + type: string + description: "The confidence value." + example: "0.85" + example: {} + status: + type: string + description: "A flag to indicate the report is ready or not." + example: ok +info: + version: "1.0" + contact: {} + description: " + The Advanced Threat Prevention API endpoints require an active subscription to the Advanced Threat Prevention security service. These endpoints can only be accessed using the API key associated with the account that holds the subscription. Attempting to view an unauthorized report ID will not return any results. + List of Advanced Threat Prevention API endpoints: + 1. Link to [Request Advanced Threat Prevention cloud analysis report](/threat-vault/api/postatpreportsbatchmode) + 2. Link to [Request Advanced Threat Prevention cloud analysis report PCAP](/threat-vault/api/getatppcaps) + " + title: Advanced Threat Prevention + +openapi: 3.0.1 + +paths: + /atp/reports: + post: + description: + "A POST request to retrieve the ATP report by report id in batch + mode. Batch limit is 100 entries. + Get one or more ATP reports. + User must provide **one or more** report IDs in request body. + " + operationId: postatpreportsbatchmode + requestBody: + content: + application/json: + schema: + example: + id: + [ + c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50, + a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50, + ] + properties: + id: + description: + "Provides the ATP report by matching the report id\ + \ of the customer.\n\n---\n```\ncurl -v -X POST -H 'X-API-KEY:\ + \ API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d\ + \ '{\"id\": [\"c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50\"\ + , \"a23b5d46d6ac77e70376080517991187a07ac008bfc799f08795d59c57e23a50\"\ + ]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports'\n\ + ```\n" + items: { type: string } + type: array + type: object + required: true + responses: + "200": + description: Request succeeded + content: + application/json: + schema: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + data: + type: array + description: | + The data of the response. + items: + $ref: "#/components/schemas/ATPReportList" + message: + type: string + description: "Generic response message." + example: "Successful" + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Advanced Threat Prevention Report in Batch Mode + tags: [Advanced Threat Prevention] + /atp/reports/pcaps: + get: + description: + "A GET request to retrieve the ATP report sample (packet capture) + by report id. + " + operationId: getatppcaps + parameters: + - description: + "Retrieve the ATP report sample (packet capture) by report id.\n\ + \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/atp/reports/pcaps?id=c25b5d86d8ac77e10376000517491157a07ac008bfc799f08795d59c57e23a50'\n\ + ```" + in: query + name: id + required: true + schema: { type: string } + responses: + "200": + content: + application/octet-stream: + schema: { format: binary, type: string } + description: Request succeeded + headers: + X-Day-RateLimit-Limit: + description: The maximum number of requests that the user is permitted to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: The number of requests remaining in the current rate limit window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: The epoch timestamp at which the current rate limit window (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: The maximum number of requests that the user is permitted to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: The number of requests remaining in the current rate limit window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: The epoch timestamp at which the current rate limit window (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Certificate related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Advanced Threat Prevention Report PCAP + tags: [Advanced Threat Prevention] +servers: + - { url: "https://api.threatvault.paloaltonetworks.com/service/v1" } +tags: - { name: Advanced Threat Prevention } \ No newline at end of file diff --git a/openapi-specs/threat-vault/ThreatPrevention.yaml b/openapi-specs/threat-vault/ThreatPrevention.yaml index 60f64434d..df3ca4ced 100644 --- a/openapi-specs/threat-vault/ThreatPrevention.yaml +++ b/openapi-specs/threat-vault/ThreatPrevention.yaml @@ -1,1380 +1,1782 @@ -components: - securitySchemes: - X-API-KEY: - description: API key to query https://api.threatvault.paloaltonetworks.com/service/v1 - in: header - name: X-API-KEY - type: apiKey - schemas: - GetThreatBatchList: - type: object - properties: - antivirus: - type: array - description: "List of Antivirus signatures." - items: - type: object - properties: - id: - type: string - description: "The unique threat signature id." - example: "280392504" - name: - type: string - description: "The threat signature name." - example: "trojan/Win32 DLL.razy.slo" - severity: - type: string - description: | - The threat signature severity. - *List: low, informative, medium, high or critical* - example: "medium" - type: - type: string - description: "A numerical value describing the type of the threat signature." - example: "0" - subtype: - type: string - description: "The threat signature subtype." - example: "virus" - action: - type: string - description: "The threat signature default action. This is generally empty for Antivirus signatures." - example: "" - description: - type: string - description: "The threat signature description." - example: "This signature detected trojan/Win32 DLL.razy.slo" - create_time: - type: string - description: "The threat signature creation time." - example: "2019-06-19T17:06:12Z" - status: - type: string - description: | - The threat signature creation time. - *List: active or inactive* - example: "active" - related_sha256_hashes: - type: array - description: "The list of related sha256 hashes for the threat signature." - items: - type: string - example: - [ - "47e3da7e179b755a1ccc8fe8fc506a2fb15baff2c124b15cf2f5e29038f3d1ac", - "5cd3e058f6049a31a42c292ebb091a1b5ea4bd9c7bc6fed5ac8a33c5fc89924a", - ] - release: - type: object - description: "The threat signature release information." - properties: - antivirus: - type: object - description: "The threat signature information related to Antivirus package updates." - properties: - first_release_version: - type: string - description: "The release version when the threat signature was first released with Antivirus package." - example: "3017" - first_release_time: - type: string - description: "The release time when the threat signature was first released with Antivirus package." - example: "2018-03-02T11:06:51Z" - last_release_version: - type: string - description: "The release version when the threat signature was last released with Antivirus package." - example: "4115" - last_release_time: - type: string - description: "The release time when the threat signature was last released with Antivirus package." - example: "2022-06-14T13:35:54Z" - wildfire: - type: object - description: "The threat signature information related to WildFire package updates." - properties: - first_release_version: - type: string - description: "The release version when the threat signature was first released with WildFire package." - example: "359199" - first_release_time: - type: string - description: "The release time when the threat signature was first released with WildFire package." - example: "2019-06-19T17:06:35Z" - last_release_version: - type: string - description: "The release version when the threat signature was last released with WildFire package." - example: "672412" - last_release_time: - type: string - description: "The release time when the threat signature was last released with WildFire package." - example: "2022-06-14T16:56:15Z" - EdlDataList: - type: object - properties: - version: - type: string - description: "The version of the release." - example: "4030" - name: - type: string - description: "The name of the predefined EDL." - example: "panw-known-ip-list" - ipaddr: - type: string - description: "The IP address." - example: "192.0.2.0" - GetEdlSuccessResponse: - type: object - properties: - success: - type: boolean - description: "The response status." - example: true - link: - type: array - description: "The pagination information of the results." - items: - $ref: "#/components/schemas/Pagination" - count: - type: integer - description: "The total number of entries found." - example: 1 - data: - type: array - description: "The data of the response." - items: - $ref: '#/components/schemas/EdlDataList' - message: - type: string - description: "Generic response message." - example: "Successful" - - Pagination: - type: object - properties: - next: - type: string - description: "The URL of previous page with results." - previous: - type: string - description: "The URL of next page with results." - ReleaseNotesDataList: - type: object - properties: - release_version: - type: integer - description: "The release version of the update." - example: 8446 - content_version: - type: string - description: "The content version of the update." - example: "8446-6886" - type: - type: string - description: "The type of the release notes." - example: "content" - json_data: - type: array - description: "The release notes information." - items: - type: object - properties: - notes: - type: array - description: "General notices and reminders." - applications: - type: array - description: "The APP-ID updates in the release notes." - decoders: - type: array - description: "The decoder updates in the release notes." - example: ["improved ..."] - data_correlation: - type: array - description: "The Data Correlation Object updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - modified: - type: array - description: "List of modified entries." - deleted: - type: array - description: "List of deleted entries." - file_type: - type: array - description: "The File-Format updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - modified: - type: array - description: "List of modified entries." - disabled: - type: array - description: "List of disabled entries." - spyware: - type: array - description: "The Anti-Spyware updates in the release notes." - vulnerability: - type: array - description: "The Vulnerability Protection updates in the release notes." - items: - type: object - properties: - new: - type: array - description: "List of new entries." - items: - type: object - properties: - severity: - type: string - description: "The severity of the threat." - example: "high" - pan_id: - type: integer - description: "The unique id of the signature." - example: 30515 - attack_name: - type: string - description: "The name of the signature." - example: "File Loading" - cve: - type: string - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: "" - vendor: - type: string - description: "The vulnerability identifier issued by vendor on advisories." - example: "" - action: - type: string - description: "The default action when the signature is triggered." - example: "reset-both" - change_data: - type: string - description: "Additional information about the updated signature." - example: "updated action to ...." - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "9.1.0" - modified: - type: array - items: - type: object - properties: - severity: - type: string - description: "The severity of the threat." - example: "high" - pan_id: - type: integer - description: "The unique id of the signature." - example: 30077 - attack_name: - type: string - description: "The name of the signature." - example: "Vulnerability" - cve: - type: string - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: "CVE-2006-3942, CVE-2006-1314" - vendor: - type: string - description: "The vulnerability identifier issued by vendor on advisories." - example: "MS06-063" - action: - type: string - description: "The default action when the signature is triggered." - example: "reset-server" - change_data: - type: string - description: "Additional information about the updated signature." - example: "updated action to ...." - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "" - disabled: - type: array - description: "List of disabled entries." - ThreatDataList: - type: object - properties: - fileformat: - type: array - description: "List of File-Format signatures." - spyware: - type: array - description: "List of Anti-Spyware signatures." - vulnerability: - type: array - description: "List of Vulnerability Protection signatures." - items: - type: object - properties: - id: - type: string - description: "The unique id of the signature." - example: "30135" - name: - type: string - description: "The name of the signature." - example: "Name of the threat" - description: - type: string - description: "The description of the signature." - example: "Description of the threat ..." - category: - type: string - description: "The threat category of the signature." - example: "code-execution" - min_version: - type: string - description: "The PAN-OS minimum version." - example: "8.1.0" - max_version: - type: string - description: "The PAN-OS maximum version." - example: "11.1.0" - severity: - type: string - description: "The severity of the threat." - example: "high" - default_action: - type: string - description: "The default action when the signature is triggered." - example: "alert" - cve: - type: array - description: "The CVE (Common Vulnerabilities and Exposures) of the threat." - example: ["CVE-2007-1204", "CVE-2021-35393"] - vendor: - type: array - description: "The vulnerability identifier issued by vendor on advisories." - example: ["MS07-019"] - reference: - type: array - description: "The public reference of the threat." - example: ["Url1", "Url2"] - status: - type: string - description: "The status of the signature." - example: "released" - details: - type: object - description: "Any additional details of the signature." - example: {} - ori_release_version: - type: string - description: "The original release version of the signature." - example: "8451" - latest_release_version: - type: string - description: "The latest release version of the signature." - example: "8451" - ori_release_time: - type: string - description: "The original release time of the signature." - example: "2021-08-31 01:25:04" - latest_release_time: - type: string - description: "The latest release time of the signature." - example: "2021-08-31 01:25:04" - ThreatHistoryDataList: - type: object - properties: - version: - type: string - description: "The version of the release." - example: "4020-4531" - build_time: - type: string - description: "The time when the package was built." - example: "2022-03-12T22:23:38Z" - release_time: - type: string - description: "The time when the package was released externally." - example: "2022-03-13T03:02:24Z" -info: - contact: {} - description: " - The Threat Prevention API endpoints are available to customers with an active Threat Prevention or Advanced Threat Prevention subscription. - List of Threat Prevention API endpoints: - 1. Link to [Request Content Release Notes](/threat-vault/api/releasenotes) - 2. Link to [Request Threat Metadata](/threat-vault/api/threats) - 3. Link to [Request Threat Signature Metadata in Batch Mode](/threat-vault/api/threatsbatch) - 4. Link to [Request Threat Signature Release History](/threat-vault/api/threatshistory) - " - title: Threat Prevention - version: "1.0" -openapi: 3.0.1 -paths: - /release-notes: - get: - description: - "A GET request to retrieve the release notes information by type\ - \ and version.\n\n- Notes:\n - Any Content release notes before Version 8000\ - \ is best effort.\n" - operationId: releasenotes - parameters: - - description: - "The type of the release notes (ex. Content).\n>\u26A0\uFE0F\ - \ ***Use without quotes***\n" - in: query - name: type - required: true - schema: - enum: [content] - type: string - - description: " - The release version (ex. 8446) or content version (ex. 8446-6886) of the release notes. - - \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=8446-6886'\n\ - ```\n - - Use latest for latest release version: - - \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=latest'\n\ - ```\n - " - - - - - - in: query - name: version - required: true - schema: { type: string } - responses: - "200": - content: - application/json: - schema: - properties: - count: - { - description: The total number of entries found., - example: 2, - type: integer, - } - data: - description: The data of the response. - items: { $ref: "#/components/schemas/ReleaseNotesDataList" } - type: array - link: - description: The pagination information of the results. - items: { $ref: "#/components/schemas/Pagination" } - type: array - message: - { - description: Generic response message., - example: Successful, - type: string, - } - success: - { - description: The response status., - example: true, - type: boolean, - } - type: object - description: Request succeeded - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Content Release Notes - tags: [Threat Prevention] - /threats: - get: - description: - "A GET request to retrieve threat metadata. The nature of the query is determined by the query parameter that you provide on the call to this API. - \n- Notes: \n - Optionally, each query parameter can be used together\ - \ with the \"type\" query parameter to filter out the results.\n - Any Antivirus /\ - \ WildFire release summary information before **February 2020** is best-effort\ - \ since the information is not available.\n" - operationId: threats - parameters: - - description: "Query a specific Threat signature by signature ID. - " - in: query - name: id - schema: { type: string } - - description: - "Provides the threat signatures metadata by exact match of the\ - \ signature names.\n\n*Note: IPS threat signatures also support partial\ - \ match.*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?name=Microsoft+PE+File'\n\ - ```\n" - in: query - name: name - schema: { type: string } - - description: - "Provides the threat signatures metadata by exact or partial\ - \ match of the CVE tied to the signatures.\n\n*Valid partial CVE format:\ - \ CVE-YYYY*\n\n*Valid exact CVE format: CVE-YYYY-NNNN (NNNN can be 4 or\ - \ more digits)*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?cve=CVE-2020-1234'\n\ - ```\nor \n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?cve=CVE-2021'\n\ - ```\n" - in: query - name: cve - schema: { type: string } - - - description: - "Provides the threat signature metadata by matching the vendor ID tied to the signatures.\ - \n\n*This parameter is only supported for IPS threat signature\ - \ requests.*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?vendor=MS16-095'\n\ - ```\n" - in: query - name: vendor - schema: { type: string } - - - description: - "Used together with toReleaseDate field. Provides the IPS threat\ - \ signatures metadata by the release dates range.\n\n*Only supported for\ - \ IPS threat signatures: fileformat, spyware, vulnerability*\n\n---\n```\n\ - curl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8440&toReleaseVersion=8446'\n\ - ```\n" - in: query - name: fromReleaseDate - schema: { type: string } - - description: - "The right boundary of date range query, must use with `fromReleaseDate`. - Example can be found in **fromReleaseDate** section - " - in: query - name: toReleaseDate - schema: { type: string } - - description: - "Used together with toReleaseVersion field. Provides the IPS\ - \ threat signatures metadata by the release versions range.\n\n*Only supported\ - \ for IPS threat signatures: fileformat, spyware, vulnerability*\n\n---\n\ - ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8440&toReleaseVersion=8446'\n\ - ```\n" - in: query - name: fromReleaseVersion - schema: { type: string } - - description: - "The right boundary of version range query, must use with `fromReleaseVersion`. - Example can be found in **toReleaseVersion** section - " - in: query - name: toReleaseVersion - schema: { type: string } - - description: - "Provides the IPS threat signatures metadata by the release date.\n\ - \n*Only supported for IPS threat signatures: fileformat, spyware, vulnerability*\n\ - \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?releaseDate=2021-08-17'\n\ - ```\n" - in: query - name: releaseDate - schema: { type: string } - - description: - "Provides the IPS threat signatures metadata by the release version.\n\ - \n*Only supported for IPS threat signatures: fileformat, spyware, vulnerability*\n\ - \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?releaseVersion=8446'\n\ - ```\n" - in: query - name: releaseVersion - schema: { type: string } - - description: - "Provides the threat signature metadata based on the threat type.\ - \ Use together with the other fields to filter out the results.\n>\u26A0\ - \uFE0F ***Use without quotes***\n\n- Options:\n - antivirus (Provides Antivirus\ - \ signatures metadata)\n - dns (Provides DNS signatures metadata)\n -\ - \ fileformat (Provides all IPS File-Format signature metadata)\n - ips\ - \ (Provides all IPS signature metadata)\n - rtdns (Provides Real-Time DNS\ - \ Detection entries metadata)\n - spyware (Provides all IPS Anti-Spyware\ - \ signature metadata)\n - spywarec2 (Provides Spyware C2 signatures metadata)\n\ - \ - vulnerability (Provides all IPS Vulnerability Protection signature\ - \ metadata)\n \n---\nGet all IPS signatures:\n``` \ncurl -v -H 'X-API-KEY:\ - \ API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips'\n\ - ```\n*Note: This use-case is only supported for IPS threat signatures: fileformat,\ - \ spyware, vulnerability*\n\n---\nGet all File-Format signatures that were\ - \ recently updated between Content Version 8590 and Content Version 8594:\n\ - ``` \ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8590&toReleaseVersion=8594&type=fileformat'\n\ - ```\n" - in: query - name: type - schema: - enum: - [ - ips, - fileformat, - spyware, - vulnerability, - antivirus, - dns, - rtdns, - spywarec2, - ] - type: string - - description: - "Provides the file information and threat signatures that match\ - \ the hash of the sample.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\ - \n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?sha256=7879722cd37b1c5b2703ea5a1a92a036a96f4a1fc6272b92c197b3a4b17267cc'\n\ - ```\n" - in: query - name: sha256 - schema: { type: string } - - description: - "Provides the file information and threat signatures that match\ - \ the hash of the sample.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\ - \n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?md5=ca066f965dfbc5392871d3fa281236cf'\n\ - ```\n" - in: query - name: md5 - schema: { type: string } - - - description: - "The maximum number of results to return in each page.\n\n---\n\ - ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips&limit=1000'\n\ - ```\n" - in: query - name: limit - required: false - schema: { type: string } - - description: - "The starting position of the query in relation to the complete\ - \ set of the unpaginated results.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips&limit=1000&offset=1000'\n\ - ```\n" - in: query - name: offset - required: false - schema: { type: string } - - responses: - "200": - content: - application/json: - schema: - properties: - count: - { - description: The total number of entries found., - example: 6, - type: integer, - } - data: - description: The data of the response. - items: { $ref: "#/components/schemas/ThreatDataList" } - type: array - link: - description: The pagination information of the results. - items: { $ref: "#/components/schemas/Pagination" } - type: array - message: - { - description: Generic response message., - example: Successful, - type: string, - } - success: - { - description: The response status., - example: true, - type: boolean, - } - type: object - description: Request succeeded - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Threat Metadata - tags: [Threat Prevention] - post: - description: - "A POST request to retrieve the threats signature metadata by id,\ - \ name or sample hash (sha256 or md5) in batch mode. Batch limit is 100 entries.\n\ - \n- Notes: \n - Optionally, each query parameter can be used together\ - \ with the \"type\" query parameter to filter out the results.\n - Any Antivirus /\ - \ WildFire release summary information before **February 2020** is best-effort\ - \ since the information is not available.\n" - operationId: threatsbatch - requestBody: - content: - application/json: - schema: - properties: - id: - description: - "Provides the threat signatures metadata by exact match\ - \ of the signature ids.\n\n---\n```\ncurl -v -X POST -H 'X-API-KEY:\ - \ API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d\ - \ '{\"id\": [\"280392504\"]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ - ```\n" - items: { type: string } - type: array - md5: - description: - "Provides the file information and threat signatures\ - \ that match the hash of the sample.\n\n---\n```\ncurl -v -X POST\ - \ -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ - \ \\\n -d '{\"md5\": [\"ca066f965dfbc5392871d3fa281236cf\"]}'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ - ```\n" - items: { type: string } - type: array - name: - description: - "Provides the threat signatures metadata by exact match\ - \ of the signature names.\n \n---\n```\ncurl -v -X POST -H\ - \ 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ - \ \\\n -d '{\"name\": [\"Microsoft PE File\"]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ - ```\n" - items: { type: string } - type: array - sha256: - description: - "Provides the file information and threat signatures\ - \ that match the hash of the sample.\n\n---\n```\ncurl -v -X POST\ - \ -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ - \ \\\n -d '{\"sha256\": [\"7879722cd37b1c5b2703ea5a1a92a036a96f4a1fc6272b92c197b3a4b17267cc\"\ - ]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ - ```\n" - items: { type: string } - type: array - type: - description: - "Provides the threat signature metadata based on the\ - \ threat type. Use together with the other fields to filter out\ - \ the results.\n>\u26A0\uFE0F ***Use without quotes***\n\n- Options:\n\ - \ - antivirus (Provides Antivirus signatures metadata)\n - dns\ - \ (Provides DNS signatures metadata)\n - fileformat (Provides\ - \ all IPS File-Format signature metadata)\n - ips (Provides all\ - \ IPS signature metadata)\n - rtdns (Provides Real-Time DNS Detection\ - \ entries metadata)\n - spyware (Provides all IPS Anti-Spyware\ - \ signature metadata)\n - spywarec2 (Provides Spyware C2 signatures\ - \ metadata)\n - vulnerability (Provides all IPS Vulnerability\ - \ Protection signature metadata)\n \n---\n```\ncurl -v\ - \ -X POST -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ - \ \\\n -d '{\"id\": [\"280392504\"], \"type\":\"antivirus\"}'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ - ```\n" - enum: - [ - ips, - fileformat, - spyware, - vulnerability, - antivirus, - dns, - rtdns, - spywarec2, - ] - type: string - type: object - required: true - responses: - "200": - content: - application/json: - schema: - properties: - count: - { - description: The total number of entries found., - example: 1, - type: integer, - } - data: - description: "The data of the response. - " - items: { $ref: "#/components/schemas/GetThreatBatchList" } - type: array - link: - description: The pagination information of the results. - items: { $ref: "#/components/schemas/Pagination" } - type: array - message: - { - description: Generic response message., - example: Successful, - type: string, - } - success: - { - description: The response status., - example: true, - type: boolean, - } - type: object - description: Request succeeded - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Threat Signature Metadata in Batch Mode - tags: [Threat Prevention] - /threats/history: - get: - description: - "A GET request to retrieve the threats signature release history\ - \ by id and package type.\n\n- Notes:\n - The retention policy of **Antivirus**\ - \ release history data is for **1 year** (only the last 1 year of release\ - \ history data will be available).\n - The retention policy of **WildFire**\ - \ release history data is for **30 days** (only the last 30 days of release\ - \ history data will be available).\n - Any Antivirus / WildFire release history\ - \ information before **Version 4140** is best-effort since the information\ - \ is not available.\n - The Antivirus / WildFire version field in the responses\ - \ before **Version 4140** is in the format of **XXXX** (ex. \"version\": \"\ - 4140\") and after that the format is **XXXX-YYYY** (ex. \"version\": \"4141-4637\"\ - ).\n - The Antivirus / WildFire release time before **Version 4140** is the\ - \ package start building time as the actual release time is not available.\n" - operationId: threatshistory - parameters: - - description: - "Provides the threat signature metadata based on the threat type.\n\ - >\u26A0\uFE0F ***Use without quotes***\n\n- Options:\n - antivirus (Provides\ - \ Antivirus signature release information)\n - wildfire (Provides WildFire\ - \ signature release information)\n" - in: query - name: type - required: true - schema: - enum: [antivirus, wildfire] - type: string - - description: - "Provides the threat signature release history by matching the\ - \ signature id in the releases.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus'\n\ - ```\n" - in: query - name: id - required: true - schema: { type: string } - - description: - "The maximum number of results to return in each page.\n\n---\n\ - ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&limit=3'\n\ - ```\n" - in: query - name: limit - required: false - schema: { type: string } - - description: - "The starting position of the query in relation to the complete\ - \ set of the unpaginated results.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&limit=3&offset=3'\n\ - ```\n" - in: query - name: offset - required: false - schema: { type: string } - - description: - "The order in which the results to be returned.\n>\u26A0\uFE0F\ - \ ***Use without quotes***\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ - \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&order=desc'\n\ - ```\n" - in: query - name: order - required: false - schema: - enum: [asc, desc] - type: string - responses: - "200": - content: - application/json: - schema: - properties: - count: - { - description: The total number of entries found., - example: 3, - type: integer, - } - data: - description: "The data of the response. - " - items: - { $ref: "#/components/schemas/ThreatHistoryDataList" } - type: array - link: - description: The pagination information of the results. - items: { $ref: "#/components/schemas/Pagination" } - type: array - message: - { - description: Generic response message., - example: Successful, - type: string, - } - success: - { - description: The response status., - example: true, - type: boolean, - } - type: object - description: Request succeeded - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Threat Signature Release History - tags: [Threat Prevention] - - - /edl: - get: - operationId: edl - description: | - A GET request to retrieve the predefined external dynamic lists by name and version. - parameters: - - name: name - in: query - required: false - schema: - type: string - enum: - - panw-known-ip-list - - panw-highrisk-ip-list - - panw-torexit-ip-list - - panw-bulletproof-ip-list - description: | - Provides the EDL by the name. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest' - ``` - - - name: ipaddr - in: query - required: false - schema: - type: string - description: | - Provides the EDLs containing the IP address. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0' - ``` - - - name: version - in: query - required: false - schema: - type: string - description: | - Provides the EDL by the specific AV package version. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-highrisk-ip-list&version=4024' - ``` - - Use "latest" for latest release version: - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0&version=latest' - ``` - - - name: listformat - in: query - required: false - schema: - type: string - enum: - - array - description: | - Optional field to provide more convenient way to ingest the EDL. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&listformat=array' - ``` - - - name: limit - in: query - required: false - schema: - type: string - description: | - Optional parameter. The maximum number of results to return in each page. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&limit=5' - ``` - - - name: offset - in: query - required: false - schema: - type: string - description: | - Optional parameter. The starting position of the query in relation to the complete set of the unpaginated results. - - --- - ``` - curl -v -H 'X-API-KEY: API_KEY' \ - 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-torexit-ip-list&version=latest&limit=5&offset=5' - ``` - responses: - "200": - description: Request succeeded - content: - application/json: - schema: - type: object - properties: - data: - type: object - items: - $ref: "#/components/schemas/GetEdlSuccessResponse" - headers: - X-Day-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per day. - example: 2000 - schema: { type: integer } - X-Day-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one day). - schema: { type: integer } - X-Day-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one day) resets. - schema: { type: integer } - X-Minute-RateLimit-Limit: - description: - The maximum number of requests that the user is permitted - to make per minute. - example: 200 - schema: { type: integer } - X-Minute-RateLimit-Remaining: - description: - The number of requests remaining in the current rate limit - window (one minute). - schema: { type: integer } - X-Minute-RateLimit-Reset: - description: - The epoch timestamp at which the current rate limit window - (one minute) resets. - schema: { type: integer } - 4XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Client related error response - 5XX: - content: - application/json: - schema: - properties: - message: - { description: Generic response message., example: Error - message., type: string } - success: - { - description: The response status., - example: false, - type: boolean, - } - type: object - description: Server related error response - security: - - X-API-KEY: [] - summary: Request Predefined EDL Content - tags: [Threat Prevention] - - -servers: - - { url: "https://api.threatvault.paloaltonetworks.com/service/v1" } -tags: - - { name: Threat Prevention } +components: + securitySchemes: + X-API-KEY: + description: API key to query https://api.threatvault.paloaltonetworks.com/service/v1 + in: header + name: X-API-KEY + type: apiKey + schemas: + GetThreatBatchList: + type: object + properties: + antivirus: + type: array + description: "List of Antivirus signatures." + items: + type: object + properties: + id: + type: string + description: "The unique threat signature id." + example: "280392504" + name: + type: string + description: "The threat signature name." + example: "trojan/Win32 DLL.razy.slo" + severity: + type: string + description: | + The threat signature severity. + *List: low, informative, medium, high or critical* + example: "medium" + type: + type: string + description: "A numerical value describing the type of the threat signature." + example: "0" + subtype: + type: string + description: "The threat signature subtype." + example: "virus" + action: + type: string + description: "The threat signature default action. This is generally empty for Antivirus signatures." + example: "" + description: + type: string + description: "The threat signature description." + example: "This signature detected trojan/Win32 DLL.razy.slo" + create_time: + type: string + description: "The threat signature creation time." + example: "2019-06-19T17:06:12Z" + status: + type: string + description: | + The threat signature creation time. + *List: active or inactive* + example: "active" + related_sha256_hashes: + type: array + description: "The list of related sha256 hashes for the threat signature." + items: + type: string + example: + [ + "47e3da7e179b755a1ccc8fe8fc506a2fb15baff2c124b15cf2f5e29038f3d1ac", + "5cd3e058f6049a31a42c292ebb091a1b5ea4bd9c7bc6fed5ac8a33c5fc89924a", + ] + release: + type: object + description: "The threat signature release information." + properties: + antivirus: + type: object + description: "The threat signature information related to Antivirus package updates." + properties: + first_release_version: + type: string + description: "The release version when the threat signature was first released with Antivirus package." + example: "3017" + first_release_time: + type: string + description: "The release time when the threat signature was first released with Antivirus package." + example: "2018-03-02T11:06:51Z" + last_release_version: + type: string + description: "The release version when the threat signature was last released with Antivirus package." + example: "4115" + last_release_time: + type: string + description: "The release time when the threat signature was last released with Antivirus package." + example: "2022-06-14T13:35:54Z" + wildfire: + type: object + description: "The threat signature information related to WildFire package updates." + properties: + first_release_version: + type: string + description: "The release version when the threat signature was first released with WildFire package." + example: "359199" + first_release_time: + type: string + description: "The release time when the threat signature was first released with WildFire package." + example: "2019-06-19T17:06:35Z" + last_release_version: + type: string + description: "The release version when the threat signature was last released with WildFire package." + example: "672412" + last_release_time: + type: string + description: "The release time when the threat signature was last released with WildFire package." + example: "2022-06-14T16:56:15Z" + EdlDataList: + type: object + properties: + version: + type: string + description: "The version of the release." + example: "4030" + name: + type: string + description: "The name of the predefined EDL." + example: "panw-known-ip-list" + ipaddr: + type: string + description: "The IP address." + example: "192.0.2.0" + GetEdlSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: "#/components/schemas/Pagination" + count: + type: integer + description: "The total number of entries found." + example: 1 + data: + type: array + description: "The data of the response." + items: + $ref: '#/components/schemas/EdlDataList' + message: + type: string + description: "Generic response message." + example: "Successful" + Pagination: + type: object + properties: + next: + type: string + description: "The URL of previous page with results." + previous: + type: string + description: "The URL of next page with results." + ReleaseNotesDataList: + type: object + properties: + release_version: + type: integer + description: "The release version of the update." + example: 8446 + content_version: + type: string + description: "The content version of the update." + example: "8446-6886" + type: + type: string + description: "The type of the release notes." + example: "content" + json_data: + type: array + description: "The release notes information." + items: + type: object + properties: + notes: + type: array + description: "General notices and reminders." + applications: + type: array + description: "The APP-ID updates in the release notes." + decoders: + type: array + description: "The decoder updates in the release notes." + example: ["improved ..."] + data_correlation: + type: array + description: "The Data Correlation Object updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + modified: + type: array + description: "List of modified entries." + deleted: + type: array + description: "List of deleted entries." + file_type: + type: array + description: "The File-Format updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + modified: + type: array + description: "List of modified entries." + disabled: + type: array + description: "List of disabled entries." + spyware: + type: array + description: "The Anti-Spyware updates in the release notes." + vulnerability: + type: array + description: "The Vulnerability Protection updates in the release notes." + items: + type: object + properties: + new: + type: array + description: "List of new entries." + items: + type: object + properties: + severity: + type: string + description: "The severity of the threat." + example: "high" + pan_id: + type: integer + description: "The unique id of the signature." + example: 30515 + attack_name: + type: string + description: "The name of the signature." + example: "File Loading" + cve: + type: string + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: "" + vendor: + type: string + description: "The vulnerability identifier issued by vendor on advisories." + example: "" + action: + type: string + description: "The default action when the signature is triggered." + example: "reset-both" + change_data: + type: string + description: "Additional information about the updated signature." + example: "updated action to ...." + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "9.1.0" + modified: + type: array + items: + type: object + properties: + severity: + type: string + description: "The severity of the threat." + example: "high" + pan_id: + type: integer + description: "The unique id of the signature." + example: 30077 + attack_name: + type: string + description: "The name of the signature." + example: "Vulnerability" + cve: + type: string + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: "CVE-2006-3942, CVE-2006-1314" + vendor: + type: string + description: "The vulnerability identifier issued by vendor on advisories." + example: "MS06-063" + action: + type: string + description: "The default action when the signature is triggered." + example: "reset-server" + change_data: + type: string + description: "Additional information about the updated signature." + example: "updated action to ...." + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "" + disabled: + type: array + description: "List of disabled entries." + ThreatDataList: + type: object + properties: + fileformat: + type: array + description: "List of File-Format signatures." + spyware: + type: array + description: "List of Anti-Spyware signatures." + vulnerability: + type: array + description: "List of Vulnerability Protection signatures." + items: + type: object + properties: + id: + type: string + description: "The unique id of the signature." + example: "30135" + name: + type: string + description: "The name of the signature." + example: "Name of the threat" + description: + type: string + description: "The description of the signature." + example: "Description of the threat ..." + category: + type: string + description: "The threat category of the signature." + example: "code-execution" + min_version: + type: string + description: "The PAN-OS minimum version." + example: "8.1.0" + max_version: + type: string + description: "The PAN-OS maximum version." + example: "11.1.0" + severity: + type: string + description: "The severity of the threat." + example: "high" + default_action: + type: string + description: "The default action when the signature is triggered." + example: "alert" + cve: + type: array + description: "The CVE (Common Vulnerabilities and Exposures) of the threat." + example: ["CVE-2007-1204", "CVE-2021-35393"] + vendor: + type: array + description: "The vulnerability identifier issued by vendor on advisories." + example: ["MS07-019"] + reference: + type: array + description: "The public reference of the threat." + example: ["Url1", "Url2"] + status: + type: string + description: "The status of the signature." + example: "released" + details: + type: object + description: "Any additional details of the signature." + example: {} + ori_release_version: + type: string + description: "The original release version of the signature." + example: "8451" + latest_release_version: + type: string + description: "The latest release version of the signature." + example: "8451" + ori_release_time: + type: string + description: "The original release time of the signature." + example: "2021-08-31 01:25:04" + latest_release_time: + type: string + description: "The latest release time of the signature." + example: "2021-08-31 01:25:04" + ThreatHistoryDataList: + type: object + properties: + version: + type: string + description: "The version of the release." + example: "4020-4531" + build_time: + type: string + description: "The time when the package was built." + example: "2022-03-12T22:23:38Z" + release_time: + type: string + description: "The time when the package was released externally." + example: "2022-03-13T03:02:24Z" + GetIpFeedSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: '#/components/schemas/Pagination' + count: + type: integer + description: "The total number of entries found." + example: 1 + data: + type: array + description: "The data of the response." + items: + $ref: '#/components/schemas/IpFeedDataList' + message: + type: string + description: "Generic response message." + example: "Successful" + PostIpFeedBatchSuccessResponse: + type: object + properties: + success: + type: boolean + description: "The response status." + example: true + link: + type: array + description: "The pagination information of the results." + items: + $ref: '#/components/schemas/Pagination' + count: + type: integer + description: "The total number of entries found." + example: 1 + data: + type: array + description: | + The data of the response. + items: + $ref: '#/components/schemas/PostIpFeedBatchList' + message: + type: string + description: "Generic response message." + example: "Successful" + PostIpFeedBatchList: + type: object + properties: + ipaddr: + type: string + description: "The IP address." + example: "2.59.154.102" + name: + type: string + description: "The name of the IP Feed entry." + example: "High Risk IP Feed" + status: + type: string + description: "The status of the IP Feed entry." + example: "released" + release: + type: object + description: "The release information." + properties: + first_release_version: + type: string + description: "The release version when the IP Feed was released." + example: "3566" + first_release_time: + type: string + description: "The release time when the IP Feed was released." + example: "2020-12-16T23:40:24Z" + IpFeedDataList: + type: object + properties: + ipaddr: + type: string + description: "The IP address." + example: "2.59.154.102" + name: + type: string + description: "The name of the IP Feed entry." + example: "High Risk IP Feed" + status: + type: string + description: "The status of the IP Feed entry." + example: "released" + release: + type: object + description: "The release information." + properties: + first_release_version: + type: string + description: "The release version when the IP Feed was released." + example: "3566" + first_release_time: + type: string + description: "The release time when the IP Feed was released." + example: "2020-12-16T23:40:24Z" + geo: + type: string + description: "The geolocation information of the IP address." + example: "JP (Japan)" + asn: + type: string + description: "The Autonomous System information of the IP address." + example: "136526 (ALLCLOUD-AS-AP ALLCLOUD LIMITED, HK)" + geo: + type: string + description: "The geolocation information of the IP address." + example: "JP (Japan)" + asn: + type: string + description: "The Autonomous System information IP address." + example: "136526 (ALLCLOUD-AS-AP ALLCLOUD LIMITED, HK)" +info: + contact: {} + description: " + The Threat Prevention API endpoints are available to customers with an active Threat Prevention or Advanced Threat Prevention subscription. + List of Threat Prevention API endpoints: + 1. Link to [Request Content Release Notes](/threat-vault/api/releasenotes) + 2. Link to [Request Threat Metadata](/threat-vault/api/threats) + 3. Link to [Request Threat Signature Metadata in Batch Mode](/threat-vault/api/threatsbatch) + 4. Link to [Request Threat Signature Release History](/threat-vault/api/threatshistory) + " + title: Threat Prevention + version: "1.0" +openapi: 3.0.1 +paths: + /release-notes: + get: + description: + "A GET request to retrieve the release notes information by type\ + \ and version.\n\n- Notes:\n - Any Content release notes before Version 8000\ + \ is best effort.\n" + operationId: releasenotes + parameters: + - description: + "The type of the release notes (ex. Content).\n>\u26A0\uFE0F\ + \ ***Use without quotes***\n" + in: query + name: type + required: true + schema: + enum: [content] + type: string + - description: " + The release version (ex. 8446) or content version (ex. 8446-6886) of the release notes. + + \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=8446-6886'\n\ + ```\n + + Use latest for latest release version: + + \n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/release-notes?type=content&version=latest'\n\ + ```\n + " + + + + + + in: query + name: version + required: true + schema: { type: string } + responses: + "200": + content: + application/json: + schema: + properties: + count: + { + description: The total number of entries found., + example: 2, + type: integer, + } + data: + description: The data of the response. + items: { $ref: "#/components/schemas/ReleaseNotesDataList" } + type: array + link: + description: The pagination information of the results. + items: { $ref: "#/components/schemas/Pagination" } + type: array + message: + { + description: Generic response message., + example: Successful, + type: string, + } + success: + { + description: The response status., + example: true, + type: boolean, + } + type: object + description: Request succeeded + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Content Release Notes + tags: [Threat Prevention] + /threats: + get: + description: + "A GET request to retrieve threat metadata. The nature of the query is determined by the query parameter that you provide on the call to this API. + \n- Notes: \n - Optionally, each query parameter can be used together\ + \ with the \"type\" query parameter to filter out the results.\n - Any Antivirus /\ + \ WildFire release summary information before **February 2020** is best-effort\ + \ since the information is not available.\n" + operationId: threats + parameters: + - description: "Query a specific Threat signature by signature ID. + " + in: query + name: id + schema: { type: string } + - description: + "Provides the threat signatures metadata by exact match of the\ + \ signature names.\n\n*Note: IPS threat signatures also support partial\ + \ match.*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?name=Microsoft+PE+File'\n\ + ```\n" + in: query + name: name + schema: { type: string } + - description: + "Provides the threat signatures metadata by exact or partial\ + \ match of the CVE tied to the signatures.\n\n*Valid partial CVE format:\ + \ CVE-YYYY*\n\n*Valid exact CVE format: CVE-YYYY-NNNN (NNNN can be 4 or\ + \ more digits)*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?cve=CVE-2020-1234'\n\ + ```\nor \n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?cve=CVE-2021'\n\ + ```\n" + in: query + name: cve + schema: { type: string } + + - description: + "Provides the threat signature metadata by matching the vendor ID tied to the signatures.\ + \n\n*This parameter is only supported for IPS threat signature\ + \ requests.*\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?vendor=MS16-095'\n\ + ```\n" + in: query + name: vendor + schema: { type: string } + + - description: + "Used together with toReleaseDate field. Provides the IPS threat\ + \ signatures metadata by the release dates range.\n\n*Only supported for\ + \ IPS threat signatures: fileformat, spyware, vulnerability*\n\n---\n```\n\ + curl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8440&toReleaseVersion=8446'\n\ + ```\n" + in: query + name: fromReleaseDate + schema: { type: string } + - description: + "The right boundary of date range query, must use with `fromReleaseDate`. + Example can be found in **fromReleaseDate** section + " + in: query + name: toReleaseDate + schema: { type: string } + - description: + "Used together with toReleaseVersion field. Provides the IPS\ + \ threat signatures metadata by the release versions range.\n\n*Only supported\ + \ for IPS threat signatures: fileformat, spyware, vulnerability*\n\n---\n\ + ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8440&toReleaseVersion=8446'\n\ + ```\n" + in: query + name: fromReleaseVersion + schema: { type: string } + - description: + "The right boundary of version range query, must use with `fromReleaseVersion`. + Example can be found in **toReleaseVersion** section + " + in: query + name: toReleaseVersion + schema: { type: string } + - description: + "Provides the IPS threat signatures metadata by the release date.\n\ + \n*Only supported for IPS threat signatures: fileformat, spyware, vulnerability*\n\ + \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?releaseDate=2021-08-17'\n\ + ```\n" + in: query + name: releaseDate + schema: { type: string } + - description: + "Provides the IPS threat signatures metadata by the release version.\n\ + \n*Only supported for IPS threat signatures: fileformat, spyware, vulnerability*\n\ + \n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?releaseVersion=8446'\n\ + ```\n" + in: query + name: releaseVersion + schema: { type: string } + - description: + "Provides the threat signature metadata based on the threat type.\ + \ Use together with the other fields to filter out the results.\n>\u26A0\ + \uFE0F ***Use without quotes***\n\n- Options:\n - antivirus (Provides Antivirus\ + \ signatures metadata)\n - dns (Provides DNS signatures metadata)\n -\ + \ fileformat (Provides all IPS File-Format signature metadata)\n - ips\ + \ (Provides all IPS signature metadata)\n - rtdns (Provides Real-Time DNS\ + \ Detection entries metadata)\n - spyware (Provides all IPS Anti-Spyware\ + \ signature metadata)\n - spywarec2 (Provides Spyware C2 signatures metadata)\n\ + \ - vulnerability (Provides all IPS Vulnerability Protection signature\ + \ metadata)\n \n---\nGet all IPS signatures:\n``` \ncurl -v -H 'X-API-KEY:\ + \ API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips'\n\ + ```\n*Note: This use-case is only supported for IPS threat signatures: fileformat,\ + \ spyware, vulnerability*\n\n---\nGet all File-Format signatures that were\ + \ recently updated between Content Version 8590 and Content Version 8594:\n\ + ``` \ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?fromReleaseVersion=8590&toReleaseVersion=8594&type=fileformat'\n\ + ```\n" + in: query + name: type + schema: + enum: + [ + ips, + fileformat, + spyware, + vulnerability, + antivirus, + dns, + rtdns, + spywarec2, + ] + type: string + - description: + "Provides the file information and threat signatures that match\ + \ the hash of the sample.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\ + \n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?sha256=7879722cd37b1c5b2703ea5a1a92a036a96f4a1fc6272b92c197b3a4b17267cc'\n\ + ```\n" + in: query + name: sha256 + schema: { type: string } + - description: + "Provides the file information and threat signatures that match\ + \ the hash of the sample.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY' \\\ + \n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?md5=ca066f965dfbc5392871d3fa281236cf'\n\ + ```\n" + in: query + name: md5 + schema: { type: string } + + - description: + "The maximum number of results to return in each page.\n\n---\n\ + ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips&limit=1000'\n\ + ```\n" + in: query + name: limit + required: false + schema: { type: string } + - description: + "The starting position of the query in relation to the complete\ + \ set of the unpaginated results.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats?type=ips&limit=1000&offset=1000'\n\ + ```\n" + in: query + name: offset + required: false + schema: { type: string } + + responses: + "200": + content: + application/json: + schema: + properties: + count: + { + description: The total number of entries found., + example: 6, + type: integer, + } + data: + description: The data of the response. + items: { $ref: "#/components/schemas/ThreatDataList" } + type: array + link: + description: The pagination information of the results. + items: { $ref: "#/components/schemas/Pagination" } + type: array + message: + { + description: Generic response message., + example: Successful, + type: string, + } + success: + { + description: The response status., + example: true, + type: boolean, + } + type: object + description: Request succeeded + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Threat Metadata + tags: [Threat Prevention] + post: + description: + "A POST request to retrieve the threats signature metadata by id,\ + \ name or sample hash (sha256 or md5) in batch mode. Batch limit is 100 entries.\n\ + \n- Notes: \n - Optionally, each query parameter can be used together\ + \ with the \"type\" query parameter to filter out the results.\n - Any Antivirus /\ + \ WildFire release summary information before **February 2020** is best-effort\ + \ since the information is not available.\n" + operationId: threatsbatch + requestBody: + content: + application/json: + schema: + properties: + id: + description: + "Provides the threat signatures metadata by exact match\ + \ of the signature ids.\n\n---\n```\ncurl -v -X POST -H 'X-API-KEY:\ + \ API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d\ + \ '{\"id\": [\"280392504\"]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ + ```\n" + items: { type: string } + type: array + md5: + description: + "Provides the file information and threat signatures\ + \ that match the hash of the sample.\n\n---\n```\ncurl -v -X POST\ + \ -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ + \ \\\n -d '{\"md5\": [\"ca066f965dfbc5392871d3fa281236cf\"]}'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ + ```\n" + items: { type: string } + type: array + name: + description: + "Provides the threat signatures metadata by exact match\ + \ of the signature names.\n \n---\n```\ncurl -v -X POST -H\ + \ 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ + \ \\\n -d '{\"name\": [\"Microsoft PE File\"]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ + ```\n" + items: { type: string } + type: array + sha256: + description: + "Provides the file information and threat signatures\ + \ that match the hash of the sample.\n\n---\n```\ncurl -v -X POST\ + \ -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ + \ \\\n -d '{\"sha256\": [\"7879722cd37b1c5b2703ea5a1a92a036a96f4a1fc6272b92c197b3a4b17267cc\"\ + ]}' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ + ```\n" + items: { type: string } + type: array + type: + description: + "Provides the threat signature metadata based on the\ + \ threat type. Use together with the other fields to filter out\ + \ the results.\n>\u26A0\uFE0F ***Use without quotes***\n\n- Options:\n\ + \ - antivirus (Provides Antivirus signatures metadata)\n - dns\ + \ (Provides DNS signatures metadata)\n - fileformat (Provides\ + \ all IPS File-Format signature metadata)\n - ips (Provides all\ + \ IPS signature metadata)\n - rtdns (Provides Real-Time DNS Detection\ + \ entries metadata)\n - spyware (Provides all IPS Anti-Spyware\ + \ signature metadata)\n - spywarec2 (Provides Spyware C2 signatures\ + \ metadata)\n - vulnerability (Provides all IPS Vulnerability\ + \ Protection signature metadata)\n \n---\n```\ncurl -v\ + \ -X POST -H 'X-API-KEY: API_KEY' \\\n -H 'Content-Type: application/json'\ + \ \\\n -d '{\"id\": [\"280392504\"], \"type\":\"antivirus\"}'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats'\n\ + ```\n" + enum: + [ + ips, + fileformat, + spyware, + vulnerability, + antivirus, + dns, + rtdns, + spywarec2, + ] + type: string + type: object + required: true + responses: + "200": + content: + application/json: + schema: + properties: + count: + { + description: The total number of entries found., + example: 1, + type: integer, + } + data: + description: "The data of the response. + " + items: { $ref: "#/components/schemas/GetThreatBatchList" } + type: array + link: + description: The pagination information of the results. + items: { $ref: "#/components/schemas/Pagination" } + type: array + message: + { + description: Generic response message., + example: Successful, + type: string, + } + success: + { + description: The response status., + example: true, + type: boolean, + } + type: object + description: Request succeeded + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Threat Signature Metadata in Batch Mode + tags: [Threat Prevention] + /threats/history: + get: + description: + "A GET request to retrieve the threats signature release history\ + \ by id and package type.\n\n- Notes:\n - The retention policy of **Antivirus**\ + \ release history data is for **1 year** (only the last 1 year of release\ + \ history data will be available).\n - The retention policy of **WildFire**\ + \ release history data is for **30 days** (only the last 30 days of release\ + \ history data will be available).\n - Any Antivirus / WildFire release history\ + \ information before **Version 4140** is best-effort since the information\ + \ is not available.\n - The Antivirus / WildFire version field in the responses\ + \ before **Version 4140** is in the format of **XXXX** (ex. \"version\": \"\ + 4140\") and after that the format is **XXXX-YYYY** (ex. \"version\": \"4141-4637\"\ + ).\n - The Antivirus / WildFire release time before **Version 4140** is the\ + \ package start building time as the actual release time is not available.\n" + operationId: threatshistory + parameters: + - description: + "Provides the threat signature metadata based on the threat type.\n\ + >\u26A0\uFE0F ***Use without quotes***\n\n- Options:\n - antivirus (Provides\ + \ Antivirus signature release information)\n - wildfire (Provides WildFire\ + \ signature release information)\n" + in: query + name: type + required: true + schema: + enum: [antivirus, wildfire] + type: string + - description: + "Provides the threat signature release history by matching the\ + \ signature id in the releases.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus'\n\ + ```\n" + in: query + name: id + required: true + schema: { type: string } + - description: + "The maximum number of results to return in each page.\n\n---\n\ + ```\ncurl -v -H 'X-API-KEY: API_KEY' \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&limit=3'\n\ + ```\n" + in: query + name: limit + required: false + schema: { type: string } + - description: + "The starting position of the query in relation to the complete\ + \ set of the unpaginated results.\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&limit=3&offset=3'\n\ + ```\n" + in: query + name: offset + required: false + schema: { type: string } + - description: + "The order in which the results to be returned.\n>\u26A0\uFE0F\ + \ ***Use without quotes***\n\n---\n```\ncurl -v -H 'X-API-KEY: API_KEY'\ + \ \\\n 'https://api.threatvault.paloaltonetworks.com/service/v1/threats/history?id=280392504&type=antivirus&order=desc'\n\ + ```\n" + in: query + name: order + required: false + schema: + enum: [asc, desc] + type: string + responses: + "200": + content: + application/json: + schema: + properties: + count: + { + description: The total number of entries found., + example: 3, + type: integer, + } + data: + description: "The data of the response. + " + items: + { $ref: "#/components/schemas/ThreatHistoryDataList" } + type: array + link: + description: The pagination information of the results. + items: { $ref: "#/components/schemas/Pagination" } + type: array + message: + { + description: Generic response message., + example: Successful, + type: string, + } + success: + { + description: The response status., + example: true, + type: boolean, + } + type: object + description: Request succeeded + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Threat Signature Release History + tags: [Threat Prevention] + + + /edl: + get: + operationId: edl + description: | + A GET request to retrieve the predefined external dynamic lists by name and version. + parameters: + - name: name + in: query + required: false + schema: + type: string + enum: + - panw-known-ip-list + - panw-highrisk-ip-list + - panw-torexit-ip-list + - panw-bulletproof-ip-list + description: | + Provides the EDL by the name. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest' + ``` + + - name: ipaddr + in: query + required: false + schema: + type: string + description: | + Provides the EDLs containing the IP address. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0' + ``` + + - name: version + in: query + required: false + schema: + type: string + description: | + Provides the EDL by the specific AV package version. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-highrisk-ip-list&version=4024' + ``` + + Use "latest" for latest release version: + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?ipaddr=192.0.2.0&version=latest' + ``` + + - name: listformat + in: query + required: false + schema: + type: string + enum: + - array + description: | + Optional field to provide more convenient way to ingest the EDL. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&listformat=array' + ``` + + - name: limit + in: query + required: false + schema: + type: string + description: | + Optional parameter. The maximum number of results to return in each page. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-known-ip-list&version=latest&limit=5' + ``` + + - name: offset + in: query + required: false + schema: + type: string + description: | + Optional parameter. The starting position of the query in relation to the complete set of the unpaginated results. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/edl?name=panw-torexit-ip-list&version=latest&limit=5&offset=5' + ``` + responses: + "200": + description: Request succeeded + content: + application/json: + schema: + type: object + properties: + data: + type: object + items: + $ref: "#/components/schemas/GetEdlSuccessResponse" + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response message., example: Error + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + security: + - X-API-KEY: [] + summary: Request Predefined EDL Content + tags: [Threat Prevention] + + + + /ip-feed: + get: + operationId: ip_feed + security: + - X-API-KEY: [ ] + summary: Request IP Feed information through the Threat Vault API + tags: [Threat Prevention] + description: | + A GET request to retrieve the IP feed information by name, IP address or IP address range. + parameters: + - name: name + in: query + required: false + schema: + type: string + enum: + - malicious + - high-risk + description: | + Provides the IP feed entries by the feed name. + + *Note: Returns only entries with 'released' status that exist in the Threat Intelligence database.* + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?name=malicious' + ``` + + - name: ipaddr + in: query + required: false + schema: + type: string + description: | + Provides the IP feed information by IP address. + + *Note:* + *Always returns a result.* + *Returns feed information if IP Address exists in the Threat Intelligence database, + otherwise returns only the Geolocation and Autonomous System information.* + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?ipaddr=193.189.116.210' + ``` + + - name: fromipaddr + in: query + required: false + schema: + type: string + description: | + Used together with `toipaddr` field. Provides the IP feed entries based on IP address range. + + *Note: Returns entries with 'released', 'disabled' or 'expired' status that exist in the Threat Intelligence database.* + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?fromipaddr=185.130.5.207&toipaddr=185.130.5.236' + ``` + + - name: toipaddr + in: query + required: false + schema: + type: string + description: | + The right boundary of date range query, must use with `toipaddr`. + + Example can be found in **toipaddr** section + + - name: limit + in: query + required: false + schema: + type: string + description: | + Optional parameter. The maximum number of results to return in each page. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?name=high-risk&limit=3' + ``` + + - name: offset + in: query + required: false + schema: + type: string + description: | + Optional parameter. The starting position of the query in relation to the complete set of the unpaginated results. + + --- + ``` + curl -v -H 'X-API-KEY: API_KEY' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?name=high-risk&limit=10&offset=10' + ``` + responses: + "200": + description: Request succeeded + content: + 'application/json': + schema: + $ref: "#/components/schemas/GetIpFeedSuccessResponse" + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response messa + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response messa + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + + post: + operationId: ip_feed_batch + security: + - X-API-KEY: [] + summary: Request IP Feed information through the Threat Vault API in Batch Mode + tags: [Threat Prevention] + description: | + A POST request to retrieve the IP feed information by IP address. Batch limit is 100 entries. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ipaddr: + type: array + description: | + Provides the IP feed information by a list of IP addresses. Limit is 100. + + --- + ``` + curl -v -X POST -H 'X-API-KEY: API_KEY' \ + -H 'Content-Type: application/json' \ + -d '{"ipaddr": ["185.130.5.200", "185.130.5.201", "185.130.5.202", "185.130.5.203", "185.130.5.204", "185.130.5.205", "185.130.5.206", "185.130.5.207", "185.130.5.208", "185.130.5.209", "185.130.5.210"]}' \ + 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed' + ``` + items: + type: string + + responses: + "200": + description: Request succeeded + content: + 'application/json': + schema: + $ref: "#/components/schemas/GetIpFeedSuccessResponse" + headers: + X-Day-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per day. + example: 2000 + schema: { type: integer } + X-Day-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one day). + schema: { type: integer } + X-Day-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one day) resets. + schema: { type: integer } + X-Minute-RateLimit-Limit: + description: + The maximum number of requests that the user is permitted + to make per minute. + example: 200 + schema: { type: integer } + X-Minute-RateLimit-Remaining: + description: + The number of requests remaining in the current rate limit + window (one minute). + schema: { type: integer } + X-Minute-RateLimit-Reset: + description: + The epoch timestamp at which the current rate limit window + (one minute) resets. + schema: { type: integer } + 4XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response messa + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Client related error response + 5XX: + content: + application/json: + schema: + properties: + message: + { description: Generic response messa + message., type: string } + success: + { + description: The response status., + example: false, + type: boolean, + } + type: object + description: Server related error response + + + + +servers: + - { url: "https://api.threatvault.paloaltonetworks.com/service/v1" } +tags: + - { name: Threat Prevention } From 953298d2242b15491e3824580a0c5ed219744c42 Mon Sep 17 00:00:00 2001 From: hokim Date: Tue, 14 Nov 2023 15:40:53 -0800 Subject: [PATCH 6/8] Additional IP list changes --- .../threat-vault/ThreatPrevention.yaml | 4 +- package.json | 2 +- products/cdss/docs/release-notes/changelog.md | 1 + .../cdss/docs/release-notes/release-notes.md | 2 +- products/cdss/sidebars.js | 8 + .../docs/examples/get-ip-feed-batch-mode.mdx | 80 ++++++ .../docs/examples/get-ip-feed-information.mdx | 239 ++++++++++++++++++ .../threat-vault-response-fields.mdx | 28 +- 8 files changed, 357 insertions(+), 7 deletions(-) create mode 100644 products/threat-vault/docs/examples/get-ip-feed-batch-mode.mdx create mode 100644 products/threat-vault/docs/examples/get-ip-feed-information.mdx diff --git a/openapi-specs/threat-vault/ThreatPrevention.yaml b/openapi-specs/threat-vault/ThreatPrevention.yaml index df3ca4ced..7303913f0 100644 --- a/openapi-specs/threat-vault/ThreatPrevention.yaml +++ b/openapi-specs/threat-vault/ThreatPrevention.yaml @@ -1500,7 +1500,7 @@ paths: operationId: ip_feed security: - X-API-KEY: [ ] - summary: Request IP Feed information through the Threat Vault API + summary: Request IP Feed Information tags: [Threat Prevention] description: | A GET request to retrieve the IP feed information by name, IP address or IP address range. @@ -1674,7 +1674,7 @@ paths: operationId: ip_feed_batch security: - X-API-KEY: [] - summary: Request IP Feed information through the Threat Vault API in Batch Mode + summary: Request IP Feed Information in Batch Mode tags: [Threat Prevention] description: | A POST request to retrieve the IP feed information by IP address. Batch limit is 100 entries. diff --git a/package.json b/package.json index b37a53d53..18db72f6a 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,7 @@ "re-gen": "yarn clean-all && yarn gen-all", "getBlogs": "curl -H \"Accept: application/json\" \"https://api.rss2json.com/v1/api.json?rss_url=https%3A%2F%2Fmedium.com%2Ffeed%2Fpalo-alto-networks-developer-blog\" -o src/components/Medium/blogs.json", "getHashicorpBlogs": "curl -H \"Accept: application/json\" \"https://api.rss2json.com/v1/api.json?rss_url=https%3A%2F%2Fwww.hashicorp.com%2Fblog%2Fproducts%2Fterraform%2Ffeed.xml\" -o src/components/ProductLandingPage/Feeds/feeds.json", - "start:netsec": "cross-env PRODUCTS_INCLUDE=cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw yarn start", + "start:netsec": "cross-env PRODUCTS_INCLUDE=cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw-bpa yarn start", "start:splunk": "cross-env PRODUCTS_INCLUDE=panos,terraform,ansible,splunk yarn start", "start:sase": "cross-env PRODUCTS_INCLUDE=sase,access,sdwan yarn start", "start:cloud": "cross-env PRODUCTS_INCLUDE=prisma-cloud,compute yarn start", diff --git a/products/cdss/docs/release-notes/changelog.md b/products/cdss/docs/release-notes/changelog.md index b2a619ce5..204cf1f3f 100644 --- a/products/cdss/docs/release-notes/changelog.md +++ b/products/cdss/docs/release-notes/changelog.md @@ -15,3 +15,4 @@ keywords: | August 08, 2022 | First public release of the Threat Vault API for Threat Prevention and Advanced Threat Prevention subscription holders. | | August 23, 2022 | First public `BETA` release of the DNS Security API for DNS Security subscription holders. | | April 23, 2023 | The Threat Vault API now supports retrieval of [predefined EDL](https://docs.paloaltonetworks.com/pan-os/11-0/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/built-in-edls.html) ([external dynamic list](https://docs.paloaltonetworks.com/pan-os/11-0/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/external-dynamic-list.html)) content. | +| November 01, 2023 | The Threat Vault API now supports retrieval of [IP Feed Information](/threat-vault/api/ip-feed/) and [IP Feed Information in Batch Mode](/threat-vault/api/ip-feed-batch/). | diff --git a/products/cdss/docs/release-notes/release-notes.md b/products/cdss/docs/release-notes/release-notes.md index 70967196c..3fdacfeef 100644 --- a/products/cdss/docs/release-notes/release-notes.md +++ b/products/cdss/docs/release-notes/release-notes.md @@ -14,7 +14,7 @@ These release notes highlight API changes made for the various CDSS (Cloud-Deliv In addition, you can refer to the TechDocs [product documentation](https://docs.paloaltonetworks.com/cdss) for release information about non-API feature enhancements: -See also the [change log](/cdss/docs/release-notes/changelog) for information on all changes to this API documentation, some of which have +See also the [change log](../../cdss/docs/release-notes/changelog) for information on all changes to this API documentation, some of which have occurred in between API product releases. ## August 2022 diff --git a/products/cdss/sidebars.js b/products/cdss/sidebars.js index f8145c504..9875b2520 100644 --- a/products/cdss/sidebars.js +++ b/products/cdss/sidebars.js @@ -94,6 +94,14 @@ module.exports = { type: "doc", id: "threat-vault/docs/examples/get-content-release-notes", }, + { + type: "doc", + id: "threat-vault/docs/examples/get-ip-feed-information", + }, + { + type: "doc", + id: "threat-vault/docs/examples/get-ip-feed-batch-mode", + }, ], }, { diff --git a/products/threat-vault/docs/examples/get-ip-feed-batch-mode.mdx b/products/threat-vault/docs/examples/get-ip-feed-batch-mode.mdx new file mode 100644 index 000000000..c7b756bef --- /dev/null +++ b/products/threat-vault/docs/examples/get-ip-feed-batch-mode.mdx @@ -0,0 +1,80 @@ +--- +id: get-ip-feed-batch-mode +title: Request IP Feed Information in Batch Mode +description: Threat Vault API example showing how to request IP feed information using the IP address, IP address range, or the name of the feed in batch mode. +hide_title: false +hide_table_of_contents: false +keywords: + - security subscription +--- + +The API Reference information for retrieving IP feed information can be found +[here](/threat-vault/api/ip-feed-batch/). + +## Overview + +The Threat Vault API can be used to request IP feed information in batch mode. Consider the following examples: + +Keep a few things in mind when formatting your API query: + +1. All the query strings in Get requests must be a URL-Encoded parameter string. If you use a space in the URL-Encoded request, you must include either a plus sign (+) or %20 to replace the space. +2. You can specify the content type of the request body and response by specifying the Content-Type header. Some responses generate an HTTP response in addition to a JSON object. +3. Do not embed API keys in code or application source tree files. This can inadvertently expose the API key. Instead, consider storing the API key in environmental variables or files that are excluded from your application source tree files. + +## Example 1: A POST request to retrieve the IP feed information based on a list of IP addresses: + +```shell-session +curl -X POST -d '{"ipaddr": ["1.33.230.137", "1.117.154.185", "1.117.180.42"]}' 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed' \ + -H 'X-API-KEY: API_KEY' \ + -H 'Content-Type: application/json' +``` + +A successful API call returns, within the contents section, `status="success"` along with the IP feed results. + +```json +{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 3, + "data": [ + { + "ipaddr": "1.33.230.137", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "3327", + "first_release_time": "2020-04-22T20:38:31Z" + }, + "geo": "JP (Japan)", + "asn": "2514 (INFOSPHERE NTT PC Communications, Inc., JP)" + }, + { + "ipaddr": "1.117.154.185", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "4090", + "first_release_time": "2022-05-21T21:43:42Z" + }, + "geo": "CN (China)", + "asn": "45090 (TENCENT-NET-AP Shenzhen Tencent Computer Systems Company Limited, CN)" + }, + { + "ipaddr": "1.117.180.42", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "3888", + "first_release_time": "2021-11-02T00:53:22Z" + }, + "geo": "CN (China)", + "asn": "45090 (TENCENT-NET-AP Shenzhen Tencent Computer Systems Company Limited, CN)" + } + ], + "message": "Successful" +} +``` + diff --git a/products/threat-vault/docs/examples/get-ip-feed-information.mdx b/products/threat-vault/docs/examples/get-ip-feed-information.mdx new file mode 100644 index 000000000..4be680af1 --- /dev/null +++ b/products/threat-vault/docs/examples/get-ip-feed-information.mdx @@ -0,0 +1,239 @@ +--- +id: get-ip-feed-information +title: Request IP Feed Information +description: Threat Vault API example showing how to request IP feed information using the IP address, IP address range, or the name of the feed. +hide_title: false +hide_table_of_contents: false +keywords: + - security subscription +--- + +The API Reference information for retrieving IP feed information can be found +[here](/threat-vault/api/ip-feed/). + +## Overview + +The Threat Vault API can be used to request IP feed information. Consider the following examples: + +Keep a few things in mind when formatting your API query: + +1. All the query strings in Get requests must be a URL-Encoded parameter string. If you use a space in the URL-Encoded request, you must include either a plus sign (+) or %20 to replace the space. +2. You can specify the content type of the request body and response by specifying the Content-Type header. Some responses generate an HTTP response in addition to a JSON object. +3. Do not embed API keys in code or application source tree files. This can inadvertently expose the API key. Instead, consider storing the API key in environmental variables or files that are excluded from your application source tree files. + +## Example 1: Request information about the specific IP feed name that is present in the Threat Intelligence database while limiting the maximum number of results to three: + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?name=malicious&limit=3' +``` + +A successful API call returns, within the contents section, `status="success"` along with the IP feed results. + +```json +{ + "success": true, + "link": { + "next": "https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?name=malicious&limit=3&offset=3", + "previous": null + }, + "count": 4508, + "data": [ + { + "ipaddr": "1.33.230.137", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "3327", + "first_release_time": "2020-04-22T20:38:31Z" + }, + "geo": "JP (Japan)", + "asn": "2514 (INFOSPHERE NTT PC Communications, Inc., JP)" + }, + { + "ipaddr": "1.117.154.185", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "4090", + "first_release_time": "2022-05-21T21:43:42Z" + }, + "geo": "CN (China)", + "asn": "45090 (TENCENT-NET-AP Shenzhen Tencent Computer Systems Company Limited, CN)" + }, + { + "ipaddr": "1.117.180.42", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "3888", + "first_release_time": "2021-11-02T00:53:22Z" + }, + "geo": "CN (China)", + "asn": "45090 (TENCENT-NET-AP Shenzhen Tencent Computer Systems Company Limited, CN)" + } + ], + "message": "Successful" +} +``` + +## Example 2: Request information about the specific matching IP address in the Threat Intelligence database: + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?ipaddr=193.189.116.210' +``` + +A successful API call returns, within the Contents section, `status="success"` along with the associated IP feed entry details: + +```json +{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 1, + "data": [ + { + "ipaddr": "193.189.116.210", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T11:06:51Z" + }, + "geo": "PL (Poland)", + "asn": "44124 (RYBNET-AS, PL)" + } + ], + "message": "Successful" +} +``` + +## Example 3: Request information about the specific IP address using an IP address that does [not] exist in the Threat Intelligence database. This returns only Geolocation and Autonomous System information: + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?ipaddr=193.189.116.215' +``` + +A successful API call returns, within the Contents section, `status="success"` along with the associated IP feed entry details: + +```json +{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 1, + "data": [ + { + "ipaddr": "193.189.116.215", + "name": null, + "status": "N/A", + "release": {}, + "geo": "PL (Poland)", + "asn": "44124 (RYBNET-AS, PL)" + } + ], + "message": "Successful" +} +``` + +## Example 4: Request information about matching IP feed entries found in the Threat Intelligence database based on a range of IP addresses. This returns only Geolocation and Autonomous System information: + +```shell-session +curl -H 'X-API-KEY: API_KEY' 'https://api.threatvault.paloaltonetworks.com/service/v1/ip-feed?fromipaddr=185.130.5.207&toipaddr=185.130.5.236' +``` + +A successful API call returns, within the Contents section, `status="success"` along with the associated IP feed entry details: + +```json +{ + "success": true, + "link": { + "next": null, + "previous": null + }, + "count": 7, + "data": [ + { + "ipaddr": "185.130.5.207", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.208", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.224", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.231", + "name": "Malicious IP Feed", + "status": "released", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.233", + "name": "High Risk IP Feed", + "status": "expired", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.234", + "name": "High Risk IP Feed", + "status": "expired", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + }, + { + "ipaddr": "185.130.5.235", + "name": "High Risk IP Feed", + "status": "expired", + "release": { + "first_release_version": "2113", + "first_release_time": "2016-10-18T07:00:00Z" + }, + "geo": "DE (Germany)", + "asn": "204527 (BJNIP, DE)" + } + ], + "message": "Successful" +} +``` diff --git a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx index 1a524d782..52894709b 100644 --- a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx +++ b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx @@ -47,7 +47,7 @@ Metadata](/threat-vault/api/threats/): ## Threat Metadata Response Fields (Antivirus) -The following JSON response fields are found in [Request Threat Metadata](/threat-vault/api/threat-prevention#operation/threats): +The following JSON response fields are found in [Request Threat Metadata](/threat-vault/api/threats/): | Field | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -99,7 +99,7 @@ The following JSON response fields are found in [Request Threat Metadata](/threa ## Threat Signature Release History Response Fields -The following JSON response fields are found in [Request Threat Signature Release History](/threat-vault/api/threat-prevention#operation/threatshistory): +The following JSON response fields are found in [Request Threat Signature Release History](/threat-vault/api/threatshistory/): | Field | Description | | ------------------- | -------------------------------------------------- | @@ -116,7 +116,7 @@ The following JSON response fields are found in [Request Threat Signature Releas ## Predefined EDL Content Response Fields -The following JSON response fields are found in [Request Predefined EDL Content](/threat-vault/api/threat-prevention#operation/edl): +The following JSON response fields are found in [Request Predefined EDL Content](/threat-vault/api/edl/): | Field | Description | | ------------------- | -------------------------------------------------- | @@ -131,6 +131,28 @@ The following JSON response fields are found in [Request Predefined EDL Content] | `data.ipaddr` | The IP address. | | `message` | Generic response message. | +## Threat Prevention IP Feed Response Fields + +The following JSON response fields are found in [Request IP Feed Information](/threat-vault/api/ip-feed/) and [Request IP Feed Information in Batch Mode](/threat-vault/api/ip-feed-batch/): + +| Field | Description | +| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `success` | The response status. | +| `link` | The pagination information of the results. | +| `link.previous` | The URL of previous page with results. | +| `link.next` | The URL of next page with results. | +| `count` | The total number of entries found. | +| `data` | The data of the response. | +| `data.ipaddr` | The IP address. | +| `data.name` | The feed name. | +| `data.status` | The current status of the feed. | +| `data.release` | The release information of the feed. | +| `data.release.first_release_version` | The first release version of the feed. | +| `data.release.first_release_time` | The first release time of the feed. | +| `data.geo` | The geolocation information. | +| `data.asn` | The autonomous system information. | +| `message` | Generic response message. | + ## Advanced Threat Prevention Report Response Fields The following JSON response fields are found in [Request ATP Report in Batch Mode](/threat-vault/api/advanced-threat-prevention#operation/postatpreportsbatchmode): From ded0580a9b14c55069836648da9eb23dc9802ab5 Mon Sep 17 00:00:00 2001 From: hokim Date: Wed, 15 Nov 2023 15:10:58 -0800 Subject: [PATCH 7/8] Minor changes for IP feed update Changed RN entry status and fixed typo --- openapi-specs/threat-vault/AdvancedThreatPrevention.yaml | 2 +- products/cdss/docs/release-notes/release-notes.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml b/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml index a16c23ac7..0a20d7ca0 100644 --- a/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml +++ b/openapi-specs/threat-vault/AdvancedThreatPrevention.yaml @@ -611,7 +611,7 @@ components: Attack Evidences: type: string description: "The attack evidence." - example: "The session key is encoded with netbiosu." + example: "The session key is encoded with netbios." payload_info: type: object description: "The request payload information." diff --git a/products/cdss/docs/release-notes/release-notes.md b/products/cdss/docs/release-notes/release-notes.md index 3fdacfeef..e12b8f960 100644 --- a/products/cdss/docs/release-notes/release-notes.md +++ b/products/cdss/docs/release-notes/release-notes.md @@ -25,4 +25,4 @@ The following known issues are present in the current API release: | Known Issue ID | Description | Status | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | -| `CSP-12173` | Advanced Threat Prevention and Threat Prevention subscriptions included as part of a bundle package cannot currently access the ThreatVault API. | Unresolved | +| `CSP-12173` | Advanced Threat Prevention and Threat Prevention subscriptions included as part of a bundle package cannot currently access the ThreatVault API. | Resolved | From 47f9b27fb37a1756f3f591d601a4e3975b59bb06 Mon Sep 17 00:00:00 2001 From: hokim Date: Thu, 16 Nov 2023 10:35:32 -0800 Subject: [PATCH 8/8] ATP Reports Update Added additional report response fields. --- .../threat-vault-response-fields.mdx | 99 ++++++++++++------- 1 file changed, 66 insertions(+), 33 deletions(-) diff --git a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx index 52894709b..7c00a5e29 100644 --- a/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx +++ b/products/threat-vault/docs/response-fields/threat-vault-response-fields.mdx @@ -157,36 +157,69 @@ The following JSON response fields are found in [Request IP Feed Information](/t The following JSON response fields are found in [Request ATP Report in Batch Mode](/threat-vault/api/advanced-threat-prevention#operation/postatpreportsbatchmode): -| Field | Description | -| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `success` | The response status. | -| `data` | The data of the response. | -| `data.report_id` | The ID of the ATP report. | -| `data.err_msg` | Any error message related to the report. | -| `data.panos_info` | All related PAN-OS information. | -| `data.panos_info.fw_addr_v4` | Firewall IPv4 MP interface. | -| `data.panos_info.fw_addr_v6` | Firewall IPv6 MP interface (can be empty). | -| `data.panos_info.fw_app_version` | Firewall content package version. | -| `data.panos_info.fw_hostname` | Firewall hostname. | -| `data.panos_info.fw_model` | Firewall model. | -| `data.panos_info.serial` | Firewall serial number. | -| `data.panos_info.fw_sw_version` | Firewall PAN-OS version. | -| `data.session_info` | All related session information. | -| `data.session_info.flow_info.saddr` | Session source IP address. | -| `data.session_info.flow_info.daddr` | Session destination IP address. | -| `data.session_info.flow_info.sport` | Session source IP port. | -| `data.session_info.flow_info.dport` | Session destination IP port. | -| `data.session_info.flow_info.data_type` | The payload type. List: http, ssl, unknown-tcp and unknown-udp. | -| `data.session_info.session_id` | Session ID. | -| `data.session_info.session_timestamp` | Session timestamp. | -| `data.transaction_data` | The list of transactions of the session. One session may have one or many transactions. | -| `data.transaction_data.transaction_id` | The transaction ID. | -| `data.transaction_data.payload_sha256` | The SHA256 hash value of the payload. | -| `data.transaction_data.reports` | The list of detection service reports. | -| `data.transaction_data.reports.ds_name` | The detection service name. | -| `data.transaction_data.reports.status` | A flag to indicate the report is ready or not. | -| `data.transaction_data.reports.ds_report.payload_info` | Optional payload information. For HTTP: Method, URI, Version, Host, User-Agent, Content-Type, Cookies. For other protocols: This field will not be available. | -| `data.transaction_data.reports.ds_report.malware_families` | The list of malware families. | -| `data.transaction_data.reports.ds_report.malware_families.malware_family_type` | The name/type of the malware family. | -| `data.transaction_data.reports.ds_report.malware_families.confidence` | The confidence value. | -| `message` | Generic response message. | +| Field | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `success` | The response status. | +| `data` | The data of the response. | +| `data.report_id` | The ID of the ATP report. | +| `data.err_msg` | Any error message related to the report. | +| `data.panos_info` | All related PAN-OS information. | +| `data.panos_info.fw_addr_v4` | Firewall IPv4 MP interface. | +| `data.panos_info.fw_addr_v6` | Firewall IPv6 MP interface (can be empty). | +| `data.panos_info.fw_app_version` | Firewall content package version. | +| `data.panos_info.fw_hostname` | Firewall hostname. | +| `data.panos_info.fw_model` | Firewall model. | +| `data.panos_info.serial` | Firewall serial number. | +| `data.panos_info.fw_sw_version` | Firewall PAN-OS version. | +| `data.session_info` | All related session information. | +| `data.session_info.flow_info.saddr` | Session source IP address. | +| `data.session_info.flow_info.daddr` | Session destination IP address. | +| `data.session_info.flow_info.sport` | Session source IP port. | +| `data.session_info.flow_info.dport` | Session destination IP port. | +| `data.session_info.flow_info.data_type` | The payload type. List: http, ssl, unknown-tcp and unknown-udp. | +| `data.session_info.session_id` | Session ID. | +| `data.session_info.session_timestamp` | Session timestamp. | +| `data.transaction_data` | The list of transactions of the session. One session may have one or many transactions. | +| `data.transaction_data.transaction_id` | The transaction ID. | +| `data.transaction_data.payload_sha256` | The SHA256 hash value of the payload. | +| `data.transaction_data.detection_results` | The detection results information. | +| `data.transaction_data.detection_results.detection_service` | The detection service. | +| `data.transaction_data.detection_results.details` | Details information. | +| `data.transaction_data.detection_results.details.attack_analysis` | The attack analysis information. | +| `data.transaction_data.detection_results.details.attack_analysis.Attack Description` | The attack description. | +| `data.transaction_data.detection_results.details.attack_analysis.Attack Details` | The attack details. | +| `data.transaction_data.detection_results.details.attack_analysis.Attack Evidences` | The attack evidence. | +| `data.transaction_data.detection_results.details.payload_info` | The request payload information. | +| `data.transaction_data.detection_results.details.payload_info.Connection` | A general header controls whether the network connection stays open after the current transaction finishes. | +| `data.transaction_data.detection_results.details.payload_info.Cookie` | A header that contains stored HTTP cookies associated with the server. | +| `data.transaction_data.detection_results.details.payload_info.Host` | A header that specifies the host and port number of the server to which the request is being sent. | +| `data.transaction_data.detection_results.details.payload_info.Method` | A header that defines the desired action to be performed for a given resource. | +| `data.transaction_data.detection_results.details.payload_info.URI` | A header that defines the resource. | +| `data.transaction_data.detection_results.details.payload_info.User-Agent` | A header that identifies the requesting user agent. | +| `data.transaction_data.detection_results.details.payload_info.Version` | A header that specifies the HTTP version. | +| `data.transaction_data.detection_results.verdict` | The verdict value. | +| `data.transaction_data.reports` | The list of detection service reports. | +| `data.transaction_data.reports.ds_name` | The detection service name. | +| `data.transaction_data.reports.status` | A flag to indicate the report is ready or not. | +| `data.transaction_data.reports.ds_report.payload_info` | Optional payload information. For HTTP: Method, URI, Version, Host, User-Agent, Content-Type, Cookies. For other protocols: This field will not be available. | +| `data.transaction_data.reports.ds_report.malware_families` | The list of malware families. | +| `data.transaction_data.reports.ds_report.malware_families.malware_family_type` | The name/type of the malware family. | +| `data.transaction_data.reports.ds_report.malware_families.confidence` | The confidence value. | +| `message` | Generic response message. | + + + + + + + + + + + + + + + + +