Proofpoint TAP - Wazuh Integration

Wazuh wodle that ingests threat events and People intelligence from Proofpoint Targeted Attack Protection (TAP) into Wazuh SIEM via the Proofpoint TAP API.

---

Dashboard

Wazuh Threat Hunting dashboard filtered by integration proofpoint, showing ingested events with severity levels, rule IDs, and descriptions.

Proofpoint TAP dashboard — messages by status, clicks permitted, quarantine counts, top threat URLs, source IPs, recipients, and VAP users.

---

Features

• Full threat coverage — all three threatStatus values (active, cleared, falsePositive) are fetched in a single API call per time window.
• Six event types — messages blocked, messages delivered, clicks blocked, clicks permitted, VAP users, top clickers.
• Single wodle block — one scheduled command drives both SIEM and People API polling. People cadence is managed internally via the state file.
• Automatic catch-up — gaps longer than 1 hour are chunked into sequential API calls with per-chunk checkpointing. A timeout mid-catch-up never discards progress.
• Independent failure isolation — a SIEM API failure never prevents the People fetch, and vice versa. Every failure produces a structured error event.
• Atomic state management — tempfile + os.replace ensures a process kill mid-write never corrupts state.
• Secure credential chain — systemd encrypted credentials > .secrets file > environment variables. Credentials are never logged.
• True nested JSON — threatsInfoMap, messageParts, identity, and statistics are emitted as native JSON objects, enabling rich OpenSearch queries without preprocessing.
• Zero external Python dependencies — stdlib only.

---

Installation

1. Copy wodle/* to /var/ossec/wodles/proofpoint/ on the Wazuh manager. Create .secrets from .secrets.example — set PP_PRINCIPAL and PP_SECRET. Set permissions chmod 640, chown root:wazuh.
2. Copy rules/proofpoint_rules.xml to /var/ossec/etc/rules/ and rules/proofpoint_decoder.xml to /var/ossec/etc/decoders/.
3. Add a wodle stanza to /var/ossec/etc/ossec.conf using the example in artifacts/configs/ossec_proofpoint.conf.
4. Restart Wazuh manager.
5. (Optional) Import artifacts/objects/proofpoint_tap_dash.ndjson into Wazuh/OpenSearch via Dashboard Management > Saved Objects > Import. This adds the Proofpoint TAP dashboard and its 9 visualizations.

See artifacts/configs/ for ossec.conf examples. Docker Compose volume mappings are in artifacts/overrides/.

---

Repository structure

wazuh-proofpoint/
├── wodle/
│   ├── proofpoint.py               <- Entry point, CLI, orchestration
│   ├── proofpoint_siem.py          <- SIEM API module (messages + clicks)
│   ├── proofpoint_people.py        <- People API module (VAP + top clickers)
│   ├── proofpoint_utils.py         <- Auth, HTTP, atomic state, emit, logging, secrets
│   ├── run.sh                      <- Runtime config wrapper (ossec.conf <command> target)
│   └── .secrets.example            <- Credentials template (copy to .secrets)
├── rules/
│   ├── proofpoint_rules.xml        <- Custom Wazuh rules (IDs 100600-100699)
│   └── proofpoint_decoder.xml      <- JSON decoder registration
├── artifacts/
│   ├── configs/
│   │   └── ossec_proofpoint.conf              <- ossec.conf wodle stanza example
│   ├── guides/
│   │   ├── configuration.md                   <- All env vars, CLI flags
│   │   ├── rules-reference.md                 <- Rule catalog with field reference
│   │   └── troubleshooting.md                 <- Test commands, common errors
│   ├── objects/
│   │   └── proofpoint_tap_dash.ndjson         <- OpenSearch dashboard export (9 visualizations)
│   ├── overrides/
│   │   └── docker-compose.single-node.override.yml  <- Docker volume mappings
│   └── images/
│       ├── wazuh_pp_events_pv.png                   <- Threat Hunting screenshot
│       └── wazuh_pp_tap_dash_pv.png                 <- TAP dashboard screenshot
├── CHANGELOG.md
└── README.md

---

How it works

ossec.conf <wodle command>
    └-> run.sh  (sets runtime config; execs proofpoint.py)
            └-> proofpoint.py  (parses args, loads state)
                    ├-> proofpoint_siem.py    -> http_get() -> emit() -> stdout
                    └-> proofpoint_people.py  -> http_get() -> emit() -> stdout
                                                    |
                                          proofpoint_utils.py
                              (auth, HTTP, atomic state, emit, secrets)
                                          |
                          Secret priority chain (first match wins):
                          [systemd $CREDENTIALS_DIRECTORY]
                                    > [.secrets file]
                                    > [env vars]

stdout --> Wazuh wodle manager --> proofpoint_decoder.xml --> proofpoint_rules.xml
                                                                       |
                                                           OpenSearch / Dashboard

Each event is emitted as a single JSON line. All Proofpoint data lives under a pp namespace object to avoid collisions with Wazuh's reserved field names. In rules, fields are referenced as pp.event_type, pp.senderIP, etc. In OpenSearch they appear as data.pp.event_type, data.pp.senderIP.

---

Requirements

• Wazuh 4.4 or later
• Python 3.8 or later on the Wazuh manager host or agent
• Network access to tap-api-v2.proofpoint.com over HTTPS (port 443)
• Proofpoint TAP service principal and secret

---

Reference docs

• Configuration reference — all environment variables, CLI flags, multi-tenant setup
• Rules reference — rule families, severity mapping, field reference
• Troubleshooting — test commands, common errors, state reset, backfill