Determines whether USB device mathing specified criteria should be authorized, deauthorized or removed. More...

#include <Rule.hpp>

Classes
class	Attribute
	Specifies which devices to match or what condition have to be met for the rule to be aplicable. More...

Public Types
enum	Target { Target::Allow = 0, Target::Block = 1, Target::Reject = 2, Target::Match = 3, Target::Unknown = 4, Target::Device = 5, Target::Empty = 6, Target::Invalid = 7 }
	Enumeration of possible rule targets. More...

enum	SetOperator { SetOperator::AllOf, SetOperator::OneOf, SetOperator::NoneOf, SetOperator::Equals, SetOperator::EqualsOrdered, SetOperator::Match }
	Defines set operators that can be used in the rules. More...

Public Member Functions
	Rule ()
	Construct a default rule. More...

	~Rule ()
	Default destructor.

	Rule (const Rule &rhs)
	Constructs rule based on rhs. More...

const Rule &	operator= (const Rule &rhs)
	Assignes rhs rule to this. More...

void	setRuleID (uint32_t rule_id)
	Sets rule ID. More...

uint32_t	getRuleID () const
	Returns rule ID. More...

void	setTarget (Rule::Target target)
	Sets rule target. More...

Target	getTarget () const
	Returns rule target. More...

void	setDeviceID (const USBDeviceID &value)
	Sets USB Device ID attribute. More...

const USBDeviceID &	getDeviceID () const
	Returns USB device ID. More...

const Attribute< USBDeviceID > &	attributeDeviceID () const
	Returns imutable USB device ID attribute. More...

Attribute< USBDeviceID > &	attributeDeviceID ()
	Returns mutable USB device ID attribute. More...

void	setSerial (const std::string &value)
	Sets serial number attribute. More...

const std::string &	getSerial () const
	Returns serial number. More...

const Attribute< std::string > &	attributeSerial () const
	Returns imutable serial number attribute. More...

Attribute< std::string > &	attributeSerial ()
	Returns mutable serial number attribute. More...

void	setLabel (const std::string &value)
	Sets rule label attribute. More...

const std::string &	getLabel () const
	Returns rule label. More...

const Attribute< std::string > &	attributeLabel () const
	Returns imutable rule label attribute. More...

Attribute< std::string > &	attributeLabel ()
	Returns mutable rule label attribute. More...

void	setWithConnectType (const std::string &value)
	Sets with-connect-type attribute. More...

const std::string &	getWithConnectType () const
	Returns type of conncetion USB device uses. More...

const Attribute< std::string > &	attributeWithConnectType () const
	Returns imutable with-connect-type attribute. More...

Attribute< std::string > &	attributeWithConnectType ()
	Returns mutable with-connect-type attribute. More...

void	setName (const std::string &value)
	Sets device name attribute. More...

const std::string &	getName () const
	Returns device name. More...

const Attribute< std::string > &	attributeName () const
	Returns imutable device name attribute. More...

Attribute< std::string > &	attributeName ()
	Returns mutable device name attribute. More...

void	setHash (const std::string &value)
	Sets device hash attribute. More...

const std::string &	getHash () const
	Returns device hash. More...

const Attribute< std::string > &	attributeHash () const
	Returns imutable device hash attribute. More...

Attribute< std::string > &	attributeHash ()
	Returns mutable device hash attribute. More...

void	setParentHash (const std::string &value)
	Sets parent hash attribute. More...

const std::string &	getParentHash () const
	Returns parent hash. More...

const Rule::Attribute< std::string > &	attributeParentHash () const
	Returns imutable parent hash attribute. More...

Rule::Attribute< std::string > &	attributeParentHash ()
	Returns mutable parent hash attribute. More...

void	setViaPort (const std::string &value)
	Sets via-port attribute. More...

const std::string &	getViaPort () const
	Returns USB port through which the device is connected. More...

const Attribute< std::string > &	attributeViaPort () const
	Returns imutable via-port attribute. More...

Attribute< std::string > &	attributeViaPort ()
	Returns mutable via-port attribute. More...

const Attribute< USBInterfaceType > &	attributeWithInterface () const
	Returns imutable with-interface attribute. More...

Attribute< USBInterfaceType > &	attributeWithInterface ()
	Returns mutable with-interface attribute. More...

const Attribute< RuleCondition > &	attributeConditions () const
	Returns imutable rule conditions attribute. More...

Attribute< RuleCondition > &	attributeConditions ()
	Returns mutable rule conditions attribute. More...

bool	appliesTo (std::shared_ptr< const Rule > rhs) const
	Checks whether this rule applies to rhs rule. More...

bool	appliesTo (const Rule &rhs) const
	Checks whether this rule applies to rhs rule. More...

bool	appliesTo (const Rule &rhs)
	Checks whether this rule applies to rhs rule and updates last evaluated meta-data counter. More...

bool	isImplicit () const
	Checks whether the rule is implicit (rule has default rule ID). More...

	operator bool () const
	Returns true if rule target is neither unknown nor invalid nor empty. More...

std::string	toString (bool invalid=false, bool hide_serial=false) const
	Returns string representation of this rule. More...

void	updateMetaDataCounters (bool applied=true, bool evaluated=false)
	Updates meta-data last applied and last evaluated counters. More...

std::unique_ptr< RulePrivate > &	internal ()
	Returns reference to mutable RulePrivate object of this rule. More...

const std::unique_ptr< RulePrivate > &	internal () const
	Returns reference to imutable RulePrivate object of this rule. More...

Static Public Member Functions
static const std::string	targetToString (Target target)
	Converts given rule target to its string representation. More...

static Target	targetFromString (const std::string &target_string)
	Converts given string into rule target. More...

static uint32_t	targetToInteger (Target target)
	Converts rule target to its integer representation. More...

static Target	targetFromInteger (uint32_t target_integer)
	Converts integer into rule target. More...

static const std::string	setOperatorToString (const Rule::SetOperator &op)
	Converts given set operator to its string representation. More...

static SetOperator	setOperatorFromString (const std::string &set_operator_string)
	Converts string into set operator. More...

static Rule	fromString (const std::string &rule_string)
	Parses given rule_string and returns Rule object. More...

Static Public Attributes
static const uint32_t	RootID = std::numeric_limits<uint32_t>::min()
	Sequence number of the (fake) root rule.

static const uint32_t	DefaultID = std::numeric_limits<uint32_t>::max()
	Sequence number assigned to default constructed rules. Cannot be used for searching.

static const uint32_t	LastID = std::numeric_limits<uint32_t>::max() - 2
	Sequence number for specifying that the last rule in the ruleset should be used in context of the operation.

static const uint32_t	ImplicitID = std::numeric_limits<uint32_t>::max() - 1
	Sequence number of the implicit target rule.

Detailed Description

Determines whether USB device mathing specified criteria should be authorized, deauthorized or removed.

Member Enumeration Documentation

◆ SetOperator

enum usbguard::Rule::SetOperator

strong

Defines set operators that can be used in the rules.

Enumerator
AllOf	The device attribute set must contain all of the specified values for the rule to match.
OneOf	The device attribute set must contain at least one of the specified values for the rule to match.
NoneOf	The device attribute set must not contain any of the specified values for the rule to match.
Equals	The device attribute set must contain exactly the same set of values for the rule to match.
EqualsOrdered	The device attribute set must contain exactly the same set of values in the same order for the rule to match.
Match	Special operator: matches anything, cannot be used directly in a rule.

◆ Target

enum usbguard::Rule::Target

strong

Enumeration of possible rule targets.

The target of a rule specifies whether the device will be authorized for use or not.

Enumerator
Allow	Devices matching this rule will be authorized. In other words, the device and its interface will be allowed to communicate with the system.
Block	Devices matching this rule will not be authorized.
Reject	Devices matching this rule will not be authorized and will be detached.
Match	Special target which can be used to trigger actions. The rule wont affect the final decision.
Unknown	Unknown target. Used for default constructed rules.
Device	Special target which can only be used for a rule that represents a single device.
Empty	Special target to represent the case the parser reaches a comment only line.
Invalid	Represents invalid target.

Constructor & Destructor Documentation

◆ Rule() [1/2]

usbguard::Rule::Rule ( )

Construct a default rule.

This rule matches only a default rule and cannot be converted to a string representation.

◆ Rule() [2/2]

usbguard::Rule::Rule ( const Rule & rhs )

Constructs rule based on rhs.

Parameters

rhs	Rule to copy.

Member Function Documentation

◆ appliesTo() [1/3]

bool usbguard::Rule::appliesTo ( std::shared_ptr< const Rule > rhs ) const

Checks whether this rule applies to rhs rule.

Parameters

rhs	Rule to apply to.

Returns: True if this rule applies to rhs rule, false otherwise.

◆ appliesTo() [2/3]

bool usbguard::Rule::appliesTo ( const Rule & rhs ) const

Checks whether this rule applies to rhs rule.

Parameters

rhs	Rule to apply to.

Returns: True if this rule applies to rhs rule, false otherwise.

◆ appliesTo() [3/3]

bool usbguard::Rule::appliesTo ( const Rule & rhs )

Checks whether this rule applies to rhs rule and updates last evaluated meta-data counter.

Parameters

rhs	Rule to apply to.

Returns: True if this rule applies to rhs rule, false otherwise.

◆ attributeConditions() [1/2]

const Rule::Attribute< RuleCondition > & usbguard::Rule::attributeConditions ( ) const

Returns imutable rule conditions attribute.

Returns: Imutable rule conditions attribute.

◆ attributeConditions() [2/2]

Rule::Attribute< RuleCondition > & usbguard::Rule::attributeConditions ( )

Returns mutable rule conditions attribute.

Returns: Mutable rule conditions attribute.

◆ attributeDeviceID() [1/2]

const Rule::Attribute< USBDeviceID > & usbguard::Rule::attributeDeviceID ( ) const

Returns imutable USB device ID attribute.

Returns: Imutable USB device ID attribute.

◆ attributeDeviceID() [2/2]

Rule::Attribute< USBDeviceID > & usbguard::Rule::attributeDeviceID ( )

Returns mutable USB device ID attribute.

Returns: Mutable USB device ID attribute.

◆ attributeHash() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeHash ( ) const

Returns imutable device hash attribute.

Returns: Imutable device hash attribute.

◆ attributeHash() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeHash ( )

Returns mutable device hash attribute.

Returns: Mutable device hash attribute.

◆ attributeLabel() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeLabel ( ) const

Returns imutable rule label attribute.

Returns: Imutable rule label attribute.

◆ attributeLabel() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeLabel ( )

Returns mutable rule label attribute.

Returns: Mutable rule label attribute.

◆ attributeName() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeName ( ) const

Returns imutable device name attribute.

Returns: Imutable device name attribute.

◆ attributeName() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeName ( )

Returns mutable device name attribute.

Returns: Mutable device name attribute.

◆ attributeParentHash() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeParentHash ( ) const

Returns imutable parent hash attribute.

Returns: Imutable parent hash attribute.

◆ attributeParentHash() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeParentHash ( )

Returns mutable parent hash attribute.

Returns: Mutable parent hash attribute.

◆ attributeSerial() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeSerial ( ) const

Returns imutable serial number attribute.

Returns: Imutable serial number attribute.

◆ attributeSerial() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeSerial ( )

Returns mutable serial number attribute.

Returns: Mutable serial number attribute.

◆ attributeViaPort() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeViaPort ( ) const

Returns imutable via-port attribute.

Returns: Imutable via-port attribute.

◆ attributeViaPort() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeViaPort ( )

Returns mutable via-port attribute.

Returns: Mutable via-port attribute.

◆ attributeWithConnectType() [1/2]

const Rule::Attribute< std::string > & usbguard::Rule::attributeWithConnectType ( ) const

Returns imutable with-connect-type attribute.

Returns: Imutable with-connect-type attribute.

◆ attributeWithConnectType() [2/2]

Rule::Attribute< std::string > & usbguard::Rule::attributeWithConnectType ( )

Returns mutable with-connect-type attribute.

Returns: Mutable with-connect-type attribute.

◆ attributeWithInterface() [1/2]

const Rule::Attribute< USBInterfaceType > & usbguard::Rule::attributeWithInterface ( ) const

Returns imutable with-interface attribute.

Note: Set/get methods for a single value isn't useful for the with-interface attribute as it usually contains multiple values. Therefore, we provide only the attribute accessors in this case.

Returns: Imutable with-interface attribute.

◆ attributeWithInterface() [2/2]

Rule::Attribute< USBInterfaceType > & usbguard::Rule::attributeWithInterface ( )

Returns mutable with-interface attribute.

Note: Set/get methods for a single value isn't useful for the with-interface attribute as it usually contains multiple values. Therefore, we provide only the attribute accessors in this case.

Returns: Mutable with-interface attribute.

◆ fromString()

Rule usbguard::Rule::fromString ( const std::string & rule_string )

static

Parses given rule_string and returns Rule object.

Parameters

rule_string String to parse.

Returns: Rule object from given rule_string.

See also: parseRuleFromString()

◆ getDeviceID()

const USBDeviceID & usbguard::Rule::getDeviceID ( ) const

Returns USB device ID.

Returns: USB device ID.

See also: get()

◆ getHash()

const std::string & usbguard::Rule::getHash ( ) const

Returns device hash.

Returns: Device hash.

See also: get()

◆ getLabel()

const std::string & usbguard::Rule::getLabel ( ) const

Returns rule label.

Returns: Rule label.

See also: get()

◆ getName()

const std::string & usbguard::Rule::getName ( ) const

Returns device name.

Returns: Device name.

See also: get()

◆ getParentHash()

const std::string & usbguard::Rule::getParentHash ( ) const

Returns parent hash.

Returns: Parent hash.

See also: get()

◆ getRuleID()

uint32_t usbguard::Rule::getRuleID ( ) const

Returns rule ID.

Returns: Rule ID.

◆ getSerial()

const std::string & usbguard::Rule::getSerial ( ) const

Returns serial number.

Returns: Serial number.

See also: get()

◆ getTarget()

Rule::Target usbguard::Rule::getTarget ( ) const

Returns rule target.

Returns: Rule target.

◆ getViaPort()

const std::string & usbguard::Rule::getViaPort ( ) const

Returns USB port through which the device is connected.

Returns: USB port through which the device is connected.

See also: get()

◆ getWithConnectType()

const std::string & usbguard::Rule::getWithConnectType ( ) const

Returns type of conncetion USB device uses.

Returns: Type of connection USB device uses.

See also: get()

◆ internal() [1/2]

std::unique_ptr< RulePrivate > & usbguard::Rule::internal ( )

Returns reference to mutable RulePrivate object of this rule.

Returns: Mutable RulePrivate.

◆ internal() [2/2]

const std::unique_ptr< RulePrivate > & usbguard::Rule::internal ( ) const

Returns reference to imutable RulePrivate object of this rule.

Returns: Imutable RulePrivate.

◆ isImplicit()

bool usbguard::Rule::isImplicit ( ) const

Checks whether the rule is implicit (rule has default rule ID).

Returns: True if rule has default rule ID, false otherwise.

◆ operator bool()

usbguard::Rule::operator bool ( ) const

Returns true if rule target is neither unknown nor invalid nor empty.

Returns: True if rule target is neither unknown nor invalid nor empty, false otherwise.

◆ operator=()

const Rule & usbguard::Rule::operator= ( const Rule & rhs )

Assignes rhs rule to this.

Parameters

rhs	Rule to assign.

Returns: This object.

◆ setDeviceID()

void usbguard::Rule::setDeviceID ( const USBDeviceID & value )

Sets USB Device ID attribute.

Parameters

value USB device ID to set.

See also: set()

◆ setHash()

void usbguard::Rule::setHash ( const std::string & value )

Sets device hash attribute.

Parameters

value Device hash to set.

See also: set()

◆ setLabel()

void usbguard::Rule::setLabel ( const std::string & value )

Sets rule label attribute.

Label assosiates an arbitrary string with a rule. This string can, for instance, be used to store the origin of the rule or some contextual information about it. It is not used when testing if a rule applies to a device.

Parameters

value Label to set.

See also: set()

◆ setName()

void usbguard::Rule::setName ( const std::string & value )

Sets device name attribute.

Parameters

value Device name to set.

See also: set()

◆ setOperatorFromString()

Rule::SetOperator usbguard::Rule::setOperatorFromString ( const std::string & set_operator_string )

static

Converts string into set operator.

Parameters

set_operator_string String to convert.

Returns: Set operator.

Exceptions

runtime_error If given string does not contain valid set operator.

◆ setOperatorToString()

const std::string usbguard::Rule::setOperatorToString ( const Rule::SetOperator & op )

static

Converts given set operator to its string representation.

Parameters

op	Set operator to convert.

Returns: String representation of given set operator.

Exceptions

runtime_error If string representation for given set operator does not exist.

◆ setParentHash()

void usbguard::Rule::setParentHash ( const std::string & value )

Sets parent hash attribute.

Parameters

value Parent hash to set.

See also: set()

◆ setRuleID()

void usbguard::Rule::setRuleID ( uint32_t rule_id )

Sets rule ID.

Parameters

rule_id Rule ID to set.

◆ setSerial()

void usbguard::Rule::setSerial ( const std::string & value )

Sets serial number attribute.

Parameters

value Serial number to set.

See also: set()

◆ setTarget()

void usbguard::Rule::setTarget ( Rule::Target target )

Sets rule target.

In other words, sets whether USB device will be authorized for use or not.

Parameters

target Rule target to set.

◆ setViaPort()

void usbguard::Rule::setViaPort ( const std::string & value )

Sets via-port attribute.

Describes through which USB port the device is connected.

Parameters

value Port to set.

See also: set()

◆ setWithConnectType()

void usbguard::Rule::setWithConnectType ( const std::string & value )

Sets with-connect-type attribute.

Describes what type of connection USB device uses. Helps to distinguish between internal (hardwired) and external (hotplug) ports.

Parameters

value With-connect-type to set.

See also: set()

◆ targetFromInteger()

Rule::Target usbguard::Rule::targetFromInteger ( uint32_t target_integer )

static

Converts integer into rule target.

Parameters

target_integer Integer to convert.

Returns: Rule target.

Exceptions

runtime_error If given integer can not be converted into rule target.

◆ targetFromString()

Rule::Target usbguard::Rule::targetFromString ( const std::string & target_string )

static

Converts given string into rule target.

Parameters

target_string String to convert.

Returns: Rule target.

Exceptions

runtime_error If string does not contain valid rule target.

◆ targetToInteger()

uint32_t usbguard::Rule::targetToInteger ( const Rule::Target target )

static

Converts rule target to its integer representation.

Parameters

target Rule target to convert.

Returns: Integer representation of given rule target.

◆ targetToString()

const std::string usbguard::Rule::targetToString ( const Rule::Target target )

static

Converts given rule target to its string representation.

Parameters

target Rule target to convert.

Returns: String representation of given target.

Exceptions

runtime_error If no string representation for given rule target has been found.

◆ toString()

std::string usbguard::Rule::toString	(	bool	invalid = `false`,
		bool	hide_serial = `false`
	)		const

Returns string representation of this rule.

Parameters

invalid	If rule target is invalid and this option is set to true, then no exception will be thrown but string "<invalid>" will be put instead of rule target into the string.
hide_serial	If true, serial number and any PII (Personally identifiable information) will not be included in the string.

Returns: String representation of this rule.

◆ updateMetaDataCounters()

void usbguard::Rule::updateMetaDataCounters	(	bool	applied = `true`,
		bool	evaluated = `false`
	)

Updates meta-data last applied and last evaluated counters.

RulePrivate object contains three meta-data counters:

when was Rule object created.
when was rule last applied.
when was rule last evaluated.

Parameters

applied	If true, last applied counter is updated to current time.
evaluated	If true, last evaluated counter is updated to current time.

The documentation for this class was generated from the following files:

Rule.hpp
Rule.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ SetOperator

◆ Target

Constructor & Destructor Documentation

◆ Rule() [1/2]

◆ Rule() [2/2]

Member Function Documentation

◆ appliesTo() [1/3]

◆ appliesTo() [2/3]

◆ appliesTo() [3/3]

◆ attributeConditions() [1/2]

◆ attributeConditions() [2/2]

◆ attributeDeviceID() [1/2]

◆ attributeDeviceID() [2/2]

◆ attributeHash() [1/2]

◆ attributeHash() [2/2]

◆ attributeLabel() [1/2]

◆ attributeLabel() [2/2]

◆ attributeName() [1/2]

◆ attributeName() [2/2]

◆ attributeParentHash() [1/2]

◆ attributeParentHash() [2/2]

◆ attributeSerial() [1/2]

◆ attributeSerial() [2/2]

◆ attributeViaPort() [1/2]

◆ attributeViaPort() [2/2]

◆ attributeWithConnectType() [1/2]

◆ attributeWithConnectType() [2/2]

◆ attributeWithInterface() [1/2]

◆ attributeWithInterface() [2/2]

◆ fromString()

◆ getDeviceID()

◆ getHash()

◆ getLabel()

◆ getName()

◆ getParentHash()

◆ getRuleID()

◆ getSerial()

◆ getTarget()

◆ getViaPort()

◆ getWithConnectType()

◆ internal() [1/2]

◆ internal() [2/2]

◆ isImplicit()

◆ operator bool()

◆ operator=()

◆ setDeviceID()

◆ setHash()

◆ setLabel()

◆ setName()

◆ setOperatorFromString()

◆ setOperatorToString()

◆ setParentHash()

◆ setRuleID()

◆ setSerial()

◆ setTarget()

◆ setViaPort()

◆ setWithConnectType()

◆ targetFromInteger()

◆ targetFromString()

◆ targetToInteger()

◆ targetToString()

◆ toString()

◆ updateMetaDataCounters()