From 078d192b28d68967a28152db8815f66b7fd9212c Mon Sep 17 00:00:00 2001 From: LeChatP Date: Sat, 4 May 2024 10:04:40 +0200 Subject: [PATCH] Update Docs --- book/src/README.md | 38 ++-- book/src/SUMMARY.md | 8 +- book/src/chsr/README.md | 345 +-------------------------------- book/src/chsr/file-config.md | 337 ++++++++++++++++++++++++++++++++ book/src/guide/installation.md | 28 ++- 5 files changed, 402 insertions(+), 354 deletions(-) create mode 100644 book/src/chsr/file-config.md diff --git a/book/src/README.md b/book/src/README.md index 8e6d92d7..69714dbe 100644 --- a/book/src/README.md +++ b/book/src/README.md @@ -1,19 +1,33 @@ # Introduction -**RootAsRole** is a prject to allow Linux/Unix administrators to delegate their administrative tasks access rights to users. This tool allows you to configure your privilege access management more securely on a single operating system. +**RootAsRole** is a project to allow Linux/Unix administrators to delegate their administrative tasks access rights to users. Its main features are : -Unlike sudo, this project sets the principle least privilege on its core features. Like sudo, this project wants to be usable. More than sudo, we care about configurators, and we try to warn configurators about dangerous manipulations. - -By using a role-based access control model, this project allows us to better manage administrative tasks. With this project, you could distribute privileges and prevent them from escalating directly. Unlike sudo does, we don't want to give entire privileges for any insignificant administrative task. You can configure our tool easily with `chsr` command. To find out which capability is needed for a administrative command, we provide the `capable` command. With these two tools, administrators could respect the least privilege principle on their system. - -What we offer that sudo don't : -* [Linux Capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) support * [A structured access control model based on Roles](https://dl.acm.org/doi/10.1145/501978.501980) -* Command matching based on commonly-used open-source libraries + * [Role hierarchy](https://dl.acm.org/doi/10.1145/501978.501980) + * [Static/Dynamic Separation of Duties](https://dl.acm.org/doi/10.1145/501978.501980) +* [Linux Capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) support, to minimize the privileges of the user executing the command. + * Prevent the escalation of privileges via Bounding set manipulation. +* [Highly configurable](chsr/README.md) with a simple command line interface. This interface is designed to be as easy as `ip` command. + * File relocation ability. + * Multi-layered and inheritable execution environment configuration. + * Interoperable and evolvable by using [JSON](https://www.json.org/) as the main configuration file format. +* Command matching based on commonly-used open-source libraries: * [glob](https://docs.rs/glob/latest/glob/) for binary path * [PCRE2](https://www.pcre.org/) for command arguments -* Standardized file configuration with [JSON](https://www.json.org/) -* Separation of duties. -* Multi-layered configuration. -* A simple and easy-to-use configuration command line interface. + +## Usage + +The main command line tool is `sr`. It allows you to execute a command by simply typing: + +```bash +sr +``` + +You can find more information about this command in the [sr](sr/README.md) section. + +The `chsr` command allows you to configure the roles and capabilities of the system. You can find more information about this command in the [Configure RootAsRole](chsr/README.md) section. + +## Comparison with sudo + +By using a role-based access control model, this project allows us to better manage administrative tasks. With this project, you could distribute privileges and prevent them from escalating directly. Unlike sudo does, we don't want to give entire privileges for any insignificant administrative task. You can configure our tool easily with `chsr` command. To find out which capability is needed for a administrative command, we provide the `capable` command. With these two tools, administrators could configure its system to respect the least privilege principle. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 4a54aae6..8cb4e5ac 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -5,7 +5,9 @@ # User Guide - [Installation](guide/installation.md) -- [Configure RootAsRole](chsr/README.md) +- [`sr` Command Line Tool](sr/README.md) +- [`chsr` Command Line Tool](chsr/README.md) + # Knowledge Guide @@ -18,9 +20,7 @@ # Reference Guide -- [`sr` Command Line Tool](sr/README.md) -- [`chsr` Command Line Tool](chsr/README.md) - +- [Configure RootAsRole](chsr/file-config.md) - [Continuous Integration](continuous-integration.md) - [How to contribute](dev/CONTRIBUTE.md) - [Code of Conduct](dev/CODE_OF_CONDUCT.md) diff --git a/book/src/chsr/README.md b/book/src/chsr/README.md index 962134a0..f7a6ca46 100644 --- a/book/src/chsr/README.md +++ b/book/src/chsr/README.md @@ -1,342 +1,10 @@ # Chsr tool documentation -Chsr is a command-line tool to configure roles, permissions and execution options. - -## How does configuration work? - -The configuration is stored in a JSON file. The default path is `/etc/security/rootasrole.json`. It is possible to change the path where the configuration is stored by changing the `path` setting in the configuration file manually. -Note: The configuration file must be immutable after edition. -```json -"storage": { - "method": "json", - "settings": { - "path": "/etc/security/rootasrole.json", - "immutable": true - } -} -``` - -Next, the configuration is divided into roles, tasks, commands, credentials, and options. Each role can have multiple tasks, each task can have multiple commands and credentials. The options are global and can be set for the whole configuration or for a specific role or task. - -## How options work with examples - -### Path options example 1 - -Here is an example global configuration: - -```json -{ - "options": { - "path": { - "default": "delete-all", - "add": [ - "/usr/bin" - ] - } - } -} -``` - -This configuration will delete all paths and add `/usr/bin` to the whitelist. - -```json -{ - "options": { - "path": { - "default": "delete-all", - "add": [ - "/usr/bin" - ] - } - }, - "roles": { - "admin": { - "options": { - "path": { - "default": "inherit", - "add": [ - "/usr/sbin" - ] - } - } - } - } -} -``` - -This configuration will delete all paths and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin`. - -### Path options example 2 - -Here is an example global configuration: - -```json -{ - "options": { - "path": { - "default": "keep-safe", - "add": [ - "/usr/bin" - ] - } - } -} -``` - -This configuration will keep all paths that are absolute and add `/usr/bin` to the path. - -```json -{ - "options": { - "path": { - "default": "keep-safe", - "add": [ - "/usr/bin" - ] - } - }, - "roles": { - "admin": { - "options": { - "path": { - "default": "inherit", - "add": [ - "/usr/sbin" - ] - } - } - } - } -} -``` - -This configuration will keep all paths that are absolute and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin:$PATH`, where `$PATH` is the current executor path value. - -### Path options example 3 - -Here is an example global configuration: - -```json -{ - "options": { - "path": { - "default": "keep-unsafe", - "sub": [ - "/usr/bin" - ] - } - } -} -``` - -This configuration will keep all paths, even them that are relative, and remove `/usr/bin` from the path. - -```json -{ - "options": { - "path": { - "default": "keep-unsafe", - "add": [ - "/usr/bin" - ] - } - }, - "roles": { - "admin": { - "options": { - "path": { - "default": "inherit", - "add": [ - "/usr/sbin" - ] - } - } - } - } -} -``` - -This configuration will keep all paths, even them that are relative, and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin:$PATH`, where `$PATH` is the current executor path value. - -Note: path are always prepended to the current path value. - -### Path options example 4 - -Here is an example global configuration: - -```json -{ - "options": { - "path": { - "default": "inherit", - "add": [ - "/usr/bin" - ] - } - } -} -``` - -If the policy is inherit in global configuration, the policy will be `delete-all`. - -```json -{ - "options": { - "path": { - "default": "delete-all", - "add": [ - "/usr/bin" - ] - } - }, - "roles": { - "admin": { - "options": { - "path": { - "default": "keep-safe", - "sub": [ - "/usr/sbin" - ] - } - }, - "tasks": { - "task1": { - "options": { - "path": { - "default": "inherit", - "add": [ - "/usr/sbin" - ] - } - } - } - } - } - } -} -``` - -This complex configuration will delete-all paths in the global configuration for all roles except for `admin` role. The `admin` role will keep all paths that are absolute and remove `/usr/sbin` from the path. The `task1` task will inherit the `admin` role configuration and tries to add `/usr/sbin` to the path but it will be ignored because the task inherits the `admin` role configuration, and it removes `/usr/sbin` from the path. So the final path is the current executor path value less `/usr/sbin`. - -In conclusion, two logical properties can be deducted : -1. The path removed from the path variable cannot be added, even by inheritance. -2. When a more precise configuration defines a policy (delete-all,keep-safe,keep-unsafe), it will override less precise configuration. - * Global is less precise than Role, Role is less precise than Task - -### Environment options example 1 - -Here is an example global configuration: - -```json -{ - "options": { - "env": { - "default": "delete", - "keep": [ - "VAR1" - ] - } - } -} -``` - -Environment variables are managed in the same way as paths. The policy can be `delete`, `keep`, or `inherit`. The `delete` policy will remove all environment variables except the ones in the `keep` list. The `keep` list is a list of environment variables that will be kept in the environment. - -```json -{ - "options": { - "env": { - "default": "delete", - "keep": [ - "VAR1" - ] - } - }, - "roles": { - "admin": { - "options": { - "env": { - "default": "inherit", - "keep": [ - "VAR2" - ] - } - } - } - } -} -``` - -This configuration will delete all environment variables except `VAR1` for all roles. The `admin` role will inherit the global configuration and keep `VAR2` in the environment. So only `VAR1` and `VAR2` values will be kept in the environment for the `admin` role. - -### Environment options example 2 - -Here is an example global configuration: - -```json -{ - "options": { - "env": { - "default": "keep", - "delete": [ - "VAR1" - ] - } - } -} -``` - -The `delete` list is a list of environment variables that will be removed from the environment. - -```json -{ - "options": { - "env": { - "policy": "keep", - "delete": [ - "VAR1" - ] - } - }, - "roles": { - "admin": { - "options": { - "env": { - "policy": "inherit", - "delete": [ - "VAR2" - ] - } - } - } - } -} -``` - -This configuration will keep all environment variables except `VAR1` for all roles. The `admin` role will inherit the global configuration and remove `VAR2` from the environment. So only `VAR1` and `VAR2` values are removed from the environment for the `admin` role. - -### Environment options example 3 - -Here is an example global configuration: - -```json -{ - "options": { - "env": { - "default": "keep", - "check": [ - "VAR1" - ] - } - } -} -``` - -The `check` list is a list of environment variables that will be checked for unsafe characters. If an environment variable contains unsafe characters, it will be removed from the environment. +Chsr is a command-line tool to configure roles, permissions and execution options. If you want to know how the file configuration works, you can check the [file configuration](file-config.md) section. ## Usage -
+
 Usage: chsr [command] [options]
 
 Commands:
@@ -355,7 +23,10 @@ chsr role [role_name] [operation] [options]
   grant                         Grant permissions to a user or group.
   revoke                        Revoke permissions from a user or group.
     -u, --user [user_name]      Specify a user for grant or revoke operations.
-    -g, --group [group_names]   Specify one or more groups combinaison for grant or revoke operations.
+    -g, --group [nameA,...]     Specify one or more groups combinaison for grant or revoke operations.
+Example : chsr role roleA grant -u userA -g groupA,groupB -g groupC
+This command will grant roleA to "userA", "users that are in groupA AND groupB" and "groupC".
+
 
 
 Task Operations:
@@ -378,6 +49,8 @@ chsr role [role_name] task [task_name] command [cmd]
 chsr role [role_name] task [task_name] credentials [operation]
   show                          Show credentials.
   set, unset                    Set or unset credentials details.
+     --setuid [user]            Specify the user to set.
+     --setgid [group,...]       Specify groups to set.
   caps                          Manage capabilities for credentials.
 
 
@@ -429,4 +102,4 @@ chsr options timeout [operation]
     del [items,...]                        Remove items from the list.
     set [items,...]                        Set items in the list.
     purge                                  Remove all items from the list.
-

\ No newline at end of file
+
diff --git a/book/src/chsr/file-config.md b/book/src/chsr/file-config.md new file mode 100644 index 00000000..76bd3571 --- /dev/null +++ b/book/src/chsr/file-config.md @@ -0,0 +1,337 @@ +# How does configuration work? + +The configuration is stored in a JSON file. The default path is `/etc/security/rootasrole.json`. It is possible to change the path where the configuration is stored by changing the `path` setting in the configuration file manually. +Note: The configuration file must be immutable after edition. +```json +"storage": { + "method": "json", + "settings": { + "path": "/etc/security/rootasrole.json", + "immutable": true + } +} +``` + +Next, the configuration is divided into roles, tasks, commands, credentials, and options. Each role can have multiple tasks, each task can have multiple commands and credentials. The options are global and can be set for the whole configuration or for a specific role or task. + +## How configuration work with examples + +### Role example + + + +## How options work with examples + +### Path options example 1 + +Here is an example global configuration: + +```json +{ + "options": { + "path": { + "default": "delete-all", + "add": [ + "/usr/bin" + ] + } + } +} +``` + +This configuration will delete all paths and add `/usr/bin` to the whitelist. + +```json +{ + "options": { + "path": { + "default": "delete-all", + "add": [ + "/usr/bin" + ] + } + }, + "roles": { + "admin": { + "options": { + "path": { + "default": "inherit", + "add": [ + "/usr/sbin" + ] + } + } + } + } +} +``` + +This configuration will delete all paths and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin`. + +### Path options example 2 + +Here is an example global configuration: + +```json +{ + "options": { + "path": { + "default": "keep-safe", + "add": [ + "/usr/bin" + ] + } + } +} +``` + +This configuration will keep all paths that are absolute and add `/usr/bin` to the path. + +```json +{ + "options": { + "path": { + "default": "keep-safe", + "add": [ + "/usr/bin" + ] + } + }, + "roles": { + "admin": { + "options": { + "path": { + "default": "inherit", + "add": [ + "/usr/sbin" + ] + } + } + } + } +} +``` + +This configuration will keep all paths that are absolute and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin:$PATH`, where `$PATH` is the current executor path value. + +### Path options example 3 + +Here is an example global configuration: + +```json +{ + "options": { + "path": { + "default": "keep-unsafe", + "sub": [ + "/usr/bin" + ] + } + } +} +``` + +This configuration will keep all paths, even them that are relative, and remove `/usr/bin` from the path. + +```json +{ + "options": { + "path": { + "default": "keep-unsafe", + "add": [ + "/usr/bin" + ] + } + }, + "roles": { + "admin": { + "options": { + "path": { + "default": "inherit", + "add": [ + "/usr/sbin" + ] + } + } + } + } +} +``` + +This configuration will keep all paths, even them that are relative, and add `/usr/bin` to the whitelist for all roles. The `admin` role will inherit the global configuration and add `/usr/sbin` to the whitelist. So the final configuration for the `admin` role will be `/usr/bin:/usr/sbin:$PATH`, where `$PATH` is the current executor path value. + +Note: path are always prepended to the current path value. + +### Path options example 4 + +Here is an example global configuration: + +```json +{ + "options": { + "path": { + "default": "inherit", + "add": [ + "/usr/bin" + ] + } + } +} +``` + +If the policy is inherit in global configuration, the policy will be `delete-all`. + +```json +{ + "options": { + "path": { + "default": "delete-all", + "add": [ + "/usr/bin" + ] + } + }, + "roles": { + "admin": { + "options": { + "path": { + "default": "keep-safe", + "sub": [ + "/usr/sbin" + ] + } + }, + "tasks": { + "task1": { + "options": { + "path": { + "default": "inherit", + "add": [ + "/usr/sbin" + ] + } + } + } + } + } + } +} +``` + +This complex configuration will delete-all paths in the global configuration for all roles except for `admin` role. The `admin` role will keep all paths that are absolute and remove `/usr/sbin` from the path. The `task1` task will inherit the `admin` role configuration and tries to add `/usr/sbin` to the path but it will be ignored because the task inherits the `admin` role configuration, and it removes `/usr/sbin` from the path. So the final path is the current executor path value less `/usr/sbin`. + +In conclusion, two logical properties can be deducted : +1. The path removed from the path variable cannot be added, even by inheritance. +2. When a more precise configuration defines a policy (delete-all,keep-safe,keep-unsafe), it will override less precise configuration. + * Global is less precise than Role, Role is less precise than Task + +### Environment options example 1 + +Here is an example global configuration: + +```json +{ + "options": { + "env": { + "default": "delete", + "keep": [ + "VAR1" + ] + } + } +} +``` + +Environment variables are managed in the same way as paths. The policy can be `delete`, `keep`, or `inherit`. The `delete` policy will remove all environment variables except the ones in the `keep` list. The `keep` list is a list of environment variables that will be kept in the environment. + +```json +{ + "options": { + "env": { + "default": "delete", + "keep": [ + "VAR1" + ] + } + }, + "roles": { + "admin": { + "options": { + "env": { + "default": "inherit", + "keep": [ + "VAR2" + ] + } + } + } + } +} +``` + +This configuration will delete all environment variables except `VAR1` for all roles. The `admin` role will inherit the global configuration and keep `VAR2` in the environment. So only `VAR1` and `VAR2` values will be kept in the environment for the `admin` role. + +### Environment options example 2 + +Here is an example global configuration: + +```json +{ + "options": { + "env": { + "default": "keep", + "delete": [ + "VAR1" + ] + } + } +} +``` + +The `delete` list is a list of environment variables that will be removed from the environment. + +```json +{ + "options": { + "env": { + "policy": "keep", + "delete": [ + "VAR1" + ] + } + }, + "roles": { + "admin": { + "options": { + "env": { + "policy": "inherit", + "delete": [ + "VAR2" + ] + } + } + } + } +} +``` + +This configuration will keep all environment variables except `VAR1` for all roles. The `admin` role will inherit the global configuration and remove `VAR2` from the environment. So only `VAR1` and `VAR2` values are removed from the environment for the `admin` role. + +### Environment options example 3 + +Here is an example global configuration: + +```json +{ + "options": { + "env": { + "default": "keep", + "check": [ + "VAR1" + ] + } + } +} +``` + +The `check` list is a list of environment variables that will be checked for unsafe characters. If an environment variable contains unsafe characters, it will be removed from the environment. diff --git a/book/src/guide/installation.md b/book/src/guide/installation.md index 32628469..3eefa16f 100644 --- a/book/src/guide/installation.md +++ b/book/src/guide/installation.md @@ -12,5 +12,29 @@ Install git 1. sudo ./configure.sh 1. sudo make install -> [!WARNING] -> **This installation process gives by default the entire privileges set for the user which execute sudo. This means that the user which install this program will be privileged.** \ No newline at end of file +
+ +The installation process requires CAP_SETFCAP privileges and also grants full privileges to the user who installs, making them privileged by default. + +
+ +### What does the installation script do? + +The installation script does the following: +- dependencies.sh + - Installs Rust and Cargo + - Copy cargo binary to /usr/local/bin directory + - Create a link /usr/local/bin/cargo to /bin/cargo + - Installs `pkgconf openssl curl cargo-make gcc llvm clang libcap libcap-ng libelf libxml2 linux-headers linux-api-headers make` + - Installs `bpf-linker` tool for `capable` eBPF tool +- configure.sh + - Deploy `sr` PAM module to /etc/pam.d directory + - Deploy `rootasrole.json` to /etc/security directory + - Set immutable attribute to `rootasrole.json` file. Note : It requires a compatible filesystem like ext2/3/4, xfs, btrfs, reisefs, etc. + - Define the user who installs the project in a role which has all capabilities for all commands. +- Executes make install + - Compiles `sr`, `chsr` and `capable` binaries + - Deploy `sr`, `chsr` and `capable` binaries to /usr/bin directory + - Set user and group ownership of `sr`, `chsr` and `capable` binaries to root + - Set file access permissions of `sr`, `chsr` and `capable` binaries to `r-xr-xr-x` + - Set file capabilities of `sr`, `chsr` and `capable` binaries \ No newline at end of file