Proofpoint On Demand Log Api Rev C
Proofpoint On Demand Log Api Rev C
November 2020
Revision C
Endpoint ..................................................................................................................................... 3
Fields .......................................................................................................................................... 5
Authentication ............................................................................................................................. 5
Signing Key......................................................................................................................... 6
Example ............................................................................................................................ 22
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 2 of 23
PoD Log API
The PoD Log service is a webservice for Proofpoint on Demand customers that offers a
real-time email processing log feed for use with Security Information and Event Management
(SIEM) solutions. This webservice uses the secure WebSocket (WSS) protocol to stream logs to
supporting solutions.
This log feed can be used to identify mail and message filtering events.
Connection Notes
The PoD Log API does not allow use of the same token for more than one session at the same
time. If you need to open more than one simultaneous connection to receive the same type of
data, additional token(s) must be requested.
When the connection between the client and the service is dropped and restored within one hour,
the data will be sent from the moment of time when the previous session had dropped, so there is
no need to perform any additional action from the client side.
In the case where the client was connected to the PoD Log service and disconnected for more
than one hour, after a new session is established, the client will start receiving the accumulated
data starting from the last one hour of the new session.
For example:
The previous session was terminated at 1PM EST on 11/17/2020 and at 3PM EST 11/17/2020 a
new connection was established. In this case the client will start receiving "real-time" data from
2PM EST 11/17/2020. To backfill the gap and retrieve the data from 1PM EST to 2PM EST, a
separate request to the archive must be made. To do this, the sinceTime parameter should be
set as 2020-11-17T14:00:00-0005 and the toTime as 2020-11-17T14:59:59-0005.
API Features
Endpoint
The PoD Logging Service production endpoint is
wss://logstream.proofpoint.com/
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 3 of 23
The API signature is
/v1/stream?cid={clusterId}&type=[message|maillog]&sinceTime={sinceTime}
&toTime={toTime}
The sinceTime and toTime parameters must be specified to request the archived data.
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 4 of 23
Part Required Type Example Default Description
Note: If a time is not specified, it means “now.” The limit to data availability is 30 days.
You can specify a query going back in time 30 days from the present time. The archived
data granularity is one (1) hour, not a minute or second. The service rounds down the
sinceTime and rounds up the toTime parameter values to the nearest hour.
Fields
The JSON schema format is used to describe each field. This service supports only JSON.
Authentication
The authorization header must be set as part of the request to authenticate and be authorized to
stream log data.
Proofpoint will provide the token and credentials to connect to the webservice.
Required header:
The token value is uniquely generated and provided by Proofpoint for a customer cluster to
authenticate with the service. The service uses JSON Web Token (JWT) to communicate the
client identity to the service.
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 5 of 23
Signing Key
This is your CLUSTER_ID assigned by Proofpoint. The CLUSTER_ID is displayed in the upper-right
corner of the management interface next to the release number.
Example for curl command to request a data stream compressed by the Deflate
algorithm:
Note: The PoD Log API service supports only the permessage-deflate,
client_no_context_takeover, and server_no_context_takeover extensions.
Refer to RFC7692 for a description of Compression Extensions for WebSocket.
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 6 of 23
Error Codes
The following table describes error handling codes.
405 HTTP Method not allowed - Client is sending non GET requests
Exceeded maximum
The access token is being used by
409 HTTP number of sessions per
another session
token
Message Schema
The following tables describe the message data fields. Fields that are required are indicated as
such in the Description column.
guid Required Globally unique identifier for the message object. string
Required
connection Connection-related data. object
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 7 of 23
Name Required? Description Data Type
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 8 of 23
Name
(Connection/Session Required? Description Data Type
Object Data)
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 9 of 23
Name (Message Object Data) Description Data Type
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 10 of 23
Name (Message Parts
Required? Description Data Type
Object Data)
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 11 of 23
Name (Message Parts
Required? Description Data Type
Object Data)
urls.[].src Required The PPS sources that detected the URL. array of strings
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 12 of 23
Data
Name (Filter Object Data) Required? Description
Type
modules.dmarc.authResults
The result value for the authorization result. string
.[].result
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 13 of 23
Data
Name (Filter Object Data) Required? Description
Type
modules.dmarc.alignment.[]
The DMARC TLD from the MAIL FROM data. string
.fromDomain
The DMARC results array object; there can be
modules.dmarc.alignment.[]
multiple of these per method-identity array
.results
combinations.
modules.dmarc.alignment.[] The DMARC domain identity as reported in the
string
.results.[].identity signature.
modules.sandbox.errorStat
Required The Attachment Defense error status string. string
us
modules.urldefense.rewritte
Required The URLs rewritten by URL Defense. array
nUrls
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 14 of 23
Data
Name (Filter Object Data) Required? Description
Type
modules.urldefense.version
Required Engine version for the URL Defense Module. string
.engine
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 15 of 23
Data
Name (Filter Object Data) Required? Description
Type
inbound
outbound
routeDirection string
internal
external
string
throttleIp The IP address being rate-controlled.
(ipv4/ipv6)
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 16 of 23
Mail Schema
These fields represent the data in the mail logs. Each record or object matches a log line in the
maillog given a particular qid (queue ID).
Field Properties
Name Required? Description Data Type
sm.auth string
sm.msgid Required The message id of the message (from the header). string
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 17 of 23
Name Required? Description Data Type
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 18 of 23
Name Required? Description Data Type
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 19 of 23
Mail Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "https://www.proofpoint.com/v2/schemas/maillog.json",
"properties": {
"data": {
"id": "/properties/data",
"type": "string"
},
"id": {
"id": "/properties/id",
"type": "string"
},
"pps": {
"id": "/properties/pps",
"properties": {
"agent": {
"id": "/properties/pps/properties/agent",
"type": "string"
},
"cid": {
"id": "/properties/pps/properties/cid",
"type": "string"
}
},
"required": [
"agent",
"cid"
],
"type": "object"
},
"sm": {
"id": "/properties/sm",
"properties": {
"ctladdr": {
"id": "/properties/sm/properties/ctladdr",
"type": "string"
},
"delay": {
"id": "/properties/sm/properties/delay",
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 20 of 23
"type": "string"
},
"dsn": {
"id": "/properties/sm/properties/dsn",
"type": "string"
},
"mailer": {
"id": "/properties/sm/properties/mailer",
"type": "string"
},
"pri": {
"id": "/properties/sm/properties/pri",
"type": "integer"
},
"qid": {
"id": "/properties/sm/properties/qid",
"type": "string"
},
"stat": {
"id": "/properties/sm/properties/stat",
"type": "string"
},
"tls": {
"id": "/properties/sm/properties/tls",
"properties": {
"verify": {
"id":
"/properties/sm/properties/tls/properties/verify",
"type": "string"
}
},
"required": [
"verify"
],
"type": "object"
},
"to": {
"id": "/properties/sm/properties/to",
"items": {
"id": "/properties/sm/properties/to/items",
"type": "string"
},
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 21 of 23
"type": "array"
},
"xdelay": {
"id": "/properties/sm/properties/xdelay",
"type": "string"
}
},
"required": [
"qid"
],
"type": "object"
},
"ts": {
"id": "/properties/ts",
"type": "string"
}
},
"required": [
"pps",
"data",
"ts",
"sm",
"id"
],
"type": "object"
}
Example
{
"pps": {
"agent": "example.proofpoint.com",
"cid": "mmeng_uivm071"
},
"ts": "2017-08-17T14:54:12.949180-07:00",
"data": "2017-08-17T14:54:12.949180-07:00 example sendmail[30641]:
v7HLqYbx029423: to=/dev/null, ctladdr=<[email protected]> (8/0),
delay=00:00:00, xdelay=00:00:00, mailer=*file*, tls_verify=NONE, pri=35342,
dsn=2.0.0, stat=Sent",
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 22 of 23
"sm": {
"tls": { "verify": "NONE" },
"stat": "Sent",
"qid": "v7HLqYbx029423",
"dsn": "2.0.0",
"mailer": "*file*",
"to": ["/dev/null"],
"ctladdr": "<[email protected]> (8/0)",
"delay": "00:00:00",
"xdelay": "00:00:00",
"pri": 35342
},
"id": "ZeYGULpZmL5N0151HN1OyA"
}
Proofpoint, Inc - Proprietary and Confidential © 2020 PoD Log API - Rev C - Page 23 of 23