Proofpoint Cloud Threat Response

Fetches Proofpoint Cloud Threat Response (CTR) incidents into Cortex XSOAR for case management, and exposes commands to list and retrieve incident details.

Case Management · Proofpoint Cloud Threat Response

Details

IDProofpoint Cloud Threat Response
ProviderProofpoint
CategoryCase Management
From Version6.10.0
Docker Imagedemisto/fastapi:0.125.0.10158186
Supported ModulesAgentix XSIAM

README

Fetches Proofpoint Cloud Threat Response (CTR) incidents into Cortex XSOAR for case management, and exposes commands to list and retrieve incident details.
This integration was integrated and tested with version 1.0 of Proofpoint Cloud Threat Response.

Configure Proofpoint Cloud Threat Response in Cortex

Parameter Description Required
Server URL The base URL of the Proofpoint Cloud Threat Response API. True
Client ID The Client ID and Client Secret generated from your Proofpoint Threat Response account (API Key Management). True
Client Secret   True
Fetch incidents   False
Incident type   False
First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)   False
Maximum number of incidents per fetch The maximum number of incidents to fetch each interval. Default and maximum is 200. False
Fetch delta (minutes) An additional buffer (in minutes) subtracted from the start of each fetch window to mitigate clock drift and ensure no incidents are missed. False
Fetch incidents with specific states Must be set when fetch is enabled. Selecting both `open_incidents` and `closed_incidents` returns an empty result from the upstream API. False
Enrich incidents during fetch When enabled, each fetched incident is enriched with full details (activities, comments, message source data) by calling the GET /incidents/{id} endpoint once per incident. Disable when fetching large volumes to avoid rate limits. False
Trust any certificate (not secure)   False
Use system proxy settings   False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

proofpoint-ctr-incidents-list

Returns a list of Proofpoint Cloud Threat Response incidents matching the supplied filters.

Base Command

proofpoint-ctr-incidents-list

Input

Argument Name Description Required
start_time The start of the time range filter. Accepts a free text date (e.g., 3 days, 2024-11-26T16:18:07Z). Optional
end_time The end of the time range filter. Accepts a free text date. Defaults to now when omitted. Optional
incident_id_filters A comma-separated list of incident displayId values (numeric). For example, 781,782. Optional
source_filters Filter incidents by source. Possible values are: abuse_mailbox, tap, smart_search, message_csv_upload. Optional
other_filters Filter incidents by state or VAP. Selecting both open_incidents and closed_incidents returns an empty result from the upstream API. Possible values are: open_incidents, closed_incidents, vap. Optional
verdict_filters Filter incidents by verdict. Possible values are: verdict_failed, verdict_low_risk, verdict_manual_review, verdict_threat. Optional
disposition Filter incidents by disposition. Possible values are: bulk, clean, impostor, in_progress, internal, low_risk, malware, manual_review, not_set, phish, scam, simulated_phish, spam, suspicious, tap_false_positive, toad, vendor. Optional
confidence_filters Filter incidents by confidence level. Possible values are: confidence_high, confidence_medium, confidence_low. Optional
limit The maximum number of incidents to return. Default is 50. Optional

Context Output

Path Type Description
ProofPointCloud.Incident.id String The internal UUID of the incident.
ProofPointCloud.Incident.displayId Number The numeric display ID of the incident.
ProofPointCloud.Incident.title String The incident title.
ProofPointCloud.Incident.state String The state of the incident (open/closed).
ProofPointCloud.Incident.createdAt Date The creation timestamp of the incident.
ProofPointCloud.Incident.updatedAt Date The last update timestamp of the incident.
ProofPointCloud.Incident.messageCount Number The number of messages associated with the incident.
ProofPointCloud.Incident.assignedTeamName String The name of the team the incident is assigned to.
ProofPointCloud.Incident.priority String The priority of the incident.
ProofPointCloud.Incident.closedAt Date The timestamp when the incident was closed, if applicable.
ProofPointCloud.Incident.assignedUserName String The username of the individual the incident is assigned to.
ProofPointCloud.Incident.sourceTypes Array The list of source types that produced the incident.
ProofPointCloud.Incident.dispositions Array The list of dispositions assigned to the incident.
ProofPointCloud.Incident.clearVerdicts Array The list of clear verdicts for the incident.
ProofPointCloud.Incident.clearConfidences Array The list of confidence values for the incident.
ProofPointCloud.Incident.sourcesData Array The raw sources data array for the incident.

Command Example

!proofpoint-ctr-incidents-list limit=2

Context Example

[
    {
        "id": "00000000-0000-0000-0000-000000000001",
        "createdAt": "2024-01-01T10:00:00.000+00:00",
        "updatedAt": "2024-01-01T10:05:00.000+00:00",
        "displayId": 12345,
        "priority": "high",
        "title": "user[@]example[.]com reported a message \"Suspicious phishing attempt\"",
        "state": "open",
        "assignedTeamName": "SOC_Analyst",
        "messageCount": 1,
        "sourceTypes": ["abuse_mailbox"],
        "sourcesData": [{"type": "AbuseMailbox", "name": "Proofpoint CLEAR"}],
        "dispositions": ["manual_review"],
        "clearVerdicts": ["manual_review"],
        "clearConfidences": ["low"]
    },
    {
        "id": "00000000-0000-0000-0000-000000000002",
        "createdAt": "2024-01-01T09:00:00.000+00:00",
        "updatedAt": "2024-01-01T09:30:00.000+00:00",
        "closedAt": "2024-01-01T09:30:00.000+00:00",
        "displayId": 12344,
        "priority": null,
        "title": "other[@]example[.]com reported a message \"Low risk email review\"",
        "state": "closed",
        "assignedTeamName": "SOC_Analyst",
        "messageCount": 18,
        "sourceTypes": ["abuse_mailbox"],
        "sourcesData": [{"type": "AbuseMailbox", "name": "Proofpoint CLEAR"}],
        "dispositions": ["low_risk"],
        "clearVerdicts": ["low_risk"],
        "clearConfidences": ["high"]
    }
]

Human Readable Output

Proofpoint Cloud Threat Response Incidents

ID Created At Type State Message Count Assigned Team Name Title Source Types
00000000-0000-0000-0000-000000000001 2024-01-01T10:00:00.000+00:00 AbuseMailbox open 1 SOC_Analyst user[@]example[.]com reported a message “Suspicious phishing attempt” abuse_mailbox
00000000-0000-0000-0000-000000000002 2024-01-01T09:00:00.000+00:00 AbuseMailbox closed 18 SOC_Analyst other[@]example[.]com reported a message “Low risk email review” abuse_mailbox

proofpoint-ctr-incident-get

Returns full details for a specific Proofpoint Cloud Threat Response incident.

Base Command

proofpoint-ctr-incident-get

Input

Argument Name Description Required
incident_id A comma-separated list of incident UUIDs (e.g., 440def43-c322-42ba-a6d6-a2306128ea3b). Required

Context Output

Path Type Description
ProofPointCloud.Incident.id String The internal UUID of the incident.
ProofPointCloud.Incident.displayId Number The numeric display ID of the incident.
ProofPointCloud.Incident.title String The incident title.
ProofPointCloud.Incident.state String The state of the incident.
ProofPointCloud.Incident.createdAt Date The creation timestamp of the incident.
ProofPointCloud.Incident.updatedAt Date The last update timestamp of the incident.
ProofPointCloud.Incident.priority String The priority of the incident.
ProofPointCloud.Incident.messageCount Number The number of messages associated with the incident.
ProofPointCloud.Incident.assignedTeamName String The name of the team the incident is assigned to.
ProofPointCloud.Incident.assignedApplicationUserName String The user the incident is assigned to.
ProofPointCloud.Incident.closedAt Date The timestamp when the incident was closed, if applicable.
ProofPointCloud.Incident.openedAt Date The timestamp when the incident was opened.
ProofPointCloud.Incident.messageSourceData Unknown Breakdown of message sources (TAP, abuse mailbox, smart search, etc.) for the incident.
ProofPointCloud.Incident.comments Array The comments associated with the incident.
ProofPointCloud.Incident.activities Array The activities associated with the incident.

Command Example

!proofpoint-ctr-incident-get incident_id=00000000-0000-0000-0000-000000000001

Context Example

{
    "id": "00000000-0000-0000-0000-000000000001",
    "createdAt": "2024-01-01T10:00:00.000+00:00",
    "updatedAt": "2024-01-01T10:05:00.000+00:00",
    "displayId": 12345,
    "priority": "high",
    "state": "open",
    "title": "user[@]example[.]com reported a message \"Suspicious phishing attempt\"",
    "closedAt": null,
    "openedAt": "2024-01-01T10:00:00.000+00:00",
    "assignedTeamName": "SOC_Analyst",
    "assignedApplicationUserName": null,
    "messageCount": 1,
    "messageSourceData": {
        "hasTapAlert": false,
        "hasAbuseAlert": true,
        "hasSmartSearchImport": false,
        "hasMessageCsvUpload": false,
        "hasWorkbenchEvent": false,
        "hasImdAlert": false,
        "hasMailBombAlert": false
    },
    "comments": [],
    "activities": [
        {
            "id": "00000000-0000-0000-0000-000000000006",
            "cause_type": "system",
            "created_at": "2024-01-01T10:00:00.000",
            "occurred_at": "2024-01-01T10:00:00.000000",
            "activity_type": "incident_creation",
            "activity_details": {
                "source_name": "Proofpoint CLEAR",
                "initial_priority": null,
                "initial_team_name": "SOC_Analyst"
            },
            "causing_user_name": null,
            "causing_workflow_name": null
        },
        {
            "id": "00000000-0000-0000-0000-000000000008",
            "cause_type": "history",
            "created_at": "2024-01-01T10:00:10.000",
            "activity_type": "quarantine",
            "activity_details": {
                "quarantine_attempts": [
                    {
                        "state": "complete",
                        "disposition": "message_moved"
                    }
                ]
            },
            "causing_workflow_name": "Official Manual Review"
        }
    ]
}

Human Readable Output

Proofpoint Cloud Threat Response Incident: 12345

ID Created At State Message Count Assigned Team Name Title
00000000-0000-0000-0000-000000000001 2024-01-01T10:00:00.000+00:00 open 1 SOC_Analyst user[@]example[.]com reported a message “Suspicious phishing attempt”

Known Limitations

Fetch Enrichment and API Rate Limits

By default, the “Enrich incidents during fetch” parameter is disabled. When disabled, each fetch cycle makes a single API call to retrieve the incident list, and the raw JSON stored per incident contains only the fields returned by the list endpoint (summary fields such as id, title, state, createdAt, messageCount, etc.).

When enrichment is enabled, the integration makes one additional GET /api/v1/tric/incidents/{id} call per incident in every fetch cycle. This provides richer data immediately (activities, comments, messageSourceData) but multiplies API call volume proportionally to the number of incidents fetched. In environments with high incident volume this can trigger Proofpoint API rate limits (HTTP 429).

Recommended approach for high-volume environments:

  1. Keep “Enrich incidents during fetch” disabled (default).
  2. Use the proofpoint-ctr-incident-get command to enrich individual incidents on demand from a playbook or manually from the War Room.
  3. Because both commands write to the same context key (ProofPointCloud.Incident.id), running proofpoint-ctr-incident-get after proofpoint-ctr-incidents-list will enrich the existing context entry rather than creating a duplicate.

Configuration parameters

  • url — Server URL (required)
  • credentials — Client ID (required)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings
  • isFetch — Fetch incidents
  • incidentType — Incident type
  • incidentFetchInterval — Incidents Fetch Interval
  • first_fetch — First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
  • max_fetch — Maximum number of incidents per fetch
  • fetch_delta — Fetch delta (minutes)
  • fetch_states — Fetch incidents with specific states
  • fetch_enrich — Enrich incidents during fetch

Commands (2)

  • proofpoint-ctr-incident-get

    Returns full details for a specific Proofpoint Cloud Threat Response incident.

  • proofpoint-ctr-incidents-list

    Returns a list of Proofpoint Cloud Threat Response incidents matching the supplied filters.

Source

ProofpointCloudThreatResponse.py ProofpointCloudThreatResponse_test.py ProofpointCloudThreatResponse.yml ProofpointCloudThreatResponse_description.md
Download History Raw 
name: Proofpoint Cloud Threat Response
display: Proofpoint Cloud Threat Response
description: Fetches Proofpoint Cloud Threat Response (CTR) incidents into Cortex XSOAR for case management, and exposes commands to list and retrieve incident details.
category: Case Management
provider: Proofpoint
sectionorder:
- Connect
- Collect
commonfields:
  id: Proofpoint Cloud Threat Response
  version: -1
configuration:
- display: Server URL
  name: url
  defaultvalue: https://threatprotection-api.proofpoint.com
  type: 0
  required: true
  additionalinfo: The base URL of the Proofpoint Cloud Threat Response API.
  section: Connect
- displaypassword: Client Secret
  display: Client ID
  name: credentials
  type: 9
  required: true
  additionalinfo: The Client ID and Client Secret generated from your Proofpoint Threat Response account (API Key Management).
  section: Connect
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  required: false
  section: Connect
  advanced: true
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
  section: Connect
  advanced: true
- display: Fetch incidents
  name: isFetch
  type: 8
  required: false
  section: Collect
- display: Incident type
  name: incidentType
  defaultvalue: Cloud Threat Response Incident
  type: 13
  required: false
  section: Collect
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: '1'
  required: false
  type: 19
  section: Collect
  advanced: true
- display: First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
  name: first_fetch
  defaultvalue: 3 days
  type: 0
  required: false
  section: Collect
- display: Maximum number of incidents per fetch
  name: max_fetch
  defaultvalue: '50'
  type: 0
  required: false
  additionalinfo: The maximum number of incidents to fetch each interval. Default and maximum is 200.
  section: Collect
- display: Fetch delta (minutes)
  name: fetch_delta
  defaultvalue: '1'
  type: 0
  required: false
  additionalinfo: An additional buffer (in minutes) subtracted from the start of each fetch window to mitigate clock drift and ensure no incidents are missed.
  section: Collect
- display: Fetch incidents with specific states
  name: fetch_states
  defaultvalue: open_incidents
  type: 15
  required: false
  options:
  - open_incidents
  - closed_incidents
  additionalinfo: Must be set when fetch is enabled. Selecting both `open_incidents` and `closed_incidents` returns an empty result from the upstream API.
  section: Collect
- display: Enrich incidents during fetch
  name: fetch_enrich
  defaultvalue: 'false'
  type: 8
  required: false
  additionalinfo: >-
    When enabled, each fetched incident is enriched with full details (activities, comments, message source data)
    by calling the GET /incidents/{id} endpoint once per incident. This provides richer data immediately but
    increases API call volume proportionally to the number of incidents fetched. Disable this option when
    fetching large volumes of incidents to avoid rate limits; you can always enrich individual incidents
    on demand using the `proofpoint-ctr-incident-get` command.
  section: Collect
  advanced: true
script:
  commands:
  - name: proofpoint-ctr-incidents-list
    description: Returns a list of Proofpoint Cloud Threat Response incidents matching the supplied filters.
    arguments:
    - name: start_time
      description: The start of the time range filter. Accepts a free text date (e.g., `3 days`, `2024-11-26T16:18:07Z`).
    - name: end_time
      description: The end of the time range filter. Accepts a free text date. Defaults to now when omitted.
    - name: incident_id_filters
      description: A comma-separated list of incident `displayId` values (numeric). For example, `781,782`.
      isArray: true
    - name: source_filters
      description: Filter incidents by source.
      isArray: true
      auto: PREDEFINED
      predefined:
      - abuse_mailbox
      - tap
      - smart_search
      - message_csv_upload
    - name: other_filters
      description: Filter incidents by state or VAP. Selecting both `open_incidents` and `closed_incidents` returns an empty result from the upstream API.
      isArray: true
      auto: PREDEFINED
      predefined:
      - open_incidents
      - closed_incidents
      - vap
    - name: verdict_filters
      description: Filter incidents by verdict.
      isArray: true
      auto: PREDEFINED
      predefined:
      - verdict_failed
      - verdict_low_risk
      - verdict_manual_review
      - verdict_threat
    - name: disposition
      description: Filter incidents by disposition.
      isArray: true
      auto: PREDEFINED
      predefined:
      - bulk
      - clean
      - impostor
      - in_progress
      - internal
      - low_risk
      - malware
      - manual_review
      - not_set
      - phish
      - scam
      - simulated_phish
      - spam
      - suspicious
      - tap_false_positive
      - toad
      - vendor
    - name: confidence_filters
      description: Filter incidents by confidence level.
      isArray: true
      auto: PREDEFINED
      predefined:
      - confidence_high
      - confidence_medium
      - confidence_low
    - name: limit
      description: The maximum number of incidents to return. Default is 50.
      defaultValue: '50'
    outputs:
    - contextPath: ProofPointCloud.Incident.id
      description: The internal UUID of the incident.
      type: String
    - contextPath: ProofPointCloud.Incident.displayId
      description: The numeric display ID of the incident.
      type: Number
    - contextPath: ProofPointCloud.Incident.title
      description: The incident title.
      type: String
    - contextPath: ProofPointCloud.Incident.state
      description: The state of the incident (open/closed).
      type: String
    - contextPath: ProofPointCloud.Incident.createdAt
      description: The creation timestamp of the incident.
      type: Date
    - contextPath: ProofPointCloud.Incident.updatedAt
      description: The last update timestamp of the incident.
      type: Date
    - contextPath: ProofPointCloud.Incident.messageCount
      description: The number of messages associated with the incident.
      type: Number
    - contextPath: ProofPointCloud.Incident.assignedTeamName
      description: The name of the team the incident is assigned to.
      type: String
    - contextPath: ProofPointCloud.Incident.sourceTypes
      description: The list of source types that produced the incident.
      type: Array
    - contextPath: ProofPointCloud.Incident.dispositions
      description: The list of dispositions assigned to the incident.
      type: Array
    - contextPath: ProofPointCloud.Incident.clearConfidences
      description: The list of confidence values for the incident.
      type: Array
    - contextPath: ProofPointCloud.Incident.priority
      description: The priority of the incident.
      type: String
    - contextPath: ProofPointCloud.Incident.closedAt
      description: The timestamp when the incident was closed, if applicable.
      type: Date
    - contextPath: ProofPointCloud.Incident.assignedUserName
      description: The username of the individual the incident is assigned to.
      type: String
    - contextPath: ProofPointCloud.Incident.clearVerdicts
      description: The list of clear verdicts for the incident.
      type: Array
    - contextPath: ProofPointCloud.Incident.sourcesData
      description: The raw sources data array for the incident.
      type: Array
  - name: proofpoint-ctr-incident-get
    description: Returns full details for a specific Proofpoint Cloud Threat Response incident.
    arguments:
    - name: incident_id
      description: A comma-separated list of incident UUIDs (e.g., `440def43-c322-42ba-a6d6-a2306128ea3b`).
      required: true
      isArray: true
    outputs:
    - contextPath: ProofPointCloud.Incident.id
      description: The internal UUID of the incident.
      type: String
    - contextPath: ProofPointCloud.Incident.displayId
      description: The numeric display ID of the incident.
      type: Number
    - contextPath: ProofPointCloud.Incident.title
      description: The incident title.
      type: String
    - contextPath: ProofPointCloud.Incident.state
      description: The state of the incident.
      type: String
    - contextPath: ProofPointCloud.Incident.createdAt
      description: The creation timestamp of the incident.
      type: Date
    - contextPath: ProofPointCloud.Incident.updatedAt
      description: The last update timestamp of the incident.
      type: Date
    - contextPath: ProofPointCloud.Incident.priority
      description: The priority of the incident.
      type: String
    - contextPath: ProofPointCloud.Incident.messageCount
      description: The number of messages associated with the incident.
      type: Number
    - contextPath: ProofPointCloud.Incident.assignedTeamName
      description: The name of the team the incident is assigned to.
      type: String
    - contextPath: ProofPointCloud.Incident.assignedApplicationUserName
      description: The user the incident is assigned to.
      type: String
    - contextPath: ProofPointCloud.Incident.closedAt
      description: The timestamp when the incident was closed, if applicable.
      type: Date
    - contextPath: ProofPointCloud.Incident.openedAt
      description: The timestamp when the incident was opened.
      type: Date
    - contextPath: ProofPointCloud.Incident.messageSourceData
      description: Breakdown of message sources (TAP, abuse mailbox, smart search, etc.) for the incident.
      type: Unknown
    - contextPath: ProofPointCloud.Incident.comments
      description: The comments associated with the incident.
      type: Array
    - contextPath: ProofPointCloud.Incident.activities
      description: The activities associated with the incident.
      type: Array
  dockerimage: demisto/fastapi:0.125.0.10158186
  isfetch: true
  runonce: false
  script: '-'
  subtype: python3
  type: python
fromversion: 6.10.0
tests:
- No tests (auto formatted)