Configuring a Custom AlienApp for Use with Your USM Anywhere

AT&T Cybersecurity provides the opportunity to configure your own custom AlienApps to better monitor activity in your USM Anywhere environment. You can use custom AlienApps to extend the threat detection and response capabilities of the USM Anywhere platform according to your needs. Import data from products and services that use a Representational State Transfer (REST) API by configuring your custom AlienApp using basic authentication, an API key, or OAuth2.

Important: Custom AlienApps connect using dynamic IP addresses. AT&T Cybersecurity recommends that you allow AlienApps outbound access across all IP addresses.

To configure a custom AlienApp

  1. Go to Data Sources > AlienApps > Custom Apps.
    The My Custom Apps page lists all of your custom apps and allows you to create a new custom app.
  2. Click Add Custom App to begin creating your new AlienApp.
  3. On the App Information and Mapping page, give your AlienApp a name and some identifying information.
    Use this page to enter information for your app, such as name, description, icon, and category.

    • App Name: Provide a unique name for your AlienApp.

    • (Optional.) App Description: Describe the new AlienApp's intent or functionality.

    • AlienApp Category: Tag your app with a category, which will help you organize your AlienApps. You can search for AlienApps by category in the Custom App main page.

    • (Optional.) Logo: You may import a logo for this AlienApp.

  4. Click Save & Next to save your new AlienApp and begin configuring it.

  5. Configure the authentication credentials your AlienApp will use to connect to the third-party application. When you have finished entering your credentials, confirm them by clicking Test Connection.

    Important: This is entirely dependent upon your third-party application. Be sure to make selections in line with the authentication method required by your third-party application.

    Configure the credentials that your custom AlienApp will use to connect to your third party resource.

    1. In the Auth Type drop-down list, select API Key.

    2. Enter the necessary connection information for your AlienApp to connect to the API:

      • Event URL: The destination address for the API connection.

      • Header Name and Header Value: The API authentication key-value pair for your AlienApp to use when connecting to the third-party API.

      • Request Method: Select GET, POST, or PUT.

    3. Click Test Connection to verify the connection information you have just entered.

    1. In the Auth Type drop-down list, select Basic Auth.

    2. Enter the necessary connection information for your AlienApp to connect to the API:

      • Event URL: The destination address for the authenticated connection.

      • Username and Password: The authentication credentials for your AlienApp to use when connecting to the third-party API.

      • Request Method: Select GET, POST, or PUT.

    3. Click Test Connection to verify the connection information you have just entered.

    1. In the Auth Type drop-down list, select OAuth2.
    2. Enter your Event URL.
    3. Use the OAuth2 Auth Type drop-down to select your authentication type, and then enter the information required by that authentication type:
      • Basic: Configure the app to authenticate with a username and password.
      • Client ID and Client Secret: Configure the app to authenticate with a client ID and secret.

    4. Enter the necessary connection information for your AlienApp to connect to the API:

      • Client ID and Client Secret: The authentication credentials for your AlienApp to use when connecting to the third-party API if using client ID and client secret authentication.
      • Username and Password: The authentication credentials for your AlienApp to use when connecting to the third-party API if using basic authentication.
      • Access Token Endpoint: The access token endpoint for your OAuth2 connection.
      • Refresh Token Endpoint: The refresh token endpoint for your OAuth2 connection.
      • Content Type: The appropriate content type for your connection.
      • Request Method: Select GET, POST, or PUT.

    5. Click Test Connection to verify the connection information you have just entered.

  6. Once your credentials have been verified, click Save & Next.

    7. Important: The credentials you have entered will be validated when you click Test Connection. If they cannot be verified at this step, you must correct them and ensure they are validated before moving on to the next step.

  7. Represent the API configuration your custom AlienApp should expect from your third-party resource.
    Represent the API configuration your custom AlienApp should expect from your third party resource.

    Warning: This is entirely dependent upon your third-party application. Be sure to make selections in line with the authentication method required by your third-party application.

    1. Specify the return format, pagination methods, date format, and output format (JSON, XML, or CEF).

    2. Configure the required values your API call may require. When the field is nested in the return under parent fields, use a period to separate parent and child fields.

    3. Configure Headers, Params, and Body as required by the third-party application's API.

    Note: If there are any fields you want to be able to filter against, you must configure them under Params.

    Click Next to continue.

  8. USM Anywhere uses the configuration details from the previous two steps to connect with your third party and extract data fields found in the logs they send. Use this page to configure the mapping details between the third-party application's data fields and fields in USM Anywhere by dragging and dropping from the detected fields to their matching fields in USM Anywhere.
    Configure which USM Anywhere data fields map to which fields discovered in your source API.

    • Found Parameters: Fields on the left are extracted from logs fetched from your third-party application.

    • USM Anywhere App Fields: Fields on the right are the standard USM Anywhere data labels. Users can map multiple found parameters to the same USM Anywhere app field.

      • Important: See Event Keys descriptions to help you match extracted fields with standard USM Anywhere data fields.

    Click Next to continue.

  9. Select which log fields to include in the Event Details for events your new AlienApp will generate.
    Choose which of the data fields you previously mapped will appear in the Event Details for events your new app will generate.

    Click Save & Next to continue.

  10. Use the Preview screen to review your custom AlienApp's configuration.
    Use this preview screen to check the details of your new custom AlienApp, including expanding the data source details.

    You can use the Back button to navigate to any previous page and make changes.

  11. Once you have finalized your AlienApp details and configuration, click Save & Close to finish creating your new AlienApp.

After you have finalized and created your custom AlienApp, you can continue to make changes or refine its configuration by returning to the Custom Apps page and opening your AlienApp for editing.