EventCap Revisited Using NMAPI

You may remember a blog where we talked about automating a capture so that it stops when a particular event shows up in the Windows Event Log. (https://blogs.technet.com/netmon/archive/2007/02/22/eventmon-stopping-a-capture-based-on-an-eventlog-event.aspx). Now that we have the API for NM3.2, we are going to revisit this tool and rewrite it as an expert. Furthermore, the code for the tool is available as a project on https://www.CodePlex.com/NM3EventCap.

The Problem We Are Solving

Often you need to gather a trace, up until a certain event occurs in the event log. Back in the day, we had a tool called EventCap which allowed you to do this. But since it was based on Netmon2.x, it is limited to older OS’s. The NM3.2 API gives us access to the capture engine, so as long as you have NM3.2 installed, this program now gives you this capability in one executable!

Examples

The basic example is you supply a capture file and event number to wait for. In this case we’ll want to stop when PowerShell is run, which is event message 400. We’ll save the capture file to t1.cap.

    NM3EventCap t1.cap 400

The cool thing with the API is that you get access to all the various capturing formats for free. So you can do chained files and different size circular captures. It’s just a matter of exposing those in your code. So for instance to make this a chained capture with a 200 MB size, you would execute:

    NM3EventCap t1.cap 400 –b 200 –c

The Source Code

I’m not going to go into much detail here as you can look at the source code on https://www.codeplex.com/NM3EventCap/SourceControl/ListDownloadableCommits.aspx, but here the basics.

The CPrgExeState class reads the parameters, initializes the capture file and sets up the Network Monitor 3.2 engine. It opens the capture engine, initializes the capture file, and loads the NPL parser. This class also provides methods to start and stop the capture. Look at PrgExeState::InitCapture to see how to initialize the capture engine. CPrgExeState::StartCapture and CPrgExeState::StopCapture show you how to start and stop the capture engine. To understand how we created the capture file, look at CPrgExeState::CreateCap.

The rest of the code is to control the access to the event log error message (the CEventMonWbem class). This is out of scope of Network Monitor, but these interfaces are documented on MSDN if you want more information.

The CodePlex Connection

CodePlex will be the location where further examples are posted. At some point we’ll create a portal that will be used to centralize Network Monitor 3 API related projects. The goal is to create a set of useful tools for capturing and analyzing network traffic. So if there are networking folks out there with ideas that can be turned into simple experts and network tools please create a project and let us know.