diff --git a/doc/source/index.rst b/doc/source/index.rst index 937e796fe..93d86225c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,6 +9,7 @@ Volatility 3 is Open Source. basics simple-plugin + vol2to3 Python Packages diff --git a/doc/source/vol2to3.rst b/doc/source/vol2to3.rst new file mode 100644 index 000000000..d86da6af3 --- /dev/null +++ b/doc/source/vol2to3.rst @@ -0,0 +1,79 @@ +Changes between Volatility 2 and Volatility 3 +============================================= + +Library and Context +------------------- + +Volatility 3 has been designed from the ground up to be a library, this means the components are independent and all +state required to run a particular plugin at a particular time is self-contained in an object derived from +a :py:class:`~volatility.framework.interfaces.contexts.ContextInterface`. + +The context contains the two core components that make up volatility, layers of data and the available symbols. + +Symbols and Types +----------------- + +Volatility 3 no longer uses profiles, it comes with an extensive library of symbol tables +(:py:class:`~volatility.framework.interfaces.symbols.SymbolTableInterface`), and can generate new symbol +tables for most windows memory images, based on the memory image itself. This allows symbol tables to include specific +offsets for locations (symbol locations) based on that operating system in particular. This means it is easier and quicker +to identify structures within an operating system, by having known offsets for those structures provided by the official +debugging information. + +Object Model changes +-------------------- + +The object model has changed as well, objects now inherit directly from their python counterparts, meaning an integer +object is actually a python integer (and has all the associated methods, and can be used whereever a normal int could). +In volatility 2, a complex proxy object was constructed which tried to emulate all the methods of the host object, but +ultimately it was a different type and could not be used in the same places (critically, it could make the ordering of +operations important, since a + b might not work, but b + a might work fine). + +Volatility 3 has also had significant speed improvements, where volatility 2 was designed to allow access to live memory +images wehre the underlying data could change during the run of the plugin, in volatility 3 the data is now read once +at the time of object construction, and will remain static, even if the underlying layer changes. This was because live +memory analysis was barely ever used, and this feature could cause a particular value to be re-read many times over for +no benefit (particularly since each re-read could result in many image reads due to page table translations being followed). + +Finally, in order to provide volatility specific information without impact on the ability for structures to have members +with arbitrary names, all the metadata about the object (such as its layer or offset) have been moved to a read-only `vol` +dictionary. + +Further the distinction between a :py:class:`~volatility.framework.interfaces.objects.Template` (the thing that +constructs an object) and the Object (:py:class:`~volatility.framework.interfaces.objects.ObjectInterface`) itself has +been made more explicit. In volatility 2, some information (such as size) could only be determined from a constructed object, +leading to instantiating a template on an empty buffer, just to determine the size. In volatility 3, templates contain +information such as their size, which can be queried directly without constructing the object. + +Layer and Layer dependencies +---------------------------- +Address spaces in volatility 2, are now more accurately referred to as Translation Layers +(:py:class:`~volatility.framework.interfaces.layers.TranslationLayerInterface`), since each one typically sits +atop another and can translate addresses between the higher logical layer and the lower physical layer. Address spaces in +volatility 2 were strictly limited to a stack, one on top of one other. In volatility 3, layers can have multiple +"dependencies" (lower layers), which allows for the integration of features such as swap space. + +Automagic +--------- +In volatility 2, we often tried to make this simpler for both users and developers. This resulted in something was +referred to as automagic, in that it was magic that happened automatically. We've now codified that more, so that the +automagic processes are clearly defined and can be enabled or disabled as necessary for any particular run. We also +included a stacker automagic to emulate the most common feature of volatility 2, automatically stacking address spaces +(now translation layers) on top of each other. + +Searching and Scanning +---------------------- +Scanning is very similar to scanning in volatility 2, a scanner object (such as a +:py:class:`~volatility.framework.layers.scanners.BytesScanner` or :py:class:`~volatility.framework.layers.scanners.RegExScanner`) is +primed with the data to be searched for, and the `scan` method is called on the layer to be searched. + +Output Rendering +---------------- +This is extremely similar to volatility 2, because we were developing it for volatility 3 when we added it to volatility 2. +We now require that all plugins produce output in a :py:class:`~volatility.framework.interfaces.renderers.TreeGrid` object, +which ensure that the library can be used regardless of which interface is driving it. An example web GUI is also available +called Volumetric which allows all the plugins that can be run from the command line to be run from a webpage, and offers +features such as automatic formatting and sorting of the data, which previously couldn't be provided easily from the CLI. + +There is also the ability to provide file output such that the user interface can provide a means to render or save those files. +