Threat Response Auto Pull (TRAP) - Installation Guide

Installation guide provides information on how to get Threat Response Auto Pull (TRAP) up and running in your environment. The Installation guide includes the list of hardware requirements, all the major steps to install Threat Response Auto Pull image in VMware environment, configure required bootstrap services, and perform initial configuration.

TRAP Installation Requirements

Virtual Machine Requirements

TRAP Auto Pull (TRAP) is a stand-alone virtual appliance. It is distributed as an OVA file, and can be downloaded from the Proofpoint Customer Portal.

The virtual machine requires the following, minimum hardware configuration for production deployments:

  • 4x vCPU Cores (8x vCPU cores recommended)
  • 8 GB RAM (16 GB RAM recommended)
  • 50 GB HDD (base system for version 5.0 and beyond)
  • 500 GB HDD (local databases and backups)
  • 1 network adaptor (default is E1000 but VMXNET3 is also supported)

For administration and general usage, TRAP will need one IP address allocated to it for network access. If you plan to build a cluster for high-availability, you will need one local IP per-system, plus a single management IP to be shared between the systems.

Active Directory Requirements

Active Directory enables Threat Response Auto-Pull to gather details about users in alerts including information such as group membership, department, location, and more. Threat Response Auto-Pull requires read-only permissions in Active Directory.

Exchange Web Services Requirements

Threat Response Auto-Pull requires the connection with Exchange Web Services to perform email quarantine action. To configure Exchange EWS, you will need the following information:

  • Exchange Web Services:
    • EWS URL: Based on your Exchange deployment you will need the Exchange Web Services URL. If you have a hybrid Exchange setup, you can configure both Exchange on-premise and Office 365 EWS URLs.
      • On-premise Exchange: https://yourexchangehost.yourdomain.com/ews/exchange.asmx
        • In most cases, this host is same as the one that is hosting the Exchange OWA service.
      • Office 365: https://outlook.office365.com/ews/exchange.asmx
    • (Optional) EWS Certificate: If you are using a self-signed certificate on Exchange CAS server for EWS service, you will need to import the cert to TRAP certificate store.
  • Exchange Service Account: TRAP requires a service account with the privilege to quarantine messages in targeted mailboxes. This service account must meet the following requirements:
    • The service account must have an associated mailbox
    • The service account must have permission to scan targeted mailboxes. Choose one of the two supported exchange permission models:
      • Application Impersonation role (recommended): Grant explicit application impersonation role to the Exchange service account used for TRAP. Please ensure that this account has no other Exchange permissions or roles assigned.
      • Full Access permission: The Exchange service account used for quarantining has “Full Access” permission to all mailboxes.
  • Exchange Throttle Setting: To enable faster email quarantine rates, we recommend exempting this service/user account from any EWS Throttling limitations you may have configured on Exchange CAS server.

Supported Exchange Versions

TRAP supports the following:

  • Exchange on-premise: Exchange 2010, 2013, 2016, and 2019
  • Office 365

Required ports for network communication

TRAP requires the following ports to be opened for management purposes, and to allow it to communicate with your devices. Refer to the table below for a list of ports that should be allowed between TRAP and other systems.

Port Direction Purpose
TCP/8080 Admin Network to TRAP Appliance Management Console
TCP/22 Admin Network to TRAP SSH access to CLI
TCP/443 “Any” to TRAP TRAP GUI & HTTPS alert listeners
TCP/443 TRAP to “overcast.proofpoint.com” Communication with Overcast for Alert Enrichment
TCP/443 TRAP to “overcast.proofpoint.com” Communication with Overcast SmartSearch export from the Admin Portal
TCP/443 TRAP to “tap-api-v2.proofpoint.com” Pulling alerts from TAP
TCP/443 TRAP to “saasisolation.com” and “proofpointisolation.com” Rendering suspicious web pages from abuse-reported messages using Proofpoint Browser Isolation
TCP/443 TRAP to Exchange/O365/Gmail Used to quarantine messages
TCP/443 Threat Response to login.windows.net Used to obtain OAuth token from Azure AD Auth for O365 connectivity
TCP/389 TRAP to LDAP Server Query LDAP for user details
TCP/25 TRAP to Mail Server Notifications & alerts via email
UDP/53 TRAP to DNS Server DNS services
UDP/123 TRAP to NTP Server NTP services
TCP/2224 Threat Response Clustering Basic Clustering comms
UDP/5405 Threat Response Clustering Basic Clustering comms
TCP/7789 Threat Response Clustering Disk Replication

Supported browsers

TRAP supports the following browsers:

Browser Version
Google Chrome 51.0 +
Mozilla Firefox 47.0 +

Supported hypervisors

Today TRAP supports the following virtualization environments:

Initial TRAP configuration

Building TRAP VM

Importing TRAP to VMware

This example shows how to configure the Proofpoint TRAP on VMware ESX 6.0.

Note

This example assumes you have downloaded the OVA file from the Proofpoint Customer Portal as described in your Proofpoint Welcome letter.

To install TRAP in a VMware environment:

  1. Start the VMware vSphere Client on your workstation.
  2. Log in to the VMware ESXi server that will host the VM.

  3. Select File > Deploy OVF Template to open the Deploy OVF Template dialog box.

    Note: the installation steps are listed in the panel on the left. You can use this list to follow your progress.

  4. Go to the Deploy from file field and browse to the TRAP OVA file.

  5. Click Open, then click Next.
  6. Verify the OVF Template details then click Next.
  7. Review the TRAP End User License Agreement.
  8. Click Accept, then click Next.
  9. Accept or change the default name in the Name and Location field, then click Next.
  10. Select the resource pool for this VM, then click Next.
  11. Select the data store to use for the TRAP files, then click Next.

  12. Map the networks in the OVF template to your networks, then click Next.

    Note: The managed devices must be reachable from the TRAP virtual appliance.

  13. Review the settings and click Finish to begin installing TRAP.

    Note: The system takes a few minutes to import the virtual appliance. Do not shut down the application during this process.

  14. In the Deployment Completed Successfully window, click Close.

Initial Configuration Wizard (New)

Once you deploy the Threat Response VM, you can proceed with the initial configuration. Begin by powering up Threat Response.

  1. In the vSphere Client, select the Threat Response appliance that was just installed. Right-click the name, then click on Power > Power On.
  2. Launch a Console for this VM.
  3. Go to the next section to begin configuring the Threat Response appliance.

Once Threat Response has started, you can proceed with the Initial Configuration Wizard. This can take up to five minutes.

  1. Open a console window to start the Initial Configuration Wizard.

  2. Type admin at the prompt, then press Enter.

  3. Set an administrator password for your admin user.

  4. Enter the password again for verification purposes.

  5. Enter (set) a hostname for the appliance. Be sure to record it in the Managing TRAP Configuration Information section below.

  6. a. (Optional) Select yes for DHCP, then press Enter if you want to use a DHCP server to dynamically assign an IP address to Threat Response.

b. Select no for manual configuration by means of three prompts:

  1. Enter an IP address and netmask in the Classless Inter-Domain Routing (CIDR) format (IP address/masking bits), e.g. 10.21.68.21/8.

  2. Enter your gateway IP address.

  3. List any DNS servers separated by commas.

Note that new first boot steps have been added to version 5.0.1 (and beyond).

Threat Response uses the following two gateways/subnets for internal use by default:

  1. 172.31.250.1/24 is a subnet used by Docker containers running various back-end services in Threat Response.
  2. 172.31.251.1/24 is a subnet used by Docker containers created for scripted listeners, pollers, and responses.

Importantly, if they conflict with your network, you will not get return network traffic to any addresses within those ranges. If you choose Yes (to change the gateways), the following will appear. Note that the gateways must be different, unique subnets. Moreover, they are only meant to be routed within the appliance.

  1. Enter the gateway/subnet in CIDR format for Threat Response services, e.g. 172.31.250.1/24.
  2. Enter the gateway/subnet in CIDR format for Threat Response scripting services, e.g. 172.31.251.1/24.

You will be asked if you want to confirm the entirety of the settings above. Choose Yes to configure and initialize the system. This may take a few minutes.

Note

Importantly, these two /24 subnets have not been extracted from the existing network infrastructure. Note that you may pick two IP address ranges that do not overlap with anything else in your data center. Alternatively, you can pick Class C network IP address ranges (192.x.x.x).

Initial Configuration Wizard (Old)

Once you deploy the TRAP VM, you can proceed with the initial configuration. Begin by powering up TRAP.

  1. In the vSphere Client, select the TRAP appliance that was just installed. Right-click the name, then click on Power > Power On.
  2. Click the Console tab to emulate a console port.
  3. Go to the next section to begin configuring the TRAP appliance.

Once TRAP has started, you can proceed with the Initial Configuration Wizard. This can take up to five minutes.

  1. Open a console window to start the Initial Configuration Wizard.

  2. Type admin at the prompt, then press Enter. Further, if the system prompts you for a password, enter proofpoint.

  3. Type yes at the “Do you want to use the wizard …” prompt, then press Enter.

  4. Enter (set) a name for the virtual machine at the Hostname prompt, then press Enter. Be sure to record it in the Managing TRAP Configuration Information section below.

  5. (Optional) Select yes for DHCP, then press Enter if you want to use a DHCP server to dynamically assign an IP address to TRAP.

  6. Enter your choice of a password at the password prompt, then press Enter. Be sure to record it in the Managing TRAP Configuration Information section below.

  7. Reenter your password when prompted, then press Enter to save your changes and to exit the program. Note that when you enter and reenter your password, no keystrokes are displayed on the console; however, the password is being entered.

  8. Enter your admin email address, then press Enter.

  9. Scroll through the list of available time zones to find your applicable code. Enter n (for “next”), then press Enter to scroll through the next series or p (for “preceding”), then press Enter to scroll through the preceding series. Codes applicable to the mainland United States time zones are

    US/Eastern: 509
US/Central: 507
US/Mountain: 513
US/Pacific: 514

  10. Enter either the text string or the numeric value for the time zone, then press Enter.

  11. Enter your NTP server name at the NTP server prompt if you want to use such a server or enter No if you do not, then press Enter.
  12. Review your information. To change an answer, enter the relevant step number, then press Enter. To proceed, press Enter to save any changes and to exit the Wizard.

Determining the DHCP Address

Use the steps below to display the system’s IP address if DHCP was selected during the “initial configuration” discussed above.

  1. Log in to the Threat Response/TRAP console.
  2. Enter enable at the hostname prompt, then press Enter.
  3. Enter show interfaces eth0 at the hostname# prompt, press Enter.
  4. Record the IP address in the Managing TRAP Configuration Information section below because it is not possible to copy and paste it from the console script window.
  5. Type Exit to log out of the console.

Managing TRAP Configuration Information

This section provides an opportunity to manage important TRAP configuration information efficiently.

Gather the following information Record the information here
Hostname
VM Username
VM Password
TRAP IP Address
Hostname of Virtual Machine

License Installation

Use the steps in this section to install the TRAP License.

  1. Open the Proofpoint Welcome email containing your license.
  2. Locate and copy the license key to use in step 7 below.
  3. In the browser window, enter https://ptr_ip_address:8080.

  4. Provide the Proofpoint username and password then press Enter to open the Proofpoint Appliance Management Console window.

    Use the IP address assigned to the TRAP virtual machine in the Deploying the Virtual Machine section earlier in this chapter or go to the Managing TRAP Configuration Information section if you recorded the IP address there.

  5. Click the Setup tab then click Licensing in the left menu.

  6. Paste the Proofpoint license key you copied from the Proofpoint Welcome email (in step 2 above) into the text field below Add New License.
  7. Click Add Licenses then click Save in the top right corner of the window to validate and save the license.

Note

TRAP licenses have expiration dates. A month before your license expires, TR opens a pop-up message each time you log in reminding that your license will expire soon. Once it expires, you will not be able to log in until you enter a new license in the Proofpoint Appliance Management console window. To renew your license, contact Sales at 1-877-634-7660.

Logging Into TRAP

Use the steps in this section to run TRAP in a browser window.

  1. Open a supported browser.

  2. Navigate to https://ptr_ip_address to open the Proofpoint TRAP login window.

    This is the IP address assigned to the TRAP virtual machine when you set up your virtual environment in the Deploying the Virtual Machine section of the previous chapter.

  3. Enter your username and password into TRAP login window.

    This is the admin password you created for yourself when you set up the virtual machine in the Deploying the Virtual Machine section and recorded in the section, Managing TRAP Configuration Information.

  4. Click Login to open the TRAP Dashboard window. Initially, this window will be empty of data.

Active Directory and LDAP

LDAP / Active Directory support enables TRAP to map users to alerts that it receives, and to retrieve details about user accounts, such as location and group membership. The configuration is broken up into the two sections below.

Server Configuration

Create a server listing in TRAP to tell the systems which LDAP server to query for user information. Multiple servers can be created.

  1. Log in to TRAP.
  2. Navigate to System Settings > Contextual Data Sources > LDAP Servers.
  3. Click the blue Add (+) button next to LDAP Servers to bring up the New LDAP Server panel.
  4. Set the following fields:
    • IP/Hostname: <ldap_hostname_or_ip>
    • Port: <ldap_port>
    • SSL: Check to enable SSL encryption
    • Search Base: <directory_path> (e.g., DC=domain,DC=com)
    • Requires Authentication (Optional)
  5. Save changes.

Note

The authentication username may vary in syntax depending on your directory server’s authentication requirements. In most cases, the full, distinguished name (DN) for the user should be used as the username.

LDAP attribute selection

TRAP allows you to configure the user attributes that will be pulled from your LDAP / Active Directory server. By default, the system is configured to collect and display the following common user attributes:

  • Display Name
  • Telephone Number
  • Mobile Number
  • Email Address
  • Company
  • Department
  • Street Address
  • City
  • State
  • Country
  • Group Memberships

image

To add, or remove items from this list, use the steps below.

  1. Log in to TRAP.
  2. Navigate to Settings > Contextual Data Sources > Displayed User Attributes.
  3. Select attribute that you would like to be displayed for users.
    • Place a checkmark next to items in Available Attributes to select them
    • Uncheck items in Selected Attributes to remove them
  4. Re-order the Selected Attributes by dragging-and-dropping items into your preferred order. This is how they will be displayed in the UI.
  5. Click Save.