Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
firejox committed Oct 16, 2022
1 parent 144ed94 commit f743a6b
Showing 1 changed file with 28 additions and 16 deletions.
44 changes: 28 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
# WinSocat [![Testing](https://github.com/firejox/WinSocat/actions/workflows/unit-test.yml/badge.svg)](https://github.com/firejox/WinSocat/actions/workflows/unit-test.yml) [![](https://img.shields.io/github/v/release/firejox/WinSocat?include_prereleases)](https://github.com/firejox/WinSocat/releases/latest)
# WinSocat [![Testing][ci-badge]][ci] [![Release][release-badge]][release] [![Nuget][nuget-badge]][nuget]

WinSocat is a socat-like program specific on Windows platform. It can bridge Windows named pipe and other general I/O, e.g., STDIO, TCP, the STDIO of Process.

## Prerequisite
[ci]: https://github.com/firejox/WinSocat/actions/workflows/unit-test.yml
[ci-badge]: https://github.com/firejox/WinSocat/actions/workflows/unit-test.yml/badge.svg
[release]: https://github.com/firejox/WinSocat/releases
[release-badge]: https://img.shields.io/github/v/release/firejox/WinSocat?include_prereleases
[nuget]: https://www.nuget.org/packages/winsocat
[nuget-badge]: https://img.shields.io/nuget/vpre/winsocat

WinSocat is built under .Net 6.0. Make sure the corresponding .Net runtime is installed before using it.
WinSocat is a socat-like program specific on Windows platform. It can bridge Windows named pipe and other general I/O, e.g., STDIO, TCP, the STDIO of Process.

## Installation

You can download binary from [release](https://github.com/firejox/WinSocat/releases), or build from source.
[Install .NET 6 or newer](https://get.dot.net) and install via `dotnet tool`

```
dotnet tool install -g winsocat
```

## Command Form

Expand All @@ -18,41 +25,46 @@ The WinSocat is accept two address pattern
winsocat.exe [address1] [address2]
```

The `address1` can accept `STDIO`, `TCP-LISTEN`, `TCP`, `NPIPE`, `NPIPE-LISTEN`, `EXEC`, `WSL` socket types.
The `address1` can accept `STDIO`, `TCP-LISTEN`, `TCP`, `NPIPE`, `NPIPE-LISTEN`, `EXEC`, `WSL`, `UNIX`, `UNIX-LISTEN` socket types.

The `address2` can accept `STDIO`, `TCP`, `NPIPE`, `EXEC`, `WSL` socket types.
The `address2` can accept `STDIO`, `TCP`, `NPIPE`, `EXEC`, `WSL`, `UNIX` socket types.

## Examples

* It can bridge standard input/output and tcp connection to address **127.0.0.1** on port **80**.
```
winsocat.exe STDIO TCP:127.0.0.1:80
winsocat STDIO TCP:127.0.0.1:80
```

* It can forward from Windows named pipe to remote tcp socket.
```
winsocat.exe NPIPE-LISTEN:myPipe TCP:127.0.0.1:80
winsocat NPIPE-LISTEN:myPipe TCP:127.0.0.1:80
```

* It can use Windows named pipe for network connection
```
winsocat.exe NPIPE:RemoteServer:RemotePipe STDIO
winsocat NPIPE:RemoteServer:RemotePipe STDIO
```

* It can create reverse shell.
```
winsocat.exe EXEC:C:\Windows\syetem32\cmd.exe TCP:127.0.0.1:8000
winsocat EXEC:C:\Windows\syetem32\cmd.exe TCP:127.0.0.1:8000
```

* It can bridge Windows named pipe and [unix socket on Windows](https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/)
```
winsocat NPIPE-LISTEN:fooPipe UNIX:foo.sock
```

### Interact with WSL(Windows Subsystem for Linux)

WinSocat provide the syntax sugar for WSL program. Hence, this example
```
winsocat.exe STDIO WSL:cat,distribution=Ubuntu,user=root
winsocat STDIO WSL:cat,distribution=Ubuntu,user=root
```
would be equivalent to
```
winsocat.exe STDIO EXEC:"C:\Windows\System32\wsl.exe -d Ubuntu -u root cat"
winsocat STDIO EXEC:"C:\Windows\System32\wsl.exe -d Ubuntu -u root cat"
```
if `wsl.exe` is located on `C:\Windows\System32`.

Expand All @@ -61,10 +73,10 @@ You can combine the `socat` of WSL distribution for the communication between WS

* Windows named pipe forwarding to WSL Unix Socket
```
winsocat.exe NPIPE-LISTEN:fooPipe WSL:"socat STDIO unix-connect:foo.sock"
winsocat NPIPE-LISTEN:fooPipe WSL:"socat STDIO unix-connect:foo.sock"
```

* WSL Unix Socket forwarding to Windows named pipe
```
socat unix-listen:foo.sock EXEC:"/path/to/winsocat.exe STDIO NPIPE:fooPipe"
socat unix-listen:foo.sock,fork EXEC:"/path/to/winsocat.exe STDIO NPIPE:fooPipe"
```

0 comments on commit f743a6b

Please sign in to comment.