vos

package
v0.0.0-...-6a41818 Latest Latest
Warning

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

 Go to latest Published: Mar 18, 2024 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package vos provides a virtual OS abstraction.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = exec.ErrNotFound

ErrNotFound is the error resulting if a path search failed to find an executable file.

Functions

func CopyEnv 

func CopyEnv(dst VEnv, src []string) error

CopyEnv copies all the environment variables from src to dst.

Example 
env := NewMapEnv()
CopyEnv(env, []string{"A=B", "C=D", "E", "F=G=H"})

fmt.Printf("Environ(): %q\n", env.Environ())
fmt.Printf("Getenv(\"F\"): %q\n", env.Getenv("F"))

Output:

Environ(): ["A=B" "C=D" "E=" "F=G=H"]
Getenv("F"): "G=H"

func ExtractTarToVFS 

func ExtractTarToVFS(vfs VFS, t *tar.Reader) error

func LookPath 

func LookPath(vos VOS, file string) (string, error)

LookPath searches for an executable named file in the directories named by the PATH environment variable. If file contains a slash, it is tried directly and the PATH is not consulted. The result may be an absolute path or a path relative to the current directory.

func NewPathMappingFs 

func NewPathMappingFs(base afero.Fs, mapper FileMapper) afero.Fs

Types

type DownloadInfo 

type DownloadInfo struct {
	Source    string   `json:"source"`
	SessionID string   `json:"session_id"`
	Cmd       []string `json:"cmd"`
}

type EnvironFetcher 

type EnvironFetcher interface {
	// Environ returns a copy of strings representing the environment, in the
	// form "key=value".
	Environ() []string
}

type EventRecorder 

type EventRecorder interface {
	Record(event logger.LogType) error
	SessionID() string
}

type FileMapper 

type FileMapper func(op FsOp, name string) (path string, err error)

type FsOp 

type FsOp = string

FsOp is a textual description of the filesystem operation. 

const (
	FsOpChtimes  FsOp = "chtimes"
	FsOpSymlink  FsOp = "symlink"
	FsOpChmod    FsOp = "chmod"
	FsOpChown    FsOp = "chown"
	FsOpStat     FsOp = "stat"
	FsOpRename   FsOp = "rename"
	FsOpRemove   FsOp = "remove"
	FsOpOpen     FsOp = "open"
	FsOpMkdir    FsOp = "mkdir"
	FsOpCreate   FsOp = "create"
	FsOpLstat    FsOp = "lstat"
	FsOpReadlink FsOp = "readlink"
)

type Honeypot 

type Honeypot interface {
	// BootTime provides a fake boot itme.
	BootTime() time.Time
	// LoginTime provides the time the session started.
	LoginTime() time.Time
	// SSHUser returns the username used when establishing the SSH connection.
	SSHUser() string
	// SSHRemoteAddr returns the net.Addr of the client side of the connection.
	SSHRemoteAddr() net.Addr
	// Write to the attahed SSH session's output.
	SSHStdout() io.Writer
	// Exit the attached SSH session.
	SSHExit(int) error

	SetPTY(PTY)
	GetPTY() PTY

	StartProcess(name string, argv []string, attr *ProcAttr) (VOS, error)

	// Log an invalid command invocation, it may indicate a missing honeypot
	// feature.
	LogInvalidInvocation(err error)

	// Record when credentials are used by the attacker.
	LogCreds(*logger.Credentials)

	// Get a unique path in the downloads folder that the session can write a
	// file to.
	DownloadPath(source string) (afero.File, error)

	// Now is the current honeypot time.
	Now() time.Time
}

Honeypot contains non-OS utilities related to running the honeypot.

type LinkingFsWrapper 

type LinkingFsWrapper struct {
	VFS
}

LinkingFsWrapper backfills POSIX style symlink functionality onto other file types.

func (*LinkingFsWrapper) LstatIfPossible 

func (lfs *LinkingFsWrapper) LstatIfPossible(name string) (os.FileInfo, bool, error)

func (*LinkingFsWrapper) ReadlinkIfPossible 

func (lfs *LinkingFsWrapper) ReadlinkIfPossible(name string) (string, error)

func (*LinkingFsWrapper) SymlinkIfPossible 

func (lfs *LinkingFsWrapper) SymlinkIfPossible(oldname, newname string) error

type MapEnv 

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

MapEnv implemnts an in-memory VEnv.

func NewMapEnv 

func NewMapEnv() *MapEnv

NewMapEnv creates a new environment backed by a map.

func NewMapEnvFromEnvList 

func NewMapEnvFromEnvList(environ []string) *MapEnv

NewMapEnvFrom creates a new environment with a copy of the environment variables from the given map.

Example 
env := NewMapEnvFromEnvList([]string{"A=B", "C=D", "E", "F=G=H"})

fmt.Printf("Environ(): %q\n", env.Environ())
fmt.Printf("Getenv(\"F\"): %q\n", env.Getenv("F"))

Output:

Environ(): ["A=B" "C=D" "E=" "F=G=H"]
Getenv("F"): "G=H"

func (*MapEnv) Environ 

func (m *MapEnv) Environ() []string

Environ implements VEnv.Environ.

func (*MapEnv) Getenv 

func (m *MapEnv) Getenv(key string) string

Getenv implements VEnv.Getenv.

func (*MapEnv) LookupEnv 

func (m *MapEnv) LookupEnv(key string) (string, bool)

LookupEnv implements VEnv.LookupEnv.

Example 
env := NewMapEnv()
env.Setenv("A", "B")

val, ok := env.LookupEnv("A")
fmt.Println("Existing", "val:", val, "ok:", ok)
val, ok = env.LookupEnv("B")
fmt.Println("Missing", "val:", val, "ok:", ok)

Output:

Existing val: B ok: true
Missing val:  ok: false

func (*MapEnv) Setenv 

func (m *MapEnv) Setenv(key, value string) error

Setenv implements VEnv.Setenv.

func (*MapEnv) Unsetenv 

func (m *MapEnv) Unsetenv(key string) error

Unsetenv implements VEnv.Unsetenv.

Example 
env := NewMapEnv()
env.Setenv("A", "B")
env.Setenv("C", "D")

fmt.Println("Before:", env.Environ())
env.Unsetenv("A")
fmt.Println("After:", env.Environ())

Output:

Before: [A=B C=D]
After: [C=D]

type Mount 

type Mount struct {
	// Path is the directory the volume is mounted at.
	Path string
	FS   VFS
}

type MountFS 

type MountFS struct {
	// Root is the root filesystem.
	Root VFS
	// List of mounted volumes, sorted deepest first.
	Mounts []Mount
}

func NewMountFS 

func NewMountFS(root VFS) *MountFS

func (*MountFS) Chmod 

func (mfs *MountFS) Chmod(name string, mode fs.FileMode) error

Chmod changes the mode of the named file to mode.

func (*MountFS) Chown 

func (mfs *MountFS) Chown(name string, uid, gid int) error

Chown changes the uid and gid of the named file.

func (*MountFS) Chtimes 

func (mfs *MountFS) Chtimes(name string, atime, mtime time.Time) error

Chtimes changes the access and modification times of the named file

func (*MountFS) Create 

func (mfs *MountFS) Create(name string) (afero.File, error)

Create creates a file in the filesystem, returning the file and an error, if any happens.

func (*MountFS) Mkdir 

func (mfs *MountFS) Mkdir(name string, mode fs.FileMode) error

Mkdir creates a directory in the filesystem, return an error if any happens.

func (*MountFS) MkdirAll 

func (mfs *MountFS) MkdirAll(name string, mode fs.FileMode) error

MkdirAll creates a directory path and all parents that does not exist yet.

func (*MountFS) Mount 

func (mfs *MountFS) Mount(path string, mountFS VFS) error

func (*MountFS) Name 

func (mfs *MountFS) Name() string

func (*MountFS) Open 

func (mfs *MountFS) Open(name string) (afero.File, error)

Open opens a file, returning it or an error, if any happens.

func (*MountFS) OpenFile 

func (mfs *MountFS) OpenFile(name string, flag int, perm fs.FileMode) (afero.File, error)

func (*MountFS) Remove 

func (mfs *MountFS) Remove(name string) error

Remove removes a file identified by name, returning an error, if any happens.

func (*MountFS) RemoveAll 

func (mfs *MountFS) RemoveAll(name string) error

RemoveAll removes a directory path and any children it contains. It does not fail if the path does not exist (return nil).

func (*MountFS) Rename 

func (mfs *MountFS) Rename(oldname, newname string) error

Rename renames (moves) oldpath to newpath. If newpath already exists and is not a directory, Rename replaces it. Files may not be moved across FS boundaries.

func (*MountFS) Resolve 

func (mfs *MountFS) Resolve(path string) (VFS, string)

func (*MountFS) Stat 

func (mfs *MountFS) Stat(name string) (fs.FileInfo, error)

Stat returns a FileInfo describing the named file, or an error, if any happens.

type PTY 

type PTY struct {
	Width  int
	Height int
	Term   string
	IsPTY  bool
}

type PathMappingFs 

type PathMappingFs struct {
	BaseFs afero.Fs
	Mapper FileMapper
}

PathMappingFs maps all paths on a filesystem via callback to another path.

func (*PathMappingFs) Chmod 

func (b *PathMappingFs) Chmod(name string, mode os.FileMode) (err error)

func (*PathMappingFs) Chown 

func (b *PathMappingFs) Chown(name string, uid, gid int) (err error)

func (*PathMappingFs) Chtimes 

func (b *PathMappingFs) Chtimes(name string, atime, mtime time.Time) (err error)

func (*PathMappingFs) Create 

func (b *PathMappingFs) Create(name string) (f afero.File, err error)

func (*PathMappingFs) LstatIfPossible 

func (b *PathMappingFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

func (*PathMappingFs) Mkdir 

func (b *PathMappingFs) Mkdir(name string, mode os.FileMode) (err error)

func (*PathMappingFs) MkdirAll 

func (b *PathMappingFs) MkdirAll(name string, mode os.FileMode) (err error)

func (*PathMappingFs) Name 

func (b *PathMappingFs) Name() string

func (*PathMappingFs) Open 

func (b *PathMappingFs) Open(name string) (f afero.File, err error)

func (*PathMappingFs) OpenFile 

func (b *PathMappingFs) OpenFile(name string, flag int, mode os.FileMode) (f afero.File, err error)

func (*PathMappingFs) ReadlinkIfPossible 

func (b *PathMappingFs) ReadlinkIfPossible(name string) (string, error)

func (*PathMappingFs) Remove 

func (b *PathMappingFs) Remove(name string) (err error)

func (*PathMappingFs) RemoveAll 

func (b *PathMappingFs) RemoveAll(name string) (err error)

func (*PathMappingFs) Rename 

func (b *PathMappingFs) Rename(oldname, newname string) (err error)

func (*PathMappingFs) Stat 

func (b *PathMappingFs) Stat(name string) (fi os.FileInfo, err error)

func (*PathMappingFs) SymlinkIfPossible 

func (b *PathMappingFs) SymlinkIfPossible(oldname, newname string) error

type PathMappingFsFile 

type PathMappingFsFile struct {
	afero.File
	// contains filtered or unexported fields
}

PathMappingFsFile implements afero.File.

func (*PathMappingFsFile) Name 

func (f *PathMappingFsFile) Name() string

Name returns the name of the file.

type ProcAttr 

type ProcAttr struct {
	// If Dir is non-empty, the child changes into the directory before
	// creating the process.
	Dir string
	// If Env is non-empty, it gives the environment variables for the
	// new process in the form returned by Environ.
	// If it is nil, the result of Environ will be used.
	Env []string

	// Files specifies the open files inherited by the new process.
	Files VIO
}

type ProcFS 

type ProcFS struct {
	VirtualFS
	// contains filtered or unexported fields
}

func NewProcFS 

func NewProcFS(sharedOS *SharedOS) *ProcFS

func (*ProcFS) Name 

func (*ProcFS) Name() string

func (*ProcFS) Open 

func (pfs *ProcFS) Open(name string) (afero.File, error)

func (*ProcFS) OpenFile 

func (pfs *ProcFS) OpenFile(name string, flag int, perm fs.FileMode) (afero.File, error)

func (*ProcFS) Stat 

func (pfs *ProcFS) Stat(name string) (fs.FileInfo, error)

type ProcessFunc 

type ProcessFunc func(VOS) int

ProcessFunc is a "process" that can be run.

type ProcessResolver 

type ProcessResolver func(path string) ProcessFunc

ProcessResolver looks up a fake process by path, it reuturns nil if no process was found.

type SSHSession 

type SSHSession interface {
	User() string
	RemoteAddr() net.Addr
	Exit(code int) error
	Write([]byte) (int, error)
}

type SharedOS 

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

SharedOS is the shared base OS that each honeypot user gets overlaid on.

All public variables and methods no this type are guaranteed to produce immutable objects.

func NewSharedOS 

func NewSharedOS(baseFS VFS, procResolver ProcessResolver, config *config.Configuration, timeSource TimeSource) *SharedOS

func (*SharedOS) BootTime 

func (s *SharedOS) BootTime() time.Time

func (*SharedOS) GetUser 

func (s *SharedOS) GetUser(username string) (usr config.User, ok bool)

func (*SharedOS) Hostname 

func (s *SharedOS) Hostname() string

func (*SharedOS) NextPID 

func (s *SharedOS) NextPID() int

NextPID gets a monotonically increasing PID.

func (*SharedOS) Now 

func (s *SharedOS) Now() time.Time

func (*SharedOS) ReadOnlyFs 

func (s *SharedOS) ReadOnlyFs() VFS

ReadOnlyFs returns a read only version of the base filesystem that multiple tenants can read from.

func (*SharedOS) SetPID 

func (s *SharedOS) SetPID(pid int32)

func (*SharedOS) Uname 

func (s *SharedOS) Uname() Utsname

type TenantOS 

type TenantOS struct {
	*SharedOS
	// contains filtered or unexported fields
}

func NewTenantOS 

func NewTenantOS(sharedOS *SharedOS, eventRecorder EventRecorder, session SSHSession) *TenantOS

func (*TenantOS) GetPTY 

func (t *TenantOS) GetPTY() PTY

func (*TenantOS) LogCreds 

func (t *TenantOS) LogCreds(creds *logger.Credentials)

LogCreds records credentials that the attacker used.

func (*TenantOS) LoginProc 

func (t *TenantOS) LoginProc() *TenantProcOS

func (*TenantOS) LoginTime 

func (t *TenantOS) LoginTime() time.Time

func (*TenantOS) SSHExit 

func (t *TenantOS) SSHExit(code int) error

SSHExit hangs up the incoming SSH connection.

func (*TenantOS) SSHRemoteAddr 

func (t *TenantOS) SSHRemoteAddr() net.Addr

SSHRemoteAddr returns the net.Addr of the client side of the connection.

func (*TenantOS) SSHStdout 

func (t *TenantOS) SSHStdout() io.Writer

SSHStdout is a direct connection to the SSH stdout stream. Useful for broadcasting messages.

func (*TenantOS) SSHUser 

func (t *TenantOS) SSHUser() string

SSHUser returns the username used when establishing the SSH connection.

func (*TenantOS) SetPTY 

func (t *TenantOS) SetPTY(pty PTY)

type TenantProcOS 

type TenantProcOS struct {
	*TenantOS

	VEnv

	VFS

	VIO

	// Path to the executable that started the process, errors if blank.
	ExecutablePath string
	// Args holds command line arguments, including the command as Args[0].
	ProcArgs []string
	// The process ID of the process
	PID int
	// The user ID of the process.
	UID int
	// Dir specifies the working directory of the command.
	Dir string
	// Exec is the process executable that is run when the process starts.
	Exec ProcessFunc
}

func (*TenantProcOS) Args 

func (ea *TenantProcOS) Args() []string

Args implements VOS.Args.

func (*TenantProcOS) Chdir 

func (ea *TenantProcOS) Chdir(dir string) (err error)

Chdir implements VOS.Chdir.

func (*TenantProcOS) DownloadPath 

func (t *TenantProcOS) DownloadPath(source string) (afero.File, error)

func (*TenantProcOS) Getpid 

func (ea *TenantProcOS) Getpid() int

Getpid implements VOS.Getpid.

func (*TenantProcOS) Getuid 

func (ea *TenantProcOS) Getuid() int

Getuid implements VOS.Getuid.

func (*TenantProcOS) Getwd 

func (ea *TenantProcOS) Getwd() (dir string)

Getwd implements VOS.Getwd.

func (*TenantProcOS) LogInvalidInvocation 

func (ea *TenantProcOS) LogInvalidInvocation(err error)

func (*TenantProcOS) Run 

func (ea *TenantProcOS) Run() (resultCode int)

func (*TenantProcOS) Setuid 

func (ea *TenantProcOS) Setuid(UID int)

Setuid sets the numeric user id of the caller.

func (*TenantProcOS) StartProcess 

func (ea *TenantProcOS) StartProcess(name string, argv []string, attr *ProcAttr) (VOS, error)

StartProcess starts a new process with the program, arguments and attributes specified by name, argv and attr. The argv slice will become os.Args in the new process, so it normally starts with the program name.

type TimeSource 

type TimeSource func() time.Time

type Utsname 

type Utsname struct {
	Sysname    string // OS name e.g. "Linux".
	Nodename   string // Hostname of the machine on one of its networks.
	Release    string // OS release e.g. "4.15.0-147-generic"
	Version    string // OS version e.g. "#151-Ubuntu SMP Fri Jun 18 19:21:19 UTC 2021"
	Machine    string // Machnine name e.g. "x86_64"
	Domainname string // NIS or YP domain name
}

Utsname mimics POSIX sys/utsname.h https://pubs.opengroup.org/onlinepubs/7908799/xsh/sysutsname.h.html

type VEnv 

type VEnv interface {
	// Unsetenv unsets a single environment variable.
	Unsetenv(key string) error

	// Setenv sets the value of the environment variable named by the key.
	// It returns an error, if any.
	Setenv(key, value string) error

	// LookupEnv retrieves the value of the environment variable named by the key.
	// If the variable is present in the environment the value (which may be
	// empty) is returned and the boolean is true. Otherwise the returned value
	// will be empty and the boolean will be false.
	LookupEnv(key string) (string, bool)

	// Getenv retrieves the value of the environment variable named by the key.
	// It returns the value, which will be empty if the variable is not present.
	// To distinguish between an empty value and an unset value, use LookupEnv.
	Getenv(key string) string

	// Environ returns a copy of strings representing the environment, in the
	// form "key=value".
	Environ() []string
}

VEnv represents a virtual environment.

type VFS 

type VFS interface {
	// Create creates a file in the filesystem, returning the file and an
	// error, if any happens.
	Create(name string) (afero.File, error)

	// Mkdir creates a directory in the filesystem, return an error if any
	// happens.
	Mkdir(name string, perm os.FileMode) error

	// MkdirAll creates a directory path and all parents that does not exist
	// yet.
	MkdirAll(path string, perm os.FileMode) error

	// Open opens a file, returning it or an error, if any happens.
	Open(name string) (afero.File, error)

	// OpenFile opens a file using the given flags and the given mode.
	OpenFile(name string, flag int, perm os.FileMode) (afero.File, error)

	// Remove removes a file identified by name, returning an error, if any
	// happens.
	Remove(name string) error

	// RemoveAll removes a directory path and any children it contains. It
	// does not fail if the path does not exist (return nil).
	RemoveAll(path string) error

	// Rename renames a file.
	Rename(oldname, newname string) error

	// Stat returns a FileInfo describing the named file, or an error, if any
	// happens.
	Stat(name string) (os.FileInfo, error)

	Name() string

	// Chmod changes the mode of the named file to mode.
	Chmod(name string, mode os.FileMode) error

	// Chown changes the uid and gid of the named file.
	Chown(name string, uid, gid int) error

	// Chtimes changes the access and modification times of the named file
	Chtimes(name string, atime time.Time, mtime time.Time) error
}

VFS implements a virtual filesystem and is the second layer of the virtual OS.

func NewLinkingFs 

func NewLinkingFs(base VFS) VFS

func NewMemCopyOnWriteFs 

func NewMemCopyOnWriteFs(base VFS, timeSource TimeSource) VFS

func NewSymlinkResolvingRelativeFs 

func NewSymlinkResolvingRelativeFs(base VFS, Getwd func() (dir string)) VFS

func NewVFSFromConfig 

func NewVFSFromConfig(configuration *config.Configuration) (VFS, error)

type VIO 

type VIO interface {
	Stdin() io.ReadCloser
	Stdout() io.WriteCloser
	Stderr() io.WriteCloser
}

func NewNullIO 

func NewNullIO() VIO

NewNullIO creates a valid /dev/null style I/O, reads won't work and writes will be discarded.

type VIOAdapter 

type VIOAdapter struct {
	IStdin  io.ReadCloser
	IStdout io.WriteCloser
	IStderr io.WriteCloser
}

func NewVIOAdapter 

func NewVIOAdapter(stdin io.Reader, stdout, stderr io.Writer) *VIOAdapter

func (*VIOAdapter) Stderr 

func (pr *VIOAdapter) Stderr() io.WriteCloser

func (*VIOAdapter) Stdin 

func (pr *VIOAdapter) Stdin() io.ReadCloser

func (*VIOAdapter) Stdout 

func (pr *VIOAdapter) Stdout() io.WriteCloser

type VKernel 

type VKernel interface {
	Hostname() string
	// Uname mimics the uname syscall.
	Uname() Utsname
}

type VOS 

type VOS interface {
	VKernel
	VEnv
	VIO
	VProc
	VFS
	Honeypot
}

VOS provides a virtual OS interface.

type VProc 

type VProc interface {
	// Getpid returns the process id of the caller.
	Getpid() int

	// Getuid returns the numeric user id of the caller.
	Getuid() int

	// Setuid sets the numeric user id of the caller.
	Setuid(int)

	// Returns the arguments to the current process.
	Args() []string

	// Getwd returns a rooted path name corresponding to the current directory.
	Getwd() (dir string)

	// Chdir changes the directory.
	Chdir(dir string) error

	// Run executes the command, waits for it to finish and returns the status
	// code.
	Run() int
}

type VirtualFS 

type VirtualFS struct{}

VirtualFS returns ErrNotExist for any write or modify operations.

func (*VirtualFS) Chmod 

func (*VirtualFS) Chmod(_ string, _ fs.FileMode) error

func (*VirtualFS) Chown 

func (*VirtualFS) Chown(_ string, _ int, _ int) error

func (*VirtualFS) Chtimes 

func (*VirtualFS) Chtimes(_ string, _, _ time.Time) error

func (*VirtualFS) Create 

func (*VirtualFS) Create(_ string) (afero.File, error)

func (*VirtualFS) Mkdir 

func (*VirtualFS) Mkdir(_ string, _ fs.FileMode) error

func (*VirtualFS) MkdirAll 

func (*VirtualFS) MkdirAll(_ string, _ fs.FileMode) error

func (*VirtualFS) Remove 

func (*VirtualFS) Remove(name string) error

func (*VirtualFS) RemoveAll 

func (*VirtualFS) RemoveAll(name string) error

func (*VirtualFS) Rename 

func (*VirtualFS) Rename(oldname, newname string) error

Source Files

View all Source files

Directories

Path Synopsis

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.