Cortex Xpanse API

openapi: 3.1.0
info:
  title: Palo Alto Networks Cortex Xpanse REST API
  description: >-
    REST API for the Cortex Xpanse attack surface management (ASM) platform.
    Provides programmatic access to internet-exposed asset discovery, attack
    surface incident management, attack surface rules, exposed service
    enumeration, IP range ownership, and audit logs. Cortex Xpanse
    continuously discovers and monitors internet-facing infrastructure to
    identify exposures before attackers do. Authentication uses a custom
    HMAC-SHA256 scheme identical to Cortex XDR: include x-xdr-auth-id,
    x-xdr-nonce, x-xdr-timestamp, and x-xdr-hmac-v2 headers on every
    request. Role-based access control (RBAC) API key pairs determine which
    data and operations are accessible. All endpoints use POST with JSON
    request bodies.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/cortex/docs/xpanse/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api-{fqdn}/public_api/v1
  description: Cortex Xpanse tenant API endpoint.
  variables:
    fqdn:
      description: >-
        Tenant FQDN from the Xpanse settings page (e.g.,
        example.xpanse.paloaltonetworks.com).
      default: example.xpanse.paloaltonetworks.com
security:
- xpanseAuth: []
tags:
- name: Assets
  description: Internet-exposed asset discovery and enumeration.
- name: AttackSurfaceRules
  description: Attack surface rule configuration and management.
- name: Audit
  description: Audit and management log retrieval.
- name: Incidents
  description: Attack surface incident management.
- name: IPRanges
  description: Owned IP range management.
paths:
  /assets/get_assets_internet_exposure:
    post:
      operationId: getAssetsInternetExposure
      summary: Palo Alto Networks Get Internet-exposed Assets
      description: >-
        Returns a list of assets with internet exposure discovered by Xpanse.
        Assets include servers, cloud instances, network devices, and any
        internet-facing infrastructure. Supports filtering by asset type,
        business unit, tags, and exposure classification. Use this endpoint
        to inventory all externally visible infrastructure.
      tags:
      - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                      description: Filter criteria for asset list.
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAssetsInternetExposureRequestExample:
                summary: Default getAssetsInternetExposure request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: contains
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Internet-exposed assets returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      assets_internet_exposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssetInternetExposure'
              examples:
                GetAssetsInternetExposure200Example:
                  summary: Default getAssetsInternetExposure 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 214
                      result_count: 275
                      assets_internet_exposure:
                      - asm_id_list: &id007
                        - '594748'
                        asset_name: Branch Policy 81
                        asset_type: UNMANAGED_NETWORK_DEVICE
                        ip_address: &id008
                        - 10.131.211.150
                        - 10.237.60.87
                        domain: &id009
                        - example-domain_item
                        ipv6_address: &id010
                        - 10.147.211.139
                        cloud_id: '583636'
                        cloud_provider: Azure
                        externally_detected_providers: &id011
                        - example-externally_detected_providers_item
                        business_units: &id012
                        - example-business_units_item
                        tags: &id013
                        - key: example-key
                          value: example-value
                        - key: example-key
                          value: example-value
                        created: 919
                        last_observed: 958
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /assets/get_asset_internet_exposure:
    post:
      operationId: getAssetInternetExposure
      summary: Palo Alto Networks Get Single Asset Details
      description: >-
        Returns detailed information about a specific internet-exposed asset
        identified by its asset ID. Includes all services, certificates,
        observations, and associated business context data.
      tags:
      - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - asm_id_list
                  properties:
                    asm_id_list:
                      type: array
                      items:
                        type: string
                      description: List of asset IDs to retrieve details for.
            examples:
              GetAssetInternetExposureRequestExample:
                summary: Default getAssetInternetExposure request
                x-microcks-default: true
                value:
                  request_data:
                    asm_id_list:
                    - '595684'
      responses:
        '200':
          description: Asset details returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      assets_internet_exposure:
                        type: array
                        items:
                          $ref: '#/components/schemas/AssetInternetExposureDetail'
              examples:
                GetAssetInternetExposure200Example:
                  summary: Default getAssetInternetExposure 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 12
                      result_count: 106
                      assets_internet_exposure:
                      - example-assets_internet_exposure_item
                      - example-assets_internet_exposure_item
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incident_management/get_incidents:
    post:
      operationId: getIncidents
      summary: Palo Alto Networks Get Attack Surface Incidents
      description: >-
        Returns a list of attack surface incidents. Xpanse incidents represent
        confirmed exposures that require remediation such as unintended services,
        misconfigured certificates, or shadow IT. Supports filtering by status,
        severity, type, and assignee.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetIncidentsRequestExample:
                summary: Default getIncidents request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: contains
                      value: example-value
                    - field: example-field
                      operator: contains
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Attack surface incidents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      incidents:
                        type: array
                        items:
                          $ref: '#/components/schemas/AsmIncident'
              examples:
                GetIncidents200Example:
                  summary: Default getIncidents 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 723
                      result_count: 282
                      incidents:
                      - incident_id: '593269'
                        incident_name: Production Agent 40
                        status: resolved_no_risk
                        severity: informational
                        incident_type: &id001
                        - standard
                        assigned_user_mail: [email protected]
                        assigned_user_pretty_name: John Smith
                        alert_count: 939
                        description: Alert threat detected Security incident monitoring activity incident.
                        creation_time: 1704469877477
                        modification_time: 1740534005374
                        resolved_by: example-resolved_by
                        resolve_comment: Rule on firewall violation traffic violation Security detected.
                        tags: &id002
                        - key: example-key
                          value: example-value
                      - incident_id: '593269'
                        incident_name: Production Agent 40
                        status: resolved_no_risk
                        severity: informational
                        incident_type: *id001
                        assigned_user_mail: [email protected]
                        assigned_user_pretty_name: John Smith
                        alert_count: 939
                        description: Alert threat detected Security incident monitoring activity incident.
                        creation_time: 1704469877477
                        modification_time: 1740534005374
                        resolved_by: example-resolved_by
                        resolve_comment: Rule on firewall violation traffic violation Security detected.
                        tags: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /incident_management/update_incident:
    post:
      operationId: updateIncident
      summary: Palo Alto Networks Update Attack Surface Incident
      description: >-
        Updates the status, assignee, severity, or resolution details of an
        attack surface incident. Use this endpoint to track remediation
        progress and close incidents after the exposure has been addressed.
      tags:
      - Incidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - incident_id
                  properties:
                    incident_id:
                      type: string
                      description: Unique identifier of the attack surface incident.
                    status:
                      type: string
                      enum:
                      - new
                      - under_investigation
                      - resolved
                      - resolved_no_risk
                      - resolved_risk_accepted
                      - resolved_contested_asset
                      - resolved_remediated_automatically
                    assigned_user_mail:
                      type: string
                      description: Email of the user to assign the incident to.
                    assigned_user_pretty_name:
                      type: string
                    severity:
                      type: string
                      enum:
                      - critical
                      - high
                      - medium
                      - low
                      - informational
                    resolve_comment:
                      type: string
                      description: Resolution comment when closing an incident.
                    comment:
                      type: string
                      description: Comment to add to the incident.
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  request_data:
                    incident_id: '742866'
                    status: resolved_no_risk
                    assigned_user_mail: [email protected]
                    assigned_user_pretty_name: John Kumar
                    severity: low
                    resolve_comment: Endpoint incident malware on configured on incident policy endpoint.
                    comment: Security incident rule malware suspicious detected incident traffic violation configured.
      responses:
        '200':
          description: Attack surface incident updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: boolean
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    reply: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attack_surface_rules/get_attack_surface_rules:
    post:
      operationId: getAttackSurfaceRules
      summary: Palo Alto Networks Get Attack Surface Rules
      description: >-
        Returns the configured attack surface rules. Attack surface rules define
        the criteria Xpanse uses to classify exposures as incidents, including
        service type, port, protocol, and risk classification logic. Rules can
        be enabled, disabled, or customized per business context.
      tags:
      - AttackSurfaceRules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAttackSurfaceRulesRequestExample:
                summary: Default getAttackSurfaceRules request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: contains
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Attack surface rules returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      attack_surface_rules:
                        type: array
                        items:
                          $ref: '#/components/schemas/AttackSurfaceRule'
              examples:
                GetAttackSurfaceRules200Example:
                  summary: Default getAttackSurfaceRules 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 281
                      result_count: 551
                      attack_surface_rules:
                      - attack_surface_rule_id: '791314'
                        attack_surface_rule_name: Production Policy 68
                        category: standard
                        description: Monitoring activity on rule malware Security policy violation configured activity applied violation.
                        remediation_guidance: example-remediation_guidance
                        enabled_status: OFF
                        severity: low
                        created: 981
                        modified: 233
                        release_status: BETA
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /attack_surface_rules/update_attack_surface_rule:
    post:
      operationId: updateAttackSurfaceRule
      summary: Palo Alto Networks Update Attack Surface Rule
      description: >-
        Updates the configuration of an attack surface rule, such as enabling
        or disabling it, changing its severity, or modifying the scope of
        assets it applies to.
      tags:
      - AttackSurfaceRules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - request_data
              properties:
                request_data:
                  type: object
                  required:
                  - attack_surface_rule_id
                  properties:
                    attack_surface_rule_id:
                      type: string
                      description: Unique identifier of the attack surface rule.
                    enabled_status:
                      type: string
                      enum:
                      - ON
                      - OFF
                    severity:
                      type: string
                      enum:
                      - critical
                      - high
                      - medium
                      - low
                      - informational
                    remediation_guidance:
                      type: string
                      description: Updated remediation guidance text.
            examples:
              UpdateAttackSurfaceRuleRequestExample:
                summary: Default updateAttackSurfaceRule request
                x-microcks-default: true
                value:
                  request_data:
                    attack_surface_rule_id: '160681'
                    enabled_status: OFF
                    severity: informational
                    remediation_guidance: example-remediation_guidance
      responses:
        '200':
          description: Attack surface rule updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: boolean
              examples:
                UpdateAttackSurfaceRule200Example:
                  summary: Default updateAttackSurfaceRule 200 response
                  x-microcks-default: true
                  value:
                    reply: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/get_services:
    post:
      operationId: getServices
      summary: Palo Alto Networks Get Exposed Services
      description: >-
        Returns a list of internet-exposed network services discovered by
        Xpanse. Services represent open ports and protocols observed on
        internet-facing assets. Supports filtering by service type, port,
        protocol, country, and associated asset.
      tags: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetServicesRequestExample:
                summary: Default getServices request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: contains
                      value: example-value
                    - field: example-field
                      operator: contains
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Exposed services returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      services:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExposedService'
              examples:
                GetServices200Example:
                  summary: Default getServices 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 543
                      result_count: 703
                      services:
                      - service_id: '336506'
                        service_name: Corporate Agent 50
                        service_type: NETWORKING
                        ip_address: &id003
                        - 10.239.5.194
                        domain: &id004
                        - example-domain_item
                        - example-domain_item
                        port: 278
                        protocol: TCP
                        provider: &id005
                        - example-provider_item
                        business_units: &id006
                        - example-business_units_item
                        - example-business_units_item
                        created: 966
                        last_observed: 356
                        is_active: Unconfirmed
                        discovery_type: DirectlyDiscovered
                      - service_id: '336506'
                        service_name: Corporate Agent 50
                        service_type: NETWORKING
                        ip_address: *id003
                        domain: *id004
                        port: 278
                        protocol: TCP
                        provider: *id005
                        business_units: *id006
                        created: 966
                        last_observed: 356
                        is_active: Unconfirmed
                        discovery_type: DirectlyDiscovered
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ip_range/get_owned_ip_ranges:
    post:
      operationId: getOwnedIpRanges
      summary: Palo Alto Networks Get Owned IP Ranges
      description: >-
        Returns the IP ranges registered as owned by the organization in
        Xpanse. Owned IP ranges define the scope of internet-facing
        infrastructure that Xpanse monitors for exposures. Includes both
        manually configured ranges and auto-discovered ranges attributed
        to the organization.
      tags:
      - IPRanges
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetOwnedIpRangesRequestExample:
                summary: Default getOwnedIpRanges request
                x-microcks-default: true
                value:
                  request_data:
                    filters:
                    - field: example-field
                      operator: contains
                      value: example-value
                    search_from: 0
                    search_to: 100
                    sort:
                      field: example-field
                      keyword: asc
      responses:
        '200':
          description: Owned IP ranges returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    type: object
                    properties:
                      total_count:
                        type: integer
                      result_count:
                        type: integer
                      owned_ip_ranges:
                        type: array
                        items:
                          $ref: '#/components/schemas/OwnedIpRange'
              examples:
                GetOwnedIpRanges200Example:
                  summary: Default getOwnedIpRanges 200 response
                  x-microcks-default: true
                  value:
                    reply:
                      total_count: 213
                      result_count: 881
                      owned_ip_ranges:
                      - range_id: '919843'
                        cidr: example-cidr
                        first_ip: example-first_ip
                        last_ip: example-last_ip
                        range_size: 365
                        business_units: &id014
                        - example-business_units_item
                        - example-business_units_item
                        attribution_reason: RIR
                        created: 408
                        modified: 724
                        tags: &id015
                        - key: example-key
                          value: example-value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /audit/get_audit_management_logs:
    post:
      operationId: getAuditManagementLogs
      summary: Palo Alto Networks Get Audit Management Logs
      description: >-
        Retrieves audit management logs recording administrative actions
        performed in the Xpanse console, including user logins, IP range
        modifications, rule configuration changes, and API key management.
      tags:
      - Audit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_data:
                  type: object
                  properties:
                    filters:
                      type: array
                      items:
                        $ref: '#/components/schemas/Filter'
                    search_from:
                      type: integer
                      default: 0
                    search_to:
                      type: integer
                      default: 100
                    sort:
                      $ref: '#/components/schemas/SortOrder'
            examples:
              GetAuditManagementLogsRe

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-cortex-xpanse-api-openapi-original.yml