Getting Started

Review the steps to integrate URL Intel into your app

Introduction

The URL Intel service must be enabled from the Pangea Console before use. Make sure you have access to the Pangea Console and you’ve created a project.

Create a token

Expand for details

Create a token so that you can access the URL Intel endpoints:

1. Go to the Pangea Console and click URL Intel in the left-hand navigation menu. The URL Intel Overview page will appear.
2. On the URL Intel Overview page, you'll see a notification asking you to set a service token. Click Create new token toward the bottom right side of your screen.
3. You’ll be prompted to create a token. Enter a Token name and select an Expiration Date. You may also create a token for all Intel services, if you wish.
4. Once configured, the token is available in the Tokens section of the URL Intel Overview page.

Select a provider

Expand for details

Providers can be selected as default in the Pangea Console. Setting a provider as default in the Pangea Console means your API request calls will use this provider, unless another provider is specified as part of your API request.

To select a provider as default for an API:

1. Go to the Pangea Console
2. On the left-hand navigation menu, select URL Intel
3. Go to Settings
4. Click Set as default for your preferred provider

tip

You can override the default provider by specifying their name in the provider field when making an API request to the reputation endpoint. This is helpful if your default provider returns a verdict of Unknown and you want a second opinion from another provider.

Configure your app for communication with the Pangea service​

For your app to communicate with the Pangea service, you must put the values of the following Configuration Details into the PANGEA_INTEL_TOKEN and PANGEA_DOMAIN environment variables:

• token
• domain

These Configuration Details are created when you enable URL Intel and can be found in the Overview section under URL Intel.

Set environment variables

To set each variable in bash:

export PANGEA_DOMAIN="yourServiceDomain"

export PANGEA_INTEL_TOKEN="yourAccessToken"

Test the service

The interactive URL Intel API Reference allows you to test API endpoints from the documentation. This is an easy way to play around with different URLs and providers to see what kind of data is returned.

tip

Make sure you set a token in the Pangea Console so you can test data in the API Reference.

Make a reputation call

Use the /reputation endpoint to make an API call and return URL details. In this example, we are using the following parameters:

• url
• provider

curl -sSLX POST 'https://url-intel.'"$PANGEA_DOMAIN"'/v1/reputation' \
-H 'Authorization: Bearer '$"PANGEA_INTEL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"provider":"crowdstrike","url":"http://113.235.101.11:54384"}'

Receive a response

The URL Intel service will send a JSON response, like the one below:

{
  "request_id": "prq_yg7qpjltioi63bb3b4gydatscmdsulta",
  "request_time": "2022-12-20T22:55:27.734018Z",
  "response_time": "2022-12-20T22:55:27.761741Z",
  "status": "Success",
  "summary": "Url was found",
  "result": {
    "data": {
      "category": ["Not Provided"],
      "score": 100,
      "verdict": "malicious"
    }
  }
}

Understand and review results

The API response sent by URL Intel includes various fields and values; however, the ones listed below give you the most information about the disposition of a URL. To learn about more response fields, visit the URL Intel API Reference.

verdict	The verdict normalized categorization as interpreted by the data returned by the third party provider. There are four possible verdicts: Benign - Confirmed as non-malicious Suspicious - Associated with actions that are malicious Malicious - Confirmed as malicious Unknown - No data
score	The normalized score as interpreted by the data returned by the third party provider. Scores are associated with the verdict values listed above: 0 = Benign 1 - 99 = Suspicious 100 = Malicious -1 = Unknown
summary	A summary of the various categories associated with a URL, which help illustrate why a URL received a particular verdict.
category	Indicates the category associated with the URL (e.g. Adware, Malware). This field may return more than one category and may, at times, not be populated.
raw	Raw data returned by the provider you specified in the API request. You can investigate the raw data if its meaningful to your use case or if you want to supply it to your users. You must set the raw field to true to receive this data.

Share your implementation

Reach out to the Pangea community on our

Discourse to let us know how you've integrated URL Intel into your application.

Was this article helpful?

Contact us