1USBGUARD-RULES.CONF(5) USBGUARD-RULES.CONF(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 Attributes
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 after
63 it’s inserted to the system. Which attributes are available is defined
64 below. Some of the attributes are derived and some are based on
65 attributes read directly from the device. All attributes support two
66 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 values
80 for the rule to match.
81 one-of
83 The device attribute set must contain at least one of the specified
84 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 USB
110 descriptor data. The hash is computed for every device by USBGuard.
111 hash [operator] { "value" ... }
113 Match a set of device hashes.
114 parent-hash "value"
116 Match a hash of the parent device.
117 parent-hash [operator] { "value" ... }
119 Match a set of parent device hashes.
120 name "device-name"
122 Match the USB device name attribute.
123 name [operator] { "device-name" ... }
125 Match a set of USB device names.
126 serial "serial-number"
128 Match the USB iSerial device attribute.
129 serial [operator] { "serial-number" ... }
131 Match a set of USB iSerial device attributes.
132 via-port "port-id"
134 Match the USB port through which the device is connected. Note that
135 some systems have unstable port numbering. The port might change
136 after the system reboots or when certain kernel modules are
137 reloaded. Use the parent-hash attribute if you want to ensure that
138 a device is connected via a specific parent device.
139 via-port [operator] { "port-id" ... }
141 Match a set of USB ports.
142 with-interface interface-type
144 Match an interface type that the USB device provides.
145 with-interface [operator] { interface-type ... }
147 Match a set of interface types against the set of interfaces that
148 the USB device provides.
149 The usb-device-id is a colon delimited pair in the form
151 vendor_id:product_id. All USB devices have this ID assigned by the
152 manufacturer and it should uniquely identify a USB product type. Both
153 vendor_id and product_id are 16-bit numbers represented in hexadecimal
154 base. It’s possible to use an asterisk character to match either any
155 device ID *:* or any product ID from a specific vendor, e.g. 1234:*.
156 The port-id value is a platform specific USB port identification. On
158 Linux it’s in the form of "usbN" in case of a USB controller (more
159 accurately a "root hub") or "bus-port[.port[.port ...]]" (e.g. 1-2,
160 1-2.1, ...) in case of a USB device.
161 The interface-type represents a USB interface and should be formatted
163 as three 8-bit numbers in hexadecimal base delimited by a colon
164 character, i.e. cc:ss:pp. The numbers represent the interface class
165 (cc), subclass (ss) and protocol (pp) as assigned by the USB-IF
166 <http://www.usb.org/about>. See the list of assigned classes,
167 subclasses and protocols <http://www.usb.org/developers/defined_class>
168 for details. Instead of the subclass and protocol number, you may write
169 an asterisk character (*) to match all subclasses or protocols.
170 Matching a specific class and a specific protocol is not allowed, i.e.
171 if you use an asterisk as the subclass number, you have to use an
172 asterisk for the protocol too.
173 Conditions
175 Whether a rule that matches a device will be applied or not can be
176 further restricted using rule conditions. If the condition expression
177 is met at the rule evaluation time, then the rule target is applied for
178 the device. A condition expression is met if it evaluates to true.
179 Otherwise, the rule evaluation continues with the next rule. A rule
180 conditions has the following syntax:
181 if [!]condition
183 if [operator] { [!]conditionA [!]conditionB ... }
184 Optionally, an exclamation mark (!) can be used to negate the result of
186 a condition.
187 Interpretation of the set operator:
189 all-of
191 Evaluate to true if all of the specified conditions evaluated to
192 true.
193 one-of
195 Evaluate to true if one of the specified conditions evaluated to
196 true.
197 none-of
199 Evaluate to true if none of the specified conditions evaluated to
200 true.
201 equals
203 Same as all-of.
204 equals-ordered
206 Same as all-of.
207 List of conditions:
209 localtime(time_range)
211 Evaluates to true if the local time is in the specified time range.
212 time_range can be written either as HH:MM[:SS] or
213 HH:MM[:SS]-HH:MM[:SS].
214 allowed-matches(query)
216 Evaluates to true if an allowed device matches the specified query.
217 The query uses the rule syntax. Conditions in the query are not
218 evaluated.
219 rule-applied
221 Evaluates to true if the rule currently being evaluated ever
222 matched a device.
223 rule-applied(past_duration)
225 Evaluates to true if the rule currently being evaluated matched a
226 device in the past duration of time specified by the parameter.
227 past_duration can be written as HH:MM:SS, HH:MM, or SS.
228 rule-evaluated
230 Evaluates to true if the rule currently being evaluated was ever
231 evaluated before.
232 rule-evaluated(past_duration)
234 Evaluates to true if the rule currently being evaluated was
235 evaluated in the pas duration of time specified by the parameter.
236 past_duration can be written as HH:MM:SS, HH:MM, or SS.
237 random
239 Evaluates to true/false with a probability of p(true)=0.5.
240 random(p_true)
242 Evaluates to true with the specified probability p(true)=p_true.
243 true
245 Evaluates always to true.
246 false
248 Evaluates always to false.
249
251 Using the usbguard CLI tool and its generate-policy subcommand, you can
252 generate an initial policy for your system instead of writing one from
253 scratch. The tool generates an allow policy for all devices connected
254 to the system at the time of execution. It has several options to tweak
255 the resulting policy, see usbguard(1) for further details.
256 The policy will be printed out on the standard output. It’s a good idea
258 to review the generated rules before using them on a system. The
259 typical workflow for generating an initial policy could look like this:
260 $ sudo usbguard generate-policy > rules.conf
262 $ vi rules.conf
263 (review/modify the rule set)
264 $ sudo install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf
265 $ sudo systemctl restart usbguard
266
268 The following examples show what to put into the rules.conf file in
269 order to implement the given policy.
270 1. Allow USB mass storage devices (USB flash disks) and block
272 everything else
273 This policy will block any device that isn’t just a mass storage
275 device. Devices with a hidden keyboard interface in a USB flash
276 disk will be blocked. Only devices with a single mass storage
277 interface will be allowed to interact with the operating system.
278 The policy consists of a single rule:
279 allow with-interface equals { 08:*:* }
281 The blocking is implicit in this case because we didn’t write a
283 block rule. Implicit blocking is useful to desktop users. A desktop
284 applet listening to USBGuard events can ask the user for a decision
285 if an implicit target was applied.
286 2. Allow a specific Yubikey device to be connected via a specific port
288 (and reject everything else on that port)
289 allow 1050:0011 name "Yubico Yubikey II" serial "0001234567" via-port "1-2" hash "044b5e168d40ee0245478416caf3d998"
291 reject via-port "1-2"
292 We could use just the hash to match the device. However, using the
294 name and serial attributes provide an useful hint for later
295 inspection of the policy. On the other hand, the hash is the most
296 specific value we can use to identify a device. It’s the best
297 attribute to use if you want a rule to match just one device.
298 3. Reject devices with suspicious combination of interfaces
300 A USB flash disk which implements a keyboard or a network interface
302 is very suspicious. The following set of rules forms a policy that
303 allows USB flash disks and explicitly rejects devices with an
304 additional and suspicious (as defined before) interface.
305 allow with-interface equals { 08:*:* }
307 reject with-interface all-of { 08:*:* 03:00:* }
308 reject with-interface all-of { 08:*:* 03:01:* }
309 reject with-interface all-of { 08:*:* e0:*:* }
310 reject with-interface all-of { 08:*:* 02:*:* }
311 The policy rejects all USB flash disk devices with an interface
313 from the HID/Keyboard, Communications and Wireless classes. Note
314 that blacklisting is the wrong approach and you shouldn’t just
315 blacklist a set of devices and allow the rest. The policy above
316 assumes that blocking is the default. Rejecting a set of devices
317 considered as "bad" is a good approach how to limit the exposure of
318 the OS to such devices as much as possible.
319 4. Allow a keyboard-only USB device only if there isn’t already a USB
321 device with a keyboard interface allowed
322 allow with-interface one-of { 03:00:01 03:01:01 } if !allowed-matches(with-interface one-of { 03:00:01 03:01:01 })
324 5. Play "Russian roulette" with USB devices
326 allow if random(0.1666)
328 reject
329
331 usbguard-daemon(8), usbguard-daemon.conf(5)
332 Unresolved directive in usbguard-rules.conf.5.adoc -
334 include::footer.adoc[]
335 2017-11-30 USBGUARD-RULES.CONF(5)