Netskope

Configure HTTP Pull to collect security events from Netskope SASE platform using REST API v2.

7 minute read

Overview

Netskope’s REST API v2 provides access to comprehensive security data across multiple event streams including network traffic, applications, alerts, audit logs, and infrastructure events. This integration enables collection from all major Netskope event categories with proper time windowing and rate limiting.

The API supports both iterator-based endpoints (for streaming recent events) and time-range queries (for historical data retrieval).

Endpoints

Endpoint	Description	API Type
Network Events	Real-time network activity	Iterator
Application Events	SaaS and web app usage	Time-range
Alert Events	Security alerts and violations	Iterator
Network Data	Detailed network telemetry	Time-range
Application Data	Extended app telemetry	Time-range
Page Events	Web browsing activity	Time-range
Audit Logs	Admin actions and config	Time-range
Infrastructure Events	System monitoring	Time-range
Connection Events	Network connections	Iterator

Prerequisites

Netskope tenant with API v2 enabled and a valid API token with read permissions for events and alerts.

Version Requirements: HTTP Pull requires Edge Delta Agent v2.6.0 or higher.

Authentication Method

Netskope uses Bearer token authentication:

API Token: Generated from Netskope Tenant UI under Settings → Tools → REST API v2
Tenant URL: Your Netskope tenant URL (e.g., cxloyalty.goskope.com)
Token Permissions: Read access for Events, Alerts, and Audit logs

Environment Variables

Set these environment variables for secure credential management:

# Netskope API Token
export NETSKOPE_API_TOKEN="your_api_token_here"

# Netskope Tenant Name (e.g., "cxloyalty" for cxloyalty.goskope.com)
export NETSKOPE_TENANT="your_tenant_name"

Configuration Examples

Network Events (Iterator API)

Real-time network activity monitoring using the iterator-based export API:

nodes:
- name: netskope_network_events
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/dataexport/events/network
  method: GET
  pull_interval: 25s

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: index
      value: network_events_iterator

  parameter_expressions:
    # Iterator operation timestamp - last 30 seconds
    - name: operation
      value_expression: String(Int(UnixSeconds(Now()) - 30))

Application Events

Monitor SaaS and web application usage across your organization:

nodes:
- name: netskope_app_events
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/application
  method: GET
  pull_interval: 1m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 62-second window with 2-second overlap
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("62s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Alert Events (Iterator API)

Capture security alerts and policy violations in real-time:

nodes:
- name: netskope_alerts
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/dataexport/events/alert
  method: GET
  pull_interval: 1m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: index
      value: alerts_iterator

  parameter_expressions:
    # Iterator operation timestamp
    - name: operation
      value_expression: String(Int(UnixSeconds(Now()) - 30))

Network Data

Detailed network telemetry for traffic analysis and forensics:

nodes:
- name: netskope_network_data
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/network
  method: GET
  pull_interval: 5m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 5-minute window
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("300s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Application Data

Extended application telemetry with deeper usage analytics:

nodes:
- name: netskope_app_data
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/application
  method: GET
  pull_interval: 6m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 6-minute window
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("360s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Page Events

Track web page access and browsing activity:

nodes:
- name: netskope_page_events
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/page
  method: GET
  pull_interval: 7m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 7-minute window
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("420s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Audit Logs

Monitor administrative actions and configuration changes:

nodes:
- name: netskope_audit
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/audit
  method: GET
  pull_interval: 8m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 8-minute window
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("480s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Infrastructure Events

System and infrastructure monitoring data:

nodes:
- name: netskope_infrastructure
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/data/infrastructure
  method: GET
  pull_interval: 9m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: limit
      value: "1000"

  parameter_expressions:
    # 9-minute window
    - name: starttime
      value_expression: String(Int(UnixSeconds(Now() - Duration("540s"))))
    - name: endtime
      value_expression: String(Int(UnixSeconds(Now())))

Connection Events (Iterator API)

Network connection logs for security analysis:

nodes:
- name: netskope_connections
  type: http_pull_input
  endpoint: https://YOUR_TENANT.goskope.com/api/v2/events/dataexport/events/connection
  method: GET
  pull_interval: 10m

  headers:
    - header: Authorization
      value: Bearer YOUR_API_TOKEN
    - header: Accept
      value: application/json

  parameters:
    - name: index
      value: connection_events_iterator

  parameter_expressions:
    # Iterator operation timestamp - last 10 minutes
    - name: operation
      value_expression: String(Int(UnixSeconds(Now()) - 600))

Configuration with Environment Variables

For production deployments, use environment variables:

nodes:
- name: netskope_network_events
  type: http_pull_input
  endpoint_expression: Concat(["https://", EDXEnv("NETSKOPE_TENANT", ""), ".goskope.com/api/v2/events/dataexport/events/network"], "")
  method: GET
  pull_interval: 25s

  header_expressions:
    - header: Authorization
      value_expression: Concat(["Bearer ", EDXEnv("NETSKOPE_API_TOKEN", "")], "")
    - header: Accept
      value_expression: "application/json"

  parameters:
    - name: index
      value: network_events_iterator

  parameter_expressions:
    - name: operation
      value_expression: String(Int(UnixSeconds(Now()) - 30))

API Endpoints Reference

Event Type	API Endpoint	Method	Description
Network Events	`/api/v2/events/dataexport/events/network`	Iterator	Real-time network activity
Application Events	`/api/v2/events/data/application`	Time-range	SaaS and web app usage
Alert Events	`/api/v2/events/dataexport/events/alert`	Iterator	Security alerts
Network Data	`/api/v2/events/data/network`	Time-range	Detailed network telemetry
Application Data	`/api/v2/events/data/application`	Time-range	Extended app telemetry
Page Events	`/api/v2/events/data/page`	Time-range	Web browsing activity
Audit Logs	`/api/v2/events/data/audit`	Time-range	Admin actions
Infrastructure	`/api/v2/events/data/infrastructure`	Time-range	System events
Connection Events	`/api/v2/events/dataexport/events/connection`	Iterator	Connection logs

Time Windows and Pull Intervals

Optimized intervals to balance data freshness and API load:

Event Type	Pull Interval	Time Window	Priority	Use Case
Network Events	25s	30s	Critical	Real-time threat detection
Application Events	1m	62s	High	SaaS monitoring
Alerts	1m	30s	Critical	Security incidents
Network Data	5m	5m	Medium	Traffic analysis
Application Data	6m	6m	Medium	Usage analytics
Page Events	7m	7m	Low	Web activity tracking
Audit	8m	8m	Low	Compliance
Infrastructure	9m	9m	Low	System monitoring
Connections	10m	10m	Low	Network forensics

Important

Include a small overlap (2-3 seconds) between pull intervals and time windows to prevent data loss during processing delays.

Understanding Iterator vs Time-Range Endpoints

Iterator-Based Endpoints (`/dataexport/`)

Used for streaming recent events with built-in state management:

parameter_expressions:
  - name: operation
    value_expression: String(Int(UnixSeconds(Now()) - 30))

Maintains state to prevent duplicate data
Best for high-volume, real-time event streams
Automatically drops old events if not consumed in time
Uses index parameter to identify unique iterator

Time-Range Endpoints (`/data/`)

Used for querying specific time windows:

parameter_expressions:
  - name: starttime
    value_expression: String(Int(UnixSeconds(Now() - Duration("62s"))))
  - name: endtime
    value_expression: String(Int(UnixSeconds(Now())))

Requires explicit time boundaries
Supports historical data queries
Use overlapping windows to prevent gaps
Limited by limit parameter per request

Testing the Configuration

Verify Authentication

curl -X GET "https://YOUR_TENANT.goskope.com/api/v2/events/data/audit?limit=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

Test Iterator Endpoint

curl -X GET "https://YOUR_TENANT.goskope.com/api/v2/events/dataexport/events/network?index=test_iterator&operation=$(date -u +%s)" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" | jq '.'

Test Time-Range Query

START_TIME=$(($(date +%s) - 300))
END_TIME=$(date +%s)

curl -X GET "https://YOUR_TENANT.goskope.com/api/v2/events/data/application?starttime=${START_TIME}&endtime=${END_TIME}&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" | jq '.'

Common Response Fields

Typical Netskope event structure:

{
  "_id": "event_id",
  "timestamp": 1234567890,
  "type": "event_type",
  "user": "user@example.com",
  "src_ip": "192.168.1.1",
  "dst_ip": "10.0.0.1",
  "app": "Application Name",
  "activity": "activity_type",
  "alert_type": "policy_violation",
  "severity": "high",
  "policy": "policy_name",
  "device": "device_id",
  "location": "Office Location"
}

Troubleshooting

Iterator State Issues

If missing events with iterator endpoints:

# Reset iterator by changing index name
parameters:
  - name: index
    value: network_events_iterator_v2  # New iterator name

Rate Limiting (429 Errors)

Increase pull_interval values
Reduce limit parameter for /data/ endpoints
Implement retry with exponential backoff:

retry_http_code:
  - 429
  - 503

Authentication Errors (401/403)

Verify API token is valid and not expired
Check token has necessary read permissions
Ensure correct tenant URL format

Time Synchronization

Ensure system clock is synchronized:

# Check time offset
ntpdate -q pool.ntp.org

# Sync if needed (requires admin)
sudo ntpdate -s pool.ntp.org

Security Best Practices

Token Management: Store API tokens as environment variables, never in code
Token Rotation: Regularly rotate API tokens (monthly recommended)
Least Privilege: Grant only necessary read permissions to tokens
Network Security: Restrict agent egress to Netskope API endpoints only
Monitoring: Set up alerts for authentication failures and rate limiting
Audit Trail: Monitor API usage through Netskope audit logs