1USBGUARD-RULES.CO(5)                                      USBGUARD-RULES.CO(5)
2
3
4

NAME

6       usbguard-rules.conf - USBGuard rule set file.
7

DESCRIPTION

9       The usbguard-rules.conf file is loaded by the USBGuard daemon after it
10       parses the main configuration file, usbguard-daemon.conf(5). The daemon
11       expects the file to contain rules written in a language which is
12       described in the Rule Language section below.
13

RULE LANGUAGE

15       The USBGuard daemon decides which USB device to authorize based on a
16       policy defined by a set of rules. When a USB device is inserted into
17       the system, the daemon scans the existing rules sequentially. If a
18       matching rule is found, it either authorizes (allows), deauthorizes
19       (blocks) or removes (rejects) the device, based on the rule target. If
20       no matching rule is found, the decision is based on an implicit default
21       target. This implicit default is to block the device until a decision
22       is made by the user. The rule language grammar, expressed in a BNF-like
23       syntax, is the following:
24
25               rule ::= target attributes.
26
27               target ::= "allow" | "block" | "reject".
28
29               attributes ::= attributes | attribute.
30               attributes ::= .
31
32       Rule attributes specify which devices to match or what condition have
33       to be met for the rule to be applicable. See the Device Specification
34       section for the list of available attributes and Conditions for the
35       list of supported rule rule conditions.
36
37   Targets
38       The target of a rule specifies whether the device will be authorized
39       for use or not. Three types of target are recognized:
40
41allow - Authorize the device. The device and its interfaces will be
42           allowed to communicate with the system.
43
44block - Deauthorize the device. The device will remain in a blocked
45           state until it is authorized.
46
47reject - Deauthorize and Remove the device from the system. The
48           device will have to be re-inserted to become visible to the system
49           again.
50
51   Device Specification
52       Except the target, all the other fields of a rule are optional. A rule
53       where only the target is specified will match any device. That allows
54       the policy administrator to write an explicit default target. If no
55       rule from the policy is applicable to the device, an implicit target
56       configured in usbguard-daemon.conf(5) will be used. However, if one
57       wants to narrow the applicability of a rule to a set of devices or one
58       device only, it’s possible to do so with device attributes and rule
59       conditions.
60
61       Device Attributes
62           Device attributes are specific values read from the USB device
63           after it’s inserted to the system. Which attributes are available
64           is defined below. Some of the attributes are derived and some are
65           based on attributes read directly from the device. All attributes
66           support two forms:
67
68single-valued with a syntax:
69
70                       name value
71
72multi-valued with a syntax:
73
74                       name [operator] { value1 value2 ... }
75
76           where the optional operator is one of:
77
78           all-of
79               The device attribute set must contain all of the specified
80               values for the rule to match.
81
82           one-of
83               The device attribute set must contain at least one of the
84               specified values for the rule to match.
85
86           none-of
87               The device attribute set must not contain any of the specified
88               values for the rule to match.
89
90           equals
91               The device attribute set must contain exactly the same set of
92               values for the rule to match.
93
94           equals-ordered
95               The device attribute set must contain exactly the same set of
96               values in the same order for the rule to match.
97
98           match-all
99               The device attribute set must be a subset of the specified
100               values for the rule to match.
101
102           If the operator is not specified it is set to equals.
103
104           List of attributes:
105
106           id usb-device-id
107               Match a USB device ID.
108
109           id [operator] { usb-device-id ... }
110               Match a set of USB device IDs.
111
112           hash "value"
113               Match a hash computed from the device attribute values and the
114               USB descriptor data. The hash is computed for every device by
115               USBGuard.
116
117           hash [operator] { "value" ... }
118               Match a set of device hashes.
119
120           parent-hash "value"
121               Match a hash of the parent device.
122
123           parent-hash [operator] { "value" ... }
124               Match a set of parent device hashes.
125
126           name "device-name"
127               Match the USB device name attribute.
128
129           name [operator] { "device-name" ... }
130               Match a set of USB device names.
131
132           serial "serial-number"
133               Match the USB iSerial device attribute.
134
135           serial [operator] { "serial-number" ... }
136               Match a set of USB iSerial device attributes.
137
138           via-port "port-id"
139               Match the USB port through which the device is connected. Note
140               that some systems have unstable port numbering. The port might
141               change after the system reboots or when certain kernel modules
142               are reloaded. Use the parent-hash attribute if you want to
143               ensure that a device is connected via a specific parent device.
144
145           via-port [operator] { "port-id" ... }
146               Match a set of USB ports.
147
148           with-interface interface-type
149               Match an interface type that the USB device provides.
150
151           with-interface [operator] { interface-type ... }
152               Match a set of interface types against the set of interfaces
153               that the USB device provides.
154
155           with-connect-type "connect-type"
156               Match the USB port/connect_type device attribute.
157
158           with-connect-type [operator] { "connect-type" ... }
159               Match a set of USB port/connect_type device attributes.
160
161           label "label"
162               Associates arbitrary string with a rule. Label is useful for
163               storing some contextual information about rule or for filtering
164               rules by label. This attribute is not used when testing if a
165               rule applies to a device.
166
167           The usb-device-id is a colon delimited pair in the form
168           vendor_id:product_id. All USB devices have this ID assigned by the
169           manufacturer and it should uniquely identify a USB product type.
170           Both vendor_id and product_id are 16-bit numbers represented in
171           hexadecimal base. It’s possible to use an asterisk character to
172           match either any device ID *:* or any product ID from a specific
173           vendor, e.g. 1234:*.
174
175           The port-id value is a platform specific USB port identification.
176           On Linux it’s in the form of "usbN" in case of a USB controller
177           (more accurately a "root hub") or "bus-port[.port[.port ...]]"
178           (e.g. 1-2, 1-2.1, ...) in case of a USB device.
179
180           The interface-type represents a USB interface and should be
181           formatted as three 8-bit numbers in hexadecimal base delimited by a
182           colon character, i.e. cc:ss:pp. The numbers represent the interface
183           class (cc), subclass (ss) and protocol (pp) as assigned by the
184           USB-IF. See the list of assigned classes, subclasses and protocols
185           for details. Instead of the subclass and protocol number, you may
186           write an asterisk character (*) to match all subclasses or
187           protocols. Matching a specific class and a specific protocol is not
188           allowed, i.e. if you use an asterisk as the subclass number, you
189           have to use an asterisk for the protocol too.
190
191   Conditions
192       Whether a rule that matches a device will be applied or not can be
193       further restricted using rule conditions. If the condition expression
194       is met at the rule evaluation time, then the rule target is applied for
195       the device. A condition expression is met if it evaluates to true.
196       Otherwise, the rule evaluation continues with the next rule. A rule
197       conditions has the following syntax:
198
199                if [!]condition
200                if [operator] { [!]conditionA [!]conditionB ... }
201
202       Optionally, an exclamation mark (!) can be used to negate the result of
203       a condition.
204
205       Interpretation of the set operator:
206
207       all-of
208           Evaluate to true if all of the specified conditions evaluated to
209           true.
210
211       one-of
212           Evaluate to true if one of the specified conditions evaluated to
213           true.
214
215       none-of
216           Evaluate to true if none of the specified conditions evaluated to
217           true.
218
219       equals
220           Same as all-of.
221
222       equals-ordered
223           Same as all-of.
224
225       List of conditions:
226
227       localtime(time_range)
228           Evaluates to true if the local time is in the specified time range.
229           time_range can be written either as HH:MM[:SS] or
230           HH:MM[:SS]-HH:MM[:SS].
231
232       allowed-matches(query)
233           Evaluates to true if an allowed device matches the specified query.
234           The query uses the rule syntax.  Conditions in the query are not
235           evaluated.
236
237       rule-applied
238           Evaluates to true if the rule currently being evaluated ever
239           matched a device.
240
241       rule-applied(past_duration)
242           Evaluates to true if the rule currently being evaluated matched a
243           device in the past duration of time specified by the parameter.
244           past_duration can be written as HH:MM:SS, HH:MM, or SS.
245
246       rule-evaluated
247           Evaluates to true if the rule currently being evaluated was ever
248           evaluated before.
249
250       rule-evaluated(past_duration)
251           Evaluates to true if the rule currently being evaluated was
252           evaluated in the pas duration of time specified by the parameter.
253           past_duration can be written as HH:MM:SS, HH:MM, or SS.
254
255       random
256           Evaluates to true/false with a probability of p(true)=0.5.
257
258       random(p_true)
259           Evaluates to true with the specified probability p(true)=p_true.
260
261       true
262           Evaluates always to true.
263
264       false
265           Evaluates always to false.
266
267   Partial rule
268       Partial rule is a rule without a rule target. Partial rules may by used
269       by some commands of usbguard CLI tool.
270

INITIAL POLICY

272       Using the usbguard CLI tool and its generate-policy subcommand, you can
273       generate an initial policy for your system instead of writing one from
274       scratch. The tool generates an allow policy for all devices connected
275       to the system at the time of execution. It has several options to tweak
276       the resulting policy, see usbguard(1) for further details.
277
278       The policy will be printed out on the standard output. It’s a good idea
279       to review the generated rules before using them on a system. The
280       typical workflow for generating an initial policy could look like this:
281

EXAMPLE POLICIES

283       The following examples show what to put into the rules.conf file in
284       order to implement the given policy.
285
286        1. Allow USB mass storage devices (USB flash disks) and block
287           everything else
288
289           This policy will block any device that isn’t just a mass storage
290           device. Devices with a hidden keyboard interface in a USB flash
291           disk will be blocked. Only devices with a single mass storage
292           interface will be allowed to interact with the operating system.
293           The policy consists of a single rule:
294
295                   allow with-interface equals { 08:*:* }
296
297           The blocking is implicit in this case because we didn’t write a
298           block rule. Implicit blocking is useful to desktop users. A desktop
299           applet listening to USBGuard events can ask the user for a decision
300           if an implicit target was applied.
301
302        2. Allow a specific Yubikey device to be connected via a specific port
303           (and reject everything else on that port)
304
305                   allow 1050:0011 name "Yubico Yubikey II" serial "0001234567" via-port "1-2" hash "044b5e168d40ee0245478416caf3d998"
306                   reject via-port "1-2"
307
308           We could use just the hash to match the device. However, using the
309           name and serial attributes provide an useful hint for later
310           inspection of the policy. On the other hand, the hash is the most
311           specific value we can use to identify a device. It’s the best
312           attribute to use if you want a rule to match just one device.
313
314        3. Reject devices with suspicious combination of interfaces
315
316           A USB flash disk which implements a keyboard or a network interface
317           is very suspicious. The following set of rules forms a policy that
318           allows USB flash disks and explicitly rejects devices with an
319           additional and suspicious (as defined before) interface.
320
321                   allow with-interface equals { 08:*:* }
322                   reject with-interface all-of { 08:*:* 03:00:* }
323                   reject with-interface all-of { 08:*:* 03:01:* }
324                   reject with-interface all-of { 08:*:* e0:*:* }
325                   reject with-interface all-of { 08:*:* 02:*:* }
326
327           The policy rejects all USB flash disk devices with an interface
328           from the HID/Keyboard, Communications and Wireless classes. Note
329           that default allow is the wrong approach and you shouldn’t just
330           reject a set of devices and allow the rest. The policy above
331           assumes that blocking is the default. Rejecting a set of devices
332           considered as "bad" is a good approach how to limit the exposure of
333           the OS to such devices as much as possible.
334
335        4. Allow a keyboard-only USB device only if there isn’t already a USB
336           device with a keyboard interface allowed
337
338                   allow with-interface one-of { 03:00:01 03:01:01 } if !allowed-matches(with-interface one-of { 03:00:01 03:01:01 })
339
340        5. Play "Russian roulette" with USB devices
341
342                   allow if random(0.1666)
343                   reject
344

SEE ALSO

346       usbguard-daemon(8), usbguard-daemon.conf(5)
347
348
349
350                                  07/23/2022              USBGUARD-RULES.CO(5)
Impressum