exl_netskope

README documentation for exl_netskope

stableRepositoryPythonprivate

11 min readUpdated Jul 24, 2026@integrations-teamClient Integrations

Source: ZoosGlobal/exl_netskope Visibility: Private This page is automatically synchronized from the repository README. Do not edit this generated file directly.

EXL Netskope → Datadog Windows Integration 🚀

Netskope APIs → Python collectors → Datadog Logs → Dashboards & Alerts

❓ The Problem — Why This Exists

EXL’s network security stack relies on Netskope for cloud access control, SSL inspection, and Zero Trust Network Access (ZTNA). However, Netskope’s native reporting operates in isolation — its telemetry (IPsec tunnel health, NPA user sessions, SSL bypass traffic, URL redirects, and policy inventory) is locked inside the Netskope console with no native integration into EXL’s central observability platform.

This created critical operational blind spots:

No unified visibility — Security and network teams had to context-switch between Netskope and Datadog to correlate events, delaying incident response.
No real-time alerting — Tunnel failures, zero-session anomalies, and API errors could go undetected for hours without active manual checks.
No historical trending — Netskope’s UI provides limited time-series analysis, making it impossible to track policy drift, session growth, or bypass trends over time.
No cross-correlation — Security events in Netskope could not be joined with infrastructure, application, or endpoint data already flowing into Datadog.
Windows-only environment constraint — EXL’s on-premise agents run on Windows Server, ruling out Linux-native collection approaches and requiring a purpose-built Windows pipeline.

✅ The Solution — What We Built

We built a lightweight, stateless Windows-native integration pipeline that bridges Netskope’s REST APIs into Datadog’s log ingestion layer — with zero additional infrastructure.

Architecture

Netskope REST APIs
        ↓
  Python Collectors (5 scripts, stateless)
        ↓
  Structured JSON Log Files (rotating, 7-day retention)
        ↓
  Datadog Agent 7.x (file-tail log collection)
        ↓
  Datadog Logs → Dashboards → Alerts

Key Design Decisions

Decision	Rationale
Stateless Python scripts	No database or state file needed; safe to re-run or reschedule at any time
File-based log relay	Leverages Datadog Agent’s native file-tail — no HTTP ingestion endpoint or API key in scripts
PowerShell scheduler wrappers	Windows Task Scheduler runs `.ps1` wrappers, not Python directly, enabling env-var injection and execution control
Per-source Datadog tagging	Each API gets its own `source:` tag, enabling independent dashboards and alert rules
Rotating logs (200 MB cap)	Prevents disk exhaustion on long-running Windows servers
Separate error & history logs	Operational health (scheduler SLA, exit codes) is separated from business data for clean alerting

What Gets Collected

Data Source	Frequency	Use Case
IPsec Tunnel HA Status	Every 5 min	Uptime alerting, tunnel health dashboards
NPA User Sessions	Every 1 min	Real-time ZTNA access visibility
SSL Page Bypass	Every 1 min	Security posture — bypass trend analysis
URL Redirects	Every 5 min	Policy enforcement monitoring
URL List Policies	Daily	Policy inventory drift detection

The result is full Netskope telemetry flowing into Datadog — with dashboards, cross-source correlation, and automated alerting — running entirely on existing Windows infrastructure with no new services or agents required.

📁 Production Directory Structure

C:\Scripts\exl_netskope\
│
├── config\
│   └── datadog\
│       └── netskope.d\
│           └── conf.yaml              # Datadog log collection config
│
├── schedulers\                        # Windows Task Scheduler entrypoints
│   ├── run_ipsec_tunnels.ps1
│   ├── run_npa_users.ps1
│   ├── run_page_bypass.ps1
│   ├── run_page_redirects.ps1
│   └── run_url_policies.ps1
│
├── scripts\                           # Stateless Python collectors
│   ├── netskope_ipsec_tunnels.py      # IPsec tunnel HA status
│   ├── netskope_npa_users.py          # NPA user sessions
│   ├── netskope_page_bypass.py        # SSL bypass traffic (note: filename differs from YAML)
│   ├── netskope_page_redirects.py     # URL redirect events
│   └── netskope_url_policies.py       # URL list policies (daily)
│
├── logs\                              # Runtime output (auto-created)
│   ├── apps\                          # Main JSON payload logs
│   │   ├── netskope_ipsec_tunnels.json.log
│   │   ├── netskope_npa_users.json.log
│   │   ├── netskope_page_url_bypass.json.log  # Note: matches Datadog config
│   │   ├── netskope_page_redirects.json.log
│   │   └── netskope_url_policies.json.log
│   ├── errors\                        # Python/API errors only
│   │   └── *_error.json.log
│   └── history\                       # Scheduler execution history
│       └── *.history.jsonl
│
├── tools\                             # Diagnostics & troubleshooting
│   ├── scripts\                       # Diagnostic PowerShell scripts
│   │   ├── netskope_check.ps1         # Environment validation
│   ├── netskope_dd_log_probe.ps1  # Datadog log collection status
│   │   ├── netskope_env_dump.ps1      # Environment variables dump
│   │   ├── netskope_paths_check.ps1   # Directory structure validation
    │   └── netskope_permissions.ps1   # File permissions audit
├── output\                        # Diagnostic reports (auto-created)
├── 00_EXECUTIVE_SUMMARY.txt
│   │   ├── netskope_check.log
│   │   ├── netskope_dd_log_probe.log
│   │   ├── netskope_env_dump.log
│   │   ├── netskope_paths_check.log
├── netskope_permissions.log
├── datadog_configcheck.log
│   │   └── datadog_status.log
│   ├── run_all_tools.ps1              # Master diagnostic runner
│   ├── convert_txt_to_ps1.py          # Utility: .txt → .ps1 converter
│   └── convert_ps1_to_txt.py          # Utility: .ps1 → .txt converter
│
└── README.md                          # This file

⚙️ System Requirements

Windows Server 2019+ / Windows 10+
Python 3.9+ (system-wide)
Datadog Agent 7.73+ (logs enabled)
PowerShell 5.1+
SYSTEM / Administrator privileges
Minimum 5GB free disk space

1️⃣ Install Python

Install Python for all users and add to SYSTEM PATH.

Download

https://www.python.org/downloads/windows/
✔ Install for all users
✔ Add Python to PATH

Verify

where python
python --version
pip --version

**Expected Output:**
Python 3.14.2
pip 25.3

---

2️⃣ Install Dependencies

pip install requests

Verify:

python -c "import requests; print(requests.__version__)"

Expected: 2.32.5 or higher

3️⃣ Environment Variable

The scripts require a Netskope API token.

Recommended (SYSTEM scope)

setx NETSKOPE_BEARER_TOKEN "BASE64_TOKEN_VALUE" /M

Verify

echo %NETSKOPE_BEARER_TOKEN%

PowerShell fallback (used by schedulers)

if (-not $env:NETSKOPE_BEARER_TOKEN) {
    $env:NETSKOPE_BEARER_TOKEN = "HARDCODED_FALLBACK_KEY"
}

4️⃣ Manual Script Validation (MANDATORY)

Before enabling schedulers:

cd C:\Scripts\exl_netskope\scripts

python netskope_ipsec_tunnels.py
python netskope_npa_users.py
python netskope_page_bypass.py
python netskope_page_redirects.py
python netskope_url_policies.py

Verify logs

dir ..\logs\apps\*.json.log
dir ..\logs\errors\*_error.json.log
dir ..\logs\history\*.history.jsonl

✅ Expected: 5 JSON logs in apps\, minimal/no errors, 5 history files

5️⃣ Datadog Agent Permissions ⚠️ CRITICAL

The Datadog Agent service runs as ddagentuser and needs read access to log files.

Grant Permissions (Run as Administrator)

icacls "C:\Scripts\exl_netskope\logs" /grant "ddagentuser:(OI)(CI)R" /T

Verify Permissions

icacls "C:\Scripts\exl_netskope\logs" | findstr ddagent

Expected: ddagentuser:(OI)(CI)R

6️⃣ Datadog Agent Configuration

Location

C:\ProgramData\Datadog\conf.d\netskope.d\conf.yaml

Configuration

init_config:

instances:

logs:
  # Netskope Application Logs
  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_ipsec_tunnels.json.log
    service: netskope
    source: ipsec_tunnel_status

  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_npa_users.json.log
    service: netskope
    source: npa_users

  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_page_redirects.json.log
    service: netskope
    source: page_url_redirects

  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_page_url_bypass.json.log
    service: netskope
    source: page_url_bypass

  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_url_policies.json.log
    service: netskope
    source: url_policy_details

  # Error Logs
  - type: file
    path: C:\Scripts\exl_netskope\logs\errors\*_error.json.log
    service: netskope
    source: netskope_error

  # Scheduler History
  - type: file
    path: C:\Scripts\exl_netskope\logs\history\*.history.jsonl
    service: netskope
    source: netskope_scheduler

Restart Agent

net stop datadogagent && net start datadogagent

Verify Collection

"C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" status

Look for the Logs Agent section - all Netskope inputs should show:

Status: OK
Bytes Read: > 0

7️⃣ Windows Task Scheduler Setup

⚠️ Always schedule PowerShell scripts, never Python directly

Recommended Production Schedule

Script	Interval	Priority	Task Name
IPsec tunnels	5 minutes	High	Netskope-IPsec
NPA users	1 minute	High	Netskope-NPA
Page bypass	1 minute	Critical	Netskope-Page-Bypass
Page redirects	5 minutes	Medium	Netskope-Page-Redirects
URL policies	Daily	Low	Netskope-URL-Policies

Example (Command Line)

schtasks /create /tn "Netskope-IPsec" /sc minute /mo 5 /tr "powershell.exe -ExecutionPolicy Bypass -File C:\Scripts\exl_netskope\schedulers\run_ipsec_tunnels.ps1" /ru SYSTEM /rl HIGHEST /f

schtasks /create /tn "Netskope-NPA" /sc minute /mo 1 /tr "powershell.exe -ExecutionPolicy Bypass -File C:\Scripts\exl_netskope\schedulers\run_npa_users.ps1" /ru SYSTEM /rl HIGHEST /f

schtasks /create /tn "Netskope-Page-Bypass" /sc minute /mo 1 /tr "powershell.exe -ExecutionPolicy Bypass -File C:\Scripts\exl_netskope\schedulers\run_page_bypass.ps1" /ru SYSTEM /rl HIGHEST /f

schtasks /create /tn "Netskope-Page-Redirects" /sc minute /mo 5 /tr "powershell.exe -ExecutionPolicy Bypass -File C:\Scripts\exl_netskope\schedulers\run_page_redirects.ps1" /ru SYSTEM /rl HIGHEST /f

schtasks /create /tn "Netskope-URL-Policies" /sc daily /st 01:00 /tr "powershell.exe -ExecutionPolicy Bypass -File C:\Scripts\exl_netskope\schedulers\run_url_policies.ps1" /ru SYSTEM /rl HIGHEST /f

8️⃣ Diagnostic Tools 🔧

Master Diagnostic Runner

Run comprehensive environment validation:

cd C:\Scripts\exl_netskope\tools
.\run_all_tools.ps1

Output: Creates netskope-flare-YYYYMMDD-HHMMSS.zip with:

Executive summary
Environment validation
Datadog Agent status
Permission audit
Path validation
Configuration checks

Individual Diagnostic Scripts

Script	Purpose
`netskope_check.ps1`	Python, env vars, directory structure
`netskope_dd_log_probe.ps1`	Datadog log collection analysis
`netskope_env_dump.ps1`	Environment variables (PII-masked)
`netskope_paths_check.ps1`	Directory/file validation
`netskope_permissions.ps1`	ACL and permission audit

Quick Health Check

cd C:\Scripts\exl_netskope\tools\scripts
.\netskope_check.ps1

Expected Output:

[SUCCESS] All critical checks passed!
[SUCCESS] Netskope integration is ready
Errors:   0
Warnings: 0

9️⃣ Troubleshooting

Issue: “Bytes Read: 0” in Datadog Agent

Cause: Datadog Agent only tails new log entries (doesn’t read existing data)

Solution 1 - Generate Fresh Logs:

cd C:\Scripts\exl_netskope\scripts
python netskope_ipsec_tunnels.py
python netskope_npa_users.py
python netskope_page_bypass.py
python netskope_page_redirects.py
python netskope_url_policies.py

Solution 2 - Force Read Existing: Add to Datadog YAML:

logs:
  - type: file
    path: C:\Scripts\exl_netskope\logs\apps\netskope_ipsec_tunnels.json.log
    service: netskope
    source: ipsec_tunnel_status
    start_position: beginning  # Add this line

Then: Restart-Service datadogagent

Issue: Permission Denied Errors

Cause: Datadog Agent user (ddagentuser) lacks read access

Solution:

icacls "C:\Scripts\exl_netskope\logs" /grant "ddagentuser:(OI)(CI)R" /T
Restart-Service datadogagent

Verify:

.\tools\scripts\netskope_permissions.ps1

Issue: Script Execution Errors

Diagnosis:

cd C:\Scripts\exl_netskope\tools
.\run_all_tools.ps1

Check tools\output\00_EXECUTIVE_SUMMARY.txt for:

Python installation issues
Missing environment variables
API authentication failures
File permission problems

Issue: No Logs in Datadog UI

Checklist:

✅ Datadog Agent service running: Get-Service datadogagent
✅ API key valid: Check agent.exe status
✅ Log collection enabled in datadog.yaml
✅ Netskope config present: C:\ProgramData\Datadog\conf.d\netskope.d\conf.yaml
✅ Permissions granted: icacls "C:\Scripts\exl_netskope\logs"
✅ Fresh log data exists: dir C:\Scripts\exl_netskope\logs\apps

Force Agent Refresh:

Restart-Service datadogagent

Wait 60 seconds, then check:

Datadog UI → Logs → Live Tail → Filter: service:netskope

🔟 Log Types & Purpose

Folder	Purpose	Retention
`logs/apps`	Business/security data	7 days
`logs/errors`	API, parsing, auth failures	7 days
`logs/history`	Scheduler health & SLA	7 days

History Example

{
  "timestamp":"2025-12-28T07:12:30Z",
  "script":"netskope_npa_users",
  "status":"SUCCESS",
  "exit_code":0,
  "duration_ms":421,
  "total_records":142,
  "written_records":142
}

1️⃣1️⃣ Datadog Use-Cases

Dashboards

IPsec tunnel HA health
Active NPA users (real-time count)
SSL bypass trends by category
URL redirect volume by policy
Policy inventory drift detection

Alerts

Critical: IPsec tunnel HA down
High: Zero NPA sessions (business hours)
Medium: API failures > 3 in 15 min
Medium: Scheduler failures
Low: Log collection latency > 5s

Example Alert Query

service:netskope source:ipsec_tunnel_status status:down

1️⃣2️⃣ Data Volumes (Typical)

API	Frequency	Daily Events	Volume/Day
IPsec tunnels	5 min	~300	~500 KB
NPA users	1 min	~1,500	~3 MB
Page bypass	1 min	~5,000	~10 MB
Page redirects	5 min	~2,000	~4 MB
URL policies	Daily	~100	~200 KB

Total: ~18 MB/day (~540 MB/month)

🛡️ Production Features

✅ Stateless Python collectors
✅ Strict field whitelisting
✅ Optional PII stripping (code-level)
✅ Rotating logs (200 MB max per file)
✅ 7-day local retention
✅ Windows-safe timezone handling
✅ API retries & exponential backoff
✅ Scheduler audit trail
✅ Datadog wildcard ingestion
✅ Comprehensive diagnostic tools
✅ Automated health checks
✅ Permission validation
✅ Zero-dependency diagnostics

✅ Production Checklist

Prerequisites

Python 3.9+ installed system-wide
pip install requests completed
NETSKOPE_BEARER_TOKEN environment variable set
Administrator access available

Installation

All scripts tested manually (5/5 successful)
Logs visible in C:\Scripts\exl_netskope\logs\apps\
No errors in logs\errors\
History files created in logs\history\

Datadog Configuration

Datadog Agent 7.73+ installed
Log collection enabled in datadog.yaml
Netskope config created: conf.d\netskope.d\conf.yaml
Permissions granted: icacls command executed
Agent restarted after config changes
Agent status shows “Bytes Read > 0” for all inputs

Task Scheduler

5 scheduled tasks created (SYSTEM account)
Tasks use PowerShell wrappers (not Python directly)
Tasks set to “HIGHEST” priority
Tasks tested manually (right-click → Run)

Validation

Diagnostic bundle generated: .\tools\run_all_tools.ps1
Executive summary shows: “Overall Status: HEALTHY”
Datadog UI shows logs: service:netskope
Dashboard created with key metrics
Alerts configured for critical events

Monitoring

Scheduler history monitored for failures
Error logs reviewed weekly
Datadog log ingestion metrics tracked
API quota usage monitored

🏁 FINAL STATUS

✅ DEPLOYMENT READY
Scheduler → Python → Logs → Datadog → Dashboards

✅ Secure (PII stripping, credential masking)
✅ Auditable (history logs, diagnostic tools)
✅ Scalable (stateless collectors, rotating logs)
✅ Production-hardened (retries, error handling, validation)
✅ Maintainable (comprehensive diagnostics, troubleshooting guides)

Powered by Zoos Global | EXL Service

📞 Support & Troubleshooting

Quick Diagnostics

# Run full diagnostic suite
cd C:\Scripts\exl_netskope\tools
.\run_all_tools.ps1

# Share the generated ZIP file with support
# Location: C:\Scripts\exl_netskope\tools\netskope-flare-YYYYMMDD-HHMMSS.zip

Common Commands

# Check Datadog Agent status
& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" status

# Restart Datadog Agent
Restart-Service datadogagent

# Verify permissions
icacls "C:\Scripts\exl_netskope\logs" | findstr ddagent

# Test Python environment
python -c "import requests; print('OK')"

# Check environment variable
echo $env:NETSKOPE_BEARER_TOKEN

Version: 2.0.0 Last Updated: December 2025 Status: Production Ready ✅