nskclog

A CLI for inspecting Netskope Client logs.

Netskope Client logs are notoriously chatty. They contain useful troubleshooting evidence, but it is buried in a lot of status noise, repeated info messages, and low-level debug detail. nskclog helps separate the signal from the noise so you can understand client state, check errors, and find high-value events without scrolling through thousands of lines or manually building filters with grep, awk, sed, or regular expressions.

The current build already pulls out several useful event families and shows them in a timeline: client lifecycle and UI status, config and update activity, tunnel and gateway events, DNS/proxy/PAC problems, Fail Closed and captive portal signals, NPA connection events, and TLS/certificate issues. That gives you a short chronological view of what changed or failed, separate from the surrounding debug chatter.

Every timeline row points back to the source file and line number, and --raw can print the full log line when you need to verify the exact text.

This is an early alpha. It is useful already for a first pass over a log bundle, but it is intentionally narrow for now. See the roadmap below for planned features.

Install

Interactive Installer

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/cryptochrome/nskclog/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/cryptochrome/nskclog/main/scripts/install.ps1 | iex

The installer will ask where to put nskclog and whether it should add it to your PATH.

Manual Installation

Archives:

1. Download the .tar.gz or .zip from the GitHub Releases page.
2. Unpack it.
3. Move the binary wherever you want to keep it (putting it in your path is recommended) and run it. Usage examples are shown below.

Linux packages:

Download the .deb or .rpm from the GitHub Releases page.

Debian / Ubuntu:

sudo apt install ./nskclog_<version>_linux_amd64.deb

Fedora / RHEL:

sudo dnf install ./nskclog_<version>_linux_amd64.rpm

Project Status

Alpha Status

Right now nskclog can:

• inventory a .zip bundle or folder
• recognize common Netskope Client log/config/state files
• validate known JSON files
• count lines in text files
• build scoped timelines from nsdebuglog*, nsAppUI*, npadebuglog*, install.log, nsInstallation.log, and STAUpdate*
• filter timeline output by category
• include raw evidence lines with --raw

A Note On Log Interpretation

Netskope does not appear to publish a complete public reference for every client debug log line or event. So this project needs to be built carefully over time and add new log patterns and rules as needed. Any help is appreciated, see below.

When nskclog detects an event, that means a known pattern matched a log line. It does not mean the tool has proven a root cause, and it does not mean the wording is an official Netskope interpretation. It's a best-effort interpreter.

The parser will improve as more real-world log patterns are reviewed and turned into small, testable rules.

Help Wanted

If nskclog misses something obvious (or not so obvious), please open an issue.

Good issue reports include:

• what problem you were investigating
• which command you ran
• what you expected to see
• a few relevant log lines or a complete log bundle (do not add the bundle to the issue, as it contains sensitive information. Open the issue and we will find a way to share it privately)

Also please note: The maintainer of this project currently does not have access to an environment with NPA enabled. We are working completely blind, so any input you can provide is appreciated.

Apart from that, any feedback, feature request or comment is welcome. Feel free to open a post in the discussions tab of this repo.

Usage

Inventory a bundle:

nskclog inventory ./NetskopeLogs.zip

Build the default timeline:

nskclog timeline ./NetskopeLogs.zip

NPA timeline:

nskclog timeline --scope npa ./NetskopeLogs.zip

Install/update timeline:

nskclog timeline --scope install ./NetskopeLogs.zip

Show raw evidence for timeline rows:

nskclog timeline --raw ./NetskopeLogs.zip

Filter by category:

nskclog timeline --category connectivity ./NetskopeLogs.zip
nskclog timeline --scope all --category cert_tls ./NetskopeLogs.zip

Commands

nskclog inventory <zip-or-folder>
nskclog timeline [--raw] [--scope <main|npa|install|all>] [--category <category>] <zip-or-folder>
nskclog version
nskclog help

Timeline Scopes

Scope	Reads	Use for
main	nsdebuglog*, nsAppUI*	normal Client operation
npa	npadebuglog*	Private Access troubleshooting
install	install.log, nsInstallation.log, STAUpdate*	install and upgrade troubleshooting
all	all supported timeline logs	cross-source correlation

Supported categories:

client_lifecycle
user_auth
ui_status
branding_state
config_state
version_update
connectivity
gateway_pop
network_environment
npa_state
device_state
cert_tls

network is accepted as an alias for network_environment.

Roadmap

• Broader event coverage
• Log search
• Grouped warnings/errors
• Reports (Markdown/plain text)
• Interactive TUI view/dashboard with different views (Summary, client status, etc.)
• Traffic Analyzer/Summary (tunneled, bypassed, dropped traffic) with URL category lookup
• Log sanitizer (for sharing logs and bundles)
• Possible AI support for asking natural-language questions about log content

Credits

nskclog draws on Netskope's public OSS Splunk app, netskopeoss/netskope_log_analyzer. That project has been valuable for understanding which Client artifacts, sourcetypes, timestamp formats, dashboard concepts, and event families are worth looking at first.

It is used here as practical source material, not as a complete or formal Netskope Client debug-log specification.

Disclaimer

This is an independent, unofficial tool and is not affiliated with or supported by Netskope. It may contain incomplete, outdated, or incorrect information. Use at your own risk.