satori-extensions

The Satori Extensions are the main way to extend the Satori Suite's functionalities. They use hooker, a standalone Python Package (available with pip) to add functions in events declared in the Satori Suite components.

Each extension is responsible to gather, store, compare, and even provide a way to visualize a single aspect of an Operating System instance.

Declared Events

In both Satori-ng Imager and Satori-ng Differ, there have been declared 5 hooker events.

For Satori-ng Imager they are:

• imager.on_start - Executes when the Satori-Imager starts the OS imaging process
• imager.pre_open - Executes before a file is open'd using the open OS syscall
• imager.with_open - Executes when the file is opened, the File Descriptor of the file is available
• imager.post_close - Executes when the file is closed using close OS syscall
• imager.on_end - Finally, executes when the Imaging process finishes

For Satori-ng Differ they hold the same name with differ instead of imager (e.g differ.on_start, etc)

Dissecting the entropy extension

The entropy extension code for the Imager hook is the following:

from entropy import shannon_entropy # Python dependency, available with PyPI
from hooker import hook # The hooker package
__name__ = 'shannon'  # Name of the extension

@hook("imager.with_open") # When the file is opened
def calculate(satori_image, file_path, file_type, fd):
    '''
    This argument list is declared for the "imager.with_open" calls.
    All functions hooked for "imager.with_open" must have the same argument list
    
    satori_image: The image object where everything is stored
    file_path: The full path of the opened file
    file_type: The file type as returned from a 'stat' call
    fd: The file descriptor of the opened file
    '''
    
    fd.seek(0)  # Return to the beginning of the file
    e = shannon_entropy(fd.read())  # Read the contents and calculate the entropy - uses the 'entropy' external package
    # set a key named 'entropy' in the file's image, storing the entropy value 'e' in it
    satori_image.set_attribute(file_path, str(e), __name__, force_create=True)

Non-data extensions

The stealthy extension does not gather data.

It just uses os.utime call to perform naive timestomping (resets access/modification times) on the files opened by the Satori-Imager.

It does that using the imager.post_close event hook.

Non-file extensions

What about reading and storing the iptables rules of the Linux OS that is Image'd? No files are opened (as a single iptables-save command has all useful information).

This could be implemented using the imager.on_start event hook:

from hooker import hook
from satoricore.image import _DATA_SECTION

@hook('imager.on_start')
def iptables_save(parser, args, satori_image):
  # Run the 'iptables-save' command and get the output
  proc = subprocess.Popen(['iptables-save'])
  outs, errs = proc.communicate()
  
  # Create a new 'class' in the image to store the iptables result
  satori_image.add_class(
      "iptables",
      section=_DATA_SECTION,
      data=outs,
  )

Multiple functions - single file

An extension file, say bla.py can contain all functions that are needed to Image the bla attribute of an OS instance.

---

bla.py

from hooker import hook

@hook('imager.on_start')
def calc_bla(parser, args, satori_image):
  # Stuff...

---

This same file can be used to also serve as Satori-Differ extension (and it is actually encouraged):

---

bla.py

from hooker import hook

@hook('imager.on_start')
def calc_bla(parser, args, satori_image):
  # Stuff...

@hook('differ.on_start')
def diff_bla(parser, args, source,
  destination, results, diff_name):
  # Stuff...

---

When loading such file to a Satori Component all event hooks not registered in that component (differ.on_start is not registered in Satori-Imager), will be ignored.

There also can be shared code in the extension file:

---

bla.py

from hooker import hook
from satoricore.image import SatoriImage
import os

def get_bla(image):
  if type(image) == SatoriImage:
    # Get 'bla' using some SatoriImage method
    return bla_value
  else:
    # Get 'bla' using some os function
    return bla_value
  
@hook('imager.on_start')
def calc_bla(parser, args, satori_image):
  bla = get_bla(os)
  # Stuff...

@hook('differ.on_start')
def diff_bla(parser, args, source,
  destination, results, diff_name):
  sbla = get_bla(source)
  dbla = get_bla(destination)
  # Stuff...

---