README
¶
Basic implementation of a XDR client for parsed alert ingestion API
This package provides basic types to interface with the parsed alert ingestion API provided by Palo Alto Networks Cortex XDR. It can be used to stitch third party alerts (i.e. logs from closed systems) with the incident management provided by the XDR application.
Documentation
¶
Overview ¶
Package xdrclient provides code to implement a client to the ingestion parser alerts API in XDR.
The main component is the Client type that implements a client to the Cortex XDR insert parsed alerts API. A convenience method is provided to configure and initialize a client from environmental variables.
client := NewClientFromEnv()
NewXDRClientFromEnv will throw fatal errors if the mandatory environmental variables are not found. They are:
API_KEY XDR API Key (Advanced) API_KEY_ID The XDR API Key identifier (its sequence number) FQDN Full Qualified Domain Name of the corresponding XDR Instance (i.e. myxdr.xdr.us.paloaltonetworks.com)
Another way to create the client is by initializing the struct and calling its Init() method
client := Client{
APIKey: "<my API KEY>",
APIKeyID: "37",
FQDN: "myxdr.xdr.us.paloaltonetworks.com",
}
if err := client.Init(); err != nil {
log.Fatal(err)
}
The client exposes the Send(alert *xdrgateway.Alert) (err error) and SendMulti(alert *xdrgateway.Alert) (err error) methods to push alerts into XDR.
Index ¶
Examples ¶
Constants ¶
const ( // SeverityInfo is the string XDR ingestion API expects for info-level alerts SeverityInfo Severities = iota // SeverityLow is the string XDR ingestion API expects for low-level alerts SeverityLow // SeverityMedium is the string XDR ingestion API expects for medium-level alerts SeverityMedium // SeverityHigh is the string XDR ingestion API expects for high-level alerts SeverityHigh // SeverityUnknown is the string XDR ingestion API expects for unknown-level alerts SeverityUnknown // ActionReported is the string XDR ingestion API expects for alerts that have just being reported ActionReported Actions = iota // ActionBlocked is the string XDR ingestion API expects for alerts that have been blocked at the reporting device ActionBlocked )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Alert ¶
type Alert struct {
// Product is a value that defines the product
Product string
// Vendor is a value that defines the product
Vendor string
// LocalIP is the value for the source IP address.
// It is highly recommended to use the method NetData(srcIP string, dstIP string, srcPort uint16, dstPort uint16) (err error)
// to field this field as well as the rest of network-related alert properties. The method will enforce IPv4/IPv6 address
// format validity
LocalIP string
// LocalPort is the value for the source port
LocalPort uint16
// RemoteIP is the value of the destination IP address
RemoteIP string
// RemotePort is the value for the destination port
RemotePort uint16
// Timestamp is the value representing the epoch of the time the alert occurred in milliseconds
Timestamp int64
// Severity is the value of alert severity. Use the corresponding code from the Severities enum
Severity Severities
// AlertName defines the alert name
AlertName string
// AlertDescription defines the alert description
AlertDescription string
// Action defines the alert action taken by the source. Use the corresponding code from the Actions enum
Action Actions
}
Alert is a representation of Cortex XDR alert fields. Fields are exposed for convenience but developers are encourages to use the provided methods to fill them in order to perform format validation (to avoid upstream rejects by the API)
func NewAlert ¶
func NewAlert(severity Severities, timestamp int64) (alert *Alert)
NewAlert allocates memory for a new Alert struct
func NewHighAlert ¶
NewHighAlert allocates memory for a new Alert struct with severity High
func NewLowAlert ¶
NewLowAlert allocates memory for a new Alert struct with severity Low
type Client ¶
type Client struct {
// APIKey XDR API Key (only Advanced supported)
APIKey string
// APIKeyID XDR API Key ID
APIKeyID string
// FQDN XDR instance to target
FQDN string
Stats *Stats
// Debug turn on client verbosity
Debug bool
// contains filtered or unexported fields
}
Client provides a XDR alert API client implementation for the insert_parsed_alerts endpoint users must call Init() before any other method
Example ¶
Example that creates a Client explicitly and pushes multiple alerts in a single update. Notice the client do not enforce the maximum number of alerts in a single update at it might be rejected at the XDR side as it do not accept more than 60 alerts in a single update
client := Client{
APIKey: "O4Bw...wEX",
APIKeyID: "37",
FQDN: "myxdr.xdr.us.paloaltonetworks.com",
}
if err := client.Init(); err != nil {
log.Fatal(err)
}
alert := []*Alert{
{
LocalIP: "15.14.13.12",
LocalPort: 11,
RemoteIP: "10.9.8.7",
RemotePort: 6,
Timestamp: time.Now().Unix() / int64(time.Millisecond),
Severity: SeverityHigh,
Action: ActionBlocked,
AlertName: "Unit Test",
AlertDescription: "High-Block alert from Unit Testing",
},
{
LocalIP: "12.13.14.15",
LocalPort: 11,
RemoteIP: "7.8.9.10",
RemotePort: 6,
Timestamp: time.Now().Unix() / int64(time.Millisecond),
Severity: SeverityHigh,
Action: ActionBlocked,
AlertName: "Unit Test",
AlertDescription: "High-Block alert from Unit Testing",
},
}
if err := client.SendMulti(alert); err != nil {
log.Fatal(err)
}
Output:
func NewClientFromEnv ¶
func NewClientFromEnv() (client *Client)
NewClientFromEnv creates a new XDRClient instance reading data from environmental variables
Required variables:
- API_KEY Key generated in the corresponding Cortex XDR instance (only Advanced supported)
- API_KEY_ID identifier (sequence number) of the API_KEY
- FQDN Full Qualified Domain Name of the corresponding XDR Instance (i.e. myxdr.xdr.us.paloaltonetworks.com)
Example ¶
Example that creates a Client from environmentala variables to send an alert. Notice NewClientFromEnv() will throw a fatal error if the mandatory variables are not found
client := NewClientFromEnv()
alert := &Alert{
LocalIP: "15.14.13.12",
LocalPort: 11,
RemoteIP: "10.9.8.7",
RemotePort: 6,
Timestamp: time.Now().Unix() / int64(time.Millisecond),
Severity: SeverityHigh,
Action: ActionBlocked,
AlertName: "Unit Test",
AlertDescription: "High-Block alert from Unit Testing",
}
if err := client.Send(alert); err != nil {
log.Fatal(err)
}
Output:
type Severities ¶
type Severities int
Severities is an enumeration of all supported Cortex XDR alert severities
type Stats ¶
type Stats struct {
// POSTSend amount of successful POST's to the XDR alert ingestion API (status == 200 OK)
POSTSend uint64
// POSTFailures amount of unsuccessful POST's to the XDR alert ingestion API (status ""= 200 OK)
POSTFailures uint64
}
Stats provides counters for the XDR API client
Source Files