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 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
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
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
326 usbguard-daemon(8), usbguard-daemon.conf(5)
327
328
329
330 05/17/2019 USBGUARD-RULES.CO(5)