Reference Guide

Authentication

class margaritashotgun.auth.Auth(username=None, password=None, key=None)
__init__(username=None, password=None, key=None)
Parameters:
  • username (str) – username for ssh authentication
  • password (str) – password for ssh authentication
  • key (str) – path to rsa key for ssh authentication
__module__ = 'margaritashotgun.auth'
load_key(key_path, password)

Creates paramiko rsa key

Parameters:
  • key_path (str) – path to rsa key
  • password (str) – password to try if rsa key is encrypted
class margaritashotgun.auth.AuthMethods
__module__ = 'margaritashotgun.auth'
key = 'key'
password = 'password'

Client

class margaritashotgun.client.Client(config=None, library=True, name=None, verbose=False)

Client for parallel memory capture with LiME

__init__(config=None, library=True, name=None, verbose=False)
Parameters:
  • library (bool) – Toggle for command line features
  • config (dict) – Client configuration
__module__ = 'margaritashotgun.client'
map_config()
run()

Captures remote hosts memory

statistics(results)

Cli

class margaritashotgun.cli.Cli
__module__ = 'margaritashotgun.cli'
check_directory_path(path)

Ensure directory exists at the provided path

Parameters:path (string) – path to directory to check
check_directory_paths(*args)

Ensure all arguments correspond to directories

check_file_path(path)

Ensure file exists at the provided path

Parameters:path (string) – path to directory to check
check_file_paths(*args)

Ensure all arguments provided correspond to a file

configure(arguments=None, config=None)

Merge command line arguments, config files, and default configs

Params arguments:
 Arguments produced by Cli.parse_args
Params config:configuration dict to merge and validate
configure_args(arguments)

Create configuration has from command line arguments

Params arguments:
 arguments produced by Cli.parse_args()
get_env_default(variable, default)

Fetch environment variables, returning a default if not found

load_config(path)

Load configuration from yaml file

Parameters:path (string) – path to configuration file
merge_config(base, config)
parse_args(args)

Parse arguments and return an arguments object

>>> from margaritashotgun.cli import Cli
>>> cli = CLi()
>>> cli.parse_args(sys.argv[1:])
Parameters:args (list) – list of arguments
validate_config(config)

Validate configuration dict keys are supported

Parameters:config (dict) – configuration dictionary

Exceptions

exception margaritashotgun.exceptions.AuthenticationMethodMissingError

Raised when no ssh authentication methods are specified

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.AuthenticationMissingUsernameError

Raised when authentication method is configured without a username

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.ConfigurationMergeError(reason)

Raised when merging user configuration with the base config fails

__init__(reason)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.InvalidConfigurationError(key, value, reason='unsupported configuration')

Raised when an unsupported configuration option is supplied

__init__(key, value, reason='unsupported configuration')

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.KernelModuleNotFoundError(kernel_version, repo_url)

Raised when no kernel module is provided and a suitable module cannot be found

__init__(kernel_version, repo_url)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.KernelModuleNotProvidedError(kernel_version)

Raised when no kernel module is provided and repository is disabled

__init__(kernel_version)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.LimeRetriesExceededError(retries)

Raised when max number of retries are exceeded waiting for LiME to load.

__init__(retries)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.MargaritaShotgunError

Base Error Class

__module__ = 'margaritashotgun.exceptions'
__weakref__

list of weak references to the object (if defined)

exception margaritashotgun.exceptions.MemoryCaptureAttributeMissingError(attribute)

Raised when memory capture is missing a required attribute

__init__(attribute)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.MemoryCaptureOutputMissingError(remote_host)

Raised when no output is configured when capturing memory

__init__(remote_host)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.NoConfigurationError

Raised when no configuration is supplied while operating as a library

__init__()

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryError(metadata_url, reason)

Raised when malformed repository metadata is found

__init__(metadata_url, reason)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryMissingKeyMetadataError(url)

Raised when signing public key is missing from repository

__init__(url)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryMissingSignatureError(signature_url)

Raised when a detached signature is missing in remote repository”

__init__(signature_url)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryMissingSigningKeyError(url)

Raised when signing public key is missing from repository

__init__(url)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositorySignatureError(url, signature_url)

Raised when signature verification fails

__init__(url, signature_url)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryUntrustedSigningKeyError(url, fingerprint)

Raised when repository signing key is not trusted

__init__(url, fingerprint)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.SSHCommandError(host, command, message)

Raised when an exception is encountered executing a command on a remote host

__init__(host, command, message)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.SSHConnectionError(host, inner_exception)

Raised when paramiko is unable to connect to a remote host

__init__(host, inner_exception)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.exceptions'

Logging

class margaritashotgun.logger.Logger(*args, **kwargs)
__init__(*args, **kwargs)

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'margaritashotgun.logger'
margaritashotgun.logger.cleanup(log_file)
margaritashotgun.logger.get_times()
margaritashotgun.logger.listener(queue, name, log_file, desc)

Memory

class margaritashotgun.memory.Memory(remote_addr, mem_size, progressbar=False, recv_size=1048576, sock_timeout=1)
__init__(remote_addr, mem_size, progressbar=False, recv_size=1048576, sock_timeout=1)
Parameters:
  • remote_addr (str) – hostname or ip address of target server
  • mem_size (int) – target server memory size in bytes
  • progressbar (bool) – ncurses progress bar toggle
  • recv_size (int) – transfer socket max receive size
  • sock_timeout (int) – transfer socket receive timeout
__module__ = 'margaritashotgun.memory'
capture(tunnel_addr, tunnel_port, filename=None, bucket=None, destination=None)

Captures memory based on the provided OutputDestination

Parameters:
cleanup()

Release resources used during memory capture

max_size(mem_size, padding_percentage)

Calculates the excpected size in bytes of the memory capture

Parameters:
  • mem_size (int) – target server memory in bytes
  • padding_percentage (float) – Output overhead of lime format
to_file(filename, tunnel_addr, tunnel_port)

Writes memory dump to a local file

Parameters:
  • filename (str) – memory dump output filename
  • tunnel_port (int) – ssh tunnel hostname or ip
  • tunnel_port – ssh tunnel port
to_s3(bucket, filename, tunnel_addr, tunnel_port)

Writes memory dump to s3 bucket

Parameters:
  • bucket (str) – memory dump output s3 bucket
  • filename (str) – memory dump output filename
  • tunnel_port (int) – ssh tunnel hostname or ip
  • tunnel_port – ssh tunnel port
update_progress(complete=False)

Logs capture progress

Params complete:
 toggle to finish ncurses progress bar
class margaritashotgun.memory.OutputDestinations
__module__ = 'margaritashotgun.memory'
local = 'local'
s3 = 's3'

Remote Host

class margaritashotgun.remote_host.Host
__init__()
__module__ = 'margaritashotgun.remote_host'
capture_memory(destination, filename, bucket, progressbar)
check_for_lime(pattern)

Check to see if LiME has loaded on the remote system

Parameters:
  • pattern (str) – pattern to check output against
  • listen_port (int) – port LiME is listening for connections on
cleanup()

Release resources used by supporting classes

connect(username, password, key, address, port, jump_host)

Connect ssh tunnel and shell executor to remote host

Parameters:
  • username (str) – username for authentication
  • password (str) – password for authentication, may be used to unlock rsa key
  • key (str) – path to rsa key for authentication
  • address (str) – address for remote host
  • port (int) – ssh port for remote host
kernel_version()

Returns the kernel kernel version of the remote host

load_lime(remote_path, listen_port, dump_format='lime')

Load LiME kernel module from remote filesystem

Parameters:
  • remote_path (str) – path to LiME kernel module on remote host
  • listen_port (int) – port LiME uses to listen to remote connections
  • dump_format (str) – LiME memory dump file format
log_async_result(future)
mem_size()

Returns the memory size in bytes of the remote host

start_tunnel(local_port, remote_address, remote_port)

Start ssh forward tunnel

Parameters:
  • local_port (int) – local port binding for ssh tunnel
  • remote_address (str) – remote tunnel endpoint bind address
  • remote_port (int) – remote tunnel endpoint bind port
unload_lime()

Remove LiME kernel module from remote host

upload_module(local_path=None, remote_path='/tmp/lime.ko')

Upload LiME kernel module to remote host

Parameters:
  • local_path (str) – local path to lime kernel module
  • remote_path (str) – remote path to upload lime kernel module
wait_for_lime(listen_port, listen_address='0.0.0.0', max_tries=20, wait=1)

Wait for lime to load unless max_retries is exceeded

Parameters:
  • listen_port (int) – port LiME is listening for connections on
  • listen_address (str) – address LiME is listening for connections on
  • max_tries (int) – maximum number of checks that LiME has loaded
  • wait (int) – time to wait between checks
margaritashotgun.remote_host.process(conf)

Remote Shell

class margaritashotgun.remote_shell.Commands
__module__ = 'margaritashotgun.remote_shell'
kernel_version = 'uname -r'
lime_check = 'cat /proc/net/tcp'
lime_pattern = '{0}:{1}'
load_lime = 'sudo insmod {0} "path=tcp:{1}" format={2}'
mem_size = "cat /proc/meminfo | grep MemTotal | awk '{ print $2 }'"
unload_lime = 'sudo pkill insmod; sudo rmmod lime'
class margaritashotgun.remote_shell.RemoteShell(max_async_threads=2)
__init__(max_async_threads=2)
Parameters:args (int) – maximun number of async command executors
__module__ = 'margaritashotgun.remote_shell'
cleanup()

Release resources used during shell execution

connect(auth, address, port, jump_host, jump_auth)

Creates an ssh session to a remote host

Parameters:
connect_with_auth(ssh, auth, address, port, sock)
connect_with_key(ssh, username, key, address, port, sock, timeout=20)

Create an ssh session to a remote host with a username and rsa key

Parameters:
  • username (str) – username used for ssh authentication
  • key (paramiko.key.RSAKey) – paramiko rsa key used for ssh authentication
  • address (str) – remote server address
  • port (int) – remote server port
connect_with_password(ssh, username, password, address, port, sock, timeout=20)

Create an ssh session to a remote host with a username and password

Parameters:
  • username (str) – username used for ssh authentication
  • password (str) – password used for ssh authentication
  • address (str) – remote server address
  • port (int) – remote server port
decode(stream, encoding='utf-8')

Convert paramiko stream into a string

Parameters:
  • stream – stream to convert
  • encoding (str) – stream encoding
execute(command)

Executes command on remote hosts

Parameters:command (str) – command to be run on remote host
execute_async(command, callback=None)

Executes command on remote hosts without blocking

Parameters:
  • command (str) – command to be run on remote host
  • callback (function) – function to call when execution completes
transport()
upload_file(local_path, remote_path)

Upload a file from the local filesystem to the remote host

Parameters:
  • local_path (str) – path of local file to upload
  • remote_path (str) – destination path of upload on remote host

Repository

class margaritashotgun.repository.Repository(url, gpg_verify)

Lime-compiler repository client https://github.com/ThreatResponse/lime-compiler

__init__(url, gpg_verify)
Parameters:
  • url (str) – repository url
  • gpg_verify (bool) – enable/disable gpg signature verification
__module__ = 'margaritashotgun.repository'
check_signing_key()

Check that repo signing key is trusted by gpg keychain

fetch(kernel_version, manifest_type)

Search repository for kernel module matching kernel_version

Parameters:
  • kernel_version (str) – kernel version to search repository on
  • manifest_type (str) – kernel module manifest to search on
fetch_module(module)

Download and verify kernel module

Parameters:module (str) – kernel module path
get_manifest(metadata)

Get latest manifest as specified in repomd.xml

Parameters:metadata (dict) – dictionary representation of repomd.xml
get_metadata()

Fetch repository repomd.xml file

get_signing_key()

Download a local copy of repo signing key for installation

init_gpg()

Initialize gpg object and check if repository signing key is trusted

install_key(key_data)

Install untrusted repo signing key

parse_manifest(manifest_xml)

Parse manifest xml file

Parameters:manifest_xml (str) – raw xml content of manifest file
parse_metadata(metadata_xml)

Parse repomd.xml file

Parameters:metadata_xml (str) – raw xml representation of repomd.xml
prompt_for_install()

Prompt user to install untrusted repo signing key

unzip_manifest(raw_manifest)

Decompress gzip encoded manifest

Parameters:raw_manifest (str) – compressed gzip manifest file content
verify_checksum(data, checksum, filename)

Verify sha256 checksum vs calculated checksum

Parameters:
  • data (str) – data used to calculate checksum
  • checksum (str) – expected checksum of data
  • checksum – original filename
verify_data_signature(signature_url, data_url, data)

Verify data against it’s remote signature

Parameters:
  • signature_url (str) – remote path to signature for data_url
  • data_url (str) – url from which data was fetched
  • data (str) – content of remote file at file_url
verify_file_signature(signature_url, file_url, filename)

Verify a local file against it’s remote signature

Parameters:
  • signature_url (str) – remote path to signature for file_url
  • file_url (str) – url from which file at filename was fetched
  • filename (str) – filename of local file downloaded from file_url
verify_module(filename, module, verify_signature)

Verify kernel module checksum and signature

Parameters:
  • filename (str) – downloaded kernel module path
  • module (dict) – kernel module metadata
  • verify_signature (bool) – enable/disable signature verification

SSH Tunnel

class margaritashotgun.ssh_tunnel.Forward(local_port, remote_address, remote_port, transport)
__init__(local_port, remote_address, remote_port, transport)

type: local_port: int param: local_port: local tunnel endpoint ip binding type: remote_address: str param: remote_address: Remote tunnel endpoing ip binding type: remote_port: int param: remote_port: Remote tunnel endpoint port binding type: transport: paramiko.Transport param: transport: Paramiko ssh transport

__module__ = 'margaritashotgun.ssh_tunnel'
forward_tunnel(local_port, remote_address, remote_port, transport)
run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

stop()
class margaritashotgun.ssh_tunnel.ForwardServer(server_address, RequestHandlerClass, bind_and_activate=True)
__module__ = 'margaritashotgun.ssh_tunnel'
allow_reuse_address = True
daemon_threads = True
class margaritashotgun.ssh_tunnel.Handler(request, client_address, server)
__module__ = 'margaritashotgun.ssh_tunnel'
handle()
class margaritashotgun.ssh_tunnel.SSHTunnel
__init__()
__module__ = 'margaritashotgun.ssh_tunnel'
cleanup()

Cleanup resources used during execution

configure(transport, auth, address, port)

Connect paramiko transport

Parameters:
  • auth (:py:class`margaritashotgun.auth.AuthMethods`) – authentication object
  • address (str) – remote server ip or hostname
  • port (int) – remote server port
  • hostkey (paramiko.key.HostKey) – remote host ssh server key
start(local_port, remote_address, remote_port)

Start ssh tunnel

type: local_port: int param: local_port: local tunnel endpoint ip binding type: remote_address: str param: remote_address: Remote tunnel endpoing ip binding type: remote_port: int param: remote_port: Remote tunnel endpoint port binding

Workers

class margaritashotgun.workers.Workers(conf, workers, name, library=True)
__init__(conf, workers, name, library=True)
__module__ = 'margaritashotgun.workers'
cleanup(terminate=False)
count(workers, cpu_count, host_count)
cpu_count = None
hosts = None
progress_bar = True
spawn(desc, timeout=1800)
worker_count = None