nutsak

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 8, 2022 License: GPL-3.0 Imports: 14 Imported by: 0

README

Network Utility Swiss-Army Knife (NUtSAK)

🍪 Buy me a cookie

Go Report Card

What is this?

NUtSAK is a network utility library. Included is a client offering similar features to socat.

How to install

Open a terminal and run the following:

$ # For library usage
$ go get --ldflags "-s -w" --trimpath -u gitlab.com/mjwhitta/nutsak
$ # For cli usage
$ go install --ldflags "-s -w" --trimpath \
    gitlab.com/mjwhitta/nutsak/cmd/sak@latest

Or compile from source:

$ git clone https://gitlab.com/mjwhitta/nutsak.git
$ cd nutsak
$ git submodule update --init
$ make

Usage

CLI

To create a simple TCP listner:

$ sak tcp-listen:4444,fork stdout

To create a simple TCP client:

$ sak stdin tcp:4444
Library
package main

import (
    "time"

    sak "gitlab.com/mjwhitta/nutsak"
)

func main() {
    var a sak.NUt
    var b sak.NUt
    var e error

    // Create first NUt
    if a, e = sak.NewNUt("tcp-listen:4444,fork"); e != nil {
        panic(e)
    }

    // Create second NUt
    if b, e = sak.NewNUt("stdout"); e != nil {
        panic(e)
    }

    // Shutdown in 10 seconds
    go func() {
        time.Sleep(10 * time.Second)
        a.Down()
        b.Down()
    }()

    // Pair NUts to create two-way tunnel
    if e = sak.Pair(a, b); e != nil {
        panic(e)
    }
}

TODO

  • Improve TCP/TLS fork option
  • EXEC process support
  • HTTP proxy support

Documentation

Overview

Package nutsak (Network Utility Swiss-Army Knife) will provide a means of tunneling traffic between two endpoints. Here is sample code to create a Pair:

var a sak.NUt
var b sak.NUt
var e error

// Create first NUt
if a, e = sak.NewNUt("tcp-listen:4444,fork"); e != nil {
    panic(e)
}

// Create second NUt
if b, e = sak.NewNUt("stdout"); e != nil {
    panic(e)
}

// Pair NUts to create two-way tunnel
if e = sak.Pair(a, b); e != nil {
    panic(e)
}

This will create a TCP listener on port 4444 that forks each new connection. Any received data will be written to STDOUT. The Network Utilties (NUts) are created from seeds. Below are the supported SEED TYPES along with their documentation:

FILE:addr[,mode=(append|read|write)]

This seed takes an address that is an absolute or relative filename. This seed is used to read or write a file on disk. The default mode is read.

STDIO:

Aliases: -, STDIN, STDOUT

This seed takes no address or options. It can be used to read from stdin or write to stdout.

TCP:addr

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to make an outgoing TCP connection.

TCP-LISTEN:addr[,fork]

Aliases: TCP-L

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to listen on the provided TCP address. The fork option causes the TCP listener to accept multiple connections in parallel.

TLS:addr[,ca=PATH,cert=PATH,key=PATH,verify]

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to make an outgoing TLS connection. The ca, cert, and key options take a filepath (DER or PEM formatted). The verify option determines if the the server-side CA should be verified. The cert and key options must be used together. If verify is specified, a ca must also be specified.

TLS-LISTEN:addr[,ca=PATH,cert=PATH,fork,key=PATH,verify]

Aliases: TLS-L

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to listen on the provided TCP address. The ca, cert, and key options take a filepath (DER or PEM formatted). The fork option causes the TLS listener to accept multiple connections in parallel. The verify option determines if the client-side certificate should be verified. The cert and key options are mandatory. If verify is specified, a ca must also be specified.

UDP:addr

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to make an outgoing UDP connection.

UDP-LISTEN:addr

Aliases: UDP-L

This seed takes an address of the form [IP:]PORT. The IP is optional and essentially defaults to localhost, or more specifically, 0.0.0.0 or [::]. This seed is used to listen on the provided UDP address.

Index

Constants

View Source
const Version = "1.0.3"

Version is the package version.

Variables

View Source
var LogLvl int

LogLvl will be used to determine the amount of log messages displayed.

View Source
var Logger *log.Messenger

Logger will be used to log information deemed relevant to the user.

Functions

func Banner(hide ...bool)

Banner will display a fancy piece of art to stdout.

func BannerNSFW

func BannerNSFW(hide ...bool)

BannerNSFW will display a NSFW piece of art to stdout.

func Pair

func Pair(a NUt, b NUt) error

Pair will connect two NUts together using Stream().

func Stream

func Stream(a NUt, b NUt) error

Stream will stream data from a to b using io.Copy().

Types

type FileNUt

type FileNUt struct {
	// contains filtered or unexported fields
}

FileNUt is a file network utility.

func NewFileNUt

func NewFileNUt(seed string) (*FileNUt, error)

NewFileNUt will return a pointer to a file network utility instance with the provided seed.

func (FileNUt) Close

func (nut FileNUt) Close() error

Close is an alias for Down().

func (*FileNUt) Down

func (nut *FileNUt) Down() error

Down will stop the network utility. In the case of file, it will close the file.

func (FileNUt) IsUp

func (nut FileNUt) IsUp() bool

IsUp will return whether or not the network utiltity is up and running.

func (*FileNUt) KeepAlive

func (nut *FileNUt) KeepAlive() bool

KeepAlive will return whether or not the network utility should be left running upon EOF. In the case of a file, it is dependent upon mode.

func (FileNUt) Open

func (nut FileNUt) Open() error

Open is an alias for Up().

func (*FileNUt) Read

func (nut *FileNUt) Read(p []byte) (int, error)

Read will read from the file.

func (FileNUt) String

func (nut FileNUt) String() string

String will return a string representation of the network utility.

func (FileNUt) Type

func (nut FileNUt) Type() string

Type will return the type of the network utility.

func (*FileNUt) Up

func (nut *FileNUt) Up() error

Up will start the network utility. In the case of file, it will open the file with the specified mode.

func (*FileNUt) Write

func (nut *FileNUt) Write(p []byte) (int, error)

Write will write to the file.

type NUt

type NUt interface {
	// BaseNUt
	Close() error
	IsUp() bool
	Open() error
	String() string
	Type() string

	// Needs implemented
	Down() error
	KeepAlive() bool
	Read(p []byte) (n int, e error)
	Up() error
	Write(p []byte) (n int, e error)
}

NUt is a network utility capable of reading and writing to a network connection.

func NewNUt

func NewNUt(seed string) (NUt, error)

NewNUt will return a new network utility from the provided seed string.

type StdioNUt

type StdioNUt struct {
	// contains filtered or unexported fields
}

StdioNUt is a stdio network utility.

func NewStdioNUt

func NewStdioNUt(seed string) (*StdioNUt, error)

NewStdioNUt will return a pointer to a stdio network utility instance with the provided seed.

func (StdioNUt) Close

func (nut StdioNUt) Close() error

Close is an alias for Down().

func (*StdioNUt) Down

func (nut *StdioNUt) Down() error

Down will stop the network utility. In the case of stdio, it will do nothing.

func (StdioNUt) IsUp

func (nut StdioNUt) IsUp() bool

IsUp will return whether or not the network utiltity is up and running.

func (*StdioNUt) KeepAlive

func (nut *StdioNUt) KeepAlive() bool

KeepAlive will return whether or not the network utility should be left running upon EOF. In the case of stdio, it should always return true, if it is also up.

func (StdioNUt) Open

func (nut StdioNUt) Open() error

Open is an alias for Up().

func (*StdioNUt) Read

func (nut *StdioNUt) Read(p []byte) (int, error)

Read will read from stdin.

func (StdioNUt) String

func (nut StdioNUt) String() string

String will return a string representation of the network utility.

func (StdioNUt) Type

func (nut StdioNUt) Type() string

Type will return the type of the network utility.

func (*StdioNUt) Up

func (nut *StdioNUt) Up() error

Up will start the network utility. In the case of stdio, it will do nothing.

func (*StdioNUt) Write

func (nut *StdioNUt) Write(p []byte) (int, error)

Write will write to stdout.

type TCPNUt

type TCPNUt struct {
	// contains filtered or unexported fields
}

TCPNUt is a TCP network utility.

func NewTCPNUt

func NewTCPNUt(seed string) (*TCPNUt, error)

NewTCPNUt will return a pointer to a TCP network utility instance with the provided seed.

func (TCPNUt) Close

func (nut TCPNUt) Close() error

Close is an alias for Down().

func (*TCPNUt) Down

func (nut *TCPNUt) Down() error

Down will stop the network utility. In the case of TCP, it will close the connection or listener, depending on the mode.

func (TCPNUt) IsUp

func (nut TCPNUt) IsUp() bool

IsUp will return whether or not the network utiltity is up and running.

func (*TCPNUt) KeepAlive

func (nut *TCPNUt) KeepAlive() bool

KeepAlive will return whether or not the network utility should be left running upon EOF. In the case of TCP, it is dependent upon mode.

func (TCPNUt) Open

func (nut TCPNUt) Open() error

Open is an alias for Up().

func (*TCPNUt) Read

func (nut *TCPNUt) Read(p []byte) (int, error)

Read will read from the current TCP connection.

func (TCPNUt) String

func (nut TCPNUt) String() string

String will return a string representation of the network utility.

func (TCPNUt) Type

func (nut TCPNUt) Type() string

Type will return the type of the network utility.

func (*TCPNUt) Up

func (nut *TCPNUt) Up() error

Up will start the network utility. In the case of TCP, it will either connect or listen, depending on the mode.

func (*TCPNUt) Write

func (nut *TCPNUt) Write(p []byte) (int, error)

Write will write to the current TCP connection.

type TLSNUt

type TLSNUt struct {
	// contains filtered or unexported fields
}

TLSNUt is a TLS network utility.

func NewTLSNUt

func NewTLSNUt(seed string) (*TLSNUt, error)

NewTLSNUt will return a pointer to a TLS network utility instance with the provided seed.

func (TLSNUt) Close

func (nut TLSNUt) Close() error

Close is an alias for Down().

func (*TLSNUt) Down

func (nut *TLSNUt) Down() error

Down will stop the network utility. In the case of TLS, it will close the connection or listener, depending on the mode.

func (TLSNUt) IsUp

func (nut TLSNUt) IsUp() bool

IsUp will return whether or not the network utiltity is up and running.

func (*TLSNUt) KeepAlive

func (nut *TLSNUt) KeepAlive() bool

KeepAlive will return whether or not the network utility should be left running upon EOF. In the case of TLS, it is dependent upon mode.

func (TLSNUt) Open

func (nut TLSNUt) Open() error

Open is an alias for Up().

func (*TLSNUt) Read

func (nut *TLSNUt) Read(p []byte) (int, error)

Read will read from the current TLS connection.

func (TLSNUt) String

func (nut TLSNUt) String() string

String will return a string representation of the network utility.

func (TLSNUt) Type

func (nut TLSNUt) Type() string

Type will return the type of the network utility.

func (*TLSNUt) Up

func (nut *TLSNUt) Up() error

Up will start the network utility. In the case of TLS, it will either connect or listen, depending on the mode.

func (*TLSNUt) Write

func (nut *TLSNUt) Write(p []byte) (int, error)

Write will write to the current TLS connection.

type UDPNUt

type UDPNUt struct {
	// contains filtered or unexported fields
}

UDPNUt is a UDP network utility.

func NewUDPNUt

func NewUDPNUt(seed string) (*UDPNUt, error)

NewUDPNUt will return a pointer to a UDP network utility instance with the provided seed and mode.

func (UDPNUt) Close

func (nut UDPNUt) Close() error

Close is an alias for Down().

func (*UDPNUt) Down

func (nut *UDPNUt) Down() error

Down will stop the network utility. In the case of UDP, it will close the connection.

func (UDPNUt) IsUp

func (nut UDPNUt) IsUp() bool

IsUp will return whether or not the network utiltity is up and running.

func (*UDPNUt) KeepAlive

func (nut *UDPNUt) KeepAlive() bool

KeepAlive will return whether or not the network utility should be left running upon EOF. In the case of UDP, it should always return true, if it is also up.

func (UDPNUt) Open

func (nut UDPNUt) Open() error

Open is an alias for Up().

func (*UDPNUt) Read

func (nut *UDPNUt) Read(p []byte) (int, error)

Read will read from the current UDP connection.

func (UDPNUt) String

func (nut UDPNUt) String() string

String will return a string representation of the network utility.

func (UDPNUt) Type

func (nut UDPNUt) Type() string

Type will return the type of the network utility.

func (*UDPNUt) Up

func (nut *UDPNUt) Up() error

Up will start the network utility. In the case of UDP, it will either connect or listen, depending on the mode.

func (*UDPNUt) Write

func (nut *UDPNUt) Write(p []byte) (int, error)

Write will write to the current UDP connection.

Directories

Path Synopsis
cmd
sak
tools

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL