ProofpointThreatResponseEventCollector

Use the Proofpoint Threat Response integration to orchestrate and automate incident response.

Analytics & SIEM · Proofpoint Threat Response

Details

IDProofpointThreatResponseEventCollector
ProviderThoma Bravo
CategoryAnalytics & SIEM
From Version6.8.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM EDR Cortex Cloud Cloud Runtime Security

README

Use the Proofpoint Threat Response integration to orchestrate and automate incident response.

This is the default integration for this content pack when configured by the Data Onboarder in Cortex XSIAM.

Configure Proofpoint Threat Response Event Collector in Cortex

Parameter Description Required
Server URL (e.g., https://192.168.0.1)   True
API Key for the authentication.   True
Trust any certificate (not secure)   False
Use system proxy settings   False
First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days) The time range for the initial data fetch. If timeout errors occur, consider changing this value. False
Fetch limit - maximum number of incidents per fetch   False
Fetch delta - The delta time in each batch. e.g. 1 hour, 3 minutes. The time range between create_after and created_before that is sent to the API when fetching older incidents. If timeout errors occur, consider changing this value. False
Fetch incidents with specific event sources. Can be a list of comma-separated values.   False
Fetch incidents with specific ‘Abuse Disposition’ values. Can be a list of comma-separated values.   False
Fetch incident with specific states.   False
POST URL of the JSON alert source. You can find this value by navigating to Sources -&gt; JSON event source -&gt; POST URL. 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-trap-get-events


Retrieves all incident metadata from Threat Response by specifying filter criteria such as the state of the incident or time of closure.

Base Command

proofpoint-trap-get-events

Input

Argument Name Description Required
should_push_events If true, the command will create events, otherwise it will only display them. Possible values are: true, false. Default is false. Required
state The state of the incidents to retrieve. Possible values are: new, open, assigned, closed, ignored. Optional
created_after Retrieve incidents that were created after this date, in ISO 8601 format (UTC). Example: 2020-02-22 or 2020-02-22T00:00:00Z. Optional
created_before Retrieve incidents that were created before this date, in ISO 8601 format (UTC). Example: 2020-02-22 or 2020-02-22T00:00:00Z. Optional
closed_after Retrieve incidents that were closed after this date, in ISO 8601 format (UTC). Example: 2020-02-22 or 2020-02-22T00:00:00Z. Optional
closed_before Retrieve incidents that were closed before this date, in ISO 8601 format (UTC). Example: 2020-02-22 or 2020-02-22T00:00:00Z. Optional
expand_events If false, will return an array of event IDs instead of full event objects. This will significantly speed up the response time of the API for incidents with a large number of alerts. Possible values are: true, false. Optional
limit The maximum number of incidents to return. Default is 100. Required

Context Output

There is no context output for this command.

Configuration parameters

  • url — Server URL (e.g., https://192.168.0.1) (required)
  • credentials — (required)
  • first_fetch — First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)
  • fetch_limit — Fetch limit - maximum number of incidents per fetch
  • fetch_delta — Fetch delta - The delta time in each batch. e.g., 1 hour, 3 minutes.
  • event_sources — Fetch incidents with specific event sources. Can be a list of comma-separated values.
  • abuse_disposition — Fetch incidents with specific 'Abuse Disposition' values. Can be a list of comma-separated values.
  • states — Fetch incident with specific states.
  • post_url_id — POST URL of the JSON alert source.
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings

Commands (1)

  • proofpoint-trap-get-events

    Retrieves all incident metadata from Threat Response by specifying filter criteria such as the state of the incident or time of closure.

from datetime import timedelta

from CommonServerPython import *
from ProofpointThreatResponseEventCollector import (
    MAX_API_REQUESTS,
    TIME_FORMAT,
    Client,
    fetch_events_command,
    get_incidents_batch_by_time_request,
    list_incidents_command,
)


def test_fetch_events_command(requests_mock):
    """
    Given:
    - fetch events command

    When:
    - Running fetch-events command

    Then:
    - Ensure last-fetch id is 2
    """
    base_url = "https://server_url/"
    with open("./test_data/raw_response.json") as f:
        incidents = json.loads(f.read())
    with open("./test_data/expected_result.json") as f:
        expected_result = json.loads(f.read())
    requests_mock.get(f"{base_url}api/incidents", json=incidents)
    client = Client(base_url=base_url, verify=True, headers={}, proxy=False)
    first_fetch, _ = parse_date_range("2 hours", date_format=TIME_FORMAT)
    events, last_fetch = fetch_events_command(
        client=client, first_fetch=first_fetch, last_run={}, fetch_limit="100", fetch_delta="6 hours", incidents_states=["open"]
    )
    assert events == expected_result


def test_list_incidents_command(requests_mock):
    """
    Given:
    - list_incidents_command

    When:
    - Want to list all existing incidents

    Then:
    - Ensure List Incidents Results in human-readable.
    """
    base_url = "https://server_url/"
    with open("./test_data/raw_response.json") as f:
        incidents = json.loads(f.read())
    requests_mock.get(f"{base_url}api/incidents", json=incidents)
    client = Client(base_url=base_url, verify=True, headers={}, proxy=False)
    args = {"limit": 2}
    incidents, human_readable, raw_response = list_incidents_command(client, args)
    assert "List Incidents Results:" in human_readable


def test_get_incidents_batch_by_time_request_max_api_requests(mocker, requests_mock):
    """
    Given:
    - A created_after timestamp far enough in the past that the batch loop cannot reach current_time
      within MAX_API_REQUESTS iterations (using a 1-minute fetch_delta).

    When:
    - get_incidents_batch_by_time_request is called and the loop exceeds MAX_API_REQUESTS.

    Then:
    - The [BATCH_API_LIMIT] debug log is written.
    - The returned final_created_after equals the initial created_after advanced by
      MAX_API_REQUESTS time windows (1 minute each), i.e. 50 minutes ahead.
    - The returned incidents list is empty (API returns no incidents).
    """
    base_url = "https://server_url/"
    requests_mock.get(f"{base_url}api/incidents", json=[])
    client = Client(base_url=base_url, verify=True, headers={}, proxy=False)

    fetch_delta = "1 minute"
    # Set created_after far enough in the past so the loop won't reach current_time in 50 iterations
    # (50 iterations * 1 minute = 50 minutes, so we need created_after to be more than 50 minutes ago)
    created_after = (datetime.now() - timedelta(hours=2)).strftime(TIME_FORMAT)

    params = {
        "created_after": created_after,
        "last_fetched_id": "0",
        "fetch_delta": fetch_delta,
        "state": "open",
        "fetch_limit": "100",
    }

    debug_mock = mocker.patch("ProofpointThreatResponseEventCollector.demisto.debug")

    incidents_list, final_created_after = get_incidents_batch_by_time_request(client, params)

    # Verify the [BATCH_API_LIMIT] debug log was written
    debug_calls = [call.args[0] for call in debug_mock.call_args_list]
    batch_api_limit_logs = [msg for msg in debug_calls if "[BATCH_API_LIMIT]" in msg]
    assert len(batch_api_limit_logs) == 1, f"Expected exactly one [BATCH_API_LIMIT] debug log, found {len(batch_api_limit_logs)}"

    # Verify the final_created_after is correct:
    # The loop runs MAX_API_REQUESTS (50) iterations, each advancing created_after by 1 minute.
    # So final_created_after = initial created_after + 50 minutes.
    expected_final = (datetime.strptime(created_after, TIME_FORMAT) + timedelta(minutes=MAX_API_REQUESTS)).strftime(TIME_FORMAT)
    assert final_created_after == expected_final, f"Expected final_created_after={expected_final}, got {final_created_after}"

    # Verify no incidents were returned
    assert incidents_list == []