1.1. lf.dec — Digital Evidence Containers

Digital Evidence Containers (DECs) are files that contain one or more items of digital evidence. Common examples are DD, E01, and AFF files.

In the framework, DECs are represented by two types of classes, containers and streams. Containers represent the container file, while streams are the logical representation of the digital evidence.

To use a DEC, initialize the container, and then use the Container.list() and Container.open() to enumerate and open streams inside the container. For example:

>>> raw_file = Raw.open("/path/to/image.dd")
>>> raw_file.list()
[StreamInfo(id=0)]
>>> raw_stream = raw_file.open(0)

For container types that need to manage the stream position (i.e. aren’t just wrappers around an existing stream type) there exists the ManagedIStream class.

1.1.1. Containers

class lf.dec.Container

Base class for container files. Subclasses are required to implement the list() and open() methods.

stream

If a container type only supports a single evidence stream (e.g. raw/dd files) then this is the stream. Otherwise this is None.

list()

Lists streams inside a container

Return type:list Returns:A list of StreamInfo objects, describing the streams inside the container.

open()

Opens a stream for use.

Return type:IStream Returns:The appropriate stream.

class lf.dec.SingleStreamContainer

A convenience class for containers that only have a single stream. Subclasses are required to set the :attr:stream attribute.

class lf.dec.Raw(name)

A container for raw/dd files.

Parameter:name (str) – The name of the raw/dd file.

class lf.dec.Byte(bytes_)

A container file for a bytes or bytearray object.

Parameter:bytes (bytes or bytearray) – The bytes or bytearray object to wrap around.

class lf.dec.Subset(stream, start, size)

A container for a stream whose contents are a subset of another stream.

Parameters:

• stream (IStream) – The stream to wrap around.
• start (int) – The start of the subset.
• size (int) – The maximum size (in bytes) of the subset.

class lf.dec.Composite(segments)

A container for a stream composed of subsets of other streams.

Parameter:segments (list of tuples) –

A list of tuples, where the elements of each tuple are:

1. The stream to read from.
2. The offset in the stream for the start of the segment.
3. The number of bytes in the segment.

class lf.dec.SplitRaw(names)

A container for a raw/dd file that has been split into pieces.

Parameter:names (list of strings) – A list of the names of the raw/dd files.

1.1.2. StreamInfo Objects

StreamInfo objects are used to describe information (e.g. name of file) about a stream.

class lf.dec.StreamInfo(id=0)

Creates a new StreamInfo object with the value id.

id

A container-unique identifier for the stream.

1.1.3. Stream Objects

class lf.dec.IStream

Base class for input streams. All input streams are required to be seekable (random access). Subclasses are required to implement the seek(), tell(), and readinto() methods.

size

The size of the stream in bytes. If this value is not known, it is None.

seek(offset, whence=SEEK_SET)

Positions the stream at offset, relative to whence. Valid values for whence are the same as the Python io module. They are:

• SEEK_SET - The start of the stream.
• SEEK_CUR - Current stream position.
• SEEK_END - The end of the stream.

Parameters:

• offset (int) – The position of the cursor
• whence (int) – Tells seek() how to interpret offset.

Raises ValueError:  

If the stream is closed, whence is not one of the SEEK_* constants, or whence is SEEK_SET and offset is negative.

rtype:int returns:The new position in the stream.

tell()

Returns the absolute position of the stream.

Raises ValueError:  If the stream is closed. Return type:int Returns:The position in the stream.

readable()

True if the stream is readable.

readinto(b)

Reads up to len(b) bytes into b.

Parameter:b (bytearray) – A bytearray to hold the bytes read from the stream. Raises ValueError:  If the stream is closed. Return type:int Returns:The number of bytes read.

class lf.dec.ManagedIStream

An IStream that keeps track of stream position. This class is useful when implementing your own stream types. The seek(), and tell() methods are provided.

The seek() and tell() methods update the _position attribute.

Note

In order for this class to properly implement the seek() method, subclasses are required to set the size attribute.

_position

The absolute position of the stream.

class lf.dec.IStreamWrapper(stream, size=None)

An IStream that wraps around an existing Python io stream.

Parameters:

• stream (IStream) – The underlying stream to wrap around.
• size (int or None) – The size of the stream (in bytes) or None if not known.

_stream

The underlying stream to wrap around.

class lf.dec.RawIStream(name)

A stream for raw/dd files.

Parameter:name (str) – The name of the raw/dd image file.

name

The name of the raw/dd file.

Note

This class raises IOError (instead of ValueError) in the seek() method if the offset parameter is negative, and whence is SEEK_SET.

class lf.dec.ByteIStream(bytes_)

A stream for a bytes or bytearray object.

Parameter:bytes (bytes or bytearray) – The bytes or bytearray object to read from.

class lf.dec.SubsetIStream(stream, start, size)

A stream that is a subset of another stream.

Parameters:

• stream (IStream) – The stream to wrap around.
• start (int) – The start of the subset.
• size (int) – The size (in bytes) of the subset.

_stream

The stream that is wrapped around.

_start

The start of the subset, in the _stream attribute.

class lf.dec.CompositeIStream(segments)

A stream composed of subsets of other streams.

Parameter:segments (list of tuples) –

A list of tuples where the elements of each tuple are:

1. The stream to read from.
2. The offset in the stream of the start of the segment.
3. The number of bytes in the segment.

_segments

A list of (stream, start, size) tuples.

class lf.dec.SplitRawIStream(names)

A stream for a raw/dd file that has been split into pieces.

Parameter:names (list of strings) – A list of the names of the raw/dd files.

_names

A list of the names of the raw/dd files.