Palo Alto Cortex Xpanse

the palo alto cortex xpanse connector facilitates the integration of swimlane turbine with cortex xpanse's attack surface management capabilities, enabling automated monitoring and management of internet facing assets palo alto cortex xpanse offers a comprehensive view of your organization's internet facing assets and potential security gaps this connector enables swimlane turbine users to automate asset management, incident response, and threat intelligence tasks by integrating with cortex xpanse's extensive telemetry data enhance your security posture by proactively managing alerts, assets, and vulnerabilities with streamlined workflows and real time data analysis limitations none to date prerequisites to effectively utilize the palo alto cortex xpanse connector within swimlane turbine, ensure you have the following cortex custom authentication with the following parameters fqdn the fully qualified domain name for the api endpoint api key your unique authentication key for accessing the cortex xpanse api api key id the identifier associated with your api key capabilities this connector provides the following capabilities create user defined ip range get alerts get asset details get business units get extra incident data get incidents remove assets update alerts upload assets update asset annotation update an incident create user defined ip range define an ip address range and assign a business unit (bu) or ip address tag (ipr) to that range cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/create user defined ip range get alerts get a single alert or list of alerts with multiple events cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/get alerts get asset details get asset details according to the asset id cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/get asset details get business units fetches business unit information for all or a subset of the business units in your cortex xpanse tenant cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/get business units get extra incident data get extra data fields for a specific incident including alerts and key artifacts cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/get extra incident data get incidents get details for a single incident or a list of incidents filtered by a list of severity or creation time cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/get incidents remove assets remove certificates, domains and ipv4 address ranges from your inventory cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/remove assets update alerts update one or more alerts cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/update alerts upload assets upload domains and ipv4 address ranges to your inventory cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/upload assets update asset annotation adds an annotation to an asset or ip range cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/update asset annotation update an incident update one or more fields of a specific incident cortex xpanse documentation for this action can be found here https //docs cortex paloaltonetworks com/r/cortex xpanse rest api/update an incident configurations palo alto cortex xpanse authentication palo alto cortex xpanse authenticates using api key and api key id configuration parameters parameter description type required fqdn the fqdn is a unique host and domain name associated with each tenant string required api key the api key is your unique identifier string required api key id the api key id is your unique token used to authenticate the api key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions create user defined ip range create a user defined ip range in palo alto cortex xpanse and assign it to a specific business unit or tag endpoint url /v1/assets/create user defined ip range method post input argument name type required description request data object optional request body for creating a user defined ip range startip string optional first ip address of the range endip string optional ending ip address of the range cidrip string optional ip range in cidr notation butagids array optional list of business unit tag ids that will be applied to the ip range iprtagids array optional list of ip range tag ids (ipr) that will be applied to the ip range shouldreplace boolean optional boolean denoting whether to replace all previously applied business units on overlapping ranges output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply user defined ip range string output field user defined ip range example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get alerts obtain a specific alert or a collection of alerts from palo alto cortex xpanse, utilizing the provided request data endpoint url /v2/alerts/get alerts multi events method post input argument name type required description request data object required request body for getting alerts search from number required an integer representing the starting offset within the query result set from which you want alerts returned next page token string required use string to page token into the next request to paginate the next set of data filters array required an array of filter fields field string required identifies the alert fields the filter is matching value object required value that this filter must match the contents of this field will differ based on the field operator string required string that identifies the comparison operator you want to use for this filter sort object required identifies the sort order for the result set field string required can either be severity or creation time keyword string required the sort order for the field can either be asc or desc search to number optional an integer representing the end offset within the result set after which you do not want alerts returned use page token boolean required a boolean value to paginate the response data output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation alerts array output field alerts category string output field category project string output field project cloud provider string unique identifier resource sub type string type of the resource resource type string type of the resource action country array output field action country description string output field description events string output field events event type string type of the resource is whitelisted boolean output field is whitelisted image name string name of the resource action local ip string output field action local ip action local port string output field action local port mitre tactic id and name array unique identifier mitre technique id and name array unique identifier action external hostname string name of the resource action remote ip array output field action remote ip action remote port array output field action remote port matching service rule id string unique identifier example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get all assets retrieve a comprehensive or filtered list of assets from palo alto cortex xpanse using specified request data endpoint url /v1/assets/get assets internet exposure method post input argument name type required description request data object required a dictionary containing the api request fields an empty dictionary returns all results search from number optional parameter for get all assets next page token string optional a token used to retrieve the next page of results filters array optional an array of filter fields field string required identifies the assetss field the filter is matching case sensitive value object required value depends on the filter field used operator string required identifies the comparison operator you want to use for this filter sort object optional identifies the sort order for the result set field string required the asset field by which to sort results keyword string required the sort order search to number optional an integer representing the start offset index of results use page token boolean optional boolean indicating whether to use pagination for the results output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation assets internet exposure array output field assets internet exposure agent id string unique identifier annotation string output field annotation asm ids array unique identifier asm va score number score value asset explainers array output field asset explainers asset type string type of the resource aws cloud tags array output field aws cloud tags azure cloud tags array output field azure cloud tags business units array output field business units 0 object output field 0 creation time number time value family string output field family family alias string output field family alias id string unique identifier is active number output field is active name string name of the resource parent id string unique identifier update time number time value certificate algorithm string output field certificate algorithm example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get all owned ip ranges retrieve a list of owned ip address ranges associated with specific business units and organization handles in palo alto cortex xpanse endpoint url /v1/assets/get external ip address ranges method post input argument name type required description request data object required a dictionary containing the api request fields an empty dictionary returns all results search from number optional the starting index from which to return results next page token string optional a token to retrieve the next page of results filters array optional an array of filter fields field string required identifies the external ip ranges field the filter is matching value string required value depends on the filter field used operator string required identifies the comparison operator you want to use for this filter sort object optional a dictionary containing the sort field and keyword field string required the field by which to sort the results keyword string required the sort order, either ascending (asc) or descending (desc) search to number optional parameter for get all owned ip ranges use page token boolean optional boolean indicating whether to use pagination for the results output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation external ip address ranges array output field external ip address ranges range id string unique identifier first ip string output field first ip last ip string output field last ip ips count number count value active responsive ips count number count value date added number output field date added organization handles array output field organization handles ipaddress version number output field ipaddress version tags array output field tags first ipv6 string output field first ipv6 last ipv6 string output field last ipv6 annotation string output field annotation has bu overrides boolean unique identifier next page token string output field next page token example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get all services retrieves a comprehensive or filtered list of all external services from palo alto cortex xpanse using specified request data endpoint url /v1/assets/get external services method post input argument name type required description request data object required a dictionary containing the api request fields search from number optional an integer representing the start offset index of results next page token string optional a token to retrieve the next page of results vulnerability test results boolean optional includes vulnerability test results from the last 14 days for each service in the response filters array optional an array of filter fields field string required identifies the external service field the filter is matching value object required value depends on the filter field used operator string required identifies the comparison operator you want to use for this filter sort object optional sorts the results by the specified field and order field string required the field to sort by keyword string required the sort order, either 'asc' for ascending or 'desc' for descending search to number optional an integer representing the start offset index of results use page token boolean optional boolean indicating whether to use pagination for the results output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation external services array output field external services service id string unique identifier service name string name of the resource service type string type of the resource ip address array output field ip address domain array output field domain file name string name of the resource file string output field file externally detected providers array unique identifier is active string output field is active first observed number output field first observed last observed number output field last observed port number output field port protocol string output field protocol active classifications array output field active classifications inactive classifications array output field inactive classifications file name string name of the resource file string output field file discovery type string type of the resource externally inferred vulnerability score string score value example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get all websites retrieve a comprehensive or filtered list of public facing websites from palo alto cortex xpanse, requiring request data endpoint url /v1/assets/get external websites method post input argument name type required description request data object required a dictionary containing the api request fields an empty dictionary returns all results search from number optional an integer representing the start offset index of results next page token string optional a string representing the page token from a previous response to retrieve the next page of results filters array optional parameter for get all websites field string required string that identifies the external service field the filter is matching value object required value depends on the filter field used for fields that support multiple values, provide an array of strings operator string required string that identifies the comparison operator you want to use for this filter sort object optional parameter for get all websites field string required the field by which to sort results keyword string required the direction in which to sort results search to number optional an integer representing the start offset index of results use page token boolean optional boolean indicating whether to use pagination for the results output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation websites array output field websites website id string unique identifier host string output field host protocol string output field protocol is active string output field is active site categories array output field site categories technology ids array unique identifier first observed number output field first observed last observed number output field last observed provider names array unique identifier ips array output field ips port number output field port active service ids array unique identifier http type string type of the resource third party script domains array output field third party script domains security assessments array output field security assessments name string name of the resource priority number output field priority score number score value securityassessmentdetails object output field securityassessmentdetails example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get asset details retrieve detailed information for a specified asset in palo alto cortex xpanse using the asset id provided in the request data endpoint url /v1/assets/get asset internet exposure method post input argument name type required description request data object required a dictionary containing the api request fields asm id list array required a list of string(s) representing the asset ids output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply details array output field details asm ids string unique identifier name string name of the resource type string type of the resource last observed number output field last observed first observed number output field first observed externally detected providers array unique identifier created number output field created ips array output field ips ip number output field ip ipv6 string output field ipv6 protocol string output field protocol provider string unique identifier geolocation object output field geolocation latitude number output field latitude longitude number output field longitude countrycode string output field countrycode city string output field city regioncode string output field regioncode timezone string output field timezone activitystatus string status value lastobserved number output field lastobserved example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get assets last assessment retrieve the last assessment time and status for assets in palo alto cortex xpanse, requiring request data endpoint url /v1/assets/get assets internet exposure/last external assessment method post input argument name type required description request data string required an empty dictionary returns the time and status of the last websites assessment output parameter type description status code number http status code of the response reason string response reason phrase last external assessment object output field last external assessment status boolean status value time string time value example \[ { "status code" 200, "reason" "ok", "json body" { "last external assessment" {} } } ] get business units retrieves information for all or specific business units within your palo alto cortex xpanse tenant endpoint url /v1/assets/get business units method post input argument name type required description request data object optional a dictionary containing the api request fields an empty dictionary returns all results filters array required an array of filter fields field string required identifies the business unit field the filter is matching operator string required identifies the comparison operator you want to use for this filter value string required value depends on the filter field used use page token boolean optional boolean indicating whether to use pagination for the results next page token string optional token to retrieve the next page of results if pagination is enabled output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation business units array output field business units business unit id string unique identifier business unit name string name of the resource parent id string unique identifier example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get extra incident data retrieve additional data fields for a specified incident, encompassing alerts and key artifacts in palo alto cortex xpanse endpoint url /v1/incidents/get incident extra data method post input argument name type required description request data object required a dictionary containing the api request fields alerts limit number optional the maximum number of related alerts in the incident that you want to retrieve incident id string required the id of the incident for which you want to retrieve extra data output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply incident object unique identifier incident id string unique identifier is blocked boolean output field is blocked incident name string unique identifier creation time number time value modification time number time value detection time number time value status string status value severity string output field severity description string output field description assigned user mail string output field assigned user mail assigned user pretty name string name of the resource alert count number count value low severity alert count number count value med severity alert count number count value high severity alert count number count value critical severity alert count number count value user count number count value host count number count value notes string output field notes resolve comment string output field resolve comment resolved timestamp number output field resolved timestamp example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get incidents retrieve detailed information for a single incident or multiple incidents filtered by severity or creation time in palo alto cortex xpanse endpoint url /v1/incidents/get incidents method post input argument name type required description request data object required a dictionary containing the api request fields search from number optional integer representing the starting offset within the query result set from which you want incidents returned filters array required array of filter fields field string required identifies the incident field the filter is matching value object required value that this filter must match the content of this field will differ depending on the field operator string required identifies the comparison operator you want to use for this filter sort object optional identifies the sort order for the results field string optional field to sort by keyword string optional sort order, either asc or desc search to number optional integer representing the end offset within the result set after which you do not want incidents returned output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply total count number count value result count number result of the operation incidents array unique identifier incident id string unique identifier is blocked boolean output field is blocked incident name string unique identifier creation time number time value modification time number time value detection time number time value status string status value severity string output field severity description string output field description assigned user mail string output field assigned user mail assigned user pretty name string name of the resource alert count number count value low severity alert count number count value med severity alert count number count value high severity alert count number count value critical severity alert count number count value user count number count value host count number count value notes string output field notes example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get ip address ranges last assessment retrieve the last assessment time and status for ip address ranges in palo alto cortex xpanse, requiring request data endpoint url /v1/assets/get external ip address ranges/last external assessment method post input argument name type required description request data string required an empty dictionary returns the time and status of the last websites assessment output parameter type description status code number http status code of the response reason string response reason phrase last external assessment object output field last external assessment status boolean status value time string time value example \[ { "status code" 200, "reason" "ok", "json body" { "last external assessment" {} } } ] get owned ip range details retrieve details for owned external ip address ranges using specified range ids in palo alto cortex xpanse endpoint url /v1/assets/get external ip address range method post input argument name type required description request data object required a dictionary containing the api request fields range id list array required a string representing the range id for which you want to get the details output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply details array output field details range id string unique identifier first ip string output field first ip last ip string output field last ip ips count number count value active responsive ips count number count value date added number output field date added organization handles array output field organization handles details object output field details networkrecords array output field networkrecords firstip string output field firstip firstipv6 string output field firstipv6 handle string output field handle lastchanged number output field lastchanged lastip string output field lastip lastipv6 string output field lastipv6 name string name of the resource organizationrecords array output field organizationrecords remarks string output field remarks whoisserver string output field whoisserver explainers array output field explainers ipaddress version number output field ipaddress version example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get service details retrieve detailed information for a specific service in palo alto cortex xpanse using the service id provided in the request data endpoint url /v1/assets/get external service method post input argument name type required description request data object required a dictionary containing the api request fields service id list array required a list of one or more service ids to retrieve details for output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply details array output field details service id string unique identifier service name string name of the resource service type string type of the resource ip address array output field ip address domain array output field domain externally detected providers array unique identifier is active string output field is active first observed number output field first observed last observed number output field last observed port number output field port protocol string output field protocol active classifications array output field active classifications inactive classifications array output field inactive classifications discovery type string type of the resource externally inferred vulnerability score number score value externally inferred cves array output field externally inferred cves details object output field details servicekey string output field servicekey servicekeytype string type of the resource providerdetails array unique identifier name string name of the resource example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get services last assessment retrieves the last assessment time and status for services data in palo alto cortex xpanse, requiring request data in json body endpoint url /v1/assets/get external services/last external assessment method post input argument name type required description request data string required an empty dictionary returns the time and status of the last websites assessment output parameter type description status code number http status code of the response reason string response reason phrase last external assessment object output field last external assessment status boolean status value time string time value example \[ { "status code" 200, "reason" "ok", "json body" { "last external assessment" {} } } ] get website details retrieve detailed information about specific websites using their ids in palo alto cortex xpanse endpoint url /v1/assets/get external website method post input argument name type required description request data object required a dictionary containing the api request fields website id list array required a string representing the website id you want to get details for limit is 20 website ids output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply details array output field details website id string unique identifier host string output field host protocol string output field protocol is active string output field is active site categories array output field site categories technology ids array unique identifier first observed number output field first observed last observed number output field last observed provider names array unique identifier ips array output field ips port number output field port active service ids array unique identifier http type string type of the resource security assessments array output field security assessments name string name of the resource priority number output field priority score number score value securityassessmentdetails object output field securityassessmentdetails pages array output field pages description string output field description rootpagehttpstatuscode string status value example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] get websites last assessment retrieve the latest assessment time and status for websites in palo alto cortex xpanse, requiring request data endpoint url /v1/assets/get external websites/last external assessment method post input argument name type required description request data string required an empty dictionary returns the time and status of the last websites assessment output parameter type description status code number http status code of the response reason string response reason phrase last external assessment object output field last external assessment status boolean status value time string time value example \[ { "status code" 200, "reason" "ok", "json body" { "last external assessment" {} } } ] remove alerts remove certificates, domains, and ipv4 address ranges from your palo alto cortex xpanse inventory endpoint url /public api/v1/asm management/remove asm data method post input argument name type required description data body object optional data body headers object optional request headers remove assets removes specified certificates, domains, and ipv4 address ranges from the palo alto cortex xpanse inventory endpoint url /v1/asm management/remove asm data method post input argument name type required description request data object required a dictionary containing the api request fields asset type string required the type of asset being removed asset identifiers array required a list of one or more assets you want to add to the inventory output parameter type description status code number http status code of the response reason string response reason phrase reply string output field reply example \[ { "status code" 200, "reason" "ok", "json body" { "reply" "successfully removed assets " } } ] update alerts update one or more alerts in palo alto cortex xpanse using specified request data endpoint url /v1/alerts/update alerts method post input argument name type required description request data object required a dictionary containing the api request fields an empty dictionary returns all results alert id list array optional a list of alert ids to update update data object optional a dictionary containing the fields to update for the specified alerts severity string optional the severity level to set for the alerts status string optional the status to set for the alerts comment string optional a comment to add to the alerts output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply alerts ids array unique identifier example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] update an incident updates specific fields of an incident in palo alto cortex xpanse using the provided request data endpoint url /v1/incidents/update incident method post input argument name type required description request data object required response data incident id string optional unique identifier update data object required response data assigned user mail string required updated email address of the incident assignee comment object required add a comment to the incident comment action string required action to perform on the comment value string required the content of the comment to be added assigned user pretty name string required updated full name of the incident assignee manual severity string required administrator defined severity status string required updated incident status resolve comment string required descriptive comment explaining the incident change output parameter type description status code number http status code of the response reason string response reason phrase reply boolean output field reply warnings array output field warnings example \[ { "status code" 200, "reason" "ok", "json body" { "reply" false, "warnings" \[] } } ] update asset annotation adds an annotation to a specified asset or ip range in palo alto cortex xpanse using the provided request data endpoint url /v1/assets/assets internet exposure/annotation method post input argument name type required description request data object required response data assets array required parameter for update asset annotation annotation string required annotation text entity type string required type of the entity being annotated entity id string required unique identifier for the entity being annotated should append boolean optional boolean indicating whether to append the annotation to existing annotations or replace them output parameter type description status code number http status code of the response reason string response reason phrase reply string output field reply example \[ { "status code" 200, "reason" "ok", "json body" { "reply" "reply example" } } ] upload assets upload domains and ipv4 address ranges to your palo alto cortex xpanse inventory using the provided request data endpoint url /v1/asm management/upload asm data method post input argument name type required description request data object required a dictionary containing the api request fields request type string required indicates that you want to add new assets to your inventory asset type string required the type of asset being added asset identifiers array required list of assets to be uploaded business units array required one or more business unit ids or business unit names to which the uploaded assets will be assigned output parameter type description status code number http status code of the response reason string response reason phrase reply object output field reply asset names array name of the resource errors array error message if any example \[ { "status code" 200, "reason" "ok", "json body" { "reply" {} } } ] notes get your cortex xpanse api key in cortex xpanse, navigate to settings & info > settings > integrations > api keys select + new key choose the type of api key you want to generate based on your desired security level advanced or standard the advanced api key hashes the key using a nonce, a random string, and a timestamp to prevent replay attacks curl does not support this but is suitable with scripts use the example script to create the advanced api authentication token if you want to define a time limit on the api key authentication, mark enable expiration date and select the expiration date and time navigate to settings & info > settings > integrations > api keys to track the expiration time field for each api key in addition, cortex xsoar displays an api key expiration notification in the notification center one week and one day prior to the defined expiration date provide a comment that describes the purpose for the api key, if desired select the desired level of access for this key you can select existing roles , or you can select custom to set the permissions on a more granular level be sure to select a role with view/edit access for the public api use the predefined instance administrator role or a create a custom role with public api permission roles are described in the manage roles section of the cortex xpanse user guide generate the api key copy the api key, and then click done this value represents your unique authorization {key}