User Guide
Synapse-Proofpoint User Guide
Synapse-Proofpoint adds new Storm commands to allow you to query the Proofpoint API using your existing API credentials.
Getting Started
Check with your Admin to enable permissions and find out if you need a personal API credentials.
Examples
Adding your personal API credentials
To add a personal API credentials:
> proofpoint.config.add myconfig myprincipal mysecret --scope self --tag-prefix "my.user.proofpoint"
Synapse-Proofpoint config "myconfig" added
List available configurations
To list the available configurations, use the proofpoint.config.list
command:
> proofpoint.config.list
name | scope | owner
===========================|==========|====================================================
myconfig | user | root
To view the tag prefix of a configuration, use the vault.list --name <name> command where <name> is synapse-proofpoint:<config name>:
> vault.list --name synapse-proofpoint:myconfig
Available Vaults
----------------
Vault: c411dc357c04ab21d153fe3f2d529764
Name: synapse-proofpoint:myconfig
Type: synapse-proofpoint
Scope: user
Permissions:
Users:
root: admin
Roles: None
Configs:
proxy: true
ssl_verify: true
tag_prefix: my.user.proofpoint
principal: myprincipal
Fetching campaign data
To fetch a list of active campaign IDs within a given time window, use the proofpoint.tap.campaigns command:
> proofpoint.tap.campaigns --updated ("2025-05-18 00:00:00", "2025-05-19 00:00:00") --size 1 --yield
ou:campaign=d8a677359f998faac6a621615279b41b
.created = 2025/11/18 23:28:57.750
:desc = Emails with characteristics (Examples):
From: "phonycompany.co.jp " <phonycompany.foo@bar.com>
From: "phonycompany.co.jp " <phonycompany.bar@foo.com>
:ext:id = 0a9f5348-c955-4e19-895f-f779658ae5c0
:name = company abc phishing | "cogui" | urls | "vevncupnsodm" | japan | 18 - 22 may 2025
:period = ('2025/05/18 00:00:00.000', '2025/05/18 00:00:00.001')
:reporter = ab4e472b1463f912ea91897fa366ec84
:reporter:name = proofpoint
#my.user.proofpoint.ttp.cogui_phishing_kit
#my.user.proofpoint.ttp.geofencing
#my.user.proofpoint.ttp.headers_fencing
To fetch campaign data for a specific campaign, use the proofpoint.tap.campaigns.get command:
> proofpoint.tap.campaigns.get --campaign-id 0a9f5348-c955-4e19-895f-f779658ae5c0 --no-forensics --yield
ou:campaign=d8a677359f998faac6a621615279b41b
.created = 2025/11/18 23:28:57.750
:desc = Emails with characteristics (Examples):
From: "phonycompany.co.jp " <phonycompany.foo@bar.com>
From: "phonycompany.co.jp " <phonycompany.bar@foo.com>
:ext:id = 0a9f5348-c955-4e19-895f-f779658ae5c0
:name = company abc phishing | "cogui" | urls | "vevncupnsodm" | japan | 18 - 22 may 2025
:period = ('2025/05/18 00:00:00.000', '2025/05/18 00:00:00.001')
:reporter = ab4e472b1463f912ea91897fa366ec84
:reporter:name = proofpoint
#my.user.proofpoint.ttp.cogui_phishing_kit
#my.user.proofpoint.ttp.geofencing
#my.user.proofpoint.ttp.headers_fencing
Fetching threat data
To fetch threat data for a specific threat, use the proofpoint.tap.threats.get command:
> proofpoint.tap.threats.get --threat-id 0ff0ee396f7dc349b7348ffa32c3163e79e3301a6fcaabda2b0ae4f847da3066 --no-forensics --yield
risk:alert=bf28af2583ff1ee19d368de76f53ee77
.created = 2025/11/18 23:28:57.862
:_proofpoint:severity = 0
:_proofpoint:spread = 1541
:detected = 2025/05/18 16:54:01.000
:ext:id = 0ff0ee396f7dc349b7348ffa32c3163e79e3301a6fcaabda2b0ae4f847da3066
:service:platform = 78a0480a6245c042ae80e8cc45d19680
:type = proofpoint.phish.url
#my.user.proofpoint.phish.url
#my.user.proofpoint.ttp.cogui_phishing_kit
#my.user.proofpoint.ttp.compromised_website
#my.user.proofpoint.ttp.geofencing
#my.user.proofpoint.ttp.headers_fencing
Fetching Very Attacked People (VAP)
To fetch Very Attacked People (VAP) data for a specific number of days (14, 30, or 90), use the proofpoint.tap.people.vap command:
> proofpoint.tap.people.vap 14 --yield
ps:contact=ef1e5cf20c505ef3b546e7d9f263f96e
.created = 2025/11/18 23:28:57.906
:email = user1@example.com
:emails = ['user1@example.com']
:id = 93115f20-11ba-d9d8-8h7c-698a7226a0b9
:type = proofpoint
#my.user.proofpoint.vap = (2025/08/27 01:47:20.000, 2025/09/10 01:47:20.000)
#my.user.proofpoint.vap.credential_phishing
Fetching SIEM events for messages blocked
To fetch blocked messages from the Proofpoint SIEM, use the proofpoint.tap.siem.messages.blocked command.
To filter the results by a specific time range, use the --min-time and --max-time arguments:
> proofpoint.tap.siem.messages.blocked --min-time "2025-09-10 13:42:00" --max-time "2025-09-10 14:42:00" --yield
it:log:event=bb832fea0280773b62e0faea6439e314
.created = 2025/11/18 23:28:57.947
:data = {'spamScore': 0, 'phishScore': 100, 'threatsInfoMap': ({'threatID': '0e65443125115882130505020eaf71569f0af6258274c9a903a19573bd1785d4', 'threatStatus': 'active', 'classification': 'phish', 'detectionType': 'NONE', 'threatUrl': 'https://threatinsight.proofpoint.com/a-url', 'threatTime': '2025-09-09T14:34:22.000Z', 'threat': 'https://phishing.site/ab5n9ekw/yv3DZL/7', ' campaignID': None, 'actors': (), 'threatType': 'url'},), 'messageTime': '2025-09-10T13:21:48.000Z', 'impostorScore': 0.0, 'malwareScore': 0, 'cluster': 'cluster1', 'subject': 'Test subject', 'quarantineFolder': 'Phish', 'quarantineRule': 'inbound_phish', 'policyRoutes': ('default_inbound',), 'modulesRun': (), 'messageSize': 3377, 'headerFrom': 'test <test@example.com>', 'headerReplyTo': None, 'fromAddress': ('test@example.com',), 'ccAddresses': (), 'replyToAddress': (), 'toAddresses': ('user2@example.com',), 'xmailer': None, 'messageParts': (), 'completelyRewritten': False, 'id': '9d1f8709-fc3a-5589-5052-36c47c053ebc', 'QID': '382yw3vcgb-1', 'GUID': 'HZA0yxJ3t4ZXetWldbdxMsDp6FDvC_l5', 'sender': 'test@example.com', 'recipient': ('user2@example.com',), 'senderIP': '127.0.0.1', 'messageID': '<CAKfd6TKDn71AGCd-7Ciomhge+28f_147zTTOm_7GxkEPpwQLpQ@example.com>'}
:ext:id = 9d1f8709-fc3a-5589-5052-36c47c053ebc
:service:platform = 78a0480a6245c042ae80e8cc45d19680
:time = 2025/09/10 13:21:48.000
:type = proofpoint.siem.message.blocked
it:log:event=8a368beb6c7f95b5c3a252a3f5e2acc0
.created = 2025/11/18 23:28:58.007
:data = {'spamScore': 0, 'phishScore': 100, 'threatsInfoMap': ({'threatID': '0e65443125115882130505020eaf71569f0af6258274c9a903a19573bd1785d4', 'threatStatus': 'active', 'classification': 'phish', 'detectionType': 'NONE', 'threatUrl': 'https://threatinsight.proofpoint.com/tenant-id/threat/email/0e65443125115882130505020eaf71569f0af6258274c9a903a19573bd1785d4', 'threatTime': '2025-09-09T14:34:22.000Z', 'threat': 'https://phishing.site/ab5n9ekw/yv3DZL/7', 'campaignID': None, 'actors': (), 'threatType': 'url'},), 'messageTime': '2025-09-10T14:30:11.000Z', 'impostorScore': 0.0, 'malwareScore': 0, 'cluster': 'cluster1', 'subject': 'Fwd: test', 'quarantineFolder': 'Phish', 'quarantineRule': 'inbound_phish', 'policyRoutes': ('default_inbound',), 'modulesRun': (), 'messageSize': 6494, 'headerFrom': 'Phishing <phishing@example.com', 'headerReplyTo': None, 'fromAddress': ('phishing@example.com',), 'ccAddresses': (), 'replyToAddress': (), 'toAddresses': ('user1@example.com',), 'xmailer': None, 'messageParts': (), 'completelyRewritten': False, 'id': '3deba9a5-2d40-2cc4-7e6e-36c47c053ebc', 'QID': '8752204k9u-1', 'GUID': 'pgIkV3f0NYiK8xixW1Iz-7uHHry-nqe8', 'sender': 'phishing@example.com', 'recipient': ('user1@example.com',), 'senderIP': '127.0.0.1', 'messageID': '<CAC4NbBimCnmaKGJ0a0xN=38D9edWtVpu7DgwzOfymTD_EqM_WA@example.com>'}
:ext:id = 3deba9a5-2d40-2cc4-7e6e-36c47c053ebc
:service:platform = 78a0480a6245c042ae80e8cc45d19680
:time = 2025/09/10 14:30:11.000
:type = proofpoint.siem.message.blocked
To filter the results by recipient email address, use the --filter-recipients argument:
> proofpoint.tap.siem.messages.blocked --filter-recipients "user1@example.com" --min-time "2025-09-10 13:42:00" --max-time "2025-09-10 14:42:00" --yield
it:log:event=8a368beb6c7f95b5c3a252a3f5e2acc0
.created = 2025/11/18 23:28:58.007
:data = {'spamScore': 0, 'phishScore': 100, 'threatsInfoMap': ({'threatID': '0e65443125115882130505020eaf71569f0af6258274c9a903a19573bd1785d4', 'threatStatus': 'active', 'classification': 'phish', 'detectionType': 'NONE', 'threatUrl': 'https://threatinsight.proofpoint.com/tenant-id/threat/email/0e65443125115882130505020eaf71569f0af6258274c9a903a19573bd1785d4', 'threatTime': '2025-09-09T14:34:22.000Z', 'threat': 'https://phishing.site/ab5n9ekw/yv3DZL/7', 'campaignID': None, 'actors': (), 'threatType': 'url'},), 'messageTime': '2025-09-10T14:30:11.000Z', 'impostorScore': 0.0, 'malwareScore': 0, 'cluster': 'cluster1', 'subject': 'Fwd: test', 'quarantineFolder': 'Phish', 'quarantineRule': 'inbound_phish', 'policyRoutes': ('default_inbound',), 'modulesRun': (), 'messageSize': 6494, 'headerFrom': 'Phishing <phishing@example.com', 'headerReplyTo': None, 'fromAddress': ('phishing@example.com',), 'ccAddresses': (), 'replyToAddress': (), 'toAddresses': ('user1@example.com',), 'xmailer': None, 'messageParts': (), 'completelyRewritten': False, 'id': '3deba9a5-2d40-2cc4-7e6e-36c47c053ebc', 'QID': '8752204k9u-1', 'GUID': 'pgIkV3f0NYiK8xixW1Iz-7uHHry-nqe8', 'sender': 'phishing@example.com', 'recipient': ('user1@example.com',), 'senderIP': '127.0.0.1', 'messageID': '<CAC4NbBimCnmaKGJ0a0xN=38D9edWtVpu7DgwzOfymTD_EqM_WA@example.com>'}
:ext:id = 3deba9a5-2d40-2cc4-7e6e-36c47c053ebc
:service:platform = 78a0480a6245c042ae80e8cc45d19680
:time = 2025/09/10 14:30:11.000
:type = proofpoint.siem.message.blocked
The command supports various time-based filtering options and can be used to set up automated data collection via cron jobs.
The --since-last option is useful for setting up cron jobs that automatically ingest data on a regular basis.
Note: only a single cron job using --since-last should be implemented to ensure results are contiguous in a running view.
Use of meta:source nodes
Synapse-Proofpoint uses a meta:source node and -(seen)> light
weight edges to track nodes observed from the Proofpoint API.
> meta:source=6c1e00b4db994549e58b3bad0b2ec654
meta:source=6c1e00b4db994549e58b3bad0b2ec654
.created = 2025/11/18 23:28:57.735
:name = proofpoint api
:type = synapse.proofpoint
Storm can be used to filter nodes to include/exclude nodes which have been observed by Synapse-Proofpoint. The following example shows how to filter the results of a query to include only results observed by Synapse-Proofpoint:
> #cool.tag.lift +{ <(seen)- meta:source=6c1e00b4db994549e58b3bad0b2ec654 }
Model Extensions
The following extended props are created by the Synapse-Proofpoint powerup:
risk:alert:_proofpoint:severity
int - The Proofpoint severity score, ranges from 0-1000.
risk:alert:_proofpoint:spread
int - The number of Proofpoint customers that also received this threat.