Skip to content

Latest commit

 

History

History
146 lines (124 loc) · 8.71 KB

README.md

File metadata and controls

146 lines (124 loc) · 8.71 KB
Raw

Description

This directory provides some examples of using gWisord and some info for it's configuration. Also, here you may found info about writing js scripts to interact with gVisor

Configuration info

May be found here

Base info

With proper configuration gVisor may use js hooks, which has ability to modify syscall arguments, return values to allow or prohibit execution of a system calls and to do some other features. Hooks should be written in some files.

Hook is registered for special syscall, and will be executed only if syscall is used.

Note that each hook is stored as string, so goja interprets the hook each time it should be executed.

For each syscall user can specify 2 hooks:

  • hook, which will be executed before syscall
  • hook, which will be executed after syscall

Both hook can use:

  • API provided by gVisor (which is called accessors) (full list of available functions you may see below)
accessors.print("my message") // "accessors" is reseved object for our API
  • local and global storage
lStore = persistence.local // is a local storage for thread
gStore = persistence.glb // is a global storage, all data will be available from any thread

// quick example of usage
lStore.someData = "my custom data" // set the string to new field 'someData' of local storage
gStore.anotherData = 25

Hook registration

You have 2 ways to register your hook

  • Call accessors.AddHookBefore(...) or accessors.AddHookAfter(...) (see below)
  • Set them in config (see the configuration/README for more info)

Hook before

Has the following abilities:

  • get syscall arguments
  • set:
    • new values for syscall arguments
    • both new syscall return value and errno (if syscall new return value and errno is specified the syscall will NOT be executed)

Hook after

Has the following abilities:

  • get syscall arguments
  • set:
    • new values for syscall arguments
    • new syscall return value

Examples

List of API functions (accessors)

Some API functions have object as return value. The structure of such objects you can see below the table

func name arguments return value description
AddHookBefore sysno number
hook function		 null Registers function (hook) which will be executed before syscall with number == sysno
AddHookAfter sysno number
hook function		 null Registers function (hook) which will be executed after syscall with number == sysno
anonMmap length number number Allocates length bytes in process memory. Returns the start address of memory region
getArgv - []string Returns array of strings which is the command line arguments
getEnvs - []string Returns the array of environment variables (string, which have format like ENVIRONMENT_NAME=environment_value)
getFdInfo fd number object (FdInfoDto) Returns the dto, which provides info about task's file description by given fd
getFdsInfo - []object (FdInfoDto) Returns the array of dto, each dto provides info for some task's file description
getMmaps - []object (MmapInfoDto) Returns the array of objects, that represents mappings of the task (content is like mappings info from procfs)
getPidInfo - object (PidInfoDto) Returns the dto, which provides info about task's PID, GID, UID, session
getSignalInfo - object (SignalInfoDto) Returns the dto, which provides info about task's signal masks and sigactions
getThreadInfo -
or
tid number		 object (ThreadInfoDto) Returns the dto, which provides TID, TGID (PID) and list of other TIDs in thread group.
logJson msg any null Sends the given msg to log socket
munmap addr number
length number		 null Delete the mappings from the specified address range by given addr and length of the region
nameToSignal name string number Returns the number of the signal by provided name
print msgs ...any null Prints all the given msgs
readBytes addr number
count number		 ArrayBuffer Reads count bytes from memory by given addr. Returns the bytes read
readString addr number
count number		 string Reads the string (string.length <= count) by given addr. Returns the read string
resumeThreads - null Resume threads stopped by stopThreads.
sendSignal tid number
signo number		 null Sends to task with tid == tid the signal with number signo
signalMaskToNames mask number []string Parses provided signal mask to signal names. Returns array of strings - names of signals specified in the mask
stopThreads - null Stop all threads except the caller. May be useful for preventing TOCTOU attack.
writeBytes addr number
buffer ArrayBuffer		 number Writes to memory the given buffer by the given addr. Returns the amount of really written bytes
writeString addr number
str string		 number Writes the given str by given addr. Returns the amount of bytes really written 
SignalInfoDto = {
  SignalMask `number`       // signal mask of the task
  SignalWaitMask `number`   // task will be blocked until one of signals in signalWaitMask is pending
  SavedSignalMask `number`  // savedSignalMask is the signal mask that should be applied after the task has either delivered one signal to a user handler or is about to resume execution in the untrusted application
  Sigactions [
    Handler `string`
    Flags `string`      
    Restorer `number`
    SignalsInSet `[]string` // array of strings, each string is a signal name      
  ]
}

PidInfoDto = {
  PID `number`
  GID `number`
  UID `number`
  Session {
    SessionID `number`
    PGID `number`
    ForegroundID `number`
    OtherPGIDs `[]number`
  }
}

FdInfoDto = {
  Fd `number`
  Name `string`       // file path
  Mode `string`       // mode like rwxr--r--
  Flags `string`      // flags of the file
  Nlinks `number`
  Readble `boolean`
  Writable `boolean`
}

ThreadInfoDto = {
  TID `number`
  TGID `number`
  TIDsInTg `[]number`
}

MmapInfo = {
  Start `number`  
  End `number`  
  Readable `boolean`   
  Writeable `boolean`  
  Executable `boolean`  
  Private `boolean` 
  Offset `number`  
  DevMajor `number` 
  DevMinor `number` 
  Inode `number`  
  Path `string` 
}