simpleshell

README

simpleshell the Library

A small library for sticking a simple shell in another program. Also makes it reasonably easy to connect something other than a shell with Curlrevshell.

Documentation

Overview

Package simpleshell is a no-frills shell which connects to Curlrevshell.

Index

• Constants
• Variables
• func Go(ctx context.Context, conf ConnConfig, shell Shell) error
• func GoSimple(ctx context.Context, c2, fingerprint string, args []string) error
• func SplitArgs(s string) []string
• func TLSFingerprintVerifier(fp string) (func(tls.ConnectionState) error, error)
• type CmdShell
  • func NewCmdShell(cmd *exec.Cmd) (*CmdShell, error)
  • func (c *CmdShell) Go(ctx context.Context) error
  • func (c *CmdShell) Output() io.ReadCloser
  • func (c *CmdShell) SetInput(in io.Reader)
  • func (c *CmdShell) String() string
• type ConnConfig
• type EchoShell
  • func NewEchoShell() (in *io.PipeWriter, out *io.PipeReader, shell *EchoShell)
  • func (e *EchoShell) Go(ctx context.Context) error
  • func (e *EchoShell) Output() io.ReadCloser
  • func (e *EchoShell) SetInput(in io.Reader)
• type Shell

Constants

const (
	// IOPath is the path on Curlrevshell to which we'll connect.
	IOPath = "/io"
	// DefaultShell is the path to the shell used if [GoSimple] is
	// called with no args.
	DefaultShell = "/bin/sh"
)

Variables

var ErrNoMatchingCertificate = errors.New(
	"no certificate with correct fingerprint found",
)

ErrNoMatchingCertificate indicates a TLS connection's peer did not present a certificate matching a configured fingerprint.

Functions

func Go

func Go(ctx context.Context, conf ConnConfig, shell Shell) error

Go connects a Shell to Curlrevshell.

func GoSimple

func GoSimple(ctx context.Context, c2, fingerprint string, args []string) error

GoSimple is the simplest way to run a shell. It wraps CmdShell, ConnConfig, and Go. If args is empty or nil, []string{DefaultShell} will be used.

func SplitArgs

func SplitArgs(s string) []string

SplitArgs splits s into a slice of strings using the first rune in s as the separator. Runs of empty elements are not compressed.

func TLSFingerprintVerifier

func TLSFingerprintVerifier(fp string) (
	func(tls.ConnectionState) error,
	error,
)

TLSFingerprintVerifier returns a function which can be used for tls.Config.VerifyConnection. It ensures the peer presents a certificate with the given fingerprint, which must be a base64-encoded sha256 hash as used by curl, with or without the leading sha256//.

Types

type CmdShell

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

CmdShell turns an *exec.Cmd into a Shell.

func NewCmdShell

func NewCmdShell(cmd *exec.Cmd) (*CmdShell, error)

NewCmdShell returns a new CmdShell which wraps cmd.

func (*CmdShell) Go

func (c *CmdShell) Go(ctx context.Context) error

Go runs c's exec.Cmd. ctx is not used; use exec.CommandContext or cause an EOF on the io.Reader set via c.SetInPipe to stop Go.

func (*CmdShell) Output

func (c *CmdShell) Output() io.ReadCloser

Output returns an io.Reader on which c sends output.

func (*CmdShell) SetInput

func (c *CmdShell) SetInput(in io.Reader)

SetInput sets the io.Reader from which c reads input.

func (*CmdShell) String

func (c *CmdShell) String() string

String calls c's exec.Cmd.String.

type ConnConfig

type ConnConfig struct {
	// C2 is where we find curlrevshell.  Its path should normaly be
	// IOPath.
	C2 string

	// Fingerprint is the Base64-encoded SHA256 hash of the server's TLS
	// certificate, as normally passed to curl --pinnedpubkey.  The
	// leading sha256// is optional.
	Fingerprint string
}

ConnConfig describes a connection between a Shell and Curlrevshell.

type EchoShell

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

EchoShell is a Shell which just echos its input to its output, useful for testing.

func NewEchoShell

func NewEchoShell() (in *io.PipeWriter, out *io.PipeReader, shell *EchoShell)

NewEchoShell returns a new EchoShell and pre-made i/o.

func (*EchoShell) Go

func (e *EchoShell) Go(ctx context.Context) error

Go copies between the returned i/o pipes. ctx is ignored; close the input to stop Go.

func (*EchoShell) Output

func (e *EchoShell) Output() io.ReadCloser

Output returns o's output. This is the same *io.PipeReader returned by NewEchoShell.

func (*EchoShell) SetInput

func (e *EchoShell) SetInput(in io.Reader)

SetInput sets e's input; this is normally unnecessary.

type Shell

type Shell interface {
	// SetInput sets the io.Reader on which data from Curlrevshell will be
	// sent.
	SetInput(in io.Reader)

	// Output returns an io.Reader from which data to send to Curlrevshell
	// will be read.  Shells must close the returned io.Reader when no more
	// will be read, e.g. when an underlying subprocess terminates.
	// Output will always be called by Go.
	Output() io.ReadCloser

	// Go runs the underlying shell.  The io.ReadCloser returned by Output
	// should be closed before Go returns.
	// Go should not return an error if both all I/O completed successfully
	// and the underlying shell completed successfully, e.g. a subprocess
	// returned 0 on Unix.
	Go(ctx context.Context) error
}

Shell is connected to Curlrevshell by Go. It need not actually be a "real" shell (e.g. /bin/sh).