Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

adding doc templates #4

Merged
merged 10 commits into from
Jul 24, 2024
Merged

adding doc templates #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
65aa077
adding doc templates
santisq Jul 22, 2024
b4f9ff6
adding client property to tcpresult.
santisq Jul 22, 2024
adf57c7
adding client property to tcpresult.
santisq Jul 22, 2024
6a5c6a5
adding tcp doc.
santisq Jul 23, 2024
10ca2b0
better wording
santisq Jul 23, 2024
198fe95
almost done with ping docs
santisq Jul 24, 2024
17afd03
done with ping docs
santisq Jul 24, 2024
83af78b
done with ping docs
santisq Jul 24, 2024
4eaf85d
done with readme
santisq Jul 24, 2024
67dbef4
done with readme
santisq Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 15 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
235 changes: 235 additions & 0 deletions docs/en-US/Test-PingAsync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading