User Guide¶
Command Line¶
Note
See the quickstart for common examples.
Usage¶
Run margaritashotgun -h
at the command line, detailed information on flags is below.
Quick Reference¶
Flag | Use | Notes |
--config |
path to config file | See the Configuration File section |
--server |
ip of remote server | DNS records may also be used |
--version |
print version info | |
--bucket |
output S3 bucket | Incommpatible with -o |
--output-dir |
local output folder | Incompatible with -b |
--port |
ssh port | 22 is used unless specified |
--username |
ssh username | Username for ssh authentication |
--module |
lime kernel module | Required if no repository is enabled |
--password |
ssh password | Unlockes RSA key when used with -k |
--key |
RSA Key | Unlocked via -p if supplied |
--jump-server |
ip of jump host | DNS records may also be used |
--jump-port |
jump host ssh port | 22 is used unless specified |
--jump-username |
jump host ssh username | Username for jump host ssh authentication |
--jump-password |
jump host ssh password | |
--jump-key |
jump host RSA key | |
--filename |
output file | |
--repository |
enable kernel repo | Default state is disabled |
--repository-url |
custom repo url | Defaults to threat response modules |
--repository-manifest |
custom repo url | Defaults to “primary” |
--gpg-no-verify |
disable signature checks | |
--workers |
worker count | Constrains parallel captures |
--verbose |
log debug messages | |
--log-dir |
log directory | |
--log-prefix |
log file prefix |
Config¶
The -c
and --config
flags accept a relative or absolute path to a yml config file.
The structure of this file is outlided in the Configuration
section below.
Server¶
The --server
flag specifies the server being targeted for memory capture.
A DNS record or IP address are valid inputs.
Version¶
The --version
flag prints the module version.
Bucket¶
The --bucket
flag specifies the destination bucket when dumping memory to s3.
This flag cannot be used in conjunction wth -o
or --output-dir
.
Output-Dir¶
The --output-dir
flags specify the destination folder when dumping memory to the local filesystem.
This flag cannot be used in conjunction with --bucket
.
Port¶
The --port
flag specifies the port that ssh is running on the remote server specified by --server
.
This flag is optional and port 22
will be assumed if no value is provided.
Username¶
The --username
flag specifies the user account to authenticate with when connecting to the remote server specified by --server
.
Module¶
The --module
flag accepts a relative or absolute path to a LiME kernel module.
This flag is required if no kernel module repository is enabled with the --repository
flag.
Password¶
The --password
flag specifies the password used for authentication with connection to the remote server specified by --server
.
When used in conjuction with the --key
flag this password will be used to unlock a password protected private key file.
Key¶
The --key
flag accepts a relative or absolute path to a a private key file used for authentication when connecting to the server specified by -server
.
If the private key file specified is password protected use the -p
or --password
flags to specify the password that unlocks the private key.
Filename¶
The --filename
flags specify the name of the file memory will be saved to when dumping to the local filesystem.
The file will be saved to the local directory unless the --output-dir
option is configured.
Repository¶
The --repository
flag enables automatic kernel module resolution via the repository configured with --repository-url
.
Margarita Shotgun will not query any repositories unless explicitly enabled with the --repository
flag.
Repository-Url¶
The --repository-url
flag specifies where to search for kernel modules. The default public repository provided by Threat Response is availible at https://threatresponse-lime-modules.s3.amazonaws.com
Repository-manifest¶
The --repository-manifest
flag specifies alternate kernel module manifests in the remote repository configured by --repository-url
. For more information on repository structure and manifests see the architecture page or lime-compiler repository.
Gpg-no-verify¶
The --gpg-no-verify
flag disables gpg verification of kernel modules downloaded from a remote repository.
Workers¶
The --workers
flag specifies how many worker processes will be spawned to process memory captures in parallel.
The default value for this flag is auto
which will spawn a process per remote host up to the number of cpu cores on the local system.
Integer values can be provided instead of the auto
keyword.
Eg. --workers 3
will process 3 memory captures simultaneously.
Verbose¶
The --verbose
flag enables debug logging, including each command executed on remote hosts as a part of the memory capture process.
Log-Dir¶
The --log-dir
flag specifies the directory in which log files will be saved during memory capture.
Log-Prefix¶
The --log-prefix
flag specifies a custom case number that is prepended onto log files.
Configuration File¶
Example configuration files are availible in the repository. More documentation about the configuration file format is in the works.
Managing AWS Credentials¶
Margarita Shotgun does not support explicitly declaring aws credentials. Currently the only way to interact with S3 is by configuring an aws profile.
A feature is planned to allow selecting a profile other than the default
profile. Until that feature is completed the default
profile must be used.
Recommended IAM Policy¶
Margarita Shotgun only requires PutObject on a specified bucket.
Example¶
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::member-berries/*"
}
]
}
Wrapping Margarita Shotgun¶
Margarita Shotgun can be driven by another program when included as a python module. The configuration object passed to the margaritashotgun client must have the exact structure of the configuration file outlined above.
Example¶
>>> import margaritashotgun
>>> config = dict(aws dict(bucket = 'case-bucket'),
... hosts = [ dict(addr = '10.10.12.10',
... port = 22,
... username = 'ec2-user',
... key = '/path/to/private-key') ]
... workers = 'auto',
... logging = dict(log_dir = 'logs/',
... prefix = 'casenumber-10.10.12.10'),
... repository = dict(enabled = true,
... url = 'your-custom-kernel-module-repo.io'))
...
>>> capture_client = margaritashotgun.client(name='mem-capture', config=config,
... library=True, verbose=False)
...
>>> response = capture_client.run()
>>> print(response)
{'total':1,'failed':[],'completed':['10.10.12.10']}
Note that calling capture_client.run()
is a blocking operation.