Threat Response - Installation Guide

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

Full documentation access

Threat Response documentation portal is accessible to Threat Response customers only. If you are accessing this page directly through the link, all the other content will be protected. To access all available documentation, please, perform the following steps:

1. Log in to Threat Response
2. At the top bar click on the ? link
3. You will be seamlessly redirected to the portal with full documentation access

Threat Response Requirements

Virtual Machine Requirements

Threat Response 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 E1000 but VMXNET3 is also supported)

For administration and general usage, Threat Response 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.

Service accounts

Threat Response interfaces with other systems to receive alerts, perform user lookups, and update systems as part of its response capabilities. It is recommended, but not required, to use a service account for these interactions. Below is a list of systems and services that you may want to create a service account for.

  • Event Sources (any detection systems where an API account is used)
  • Enforcement Devices (firewalls and proxies)
  • LDAP / Active Directory
  • Read-only permissions required for user lookups
  • Domain Admin permissions required for response behaviors (optional)

Note

For a trial run, any administrative-level account with read / write permissions will suffice in most cases.

Required ports for network communication

Threat Response 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 Threat Response and other systems.

Port Direction Purpose
TCP/8080 Admin Network to Threat Response Appliance Management Console
UDP/514 “Any” to Threat Response To receive alerts sent via syslog
TCP/443 “Any” (internal) to Threat Response Threat Response GUI & HTTPS alert liisteners
TCP/443 Threat Response to “overcast.proofpoint.com” Communication with Overcast for Alert Enrichment
TCP/443 Threat Response to “overcast.proofpoint.com” Communication with Overcast for SmartSearch export from the Admin Portal
TCP/443 Threat Response to “tap-api-v2.proofpoint.com” Pulling alerts from TAP
TCP/443 Threat Response to “saasisolation.com” and “proofpointisolation.com” Rendering suspicious web pages from abuse-reported messages using Proofpoint Browser Isolation
TCP/443 Threat Response 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/22 & TCP/443 Threat Response to Network Devices Used to push updates to Devices
TCP/22 Admin Network to Threat Response SSH access to CLI
UDP/137 Threat Response to Endpoint PCs Used to gather NetBIOS information from PCs
TCP/445 Threat Response to Endpoint PCs Used for PC Data Collection
TCP/7820 Threat Response to Endpoint PCs Used to communicate with the Remote Agent
TCP/389 Threat Response to LDAP Server Query LDAP for user details
TCP/636 Threat Response to Secure LDAP Server Query Secure LDAP for user details
TCP/25 Threat Response to Mail Server Notifications & alerts via email
UDP/53 Threat Response to DNS Server DNS services
UDP/123 Threat Response 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

Domain Controller Agent requirements

In order to associate usernames to alerts as they are received, Threat Response must interface with a system that enables it to build a table of username-to-IP mappings. To do this, Threat Response employs a Domain Controller agent (DC Agent).

The DC Agent can be deployed in one of two ways:

  • Directly on all Domain Controllers used for authentication
  • A single instance can be deployed on a stand-alone Windows system to remotely query all Domain Controllers used for authentication

Domain Controller agent supports the following platforms:

Platform Version
Windows Server Supported: 2008 (32-bit & 64-bit), 2012 (64-bit)

Note

For detailed instructions on how to install and operate domain controller agent, please, refer to the following section Installing and configuring domain controller agent.

Supported browsers

Threat Response supports the following browsers:

Browser Version
Google Chrome 51.0 +
Mozilla Firefox 47.0 +

Supported hypervisors

Today Threat Response supports the following virtualization environments:

Building Threat Response VM

Importing Threat Response to VMware

This example shows how to configure the Proofpoint Threat Response 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 Threat Response 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 Threat Response OVA file.

  5. Click Open, then click Next.
  6. Verify the OVF Template details then click Next.
  7. Review the Threat Response 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 Threat Response 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 Threat Response virtual appliance.

  13. Review the settings and click Finish to begin installing Threat Response.

    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 Threat Response 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 Threat Response 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 Threat Response 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 Threat Response 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 Threat Response Configuration Information

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

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

License Installation

Use the steps in this section to install the Threat Response 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 Threat Response virtual machine in the Deploying the Virtual Machine section earlier in this chapter or go to the Managing Threat Response Configuration Information section if you recorded the IP address there.
  5. Pre-Version 5.0: Click on Setup and then click on Licensing in the left-hand menu. Version 5.0 and beyond: Click on Licensing under System Info in the left-hand menu.
  6. Paste the Proofpoint license key, copied from the Proofpoint “welcome” email in Step 2 above, into the field below Add New License.
  7. Pre-Version 5.0: Click on Add New License(s) and then click on Save in the top right-hand corner of the window to validate the license. Version 5.0 and beyond: Click on Register a New License and then wait for the system to validate the license.

Note

Threat Response 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 Threat Response

Threat Response is the GUI tool associated with Threat Response. Use the steps in this section to run Threat Response in a browser window.

  1. Open a supported browser.

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

    This is the IP address assigned to the Threat Response 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 Threat Response 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 Threat Response Configuration Information.

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

Configuring proxy settings

If a proxy is used on your network to access the Internet, use the steps below to configure Threat Response to use the proxy.

  1. Log in to Threat Response.
  2. Navigate to System Settings > Appliance Configuration > Proxy Configuration.

  3. Configure Proxy settings…

    • Check Use proxy server to enable the proxy
    • Host: <proxy_ip_or_hostname>
    • Port: <proxy_port>``
    • Requires Authentication (Optional)

  4. Click Save Settings.

  5. Click Test Proxy Settings to confirm that Internet routing works.

Defining internal networks

In order to properly determine attack direction, Threat Response needs to know which IP subnets are used on your network. Use the steps below to configure the Internal Networks on Threat Response.

  1. Log in to Threat Response.
  2. Navigate to System Settings > Appliance Configuration > Local Networks.
  3. Enter any public IP ranges used locally on your network into the User Defined Networks box. You should enter one entry per-line, and the list does support CIDR notation.

Note

The common, RFC 1918-defined private IP ranges are assigned as internal networks by default, and do not need to be entered into this list.

Domain Controller Agent (DC agent)

The Threat Response DC Agent utilizes the domain controller’s event log to track user logins across the network. By monitoring the event log, the DC Agent can track the IPs from which users have logged in. This information is then relayed back to Threat Response, thus enabling Threat Response to associate usernames with security alerts that are received.

Step 1. Preparation for deployment

The Threat Response DC Agent references the domain controller’s record of user login events to build a list of user-to-IP mappings for Threat Response. Before installing the DC Agent, you must ensure that the domain controller is configured to record login events and that the DC Agent has the necessary access rights to read the domain controller’s event log.

Enable the Logon Audit in Active Directory

Audit logging must be enabled on your domain controller to successfully track logon events. These events are recorded in the domain controller’s event log where the DC Agent references them.

  1. Open the Group Policy Management console.
  2. Locate the Domain Controllers organizational unit within your domain.
  3. Right-click Domain Controllers and then select Create a GPO in this domain, and Link it here…:

small

  1. Give the new GPO a name and then click on OK.
  2. Right-click the new GPO and then select Edit.
  3. Navigate to Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > Audit Policy.
  4. Double-click Audit account logon events to open the Properties window.
  5. Check off the box next to Success to enable the audit of successful logon attempts.
  6. Apply the changes.

small

Enable User-IP tracking in Threat Response

User-IP tracking must be enabled in Threat Response prior to installing the agent.

To enable user-IP tracking:

  1. Log in to Threat Response.
  2. Navigate to System Settings > Contextual Data Sources > DC Agent Configuration.
  3. Check off the box to enable User-IP Tracking.
  4. Save the changes.

image

Note

The Expire Mapping setting can be adjusted to specify the length of time that a username is associated with an IP address in Threat Response. The default is one hour.

Step 2. Domain Controller Agent installation

The Threat Response DC Agent needs to be installed so that it can access the event log for all the domain controllers used for user authentication. Two deployment options are available to install the DC Agent in your environment.

The table below compares the deployment options:

Installation type Characteristics
Direct Installation on DCs - An instance must be installed on all the domain controllers
- Upgrades to the agent must be performed on each domain controller.
Remote Installation - A single instance of the DC Agent can remotely query multiple domain controllers.
- A service account is needed for the DC Agent.
- Windows RPC must be enabled between the DC Agent and domain controller.
Hybrid Installation - A mixture of direct and remote installation is used.

Download the DC Agent

The DC Agent can be downloaded directly from Threat Response. To download the agent, you can visit Threat Response from the machine onto which you are installing the agent or you can download it to your own system and then copy it to the other machine.

To download the DC Agent:

  1. Log in to Threat Response.
  2. Navigate to System Settings > Contextual Data Sources > DC Agent Configuration.
  3. Click on the link to Download Domain Controller Agent.

image

Note

Once DC agent is installed, you must copy and paste Threat Response’s unique Entrypoint URL to the DC Agent. While on the Data Collection page, click on Show Entrypoint URL… and copy the URL that is displayed. (It will be used in the next section.)

Install and Configure the DC Agent

With the agent downloaded and copied to the destination machine, you can now run the installer and complete the DC Agent configuration.

Installing the DC Agent:

  • Double-click the DC Agent MSI package to begin the installation.
  • Select the installation path and click on Next.

small

  • Following the installation, click on the checkbox to Launch Configuration Utility and then click on Finish.

small

Step 3. Domain Controller Agent configuration

DC Agent Configuration Utility

The DC Agent configuration utility is used to specify the Threat Response systems with which the DC Agent will communicate. You must paste the Entrypoint URL (copied in ”Step 1”) into the DC Agent configuration.

To configure the DC Agent:

  • Run the DC Agent configuration utility from Start Menu > Programs or run DcAgentSrv.exe from the installation directory.
  • Click on the plus [+] button to add a new Threat Response instance to the configuration.

small

  • Configure the following fields:
    • Name: Provide a name for the appliance (a label to identify the system).
    • URL: Paste the Entrypoint URL (from “Step 2”) into the URL field.
  • Click on Save to save your changes and to close the configuration utility.

Remote configuration

If you are using the remote installation option rather than deploying directly on your domain controller, then you must complete the following additional steps after running the configuration utility.

Add the domain controllers to the DC Agent configuration file:

  • Run Notepad as an administrator and open the DC Agent configuration file.
    • 32-bit OS: C:\Program Files\Proofpoint\DcAgent\DcAgentSrv.exe.config
    • 64-bit OS: C:\Program Files (x86)\Proofpoint\DcAgent\DcAgentSrv.exe.config
  • Locate the <sources> tag in the configuration file.
  • Create new entries below the <sources> tag for each of your domain controllers.
Example: <add name="dc-01" host="dc01.example.com"/>

Note

You should create an entry for each domain controller against which users authenticate. Note that the “host” value must be able to be resolved and routed from the system hosting the DC Agent.

small

  • Save the file and exit Notepad.

As a next step you need to create a service account for the DC Agent:

  1. Create a service account in Active Directory for the DC Agent.
  2. Add this account to the Event Log Readers group in Active Directory. This enables the agent to remotely access the event logs on the domain controllers.
  3. Configure the DC Agent service to run as the service account.
    • Open the Services console in Windows.
    • Right-click the Proofpoint Domain Controller Agent service and then select Properties.
    • In the Log On tab, set the DC Agent service to run as your service account.
    • Click on Apply to save your changes.

small

Step 4. Domain Controller Agent restart

With the configuration in place, it is advisable to restart the DC Agent service to ensure that no warnings are recorded in the server’s event logs.

To restart the DC Agent service:

small

  1. Open the Services administrative console in Windows and locate the Proofpoint Domain Controller Agent service.
  2. Click on Restart to restart the service.

To confirm that the service started successfully:

small

  1. Open the Windows Event Viewer.
  2. Navigate to Windows Logs > Application.
  3. Review Proofpoint DC Agent entries for successful startup events.

With the service successfully started, Threat Response begins receiving user-to-IP mappings from the DC Agent and associate usernames with the alerts that it receives.

Reviewing the Event Viewer for Startup Warnings

If any warnings are shown in the Event Viewer, they should be reviewed to determine the cause.

small

Warnings can be generated for a number of reasons. They are typically seen when the DC Agent is either unable to reach Threat Response or is unable to connect to the domain controllers (in a remote configuration). To settle connectivity issues, ensure that the system running the DC Agent can resolve any hostnames used in the configuration. Furthermore, confirm that any firewalls between the systems are configured to allow this traffic to pass.

The DC Agent uses HTTPS to communicate with Threat Response. You can quickly confirm connectivity to Threat Response by opening a browser and connecting to the Entrypoint URL from “Step 1.” In the DC Agent’s remote configuration, it uses Windows RPC to query the domain controllers.

Active Directory and LDAP

LDAP / Active Directory support enables Threat Response 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 Threat Response to tell the systems which LDAP server to query for user information. Multiple servers can be created.

  1. Log in to Threat Response.
  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

Threat Response 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 Threat Response.
  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 Settings.