XDR Quickstart

GitHub page TypeScript JavaScript

The following guide will walk you through installing @paloaltonetworks/pan-cortex-xdr, a simple JavaScript / TypeScript library implementing the Cortex XDR REST API endpoints.

Overview

The Cortex XDR REST API is simple, well organized and ease to consume. Most integrations can be achieved with basic cURL-based Bash scripts using API Keys of the basic security level.

The @paloaltonetworks/pan-cortex-xdr NodeJS package, besides implementing a 1:1 mapping between API Endpoints and functions, can help a first time Cortex XDR developer with:

  • implementation of the advanced security level API Key nonce process
  • auto-completion and type safety if using a TypeScript editor

Installing with npm

Get the module from the public NPM repository

npm i @paloaltonetworks/pan-cortex-xdr

Installing from source

In case you need to play with a pre-release version of the package then you can add dependencies from the GitHub public repo.

npm i https://github.com/PaloAltoNetworks/pan-cortex-xdr-nodejs.git

Source code is written in TypeScript and the build process produces type definition files which means you can leverage strongly type and code auto-complete features.

import * as xdr from "@paloaltonetworks/pan-cortex-xdr";

Introduction to the XdrApi object

The main component of the @paloaltonetworks/pan-cortex-xdr library is the XdrApi object that provides namespaces to reach Cortex XDR API endpoints:

  • IncidentApi: to deal with incidents and alerts
  • AlertApi: to push alerts from third party sources
  • EndpointApi: to interface with endpoints
  • DeviceControlApi: to manage device control features
  • HashExceptionApi: to manage file hash exceptions
  • AuditsApi: to retrieve audit reports
  • DistributionsApi: to manage endpoint package distributions

A quick reference to functions is each namespace is availabe in the XdrApi Object Reference document

Geting Started

Just obtain a XdrApi object by calling the top level createXdrApi() function export.

Passing API KEY material from environmental variables

Set the following environmental variables before calling createXdrApi()

  • PAN_API_KEY_ID: API KEY identifier
  • PAN_XDR_FQDN: FQDN of the XDR PRO instance
  • either PAN_ADV_API_KEY or PAN_BASIC_API_KEY based on the type of API KEY being used

Passing API KEY material explicitly

Use an object with the following attributes as the first argument to createXdrApi(data)

  • apiKey: string
  • apiKeyId: string
  • isAdvancedKey: boolean
  • xdrBaseFqdn: string

Code example

TypeScript code example

import * as xdr from '@paloaltonetworks/pan-cortex-xdr'
const apiKey = '<your Cortex API Key>'
const apiKeyId = '<your Cortex API Key Identifier>'
const xdrBaseFqdn = '<your tenant identifier>.xdr.us.paloaltonetworks.com'
const xdrapi = xdr.createXdrApi({
apiKey,
apiKeyId,
xdrBaseFqdn,
})
/**
* Dumps to console all incidents generated by the 'XDR Analytics BIOC' source
* @param xdrapi XdrApi object to use
*/
async function main(xdrapi: xdr.XdrApi): void {
const response = await xdrapi.incident.get([{
field: 'alert_sources',
operator: 'in',
value: ['XDR Analytics BIOC']
}])
console.log(JSON.stringify(response, undefined, 1))
}
main(xdrapi).then(console.log, console.error).finally(xdrapi.close)

Debugging

@paloaltonetworks/pan-cortex-xdr features a console logger that can be adjusted to be more verbose. By default it dumps messages of Info or higher severity.

To debug your application set the log level to debug.

import { setLogLevel, logLevel } from '@paloaltonetworks/pan-cortex-xdr'
setLogLevel(logLevel.DEBUG)

Similarly, you can turn console logging completely by setting the log level to NONE

setLogLevel(logLevel.NONE)
Last updated on by Xavier Homs