nutsak

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 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()
    }()

	if e = sak.Pair(a, b); e != nil {
        panic(e)
    }
}

TODO

  • 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)
}

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.0"

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()

Banner will display a fancy piece of art to stdout.

func BannerNSFW 

func BannerNSFW()

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
sak
tools
docextract

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.