Merge pull request #4 from santisq/3-make-docs-and-update-readme

adding doc templates
santisq · Jul 24, 2024 · c250183 · c250183
2 parents c6f49a9 + 67dbef4
commit c250183
Show file tree

Hide file tree

Showing 13 changed files with 537 additions and 109 deletions.
diff --git a/README.md b/README.md
@@ -10,102 +10,34 @@
 
 </div>
 
-## DESCRIPTION
+PSNetScanners is a PowerShell Module that includes two cmdlets using async techniques for ICMP and TCP scanning. Essentially, like built-in cmdlets `Test-Connection` or `Test-NetConnection` with a few less options but much faster.
 
-Two PowerShell scripts designed to scan Network IP Ranges or hostname using [`Runspace`](https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.runspace?view=powershellsdk-7.0.0) for faster execution. And two standalone functions using async techniques for ICMP and TCP scanning.
+## Documentation
 
-| Name | Description |
-| --- | --- |
-| [__`Network-IPScanner`__](https://github.com/santysq/Network-IPScanner/blob/main/Network-IPScanner.ps1) | Sends ICMP echo requests using the [__Ping Class__](https://docs.microsoft.com/en-us/dotnet/api/system.net.networkinformation.ping?view=net-6.0) and the [__Dns Class__](https://docs.microsoft.com/en-us/dotnet/api/system.net.dns?view=net-6.0) for DNS resolution in parallel with _Runspaces_. |
-| [__`Network-TCPScanner`__](https://github.com/santysq/Network-IPScanner/blob/main/Network-TCPScanner.ps1) | Sends TCP connection requests using the [__TcpClient Class__](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.tcpclient?view=net-6.0) in parallel with _Runspaces_. |
-| [__`Test-ICMPConnectionAsync`__](https://github.com/santysq/PowerShell-Network-Scanners/blob/main/Test-ICMPConnectionAsync.ps1) | Standalone function, uses [`SendPingAsync(...)` Method](https://docs.microsoft.com/en-us/dotnet/api/system.net.networkinformation.ping.sendpingasync?view=net-6.0) for the async echo requests and [`GetHostEntryAsync(...)` Method](https://docs.microsoft.com/en-us/dotnet/api/system.net.dns.gethostentryasync?view=net-6.0#system-net-dns-gethostentryasync(system-net-ipaddress)) for async DNS resolutions. |
-| [__`Network-TCPConnectionAsync`__](https://github.com/santysq/PowerShell-Network-Scanners/blob/main/Network-TCPScanner.ps1) &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | Standalone function, uses [`ConnectAsync(...)` Method](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.tcpclient.connectasync?view=net-6.0#system-net-sockets-tcpclient-connectasync(system-net-ipaddress-system-int32)) to send the async TCP connection requests. |
+Check out [__the docs__](./docs/en-US) for information about how to use this Module.
 
-## OUTPUT
+## Installation
 
-### Network-IPScanner
+### Gallery
 
-- __```System.Management.Automation.PSCustomObject```__
+The module is available through the [PowerShell Gallery](https://www.powershellgallery.com/packages/PSNetScanners):
 
 ```powershell
-Name        TypeNameOfValue
-----        ---------------
-Ping        System.Int32
-Source      System.String
-Address     System.Net.IPAddress
-Destination System.String
-Latency     System.String
-Status      System.Net.NetworkInformation.IPStatus
+Install-Module PSNetScanners -Scope CurrentUser
 ```
 
-### Network-TCPScanner
-
-- __```System.Management.Automation.PSCustomObject```__
+### Source
 
 ```powershell
-Name         TypeNameOfValue
-----         ---------------
-Source       System.String
-Destination  System.String
-Port         System.Int32
-Success      System.Boolean
+git clone 'https://github.com/santisq/PSNetScanners.git'
+Set-Location ./PSNetScanners
+./build.ps1
 ```
 
-## REQUIREMENTS
-
-- Requires __.NET Framework 4.5+__ if running __Windows PowerShell__ / __.NET Core 1.0+__ if running __PowerShell Core__.
-
-## MEASUREMENTS
-
-Below are the measurements scanning a 254 IP range with `Test-ICMPConnection` default script parameters:
-
-```powershell
-Days              : 0
-Hours             : 0
-Minutes           : 0
-Seconds           : 4
-Milliseconds      : 600
-Ticks             : 46007194
-TotalDays         : 5.32490671296296E-05
-TotalHours        : 0.00127797761111111
-TotalMinutes      : 0.0766786566666667
-TotalSeconds      : 4.6007194
-TotalMilliseconds : 4600.7194
-```
+## Requirements
 
-## SAMPLE OUTPUT
+This module has no requirements and is fully compatible with __Windows PowerShell 5.1__ and [__PowerShell Core 7+__](https://github.com/PowerShell/PowerShell).
 
-### Network-IPScanner
+## Contributing
 
-```powershell
-Ping Source Address       Destination Latency   Status
----- ------ -------       ----------- -------   ------
-   1 moon   192.168.1.1   _gateway    3 ms     Success
-   1 moon   192.168.1.2   *           113 ms   Success
-   1 moon   192.168.1.3   *           214 ms   Success
-   1 moon   192.168.1.4   *           591 ms   Success
-   1 moon   192.168.1.5   moon        0 ms     Success
-   1 moon   192.168.1.6   *           *       TimedOut
-   1 moon   192.168.1.7   *           *       TimedOut
-   1 moon   192.168.1.8   *           *       TimedOut
-   1 moon   192.168.1.9   *           *       TimedOut
-```
-
-### Network-TCPScanner
-
-```powershell
-Source          Destination  Port Success
-------          ------------ ---- -------
-myHostName      google.com     80    True
-myHostName      google.com    443    True
-myHostName      google.com   8080   False
-myHostName      google.com    125   False
-myHostName      cisco.com     443    True
-myHostName      cisco.com      80    True
-myHostName      cisco.com     125   False
-myHostName      cisco.com    8080   False
-myHostName      amazon.com    443    True
-myHostName      amazon.com     80    True
-myHostName      amazon.com    125   False
-myHostName      amazon.com   8080   False
-```
+Contributions are more than welcome, if you wish to contribute, fork this repository and submit a pull request with the changes.
diff --git a/docs/en-US/Test-PingAsync.md b/docs/en-US/Test-PingAsync.md
@@ -0,0 +1,235 @@
+---
+external help file: PSNetScanners.dll-Help.xml
+Module Name: PSNetScanners
+online version:
+schema: 2.0.0
+---
+
+# Test-PingAsync
+
+## SYNOPSIS
+
+Parallel ICMP scanner.
+
+## SYNTAX
+
+```powershell
+Test-PingAsync
+    [-Target] <String[]>
+    [-BufferSize <Int32>
+    [-ResolveDns] [-Ttl <Int32>]
+    [-DontFragment]
+    [-ThrottleLimit <Int32>]
+    [-ConnectionTimeout <Int32>]
+    [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+`Test-PingAsync` is a PowerShell cmdlet that ICMP echo-requests in parallel using [`Ping.SendPingAsync` Method](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkinformation.ping.sendpingasync). In essence, it's like `Test-Connection` with less options but faster.
+
+## EXAMPLES
+
+### Example 1: Send parallel echo-requests to remote hosts
+
+```powershell
+Test-PingAsync google.com, github.com
+
+Source           Destination      Address             Latency Status       DnsResult
+------           -----------      -------             ------- ------       ---------
+DESKTOP-1111111  google.com       142.251.133.206        8 ms Success
+DESKTOP-1111111  github.com       20.201.28.151         37 ms Success
+```
+
+### Example 2: Attempt to resolve DNS name for multiple hosts
+
+```powershell
+PS ..\PSNetScanners> $result = Test-PingAsync 8.8.8.8, 8.8.4.4, 1.1.1.1 -ResolveDns
+PS ..\PSNetScanners> $result
+
+Source           Destination      Address             Latency Status       DnsResult
+------           -----------      -------             ------- ------       ---------
+DESKTOP-1111111  8.8.8.8          8.8.8.8                8 ms Success      dns.google
+DESKTOP-1111111  8.8.4.4          8.8.4.4                8 ms Success      dns.google
+DESKTOP-1111111  1.1.1.1          1.1.1.1                8 ms Success      one.one.one.one
+
+PS ..\PSNetScanners> $result[0].DnsResult
+
+Status      : Success
+HostName    : dns.google
+AddressList : {8.8.8.8, 8.8.4.4}
+Aliases     : {}
+```
+
+### Example 3: Specify a connection timeout for each request
+
+```powershell
+PS ..\PSNetScanners> 1..20 | ForEach-Object { "192.168.1.$_" } | Test-PingAsync -ConnectionTimeout 200
+
+Source           Destination      Address             Latency Status       DnsResult
+------           -----------      -------             ------- ------       ---------
+DESKTOP-1111111  192.168.1.1      192.168.1.1            0 ms Success
+DESKTOP-1111111  192.168.1.5      192.168.1.5            0 ms Success
+DESKTOP-1111111  192.168.1.14     192.168.1.14           3 ms Success
+DESKTOP-1111111  192.168.1.7      192.168.1.7          137 ms Success
+DESKTOP-1111111  192.168.1.3      192.168.1.3          204 ms Success
+DESKTOP-1111111  192.168.1.2      *                         * TimedOut
+DESKTOP-1111111  192.168.1.4      *                         * TimedOut
+DESKTOP-1111111  192.168.1.6      *                         * TimedOut
+DESKTOP-1111111  192.168.1.8      *                         * TimedOut
+DESKTOP-1111111  192.168.1.9      *                         * TimedOut
+DESKTOP-1111111  192.168.1.10     *                         * TimedOut
+DESKTOP-1111111  192.168.1.11     *                         * TimedOut
+DESKTOP-1111111  192.168.1.12     *                         * TimedOut
+...
+...
+```
+
+## PARAMETERS
+
+### -Target
+
+Specifies one or more remote computers, Uris or Ip addresses to test connectivity.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases: ComputerName, HostName, Host, Server, Address
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -BufferSize
+
+Specifies the size, in bytes, of the buffer sent with this command.
+
+> [!NOTE]
+>
+> The default value is 32.
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases: bfs
+
+Required: False
+Position: Named
+Default value: 32
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ConnectionTimeout
+
+Specifies a timeout __in milliseconds__ for each async task.
+
+> [!NOTE]
+>
+> - If a task is not completed after this timeout, the status will be `TimedOut`.
+> - The default value for this parameter is `4000` (4 seconds).
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases: timeout, to, ct
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -DontFragment
+
+This parameter sets the Don't Fragment flag in the IP header. See [`PingOptions.DontFragment` Property](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkinformation.pingoptions.dontfragment#system-net-networkinformation-pingoptions-dontfragment) for more information.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ResolveDns
+
+Causes the cmdlet to attempt to resolve the DNS name of the target.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: dns
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ThrottleLimit
+
+Specifies the maximum number of async tasks to run in parallel.
+
+> [!NOTE]
+>
+> The default value for `-ThrottleLimit` is `50`.
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases: tl
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Ttl
+
+Sets the maximum number of hops that an ICMP request message can be sent. The default value is controlled by the operating system. The default value for Windows 10 and higher is 128 hops.
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.String[]
+
+## OUTPUTS
+
+### PSNetScanners.PingResult
+
+## NOTES
+
+## RELATED LINKS
+
+[`Ping.SendPingAsync` Method](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkinformation.ping.sendpingasync)
+
+[`PingOptions.DontFragment` Property](https://learn.microsoft.com/en-us/dotnet/api/system.net.networkinformation.pingoptions.dontfragment#system-net-networkinformation-pingoptions-dontfragment)
+
+[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216)