From ea20ae1c0cf6be7e761e6b1824391145e49c6ed6 Mon Sep 17 00:00:00 2001 From: Mike Auty Date: Sun, 28 Jun 2020 00:57:46 +0100 Subject: [PATCH] Docs: Add CLI manpage (and fix a CLI option) --- doc/source/conf.py | 2 +- doc/source/vol-cli.rst | 118 +++++++++++++++++++++++++++++++++++++ volatility/cli/__init__.py | 2 +- 3 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 doc/source/vol-cli.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 86854ed70..0bcb06e9c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -284,7 +284,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [('index', 'volatility', 'Volatility 3 Documentation', ['Volatility Foundation'], 1)] +man_pages = [('vol-cli', 'volatility', 'Volatility 3 Documentation', ['Volatility Foundation'], 1)] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/doc/source/vol-cli.rst b/doc/source/vol-cli.rst new file mode 100644 index 000000000..efe15545b --- /dev/null +++ b/doc/source/vol-cli.rst @@ -0,0 +1,118 @@ +:orphan: + +volatility manual page +====================== + +Synopsis +-------- + +**volatility** [-h] [-c CONFIG] [--parallelism [{processes,threads,off}]] + [-e EXTEND] [-p PLUGIN_DIRS] [-s SYMBOL_DIRS] [-v] [-l LOG] + [-o OUTPUT_DIR] [-q] [-r RENDERER] [-f FILE] + [--write-config] [--single-location SINGLE_LOCATION] + [--single-swap-locations SINGLE_SWAP_LOCATIONS] + plugin ... + +Description +----------- + +Volatility is a program used to analyze memory images from a computer and +extract useful information from windows, linux and mac operating systems. +The framework is intended to introduce people to the techniques and +complexities associated with extracting digital artifacts from volatile +memory samples and provide a platform for further work into this exciting +area of research. + +The command line tool allows developers to distribute and easily use the +plugins of the framework against memory images of their choice. + +Options +------- + +-h, --help + Shows a help message that lists these options, and the available plugins. + If used after a plugin has been chosen, help will show any options which + that particular plugin can accept. + +-c CONFIG, --config CONFIG + Loads a JSON configuration from the CONFIG file + +--parallelism [{processes,threads,off}] + Enables parallelism (defaults to processes if no argument given). The + parallelism can be either off, or multithreaded (but due to python's GIL + still only takes up a single CPU) or multiprocessed (which spawns other + processes, but can use the whole of the CPU). Currently parallelism is + *experimental* and provides minimal benefits whilst still being developed + +-e EXTEND, --extend EXTEND + Extends an existing configuration with a single directive as specified by + EXTEND. Extensions must be of the form **configuration.item.name=value** + +-p PLUGIN_DIRS --plugin-dirs PLUGIN_DIRS + Specified a semi-colon separated list of paths that contain directories + where plugins may be found. These paths are searched before the default + paths when loading python files for plugins. This can therefore be used + to override built-in plugins. NOTE: All python code within this directory + and any subdirectories will be evaluated during normal operation. + +-s SYMBOL_DIRS, --symbol-dirs SYMBOL_DIRS + SYMBOL_DIRS is a semi-colon separated list of paths that contain symbol + files or symbol zip packs. Symbols must be within a particular directory + structure if they depending on the operating system of the symbols, + whilst symbol packs must be in the root of the directory and named after + the after the operating system to which they apply. + +-v, --verbose + A flag which can be used multiple times, each time increasing the level of + detail in the logs produced. + +-l LOG, --log LOG + Writes all logs (even those not displayed on screen) to the file specified + by LOG. + +-o OUTPUT_DIR, --output-dir OUTPUT_DIR + Should volatility generate any files during its run (such as a `dump` + plugin), the files will be created in the OUTPUT_DIR directory. This + defaults to the current working directory. + +-q, --quiet + When present, this flag mutes the progress feedback for operations. This + can be beneficial when piping the output directly to a file or another + tool. This also removes the + +-r RENDERER, --renderer RENDERER + Specifies the output format in which to display results. The default is + the quick renderer, which produces output immediately at the cost of + spacing for columns. Pretty outputs the results at the end, but aligns + them all to column width. json and jsonl output JSON (or JSON lines) + format, which can be used directly in conjunction with -q. + +-f FILE, --file FILE + This takes the FILE value, and formats it as a file:// URL for use with + the --single-location field, which is the image that the automagic will + attempt to build upon, and can be considered the input for the program. + +--write-config + This flag specifies that volatility should write or overwrite a file + called config.json in the current directory. The file will contain + the necessary JSON configuration to recreate the environment that the + plugin was previously run in. This configuration *may* be accepted by + other plugins, but there's no guarantee that plugins use the same + configuration options. + +--single-location LOCATION + This specifies a URL which will be downloaded if necessary, and built + upon by the automagic and, since most plugins require a single memory + image, can be considered the input for the program. + +--single-swap-locations + A comma-separated list of swap files to be considered as part of the + memory image specified by the single-location or file parameters. + +**plugin** + The name of the plugin to execute (these are usually categorized by + the operating system, such as `windows.pslist.PsList`). Any subtring + that uniquely matches the desired plugin name can be used. As such + `hivescan` would match `windows.registry.hivescan.HiveScan`, but + `pslist` is ambiguous because it could match `windows.pslist` or + `linux.pslist`. diff --git a/volatility/cli/__init__.py b/volatility/cli/__init__.py index 84b31e8f8..513741e6c 100644 --- a/volatility/cli/__init__.py +++ b/volatility/cli/__init__.py @@ -120,7 +120,7 @@ class CommandLine(interfaces.plugins.FileConsumerInterface): parser.add_argument("-o", "--output-dir", help = "Directory in which to output any generated files", - default = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')), + default = os.getcwd(), type = str) parser.add_argument("-q", "--quiet", help = "Remove progress feedback", default = False, action = 'store_true') parser.add_argument("-r",