id: proofpoint_tap
name: Proofpoint TAP
version: 1.0.0
description: "Proofpoint Targeted Attack Protection (TAP SIEM API v2) — email threat detection and forensics: pull blocked/delivered message and click events, get threat/campaign forensics, list campaigns, decode URL Defense links, and read top clickers. Service-principal (HTTP Basic) authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: SIEM events (all/messages/clicks), forensics, campaign get/list, URL decode, top clickers."
category: email

# Per-instance configuration. The service principal + secret authenticate via
# HTTP Basic against the TAP API.
config_schema:
  properties:
    url:
      type: string
      description: "TAP API base URL"
      default: "https://tap-api-v2.proofpoint.com"
    service_principal:
      type: string
      description: "TAP service principal"
    secret:
      type: string
      description: "TAP secret"
      x-soar-sensitive: true
  required:
    - service_principal
    - secret

commands:
  - id: get_events
    name: proofpoint-get-events
    description: "Get all TAP events (messages and clicks, blocked and permitted) in a time window."
    risk: read
    inputs_schema:
      properties:
        since_seconds: { type: number, description: "Look-back window in seconds, 60-3600 (default 3600)" }
        interval: { type: string, description: "Optional ISO-8601 interval (overrides since_seconds), e.g. 2024-01-01T00:00:00Z/2024-01-01T01:00:00Z" }
      required: []
    outputs_schema: { properties: {} }
  - id: messages_blocked
    name: proofpoint-messages-blocked
    description: "Get messages blocked in a time window."
    risk: read
    inputs_schema:
      properties:
        since_seconds: { type: number, description: "Look-back window in seconds, 60-3600 (default 3600)" }
        interval: { type: string, description: "Optional ISO-8601 interval" }
      required: []
    outputs_schema: { properties: {} }
  - id: messages_delivered
    name: proofpoint-messages-delivered
    description: "Get messages delivered (with threats) in a time window."
    risk: read
    inputs_schema:
      properties:
        since_seconds: { type: number, description: "Look-back window in seconds, 60-3600 (default 3600)" }
        interval: { type: string, description: "Optional ISO-8601 interval" }
      required: []
    outputs_schema: { properties: {} }
  - id: clicks_blocked
    name: proofpoint-clicks-blocked
    description: "Get clicks to malicious URLs blocked in a time window."
    risk: read
    inputs_schema:
      properties:
        since_seconds: { type: number, description: "Look-back window in seconds, 60-3600 (default 3600)" }
        interval: { type: string, description: "Optional ISO-8601 interval" }
      required: []
    outputs_schema: { properties: {} }
  - id: clicks_permitted
    name: proofpoint-clicks-permitted
    description: "Get clicks to malicious URLs permitted in a time window."
    risk: read
    inputs_schema:
      properties:
        since_seconds: { type: number, description: "Look-back window in seconds, 60-3600 (default 3600)" }
        interval: { type: string, description: "Optional ISO-8601 interval" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_forensics
    name: proofpoint-get-forensics
    description: "Get forensic evidence for a threat or campaign."
    risk: read
    inputs_schema:
      properties:
        threat_id: { type: string, description: "Threat ID (provide this or campaign_id)" }
        campaign_id: { type: string, description: "Campaign ID (provide this or threat_id)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_campaign
    name: proofpoint-get-campaign
    description: "Get details for a single campaign."
    risk: read
    inputs_schema:
      properties:
        campaign_id: { type: string, description: "Campaign ID" }
      required: [campaign_id]
    outputs_schema: { properties: {} }
  - id: list_campaigns
    name: proofpoint-list-campaigns
    description: "List campaign IDs active in a time window."
    risk: read
    inputs_schema:
      properties:
        interval: { type: string, description: "ISO-8601 interval (e.g. 2024-01-01T00:00:00Z/2024-01-02T00:00:00Z)" }
        size: { type: number, description: "Page size (default 100)" }
        page: { type: number, description: "Page number (default 1)" }
      required: [interval]
    outputs_schema: { properties: {} }
  - id: url_decode
    name: proofpoint-url-decode
    description: "Decode Proofpoint URL Defense rewritten URLs back to their original form."
    risk: read
    inputs_schema:
      properties:
        urls: { type: string, description: "Comma-separated rewritten URLs to decode" }
      required: [urls]
    outputs_schema: { properties: {} }
  - id: top_clickers
    name: proofpoint-top-clickers
    description: "Get the users who clicked the most malicious URLs in a window."
    risk: read
    inputs_schema:
      properties:
        window: { type: number, description: "Look-back window in days: 14, 30, or 90 (default 30)" }
      required: []
    outputs_schema: { properties: {} }

  - id: test_connection
    name: proofpoint-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }