NetTrace Agentix

AI-powered network trace analysis for VS Code. Drop in a .pcap file, type @nettrace what's wrong? in Copilot Chat, and get expert-level network diagnosis — no Wireshark expertise required.

⚠️ Required: Wireshark / tshark must be installed on your machine before use.
tshark is the CLI engine that parses .pcap files. See Prerequisites for platform-specific install paths and how to verify it is working.

Table of Contents

• Overview
• Prerequisites
• Installation
  • From Source (Build & Install)
  • From VSIX File
• Getting Started
  • 1. Open a Workspace
  • 2. Add Capture Files
  • 3. Open a Capture
  • 4. Ask the AI
• Features
  • Chat Participant (@nettrace)
  • Capture Viewer
  • Live Packet Capture
  • Sidebar Views
  • Agentic Tool Calling
  • Client/Server Capture Comparison
  • Analysis Agents
  • Knowledge Base
• Commands
• Configuration
  • VS Code Settings
  • Workspace Configuration (.nettrace/ folder)
• Workspace Initialization Wizard
• Example Workflows
  • Quick Diagnosis
  • TLS Handshake Troubleshooting
  • Client vs Server Comparison
• Architecture
• Development
  • Building from Source
  • Running in Development
  • Packaging
  • Project Structure
• Troubleshooting
  • File Locations & Uninstalling
• License

Overview

Network Capture AI Diagnosis turns GitHub Copilot into a network analysis tool. It parses pcap/pcapng capture files using tshark (the Wireshark CLI) and feeds structured network data to an LLM through Copilot's Language Model API. The AI can then autonomously drill into specific TCP streams, apply Wireshark display filters, follow streams, and compare client/server captures — all through natural language conversation.

Key capabilities:

• Parse and analyze .pcap, .pcapng, and .cap files directly in VS Code
• Streams sorted by anomaly score — the most suspicious connections surface first
• AI autonomously calls tshark tools to drill deeper during analysis
• Compare simultaneous client-side and server-side captures
• Configuration-driven: add custom agents, tools, and filters via JSON files
• Knowledge templates inject domain expertise (known issues, security heuristics) into the LLM context

Prerequisites

Before using this extension, you need:

Verifying tshark

After installing Wireshark, verify tshark is accessible:

tshark --version

If tshark is not on your PATH, the extension will check standard install locations automatically:

• Windows: C:\Program Files\Wireshark\tshark.exe
• macOS: /Applications/Wireshark.app/Contents/MacOS/tshark, /usr/local/bin/tshark
• Linux: /usr/bin/tshark, /usr/local/bin/tshark

You can also manually configure the path in VS Code settings (see Configuration).

Installation

From Source (Build & Install)

1. Clone the repository:

   git clone https://github.com/kkfrosty/nettraceagentix.git
   cd nettraceagentix
   

2. Install dependencies:

   npm install
   

3. Compile the TypeScript:

   npm run compile
   

4. Package as a VSIX:

   npm run package
   

   This produces a .vsix file in the Release/ folder (e.g., nettrace-agentix-0.1.2.vsix).

5. Install the VSIX in VS Code:

   code --install-extension Release/nettrace-agentix-0.1.12.vsix
   

   Or in VS Code: Extensions sidebar → ... menu → Install from VSIX... → select the .vsix file.

6. Reload VS Code when prompted.

From VSIX File

If you received a pre-built .vsix file:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Click the ... menu at the top of the Extensions sidebar
4. Select Install from VSIX...
5. Browse to and select the .vsix file
6. Reload VS Code when prompted

Getting Started

1. Open a Workspace

Open any folder in VS Code. This will be your analysis workspace.

2. Add Capture Files

You have several options:

• Drag and drop .pcap, .pcapng, or .cap files into the workspace folder in the Explorer
• Use the command NetTrace: Import Capture File (Ctrl+Shift+P → type "Import Capture")
• Place files in a captures/ subdirectory within your workspace

The extension auto-detects capture files and parses them with tshark on arrival.

3. Open a Capture

In the NetTrace sidebar (network icon in the Activity Bar), you'll see your captures listed. Click the preview icon on any capture to open the Capture Viewer — an interactive webview showing packets, conversations, and statistics.

4. Ask the AI

With a capture open in the viewer, open Copilot Chat (Ctrl+Shift+I) and type:

@nettrace what's wrong with this capture?

The AI analyzes the active capture, highlights anomalies, and provides diagnosis. It can autonomously use tools to drill into specific streams, apply filters, and gather more data.

Features

Chat Participant (@nettrace)

The extension registers a @nettrace chat participant in GitHub Copilot Chat. No separate API keys are needed — it uses your existing Copilot subscription through the VS Code Language Model API.

Simply mention @nettrace followed by your question:

Multi-turn conversations are fully supported. Follow-up questions carry forward from the first analysis — the AI remembers the capture context and can call tools to revisit specific packets without re-sending all packet data.

Capture Viewer

A richly interactive webview panel that shows:

• Packet list with timestamps, source/destination, protocol, and info
• Conversation statistics
• Ability to apply Wireshark display filters
• Three-pane layout: packet list, protocol detail tree, hex dump
• Click-to-analyze integration with Copilot Chat
• Collapsible Packet Detail and Packet Bytes panes for maximum screen space

Live Packet Capture

Capture live network traffic directly from VS Code without leaving the editor:

1. Run NetTrace: Start Live Capture from the Command Palette, or ask @nettrace start capturing traffic on my Wi-Fi adapter
2. The Live Capture panel opens showing available network interfaces with friendly names
3. Optionally set a BPF capture filter (e.g., port 443, host 10.0.1.1) to limit captured traffic
4. Click ▶ Start — live packets stream into the panel in real time
5. Click ⏹ Stop when done
6. Click 🤖 Analyze with AI to immediately feed the capture to @nettrace for diagnosis

Live captures are saved as .pcapng files in your workspace, so you can revisit them later or open them in Wireshark for additional analysis.

Note: Live capture requires tshark to run with packet capture privileges. On Windows, Wireshark installs the required Npcap driver automatically. On Linux/macOS, tshark may need to run as root or your user must be in the wireshark group.

Sidebar Views

The NetTrace Activity Bar entry provides:

• Captures — All capture files in the workspace, organized by folder. Right-click for actions (analyze, parse, set as client/server, open in Wireshark).
• Analysis Agents — Lists all available agents (built-in and custom). Click to activate an agent; the active agent's persona and tools are used for the next @nettrace request.
• Knowledge Base — Shows knowledge documents organized by category (Analysis Guidance, Security Heuristics, Known Issues). Enabled/disabled status is visible at a glance; click to open and edit any file.
• Scenario Context — Optional scenario metadata (scenario ID, symptom, topology, IPs) that gets injected into every LLM prompt for more targeted diagnosis.

Agentic Tool Calling

During analysis, the LLM autonomously calls tools to gather more data — up to 25 round-trips per conversation turn. The AI starts with a high-level summary and drills into specific streams on its own when it detects something suspicious. Each agent defines which tools it has access to.

Display filter changes made by any tool are automatically pushed to the open Capture Viewer panel, keeping the UI in sync with what the AI is analyzing.

Client/Server Capture Comparison

If you have simultaneous captures from both ends of a connection:

1. Right-click a capture in the sidebar → Set as Client Capture
2. Right-click another capture → Set as Server Capture
3. Ask @nettrace /compare or @nettrace compare these captures

The extension correlates packets between captures to find what's missing, delayed, or modified in transit.

Tip: Place client captures in a folder named client/ and server captures in a folder named server/ — the extension auto-detects the roles from folder names.

Analysis Agents

Agents are specialized AI personas with tailored prompts, tools, and filters:

Select an agent via the command NetTrace: Select Analysis Agent or use the /agent command in chat.

You can also create custom agents — see Workspace Configuration.

Knowledge Base

The .nettrace/knowledge/ directory contains markdown files automatically injected into the LLM context during every analysis. This is how you teach the AI about your specific environment — devices, quirks, known issues, and false positives to ignore.

Add or edit .md files in these folders to customize the AI's knowledge. Changes take effect immediately via hot-reload — no restart needed. You can also disable individual files without deleting them by adding <!-- nettrace-disabled --> as the first line.

The Knowledge Base sidebar shows all loaded documents with their enabled/disabled status. The AI also uses the Create Knowledge tool to write new knowledge files automatically when it learns something useful during a session.

Commands

All commands are available via the Command Palette (Ctrl+Shift+P) under the NetTrace category:

Configuration

VS Code Settings

These settings are available under nettrace.* in VS Code Settings (Ctrl+,):

Default excluded protocols: arp, mdns, ssdp, nbns, igmp, llmnr, cdp, lldp, stp

Workspace Configuration (.nettrace/ folder)

For advanced configuration, create a .nettrace/ directory in your workspace root. The extension watches these files and hot-reloads changes automatically.

.nettrace/
├── config.json          # Workspace-level settings
├── scenario.json        # Scenario context injected into every prompt
├── agents/              # Custom analysis agents
│   ├── tls-specialist.json
│   ├── dns-troubleshooter.json
│   └── voip-analyzer.json
├── tools/               # Custom tool definitions
│   └── custom-tool.json
└── filters/             # Reusable filter profiles
    └── exclude-noise.json

config.json

{
  "tsharkPath": "",
  "tokenBudget": {
    "maxInputTokens": 900000,
    "reserveForResponse": 100000
  },
  "defaultAgent": "general",
  "excludeProtocols": ["arp", "mdns", "ssdp"]
}

scenario.json

Providing scenario context helps the AI give more targeted diagnosis:

{
  "scenarioId": "SR-2026-12345",
  "symptom": "TLS handshake timeout to api.contoso.com",
  "summary": "Customer reports intermittent 503 errors when connecting to the API endpoint",
  "topology": {
    "clientIP": "10.0.1.50",
    "serverIP": "40.112.72.205",
    "description": "Client → Corporate Proxy → Azure Front Door → App Service"
  },
  "notes": "Issue started after firewall rule change on Feb 10"
}

Custom Agents

Create JSON files in .nettrace/agents/ to define specialized analysis agents:

{
  "name": "tls-specialist",
  "displayName": "TLS/SSL Specialist",
  "description": "Expert analysis of TLS handshakes, certificates, and cipher suites",
  "persona": "You are an expert TLS/SSL protocol analyst...",
  "tools": ["nettrace-getStreamDetail", "nettrace-followStream", "nettrace-applyFilter"],
  "filters": {
    "displayFilter": "ssl || tls",
    "focusPorts": [443, 8443]
  }
}

Workspace Initialization Wizard

Run NetTrace: Initialize Workspace to launch an interactive wizard that:

1. Asks what kind of traffic you're analyzing (General, Web/TLS, VoIP/SIP, DNS, Custom)
2. Asks if you have matched client + server captures
3. Optionally collects scenario details (scenario ID, symptom)
4. Creates the .nettrace/ folder structure with appropriate agents and configuration

This is optional — the extension works without it — but provides a better starting point for focused analysis.

Example Workflows

Quick Diagnosis

1. Drop a .pcap file into your workspace
2. Wait for auto-parse (status bar notification)
3. Click the capture in the NetTrace sidebar to open the viewer
4. Open Copilot Chat → @nettrace what's wrong with this capture?
5. Follow the AI's suggestions for deeper analysis

TLS Handshake Troubleshooting

1. Import your capture file
2. Run "NetTrace: Initialize Workspace" → select "Web / TLS"
3. Edit Scenario Context with the server hostname and IPs
4. Open the capture viewer
5. @nettrace /agent tls-specialist
6. @nettrace analyze the TLS handshakes — are there certificate or cipher issues?

Client vs Server Comparison

1. Place client capture in a client/ subfolder
2. Place server capture in a server/ subfolder
3. Open both captures (extension auto-detects roles from folder names)
4. Open either capture in the viewer
5. @nettrace /compare — what packets are missing between client and server?

Architecture

The extension follows a three-layer design:

┌─────────────────────────────────────────────────────────┐
│                   VS Code Extension                      │
├──────────────┬──────────────────┬────────────────────────┤
│  Parsing     │  Context         │  Presentation          │
│  Layer       │  Assembly        │  Layer                 │
│              │  Engine          │                        │
│  tsharkRun-  │  contextAssem-   │  @nettrace Chat        │
│  ner.ts      │  bler.ts         │  Participant           │
│              │                  │  Capture Viewer        │
│  Spawns      │  Token budget    │  Sidebar TreeViews     │
│  tshark CLI  │  management      │  LM Tools              │
│  processes   │  (~900K usable)  │                        │
│              │  Priority-ranked │                        │
│  Parallel    │  streams (anom-  │  Commands, Menus,      │
│  execution   │  aly score)      │  Configuration         │
└──────────────┴──────────────────┴────────────────────────┘
         │                │                    │
         ▼                ▼                    ▼
    Binary pcap     Structured prompt     GitHub Copilot
    files           for LLM              Language Model API

1. Parsing Layer — Spawns tshark as a child process to convert binary pcap files into structured text. Runs multiple tshark commands in parallel for speed.
2. Context Assembly Engine — Manages the token budget, prioritizes anomalous streams, and structures the prompt for maximum diagnostic value. Knowledge templates are conditionally injected based on capture signals.
3. Presentation Layer — The @nettrace chat participant, capture viewer webview, sidebar tree views, and Language Model Tools that allow the AI to autonomously gather more data.

No separate API keys required — the extension uses vscode.lm.selectChatModels() to access the same models your Copilot subscription provides.

Development

Building from Source

git clone https://github.com/kkfrosty/nettraceagentix.git
cd nettraceagentix
npm install
npm run compile

Running in Development

1. Open the project in VS Code
2. Press F5 to launch the Extension Development Host
3. In the new VS Code window, open a folder with .pcap files
4. Use the extension normally — changes are reflected after recompile

For continuous compilation during development:

npm run watch

Or use the built-in VS Code task: Terminal → Run Build Task (Ctrl+Shift+B) which runs the watch script.

Packaging

npm run package

This runs npx @vscode/vsce package and produces a .vsix file you can distribute.

Project Structure

src/
├── extension.ts                    # Entry point — activation, commands, auto-discovery
├── types.ts                        # All shared TypeScript interfaces
├── configLoader.ts                 # Loads .nettrace/ JSON config with hot-reload watchers
├── contextAssembler.ts             # Token budgeting, priority ranking, prompt assembly
├── workspaceInitializer.ts         # Workspace scaffolding wizard
├── logger.ts                       # Structured output channel logging
├── storage.ts                      # Extension global storage management
├── parsing/
│   └── tsharkRunner.ts             # tshark execution engine (all pcap parsing + live capture)
├── participant/
│   └── nettraceParticipant.ts      # @nettrace chat participant handler
├── views/
│   ├── capturesTreeProvider.ts     # Sidebar: capture files
│   ├── streamsTreeProvider.ts      # Internal: TCP streams sorted by anomaly score
│   ├── scenarioDetailsTreeProvider.ts  # Sidebar: scenario context
│   ├── agentsTreeProvider.ts       # Sidebar: analysis agents
│   ├── knowledgeTreeProvider.ts    # Sidebar: knowledge base documents
│   ├── captureWebviewPanel.ts      # Interactive capture viewer (static pcap)
│   ├── captureEditorProvider.ts    # Custom editor provider for capture files
│   └── liveCaptureWebviewPanel.ts  # Live Capture panel (real-time packet streaming)
└── tools/
    └── lmTools.ts                  # Language Model Tools the AI calls during analysis

NetTraceAIAnalysisWorkspace/         # Working workspace for capture analysis
├── .nettrace/                       # Extension configuration (auto-created)
│   ├── knowledge/                   # Domain knowledge injected into LLM context
│   │   ├── known-issues/            # Platform/device-specific known issues
│   │   ├── security/                # Security analysis heuristics
│   │   └── wisdom/                  # False positive avoidance guidance
│   ├── agents/                      # Custom analysis agent definitions
│   ├── config.json                  # Workspace settings
│   └── scenario.json                    # Scenario context for analysis
└── captures/                        # Drop .pcap files here

Troubleshooting

tshark not found

The extension needs tshark (included with Wireshark) to parse capture files. If you see a warning:

1. Install Wireshark (includes tshark)
2. Ensure tshark is on your system PATH, or
3. Set the full path in VS Code settings: nettrace.tsharkPath

"No capture is open" when chatting

The @nettrace participant requires an active capture in the viewer:

1. Click on a capture file in the NetTrace sidebar
2. Or run NetTrace: Open Capture Viewer from the Command Palette
3. Then return to Copilot Chat and ask your question

Extension not activating

The extension activates when it detects:

• Any .pcap, .pcapng, or .cap file in the workspace
• A .nettrace/config.json file
• Or when you run a NetTrace command manually

If nothing happens, try running NetTrace: Import Capture File from the Command Palette.

Copilot Chat not showing @nettrace

Ensure:

• GitHub Copilot Chat extension is installed and active
• You have an active GitHub Copilot subscription
• The extension has loaded (check the NetTrace output channel: View → Output → select "NetTrace")

Large captures are slow

For very large captures (100MB+):

• The extension caps packet data per stream to keep within the token budget
• Use the Scenario Context to narrow the AI's focus
• Apply display filters to reduce noise: @nettrace apply filter tcp.port == 443
• Switch to a specialized agent that filters to relevant traffic only

File Locations & Uninstalling

NetTrace stores all user data (agents, knowledge files, filters, config) in one of two places depending on your settings:

Default location (no nettrace.storagePath set)

VS Code's per-extension global storage — managed automatically and removed on uninstall:

To quickly reveal this folder, run NetTrace: Show Storage Location from the Command Palette.

Custom location (nettrace.storagePath overridden)

Whatever folder you set in nettrace.storagePath. This path is not automatically deleted on uninstall — you must remove it manually if you no longer need it. The extension will warn you about this when uninstalling.

Manual cleanup after uninstall

If the extension folder is still present after uninstalling (VS Code defers cleanup until all windows are fully closed and restarted), you can remove it manually:

Windows (PowerShell):

# Extension binaries (safe to delete any time after uninstall)
Remove-Item "$env:USERPROFILE\.vscode\extensions\cognitiveagentics-krisfrost.nettrace-agentix-*" -Recurse -Force

# User data (only if you have no custom storagePath)
Remove-Item "$env:APPDATA\Code\User\globalStorage\cognitiveagentics-krisfrost.nettrace-agentix" -Recurse -Force

macOS/Linux (bash):

# Extension binaries
rm -rf ~/.vscode/extensions/cognitiveagentics-krisfrost.nettrace-agentix-*

# User data (macOS)
rm -rf "$HOME/Library/Application Support/Code/User/globalStorage/cognitiveagentics-krisfrost.nettrace-agentix"

# User data (Linux)
rm -rf ~/.config/Code/User/globalStorage/cognitiveagentics-krisfrost.nettrace-agentix

License

MIT