facedancer.descriptor module

Functionality for working with objects with associated USB descriptors.

class facedancer.descriptor.StringDescriptorManager

Bases: object

Manager class that collects active string descriptors.

__getitem__(index)

Gets the relevant string descriptor.

add_string(string, index=None)

Add a Python string as a new string descriptor, and return an index.

The specified index is used for the new string descriptor, overwriting any previous descriptor with the same index. If an index is not specified, a new, unique, incrementing index is allocated.

get_index(string)

Returns the index of the given string; creating it if the string isn’t already known.

class facedancer.descriptor.StringRef(index: int = None, string: str = None)

Bases: object

Class representing a reference to a USB string descriptor.

classmethod ensure(value)

Turn a value into a StringRef it is not one already.

classmethod field(**kwargs)

Used to create StringRef fields in dataclasses.

generate_code()

Generate input that will produce this StringRef when passed to ensure()

classmethod lookup(strings: Dict[int, str], index: int)

Try to construct a StringRef given an index and a mapping

class facedancer.descriptor.USBClassDescriptor(*, raw: bytes, type_number: int = None, number: int = None, parent: USBDescribable = None, include_in_config: bool = True)

Bases: USBDescriptor

Class for arbitrary USB Class descriptors.

include_in_config: bool = True

raw: bytes

The bDescriptorType of the descriptor.

class facedancer.descriptor.USBDescribable

Bases: object

Abstract base class for objects that can be created from USB descriptors.

DESCRIPTOR_TYPE_NUMBER = None

classmethod from_binary_descriptor(data, strings={})

Attempts to create a USBDescriptor subclass from the given raw descriptor data.

classmethod handles_binary_descriptor(data)

Returns true iff this class handles the given descriptor. By default, this is based on the class’s DESCRIPTOR_TYPE_NUMBER declaration.

class facedancer.descriptor.USBDescriptor(*, raw: bytes, type_number: int = None, number: int = None, parent: USBDescribable = None, include_in_config: bool = False)

Bases: USBDescribable, AutoInstantiable

Class for arbitrary USB descriptors; minimal concrete implementation of USBDescribable.

__call__(index=0)

Converts the descriptor object into raw bytes.

classmethod from_binary_descriptor(data, strings={})

Attempts to create a USBDescriptor subclass from the given raw descriptor data.

generate_code(name=None, indent=0)

get_identifier()

Returns a unique integer identifier for this object.

This is usually the index or address of the relevant USB object.

include_in_config: bool = False

number: int = None

Parent object which this descriptor is associated with.

parent: USBDescribable = None

Whether this descriptor should be included in a GET_CONFIGURATION response.

raw: bytes

The bDescriptorType of the descriptor.

type_number: int = None

Number to request this descriptor with a GET_DESCRIPTOR request.

class facedancer.descriptor.USBDescriptorTypeNumber(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

CONFIGURATION = 2

DEVICE = 1

DEVICE_QUALIFIER = 6

ENDPOINT = 5

HID = 33

INTERFACE = 4

INTERFACE_POWER = 8

OTHER_SPEED_CONFIGURATION = 7

REPORT = 34

STRING = 3

class facedancer.descriptor.USBStringDescriptor(*, raw: bytes, type_number: int = None, number: int = None, parent: USBDescribable = None, include_in_config: bool = False, python_string: str = None)

Bases: USBDescriptor

Class representing a USB string descriptor.

DESCRIPTOR_TYPE_NUMBER = 3

classmethod from_string(string, *, index=None)

python_string: str = None

facedancer.descriptor.include_in_config(cls)

Decorator that marks a descriptor to be included in configuration data.

facedancer.descriptor.requestable(type_number, number)

Decorator that marks a descriptor as requestable.