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
  • Sidebar Views
  • Agentic Tool Calling
  • Client/Server Capture Comparison
  • Analysis Agents
  • Knowledge Templates
• 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.2.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 Copilot Chat. Simply mention @nettrace followed by your question:

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
• Click-to-analyze integration with Copilot Chat

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).
• 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 can autonomously call these tools to gather more data:

The AI starts with a high-level summary and drills into specific streams on its own when it detects something suspicious.

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 Templates

The .nettrace/knowledge/ directory in your workspace contains markdown files that are automatically injected into the LLM context during analysis:

• known-issues/ — Firewall appliance quirks, Windows TCP stack behaviors (always loaded)
• security/ — Patterns for identifying security-relevant anomalies (loaded when suspicious packets are detected)
• wisdom/ — Common false positives to avoid misdiagnosis (always loaded)

Add or edit .md files in these folders to customize the AI's knowledge. Changes take effect immediately via hot-reload — no restart needed.

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
├── parsing/
│   └── tsharkRunner.ts             # tshark execution engine (all pcap parsing)
├── 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       # Agent management
│   └── captureWebviewPanel.ts      # Interactive capture viewer
└── 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