mecro-dev / psscanner

PSScanner is made for IT administrators to scan corporate network, showing IP address, hostname, current logon user and serialnumber for all connected computers. It is a WPF application written in Powershell; it depents on PSParallel module for multi-threaded scan.

[Installation] Install-Script -Name PSScanner

PSScanner is made for IT administrators to scan corporate network, showing IP address, hostname, current logon user and serial number for all connected computers. Initially it was made for comparing Powershell multi-threading performance, but it can be used as a great pen-testing tool whenever installing 3rd-party software is immpossible. It is a WPF application written in Powershell.

1. Featuring ICMP/ARP scan and TCP port scan/sweep, PSScanner can scan the whole subnet in a fast speed
2. Logon user query method: Windows query command
3. Host name query method: Reverse DNS resolution
4. Serial number query: WMI remote query. RPC needs to be running on each target otherwise the result will be "...". Domain admin right required
5. Arp clear cache: Local admin right required
6. Port scan/sweep
7. Intergrated PS7+ native multi-threading with ForEach-Object -Parallel (-ps7 switch will turn it on. PSScanner7.ps1 is obsolete)
8. Show the terminal console with switch -ShowConsole

This project can be a template for any Powershell/WPF application development.

1. RunspacePool management
2. Passing data from worker threads to UI thread, the best way is using dispatcher timer, rather than dispatcher invoke which freezes the UI.
3. A good producer/consumer model implementation using Concurrent Queue Collection from .Net, it is thread safe.
4. Utilizing Mutex to protect shared variables
5. Designing UI by directly editing xaml file, no UI designer software required (Visual Studio, etc.)
6. Handling custom defined events, passing data between different threads with Powershell engine events

Usage:

1. IP Address: Any IP in the target subnet (IPv4 Class A,B,C)
2. Subnet mask or CIDR of your choice. CIDR default to 24.(IPv4 Class A,B,C)
3. Runspace capacity: [1-128]. To control the degree of parallelism, i.e. the number of concurrent runspaces, use the -ThrottleLimit parameter as I call it Runspacepool capacity. Default value is 128.
4. Check "More" to show current logon user and serial number on each live node.
5. Check ARP to use ARP scan. This is limited to the local network as ARP is a layer-2 protocol. ARP-Scanning a network which differs from the one your computer is on will be resulting zero nodes alive. ARP scan will exclude the IP of your own computer on which this script is running.
6. ARP Ping delay [0-9ms]: Delay(ms) between 2 arp probes. I use UDP request for this type of probing. Default value is 2.
7. Clear ARP cache before scanning: For the most accurate result, please clear the cache so you woudn't get any disconnected nodes and won't miss any new nodes, because it only scans the IPs in the arp cache.
8. Output IP order is random due to concurrency, but it will be sorted and saved to c:\PSScanner once all worker threads completed.
9. To clear the output window, just press ESC key, or it will be automatically cleared when you press SCAN button again.
10. Even though it can scan IPv4 class A,B,C addresses, this tool is tageted on corperate LAN only, rather than WAN. Scanning /8 network will take long time.
11. To get the best result, it requires an elevated domain admin account to run.

Files:

PSScanner.ps1 : Requires Windows Powershell 5+ with PSParallel module installed. If you don't want to install PSParallel module and just want to use native multi-threading mode, you need Powershell Core 7+. Native mode has less performance on multi-threading.

PSScanner7.ps1 : Requires Powershell Core 7+, no dependent module required (Obsolete, please use PSScanner.ps1 with -ps7 switch enabled)

Contributions : Pull requests and/or suggestions are more than welcome. Currently there is no progress bar implemented for the native multi-threading. I would appreciate it if someone can add to it.

Screenshot:

1. IP Scan
2. Port Sweep
3. Port Scan

Due to scanning WAN IP, this screenshot only shows IP address.

Sorted output file:

Powershell multi-threading performance comparision:

PSParallel seems faster than ForEach-Object -Parallel. I have scanned a /16 network using both methods, PSparallel used 1:10:28.575 while ForEach-Object used 1:18:33.939. It's about 8 minutes difference.

psscanner's Issues

Concurrent Queue trydequeue sometimes getting duplicated items

This script utilizes consumer/producer model. When started scanning, many threads will keep writing the results to the concurrent queue. At the same time, there is a dispatch timer controlled ScriptBlock which calls TryDequeue method periodically and write the data to the RichTextBox. When there is more data going through the queue, sometimes there will be duplicated items showing in the GUI. Microsoft claimed the concurrent queue is thread safe but it seems like some of the Dequeue operation didn't successfully remove the item from the queue, causing the next Dequeue operation get the same item.

This might be the bug in TryDequeue method, or it is normal when there are too many threads trying to push data to the queue at the same time.