Packet Sniffing with PowerShell: Getting Started

Summary: Ed Wilson, Microsoft Scripting Guy, talks about getting started with packet sniffing in Windows PowerShell.

Microsoft Scripting Guy, Ed Wilson, is here. One of the way cool things that happened with Windows 8.1 and Windows Server 2012 R2 was the ability to do network traces with Windows PowerShell. I have found network tracing extremely useful and helpful in troubleshooting and diagnostics ever since I wrote my book, Network Monitoring and Analysis: A Protocol Approach to Troubleshooting.

In the past, I have used batch files, automated the NetMon API, and done all kinds of crazy things to try to automate capturing network traces and analyzing the data. Although the Network Event Packet Capture cmdlets have been around for at least a year, I have not written very much about them. The thing is that even though it is basic Windows PowerShell, it still takes a bit of time to figure out how to get started. This is because there are 27 cmdlets in the NetEventPacketCapture module:

PS C:\> (gcm -Module NetEventPacketCapture | measure).count

27

Here are the 27 cmdlets (functions):

PS C:\> gcm -Module NetEventPacketCapture | select name

Name

----

Add-NetEventNetworkAdapter

Add-NetEventPacketCaptureProvider

Add-NetEventProvider

Add-NetEventVmNetworkAdapter

Add-NetEventVmSwitch

Add-NetEventWFPCaptureProvider

Get-NetEventNetworkAdapter

Get-NetEventPacketCaptureProvider

Get-NetEventProvider

Get-NetEventSession

Get-NetEventVmNetworkAdapter

Get-NetEventVmSwitch

Get-NetEventWFPCaptureProvider

New-NetEventSession

Remove-NetEventNetworkAdapter

Remove-NetEventPacketCaptureProvider

Remove-NetEventProvider

Remove-NetEventSession

Remove-NetEventVmNetworkAdapter

Remove-NetEventVmSwitch

Remove-NetEventWFPCaptureProvider

Set-NetEventPacketCaptureProvider

Set-NetEventProvider

Set-NetEventSession

Set-NetEventWFPCaptureProvider

Start-NetEventSession

Stop-NetEventSession

TechNet does a good job at describing the cmdlets, but there is also a pretty good chance that it will be rather cumbersome to figure out how to get started. I mean, how do I do a basic network trace? How is that trace viewed? How do I filter that trace to find useful information? These are the sorts of things that I would need if I were going to do a network trace using Windows PowerShell. So, let's get started.

Using an ETL log

This makes sense. With a gigabyte Ethernet (or greater), there are lots of packets flying by on the wire. Many of them are encrypted, and I can learn nearly nothing by watching network packets fly past. Well, nearly nothing. I can, of course, tell if my laptop is seeing anything on the wire—but that is basically the same as looking to see if the light blinks on my network card.

As I have mentioned before, ETL logging is an extremely high performance logging interface that is capable of writing hundreds of events a second— just the thing if I want to do a network trace. And guess what? Windows PowerShell already has a cmdlet that will read ETL logs—the Get-WinEvent cmdlet. So I don’t need anything else to be able to read my traces.

Six basic steps to perform a network trace

There are six basic steps required to perform a network trace:

1. Add a new network event session with New-NetEventSession.
2. Add a network event provider to the session with New-NetEventProvider.
3. Start the session with Start-NetEventSession.
4. Get information about the session with Get-NetEventSession.
5. Stop the network event session with Stop-NetEventSession.
6. Remove the network event session with Remove-NetEventSession.

Step-by-step walkthrough

Now I will go through the six steps that are used to create a new network event tracing session.

Create a new session

The first thing I need to do is to create a new network event session. To do this, I use the New-NetEventSession cmdlet and specify a name for the session. Here is an example of this command:

New-NetEventSession -Name "Session1"

When I run this command, I receive information such as where the log file will be and the size of file:

PS C:\> New-NetEventSession -Name "Session1"

Name               : Session1

CaptureMode        : SaveToFile

LocalFilePath      : C:\Windows\system32\config\systemprofile\AppData\Local\NetEvent

                     Trace.etl

MaxFileSize        : 250 MB

TraceBufferSize    : 0 KB

MaxNumberOfBuffers : 0

SessionStatus      : NotRunning

Add a provider

The second thing I need to do is to add a provider to the network event session. To do this, I need to know two things:

• The name of the session (in my case, session1)
• The name of a provider

I can use the Get-EtwTraceProvider cmdlet; but unfortunately, it only lists GUIDs and not much more information. So I can use the Logman.exe to query for providers:

logman query providers

This command brings back pages of providers, so I can either scroll through it or use Select-String to help me find what I need. That is right. I can pipe the output from the executable directly to Select-String. This is shown here:

PS C:\Windows\system32> logman query providers | select-string tcp

Microsoft-Windows-TCPIP                  {2F07E2EE-15DB-40F1-90EF-9D7BA282188A}

Microsoft-Windows-Tcpip-SQM-Provider     {C8F7689F-3692-4D66-B0C0-9536D21082C9}

TCPIP Service Trace                      {EB004A05-9B1A-11D4-9123-0050047759BC}

I want to use the Microsoft-Windows-TCPIP provider, and my command is shown here:

PS C:\> Add-NetEventProvider -Name "Microsoft-Windows-TCPIP" -SessionName "Session1"

Name            : Microsoft-Windows-TCPIP

SessionName     : Session1

Level           : 4

MatchAnyKeyword : 0xFFFFFFFFFFFFFFFF

MatchAllKeyword : 0x0

Start the session

Now I need to start the network trace session. I use the Start-NetEventSession cmdlet and specify my session name. Note that nothing returns from the following command:

PS C:\> Start-NetEventSession -Name "Session1"

Get the session

I want to get information about my session. To do this, I use the Get-NetEventSession cmdlet:

PS C:\> Get-NetEventSession

Name               : Session1

CaptureMode        : SaveToFile

LocalFilePath      : C:\Windows\system32\config\systemprofile\AppData\Local\NetEvent

                     Trace.etl

MaxFileSize        : 250 MB

TraceBufferSize    : 64 KB

MaxNumberOfBuffers : 38

SessionStatus      : Running

The Get-NetEventSession cmdlet tells me the location of the log file, so I probably want to store that and avoid a bit of typing. This is shown here:

$s = Get-NetEventSession

Stop the session

Now it is time to stop the network trace session. To do this, I use Stop-NetEventSession and specify my session number. This command does not return any information:

PS C:\> Stop-NetEventSession -Name session1

PS C:\>

Remove the session

The last thing I need to do is to remove the session that I stopped. To do this, I use the Remove-NetEventSession cmdlet. It does not return any information either, so I use the Get-NetEventSession cmdlet to ensure that it did remove the session:

PS C:\> Remove-NetEventSession

PS C:\> Get-NetEventSession

PS C:\>

Now you know how to use Windows PowerShell to get started making network traces.  Join me tomorrow when I will talk about parsing the captured ETL log data.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy