/url-defense

name: "Proofpoint URL Defense"
description: >
  Proofpoint URL Defense fundamentals: URL rewriting (v2/v3 formats), click-time
  analysis and verdicts, and manual/API decoding of rewritten URLs back to their
  originals.
when_to_use: >-
  When working with URL rewriting, decoding, click-time protection, or investigating rewritten or
  clicked URLs in Proofpoint URL Defense. Use when: proofpoint url defense, url rewrite, proofpoint
  url, decode proofpoint url, url defense, click-time protection, proofpoint rewritten url,
  urldefense.proofpoint.com, url analysis, proofpoint link, rewritten link, or proofpoint
  decode.

Proofpoint URL Defense

Overview

Proofpoint URL Defense rewrites URLs in email messages to route clicks through Proofpoint's analysis infrastructure. When a user clicks a rewritten URL, Proofpoint performs real-time analysis of the destination before allowing or blocking access. This provides click-time protection - even if a URL was clean when the email was delivered, it will be analyzed again at the moment the user clicks.

URL Defense is a critical layer of protection because many attacks use time-delayed weaponization: a URL is clean when the email is sent but becomes malicious hours or days later.

Anti-triggers

• **The click event feed across all users and threats** — this skill

answers "who clicked *this* URL". The full permitted/blocked click stream is `proofpoint-tap`.

• **Removing the message that carried the link** — use

`proofpoint-quarantine` if it is still held, or `proofpoint-forensics` if it was delivered.

• **Turning URL rewriting on or off** — rewrite behaviour is a

Proofpoint policy setting, and no tool here changes it; use the Proofpoint console. The same is true on a Checkpoint Harmony tenant: that plugin exposes no policy tool either, so its `URL_REWRITE` configuration is console-only as well. Do not route this question to a Harmony skill expecting a tool to exist.

Key Concepts

URL Rewriting

Proofpoint rewrites URLs in email bodies and HTML attachments. The rewritten URL format is:

https://urldefense.proofpoint.com/v2/url?u=<encoded_original_url>&d=<domain_key>&c=<context>&r=<recipient_hash>&m=<message_hash>&s=<signature>&e=

**Version 3 format:**

https://urldefense.com/v3/__<encoded_url>__;!!<encoded_chars>!<signature>$

URL Rewrite Components

| Component | Description | |-----------|-------------| | `u` | URL-encoded original URL (v2) | | `d` | Domain key for the organization | | `c` | Context identifier | | `r` | Recipient hash | | `m` | Message hash | | `s` | HMAC signature for integrity | | `e` | Empty (reserved) |

Click-Time Analysis

When a user clicks a rewritten URL, Proofpoint performs:

1. **URL reputation check** - Is this URL on known blocklists? 2. **Real-time sandbox** - Load the page in a sandbox and check for malicious content 3. **Redirect chain following** - Follow all redirects to the final destination 4. **Content analysis** - Check for credential harvesting forms, drive-by downloads 5. **Verdict delivery** - Allow, warn, or block based on analysis

Click-Time Verdicts

| Verdict | User Experience | Description | |---------|-----------------|-------------| | `allow` | User proceeds to destination | URL is clean | | `warn` | Warning interstitial page | URL is suspicious but not confirmed malicious | | `block` | Block page shown | URL is confirmed malicious | | `isolate` | Opened in browser isolation | URL is risky, opened in safe container |

URL Encoding in v2

In the v2 rewrite format, the original URL is encoded:

• `-` replaces `/`
• `_` replaces `=`
• Standard URL encoding for other special characters

URL Encoding in v3

In the v3 format, the original URL uses a different encoding:

• `__` delimiters surround the encoded URL
• Special characters are encoded in the trailing `!!` section
• The `$` terminates the URL

Field Reference

URL Analysis Fields

| Field | Type | Description | |-------|------|-------------| | `originalUrl` | string | The original URL before rewriting | | `rewrittenUrl` | string | The Proofpoint-rewritten URL | | `verdict` | string | `allow`, `warn`, `block`, `isolate` | | `threatId` | string | Threat ID if URL is malicious | | `classification` | string | `malware`, `phish`, `spam`, `clean` | | `firstSeen` | datetime | When the URL was first observed | | `lastSeen` | datetime | Most recent observation | | `clickCount` | int | Number of clicks on this URL | | `blockCount` | int | Number of times clicks were blocked | | `redirectChain` | string[] | Full redirect chain to final URL | | `finalUrl` | string | Final destination after redirects | | `certificate` | object | SSL certificate details of the destination |

Decoded URL Fields

| Field | Type | Description | |-------|------|-------------| | `encodedUrl` | string | The Proofpoint-rewritten URL provided | | `decodedUrl` | string | The original URL extracted | | `version` | string | Rewrite version (`v2` or `v3`) | | `valid` | boolean | Whether the URL is a valid Proofpoint rewrite |

MCP Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | `proofpoint_url_decode` | Decode one **or many** Proofpoint-rewritten URLs back to the originals | `urls` (required, array) | | `proofpoint_url_analyze` | Analyze a URL for threats — returns classification, risk score, associated campaigns | `url` (required) |

Two tools, and that is the whole domain. `proofpoint_url_decode` takes an **array**, so batch decoding is the ordinary call, not a separate tool — pass one URL in a one-element array. `proofpoint_url_analyze` is also the verdict tool: the classification and risk score it returns *are* the verdict, so there is no separate verdict call to poll.

Not available through this plugin

**Click activity is not keyed by URL anywhere.** URL Defense here decodes and analyses; it has no click surface. Click records live in TAP — `proofpoi