My PowerShell module PSNetStat contains the Get-NetStat function that offers features similar to the popular netstat.exe command. You can use it to analyze and display network connections in PowerShell.

Josh Rickard

Josh's primary focus is in Windows security and PowerShell automation. He is a GIAC Certified Windows Security Administrator (GCWN) and GIAC Certified Forensic Analyst (GCFA). You can reach Josh at MSAdministrator.com or on Twitter at @MS_dministrator.

During the lead-up to IronScripter at the 2018 DevOps + PowerShell Global Summit, there were several weekly competitions to prepare for the official competition. One such challenge was during Week 4 where the challenge asked the competitor to generate a PowerShell equivalent to the output of netstat.exe.

This was an interesting challenge for me, so I took a shot at it, and it resulted in me creating PSNetStat: a PowerShell module. PSNetStat went further than the original inquiry, and it recreated most of the functionality of netstat.exe using PowerShell.

Netstat.exe is a command-line utility that provides network statistics. It displays active and inactive network connections (both inbound and outbound) along with protocol statistics and connections. Windows introduced netstat to its ecosystem during the beginning of the Windows NT era. There are ports of the same application on Unix, Linux, macOS, Solaris, and BSD.

PSNetStat currently only works on Windows operating systems, but as time permits, I will also support PowerShell Core in the future. Now, let's take a look at the module layout:

PSNetStat PowerShell module folder structure

PSNetStat PowerShell module folder structure

When importing this module using the PSNetStat.psm1 file, it will traverse through both the Public and Private folders and export only the Public module members. You can see this in the script module file:

I'll give a quick shout-out to Warren Frame (a.k.a. PSCookieMonster). The idea of importing PowerShell modules this way originally came from him—at least from my perspective.

As you can see, we are looping through our folder and using the Export-ModuleMember cmdlet to allow only the functions in the Public folder that are visible or usable. The functions in the Private folder are intended for internal-module use only, and we should not use them directly.

The PSD1 or PowerShell module manifest file is a configuration definition file that allows you to specify requirements, dependencies, and much more. A manifest allows the module's writer to make sure the environment it is running on meets all the requirements necessary for it to work.

We can import this PowerShell Module using the built-in Import-Module cmdlet.

After importing the module, we can take a look at the available function by using the Get-Module cmdlet and viewing the exported commands (public functions).

PSNetStat ExportedCommands

PSNetStat ExportedCommands

As you can see in the screenshot above, the only public and exposable function is the Get-NetStat function. The other functions within the Private folder are not "naturally" exposed or usable.

Let's take a look at the Get-NetStat function. This is the one and only entry point to receive network statistics using this module.

The default behavior for Get-NetStat is that it will only show the active TCP connections.

Default output of Get NetStat

Default output of Get NetStat



Below is a screenshot of both netstat.exe's output using the -p TCP command-line option vs. the default output of Get-NetStat:

Netstat p TCP and the default behavior of the Get NetStat PowerShell module

Netstat p TCP and the default behavior of the Get NetStat PowerShell module

If you would like to see all connections, you can pass in a switch of -AllConnections. By doing this, you will get all active TCP and UDP listeners and all active TCP connections. This option is the most robust option, and it will return all available information.

Get NetStat with the AllConnections switch

Get NetStat with the AllConnections switch

Using the -AllConnections switch is similar to when you run:

The last option you have is that you can select whether you want to see only TCP or UDP connections. If you want to see all connections but only the TCP ones then you would use:

Now, let's dive into the fun part! Let's take a look at one of those private functions I mentioned earlier. Here is a look at Get-ActiveTcpConnections.ps1:

Get-ActiveTcpConnections uses the System.Net.NetworkInformation namespace to retrieve information about all active TCP connections. We loop through all active connections and create our PSCustomObject. Part of the properties of this object also uses another private function called Convert-NetStatRemoteEndpoint to determine whether it is a local address. If it is a local address, we replace either 127.0.0.1 or 0.0.0.0 with the local machine's host name. If it is not a local address, we keep it as it is and return the new formatted string and add it to our PSCustomObject under the Foreign Address property.

The returned objects from Get-ActiveTcpConnections, Get-ActiveTcpListeners, and Get-ActiveUdpListeners are private functions. It calls each of these private functions depending on which switches we pass to Get-NetStat. It then returns and displays the result back to the console.

My PSNetStat PowerShell module is not exactly the same as the built-in netstat.exe application, since netstat.exe uses unmanaged code and accesses lower-level WIN_API classes to get additional information from GetExtendedTcpTable and GetExtendedUdpTable. The .NET framework doesn't natively expose these classes, so in order to access them, you would need to implement a new Add-Type or C#/C++ DLL.

Join the 4sysops PowerShell group!

2+
Share
7 Comments
  1. Mike Kanakos 1 year ago

    Josh,

    This module looks awesome. Can't wait to to fire it up and try it out. Great work!

    1+

    • Author
      Josh Rickard 1 year ago

      Mike, thanks!  I would love to hear your feedback; and I'm always accepting Pull Requests on GitHub!

      3+

      Users who have LIKED this comment:

      • avatar
  2. Anthony Bushong 1 year ago

    This is great! Just yesterday,  I was looking for a PS module to do exactly this! Can't wait to try it out. Thanks for sharing!

    1+

    • Author
      Josh Rickard 1 year ago

      Anthony, that's great to hear!  Please let me know if you encounter any issues or any positives as well!

      1+

  3. Scott L. 1 year ago

    Thanks Josh for the post, I will test drive this module myself.

    1+

    • Author
      Josh Rickard 1 year ago

      Scott, thanks!  If you run into any issues, please let me know!

      1+

  4. Imraz 2 days ago

    Hello, is there a re-req article to this one? I cant get Get-ActiveTcpConnections.ps1: to work, erroring out on:

    Convert-NetStatRemoteEndpoint : The term 'Convert-NetStatRemoteEndpoint' is not recognized as the name of a cmdlet, function, script file, or operable program.

     

    which makes sense because I never created any such function anywhere. I'm trying to create something that shows tcp connections with the state of Time_wait, Close_wait and listening and to output the info to a file or OGV with Time stamps, I want it to run for maybe 10 minutes. Not sure if this is doable, but want to get this function to work.

    0

Leave a reply

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2019

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account