kernel_hardening_checker/engine.py

   1 #!/usr/bin/env python3
   2
   3 """
   4 This tool is for checking the security hardening options of the Linux kernel.
   5
   6 Author: Alexander Popov <alex.popov@linux.com>
   7
   8 This module is the engine of checks.
   9 """
  10
  11 # pylint: disable=missing-class-docstring,missing-function-docstring
  12 # pylint: disable=line-too-long,invalid-name,too-many-branches
  13
  14 GREEN_COLOR = '\x1b[32m'
  15 RED_COLOR = '\x1b[31m'
  16 COLOR_END = '\x1b[0m'
  17
  18 def colorize_result(input_text):
  19     if input_text is None:
  20         return input_text
  21     if input_text.startswith('OK'):
  22         color = GREEN_COLOR
  23     else:
  24         assert(input_text.startswith('FAIL:')), f'unexpected result "{input_text}"'
  25         color = RED_COLOR
  26     return f'{color}{input_text}{COLOR_END}'
  27
  28
  29 class OptCheck:
  30     def __init__(self, reason, decision, name, expected):
  31         assert(name and name == name.strip() and len(name.split()) == 1), \
  32                f'invalid name "{name}" for {self.__class__.__name__}'
  33         self.name = name
  34
  35         assert(decision and decision == decision.strip() and len(decision.split()) == 1), \
  36                f'invalid decision "{decision}" for "{name}" check'
  37         self.decision = decision
  38
  39         assert(reason and reason == reason.strip() and len(reason.split()) == 1), \
  40                f'invalid reason "{reason}" for "{name}" check'
  41         self.reason = reason
  42
  43         assert(expected and expected == expected.strip()), \
  44                f'invalid expected value "{expected}" for "{name}" check (1)'
  45         val_len = len(expected.split())
  46         if val_len == 3:
  47             assert(expected in ('is not set', 'is not off')), \
  48                    f'invalid expected value "{expected}" for "{name}" check (2)'
  49         elif val_len == 2:
  50             assert(expected == 'is present'), \
  51                    f'invalid expected value "{expected}" for "{name}" check (3)'
  52         else:
  53             assert(val_len == 1), \
  54                    f'invalid expected value "{expected}" for "{name}" check (4)'
  55         self.expected = expected
  56
  57         self.state = None
  58         self.result = None
  59
  60     @property
  61     def type(self):
  62         return None
  63
  64     def set_state(self, data):
  65         assert(data is None or isinstance(data, str)), \
  66                f'invalid state "{data}" for "{self.name}" check'
  67         self.state = data
  68
  69     def check(self):
  70         # handle the 'is present' check
  71         if self.expected == 'is present':
  72             if self.state is None:
  73                 self.result = 'FAIL: is not present'
  74             else:
  75                 self.result = 'OK: is present'
  76             return
  77
  78         # handle the 'is not off' option check
  79         if self.expected == 'is not off':
  80             if self.state == 'off':
  81                 self.result = 'FAIL: is off'
  82             elif self.state == '0':
  83                 self.result = 'FAIL: is off, "0"'
  84             elif self.state is None:
  85                 self.result = 'FAIL: is off, not found'
  86             else:
  87                 self.result = f'OK: is not off, "{self.state}"'
  88             return
  89
  90         # handle the option value check
  91         if self.expected == self.state:
  92             self.result = 'OK'
  93         elif self.state is None:
  94             if self.expected == 'is not set':
  95                 self.result = 'OK: is not found'
  96             else:
  97                 self.result = 'FAIL: is not found'
  98         else:
  99             self.result = f'FAIL: "{self.state}"'
 100
 101     def table_print(self, _mode, with_results):
 102         print(f'{self.name:<40}|{self.type:^7}|{self.expected:^12}|{self.decision:^10}|{self.reason:^18}', end='')
 103         if with_results:
 104             print(f'| {colorize_result(self.result)}', end='')
 105
 106     def json_dump(self, with_results):
 107         dump = {
 108             "option_name": self.name,
 109             "type": self.type,
 110             "desired_val": self.expected,
 111             "decision": self.decision,
 112             "reason": self.reason,
 113         }
 114         if with_results:
 115             dump["check_result_text"] = self.result
 116             dump["check_result"] = "FAIL" not in self.result
 117         return dump
 118
 119
 120 class KconfigCheck(OptCheck):
 121     def __init__(self, *args, **kwargs):
 122         super().__init__(*args, **kwargs)
 123         self.name = f'CONFIG_{self.name}'
 124
 125     @property
 126     def type(self):
 127         return 'kconfig'
 128
 129
 130 class CmdlineCheck(OptCheck):
 131     @property
 132     def type(self):
 133         return 'cmdline'
 134
 135
 136 class SysctlCheck(OptCheck):
 137     @property
 138     def type(self):
 139         return 'sysctl'
 140
 141
 142 class VersionCheck:
 143     def __init__(self, ver_expected):
 144         assert(ver_expected and isinstance(ver_expected, tuple) and len(ver_expected) == 3), \
 145                f'invalid expected version "{ver_expected}" for VersionCheck (1)'
 146         assert(all(map(lambda x: isinstance(x, int), ver_expected))), \
 147                f'invalid expected version "{ver_expected}" for VersionCheck (2)'
 148         self.ver_expected = ver_expected
 149         self.ver = ()
 150         self.result = None
 151
 152     @property
 153     def type(self):
 154         return 'version'
 155
 156     def set_state(self, data):
 157         assert(data and isinstance(data, tuple) and len(data) >= 3), \
 158                f'invalid version "{data}" for VersionCheck'
 159         self.ver = data[:3]
 160
 161     def check(self):
 162         if self.ver[0] > self.ver_expected[0]:
 163             self.result = f'OK: version >= {self.ver_expected}'
 164             return
 165         if self.ver[0] < self.ver_expected[0]:
 166             self.result = f'FAIL: version < {self.ver_expected}'
 167             return
 168         # self.ver[0] and self.ver_expected[0] are equal
 169         if self.ver[1] > self.ver_expected[1]:
 170             self.result = f'OK: version >= {self.ver_expected}'
 171             return
 172         if self.ver[1] < self.ver_expected[1]:
 173             self.result = f'FAIL: version < {self.ver_expected}'
 174             return
 175         # self.ver[1] and self.ver_expected[1] are equal too
 176         if self.ver[2] >= self.ver_expected[2]:
 177             self.result = f'OK: version >= {self.ver_expected}'
 178             return
 179         self.result = f'FAIL: version < {self.ver_expected}'
 180
 181     def table_print(self, _mode, with_results):
 182         ver_req = f'kernel version >= {self.ver_expected}'
 183         print(f'{ver_req:<91}', end='')
 184         if with_results:
 185             print(f'| {colorize_result(self.result)}', end='')
 186
 187
 188 class ComplexOptCheck:
 189     def __init__(self, *opts):
 190         self.opts = opts
 191         assert(self.opts), \
 192                f'empty {self.__class__.__name__} check'
 193         assert(len(self.opts) != 1), \
 194                f'useless {self.__class__.__name__} check: {opts}'
 195         assert(isinstance(opts[0], (KconfigCheck, CmdlineCheck, SysctlCheck))), \
 196                f'invalid {self.__class__.__name__} check: {opts}'
 197         self.result = None
 198
 199     @property
 200     def type(self):
 201         return 'complex'
 202
 203     @property
 204     def name(self):
 205         return self.opts[0].name
 206
 207     @property
 208     def expected(self):
 209         return self.opts[0].expected
 210
 211     def table_print(self, mode, with_results):
 212         if mode == 'verbose':
 213             class_name = f'<<< {self.__class__.__name__} >>>'
 214             print(f'    {class_name:87}', end='')
 215             if with_results:
 216                 print(f'| {colorize_result(self.result)}', end='')
 217             for o in self.opts:
 218                 print()
 219                 o.table_print(mode, with_results)
 220         else:
 221             o = self.opts[0]
 222             o.table_print(mode, False)
 223             if with_results:
 224                 print(f'| {colorize_result(self.result)}', end='')
 225
 226     def json_dump(self, with_results):
 227         dump = self.opts[0].json_dump(False)
 228         if with_results:
 229             # Add 'result_text' and 'result' keys to the dictionary
 230             dump["check_result_text"] = self.result
 231             dump["check_result"] = "FAIL" not in self.result
 232         return dump
 233
 234
 235 class OR(ComplexOptCheck):
 236     # self.opts[0] is the option that this OR-check is about.
 237     # Use cases:
 238     #     OR(<X_is_hardened>, <X_is_disabled>)
 239     #     OR(<X_is_hardened>, <old_X_is_hardened>)
 240     def check(self):
 241         for i, opt in enumerate(self.opts):
 242             opt.check()
 243             if opt.result.startswith('OK'):
 244                 self.result = opt.result
 245                 # Add more info for additional checks:
 246                 if i != 0:
 247                     if opt.result == 'OK':
 248                         self.result = f'OK: {opt.name} is "{opt.expected}"'
 249                     elif opt.result == 'OK: is not found':
 250                         self.result = f'OK: {opt.name} is not found'
 251                     elif opt.result == 'OK: is present':
 252                         self.result = f'OK: {opt.name} is present'
 253                     elif opt.result.startswith('OK: is not off'):
 254                         self.result = f'OK: {opt.name} is not off'
 255                     else:
 256                         # VersionCheck provides enough info
 257                         assert(opt.result.startswith('OK: version')), \
 258                                f'unexpected OK description "{opt.result}"'
 259                 return
 260         self.result = self.opts[0].result
 261
 262
 263 class AND(ComplexOptCheck):
 264     # self.opts[0] is the option that this AND-check is about.
 265     # Use cases:
 266     #     AND(<suboption>, <main_option>)
 267     #       Suboption is not checked if checking of the main_option is failed.
 268     #     AND(<X_is_disabled>, <old_X_is_disabled>)
 269     def check(self):
 270         for i, opt in reversed(list(enumerate(self.opts))):
 271             opt.check()
 272             if i == 0:
 273                 self.result = opt.result
 274                 return
 275             if not opt.result.startswith('OK'):
 276                 # This FAIL is caused by additional checks,
 277                 # and not by the main option that this AND-check is about.
 278                 # Describe the reason of the FAIL.
 279                 if opt.result.startswith('FAIL: \"') or opt.result == 'FAIL: is not found':
 280                     self.result = f'FAIL: {opt.name} is not "{opt.expected}"'
 281                 elif opt.result == 'FAIL: is not present':
 282                     self.result = f'FAIL: {opt.name} is not present'
 283                 elif opt.result in ('FAIL: is off', 'FAIL: is off, "0"'):
 284                     self.result = f'FAIL: {opt.name} is off'
 285                 elif opt.result == 'FAIL: is off, not found':
 286                     self.result = f'FAIL: {opt.name} is off, not found'
 287                 else:
 288                     # VersionCheck provides enough info
 289                     self.result = opt.result
 290                     assert(opt.result.startswith('FAIL: version')), \
 291                            f'unexpected FAIL description "{opt.result}"'
 292                 return
 293
 294
 295 SIMPLE_OPTION_TYPES = ('kconfig', 'cmdline', 'sysctl', 'version')
 296
 297
 298 def populate_simple_opt_with_data(opt, data, data_type):
 299     assert(opt.type != 'complex'), \
 300            f'unexpected ComplexOptCheck "{opt.name}"'
 301     assert(opt.type in SIMPLE_OPTION_TYPES), \
 302            f'invalid opt type "{opt.type}"'
 303     assert(data_type in SIMPLE_OPTION_TYPES), \
 304            f'invalid data type "{data_type}"'
 305     assert(data), \
 306            'empty data'
 307
 308     if data_type != opt.type:
 309         return
 310
 311     if data_type in ('kconfig', 'cmdline', 'sysctl'):
 312         opt.set_state(data.get(opt.name, None))
 313     else:
 314         assert(data_type == 'version'), \
 315                f'unexpected data type "{data_type}"'
 316         opt.set_state(data)
 317
 318
 319 def populate_opt_with_data(opt, data, data_type):
 320     assert(opt.type != 'version'), 'a single VersionCheck is useless'
 321     if opt.type != 'complex':
 322         populate_simple_opt_with_data(opt, data, data_type)
 323     else:
 324         for o in opt.opts:
 325             if o.type != 'complex':
 326                 populate_simple_opt_with_data(o, data, data_type)
 327             else:
 328                 # Recursion for nested ComplexOptCheck objects
 329                 populate_opt_with_data(o, data, data_type)
 330
 331
 332 def populate_with_data(checklist, data, data_type):
 333     for opt in checklist:
 334         populate_opt_with_data(opt, data, data_type)
 335
 336
 337 def override_expected_value(checklist, name, new_val):
 338     for opt in checklist:
 339         if opt.name == name:
 340             assert(opt.type in ('kconfig', 'cmdline', 'sysctl')), \
 341                    f'overriding an expected value for "{opt.type}" checks is not supported yet'
 342             opt.expected = new_val
 343
 344
 345 def perform_checks(checklist):
 346     for opt in checklist:
 347         opt.check()