Netskope Integration Guide

Overview

The Netskope integration allows your NINA workflows to connect with Netskope's cloud security platform for URL list management and automated threat containment. This integration enables you to create, update, and manage URL lists for blocking malicious domains, IPs, and URLs in your Netskope security policies, providing a streamlined way to automate threat response and security policy enforcement.

Netskope is a leading Cloud Access Security Broker (CASB) and Secure Web Gateway (SWG) platform that provides comprehensive cloud security. The NINA integration focuses on URL list management, which is essential for maintaining dynamic blocklists and allowlists based on threat intelligence feeds and security events.

Status

Currently, our integration supports comprehensive management of URL lists:

URL List Management

• List Operations: Create, retrieve, update, and delete URL lists
• Entry Management: Add entries to existing lists without replacing content
• Flexible Matching: Support for exact matching and regex patterns
• Deployment Control: Stage changes and deploy when ready, or deploy immediately
• List Discovery: List all URL lists with filtering by status (applied, pending, or all)

Our integration focuses specifically on URL list operations, which are the foundation for Netskope's policy enforcement. However, the Netskope platform offers numerous additional capabilities that we do not yet support, including but not limited to:

• Policy Management: Real-Time Protection policies, API Data Protection policies, and DLP policies
• User and Group Management: User profiles, group management, and attribute-based policies
• Threat Intelligence: Malware scanning, sandboxing, and threat analytics
• DLP (Data Loss Prevention): Data classification, DLP rules, and incident management
• Cloud Application Visibility: Application discovery, risk scoring, and usage analytics
• Incident Management: Security incident tracking, investigation, and remediation
• Audit and Compliance: Activity logging, compliance reporting, and forensics
• Advanced Threat Protection: IPS/IDS rules, advanced malware detection, and zero-day protection
• Private Apps: Netskope Private Access (NPA) configuration and management
• User Notifications: Custom notification templates and user messaging
• Certificate Management: SSL/TLS certificate deployment and management
• Publisher Management: SaaS application publishers and connectors

For a comprehensive list of Netskope capabilities, refer to the official API documentation at https://docs.netskope.com/en/netskope-help/integrations-439794/netskope-api/

Credential Configuration

Before using the Netskope integration in your workflows, you need to configure credentials for authentication.

Authentication Method

The Netskope integration uses API Token authentication:

Field	Description	Example
Tenant URL	Your Netskope tenant URL (without https:// or /api/v2)	company.goskope.com
API Token	Netskope REST API v2 token	a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Auth Type	Authentication type	apiToken

How to get your API Token:

1. Log in to your Netskope tenant (e.g., https://company.goskope.com)
2. Navigate to Settings > Tools > Rest API v2
3. Click New Token
4. Configure the token settings:
   • Token Name: Enter a descriptive name (e.g., "NINA Integration")
   • Expires At: Set an appropriate expiration date
   • Endpoints: Select the required endpoints:
     • /api/v2/policy/urllist (required for URL list management)
5. Click Save
6. Copy the generated token immediately (it will not be shown again)

Important Security Notes:

• Store the API token securely
• Use tokens with the minimum required permissions (principle of least privilege)
• Set appropriate expiration dates for tokens
• Rotate tokens regularly according to your security policy
• Monitor token usage through Netskope's audit logs

How to find your Tenant URL:

Your Netskope tenant URL is the domain you use to access the Netskope console. For example:

• If you access Netskope at https://company.goskope.com, your tenant URL is company.goskope.com
• If you access Netskope at https://myorg.eu.goskope.com, your tenant URL is myorg.eu.goskope.com

Do not include the https:// protocol or /api/v2 path when entering the tenant URL.

Creating a Netskope Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "Netskope Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Netskope"
   • Auth Type: "API Token" (this should be automatically selected)
   • Tenant URL: Enter your Netskope tenant URL (without https://)
   • API Token: Enter your Netskope REST API v2 token

4. Click Test Connection to verify credentials

5. Click Save to store the credential

Supported Resources and Operations

The Netskope integration supports the following resource and operations:

URL List

Manage URL lists for blocking or allowing domains, IPs, and URLs in Netskope policies.

Operation	Description
List	Get all URL lists with optional filtering by status (all, applied, pending)
Get	Retrieve details of a specific URL list by ID
Create	Create a new URL list with domains, IPs, or URLs
Add Entries	Append new entries to an existing URL list
Update	Replace the entire URL list configuration
Delete	Mark a URL list for deletion
Deploy	Apply all pending URL list changes

Parameter Merging

The Netskope integration takes advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Netskope Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Netskope Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the Netskope operation

Example: Creating and Managing URL Lists

Creating a New URL List

Below is an example of creating a new URL list to block malicious domains:

Node Configuration:

{
  "resource": "urlList",
  "operation": "create",
  "parameters": {
    "name": "Malicious Domains - Threat Intel Feed",
    "urls": [
      "malicious-domain.com",
      "evil-site.net",
      "phishing-example.org",
      "192.168.100.50",
      "10.0.0.100"
    ],
    "type": "exact",
    "deploy": false
  }
}

This creates a URL list with exact matching for the specified domains and IP addresses. The deploy: false parameter stages the changes without immediately applying them, allowing for review before deployment.

Creating a URL List with Immediate Deployment

For urgent threat response, you can create and deploy a list in one operation:

Node Configuration:

{
  "resource": "urlList",
  "operation": "create",
  "parameters": {
    "name": "Emergency Block - Active Attack",
    "urls": [
      "active-threat.com",
      "c2-server.net"
    ],
    "type": "exact",
    "deploy": true
  }
}

Creating a Regex-Based URL List

For advanced matching scenarios, you can use regex patterns:

Node Configuration:

{
  "resource": "urlList",
  "operation": "create",
  "parameters": {
    "name": "Suspicious Patterns - Regex",
    "urls": [
      ".*\\.suspicious-tld$",
      "^phish-.*\\.com$",
      ".*evil-keyword.*"
    ],
    "type": "regex",
    "deploy": false
  }
}

Example: Adding Entries to Existing Lists

Appending New Threats to a List

When new threats are identified, you can append them to an existing list without replacing the entire content:

Node Configuration:

{
  "resource": "urlList",
  "operation": "addEntries",
  "parameters": {
    "listId": 12345,
    "urls": [
      "new-malware-site.com",
      "additional-threat.net",
      "203.0.113.100"
    ],
    "deploy": false
  }
}

Dynamic Entry Addition from Threat Intelligence

Input Data from Previous Node:

{
  "threat_intel": {
    "iocs": [
      {
        "type": "domain",
        "value": "malware-c2.example.com",
        "confidence": 95,
        "severity": "high"
      },
      {
        "type": "ip",
        "value": "198.51.100.50",
        "confidence": 90,
        "severity": "critical"
      }
    ],
    "source": "AlienVault OTX",
    "list_id": 12345
  }
}

Script Node (to extract IOC values):

// Extract only high-confidence IOCs
const highConfidenceIocs = input.threat_intel.iocs
  .filter(ioc => ioc.confidence >= 85)
  .map(ioc => ioc.value);

return {
  list_id: input.threat_intel.list_id,
  urls_to_add: highConfidenceIocs,
  source: input.threat_intel.source,
  total_iocs: highConfidenceIocs.length
};

Netskope Integration Node:

{
  "resource": "urlList",
  "operation": "addEntries",
  "parameters": {
    "listId": "{{list_id}}",
    "urls": "{{urls_to_add}}",
    "deploy": true
  }
}

Example: Updating and Managing Lists

Listing All URL Lists

Retrieve all URL lists with optional filtering:

Node Configuration:

{
  "resource": "urlList",
  "operation": "list",
  "parameters": {
    "pending": "all"
  }
}

The pending parameter accepts:

• "all": Return all lists (default)
• "applied": Return only applied lists
• "pending": Return only lists with pending changes

Getting a Specific URL List

Retrieve details of a specific list by ID:

Node Configuration:

{
  "resource": "urlList",
  "operation": "get",
  "parameters": {
    "listId": 12345
  }
}

Updating an Entire URL List

Replace the entire contents of a URL list:

Node Configuration:

{
  "resource": "urlList",
  "operation": "update",
  "parameters": {
    "listId": 12345,
    "name": "Updated List Name",
    "urls": [
      "domain1.com",
      "domain2.com",
      "domain3.com"
    ],
    "type": "exact",
    "deploy": false
  }
}

Note: The update operation replaces all existing entries. Use addEntries to append without replacement.

Deleting a URL List

Mark a URL list for deletion:

Node Configuration:

{
  "resource": "urlList",
  "operation": "delete",
  "parameters": {
    "listId": 12345,
    "deploy": false
  }
}

Example: Deploying Changes

Manual Deployment of Staged Changes

After staging multiple changes (creates, updates, additions), you can deploy them all at once:

Node Configuration:

{
  "resource": "urlList",
  "operation": "deploy",
  "parameters": {}
}

This operation applies all pending URL list changes. The response includes the number of lists affected by the deployment.

Integration in Workflow Context

The Netskope integration is particularly powerful when combined with other nodes in a workflow:

Common Workflow Patterns:

1. Threat Intelligence to Block List:

   • Threat Intel Feed Node → Script Node (extract domains/IPs) → Netskope Add Entries Node → Netskope Deploy Node → Slack Node (notify SOC)

2. Automated Incident Response:

   • Security Alert Node → Script Node (extract IOCs) → Netskope Create List Node → Netskope Deploy Node → Jira Node (create ticket) → Email Node (notify team)

3. Scheduled Threat Feed Updates:

   • Schedule Node → API Node (fetch threat feed) → Script Node (parse and filter) → Netskope Add Entries Node → Database Node (log update) → Netskope Deploy Node

4. Multi-Stage Approval Workflow:

   • Alert Node → Script Node (analyze) → Netskope Create List Node (deploy: false) → Slack Node (request approval) → Webhook Node (approval) → Netskope Deploy Node → Email Node (confirmation)

5. Cleanup and Maintenance:

   • Schedule Node → Netskope List Node → Script Node (identify outdated lists) → Netskope Delete Node → Netskope Deploy Node → Report Node

Response Structure Examples

URL List Creation Response

{
  "id": 12345,
  "name": "Malicious Domains - Threat Intel Feed",
  "deployed": false
}

If deploy: true was used:

{
  "id": 12345,
  "name": "Malicious Domains - Threat Intel Feed",
  "deployed": true
}

Add Entries Response

{
  "id": 12345,
  "name": "Malicious Domains - Threat Intel Feed",
  "urls_added": 5,
  "deployed": false
}

Get URL List Response

{
  "id": 12345,
  "name": "Malicious Domains - Threat Intel Feed",
  "data": {
    "urls": [
      "malicious-domain.com",
      "evil-site.net",
      "phishing-example.org"
    ],
    "type": "exact"
  },
  "modify_type": "Created",
  "modify_by": "[email protected]",
  "modify_time": 1672531200,
  "pending": 0
}

List URL Lists Response

{
  "url_lists": [
    {
      "id": 12345,
      "name": "Malicious Domains - Threat Intel Feed",
      "pending": 0
    },
    {
      "id": 12346,
      "name": "Approved Sites - Whitelist",
      "pending": 1
    }
  ]
}

Deploy Response

{
  "deployed": true,
  "lists_affected": 3
}

Deployment Strategies

Immediate Deployment

Use deploy: true in create, update, addEntries, or delete operations for immediate enforcement:

Use Cases:

• Active security incidents requiring immediate blocking
• Emergency response to ongoing attacks
• Critical IOCs from high-confidence sources

Example:

{
  "resource": "urlList",
  "operation": "create",
  "parameters": {
    "name": "Emergency Block",
    "urls": ["active-threat.com"],
    "deploy": true
  }
}

Staged Deployment

Use deploy: false to stage changes, then deploy when ready:

Use Cases:

• Batch processing multiple threat feeds
• Changes requiring approval workflows
• Testing and validation before enforcement
• Scheduled deployment windows

Example Workflow:

1. Create/update multiple lists with deploy: false
2. Review staged changes
3. Execute deploy operation to apply all changes

Hybrid Approach

Combine both strategies based on severity:

// In a Script Node
const shouldDeployImmediately = input.ioc_confidence > 90 && input.severity === "critical";

return {
  deploy_immediately: shouldDeployImmediately
};

Then use {{deploy_immediately}} in the Netskope node parameters.

Troubleshooting

Issue	Resolution
Authentication failures	Verify your API token is correct and has not expired. Ensure the token has the required /api/v2/policy/urllist permission. Check that your tenant URL is correct (no https:// or /api/v2).
Permission errors	Verify your API token has permissions for the URL list endpoint. Recreate the token with the correct endpoint permissions if needed.
List not found errors	Verify the list ID exists by using the "list" operation first. Some lists may have been deleted or the ID may be incorrect.
Deployment failures	Check that the list has pending changes to deploy. Verify there are no conflicts with existing policies. Review Netskope logs for deployment errors.
Invalid URL format	Ensure URLs, domains, and IPs are properly formatted. For regex type, verify your regex patterns are valid. For exact type, use standard domain/IP formats.
Duplicate entries	Netskope may reject duplicate entries in a list. Check existing list contents before adding entries. Use the "get" operation to review current entries.
Rate limiting	Netskope enforces rate limits on API calls. Implement delays between operations or use exponential backoff in your workflows.
Connection timeout	Verify network connectivity to your Netskope tenant. Check for firewall restrictions that might block HTTPS traffic to *.goskope.com.
Empty list creation	Lists must contain at least one URL entry. Ensure the "urls" parameter contains at least one item.
List name conflicts	List names must be unique. Use descriptive, unique names or check existing lists before creation.

Best Practices

1. Use Descriptive List Names: Give your URL lists clear, descriptive names that indicate their purpose, source, and scope (e.g., "Malicious Domains - AlienVault OTX - 2024-01").

2. Implement Proper Deployment Strategy: For non-critical updates, stage changes and deploy during maintenance windows. Use immediate deployment only for critical security threats.

3. Validate Before Deployment: Use the "get" operation to review list contents before deploying changes. Implement approval workflows for high-impact changes.

4. Leverage Add Entries for Updates: When adding new threats to existing lists, use "addEntries" instead of "update" to preserve existing entries and avoid accidental data loss.

5. Monitor List Growth: Large lists can impact performance. Consider splitting very large lists into multiple smaller lists organized by category or threat type.

6. Document List Purposes: Maintain clear documentation of what each list is for, its source, and when it should be reviewed or updated.

7. Implement Expiration Logic: Include logic to periodically review and clean up outdated entries. Not all IOCs remain relevant indefinitely.

8. Use Consistent Naming Conventions: Adopt a naming convention for lists that makes them easy to identify and manage (e.g., "BLOCK-MALWARE-SOURCE-DATE").

9. Test with Exact Matching First: Start with exact matching before implementing regex patterns. Regex patterns can be powerful but require careful testing to avoid false positives.

10. Batch Related Changes: When updating multiple lists, stage all changes first and deploy them together to minimize policy update overhead.

11. Handle Errors Gracefully: Implement error handling in your workflows to manage API failures, rate limits, and validation errors. Include retry logic for transient failures.

12. Secure API Tokens: Rotate API tokens regularly and limit their scope to only required endpoints. Monitor token usage through Netskope's audit logs.

13. Log All Changes: Maintain audit logs of all URL list modifications for compliance and troubleshooting purposes.

14. Use Script Nodes for Filtering: Before adding entries, use Script Nodes to filter, deduplicate, and validate IOCs to ensure high-quality data.

15. Coordinate with Policy Teams: Work with your Netskope policy administrators to ensure URL lists are properly referenced in security policies.

16. Regular List Audits: Implement workflows to regularly audit list contents and remove entries that are no longer relevant or have expired.

17. Test Before Production: When possible, test changes in a development environment or use Netskope's testing features before applying to production policies.

18. Monitor Deployment Results: After deploying changes, monitor security events and policy logs to ensure the changes have the desired effect without causing false positives.

Updated: 2026-01-28