1USBGUARD-RULES.CO(5) USBGUARD-RULES.CO(5)
2
3
4
6 usbguard-rules.conf - USBGuard rule set file.
7
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
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 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
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 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
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
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
346 usbguard-daemon(8), usbguard-daemon.conf(5)
347
348
349
350 07/23/2022 USBGUARD-RULES.CO(5)