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)¶
-
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
-
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'¶
-
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:
-
__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
¶ -
__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)¶ -
-
__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
()¶
-
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¶
-