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
__format__(format_spec)
__module__ = 'margaritashotgun.auth'
static __new__(value)
__reduce_ex__(proto)
__repr__()
__str__()
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__()
__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.AuthenticationMissingUsernameError

Raised when authentication method is configured without a username

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

Raised when merging user configuration with the base config fails

__init__(reason)
__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')
__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)
__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.KernelModuleNotProvidedError(kernel_version)

Raised when no kernel module is provided and repository is disabled

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

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

__init__(retries)
__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)
__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.MemoryCaptureOutputMissingError(remote_host)

Raised when no output is configured when capturing memory

__init__(remote_host)
__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.NoConfigurationError

Raised when no configuration is supplied while operating as a library

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

Raised when malformed repository metadata is found

__init__(metadata_url, reason)
__module__ = 'margaritashotgun.exceptions'
exception margaritashotgun.exceptions.RepositoryMissingKeyMetadataError(url)

Raised when signing public key is missing from repository

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

Raised when a detached signature is missing in remote repository”

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

Raised when signing public key is missing from repository

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

Raised when signature verification fails

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

Raised when repository signing key is not trusted

__init__(url, fingerprint)
__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)
__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)
__module__ = 'margaritashotgun.exceptions'

Logging

class margaritashotgun.logger.Logger(*args, **kwargs)
__init__(*args, **kwargs)
__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
__format__(format_spec)
__module__ = 'margaritashotgun.memory'
static __new__(value)
__reduce_ex__(proto)
__repr__()
__str__()
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
__format__(format_spec)
__module__ = 'margaritashotgun.remote_shell'
static __new__(value)
__reduce_ex__(proto)
__repr__()
__str__()
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()
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