4 *** RSBAC Python bindings ***
8 = rsbac -- An Python interface to the RSBAC system =
10 The `rsbac` package is a full interface to the [RSBAC
11 http://rsbac.org] Linux security system, including support to manage
12 the various models it provides. Its goal is to be easy to use,
13 high-level, "object-oriented", complete and with acceptable
14 performance. It allows to easily administrate the RSBAC configuration
15 with the power of Python.
17 You can download a frequently updated release [here
18 py-rsbac-unstable-latest.tar.gz].
20 Multithreading is not supported at all. Please use some lock to access
21 the package in a multithread environment.
23 It was developped first for RSBAC 1.2.8 then for RSBAC 1.3.0, tested
24 mainly on a x86 machine and a PowerPC (G4) machine. Compatibility with
25 1.2.8 is not ensured. However with the correct `rsbac.headers` module,
28 The first release of this package will target full coverage of the
29 RSBAC API (except for PM and MAC models which remain to be added.)
30 More high-level tools built on top of it are planned (such as a GUI,
31 new command line tools, a dedicated shell, backup tools or automatic
32 deployment for example.)
34 == Main functions and variables ==
36 The `rsbac` package provides some generic functions.
40 The RSBAC Python package version as a tuple
41 `(major,middle,minor,extra)` where `extra` is a string, and other
42 components are integers.
46 The RSBAC kernel version as a tuple `(major,middle,minor)`.
50 The RSBAC library version as a tuple `(major,middle,minor)`.
54 The RSBAC headers version as a tuple `(major,middle,minor)`.
58 Dump statistics about RSBAC to kernel log.
60 `checkConsistency(correct, checkInode)`
62 Check RSBAC configuration consistency. The `correct` argument is 0 to
63 do only a check, 1 to correct errors and 2 to correct even more
64 errors. The `checkInode` argument is a boolean which indicate if
65 inode numbers must also be checked or not.
69 Write all dirty lists to disk. Returns number of lists written.
73 Initialize a filesystem with RSBAC. This is normally not needed,
74 since filesystems are automatically initialized on mount.
76 === symbolics name and documentation related functions ===
78 The `librsbac.so` provides various functions to retrieve symbolic
79 names for most of the RSBAC constants and conversely to retrieve
80 constant from the symbolic name. These various functions are provided
81 in the rsbac python package.
83 For each types of constants, there are 3 functions defined as follow:
87 Retrieve the integer constant from the symbolic name `name`.
91 Retrieve the symbolic name from the integer constant `n`.
95 Retrieve the list of names. Note that `getFooNames()[n]` is
96 equivalent to `getFooName(n)`, as long as `n` is valid.
99 There are the following functions:
101 `getRequestName(n)`, `getRequestNames()`, `getRequestNumber(name)`
103 Name of the requests (`ADD_TO_KERNEL`, `ALTER`, `APPEND_OPEN`,..)
105 `getResultName(n)`, `getResultNames()`, `getResultNumber(name)`
107 Name of the results (`NOT_GRANTED`, `GRANTED`,..)
109 `getAttributeName(n)`, `getAttributeNames()`, `getAttributeNumber(name)`
111 Name of the attributes (`pseudo`, `security_level`, `rc_type_fd`,..)
113 `getScdTypeName(n)`, `getScdTypeNames()`, `getScdTypeNumber(name)`
115 Name of the system control data (`time_strucs`, `clock`, `host_id`,..)
117 `getTargetName(n)`, `getTargetNames()`, `getTargetNumbel(name)`
119 Name of the RSBAC target (`FILE`, `DIR`, `NETTEMP_NT`,..)
121 `getIpcTargetName(n)`, `getIpcTargetNames()`, `getIpcTargetNumber(name)`
123 Name of the IPC types (`sem`, `msg`, `shm`,..)
125 `getSwitchTargetName(n)`, `getSwitchTargetNames()`, `getSwitchTargetNumber(name)`
127 Name of the RSBAC modules (`GEN`, `MAC`, `PM`,..)
129 `getCapName(n)`, `getCapNames()`, `getCapNumber(name)`
131 Name of the Linux capabilities (`CHOWN`, `DAC_OVERRIDE`, `NET_RAW`,..)
133 `getRcTargetName(n)`, `getRcTargetNames()`, `getRcTargetNumber(name)`
135 Name of the RC target (`ROLE` and `TYPE`)
137 `getRcAdminName(n)`, `getRcAdminNames()`, `getRcAdminNumber(name)`
139 Name of the RC admin types (`no_admin`, `role_admin`,..)
141 `getRcScdTypeName(n)`, `getRcScdTypeNames()`, `getRcScdTypeNumber(name)`
143 Like `ScdType`, but with additionnal constants specific to the RC
146 `getRcSpecialRightName(n)`, `getRcSpecialRightNames()`, `getRcSpecialRightNumber(name)`
148 Like `Request`, but with additionnal constants specific to the RC
151 `getRessourceName(n)`, `getRessourceNames()`, `getRessourceNumbers(name)`
153 Name of the ressource (those settable by ulimit.) (`cpu`, `stack`,
156 `getLogLevelName(n)`, `getLogLevelNames()`, `getLogLevelNumber(name)`
158 Name of the log levels (`none`, `denied`, `full`,..)
160 `getAttributeModule(attribute)`
162 Get the module ID to which an attribute belong. The `attribute`
163 parameter is an integer.
167 Get the name of the error identified by `n`. This value must be
168 negative, and is usually below or equal to -1001. Be careful: All
169 unknown errors are reported as "Success"!
171 `getAttributeParameters(attribute)`
173 Return a textual description of the attribute. The resulting string
174 is only useful for debugging purpose.
176 `getRcItemParameters(value)`
178 Return a textual description of the RC item. The resulting string is
179 only useful for debugging purpose.
181 === log related functions ===
185 Open RSBAC log. *Note*: This function does nothing.
189 Close RSBAC log. *Note*: This function does nothing.
193 Read RSBAC log. Up to `size` bytes are read. Return a string.
195 `readRingBuffer(size=4096)`
197 Read the RSBAC ring buffer. Up to `size` bytes are read. Return a
200 `readAndClearRingBuffer(size=4096)`
202 Read then clear the RSBAC ring buffer. Up to `size` bytes are
203 read. Return a string.
207 Clear the RSBAC ring buffer.
213 Each users have several type of roles for each of the RSBAC
214 modules. For example, root default system role for the FF module is
215 "administrator", while default system role for the security officer
216 for this module is "security_officer" and all others users have the
217 role "user". This way, each users can administrate or obtains rights
220 The module `rsbac.roles` allows to represent the system roles (not
221 related to RC roles!) The class `SystemRole` is already instantiated
222 for the predefined RSBAC system role, which are:
226 * `roles.security_officer`
228 * `roles.administrator`
232 Since `SystemRole` class build singleton instances, it is possible to
233 compare them with the `is` operator.
237 Several data types in RSBAC are in fact integers used as bit vector.
238 For example, the `rsbac_request_vector_t` is an integer that hold a
239 set of flags related to allowed requests. To manipulate them
240 conveniently under Python, a class was created for each such
241 types. So, for the `rsbac_request_vector_t` there is the corresponding
242 `rsbac.RequestVector` data type in the rsbac package, and so on for
245 Such classes provides an immutable set. To modify them, it is
246 necessary to create a new instance. It is similar to string
247 manipulations under Python, where a new string must be created for
250 The flags classes defined in the `rsbac` module are the following:
252 * `RequestVector`, `RcRequestVector`, `AclRequestVector`
254 * `ScdVector`, `JailScdVector`
264 Generic description follows: (where `Flags` name is for illustration
269 `init` is a versatile mean to specify an initial value. It can be
272 * a string, naming a flag,
274 * a tuple or a list, which is recursively visited and whose items are
277 * an integer or any object castable to an integer, representing a bit
278 vector (each bit of the integer correspond to a flag.)
282 Return an iterator over each set flags. First the flags whose name is
283 know are returned, then follows each integer representing unknown
284 flag (each integer is a power of 2, to match the constructor
289 Return a string representation of the instance such that executing
290 the string give back the same object.
296 Return respectively an int or a long which is the integer with the
297 bit pattern described by all the flags.
301 Compare two instances. The order is stable but undefined.
309 Combine two instances with one of the respective boolean operator OR,
310 XOR or AND. The `other` value should be either a `Flags` instance or
311 a value accepted by the `Flags` constructor.
315 Return a new instance where all *known* flags are inverted. Unknown
316 bit are kept unchanged.
318 FIXME: Give a better set of examples..
320 --- Example with the RequestVector type ---
323 >>> rsbac.RequestVector()
325 >>> rsbac.RequestVector('lock', 'connect', 'alter')
326 RequestVector('alter', 'connect', 'lock')
327 >>> int( rsbac.RequestVector('lock') )
328 562949953421312L # 2**49
329 >>> rsbac.RequestVector( 2**49 )
330 RequestVector('lock')
331 >>> int( rsbac.RequestVector('alter') )
333 >>> rsbac.RequestVector( [ ( 'lock' , 'ioctl' ) , [ 'mount' ] , 2 ] )
334 RequestVector('alter', 'mount', 'ioctl', 'lock')
335 >>> ~rsbac.RequestVector()
336 RequestVector('add_to_kernel', 'alter', 'append_open', ..., 'ioctl', 'lock', 'authenticate')
337 >>> rsbac.RequestVector('bind', 'listen') ^ rsbac.RequestVector('bind', 'connect')
338 RequestVector('listen', 'connect')
339 >>> rsbac.RequestVector('bind', 'listen') & ~rsbac.RequestVector('bind', 'connect')
340 RequestVector('listen')
341 >>> list( rsbac.RequestVector( 127 ) )
342 ['add_to_kernel', 'alter', 'append_open', 'change_group', 'change_owner', 'chdir', 'clone']
346 >>> a = rsbac.RequestVector( 'bind' )
347 >>> a |= 'listen' , 'connect'
349 RequestVector('bind', 'listen', 'connect')
350 >>> a &= ~rsbac.RequestVector( 'bind' , 'listen' )
352 RequestVector('connect')
355 === dict- and set- like variables ===
357 At some places, some variables have a dict-like or a set-like
358 interface, meaning that they can be used and updated like the usual
359 Python dictionnaries or Python sets. These variables are usually
360 dynamic, meaning that there contents reflect the state of the RSBAC
363 There is also a type named "TTL dict-like variable" at some place in
364 this document. It's in fact a type sharing both `set` and `dict`
365 interface. This type act as a dictionnary, where the values have the
366 meaning described in the "TTL" section. To summarize: a value with
367 `False` mean that there is no entry for the given key, `None` mean to
368 keep the existing TTL, other value mean that the entry exists where an
369 integer specify the TTL and `True` mean that the TTL is illimited.
373 The way to specify TTL in the rsbac package is a bit different from
374 the usage in other RSBAC tools.
376 In other RSBAC tools (as understood internally in the kernel), a
377 special value (maximum representable TTL value) is used when we want
378 to preserve the TTL, 0 is for unlimited TTL and any other integers are
379 interpreted as a duration in seconds.
381 But we have chosen another approach. In the rsbac package, `None` mean
382 that we want to keep the TTL (thus we specify "no" TTL), `False` mean
383 that the object doesn't exists (the TTL expired, or is undefined or
384 unknown), `True` means unlimited TTL and any integer means a duration
385 in seconds. Since TTL cannot be lower than 1s, any integers is clamped
386 to this minimal duration. It means that 0 is also interpreted as a
387 number of second, which is clamped to 1s. The whole point is to have a
388 coherent behavior. (A better behavior could have been reached if it
389 was possible to set the TTL to 0s to discard immediatly the
390 corresponding settings in the RSBAC configuration.)
394 | *TTL* | *Meaning* |
395 | `False` | Expired TTL (No entry/no such object) |
396 | integer | remaining TTL in seconds |
397 | `True` | unlimited TTL |
398 | `None` | ask to keep the current TTL |
402 RSBAC is divided into various models (aka modules, depending of the
403 context.) There are for example the ACL, RC and PM modules. Each of
404 these modules can be turned on and off (depending of kernel options
405 when the kernel was compiled, or depending of the nature of the
406 model), and their softmode may be enabled or disabled. Also,
407 naturally, a model can be available or not, according to choice made
408 when compiling the kernel.
410 The `rsbac.module` module provides a list of all the RSBAC modules
411 known to the rsbac package. This module contains an instance of a
412 `module.Module` class for each of them. There is also a `module.all`
413 variable which is a list of all these instances.
415 Each module is represented by the following class:
419 This class is not meant to be instantiated by the user.
425 Cast the module instance to the corresponding RSBAC identifier.
429 This read-only property is the RSBAC identifier for the module.
433 This read-only property is the name of the module.
437 This read-only property is a boolean, which is true if the module was
438 compiled in the kernel and False otherwise. If the module is not
439 available, then access to other properties will fail.
443 This read/write property is the state of the module. If true, the
444 module is enabled. Otherwise, it is disabled.
448 This read-only property indicate if the module can be switched on.
452 This read-only property indicate if the module can be switched off.
456 This read/write property is the state of the softmode for the
457 module. If true, the softmode is enabled. Otherwise, it is disabled.
459 `softmodeSwitchableOn`
461 This read-only property indicate if the softmode of the module can be
464 `softmodeSwitchableOff`
466 This read-only property indicate if the softmode of the module can be
471 RSBAC transactions are fully supported. To make them easy to use, it
472 was chosen to use a global variable used internally by the rsbac
473 package, rather than letting the user specify the current transaction
474 manually when reading/modifying RSBAC system configuration. The module
475 `rsbac.transaction` contains the class and functions needed to manage
478 The standard method to run a block of code with a new transaction and
479 ensuring the transaction is correctly terminated even if exception
480 occurs, is to use the `transaction.withTransaction` function.
482 `withTransaction(function, uid=.., password=None, ttl=True)`
484 Create a new transaction, then call `function` to which a
485 `Transaction` instance is passed as the only argument. Anything
486 happening while `function` is called, is performed with the
487 corresponding transaction. The function must `commit` or `forget` the
488 transaction at some point before returning. If the function doesn't
489 terminate the transaction, then it is automatically canceled when the
490 function returns. See the documentation of the `Transaction` instance
493 `function` is a callable taking one argument.
495 `uid` is the UID to which the transaction belong. The default value
496 allows any users to use the transaction, in which case a password may
499 `password` is an optional password to protect the transaction. The
500 default value doesn't define any password.
502 `ttl`, used to select the time to live of the transaction. The TTL
503 cannot exceed the maximum duration specified in the kernel. The
504 default is the maximum allowed TTL.
506 The transaction is represented by a instance of the following class:
508 `class Transaction(..)`
510 This class is not meant to be instantied by the user. See
511 `withTransaction` to create and use such instance.
513 Its purpose is to represent an existing transaction, not to create
518 Reset the TTL of the transaction. Default value is to extend the TTL
519 to the maximum allowed duration.
523 Commit the transaction.
527 Forget (revert, cancel) the transaction.
529 --- Example of transaction ---
531 def doSomething( transaction ) :
540 withTransaction( doSomething , ttl = 300 )
543 == Representing objects ==
545 A central concept to RSBAC is the various Unix objects such as file
546 system objects (file, directory, fifo pipe, ..), processes, network
547 device and so on. To represent them, the `rsbac.objects` package
548 provides a hierarchy of classes for each RSBAC object type. Through
549 these classes, all RSBAC objects attributes can be read and written.
551 The module described below also contains 3 functions
552 `listAllDevices()`, `listAllUsers()` and `listAllGroups()` which
553 return the corresponding list of objects known to RSBAC.
555 Most of the following class contains a `rcTypes` attribute with a
556 dict-like interface which gives access to all the defined RC type
557 specific to the corresponding class. For more information, see the
558 section discussing this topic.
560 [[LocalTableOfContents]]
564 All common filesystem objects are represented with one of the
569 `class Directory(id)`
579 `class UnixSocket(id)`
581 The constructor takes a path to the file system objects.
583 The FD class is an abstract data type which resolve to the correct
584 type (`File`, `Directory`, `Symlink`, `Device`, `Fifo` or
585 `UnixSocket`) inside the RSBAC system (not by the `rsbac` Python
590 Return the ID (the path).
594 This dict-like attribute gives access to ACL entries for the
595 object. It's indexed by a subject (user, RC role or ACL group.)
601 A dict-like attribute which contains all FD RC types.
603 Additionnaly, there are some predefined instances to match particular
618 * `defaultUnixSocket`
620 These instances are useful for the ACL entries on the default targets.
624 The following classes derive from the `DeviceBase` class.
626 It is different from the `Device` class which is instantiated with a
627 path, while here we need the `major` and `minor` numbers.
629 `class BlockDevice(major[, minor])`
631 `class CharacterDevice(major[, minor])`
633 If `minor` is not specified, then construct an object that match any
634 device with the specified `major` number.
638 This dict-like attribute gives access to ACL entries for the
639 object. It's indexed by a subject (user, RC role or ACL group.)
645 A dict-like attribute which contains all network device RC types.
647 === User and group ===
649 See also `um.User` and `um.Group` for the UM specific settings related
652 The `rsbac.um` class contains the dict-like variable `users` and
653 `groups` which gives access to all defined users and groups in RSBAC.
654 Note that you should not perform a call like `users.clear()` (which
655 remove ALL the users from the UM module) by mistake, especially if the
656 system is configured to rely on RSBAC for all authentication.
658 `addUser(name, uid=None, password=None, ttl=True)`
660 Add an user to the UM module named 'name'. If `uid` is None, then an
661 UID is automatically chosen, otherwise the argument specify the UID
662 to use. The `password` if not None, specify the user password.
664 Return an User instance for the newly created account.
666 `addGroup(name, gid=None, password=None, ttl=True)`
668 Add an group to the UM module named 'name'. If `uid` is None, then an
669 GID is automatically chosen, otherwise the argument specify the GID
670 to use. The `password` if not None, specify the group password.
672 Return a Group instance for the newly created group.
678 The `uid` is the UID of an Unix user.
682 Remove all ACL entries on all objects whose subject is this user.
686 This dict-like attribute gives access to ACL entries for the
687 object. It's indexed by a subject (user, RC role or ACL group.)
693 A dict-like attribute which contains all user RC types.
695 There is also a module `objects.pseudoUsers` which contains predefined
696 `User` instance to represent pseudo users named `all_users` and
699 ==== Group class ====
703 The `gid` in the GID of an Unix group.
707 This dict-like attribute gives access to ACL entries for the
708 object. It's indexed by a subject (user, RC role or ACL group.)
714 A dict-like attribute which contains all group RC types.
716 There is also a module `objects.pseudoGroups` which contains
717 predefined `Group` instance to represent pseudo groups named
718 `all_groups` and `no_group`.
724 The `pid` is the PID of an Unix process.
728 This dict-like attribute gives access to ACL entries for the
729 object. It's indexed by a subject (user, RC role or ACL group.)
730 Note that it make sense only on the `defaultProcess` instance.
736 A dict-like attribute which contains all process RC types.
738 There is also a `defaultProcess` instance to represent the default
739 process (useful for the ACL entries.)
743 The following classes derive from the `objects.Ipc` class.
745 `class IpcSem(semid)`
747 A class to represent an IPC Semaphore with ID `semid`.
749 `class IpcMsg(msgid)`
751 A class to represent an IPC Message with ID `msgid`.
753 `class IpcShm(shmid)`
755 A class to represent an IPC Shared Memory with ID `shmid`.
757 `class IpcAnonPipe(inode)`
759 A class to represent an Anonymous pipe with inode `inode` (as created by `pipe(2)`.)
761 `class IpcMqueue(mqdes)`
763 A class to represent a POSIX message queues with descriptor `mqdes`
764 (as created by `mq_open(3)`.)
766 Note that it doesn't appear to be supported by RSBAC however!
768 `class IpcAnonUnix(inode)`
770 A class to represent an Anonymous Unix socket with inode `inode` (as
771 created by `socketpair(2)`)
777 A dict-like attribute which contains all IPC RC types.
783 The class `SCD` is not meant to be instantiated by the user. It is
784 already instantiated for all known system objects (System Control
785 Data) and these instances are availables in the module
786 `rsbac.objects.system` (see below.)
790 The RC type corresponding to the SCD object.
794 This dict-like attribute gives access to ACL entries for the
795 object. It's indexed by a subject (user, RC role or ACL group.)
801 A dict-like attribute which contains all SCD RC types.
803 There is also a `defaultScd` instance to represent the default SCD
806 --- SCD instances defined in objects.system ---
808 >>> dir(rsbac.objects.system)
809 ['__doc__', '__name__',
810 'capability', 'clock', 'firewall', 'host_id', 'ioports',
811 'kexec', 'kmem', 'ksyms', 'mlock', 'net_id', 'network',
812 'nfsd', 'none', 'other', 'priority', 'quota', 'rlimit',
813 'rsbac', 'rsbac_log', 'rsbac_remote_log', 'swap', 'sysctl',
814 'sysfs', 'syslog', 'time_strucs']
817 === Network device ===
819 `class NetworkDevice(name)`
821 The `name` is the network device name.
825 This dict-like attribute gives access to ACL entries for the
826 object. It's indexed by a subject (user, RC role or ACL group.)
832 A dict-like attribute which contains all network device RC types.
834 There is also a `defaultNetworkDevice` instance to represent the
835 default network device.
837 === Network template ===
839 `class NetworkTemplate(id)`
841 The `id` is the ID of the RSBAC network template.
845 This dict-like attribute gives access to ACL entries for the
846 object. It's indexed by a subject (user, RC role or ACL group.)
850 This dict-like attribute gives access to ACL entries for the template
851 itself (not to the object matched by the template.) It's indexed by a
852 subject (user, RC role or ACL group.)
854 FIXME: Choose another name for this attribute?
856 This class also contains specific attributes:
860 This read/write property is the name of the network
861 template. Setting the name of an undefined network template creates
866 This read/write property is a tuple `(address_family, addresses)`
867 where `address_family` is an integer as defined by the constants in
868 the standard module `socket` (such as `socket.AF_INET` and so on) and
869 `addresses` is a list of addresses (as string) specific to the
870 address family. To represent the IPv4 address `127.0.0.1` and the
871 IPv4 network `192.168.1.0/24`, this property can be set to
872 `(socket.AF_INET, ['127.0.0.1', '192.168.1.0/24'])`.
876 This read/write property is the type of socket to match by the
877 network template, as defined by the constants in the standard module
878 `socket` (such as `socket.SOCK_STREAM`, `socket.SOCK_DGRAM` and so
879 on). A value of 0 means any socket types.
883 This read/write property is the protocol to match by the network
884 template, as defined by the constants in the standard module `socket`
885 (such as `socket.IPPROTO_TCP`, `socket.IPPROTO_UDP` and so on). A
886 value of 0 means any protocols.
890 This read/write property is the name of a network device. If empty,
891 any network devices is matched.
895 This read/write property is a list of range of ports. A range of a
896 single port can be written as a single integer. To represent the
897 ports 1024 to 1099, plus the single port 1200, the property is
898 `[(1024,1099), 1200]`.
900 Methods for this class are:
904 Retrieve the ID of the network template if it is defined or throw an
905 exception of type `errors.Error` if not found.
909 Copy the network template to a new one with ID `target`. The target
910 network template can be an existing one.
914 Remove the network template from the RSBAC system.
916 A class method is provided to create new network templates:
920 Create a new network template of ID `id` named with the string
921 `name`. Return a `NetworkTemplate` instance for the newly created
928 A dict-like attribute which contains all network template RC types.
930 The module also provides a variable `networkTemplates` with a
931 dict-like interface to give access to all defined network templates. A
932 network template can be created with `networkTemplates[id]=name`,
933 since setting the name of an undefined network template automatically
936 === Network object ===
938 `class NetworkObject(..)`
940 This type is particular because it cannot really be instantiated from
941 the userland. The reason is that it refers to a structure which is
942 inside the kernel. See `objects.defaultNetworkObject` for the only
947 This dict-like attribute gives access to ACL entries for the
948 object. It's indexed by a subject (user, RC role or ACL group.)
950 There is however an instance `objects.defaultNetworkObject` to
951 represent the default network object.
957 A dict-like attribute which contains all network device RC types.
959 == Details about objects properties ==
961 The following properties are part of the classes described is the
964 === RSBAC attributes ===
966 All the classes used to represent a RSBAC object give access to the
967 set of RSBAC attributes for the corresponding object via
968 properties. Each of these properties is of a type specific to the
969 RSBAC attribute. The following table gives the name of the attributes,
970 the module concerned (for information purpose, but not needed
971 otherwise), the targets that own the attribute and the type as handled
972 by the rsbac package.
974 For example, to retrieve the RC type of the process of PID 1 you can
975 use `rsbac.objects.Process(1).rc_type`.
977 FIXME: Complete the following table.
979 | *Module* | *Attribute* | *Type* | *Target* |
980 | `GEN` | `audit_uid` | `objects.User` | `Process` |
981 | `GEN` | `auid_exempt` | `objects.User` | `FD`, `Process` |
982 | `AUTH` | `auth_last_auth` | `objects.User` | `Process` |
983 | `AUTH` | `auth_learn` | `bool` | `FD`, `Process` |
984 | `AUTH` | `auth_may_set_cap` | `bool` | `FD`, `Process` |
985 | `AUTH` | `auth_may_setuid` | `int` | `FD`, `Process` |
986 | `AUTH` | `auth_role` | `SystemRole` | `User` |
987 | `CAP` | `cap_ld_env` | `int` | `FD`, `Process`, `User` |
988 | `CAP` | `cap_process_hiding` | `int` | `Process` |
989 | `CAP` | `cap_role` | `SystemRole` | `User` |
990 | `MAC` | `current_sec_level` | | `Process` |
991 | `DAZ` | `daz_role` | | `User` |
992 | `DAZ` | `daz_scanned` | | `FD` |
993 | `DAZ` | `daz_scanner` | | `FD`, `Process` |
994 | `GEN` | `fake_root_uid` | `int` | `FD`, `Process` |
995 | `FF` | `ff_flags` | `FileFlags` | `FD` |
996 | `FF` | `ff_role` | `SystemRole` | `User` |
997 | `MAC` | `initial_security_level` | | `Process`, `User` |
998 | `JAIL` | `jail_flags` | `JailFlags` | `Process` |
999 | `JAIL` | `jail_id` | `int` | `Ipc`, `Process` |
1000 | `JAIL` | `jail_ip` | IP² | `Process` |
1001 | `JAIL` | `jail_max_caps` | `CapsFlags` | `Process` |
1002 | `JAIL` | `jail_parent` | `int` | `Process` |
1003 | `JAIL` | `jail_role` | `SystemRole` | `User` |
1004 | `JAIL` | `jail_scd_get` | `JailScdVector` | `Process` |
1005 | `JAIL` | `jail_scd_modify` | `JailScdVector` | `Process` |
1006 | `GEN` | `linux_dac_disable` | `int` | `FD` |
1007 | `GEN` | `local_log_array` | - | `NetworkObject` |
1008 | `MAC` | `local_mac_categories` | - | `NetworkObject` |
1009 | `PM` | `local_pm_ipc_purpose` | - | `NetworkObject` |
1010 | `PM` | `local_pm_object_class` | - | `NetworkObject` |
1011 | `PM` | `local_pm_object_type` | - | `NetworkObject` |
1012 | `RC` | `local_rc_type` | - | `NetworkObject` |
1013 | `MAC` | `local_sec_level` | - | `NetworkObject` |
1014 | `GEN` | `log_array` | `tuple`³ | `Device`, `FD`, `NetworkDevice`, `NetworkTemplate` |
1015 | `GEN` | `log_program_based` | `RequestVector` | `FD`, `Process` |
1016 | `GEN` | `log_user_based` | `RequestVector` | `User` |
1017 | `MAC` | `mac_auto` | | `FD`, `Process` |
1018 | `MAC` | `mac_categories` | | `Device`, `FD`, `Ipc`, `NetworkTemplate`, `Process`, `User` |
1019 | `MAC` | `mac_check` | | `Device` |
1020 | `MAC` | `mac_curr_categories` | | `Process` |
1021 | `MAC` | `mac_file_flags` | | `FD` |
1022 | `MAC` | `mac_initial_categories` | | `Process`, `User` |
1023 | `MAC` | `mac_min_categories` | | `Process`, `User` |
1024 | `MAC` | `mac_process_flags` | | `Process` |
1025 | `MAC` | `mac_prop_trusted` | | `FD` |
1026 | `MAC` | `mac_role` | | `User` |
1027 | `MAC` | `mac_user_flags` | | `User` |
1028 | `CAP` | `max_caps` | `CapsFlags` | `FD`, `User` |
1029 | `CAP` | `max_caps_program` | | `Process` |
1030 | `CAP` | `max_caps_user` | | `Process` |
1031 | `MAC` | `max_read_categories` | | `Process` |
1032 | `MAC` | `max_read_open` | | `Process` |
1033 | `CAP` | `min_caps` | `CapsFlags` | `FD`, `User` |
1034 | `MAC` | `min_security_level` | | `Process`, `User` |
1035 | `MAC` | `min_write_categories` | | `Process` |
1036 | `MAC` | `min_write_open` | | `Process` |
1037 | `PAX` | `pax_flags` | `PaxFlags` | `FD`, `Process` |
1038 | `PAX` | `pax_role` | `SystemRole` | `User` |
1039 | `PM` | `pm_current_task` | | `Process` |
1040 | `PM` | `pm_ipc_purpose` | | `Ipc`, `NetworkTemplate` |
1041 | `PM` | `pm_object_class` | | `Device`, `FD`, `Ipc`, `NetworkTemplate` |
1042 | `PM` | `pm_object_type` | | `Device`, `FD`, `Ipc`, `NetworkTemplate` |
1043 | `PM` | `pm_process_type` | | `Process` |
1044 | `PM` | `pm_role` | | `User` |
1045 | `PM` | `pm_task_set` | | `User` |
1046 | `PM` | `pm_tp` | | `FD`, `Process` |
1047 | `GEN` | `pseudo` | - | `User` |
1048 | `RC` | `rc_def_role` | `rc.Role` | `User` |
1049 | `RC` | `rc_force_role` | `rc.Role` | `FD`, `Process` |
1050 | `RC` | `rc_initial_role` | `rc.Role` | `FD` |
1051 | `RC` | `rc_role` | `rc.Role` | `Process` |
1052 | `RC` | `rc_select_type` | `rc.Type` | `Process` |
1053 | `RC` | `rc_type` | `rc.Type` | `Device`, `Group`, `Ipc`, `NetworkDevice`, `NetworkTemplate`, `Process`, `User` |
1054 | `RC` | `rc_type_fd` | `rc.Type` | `FD` |
1055 | `RC` | `rc_type_nt` | `rc.Type` | `NetworkTemplate` |
1056 | `GEN` | `remote_ip` | IP² | `Process` |
1057 | `GEN` | `remote_log_array` | - | `NetworkObject` |
1058 | `MAC` | `remote_mac_categories` | - | `NetworkObject` |
1059 | `PM` | `remote_pm_ipc_purpose` | - | `NetworkObject` |
1060 | `PM` | `remote_pm_object_class` | - | `NetworkObject` |
1061 | `PM` | `remote_pm_object_type` | - | `NetworkObject` |
1062 | `RC` | `remote_rc_type` | - | `NetworkObject` |
1063 | `MAC` | `remote_sec_level` | - | `NetworkObject` |
1064 | `RES` | `res_max` | `tuple`³ | `FD`, `User` |
1065 | `RES` | `res_min` | `tuple`³ | `FD`, `User` |
1066 | `RES` | `res_role` | `SystemRole` | `User` |
1067 | `MAC` | `security_level` | | `Device`, `FD`, `Ipc`, `NetworkTemplate`, `Process`, `User` |
1068 | `GEN` | `symlink_add_mac_level` | `bool` | `FD` |
1069 | `GEN` | `symlink_add_rc_role` | `bool` | `FD` |
1070 | `GEN` | `symlink_add_remote_ip` | `bool` | `FD` |
1071 | `GEN` | `symlink_add_uid` | `bool` | `FD` |
1075 * Note²: an IPv4 address represented by a tuple of 4 integers
1076 (between 0 and 255 inclusive.)
1078 * Note³: These tuples are subject to change in the future to a more
1079 convenient data type. Please refer to the RSBAC documentation in the
1080 meantime to figure the meaning of each items.
1082 * Note: The default network object doesn't have any
1083 attributes. Moreover, network object cannot be represented from
1084 userland. Thus, attributes for this target is not supported by the
1085 rsbac Python package.
1087 === rcTypes property ===
1089 This class attribute gives access to all the RC type which are
1090 specific to the corresponding objects. It's a dict-like object.
1092 For example, to obtain the RC Type 2 of the target FD, you could use
1093 `rsbac.objects.FD.rcTypes[2]`. It also works if you've an instance of
1094 the FD class in which case you could use
1095 `rsbac.objects.FD('/some/path').rcTypes[2]`, since `rcTypes` is a
1096 class attribute (not specific to an instance.)
1098 === acl property ===
1100 This dict-like attribute gives access to ACL entries for an object
1101 against a particular subject.
1103 The entries are represented by a couple `(requests,ttl)` where
1104 `requests` is of type `AclRequestVector` and `ttl` is as described in
1107 As a convenience, it is possible to the set the entry to just
1108 `request`, in which case an unlimited TTL is implied.
1110 For example, to obtain the ACL entry where:
1113 file = rsbac.objects.FD('/some/path')
1114 user = rsbac.objects.User(0)
1117 you simply use `file.acl[user]` to read and write the entry on FD
1118 object `/some/path` for the subject `User(0)` (the `root` user in this
1121 == User management ==
1123 RSBAC can optionnaly manage the Unix users and groups from inside the
1124 kernel (rather than relying on method such as the use of files
1125 `/etc/passwd` and `/etc/group`.) The `rsbac.um` package provides the
1126 API to manage these users and groups.
1128 Note that the class `um.User` is not the same as `objects.User`! The
1129 former is to manage settings related to the user as stored in RSBAC,
1130 while the latter is to manage behavior of an Unix user to a RSBAC
1131 system. FIXME: Not clear.
1133 The module also provides two dict-like variables named `users` and
1134 `groups`. They contain the list of users and groups currently
1141 Create an instance which represent the user with UID `uid`.
1147 Cast the instance to an integer which is the user's UID.
1151 This read/write property is the name of the user. It is the
1152 shortname, usually called the login name.
1156 This read/write property is the full user name. Only useful for some
1161 This read/write property is the hashed password of the user. This
1162 value is only useful for backup purpose, since it is not possible to
1163 deduce the clear password from it. And it is not recommended to set
1164 the hashed password by hand. Use the `password` property instead.
1168 This write-only property is the user password. Since the password is
1169 stored with a cryptographic hash, it is not possible to retrieve the
1170 original password from this property.
1174 This read/write property is the path to the user home directory.
1178 This read/write property is the path to the user shell.
1182 This read/write property is the GID of the main group for this user.
1183 It should not be confused with the `groups` attribute.
1187 This set-like attribute hold the set of extra groups to which the
1188 user belong. It should not be confused with the `group` property.
1192 This read-only property is True if the user exists and False
1197 This read-write property is the TTL (time to live) in seconds for
1200 Additionnaly, there is two methods:
1202 `updatePassword(old,new)`
1204 Update the user password the usual way. The `old` password should be
1205 the actual password, and the `new` password is the password to set.
1206 This method is available to the owner of the account, while the
1207 `password` property is only settable by a security officer.
1211 Remove the account from the UM configuration.
1217 Create an instance which represent the user with GID `gid`.
1223 Cast the instance to an integer which is the group's GID.
1227 This read/write property is the name of the group.
1231 This read/write property is the hashed password of the group. This
1232 value is only useful for backup purpose, since it is not possible to
1233 deduce the clear password from it. And it is not recommended to set
1234 the hashed password by hand. Use the `password` property instead.
1238 This write-only property is the group password. Since the password is
1239 stored with a cryptographic hash, it is not possible to retrieve the
1240 original password from this property.
1244 This read/write property is the TTL (time to live) in seconds for
1249 This read-only property is a tuple which contains the `um.User` which
1250 belong to this groups.
1254 This read-only property is a tuple which contains the `um.User` which
1255 have this group as an extra group.
1259 This read-only property is True if the group exists and False otherwise.
1261 Additionnaly, there is two methods:
1263 `updatePassword(old,new)`
1265 Update the group password the usual way. The `old` password should be
1266 the actual password, and the `new` password is the password to set.
1267 This method is available to the members of the group, while the
1268 `password` property is only settable by a security officer.
1272 Remove the group from the UM configuration.
1276 The module `rsbac.acl` allows to manage the ACL groups. There is a
1277 dict-like variable named `acl.groups` which contains all the existing
1280 ACL groups are represented with the following class:
1284 Create an instance to represent the ACL group with ID `id`.
1288 This read/write property is the name of the group.
1292 This TTL dict-like attribute give access to the members of the group.
1296 This read/write property is the owner of the group, represented by an
1297 `objects.User` instance.
1301 This read/write property is a boolean which indicate if the type is
1302 private (True) or global (False).
1304 The `rsbac.acl` module also provides some additionnal utility functions
1307 `grant(subject, object, requests)`
1309 Grant `requests` to the subject for the given object. The TTL is kept
1312 `revoke(subject, object, requests)`
1314 Revoke `requests` to the subject for the given object. The TTL is
1319 The module `rsbac.rc` allows to manage RC Roles and RC Types.
1325 This class is not meant to be instanciated by the user. Use the
1326 various `rcTypes` class attribute instead.
1332 Cast the RC Type to the corresponding type ID. (But note that a RC
1333 type is fully qualified by a couple `(target,id)`. So the value
1334 returned is not sufficient to uniquely identify the RC type.)
1338 This read/write property is the name of the RC type.
1342 This read/write property is a boolean which indicate if secure
1343 deletion is required for objects with this type. Note that secure
1344 deletion is not guaranteed to work with usual file systems. Be
1345 careful before trusting the behavior of this feature.
1349 Copy all the attribute of the RC type to another RC type (existing or
1354 Clone the RC type with an optional new name (otherwise the original
1355 name is also copied.) Returns the new RC Type.
1359 Delete the RC type from the RSBAC system. Basically it only means
1360 that the type become unnamed.
1366 Create an instance to represent the RC role with ID `id`.
1372 Cast the instance to the RC role ID.
1376 This read-only property is the ID of the RC role.
1380 This read/write property is the name of the RC role.
1384 This attribute is a TTL dict-like variable which gives access to the
1389 This attribute is a TTL dict-like variable which gives access to the
1390 list of RC roles that can administrate this RC role. FIXME.
1394 This attribute is a TTL dict-like variable which gives access to the
1395 list of RC roles that.. FIXME.
1399 This attribute is a dict-like variable which gives access to the
1400 permission for the RC role to a given RC type.
1402 `defaultIndividualFdCreateType`
1404 This attribute is a dict-like variable which gives access to the
1405 default RC type to use when creating object for a given RC type.
1409 This read/write property is a True if the RC role is a boot role and
1412 `requireReauthentication`
1414 This read/write property is a True if the RC role require to
1415 authenticate again when switching to another role (FIXME: or when
1416 switching to this RC role?) and False otherwise.
1420 This read/write property is the type of administrator for this RC
1421 role. It's one of the constant defined by RSBAC (0 for "No Admin", 1
1422 for "Role Admin", 2 for "System Admin").
1424 `defaultFdCreateType`
1426 `defaultUserCreateType`
1428 `defaultGroupCreateType`
1430 `defaultProcessCreateType`
1432 `defaultProcessChownType`
1434 `defaultProcessExecuteType`
1436 `defaultIpcCreateType`
1438 `defaultUnixsockCreateType`
1440 These eight attributes are dict-like variable which gives access to
1441 the corresponding RC type to use in the given context.
1445 Copy all the attribute of the RC role to another RC role (existing or
1450 Clone the RC role with an optional new name (otherwise the original
1451 name is also copied.) Returns the new RC Role.
1455 Remove the RC role from the RSBAC system.
1457 The `rsbac.rc` module also provides some additionnal utility functions
1460 `grant(role, type, requests)`
1462 Grant `requests` to the RC Role for the given RC Type. The TTL is
1465 `revoke(role, type, requests)`
1467 Revoke `requests` to the RC role for the given RC type. The TTL is
1470 `findUnnamedRole(start=0)`
1472 Search sequentially for a new unused RC role ID, starting from
1475 `findUnnamedRoles(n=1, start=0)`
1477 Search sequentially for a set of unused RC role ID up to `n` items,
1478 starting from `start`.
1480 `findRole(name,[default])`
1482 Find a role with the given name. If several roles share the same
1483 name, the one with the lowest ID is returned. If no roles is found,
1484 then default is returned if specified, otherwise an error of type
1485 `IndexError` is raised.
1487 `findUnnamedType(target,start=0)`
1489 Search sequentially for a new unused RC type ID, starting from
1492 `findUnnamedTypes(target,n=1, start=0)`
1494 Search sequentially for a set of unused RC type ID up to `n` items,
1495 starting from `start`.
1497 `findType(target,name,[default])`
1499 Find a type with the given name for the given target. If several
1500 types share the same name, the one with the lowest ID is returned. If
1501 no types is found, then default is returned if specified, otherwise
1502 an error of type `IndexError` is raised. See example section.
1504 `newRole(name, start=0)`
1506 Create a new RC role with the given name, whose ID is searched by
1507 starting from `start`.
1509 === Pseudo roles and types ===
1511 There are also predefined RC roles and RC types in the modules
1512 `rc.pseudoRoles` and `rc.pseudoTypes`:
1514 --- RC pseudo roles ---
1516 >>> dir( rsbac.rc.pseudoRoles )
1517 ['__doc__', '__name__',
1518 'inherit_parent', 'inherit_process',
1519 'inherit_up_mixed', 'inherit_user',
1521 >>> rsbac.rc.pseudoRoles.use_force_role
1522 <RC PseudoRole [-5] use_force_role>
1525 --- RC pseudo types ---
1527 >>> dir( rsbac.rc.pseudoTypes )
1528 ['__doc__', '__name__',
1529 'inherit_parent', 'inherit_process',
1530 'no_chown', 'no_create', 'no_execute',
1531 'use_fd', 'use_new_role_def_create']
1532 >>> rsbac.rc.pseudoTypes.use_fd
1533 <RC PseudoType [-7] use_fd>
1534 >>> rsbac.rc.findType( rsbac.objects.FD , 'foo' )
1535 <RC Type [14:99] 'foo'>
1536 >>> rsbac.rc.findType( rsbac.objects.FD , 'bar' )
1537 IndexError: Type named 'bar' not found
1540 All theses instances of `Role` and `Type` are singleton, meaning that
1541 you can compare them safely with the `is` operator.
1545 The module `rsbac.jail` contains a single function:
1547 `jail(path=None, ip=None, flags=None, max_caps=None, scd_get=None, scd_modify=None)`
1549 Every arguments are optional.
1551 `path` is the path to set the chroot environment. If None, then no
1552 chroot is performed.
1554 `ip` is either None or an IP address (as a string or a 4-tuple of
1555 integers). (FIXME: not implemented as described, the current jail
1556 function expect an integer.) If None, then no IP restriction is
1557 applied. Otherwise, the processes inside the jail can only bind to
1558 the specified IPv4 address.
1560 `flags` is a `JailFlags` instance (or equivalent integer.) If None,
1561 then all flags are cleared.
1563 `max_caps` is a `CapVector` instance (or equivalent integer.) If
1564 None, then all flags are cleared.
1566 `scd_get` and `scd_modify` are `ScdVector` instances (or equivalent
1567 integers.) If None, then all flags are cleared.
1569 The function returns the ID of the newly created jail.
1575 While testing, turn off softmode, but take care to turn on AUTH
1579 >>> rsbac.module.SOFTMODE
1580 <Module SOFTMODE [Enabled]>
1581 >>> rsbac.module.AUTH
1582 <Module AUTH [Enabled]>
1583 >>> rsbac.module.AUTH.softmode = True
1584 >>> rsbac.module.SOFTMODE.enabled = False
1585 >>> rsbac.module.SOFTMODE
1586 <Module SOFTMODE [Disabled]>
1587 >>> rsbac.module.AUTH
1588 <Module AUTH [Enabled,Softmode]>
1593 --- Starting the session ---
1595 >>> from rsbac import um
1598 --- We start with no users and no groups ---
1606 --- Add an user 'secoff' with UID 400 and password 'foobar' ---
1608 >>> secoff = um.addUser( 'secoff' , 400 , 'foobar' )
1609 >>> secoff.fullname = 'RSBAC security officer'
1611 <UM User [400] 'secoff'>
1613 {400: <UM User [400] 'secoff'>}
1616 --- Add a group 'secoff' with GID 400 and set it to the 'secoff' user ---
1618 >>> secoffGroup = um.addGroup( 'secoff' , 400 )
1619 >>> secoff.group = secoffGroup # or secoff.group = 400
1622 --- Add two test accounts 'foo' and 'bar' ---
1624 >>> foo = um.addUser( 'foo' )
1625 >>> bar = um.addUser( 'bar' )
1627 {400: <UM User [400] 'secoff'>, 2000: <UM User [2000] 'foo'>, 2001: <UM User [2001] 'bar'>}
1630 --- Add two test groups 'g1' and 'g2' ---
1632 >>> g1 = um.addGroup( 'g1' )
1633 >>> g2 = um.addGroup( 'g2' )
1636 --- Set group and extra groups ---
1640 >>> bar.groups.add( g1 )
1642 (<UM User [2000] 'foo'>,)
1644 (<UM User [2001] 'bar'>,)
1647 --- Change user TTL ---
1650 True # unlimited TTL
1651 >>> foo.ttl = 10 # set it to 10s
1654 <UM User [2000] (9s) 'foo'>
1657 <UM User [2000] (2s) 'foo'>
1660 <UM User [2000] (?) undefined>
1663 --- Remove the test accounts and test groups ---
1665 # foo already deleted because of the end of TTL
1670 <UM User [2000] (?) undefined>
1672 <UM Group [2000] (?) undefined>
1678 {400: <UM User [400] 'secoff'>}
1680 {400: <UM Group [400] 'secoff'>}
1686 >>> from rsbac import FileFlags
1687 >>> from rsbac.objects import Directory
1688 >>> Directory( '/tmp/foo' ).ff_flags
1689 FileFlags('add_inherited')
1690 >>> Directory( '/tmp/foo' ).eff_ff_flags
1691 FileFlags() # no effective flags
1692 >>> Directory( '/tmp/foo' ).ff_flags = FileFlags( 'no_delete_or_rename' )
1693 >>> Directory( '/tmp/foo' ).ff_flags
1694 FileFlags('no_delete_or_rename') # add_inherited was removed too
1695 >>> Directory( '/tmp/foo' ).eff_ff_flags
1696 FileFlags('no_delete_or_rename')
1701 To make it easier to figure what I set in RSBAC, I started to build a
1702 tool similar to `ls` and to `find`.
1705 # sec find /tmp --rc-type 17
1707 # sec ls -A --rc --ff /tmp/foo
1708 !17 !17 f -------I-->---------- ????-??-?? ??:?? bash
1709 0 m f ------N--->------N--- 0 2006-10-25 23:50 baz
1710 0 m f -------I-->---------- 8 2006-10-26 10:40 bla
1711 0 m f ------NI-->------N--- 0 2006-10-25 20:52 foo2
1712 0 m f -------I-->---------- 0 2006-10-26 10:40 ick
1715 The `--rc` and `--ff` specify which type of information to
1716 display. There is a flag for each RSBAC module that make sense for
1719 The `--rc` option display RC attributes, while `--ff` display FF
1720 attributes (file flags.)
1722 In the example above, the first 3 columns are the RC attributes:
1724 * The first column is the RC type of the file. A `!` mean that it is
1725 the real value, while no `!` mean that the value is inherited.
1727 * The second column is the RC forced type. Likewise, a `!` mean that
1728 it is the real value. For special role, an abbreviation is
1729 displayed. `m` is for mixed inheritance, `p` for process inheritance
1730 and `u` for user inheritance.
1732 * The third column is the RC initial type. The `f` mean to use the
1735 Then come a big column to represent the FF flags. The column has 2
1736 parts. The part before the `>` character is the real file flags, while
1737 the part after is the effective flags. Each flags is represented by a
1740 | *Letter* | *Flags* |
1741 | `r` | `read_only` |
1742 | `x` | `execute_only` |
1743 | `s` | `search_only` |
1744 | `w` | `write_only` |
1745 | `S` | `secure_delete` |
1746 | `X` | `no_execute` |
1747 | `N` | `no_delete_or_rename` |
1748 | `I` | `add_inherited` |
1749 | `a` | `append_only` |
1750 | `M` | `no_mount` |
1752 So, in the example, we can see that the `bla` file have no flags
1753 except `add_inherited`, and there is effective flags.
1755 FIXME: Choose only lower case letters, then represent inherited flag
1756 by an upper case, thus reducing the display of the file flags.
1760 * `errno` is retrieved directly from the `libc` through ctypes. It is
1761 not portable against another libc. See the `rsbac.platform` module.
1763 * MAC and PM supports are missing.
1765 * Lot of things are created on module import, which render loading
1766 the rsbac module rather slow (300ms on a 1GHz machine.)
1770 * Frédéric Jolliton ([pyrsbac@tuxee.net mailto:pyrsbac@tuxee.net])
projects / py-rsbac / blob