Campaign API

Parameters

Required Parameters

interval

A string containing an ISO8601-formatted interval. The minimum interval is 30 seconds. The maximum interval is 1 day.

Examples:

• 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z - an hour interval, beginning at noon UTC on 05-01-2020
• PT30M/2020-05-01T12:30:00Z - the thirty minutes beginning at noon UTC on 05-01-2020 and ending at 12:30pm UTC
• 2020-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone

Optional Parameters

size

The maximum number of campaign IDs to produce in the response. Defaults to 100 and the max supported value is 200.

page

The page of results to return, in multiples of the specified size (or 100, if no size is explicitly chosen). Defaults to 1.

Example Command in Curl

The following command assumes that PRINCIPAL and SECRET are defined environment variables. They correspond to the service principal and secret that was created on the Settings page. 

curl "https://tap-api-v2.proofpoint.com/v2/campaign/ids?interval=2020-08-28T00:00:00Z/2020-08-29T00:00:00Z&page=1&size=100" --user "$PRINCIPAL:$SECRET" -s

Results Format

The campaign results object format is a JSON structure.

{
    campaigns:[
        {
            "id":"e144426d-7bcd-4695-98a7-c9f6551f3d48", // campaign ID
            "lastUpdatedAt":"2020-05-13T16:35:30Z" // last updated timestamp of the campaign
        },
        {
            "id":"e144426d-7bcd-4695-98a7-c9f6551f3d47",
            "lastUpdatedAt":"2020-05-12T16:35:30Z"
        },
        {
           "id":"e144426d-7bcd-4695-98a7-c9f6551f3d46",
           "lastUpdatedAt":"2020-05-11T16:35:30Z"
        },
        {
           "id":"e144426d-7bcd-4695-98a7-c9f6551f3d45",
           "lastUpdatedAt":"2020-05-10T16:35:30Z"
        }
    ]
}

Parameters

None.

Example Command in Curl

The following command assumes that PRINCIPAL and SECRET are defined environment variables. They correspond to the service principal and secret that was created on the Settings page. The campaignId is the identifier for the campaign. This is usually found in the events produced by the SIEM API.

curl "https://tap-api-v2.proofpoint.com/v2/campaign/<campaignId>" --user "$PRINCIPAL:$SECRET" -s

Results Format

The campaign results object format is a JSON structure that contains nested objects. The results provided by this API may not be in any sorted order.

 

Top-level Structure

The top-level structure contains the attributes of the campaign and its membership.

{
    "id": "string", // the campaign id
    "name" : "string", // the name of the campaign
    "description" : "string", // a description of the campaign written by one of Proofpoint's threat analysts
    "startDate" : "string", // an  ISO8601-formatted datetime corresponding to the time the campaign's first threat variants were first observed
    "campaignMembers" : [ list<CampaignMember> ] // an array of CampaignMember objects
    "actors" : [ list<Actor> ], // optional, an array of Actor objects
    "malware" : [ list<Malware> ], // optional, an array of Malware objects
    "techniques" : [ list<Technique> ], // optional, an array of Technique objects
}

 

Actor Objects

An Actor is an individual or a group of individuals who are coordinating one or more attacks against organizations on the Internet. The actor can be associated with a given campaign by correlating common infrastructure across campaigns, identifying authors within their payload, or other threat intelligence.

{
    "name" : "string", // the name of the actor
    "id" : "string" // the actor identifier
}

 

Malware Objects

The Malware object shows the specific family of crimeware used by malicious actors.

{
    "name" : "string", // the name of the malware family
    "id" : "string" // the malware family identifier
}

 

Technique Objects

The Technique object corresponds to the specific technique used to exploit users. Some examples of techniques include exploit-laden documents, drive-by downloads, and credential phishing.

{
    "name" : "string", // the name of the technique
    "id" : "string" // the technique identifier
}

 

CampaignMember Objects

The CampaignMember objects give details about each threat variant which have been correlated to this campaign.

{
    "id" : "string", // the threat identifier
    "threat" : "string", // the attachment hash or URL fragment of the threat
    "type" : "url", // the type of the threat: attachment or url
    "subType" : "string", // the sub-type of the threat: ATTACHMENT, COMPLETE_URL, NORMALIZED_URL, HOSTNAME, or DOMAIN
    "threatTime" : "string" // an  ISO8601-formatted datetime corresponding to the the threat variant was first recognized as malicious
}

 

CampaignFamily Objects

The CampaignFamily object shows the specific category and type of campaign used by malicious actors.

{
     "name" : "string", // the name of the campaign family
     "id" : "string" // the campaign family identifier
}