Proofpoint Forensics

Overview

Proofpoint Forensics provides deep investigation capabilities for email-borne threats. When a threat is detected after delivery, Proofpoint Threat Response Auto-Pull (TRAP) can automatically or manually remediate messages that have already reached user mailboxes. This skill covers evidence collection, message investigation, search and destroy operations, and incident response workflows.

TRAP integrates with Microsoft 365 and Google Workspace to move or delete messages from user mailboxes after delivery, closing the gap between detection and remediation.

Anti-triggers

• Stopping a message before it is delivered — everything here acts after delivery. Releasing or deleting mail still held pre-delivery is proofpoint-quarantine.
• The threat event that prompted the investigation — GUIDs, dispositions, scores, and click records come from proofpoint-tap; this skill starts once you already have a GUID or threat ID.
• Campaign attribution, actor names, and IOC context — use proofpoint-threat-intel.
• "Search and destroy" on endpoints rather than mailboxes — TRAP reaches Microsoft 365 and Google Workspace mailboxes only. Killing processes or removing persistence on a host is huntress-incidents.

Key Concepts

Remediation is a two-step sequence, not one call

The single most important thing to know about this domain: finding messages and removing them are separate tools.

1. proofpoint_forensics_search_messages — read-only. Takes criteria (sender, subject, message_id, threat_id, startDate, endDate) and returns matching delivered messages. Changes nothing.
2. proofpoint_forensics_pull_messages — destructive. Takes message_ids (an explicit array) plus a reason string for the audit trail, and removes those messages from mailboxes.

The scope of the destructive step is therefore fixed and inspectable before you call it. Always look at the ID list the search returned, and its length, before passing it on. Piping step 1 straight into step 2 without reading the result is how an over-broad criterion ("subject contains Invoice") turns into hundreds of deleted legitimate messages.

Remediation actions are a tenant setting, not a parameter

Proofpoint TRAP can move a pulled message to junk, soft-delete it, hard-delete it, or quarantine it. None of these is selectable through this plugin — proofpoint_forensics_pull_messages exposes no action argument, so what "pull" does is whatever the tenant's TRAP policy says. Do not promise a user that a removal is recoverable; check the tenant's configuration in the Proofpoint console, because no tool here reports it.

Evidence types

proofpoint_forensics_get_threat returns forensic evidence for one threat, and proofpoint_forensics_get_campaign returns it aggregated across a campaign. Depending on what the tenant's analysis produced, the response may contain any of:

Type	Contents
screenshot	PNG of the rendered threat page or attachment
pcap	Full packet capture from sandbox detonation
sample	The original malicious file
headers	Full RFC 822 headers
urls	All URLs found in the message
attachments	File names, hashes, sizes
sandbox_report	Behavioural analysis results

These are response contents, not arguments — there is no per-type fetch. sample and pcap are live malware; pulling one into the session is read-tier by blast radius and handled-as-malware by common sense.

Field Reference

Forensic Report Fields

Field	Type	Description
id	string	Unique forensic report identifier
GUID	string	Message GUID (links to TAP events)
scope	string	online (cloud analysis) or sandbox (detonation)
type	string	Type of forensic evidence
name	string	Display name for the evidence
threatTime	datetime	When the threat was classified
engineResults	object[]	Results from analysis engines
platforms	object[]	Platforms where evidence was collected

Engine Result Fields

Field	Type	Description
engine	string	Analysis engine name
verdict	string	malicious, suspicious, benign
score	int	Confidence score (0-100)
details	string	Detailed analysis findings
iocs	object[]	IOCs extracted by this engine

Message Trace Fields

Field	Type	Description
GUID	string	Message GUID
messageId	string	RFC 822 Message-ID header
sender	string	Envelope sender
recipients	string[]	All recipients
subject	string	Message subject
receivedTime	datetime	When Proofpoint received the message
deliveryTime	datetime	When delivered to mailbox
disposition	string	Final message disposition
policyActions	string[]	Policy actions applied
routingPath	string[]	Mail routing hops

MCP Tools

Tool	Description	Key Parameters
proofpoint_forensics_get_threat	Forensic evidence for one threat — behavioural analysis, network activity, file modifications, sandbox results	threat_id (required), includeCampaignForensics
proofpoint_forensics_get_campaign	The same evidence aggregated across every threat in a campaign	campaign_id (required)
proofpoint_forensics_search_messages	Find delivered messages to remediate. Read-only	sender, subject, message_id, threat_id, startDate, endDate
proofpoint_forensics_pull_messages	⚠ Destructive. Auto-pull / search-and-destroy: removes delivered messages from mailboxes	message_ids (required, array), reason
proofpoint_smart_search_trace	Trace messages through mail flow — delivery status and processing history	sender, recipient, subject, message_id, startDate, endDate, status

Not available through this plugin

Do not substitute a near-miss for any of these; the correct answer is that Proofpoint is not reachable this way here.

• Polling a remediation's progress. proofpoint_forensics_pull_messages returns no operation ID and there is no status, list, or history tool. The call's own response is the only confirmation you get.
• Reading TRAP auto-pull configuration. No tool exposes whether auto-pull is on, or in which mode. Check the Proofpoint console.
• Choosing the removal action. See above — no action parameter exists.
• A standalone sandbox-report call. Sandbox behavioural analysis comes back inside proofpoint_forensics_get_threat; there is no separate fetch.

Common Workflows

Investigate a Delivered Threat

1. From a TAP delivered-message event, get the threat_id
2. Call proofpoint_forensics_get_threat for the full forensic analysis, including sandbox results and extracted IOCs
3. Set includeCampaignForensics (or call proofpoint_forensics_get_campaign) if the threat belongs to a campaign and you need the wider picture
4. Determine impact with proofpoint_forensics_search_messages — how many mailboxes actually hold the message
5. If remediation is needed, proceed to the sequence below

Search and Destroy

1. Identify the message to remediate — sender, subject, message_id, or the threat_id from the investigation above
2. Call proofpoint_forensics_search_messages with those criteria
3. Read the result. Check the returned message IDs and their count against what you expected. If the count is surprising, the criteria were wrong — narrow them and search again. This is the only point at which the mistake is still free
4. Get human approval on the resolved ID list, not on the criteria
5. Call proofpoint_forensics_pull_messages with those message_ids and a reason for the audit trail
6. Confirm the outcome by re-running the search — the pull reports no per-mailbox result, and mailboxes on legal hold will silently not be remediated
7. Record the criteria, the ID list, and the reason in the incident notes

Post-Incident Evidence Collection

1. Call proofpoint_forensics_get_threat for the threat
2. Review the returned evidence — screenshots, pcaps, samples, sandbox behavioural analysis all arrive in that one response
3. Call proofpoint_forensics_get_campaign for campaign-wide context
4. Extract IOCs from the forensic response
5. Cross-reference with proofpoint_threat_get_iocs
6. Package evidence for the incident report

Message Trace Investigation

1. User reports a suspicious message they received
2. Call proofpoint_smart_search_trace with sender and recipient
3. Review the routing path and policy actions applied
4. Check if TAP flagged the message and what disposition was applied
5. If the message was delivered and is malicious, run the search-and-destroy sequence above
6. If the message was blocked, confirm with the user

Error Handling

Common API Errors

Code	Message	Resolution
400	Invalid search criteria	proofpoint_forensics_search_messages needs at least one criterion
400	message_ids required	proofpoint_forensics_pull_messages will not run without an explicit ID array — there is no "pull everything matching" form
401	Authentication failed	Verify service principal and secret
403	TRAP access not enabled	Ensure your license includes Threat Response
404	Forensic data not found	proofpoint_forensics_get_threat has no data for every threat ID; absence is not a clean bill of health
429	Rate limit exceeded	Forensics allows 500 requests/hour — back off rather than retrying tightly

Search-and-Destroy Failures

Failure Reason	Resolution
Mailbox not accessible	Check Microsoft 365/Google Workspace integration credentials
Message already deleted	User may have deleted the message manually
Permission denied	Service account needs impersonation rights
Mailbox on hold	Legal hold prevents deletion; use move-to-junk instead
Timeout	Large-scope operations may timeout; use narrower criteria

Best Practices

1. Read the ID list before you pull it - The search result is the last point at which an over-broad criterion costs nothing. Check the count
2. Narrow your scope - Use specific criteria (message_id + sender) rather than a bare subject match
3. Never assume the removal is recoverable - No action parameter is exposed; the tenant's TRAP policy decides. Do not tell a user their mail can be restored unless you have checked the console
4. Verify, do not trust the return - Re-run proofpoint_forensics_search_messages after pulling. There is no operation-status tool and per-mailbox failures (legal hold, missing integration) do not surface in the pull response
5. Document everything - Record the criteria, the resolved ID list, and the reason string you passed; that reason is the audit trail
6. Collect evidence first - Call proofpoint_forensics_get_threat before remediating. Once the messages are pulled you cannot go back for what you did not capture
7. Coordinate with users - Notify affected users that messages were removed and explain why
8. Use message trace for debugging - When users report missing legitimate email, trace the path with proofpoint_smart_search_trace

Related Skills

• Proofpoint TAP - Threat events that trigger forensic investigation
• Proofpoint Quarantine - Pre-delivery message management
• Proofpoint Threat Intelligence - Campaign and IOC context
• Proofpoint API Patterns - Authentication and rate limits