Configuring Forescout Connectors

Use the Forescout connector to perform Respond actions on systems registered in your Forescout account. Forescout connectors in Stellar Cyber are used for response only, not collection of event data. This connector is supported with Forescout v8.2.2 and Forescout's EyeExtend Connect Module v1.9.0 or later. Refer to the following documentation, if needed, during this procedure:

https://www.forescout.com/company/resources/forescout-eyeextend-connect-app-builders-guide/

The devices you want to use with this connector must be registered in the Forescout Enterprise Console (CounterACT devices) and associated with the application module that will be creating for communication to Stellar Cyber.

Connector Overview: Forescout

               Let us know if you find the above overview useful.

Adding a Forescout Connector

To add a Forescout connector:

1. Set up Stellar Cyber access in the Forescout Console
2. Adding the connector in Stellar Cyber
3. Test the Connector
4. Use the Connector

Use our example as a guideline, as you might be using a different software version.

Preparing for Setup

Perform the following steps on the system from where you will be running the Forescout Enterprise Console:

1. Open a browser and access the Forescout Customer Support portal Downloads page (https://forescout.force.com/support/s/downloads).

2. Download the eyeExtend Connect Module, v1.9.0 or later. This .fpi file allows you to install a web API connector to configure for communication with Stellar Cyber.

   

3. You will also need an eyeExtend Connect app to enable Stellar Cyber to trigger an action using the Connect Web API framework. A sample app is available on GitHub, or you can create your own. The remainder of these steps presume you are using the sample from GitHub. Access one of the following pages to download the ActionAPI.zip file:

   • Direct download: https://github.com/Forescout/eyeExtend-Connect/raw/master/Connect-training-demo/ActionAPI/ActionAPI_v1.zip

   • Additional information: https://github.com/Forescout/eyeExtend-Connect/tree/master/Connect-training-demo/ActionAPI

4. Before you proceed, you will need to make note of the following information to use throughout this procedure.

   • Host address for your Forescout Enterprise Manager and Connecting CounterACT Device for the Forescout App
     (the CounterACT "device" is a middleman that forwards queries and requests to and from third-party instances)

   • An administrative login and password to that host console

   • The cliadmin password to use with a shell login to that server

   • You will create and use the following on both the Forescout side and Stellar Cyber side:

     • app module name

     • username for app module

     • password for that user

Setting up the Stellar Cyber App in Forescout

1. Log into the Forescout Enterprise Console as an administrative user.

   

2. Use the Help>About menu to verify that your Forescout version is v8.2.2, or later.

3. From the Forescout Console, open the Tools > Options menu.

4. In the Options dialog that opens, select the Modules block.

   

5. Click the blue Install button to begin the process of loading and installing the web connector file you downloaded above.

   

6. The install dialog displays. Check the box to Agree to the licensing terms, then click Install.

   The installation begins immediately and cannot be interrupted or canceled.

7. When the installation completes, click the Close button and return to the Options>Modules window. Expand the Connect row and make sure all the services are running.

   

8. From your local system, use a terminal window to access the command-line of the Forescout server you are accessing with the Forescout Enterprise Console, above. Use the username cliadmin, with that Forescout server address, and the password you made note of in the previous section:

   Last login: Thu Jul 15 19:44:19 on ttys001
   
   The default interactive shell is now zsh.
   To update your account to use zsh, please run `chsh -s /bin/zsh`.
   MacBook-Pro:~ dstarr$ ssh cliadmin@10.38.2.101
   cliadmin@10.38.2.101's password: 
   Last login: Thu Jul 15 19:47:19 2021 from 10.37.0.2

9. Use the cli to temporarily enable installation of the ActionAPI.app downloaded from GitHub, above:

   cliadmin@forescountem01>fstool allow_unsigned_connect_app_install true
   fs.eyeextend.connect.allow.unsigned.install=true
   cliadmin@forescountem01>exit
   Exiting...
   Connection to 10.38.2.101 closed.

   This command, as noted in the Forescout EyeExtend Connect documentation, is required to import and run unsigned applications. Refer to https://www.forescout.com/company/resources/forescout-eyeextend-connect-app-builders-guide.

10. Return to the Forescout Console's Options dialog and access the Connect > Configuration pane. You can access this two ways:

    • Click Modules from the navigation list, then expand the Connect module and select the Connect row element, then click Configure.

    • Click Connect directly from the navigation list at the left of the dialog.

    

11. When the Connect configure pane is displayed, click Import and select the ActionAPI.zip you had downloaded from GitHub, above, or your custom module.

12. This step triggers a warning regarding invalid or missing signatures. Click OK to continue.

13. When the import process has completed, click Close from the import dialog.

14. A dialog now displays that allows you to specify the username and password for this module to communicate with Stellar Cyber. Enter the username and password you want to use, and make note of those for use with the Stellar Cyber connector. Then click OK.

    

15. A system description dialog now opens, allowing you to optionally define custom sets of devices to associate with this application. Click Add to create at least one setup definition. In the dialog that displays, specify a name for the setup, then click Next.

16. The second pane allows you to specify which CounterACT Devices to associate with this app. After selecting a specific device or all of them, click Finish. The new application is added to the Connect pane. Click Apply to save the configuration.

17. Make note of the module Name displayed in the Connect dialog.  This was loaded from the file you imported and is used when you configure the Stellar Cyber connector.

You are now ready to configure your Stellar Cyber Forescout Connector.

Adding the Connector in Stellar Cyber

With the configuration information handy, you can add the Forescout connector in Stellar Cyber:

1. Log in to Stellar Cyber.

2. Click System | Integration | Connectors. The Connector Overview appears.

   

3. Click Create. The General tab of the Add Connector screen appears. The information on this tab cannot be changed after you add the connector.

   

   The asterisk (*) indicates a required field.

4. Choose Endpoint Security from the Category drop-down.

5. Choose Forescout from the Type drop-down.

6. For this connector, the supported Function is Respond, which is enabled already.

7. Enter a Name.

   This field does not accept multibyte characters.

   The name must match the name of the module you imported in the previous section.

8. Choose a Tenant Name. The Interflow records created by this connector include this tenant name.

9. Choose the device on which to run the connector.

10. Click Next. The Configuration tab appears.

    

    The asterisk (*) indicates a required field.

11. Enter the Hostname or IP. Do not include https in the Hostname. This is the address of the Forescout Connecting CounterACT Device; it forwards all the queries and requests to and from Stellar Cyber. (Forescout recommends that you not use the address of the Enterprise Manager Console.) The following parameters are the name and authentication attributes you used when you imported the action module.

12. Enter the Username you noted earlier.

13. Enter the Password you noted earlier.

14. Enter the App Name you noted earlier.

15. (Optional) App Action JSON. If there is a standard response action you want to take with this connector, or a default JSON parameters you want saved, you can add that now. The JSON content will be saved for use by anyone using the connector to run an External Action | Update Device action from the Event Details pane. You can alternatively enter JSON at the time you run the action but that JSON is not saved. For syntax guidance, refer to the section: Updating Devices with the Forescout Connector.

16. Click Next. The final confirmation tab appears.

    

17. Click Submit.

The new connector is immediately active.

Testing the Connector

When you add (or edit) a connector, we recommend that you run a test to validate the connectivity parameters you entered. (The test validates only the authentication / connectivity; it does not validate data flow).

For connectors running on a sensor, Stellar Cyber recommends that you allow 30-60 seconds for new or modified configuration details to be propagated to the sensor before performing a test.

1. Click System | Integrations | Connectors. The Connector Overview appears.

   

2. Locate the connector that you added, or modified, or that you want to test.

3. Click Test at the right side of that row. The test runs immediately.

   Note that you may run only one test at a time.

Display sample messages...

Success !

Failure with summary of issue: Show More example detail:

 

Updating Devices with the Forescout Connector

When an event has occurred on a host known to the Forescout connector, you can use this connector to perform an action on that host.

1. Access the Event Details Display:

   1. Click Investigate | Threat Hunting. The Interflow Search tab appears.

   2. Select the Indices for Traffic.

   3. Select an event and click the More Info button.

2. In the dialog that displays, click External Actions | Endpoint and choose Update Device.

   

3. From the Connector menu, select the Forescout connector.

4. The Target menu lists the addresses associated with this event. Select the host on which you want to run the Forescout connector update action. The target can be one of these: Source Host, Destination Host, Source MAC, or Destination MAC. The Target Value is updated automatically from the event data. These two fields are required default parameters for the Forescout action and should not be specified in the JSON added in the next step.

5. If your connector was created with default JSON, you can customize it now, or skip this step. Populate the JSON field with the action you want the connector to transmit to the Forescout app configured in the beginning of this procedure. Note that Stellar Cyber verifies general format of the JSON, not the logic. Following is an example based on ActionAPI's supported JSON properties:

   {
   "connect_actionapi_vlan_assign":true, 
   "connect_actionapi_vlan_assign_id":"vlan233"
   }

   Do not include the IP or MAC address, as that is added automatically based on your selection in the previous step. The JSON that is transmitted to Forescout will include the IP or MAC and the property tag, similar to the sample below.

   {
   "mac":"009027390a7c",
   "properties":{
   "connect_actionapi_vlan_assign":true, 
   "connect_actionapi_vlan_assign_id":"vlan233"
   }
   }

   Refer to Forescout documentation for supported fields and syntax details.

6. Click Submit. The connector runs the update action one time.

For more information on working with the events and the actions on them, refer to Understanding Event Details.