Reference Guide¶
Authentication¶
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:
-
__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)¶
-
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'¶
-
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:
-
__module__
= 'margaritashotgun.memory'¶
-
capture
(tunnel_addr, tunnel_port, filename=None, bucket=None, destination=None)¶ Captures memory based on the provided OutputDestination
Parameters: - tunnel_port (int) – ssh tunnel hostname or ip
- tunnel_port – ssh tunnel port
- filename (str) – memory dump output filename
- bucket (str) – output s3 bucket
- destination (
margaritashotgun.memory.OutputDestinations
) – OutputDestinations member
-
cleanup
()¶ Release resources used during memory capture
-
max_size
(mem_size, padding_percentage)¶ Calculates the excpected size in bytes of the memory capture
Parameters:
-
to_file
(filename, tunnel_addr, tunnel_port)¶ Writes memory dump to a local file
Parameters:
-
to_s3
(bucket, filename, tunnel_addr, tunnel_port)¶ Writes memory dump to s3 bucket
Parameters:
-
update_progress
(complete=False)¶ Logs capture progress
Params complete: toggle to finish ncurses progress bar
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
-
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)¶ -
-
__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: - auth (
margaritashotgun.auth.AuthMethods
) – Authentication object - address (str) – remote server address
- port (int) – remote server port
- auth (
-
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:
-
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:
-
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
()¶
-
Repository¶
-
class
margaritashotgun.repository.
Repository
(url, gpg_verify)¶ Lime-compiler repository client https://github.com/ThreatResponse/lime-compiler
-
__init__
(url, gpg_verify)¶ Parameters:
-
__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:
-
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:
-
verify_data_signature
(signature_url, data_url, data)¶ Verify data against it’s remote signature
Parameters:
-
verify_file_signature
(signature_url, file_url, filename)¶ Verify a local file against it’s remote signature
Parameters:
-
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:
-
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¶
-