Bitsight v1.0.0 Plugin for Risk Exchange

This document explains how to configure the Bitsight v1.0.0 plugin with the Risk Exchange module of the Netskope Cloud Exchange platform. This plugin fetches companies and their respective Security Rating from the Bitsight platform. It retrieves first-party companies from the Security Performance Management > Organization > My Company List page, and third-party companies from the Continuous Monitoring > Portfolio Risk > Companies List page. This plugin also support performing Add a company to a tier and Remove a company from a tier actions on Bitsight.

Netskope normalization score calculation = ((Security Rating – 250)/(900-250))) x 1000.

Prerequisites

To complete this integration, you need:

A Netskope tenant (or multiple, for example, production and development/test instances).
A Netskope Cloud Exchange tenant with the Tenant plugin and Risk Exchange module already configured.
Connectivity to Bitsight platform.
Access to generate the User API Token and pull companies.
Connectivity to the following hosts:

CE Version Compatibility

Netskope CE v5.1.0

Bitsight Plugin Support

This plugin is used to fetch companies and their respective Security Rating from the Bitsight platform. It also performs actions, like Add a company to a Tier and Remove a company from a Tier.

Type of data pulled	Companies
Actions Supported	Add a company to a Tier Remove a company from a Tier

Mappings

Mappings are used to view the pulled companies and their respective details. Fields mapped during plugin configuration will be visible on the Records page after the data is pulled. Here are the suggested mappings that should be used while configuring the plugin.

Pull Mapping

Plugin Field	Expected Datatype	Suggested Field Name	Suggested Field Aggregate Strategy
Company GUID	String	CompanyGUID	Unique
Security Rating	Number	Rating	Overwrite
Company Name	String	Labels	Overwrite
Rating Type	List	RatingType	Overwrite
Primary Domain	String	Domain	Overwrite
Tier GUID	String	TierGUID	Overwrite
Tier Name	String	TierName	Overwrite
Confidence	String	Confidence	Overwrite
Netskope Normalized Score	Number	NormalizedScore	Overwrite

Permissions

Admin, Group Admin, or Portfolio Manager user access can be used for performing actions.
Any user with permission other than National Cybersecurity subscription should be able to pull the companies.

API Details

List of APIs Used

API Endpoint	Method	Use Case
/v2/portfolio	GET	Pull companies
/ratings/v1/tiers	GET	Pull tiers
/ratings/v1/tiers	POST	Create a tier
/ratings/v1/tiers/<tier_guid>	PATCH	Add a company to a tier
/ratings/v1/tiers/<tier_guid>	PATCH	Remove a company from a tier

Pull Companies

API Endpoint: /v2/portfolio
Method: GET
Headers:

Key	Value
Authorization	Basic <Token>
User-Agent	netskope-ce-5.1.0-cre-bitsight-v1.0.0

Parameters

Key	Value	Description
limit	1000	Limit of companies to pull in a page.
rating_lte	900	Rating less than or equal to provided value will be pulled.
offset	0	Offset for pagination, starts with 0.

Sample API Response

{
    "links": {
        "next": "https://api.bitsighttech.com/ratings/v2/portfolio?limit=1&offset=1&rating_lte=900&type=SELF-PUBLISHED",
        "previous": null
    },
    "count": 11,
    "summaries": {
        "my-company": "a940bb61-33c4-42c9-9231-c8194c305db3"
    },
    "results": [
        {
            "guid": "8c40d4e3-3f67-4d49-ab53-251bdf928fb6",
            "custom_id": null,
            "name": "Bitsight Labs",
            "shortname": "AnubisNetworks - Labs",
            "network_size_v4": 438,
            "rating": 590,
            "rating_date": "2025-03-08",
            "added_date": "2025-01-31",
            "industry": {
                "name": "Technology",
                "slug": "technology"
            },
            "sub_industry": {
                "name": "Computer Software",
                "slug": "computer_software"
            },
            "type": [
                "CURATED",
                "SELF-PUBLISHED"
            ],
            "logo": "https://api.bitsighttech.com/ratings/v1/companies/8c40d4e3-3f67-4d49-ab53-251bdf928fb6/logo-image",
            "sparkline": "https://api.bitsighttech.com/ratings/v1/companies/8c40d4e3-3f67-4d49-ab53-251bdf928fb6/sparkline?size=small",
            "subscription_type": {
                "name": "Total Risk Monitoring",
                "slug": "continuous_monitoring"
            },
            "primary_domain": "bitsight.io",
            "display_url": "https://service.bitsighttech.com/app/tprm/company/8c40d4e3-3f67-4d49-ab53-251bdf928fb6/overview/",
            "tier": "542946b6-81cc-44b9-8335-fde802aff7e9",
            "tier_name": "Netskope",
            "life_cycle": null,
            "relationship": null,
            "details": {
                "confidence": "HIGH",
                "is_primary": false,
                "primary_company": null
            }
        }
    ]
}

Pull Tiers

API Endpoint: /ratings/v1/tiers
Method: GET
Headers:

Key	Value
Authorization	Basic <Token>
User-Agent	netskope-ce-5.1.0-cre-bitsight-v1.0.0

Parameters: N/A
Sample API Response

[
    {
        "rank": 1,
        "guid": "542946b6-81cc-44b9-8335-fde802aff7e9",
        "name": "Netskope",
        "description": "This is the test tier created by Netskope.",
        "companies": [
            "a940bb61-33c4-42c9-9231-c8194c305db3",
        ],
        "email_enabled": false,
        "content_subscription_types": [
            "continuous_monitoring",
            "my_subsidiary",
        ],
    },
    {
        "rank": 2,
        "guid": "7f2ffcb1-f1c6-46f5-9d6b-bfcc10d24390",
        "name": "Netskope Tier2",
        "description": "This is the test tier created by Netskope.",
        "companies": [],
        "email_enabled": false,
        "content_subscription_types": [],
    },
    {
        "rank": 3,
        "guid": "bba7ad57-0135-4e92-8694-a31300943f94",
        "name": "Netskope Tier3",
        "description": "This is the test tier created by Netskope.",
        "companies": [],
        "email_enabled": false,
        "content_subscription_types": [],
    },
    {
        "rank": 4,
        "guid": "f2be8a0f-9f62-4020-9e5b-31856e800ba5",
        "name": "testnew",
        "description": "This tier is created by Netskope.",
        "companies": [],
        "email_enabled": false,
        "content_subscription_types": [],
    },
    {
        "rank": 5,
        "guid": "0317e632-c6df-4fef-8017-538b129afffe",
        "name": "testnew2",
        "description": "This tier is created by Netskope.",
        "companies": [],
        "email_enabled": false,
        "content_subscription_types": [],
    },
]

Create a Tier

API Endpoint: /ratings/v1/tiers
Method: POST
Headers:

Key	Value
Authorization	Basic <Token>
User-Agent	netskope-ce-5.1.0-cre-bitsight-v1.0.0

Parameters: N/A
Body:

Key	Value
name	Netskope
description	This tier is created by Netskope.
companies	[]

Sample Request Body

{
    "name": "Netskope",
    "description": "This is the test tier created by Netskope.",
    "companies": [ ]
}

Sample API Response

{
    "rank": 5,
    "guid": "d5d14c16-dc69-4912-97ce-f94e7b9845c1",
    "name": "Netskope",
    "description": "This is the test tier created by Netskope.",
    "companies": [],
    "email_enabled": false,
    "content_subscription_types": []
}

Add Company to a Tier

API Endpoint: /ratings/v1/tiers/<tier_guid>
Method: PATCH
Headers:

Key	Value
Authorization	Basic <Token>
User-Agent	netskope-ce-5.1.0-cre-bitsight-v1.0.0

Parameters: N/A
Body

Key	Value
add_companies	[ <Company GUIDs>]

Sample Request Body

{
    "add_companies": [
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "1111111-2222-3333-4444-555555555555",
        "12345678-1234-1234-1234-123456789012",
        "3e58dbb7-4718-47d2-9ca3-8dc650f512ee"
    ]
}

Sample API Response

{
    "detail": "Saperix Service Provider was added to Netskope.",
    "added": [
        "3e58dbb7-4718-47d2-9ca3-8dc650f512ee"
    ],
    "not_added": [
        "12345678-1234-1234-1234-123456789012",
        "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "1111111-2222-3333-4444-555555555555"
    ],
    "companies": [
        "3e58dbb7-4718-47d2-9ca3-8dc650f512ee"
    ]
}

Remove a Company from a Tier

API Endpoint: /ratings/v1/tiers/<tier_guid>
Method: PATCH
Headers:

Key	Value
Authorization	Basic <Token>
User-Agent	netskope-ce-5.1.0-cre-bitsight-v1.0.0

Parameters: N/A
Body

Key	Value
remove_companies	[<Company GUIDs>]

Sample Request Body

{
    "remove_companies": [
        "3e58dbb7-4718-47d2-9ca3-8dc650f512ee"
    ]
}

Sample API Response

{
    "detail": "Saperix Service Provider was removed from Netskope.",
    "removed": [
        "3e58dbb7-4718-47d2-9ca3-8dc650f512ee"
    ],
    "not_removed": [],
    "companies": []
}

Performance Matrix

These performance readings are conducted on a Large CE Stack with these VM specifications by pulling 500K companies from the Bitsight plugin.

Stack details	Size: Large RAM: 32 GB CPU: 16 Cores
Companies fetched from Bitsight	~50k per minute

User Agent

netskope-ce-5.1.0-cre-bitsight-1.0.0

Workflow

Get your API Token.
Configure the Bitsight plugin.
Add Risk Exchange Business Rule for Bitsight.
Add Risk Exchange Actions for Bitsight.
Validate the Bitsight plugin.

Click play to watch a video.

Get Your API Token

To get your API Token:

Log in to Bitsight, and from Continuous Monitoring, go to Settings > Account.
Under User Preferences, scroll down to User API Token. and copy your API token. This is need to configure the Bitsight plugin.

Configure the Bitsight Plugin

In Cloud Exchange, go to Settings > Plugins and search for the Bitsight v1.0.0 (CRE) plugin box.
Add plugin configuration name and change the sync interval if needed.
Click Next and enter the Configuration Parameters.
- User API Token: Your API Token obtained previously.
- Security Rating: Only the companies with Security Rating less than or equal to the provided Security Rating will be pulled in Cloud Exchange. The value should be an integer between 250 and 900.
- Rating type: Rating type used to pull the companies from Bitsight.
Click Next and select the Entity from the Entity dropdown. The Entity fields can be created from the Schema Editor page, or using the + Add Field option from the field dropdown. Provide the field mapping. For the suggested mappings, refer to the Mapping section.
Click Save.

Add a Risk Exchange Business Rule for Bitsight

In Risk Exchange go to Business Rules and click Create New Rule.
Enter a Rule Name and select the Entity for the Fields configured for the Bitsight plugin. Configure the query based on your requirements.
Click Save.

Add Risk Exchange Actions for Bitsight

The Bitsight plugin supports the following action types:

Add a company to a tier

This action will add a company to an existing or new tier on Bitsight.

Remove a company from a tier

This action will remove the company from an existing tier on Bitsight.

No Action

No action will be performed for this action. You can generate UBA alerts in Ticket Orchestrator by using this action and enabling the Generate Alerts toggle.

Note that you can perform the Netskope related actions on the companies pulled from Bitsight.

Steps to configure the Action

In Risk Exchange, go to Actions and click Add Action Configuration.
Select the required Business Rule, Target Configuration, and Action from their respective dropdowns.
For Action Parameters, select the Company GUID and the Tiers Static option. If you want to create a new Tier on Bitsight, select the Create new tier option and enter a New Tier Name for Static.
Enable the Require Approval toggle if Approval is needed before performing an action.
If Require Approval is enabled, then to approve the action, go to Risk Exchange > Action Logs and select the action to be approved, and then click Approve.
Note that Bitsight only supports 5 Tiers at a time. If you want to add companies to the Tier that is not available on Bitsight, and the Tier count is 5, you’ll need to delete an existing Tier in order to create a new.
Click Save.

Validate the Bitsight Plugin

Validate in Cloud Exchange

To verify the companies pulled from Bitsight, go to the Logging and search for the logs from the CRE Bitsight plugin.

To check the company added to the tier, check the logs.

To check the records pulled and stored in Cloud Exchange, go to Records. Select the entity that you used while adding the mapping in the plugin configuration.

Validate in Bitsight

This plugin pulls first-party companies and third-party companies from Bitsight.

First-party companies are pulled from the Security Performance Management > Organization > My Company List page, and third-party companies from the Continuous Monitoring > Portfolio Risk > Companies List page.

To check the Tiers in which companies can be added or removed from on Bitsight, go to Continuous Monitoring > Risk Program Setup > Tier Settings.

Companies added to the Netskope Tier after the Add a company from a Tier action.

Companies removed from the Tier after the Remove a company from a Tier action.

Troubleshooting the Bitsight Plugin

Unable to configure the plugin

If you are not able to configure the plugin, it might be due to the token being revoked or invalid.

What to do:

Refer to the steps Get Your API Token section above and check that you are using a valid token. If needed, create a new one.

Unable to pull Companies

If you are unable to view company details on the record table, it could be due to one of these reasons:

No companies are present on the Bitsight platform.
Companies are available but not for the selected Rating Type.
Mapping was not provided while configuring the plugin.

What to do:

Make sure companies are present on Bitsight.
If companies are available on Bitsight, check the Rating Type and confirm the rating type was added in the plugin.
Make sure to provide the needed mapping while configuring the plugin. Make sure that the fields created in an Entity are according to the Mapping section. Companies might also not be pulled in Cloud Exchange if they are skipped as the mandatory fields for pulling are missing in the record.

Unable to perform action on Bitsight

If the company fails to be added or removed from the Tier, it might be that the company does not exist on Bitsight, or is already present, or removed from the Tier.

Unable to create Tier on Bitsight using Create new Tier option

Bitsight has a limit to create 5 Tiers at Max, so while adding the Add company to Tier action, if the Create new Tier option is selected and saved, but 5 Tiers have already been created, the action will throw an error.

What to do:

Go to Bitsight Tier Setting and check the number of Tiers created. If the count is 5, delete any of the Tiers that are not needed, and try configuring the action again.

Known Behavior

It has been noticed that while performing the Add company to Tier action, if the First-party companies (companies available in Security Performance Management > Organization > My Company List page) are added to the Tier, if those companies were successfully added, then there might be changes that are not visible in Tiers in Bitsight UI. But you can verify its existence in a tier using the Pull tiers API endpoint.

Bitsight v1.0.0 Plugin for Risk Exchange