proofpoint

README

go-proofpoint

Proofpoint API Client Library

Table of Contents

• Getting Started
• References

Getting Started

First, install ppcli:

go get -u github.com/greenpau/go-proofpoint/cmd/ppcli

Next, set environment variables for Proofpoint API Service Principal:

export PROOFPOINT_SERVICE_PRINCIPAL=8c5e8866-0062-4059-b2be-92707e4374da
export PROOFPOINT_PRINCIPAL_SECRET=f982025ecbaa8c42bec8b19c98c3ea7126241c130274cd06ac4f15cbd3ec5313737a425f

Alternatively, the settings could be passed in a configuration file. There are two options:

1. The ppcli.yaml should be located in $HOME/.config/ppcli or current directory
2. Pass the location via -config flag

---
service_principal: 8c5e8866-0062-4059-b2be-92707e4374da
principal_secret: f982025ecbaa8c42bec8b19c98c3ea7126241c130274cd06ac4f15cbd3ec5313737a425f

The following command fetches all events occured in the last 60 minutes from Proofpoint SIEM API:

ppcli -service-name siem -service-operation all -log-level debug

References

• Threat Insight Dashboard - API Documentation

Documentation

Index

• Constants
• type Click
• type Client
  • func NewClient(opts map[string]interface{}) (*Client, error)
  • func (c *Client) Close()
  • func (c *Client) GetData(serviceName, serviceOperation string, opts map[string]interface{}) ([]string, error)
  • func (c *Client) GetSiemAll(opts map[string]interface{}) ([]*Click, []*Message, error)
  • func (c *Client) GetSiemBlockedClicks(opts map[string]interface{}) ([]*Click, error)
  • func (c *Client) GetSiemBlockedMessages(opts map[string]interface{}) ([]*Message, error)
  • func (c *Client) GetSiemDeliveredMessages(opts map[string]interface{}) ([]*Message, error)
  • func (c *Client) GetSiemIssues(opts map[string]interface{}) ([]*Click, []*Message, error)
  • func (c *Client) GetSiemPermittedClicks(opts map[string]interface{}) ([]*Click, error)
  • func (c *Client) Info()
  • func (c *Client) SetHost(s string) error
  • func (c *Client) SetPort(p int) error
  • func (c *Client) SetPrincipalSecret(s string) error
  • func (c *Client) SetProtocol(s string) error
  • func (c *Client) SetServicePrincipal(s string) error
  • func (c *Client) SetValidateServerCertificate() error
• type Message
• type MessagePart
• type SiemResponse
• type Threat

Constants

const ReceiverDataLimit int64 = 1e6

ReceiverDataLimit is the limit of data in bytes the client will read from a server.

Types

type Click

type Click struct {
	Category string `json:"category,omitempty"`
	// Blocked clicks
	Blocked bool `json:"blocked,omitempty"`
	// Permitted clicks
	Permitted bool `json:"permitted,omitempty"`
	// The unique id of the click.
	ID string `json:"id,omitempty"`
	// The ID of the message within PPS. It can be used to identify the message in PPS and
	// is guaranteed to be unique.
	GUID string `json:"GUID,omitempty"`
	// An identifier for the campaign of which the threat is a member, if available
	// at the time of the query. Threats can be linked to campaigns even after these events are retrieved.
	CampaignID string `json:"campaignID,omitempty"`
	// The threat category of the malicious URL, e.g. Malware, Phish, Spam.
	Classification string `json:"classification,omitempty"`
	// The external IP address of the user who clicked on the link. If the user is behind a firewall
	// performing network address translation, the IP address of the firewall will be shown.
	ClickIPAddress string `json:"clickIP,omitempty"`
	// The time the user clicked on the URL.
	ClickTimestamp time.Time `json:"clickTime,omitempty"`
	// The email address of the recipient.
	RecipientEmailAddresses string `json:"recipient,omitempty"`
	// The email address of the sender. The user-part is hashed. The domain-part is cleartext.
	SenderEmailddress string `json:"sender,omitempty"`
	// The IP address of the sender.
	SenderIPAddress string `json:"senderIP,omitempty"`
	// The unique identifier associated with this threat. It can be used to query the forensics.
	// and campaign endpoints.
	ThreatID string `json:"threatID,omitempty"`
	// Proofpoint identified the URL as a threat at this time.
	ThreatTimestamp time.Time `json:"threatTime,omitempty"`
	// A link to the entry on the TAP Dashboard for the particular threat.
	ThreatURL string `json:"threatURL,omitempty"`
	// The current state of the threat, e.g. active, falsepositive, cleared.
	ThreatStatus string `json:"threatStatus,omitempty"`
	// The malicious URL which was clicked
	URL string `json:"url,omitempty"`
	// The User-Agent header from the clicker's HTTP request
	UserAgent string `json:"userAgent,omitempty"`
}

Click is a click to malicious URL.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an instance of Proofpoint API client.

func NewClient

func NewClient(opts map[string]interface{}) (*Client, error)

NewClient returns an instance of Client.

func (*Client) Close

func (c *Client) Close()

Close performs a cleanup associated with Client..

func (*Client) GetData

func (c *Client) GetData(serviceName, serviceOperation string, opts map[string]interface{}) ([]string, error)

GetData returns data by providing service name and operation, as well as other options.

func (*Client) GetSiemAll

func (c *Client) GetSiemAll(opts map[string]interface{}) ([]*Click, []*Message, error)

GetSiemAll fetches events for all clicks and messages relating to known threats within the specified time period.

func (*Client) GetSiemBlockedClicks

func (c *Client) GetSiemBlockedClicks(opts map[string]interface{}) ([]*Click, error)

GetSiemBlockedClicks fetches events for clicks to malicious URLs blocked in the specified time period.

func (*Client) GetSiemBlockedMessages

func (c *Client) GetSiemBlockedMessages(opts map[string]interface{}) ([]*Message, error)

GetSiemBlockedMessages fetches events for messages blocked in the specified time period which contained a known threat.

func (*Client) GetSiemDeliveredMessages

func (c *Client) GetSiemDeliveredMessages(opts map[string]interface{}) ([]*Message, error)

GetSiemDeliveredMessages fetches events for messages delivered in the specified time period which contained a known threat.

func (*Client) GetSiemIssues

func (c *Client) GetSiemIssues(opts map[string]interface{}) ([]*Click, []*Message, error)

GetSiemIssues fetches events for clicks to malicious URLs permitted and messages delivered containing a known attachment threat within the specified time period.

func (*Client) GetSiemPermittedClicks

func (c *Client) GetSiemPermittedClicks(opts map[string]interface{}) ([]*Click, error)

GetSiemPermittedClicks fetches events for clicks to malicious URLs permitted in the specified time period.

func (*Client) Info

func (c *Client) Info()

Info sends information about Client to the configured logger.

func (*Client) SetHost

func (c *Client) SetHost(s string) error

SetHost sets the target host for the API calls.

func (*Client) SetPort

func (c *Client) SetPort(p int) error

SetPort sets the port number for the API calls.

func (*Client) SetPrincipalSecret

func (c *Client) SetPrincipalSecret(s string) error

SetPrincipalSecret sets API Principal Secret.

func (*Client) SetProtocol

func (c *Client) SetProtocol(s string) error

SetProtocol sets the protocol for the API calls.

func (*Client) SetServicePrincipal

func (c *Client) SetServicePrincipal(s string) error

SetServicePrincipal sets API Service Principal.

func (*Client) SetValidateServerCertificate

func (c *Client) SetValidateServerCertificate() error

SetValidateServerCertificate instructs the client to enforce the validation of certificates and check certificate errors.

type Message

type Message struct {
	Category string `json:"category,omitempty"`
	// Blocked messages
	Blocked bool `json:"blocked,omitempty"`
	// Delivered messages
	Delivered bool `json:"delivered,omitempty"`
	// The unique id of the message.
	ID string `json:"id,omitempty"`
	// A list of email addresses contained within the CC: header, excluding friendly names.
	CarbonCopyHeaderAddresses []string `json:"ccAddresses,omitempty"`
	// The name of the PPS cluster which processed the message.
	ClusterName string `json:"cluster,omitempty"`
	// The rewrite status of the message. If value is 'true', all instances of URL
	// threats within the message were successfully rewritten. If the value is 'false',
	// at least one instance of the a threat URL was not rewritten. If the value is 'na',
	// the message did not contain any URL-based threats.
	CompletelyRewritten bool `json:"completelyRewritten,omitempty"`
	// The email address contained in the From: header, excluding friendly name.
	FromHeaderAddresses []string `json:"fromAddress,omitempty"`
	// The ID of the message within PPS. It can be used to identify the message in PPS and is guaranteed to be unique.
	GUID string `json:"GUID,omitempty"`
	// The full content of the From: header, including any friendly name.
	FromHeader string `json:"headerFrom,omitempty"`
	// If present, the full content of the Reply-To: header, including any friendly names.
	ReplyToHeader string `json:"headerReplyTo,omitempty"`
	// The impostor score of the message. Higher scores indicate higher certainty.
	ImpostorScore float64 `json:"impostorScore,omitempty"`
	// The malware score of the message. Higher scores indicate higher certainty.
	MalwareScore float64 `json:"malwareScore,omitempty"`
	// Message-ID extracted from the headers of the email message. It can be used to look
	// up the associated message in PPS and is not unique.
	MessageID string `json:"messageID,omitempty"`
	// A collection of MessagePart objects.
	MessageParts []*MessagePart `json:"messageParts,omitempty"`
	// The size in bytes of the message, including headers and attachments.
	MessageSize float64 `json:"messageSize,omitempty"`
	// When the message was delivered to the user or quarantined by PPS
	MessageTimestamp time.Time `json:"messageTime,omitempty"`
	// The list of PPS modules which processed the message.
	ModulesRun []string `json:"modulesRun,omitempty"`
	// The phish score of the message. Higher scores indicate higher certainty.
	PhishScore float64 `json:"phishScore,omitempty"`
	// The policy routes that the message matched during processing by PPS.
	PolicyRoutes []string `json:"policyRoutes,omitempty"`
	// The queue ID of the message within PPS. It can be used to identify
	// the message in PPS and is not unique.
	QID string `json:"QID,omitempty"`
	// The name of the folder which contains the quarantined message.
	// This appears only for messagesBlocked.
	QuarantineFolder string `json:"quarantineFolder,omitempty"`
	// The name of the rule which quarantined the message.
	// This appears only for messagesBlocked events.
	QuarantineRule string `json:"quarantineRule,omitempty"`
	// An array containing the email addresses of the SMTP (envelope) recipients
	RecipientEmailAddress []string `json:"recipient,omitempty"`
	// The email address contained in the Reply-To: header, excluding friendly name.
	ReplyToHeaderAddress []string `json:"replyToAddress,omitempty"`
	// The email address of the SMTP (envelope) sender. The user-part is hashed. The domain-part is cleartext.
	SenderEmailAddress string `json:"sender,omitempty"`
	// The IP address of the sender.
	SenderIPAddress string `json:"senderIP,omitempty"`
	// The spam score of the message. Higher scores indicate higher certainty.
	SpamScore float64 `json:"spamScore,omitempty"`
	// The subject line of the message, if available.
	Subject string `json:"subject,omitempty"`
	// An array of structures which contain details about detected threats within the message.
	// There may be more than one threat per message.
	Threats []*Threat `json:"threatsInfoMap,omitempty"`
	// A list of email addresses contained within the To: header, excluding friendly names.
	ToHeaderAddresses []string `json:"toAddresses,omitempty"`
	// The content of the X-Mailer: header, if present.
	XmailerHeader string `json:"xmailer,omitempty"`
}

Message is a message with threats.

type MessagePart

type MessagePart struct {
	// The true, detected Content-Type of the messagePart. This may differ from the oContentType value.
	ContentType string `json:"contentType,omitempty"`
	// If the value is "inline," the messagePart is a message body. If the value is
	// "attached," the messagePart is an attachment.
	Disposition string `json:"disposition,omitempty"`
	// The filename of the messagePart.
	FileName string `json:"filename,omitempty"`
	// The MD5 hash of the messagePart contents.
	MD5 string `json:"md5,omitempty"`
	// The declared Content-Type of the messagePart.
	DeclaredContentType string `json:"oContentType,omitempty"`
	// The verdict returned by the sandbox during the scanning process.
	// "unsupported": the messagePart is not supported by Attachment Defense
	// and was not scanned.
	// "clean": the sandbox returned a clean verdict.
	// "threat": the sandbox returned a malicious verdict.
	// "prefilter": the messagePart contained no active content, and was therefore
	// not sent to the sandboxing service.
	// "uploaded": the message was uploaded by PPS to the sandboxing service, but
	// did not yet have a verdict at the time the message was processed.
	// "inprogress": the attachment had been uploaded and was awaiting scanning
	// at the time the message was processed.
	// "uploaddisabled": the attachment was eligible for scanning, but was not
	// uploaded because of PPS policy.
	SandboxStatus string `json:"sandboxStatus,omitempty"`
	// The SHA256 hash of the messagePart contents.
	SHA256 string `json:"sha256,omitempty"`
}

MessagePart is a part of the message related to the click to a malicious URL.

type SiemResponse

type SiemResponse struct {
	QueryEndTime      string     `json:"queryEndTime,omitempty"`
	BlockedClicks     []*Click   `json:"clicksBlocked,omitempty"`
	PermittedClicks   []*Click   `json:"clicksPermitted,omitempty"`
	DeliveredMessages []*Message `json:"messagesDelivered,omitempty"`
	BlockedMessages   []*Message `json:"messagesBlocked,omitempty"`
}

SiemResponse is the response from TAP SIEM API Endpoint.

type Threat

type Threat struct {
	// An identifier for the campaign of which the threat is a member, if available
	// at the time of the query. Threats can be linked to campaigns even after
	// these events are retrieved.
	CampaignID string `json:"campaignID,omitempty"`
	// The category of threat found in the message: Malware, Phish, Spam,
	// Impostor (for BEC/Message Text threats).
	Classification string `json:"classification,omitempty"`
	// The artifact which was condemned by Proofpoint. The malicious URL, hash of
	// the attachment threat, or email address of the impostor sender.
	Name string `json:"threat,omitempty"`
	// The unique identifier associated with this threat. It can be used to query
	// the forensics and campaign endpoints.
	ID string `json:"threatID,omitempty"`
	// The current state of the threat: active, falsepositive, cleared.
	ThreatStatus string `json:"threatStatus,omitempty"`
	// Proofpoint assigned the threatStatus at this time.
	Timestamp time.Time `json:"threatTime,omitempty"`
	// Whether the threat was an attachment, URL, or message type.
	Type string `json:"threatType,omitempty"`
	// A link to the entry about the threat on the TAP Dashboard
	URL string `json:"threatUrl,omitempty"`
}

Threat contain details about detected threats within the message.