New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Rule language: device matching #11

Closed
dkopecek opened this Issue Mar 29, 2015 · 5 comments

Comments

Projects
None yet
1 participant
@dkopecek
Member

dkopecek commented Mar 29, 2015

The rule language (described here) needs some modification to be able to support various "device matching use cases". Here's a proposal for a revised set of attributes usable for matching a device:

  • hash "[0-9a-f]{32}": Match a hash of the device attributes (the hash is computed for every device by USBGuard).
  • name "device-name": Match the USB device name attribute.
  • serial "serial-number": Match the iSerial USB device attribute.
  • via-port "port-id": Match the USB port through which the device is connected.
  • via-port [operator] { "port-id" "port-id" ... }: Match a set of USB ports.
  • with-interface interface-type: Match an interface the USB device provides.
  • with-interface [operator] { interface-type interface-type ... }: Match a set of interface types against the set of interfaces the USB device provides.

operator is one of:

  • all-of: The associated device attribute set must contain all of the specified values for the rule to match.
  • any-of: The associated device attribute set must contain a combination of the specified values for the rule to match.
  • one-of: The associated device attribute set must contain one of the specified values for the rule to match.
  • none-of: The associated device attribute set must not contain any of the specified values for the rule to match.
  • equals-set-of: The associated device attribute set must contain exactly the same set of values for the rule to match.
  • equals-ordered-set-of: The associated device attribute set must contain exactly the same set of values in the same order for the rule to match.

port-id is a platform specific USB port identification. On Linux it's in the form "b-n" where b and n are unsigned integers (e.g. "1-2", "2-4", ...).

interface-type represents a USB interface and may be expressed either in a numeric form or as an interface type string.
The numeric form is expressed as three 8-bit numbers in hexadecimal base delimited using a colon: xx:xx:xx. The numbers represent the interface class, subclass and protocol as assigned by the USB-IF (List of assigned classes, subclasses and protocols).
The string form is human-readable translation of the numeric form and it's USBGuard specific. It's expressed as a string with three colon delimited substrings. The three substrings represent the number-to-string translation of the interface class, subclass and protocol as defined by a USBGuard specific file.

@dkopecek dkopecek self-assigned this Mar 29, 2015

@dkopecek dkopecek added this to the v0.2 milestone Mar 29, 2015

@dkopecek

This comment has been minimized.

Show comment
Hide comment
@dkopecek

dkopecek Mar 30, 2015

Member

Example 1: Allowing a specific flash stick via one port

allow 1234:5653 name "USB foo bar" serial "DWZ1234566" via-port "1-2" with-interface equals-set-of { 08:: }

or better (with hash)

allow 1234:5653 name "USB foo bar" hash "d123fe2394324818398492384" via-port "1-2" with-interface equals-set-of { 08:: }

Note that the name and device id aren't needed, but mentioning the the name and device id makes possible for the policy creator to know, which device is expected to match this rule (without computing the hash for every device).

Example 2: Rejecting anything which is not a mass storage device (class=08)

allow with-interface equals-set-of { 08:: }
reject
Member

dkopecek commented Mar 30, 2015

Example 1: Allowing a specific flash stick via one port

allow 1234:5653 name "USB foo bar" serial "DWZ1234566" via-port "1-2" with-interface equals-set-of { 08:: }

or better (with hash)

allow 1234:5653 name "USB foo bar" hash "d123fe2394324818398492384" via-port "1-2" with-interface equals-set-of { 08:: }

Note that the name and device id aren't needed, but mentioning the the name and device id makes possible for the policy creator to know, which device is expected to match this rule (without computing the hash for every device).

Example 2: Rejecting anything which is not a mass storage device (class=08)

allow with-interface equals-set-of { 08:: }
reject
@dkopecek

This comment has been minimized.

Show comment
Hide comment
@dkopecek

dkopecek Apr 2, 2015

Member

Changes:

  • incomplete numeric interface type specification should require an asterisk: 08:: => 08::
  • the equals-set-of and equals-ordered-set-of should be renamed to just equals and equals-ordered
Member

dkopecek commented Apr 2, 2015

Changes:

  • incomplete numeric interface type specification should require an asterisk: 08:: => 08::
  • the equals-set-of and equals-ordered-set-of should be renamed to just equals and equals-ordered
@dkopecek

This comment has been minimized.

Show comment
Hide comment
@dkopecek

dkopecek Apr 2, 2015

Member

Changes:

  • the any-of set operator is useless
Member

dkopecek commented Apr 2, 2015

Changes:

  • the any-of set operator is useless
@dkopecek

This comment has been minimized.

Show comment
Hide comment
@dkopecek

dkopecek Apr 2, 2015

Member

Partially resolved in 854a9f7. String translation of the interface types is not implemented yet and it's low priority. A separate ticket for tracking the implementation of this feature will be probably better.

Member

dkopecek commented Apr 2, 2015

Partially resolved in 854a9f7. String translation of the interface types is not implemented yet and it's low priority. A separate ticket for tracking the implementation of this feature will be probably better.

@dkopecek

This comment has been minimized.

Show comment
Hide comment
@dkopecek

dkopecek Apr 2, 2015

Member

Created separate ticket for the string<->number translation of interface types and closing this.

Member

dkopecek commented Apr 2, 2015

Created separate ticket for the string<->number translation of interface types and closing this.

@dkopecek dkopecek closed this Apr 2, 2015

dkopecek added a commit that referenced this issue May 26, 2016

Fixed a memory leak in an error path in the rule parser
Resolves: #69

Addresses:
```
Direct leak of 72 byte(s) in 1 object(s) allocated from:
    #0 0x7f8076950bb0 in operator new(unsigned long) (/usr/lib/x86_64-linux-gnu/libasan.so.3+0xc2bb0)
    #1 0x7f8075969fe5 in usbguard::parseRuleSpecification(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const*, unsigned int) src/Library/RuleParser.cpp:72
    #2 0x7f807599382f in usbguard::RulePrivate::fromString(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&) src/Library/RulePrivate.cpp:599
    #3 0x7f8075958d38 in usbguard::Rule::fromString(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&) src/Library/Rule.cpp:254
    #4 0x512764 in ____C_A_T_C_H____T_E_S_T____6 Regression/test_Rule_ghi37.cpp:15
    #5 0x461b26 in Catch::FreeFunctionTestCase::invoke() const (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x461b26)
    #6 0x416165 in Catch::TestCase::invoke() const ../../src/ThirdParty/Catch/include/internal/catch_test_case_info.hpp:176
    #7 0x45cffb in Catch::RunContext::invokeActiveTestCase() (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x45cffb)
    #8 0x45bcfe in Catch::RunContext::runCurrentTest(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&) (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x45bcfe)
    #9 0x454516 in Catch::RunContext::runTest(Catch::TestCase const&) (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x454516)
    #10 0x40d04f in Catch::runTests(Catch::Ptr<Catch::Config> const&) ../../src/ThirdParty/Catch/include/internal/../catch_session.hpp:78
    #11 0x45f67f in Catch::Session::run() (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x45f67f)
    #12 0x45ef2f in Catch::Session::run(int, char const* const*) (/home/james/deb-pkg/TEMP-PACKAGES/usbguard/upstream/src/Tests/.libs/lt-test-regression+0x45ef2f)
    #13 0x42ad3a in main ../../src/ThirdParty/Catch/include/internal/catch_default_main.hpp:15
    #14 0x7f80736df77f in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x2077f)
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment