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
41       ·   allow - Authorize the device. The device and its interfaces will be
42           allowed to communicate with the system.
43
44       ·   block - Deauthorize the device. The device will remain in a blocked
45           state until it is authorized.
46
47       ·   reject - 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 administator to write an explicit default target. If no rule
55       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
68           ·   single-valued with a syntax:
69
70                       name value
71
72           ·   multi-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           If the operator is not specified it is set to equals.
99
100           List of attributes:
101
102           id usb-device-id
103               Match a USB device ID.
104
105           id [operator] { usb-device-id ... }
106               Match a set of USB device IDs.
107
108           hash "value"
109               Match a hash computed from the device attribute values and the
110               USB descriptor data. The hash is computed for every device by
111               USBGuard.
112
113           hash [operator] { "value" ... }
114               Match a set of device hashes.
115
116           parent-hash "value"
117               Match a hash of the parent device.
118
119           parent-hash [operator] { "value" ... }
120               Match a set of parent device hashes.
121
122           name "device-name"
123               Match the USB device name attribute.
124
125           name [operator] { "device-name" ... }
126               Match a set of USB device names.
127
128           serial "serial-number"
129               Match the USB iSerial device attribute.
130
131           serial [operator] { "serial-number" ... }
132               Match a set of USB iSerial device attributes.
133
134           via-port "port-id"
135               Match the USB port through which the device is connected. Note
136               that some systems have unstable port numbering. The port might
137               change after the system reboots or when certain kernel modules
138               are reloaded. Use the parent-hash attribute if you want to
139               ensure that a device is connected via a specific parent device.
140
141           via-port [operator] { "port-id" ... }
142               Match a set of USB ports.
143
144           with-interface interface-type
145               Match an interface type that the USB device provides.
146
147           with-interface [operator] { interface-type ... }
148               Match a set of interface types against the set of interfaces
149               that the USB device provides.
150
151           The usb-device-id is a colon delimited pair in the form
152           vendor_id:product_id. All USB devices have this ID assigned by the
153           manufacturer and it should uniquely identify a USB product type.
154           Both vendor_id and product_id are 16-bit numbers represented in
155           hexadecimal base. It’s possible to use an asterisk character to
156           match either any device ID *:* or any product ID from a specific
157           vendor, e.g. 1234:*.
158
159           The port-id value is a platform specific USB port identification.
160           On Linux it’s in the form of "usbN" in case of a USB controller
161           (more accurately a "root hub") or "bus-port[.port[.port ...]]"
162           (e.g. 1-2, 1-2.1, ...) in case of a USB device.
163
164           The interface-type represents a USB interface and should be
165           formatted as three 8-bit numbers in hexadecimal base delimited by a
166           colon character, i.e. cc:ss:pp. The numbers represent the interface
167           class (cc), subclass (ss) and protocol (pp) as assigned by the
168           USB-IF. See the list of assigned classes, subclasses and protocols
169           for details. Instead of the subclass and protocol number, you may
170           write an asterisk character (*) to match all subclasses or
171           protocols. Matching a specific class and a specific protocol is not
172           allowed, i.e. if you use an asterisk as the subclass number, you
173           have to use an asterisk for the protocol too.
174
175   Conditions
176       Whether a rule that matches a device will be applied or not can be
177       further restricted using rule conditions. If the condition expression
178       is met at the rule evaluation time, then the rule target is applied for
179       the device. A condition expression is met if it evaluates to true.
180       Otherwise, the rule evaluation continues with the next rule. A rule
181       conditions has the following syntax:
182
183                if [!]condition
184                if [operator] { [!]conditionA [!]conditionB ... }
185
186       Optionally, an exclamation mark (!) can be used to negate the result of
187       a condition.
188
189       Interpretation of the set operator:
190
191       all-of
192           Evaluate to true if all of the specified conditions evaluated to
193           true.
194
195       one-of
196           Evaluate to true if one of the specified conditions evaluated to
197           true.
198
199       none-of
200           Evaluate to true if none of the specified conditions evaluated to
201           true.
202
203       equals
204           Same as all-of.
205
206       equals-ordered
207           Same as all-of.
208
209       List of conditions:
210
211       localtime(time_range)
212           Evaluates to true if the local time is in the specified time range.
213           time_range can be written either as HH:MM[:SS] or
214           HH:MM[:SS]-HH:MM[:SS].
215
216       allowed-matches(query)
217           Evaluates to true if an allowed device matches the specified query.
218           The query uses the rule syntax.  Conditions in the query are not
219           evaluated.
220
221       rule-applied
222           Evaluates to true if the rule currently being evaluated ever
223           matched a device.
224
225       rule-applied(past_duration)
226           Evaluates to true if the rule currently being evaluated matched a
227           device in the past duration of time specified by the parameter.
228           past_duration can be written as HH:MM:SS, HH:MM, or SS.
229
230       rule-evaluated
231           Evaluates to true if the rule currently being evaluated was ever
232           evaluated before.
233
234       rule-evaluated(past_duration)
235           Evaluates to true if the rule currently being evaluated was
236           evaluated in the pas duration of time specified by the parameter.
237           past_duration can be written as HH:MM:SS, HH:MM, or SS.
238
239       random
240           Evaluates to true/false with a probability of p(true)=0.5.
241
242       random(p_true)
243           Evaluates to true with the specified probability p(true)=p_true.
244
245       true
246           Evaluates always to true.
247
248       false
249           Evaluates always to false.
250

INITIAL POLICY

252       Using the usbguard CLI tool and its generate-policy subcommand, you can
253       generate an initial policy for your system instead of writing one from
254       scratch. The tool generates an allow policy for all devices connected
255       to the system at the time of execution. It has several options to tweak
256       the resulting policy, see usbguard(1) for further details.
257
258       The policy will be printed out on the standard output. It’s a good idea
259       to review the generated rules before using them on a system. The
260       typical workflow for generating an initial policy could look like this:
261

EXAMPLE POLICIES

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

SEE ALSO

326       usbguard-daemon(8), usbguard-daemon.conf(5)
327
328
329
330                                  05/17/2019              USBGUARD-RULES.CO(5)
Impressum