Netskope Alerts

Netskope Alerts collector utilizes a pull-based mechanism which provides a robust framework for retrieving security alerts from the Netskope Cloud Security Platform. The collector makes HTTP requests to the Netskope Events API endpoints to fetch real-time alert data including DLP violations, policy breaches, malware detections, and behavioral anomalies.

Purpose

The purpose of the Netskope Alerts source in Observo AI is to enable the platform to actively retrieve security alert data from the Netskope Events API v2 by making periodic requests to the configured endpoint. It pulls alert data from your Netskope tenant into Observo AI for analysis and processing. This integration supports streamlined security data pipelines, real-time threat monitoring, and compliance analytics, allowing organizations to enhance observability, security posture, and data-driven decision-making by proactively fetching alerts from Netskope.

Prerequisites

Before configuring the Netskope Alerts source in Observo AI, ensure the following requirements are met to facilitate seamless data ingestion:

• Netskope API Access:

  • An active Netskope tenant with Events API v2 enabled must be available.

  • Obtain the tenant-specific API endpoint URL in the format: https://{tenant}.goskope.com/api/v2/events/data/alert

  • Generate an API token from the Netskope console with appropriate permissions for Events API access.

• Authentication:

  • Bearer Token Authentication: Obtain a Netskope API token from Settings > Tools > REST API v2 in your Netskope tenant.

• API Permissions:

  • The API credentials must have read access to /api/v2/events/data/alert endpoint.

  • Events API scope must be enabled for the API token.

  • Read-only access is sufficient; no write or administrative permissions required.

• Network and Connectivity:

  • Ensure Observo AI can communicate with your Netskope tenant endpoint over HTTPS (port 443).

  • Check for proxy settings, firewall rules, or network policies that may affect connectivity to *.goskope.com domains.

  • IP whitelisting may be required depending on your Netskope configuration.

Prerequisite	Description	Notes
Netskope Tenant	Active tenant with Events API v2 enabled	Obtain tenant URL and API token from Netskope console
Authentication	API Token (Bearer)	Bearer token with Events API scope
API Permissions	Read access to alerts endpoint	/api/v2/events/data/alert with Events API scope
Network	HTTPS connectivity to Netskope tenant	Check firewalls, proxies, and IP whitelisting requirements

Integration

The Integration section outlines the configurations for the Netskope Alerts source. To configure Netskope Alerts as a source in Observo AI, follow these steps to set up and test the data flow:

1. Log in to Observo AI:

• Navigate to the Sources tab.

• Click the Add Source button and select Create New.

• Choose Netskope Alerts from the list of available sources to begin configuration.

1. General Settings:

• Name: A unique identifier for the source, such as netskope-security-alerts.

• Description (Optional): Provide a description for the source, such as "Netskope security alerts for DLP and policy violations".

• Config: Configure the following parameters for the Netskope API:

  Key (Default)	Value (Default)	Description
  NETSKOPE_URL	https://company.goskope.com/api/v2/events/data/alert	The URL endpoint to fetch alerts from Netskope
  ALERT_TYPES	dlp,policy	Comma-separated alert types to fetch (dlp, policy, malware, anomaly, etc.)
  QUERY_TIME_RANGE_INTERVAL_IN_SECS	300	Time range in seconds to query for alerts (e.g., 300 = 5 minutes)

• Checkpoints: Enable checkpoints to track the last successful data collection timestamp. This ensures incremental data collection without duplication.

  Key (Default)	Value (Default)	Description
  START_TIME_UNIX_TIMESTAMP	1759183461	Starting point in time (Unix timestamp in seconds) from which to begin fetching alerts

• Time in seconds to pause between script executions: Set the interval for data collection (default: 60 seconds). This controls how frequently the collector runs to fetch new alerts.

1. Authentication:

   • Bearer Authentication

     • Auth Token: Netskope API token obtained from Settings > Tools > REST API v2.

2. Advanced Settings (Optional):

   • Runtimes: Number of concurrent runtimes (default: 2).

   • Fetchers: Number of concurrent fetchers (default: 8).

   • Fetch Request Queue Depth: Queue depth for fetch requests (default: 10).

   • Fetch Response Queue Depth: Queue depth for fetch responses (default: 10).

   • Completion Queue Depth: Queue depth for completions (default: 10).

   • Event Batch Queue Depth: Queue depth for event batches (default: 10).

   • Start Routine: Function name to execute at start (default: "start").

   • Retry Configuration:

     • Initial Backoff (seconds): Initial retry delay (default: 1, range: 1-60).

     • Max Backoff (seconds): Maximum retry delay (default: 5, range: 2-60).

     • Max Retries: Maximum retry attempts (default: 4, range: 1-10).

     • Backoff Scaling Factor: Exponential backoff multiplier (default: 2.0).

Alert Types and Data Structure

The Netskope Alerts collector can retrieve the following alert types from your Netskope tenant:

Supported Alert Types

Configure one or more alert types in the ALERT_TYPES configuration parameter:

• dlp - Data Loss Prevention alerts for data exfiltration attempts or policy violations

• policy - Security policy violation alerts

• malware - Malware detection and threat alerts

• anomaly - Behavioral anomaly detection alerts

• compromisedcredential - Alerts for potentially compromised user credentials

• legal_hold - Alerts related to legal hold policies

• quarantine - Alerts for quarantined files or activities

• remediation - Alerts generated during remediation actions

• security_assessment - Security posture assessment alerts

• watchlist - Alerts triggered by watchlist matches

Error Handling

The Netskope Alerts collector implements comprehensive error handling to ensure reliable data collection:

HTTP Status Monitoring

• All API responses are validated for HTTP 200 status code.

• Non-200 responses trigger detailed error logging with context information.

Failure Scenarios

Scenario	Handling
API Authentication Failure (401/403)	Error logged with details, collection stops for that interval
Network Timeout	Automatic retry with exponential backoff up to 4 attempts
Invalid Response Format	Error logged, event skipped, collection continues with next alert type
Rate Limiting (429)	Automatic retry with backoff delays
Empty Result Set	Normal operation, checkpoint updated to end time of query window
Partial Data Retrieval	Successfully retrieved alerts are processed and emitted, checkpoint updated to highest timestamp

Checkpoint Management

The collector maintains data consistency through checkpoint management:

• Checkpoint Update: Only updated after successful alert retrieval and processing

• Recovery: Checkpoint survives collector restarts without data loss

• Per-Alert-Type Processing: Each alert type is processed independently; failure in one type doesn't affect others

Best Practices

• Query Interval: Start with 300 seconds (5 minutes) for most environments; reduce to 60-180 seconds for high-volume alert scenarios

• Alert Types: Begin with critical types (dlp, malware, anomaly); add additional types based on security monitoring requirements

• Checkpoint Management: Verify checkpoint advancement regularly to ensure continuous data flow

• Monitor error logs for authentication failures or connectivity issues

• Validate alert volumes match expected Netskope activity patterns

• Test authentication and connectivity before deploying to production

• Regularly review and update alert type configurations based on security needs