1USBGUARD-RULES.CO(5) USBGUARD-RULES.CO(5)
2
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 rule ::= target attributes.
26 target ::= "allow" | "block" | "reject".
28 attributes ::= attributes | attribute.
30 attributes ::= .
31 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 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 · allow - Authorize the device. The device and its interfaces will be
42 allowed to communicate with the system.
43 · block - Deauthorize the device. The device will remain in a blocked
45 state until it is authorized.
46 · 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 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 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 · single-valued with a syntax:
69 name value
71 · multi-valued with a syntax:
73 name [operator] { value1 value2 ... }
75 where the optional operator is one of:
77 all-of
79 The device attribute set must contain all of the specified
80 values for the rule to match.
81 one-of
83 The device attribute set must contain at least one of the
84 specified values for the rule to match.
85 none-of
87 The device attribute set must not contain any of the specified
88 values for the rule to match.
89 equals
91 The device attribute set must contain exactly the same set of
92 values for the rule to match.
93 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 If the operator is not specified it is set to equals.
99 List of attributes:
101 id usb-device-id
103 Match a USB device ID.
104 id [operator] { usb-device-id ... }
106 Match a set of USB device IDs.
107 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 hash [operator] { "value" ... }
114 Match a set of device hashes.
115 parent-hash "value"
117 Match a hash of the parent device.
118 parent-hash [operator] { "value" ... }
120 Match a set of parent device hashes.
121 name "device-name"
123 Match the USB device name attribute.
124 name [operator] { "device-name" ... }
126 Match a set of USB device names.
127 serial "serial-number"
129 Match the USB iSerial device attribute.
130 serial [operator] { "serial-number" ... }
132 Match a set of USB iSerial device attributes.
133 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 via-port [operator] { "port-id" ... }
142 Match a set of USB ports.
143 with-interface interface-type
145 Match an interface type that the USB device provides.
146 with-interface [operator] { interface-type ... }
148 Match a set of interface types against the set of interfaces
149 that the USB device provides.
150 with-connect-type "connect-type"
152 Match the USB port/connect_type device attribute.
153 with-connect-type [operator] { "connect-type" ... }
155 Match a set of USB port/connect_type device attributes.
156 The usb-device-id is a colon delimited pair in the form
158 vendor_id:product_id. All USB devices have this ID assigned by the
159 manufacturer and it should uniquely identify a USB product type.
160 Both vendor_id and product_id are 16-bit numbers represented in
161 hexadecimal base. It’s possible to use an asterisk character to
162 match either any device ID *:* or any product ID from a specific
163 vendor, e.g. 1234:*.
164 The port-id value is a platform specific USB port identification.
166 On Linux it’s in the form of "usbN" in case of a USB controller
167 (more accurately a "root hub") or "bus-port[.port[.port ...]]"
168 (e.g. 1-2, 1-2.1, ...) in case of a USB device.
169 The interface-type represents a USB interface and should be
171 formatted as three 8-bit numbers in hexadecimal base delimited by a
172 colon character, i.e. cc:ss:pp. The numbers represent the interface
173 class (cc), subclass (ss) and protocol (pp) as assigned by the
174 USB-IF. See the list of assigned classes, subclasses and protocols
175 for details. Instead of the subclass and protocol number, you may
176 write an asterisk character (*) to match all subclasses or
177 protocols. Matching a specific class and a specific protocol is not
178 allowed, i.e. if you use an asterisk as the subclass number, you
179 have to use an asterisk for the protocol too.
180 Conditions
182 Whether a rule that matches a device will be applied or not can be
183 further restricted using rule conditions. If the condition expression
184 is met at the rule evaluation time, then the rule target is applied for
185 the device. A condition expression is met if it evaluates to true.
186 Otherwise, the rule evaluation continues with the next rule. A rule
187 conditions has the following syntax:
188 if [!]condition
190 if [operator] { [!]conditionA [!]conditionB ... }
191 Optionally, an exclamation mark (!) can be used to negate the result of
193 a condition.
194 Interpretation of the set operator:
196 all-of
198 Evaluate to true if all of the specified conditions evaluated to
199 true.
200 one-of
202 Evaluate to true if one of the specified conditions evaluated to
203 true.
204 none-of
206 Evaluate to true if none of the specified conditions evaluated to
207 true.
208 equals
210 Same as all-of.
211 equals-ordered
213 Same as all-of.
214 List of conditions:
216 localtime(time_range)
218 Evaluates to true if the local time is in the specified time range.
219 time_range can be written either as HH:MM[:SS] or
220 HH:MM[:SS]-HH:MM[:SS].
221 allowed-matches(query)
223 Evaluates to true if an allowed device matches the specified query.
224 The query uses the rule syntax. Conditions in the query are not
225 evaluated.
226 rule-applied
228 Evaluates to true if the rule currently being evaluated ever
229 matched a device.
230 rule-applied(past_duration)
232 Evaluates to true if the rule currently being evaluated matched a
233 device in the past duration of time specified by the parameter.
234 past_duration can be written as HH:MM:SS, HH:MM, or SS.
235 rule-evaluated
237 Evaluates to true if the rule currently being evaluated was ever
238 evaluated before.
239 rule-evaluated(past_duration)
241 Evaluates to true if the rule currently being evaluated was
242 evaluated in the pas duration of time specified by the parameter.
243 past_duration can be written as HH:MM:SS, HH:MM, or SS.
244 random
246 Evaluates to true/false with a probability of p(true)=0.5.
247 random(p_true)
249 Evaluates to true with the specified probability p(true)=p_true.
250 true
252 Evaluates always to true.
253 false
255 Evaluates always to false.
256
258 Using the usbguard CLI tool and its generate-policy subcommand, you can
259 generate an initial policy for your system instead of writing one from
260 scratch. The tool generates an allow policy for all devices connected
261 to the system at the time of execution. It has several options to tweak
262 the resulting policy, see usbguard(1) for further details.
263 The policy will be printed out on the standard output. It’s a good idea
265 to review the generated rules before using them on a system. The
266 typical workflow for generating an initial policy could look like this:
267
269 The following examples show what to put into the rules.conf file in
270 order to implement the given policy.
271 1. Allow USB mass storage devices (USB flash disks) and block
273 everything else
274 This policy will block any device that isn’t just a mass storage
276 device. Devices with a hidden keyboard interface in a USB flash
277 disk will be blocked. Only devices with a single mass storage
278 interface will be allowed to interact with the operating system.
279 The policy consists of a single rule:
280 allow with-interface equals { 08:*:* }
282 The blocking is implicit in this case because we didn’t write a
284 block rule. Implicit blocking is useful to desktop users. A desktop
285 applet listening to USBGuard events can ask the user for a decision
286 if an implicit target was applied.
287 2. Allow a specific Yubikey device to be connected via a specific port
289 (and reject everything else on that port)
290 allow 1050:0011 name "Yubico Yubikey II" serial "0001234567" via-port "1-2" hash "044b5e168d40ee0245478416caf3d998"
292 reject via-port "1-2"
293 We could use just the hash to match the device. However, using the
295 name and serial attributes provide an useful hint for later
296 inspection of the policy. On the other hand, the hash is the most
297 specific value we can use to identify a device. It’s the best
298 attribute to use if you want a rule to match just one device.
299 3. Reject devices with suspicious combination of interfaces
301 A USB flash disk which implements a keyboard or a network interface
303 is very suspicious. The following set of rules forms a policy that
304 allows USB flash disks and explicitly rejects devices with an
305 additional and suspicious (as defined before) interface.
306 allow with-interface equals { 08:*:* }
308 reject with-interface all-of { 08:*:* 03:00:* }
309 reject with-interface all-of { 08:*:* 03:01:* }
310 reject with-interface all-of { 08:*:* e0:*:* }
311 reject with-interface all-of { 08:*:* 02:*:* }
312 The policy rejects all USB flash disk devices with an interface
314 from the HID/Keyboard, Communications and Wireless classes. Note
315 that blacklisting is the wrong approach and you shouldn’t just
316 blacklist a set of devices and allow the rest. The policy above
317 assumes that blocking is the default. Rejecting a set of devices
318 considered as "bad" is a good approach how to limit the exposure of
319 the OS to such devices as much as possible.
320 4. Allow a keyboard-only USB device only if there isn’t already a USB
322 device with a keyboard interface allowed
323 allow with-interface one-of { 03:00:01 03:01:01 } if !allowed-matches(with-interface one-of { 03:00:01 03:01:01 })
325 5. Play "Russian roulette" with USB devices
327 allow if random(0.1666)
329 reject
330
332 usbguard-daemon(8), usbguard-daemon.conf(5)
333 01/31/2020 USBGUARD-RULES.CO(5)