The RootAsRole project

by Eddie Billoir

This is the documentation for the RootAsRole project, including dosr, chsr, capable, and gensr, assuming that you want to use the latest version of the project. If you are looking for older versions, please refer to the github history of the project.

In this book, you’ll find CaRoot, our mascott! It’ll give advices all along you read the documentation.

Introduction

Cybersecurity threats are not just from outside. The major landscape of cybersecurity is undergoing a shift, with threats originating from within organizations’ trusted boundaries now posing a risk as significant as external attacks.

Yearly Data Breach Investigations Reports by Verizon state that “between 20 and 35% of breaches were caused by insiders” (e.g., employees, contractors, and other trusted individuals). Financial motives are frequently the root cause of these incidents, revealing that individuals granted excessive trust and access within an organization can abuse their privileges for personal reasons. This clearly emphasizes the significant role of internal threats in modern cyberattacks and the need to monitor and control privileged access to a system properly. Managing user privileges is particularly challenging due to modern networks and software components’ growing complexity and technological heterogeneity.

Some incidents illustrate the scale of these threats. For example, a former Ubiquiti cybersecurity engineer exploited administrative access to steal confidential data, extort money from the company, and significantly damage its reputation. Similarly, a former Chief Information Security Officer (CISO) of the Hospi Grand Ouest healthcare group in France orchestrated a cyberattack that compromised sensitive healthcare data. In March 2025, a former employee in Ohio was found guilty of installing a kill switch—a mechanism designed to destroy the infrastructure—in the event his privileged account was revoked. These cases, frequent in the news, underscore the urgent need for a targeted approach to securing administrative privileges, particularly in environments where the risk of abuse is high.

Company employees can have malicious intentions, but they can also, unbeknownst to them, become involuntary attackers. Current IT ecosystems are software supply chains, where an application depends on a long chain of other software modules developed and maintained by third parties. For instance, in the context of development environments, vulnerabilities in third-party code, such as VSCode extensions, can become attack vectors, undermining entire systems.

This internal threat is further amplified by the interconnected nature of modern software, which functions as a vast supply chain. A vulnerability concealed within a third-party library or a development tool can be exploited to compromise an entire infrastructure, turning even the most diligent administrator into an unwitting accomplice. The recent XZ incident or an innocent Visual Studio Code module is a potent reminder of this reality. Consequently, the focal point of risk converges on the concept of privileged access. The superuser accounts used by system administrators, by their very nature, offer almost unlimited control and thus represent the most fertile ground for exploitation, whether through malicious intent or unintentional error.

Faced with this challenge, cybersecurity has provided since the 1970s a clear theoretical answer: the Principle of Least Privilege (PoLP). Formulated by Saltzer and Schroeder, this principle is an engineering process that involves understanding users’ responsibilities to grant them only the minimum permissions required to accomplish their tasks using computer systems. This project focuses on a critical application of this doctrine, the Principle of Least Administrative Privilege (PoLAP), which concerns those administrators who manage and modify the system itself. In principle, the systematic application of PoLAP is already encompassed by PoLP. However, the position of Administrator is generally already an exception in the infrastructure design. Whereas it should be an exception, the reality shows in big companies that hundreds of administrators become Administrator of every new system installed, duplicating the risk considerably.

A significant gap persists between this principle and its practical implementation. On modern operating systems, particularly Linux, enforcing PoLAP is a task of considerable complexity. The administrator is confronted with a mosaic of disparate and overlapping security mechanisms: POSIX permissions, ACLs, Linux Capabilities, SELinux, AppArmor, and others. The attempt to configure these mechanisms coherently creates a daunting administrative burden. The typical response of adding a new security module often serves only to augment this complexity, failing to address the fundamental challenge of orchestrating all of these security mechanisms in a coherent policy.

The central premise is that the root cause of this failure is not technical, but lies in an incomplete methodology and a lack of consistency in the security mechanisms implemented. We postulate that a solution cannot be found by adding another layer of technology, but rather by adopting a new perspective—one that uses security models that acknowledge user needs for security. A security mechanism that is too complex, or doesn’t include user needs is, in effect, insecure. It is by examining the origins of our concepts of hierarchy, order, and control, and by placing usability at the center of the design, that we can hope to develop truly effective solutions.

It is from this perspective that we developed the RootAsRole (RaR) project. RaR is not presented as yet another security module to be added to the existing stack. Rather, it is conceived as a security orchestrator, in addition to being a better alternative to solutions found in the open-source community. As a performant, memory-safe, user-centric alternative to traditional tools like sudo, its purpose is to bring order and clarity to the existing complexity. It simplifies the management of fine-grained permissions and enables a pragmatic application of PoLAP through the Just-in-Time (JIT) elevation of privileges. RaR is thus the materialization of our approach: a pragmatic solution designed to make secure co-administration an achievable reality.[Billoir 2025]

Features

This section is currently under construction.

• A structured access control model based on Roles
  • Role hierarchy
  • Static/Dynamic Separation of Duties
• Linux Capabilities support
• Highly configurable
• Command matching with glob for binary path and PCRE2 for command arguments
• 🛠️ Configuration Helpers:
  • capable: Analyze command rights
  • gensr: Generate policy from Ansible playbooks

Compatibility

The Linux capabilities feature is available in kernel >= 4.3. So dosr tool is compatible with at least this version.

The eBPF compilation minimal features are available in kernel >= 5.0, so capable, gensr tools are compatible with at least this version.

Comparison with other tools

The sudo centralized policy feature relies on creating some LDAP entries that will be retrieved by sudo. This is somehwat not a conventional way to use LDAP. LDAP provides identity and directory information, but it does not evaluate authorization policies. So, scalability is a concern. Today, the preferred way is to use sudoers files with a configuration management tool like Ansible.

setcap is a tool to set capabilities on files, therefore comparing it with RaR or others is not relevant. We included it as many requested the comparison.

Installation

Install from Linux distributions

We really need your help to bring the project to Linux distributions repositories! Please contribute 🙏!

Arch Linux (AUR)

git clone https://aur.archlinux.org/dosr.git
cd dosr
makepkg -si

you can also use yay AUR manager or any other one you like. Please vote for the AUR if you want it into pacman extra repo! All you need is an Arch AUR account and you could vote for the AUR 🙂

Compile and install from source

This is a complete process for compiling and installing dosr and chsr binaries.

Prerequisites

• Linux system with PAM
• Rust toolchain
• Administrative rights (sudo or equivalent)

Retrieve the source code

git clone https://github.com/LeChatP/RootAsRole
cd RootAsRole

Configuring the fallback default behavior

Before installing the tool, you might want to set default behavior. You’ll find in .cargo/config.toml :

[env]
RAR_CFG_TYPE = "json"
RAR_CFG_PATH = "/etc/security/rootasrole.json"
RAR_CFG_DATA_PATH = "/etc/security/rootasrole.d/"
RAR_PAM_SERVICE = "dosr"
RAR_BIN_PATH = "/usr/bin"
RAR_CFG_IMMUTABLE = "true"
RAR_CHSR_EDITOR_PATH = "/usr/bin/vim"
RAR_TIMEOUT_TYPE = "ppid"
RAR_TIMEOUT_DURATION = "00:05:00"
RAR_TIMEOUT_MAX_USAGE = ""
RAR_PATH_DEFAULT = "delete"
RAR_PATH_ADD_LIST = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin"
RAR_PATH_REMOVE_LIST = ""
RAR_ENV_DEFAULT = "delete"
RAR_ENV_KEEP_LIST = "HOME,USER,LOGNAME,COLORS,DISPLAY,HOSTNAME,KRB5CCNAME,LS_COLORS,PS1,PS2,XAUTHORY,XAUTHORIZATION,XDG_CURRENT_DESKTOP"
RAR_ENV_CHECK_LIST = "COLORTERM,LANG,LANGUAGE,LC_.*,LINGUAS,TERM,TZ"
RAR_ENV_DELETE_LIST = "PS4,SHELLOPTS,PERLLIB,PERL5LIB,PERL5OPT,PYTHONINSPECT"
RAR_ENV_SET_LIST = ""
RAR_ENV_OVERRIDE_BEHAVIOR = "false"
RAR_AUTHENTICATION = "perform"
RAR_EXEC_INFO_DISPLAY = "hide"
RAR_USER_CONSIDERED = "user"
RAR_BOUNDING = "strict"
RAR_UMASK = "0022"
RAR_MAX_LOCKFILE_RETRIES = "10"
RAR_LOCKFILE_RETRY_INTERVAL = "1"
RAR_TIMEOUT_STORAGE = "/var/run/rar/ts"
RAR_WORKDIR_BEHAVIOR = "all"
RAR_WORKDIR_ADD_LIST = ""
RAR_WORKDIR_REMOVE_LIST = ""
#RAR_WORKDIR_FALLBACK = ""

These variables allows a customized compilation of the binary. With these variables you’ll be able to edit every behaviors, either hardcoded in the binary such as the root configuration file path, or the execution options when they aren’t defined at all in the policy.

Core Path & Configuration Storage Variables Reference

For security reasons, you'll have to set absolute paths.

Environment Variable Management

Malformed values strings create compile-time errors.

Execution Context & Workspace Controls

Be very careful with PATH management, "keep-unsafe" is insecure. And I strongly not reccommend it.

Working directory management is somewhat useful for some cases, such as allowing restricted commands only in a specific restricted directory. Of course that means that allowed commands shouldn't change internally the working directory. For example, if you set "/bin/ls" command, and setting fallback workdir to the "/tmp", then all "dosr ls" command will only show "/tmp" content, no matter where the user is located. Otherwise, if you set "/bin/ls .*" for the command, then the user still be able to retrieve folder contents everywhere on the system.

Security, Timeouts & Authentication

Showing to a user their policy can help attackers in their enumeration phase. A good policy knows what command a user is allowed to do in a such way that the user don't know that there is a strict policy applied.

Dependencies installation, compiling and installing

It might be trivial, but in order to install RootAsRole, you needs full administrative privileges. But only for specific cases when needed. Again, even here, we wants to apply PoLP. However, compiling a program will never need privileges. So managing unprivileged compilation and privileged installation is a bit tricky.

To manage that, we developed an installation helper tool

cargo xtask install -bip sudo

This command performs:

• dependency installation when required (privileged)
• project build
• deployment of dosr and chsr in RAR_BIN_PATH (privileged)
• capability/ownership setup for dosr (privileged)
• installation of PAM config for dosr with RAR_PAM_SERVICE name (privileged)
• installation of the configuration and policy with RAR_CFG_PATH and RAR_CFG_DATA_PATH paths (privileged)
• immutable flag setup on policy file when supported by the filesystem controlled with RAR_CFG_IMMUTABLE (privileged)

If you don't have sudo installed, you can use su, doas or please binaries. They should work as expected.

Your First Policy

In this chapter, we will build a minimal policy: allowing users in the ops group to reboot the host via dosr.

1. Create a Role

In RootAsRole, everything starts with a Role. A Role can be used to represent job operations, or a full procedure that some users are allowed to perform. The main idea here is to organize system administration into wellknown sets of actions, mastering your system’s operations.

Here, we create a role named ops and grant it to the system group of the same name:

chsr role ops add
chsr role ops grant -g ops

2. Define a Task

A single Role can encompass many different actions.To keep your system clean and granular, we break down Roles into Tasks. Let’s create a task specifically dedicated to rebooting the system:

chsr role ops task reboot add

Keep your tasks narrow! One operational action per task is the golden rule. If you find yourself naming a task 'manage_everything', you are accidentally recreating the 'root' user!

3. Define Execution Constraints

This is where we define what can be run and how it interacts with the system. The good practice is a whitelist approach to prevent arbitrary command execution.

3.1. Specify the Command

We must define which binary it is allowed to execute. We add the reboot command to our whitelist:

chsr role ops task reboot cmd whitelist add /usr/bin/reboot

You must write the absolute path to the command. This is a security measure to avoid command hijacking through PATH manipulation.

3.2. Configure the Execution Context

Since systemd requires the root UID, we must configure dosr to handle this securely:

# Set effective UID to root for this task
chsr r ops t reboot cred set --setuid root

# Disable all capabilities explicitly for a clean slate
chsr r ops t reboot cred caps setpolicy deny-all

# Lock the execution environment
chsr r ops t reboot o root user
chsr r ops t reboot o bounding strict

The commands are doing the following:

• cred set --setuid root: This sets the UID to root for the task.
• cred caps setpolicy deny-all: This denies all capabilities for the task.
• o root user: This enables flag on the kernel to consider the root user as a not privileged user, thus disabling the special treatment of the root user made by the kernel.
• o bounding strict: This enforces a strict bounding set of capabilities, further limiting the elevation of privileges.

In fact, The last 3 commands are not altering the configuration at all. Because RaR enforces already strict defaults, so, they were already set. But it is a good practice to explicitly set them, to avoid any misconfiguration by inheritance.

You might wonder why we need setuid if we have Linux Capabilities. Modern systems rely heavily on systemd. Unlike older tools that check for CAP_SYS_BOOT capability, systemd do a simple check: "Are you UID 0?". If you are not root, it denies the request, even if you technically have the capability.

5. Execution and Verification

Your policy is now ready! As a member of the ops group, you can now invoke the dosr engine:

dosr reboot

If a user has multiple roles or tasks that could match the command, dosr will attempt to resolve the conflict by choosing the least privileged option. However, when using dosr in automation (like Ansible), it is best to be explicit to ensure deterministic behavior:

dosr -r ops -t reboot reboot

dosr

dosr executes commands through RaR policy checks.

Usage

Execute privileged commands with a role-based access control system

Usage: dosr [OPTIONS] [COMMAND]...

Arguments:
  [COMMAND]...  Command to execute

Options:
  -r, --role <ROLE>  Role to select
  -t, --task <TASK>  Task to select (--role required)
  -u, --user <USER>  User to execute the command as
  -g, --group <GROUP<,GROUP...>> Group(s) to execute the command as
  -E, --preserve-env          Keep environment variables from the current process
  -D, --chdir <DIR>  Change working directory before executing the command
  -p, --prompt <PROMPT> Prompt to display
  -K                 Remove timestamp file
  -i, --info         Print the execution context of a command if allowed by a matching task
  -h, --help         Print help (see more with '--help')
  -V, --version      Print version

If you’re accustomed to utilizing the sudo tool and find it difficult to break that habit, consider creating an alias :

alias sudo="dosr"
alias sr="dosr"

Future Design Considerations

Today, we copied completely the CLI of sudo, thus ensuring old scripts compatibility.

We might following a new design in the future but with retro-compatibility enabled. For example, we could detect when the command name is sudo then using the sudo CLI design, otherwise fallback to a new design.

Examples

dosr reboot
dosr -r ops -t reboot reboot

Performance Evaluation and Optimisation

Infrastructure-as-code environments can generate large and complex privilege policies. Tools such as Ansible rely heavily on privilege escalation through become: true.

With RaR policies, every role and task can introduce additional access control rules. In large infrastructures, this can result in thousands of policy entries being evaluated during production operations. Therefore, the privilege evaluation engine must scale efficiently.

The initial implementation of dosr revealed a scalability challenge. The first JSON-based policy engine was faster than sudo for small policies, but its execution time increased significantly as the number of tasks grew.

As shown above, the initial implementation suffered from poor scalability. While it performed well with small policies, the execution time quickly surpassed sudo as policy size increased, making it unsuitable for large-scale deployments.

Moving from JSON to CBOR

The first optimization focused on the policy storage format. JSON is human-readable and convenient, but parsing large JSON documents introduces unnecessary overhead. To reduce this cost, dosr introduced support for Compact Binary Object Representation (CBOR), a binary format designed for efficient serialization and parsing, and completely compatible with the JSON structure.

Although CBOR reduced part of the parsing overhead, the improvement remained limited. The performance curve continued to increase significantly with policy size, demonstrating that file parsing was only one part of the problem. The main bottleneck was located deeper in the policy evaluation architecture.

Architectural Optimisation

The next optimization phase focused on the complete execution path of dosr. Instead of only improving the policy format, the internal architecture was redesigned to remove unnecessary overhead.

The main improvements included:

• reducing redundant memory allocations;
• improving internal data structures;
• streamlining policy loading and evaluation;
• optimizing rule matching and execution paths.

These changes, combined with the CBOR policy format, resulted in a significant improvement in both execution time and scalability.

The optimized dosr engine now outperforms sudo by up to 77% for a single-rule policy. More importantly, its execution time scales linearly and grows approximately 40% slower than sudo, maintaining a performance advantage even with policies containing tens of thousands of tasks.

Do you see these very straight lines compared to the previous ones? This is because we changed the way to way to plot the data. Instead of using a some arbitrary increase (e.g., 100, 200, 300), we used a logarithmic increase.

Large-Scale Automation

This scalability improvement is particularly important in automation environments.

Tools such as Ansible frequently invoke privilege escalation through become: true configuration option. With RaR, every role and task can introduce additional access control rules, potentially resulting in thousands of policy entries on a single system.

The benchmark results show that this additional security granularity does not introduce a proportional performance cost. The optimized dosr engine can reach the execution time of a single sudo rule while evaluating approximately 4,000 RaR rules.

This enables administrators to define significantly more precise privilege policies while maintaining operational efficiency.

Comparison with sudo-rs

For comparison, sudo-rs provides performance comparable to sudo in standard scenarios. However, its implementation shows a hardcoded limit of 100 rules.

Future Improvements

One potential direction is the integration of a SQLite-based policy backend. The RBAC model of RaR map to relational data structures. A relational database could provide additional advantages as we could do efficient indexing as an example.

The benchmarks presented above were performed in July 2025. Since then, additional performance optimisations have been implemented across the codebase, improving internal execution paths and reducing overhead further. [Billoir 2025]

chsr

This section needs rewriting.

chsr is the policy administration tool for RaR.

Use it to manage roles, tasks, command rules, credentials, and options.

Usage

chsr [COMMAND] [ARGS...]

Main command families

• role: create/delete roles, grant/revoke actors
• role ... task: create/delete tasks
• role ... task ... cmd: manage command allow/deny rules
• role ... task ... cred: manage setuid, setgid, and capabilities
• options: manage global/role/task execution options
• convert: convert policy storage between JSON and CBOR
• editor: open interactive editor mode (when enabled)

chsr editor

chsr editor opens an interactive policy editing mode.

When the edit session is applied, RaR validates the policy before saving. Invalid content is rejected with explicit errors.

Use chsr editor for multi-field edits when you want immediate validation.

For policy field reference, see Configuration File Format. For storage migration, see File Format Conversion.

Common examples

chsr role ops add
chsr role ops grant -g ops
chsr role ops task reboot add
chsr role ops task reboot cmd whitelist add reboot
chsr role ops task reboot cred caps whitelist add CAP_SYS_BOOT

For complete policy fields, see Configuration File Format.

capable

This section needs rewriting.

capable is a helper utility used during policy design and testing.

It observes capability requests made by a command and helps build a minimal capability allow-list.

Usage

capable [OPTIONS] [COMMAND]...

Options

• -s, --sleep <SLEEP>: wait before stopping traced process
• -d, --daemon: collect system events and print at end
• -j, --json: output JSON
• -h, --help: help

Example

capable -j cat /etc/shadow

Operational guidance

• Treat output as candidate capabilities, not final policy.
• Remove capabilities that are not strictly required.
• Validate with real-world command execution after each reduction.
• Do not rely on capable output alone for production hardening.

Policy Model and Inheritance

This section needs update.

RootAsRole policy is built on three levels:

1. Global options
2. Role options
3. Task options

A user executes a command through a matching task.

Core objects

• Role: assignment boundary for users and groups.
• Task: command pattern + execution rights.
• Credentials: setuid, setgid, and Linux capabilities.
• Options: environment, PATH, authentication, timeout, and related controls.

Matching behavior

dosr evaluates candidate tasks and selects the best match.

Selection is based on:

• Command/path and arguments match quality
• Actor match (user/group)
• Optional filters (-r, -t, -u, -g, -E)
• Least-privilege preference when candidates are equivalent

If two candidates remain ambiguous, execution is denied until policy is clarified. In operations, this is preferable to silently picking a risky path.

Inheritance behavior

Options are resolved from global to role to task.

• If a level is inherit, parent level is used.
• If a level is explicit, it overrides parent level.

This lets you keep broad defaults while tightening sensitive tasks.

Enforcing the Fail-safe default principle by Saltzer & Scroeder also implies enforcing the most strict security options at the top-level of the configuration and overriding only at the lowest according to needs!

Configuration File Format

This section needs rewriting.

This page documents the RaR policy file, usually /etc/security/rootasrole.json.

Use chsr for routine edits. Keep manual JSON editing for advanced workflows and reviewed changes.

1) Top-level structure

{
  "version": "4.0.0",
  "storage": {
    "method": "json",
    "settings": {
      "path": "/etc/security/rootasrole.json",
      "immutable": true
    }
  },
  "options": {},
  "roles": []
}

• version: policy schema version written by tooling.
• storage: where policy data is stored (json or cbor, with reconfiguration).
• options: global execution options (inherited by roles/tasks unless overridden).
• roles: list of role definitions.

2) Minimal working role example

{
  "version": "4.0.0",
  "roles": [
    {
      "name": "ops",
      "actors": [
        { "type": "group", "name": "ops" }
      ],
      "tasks": [
        {
          "name": "reboot",
          "purpose": "Allow reboot",
          "cred": {
            "capabilities": ["CAP_SYS_BOOT"]
          },
          "commands": ["/usr/sbin/reboot"]
        }
      ]
    }
  ]
}

3) Role and task model

• A role contains:
  • name
  • actors (users/groups allowed to use it)
  • tasks
  • optional options
• A task contains:
  • name
  • optional purpose
  • cred (execution credentials)
  • commands (allowed command patterns)
  • optional options

4) Command model

commands supports 3 compact forms:

1. String policy:

"commands": "all"

2. Explicit allow-list:

"commands": ["/usr/bin/systemctl restart sshd"]

3. Full object:

"commands": {
  "default": "none",
  "add": ["/usr/bin/systemctl restart sshd"],
  "del": ["/usr/bin/systemctl reboot"]
}

Supported default values are all and none.

5) Credential model (cred)

Main fields:

• setuid
• setgid
• capabilities

capabilities accepted forms

"capabilities": "all"

"capabilities": ["CAP_NET_BIND_SERVICE", "CAP_SYS_BOOT"]

"capabilities": {
  "default": "none",
  "add": ["CAP_SYS_BOOT"],
  "del": ["CAP_SYS_ADMIN"]
}

setuid selector form

"setuid": {
  "default": "none",
  "fallback": "root",
  "add": ["root"],
  "del": ["nobody"]
}

setgid selector form

"setgid": {
  "default": "none",
  "fallback": ["root"],
  "add": [["wheel"]],
  "del": [["nogroup"]]
}

setuid/setgid can also be written in compact mandatory form (single user/group or group list).

6) Options and inheritance

options can be declared at:

1. global level
2. role level
3. task level

Resolution is hierarchical: task overrides role, role overrides global. inherit means “use parent level”.

Important option families:

• path: execution PATH filtering/override policy
• env: environment policy (keep/delete/check/set with inheritance)
• root: user or privileged
• bounding: strict or ignore
• authentication: perform or skip
• execinfo: show or hide
• timeout: { type, duration, max_usage }
• umask: octal string (example: "022")

7) Plugins and extra fields

RaR supports extension fields (for example role hierarchy or separation-of-duty metadata) and command plugin objects (for example hash-check metadata).

These fields are preserved by the policy model and consumed by relevant tooling/plugins.

8) dbus and file credential fields

dbus and file entries are primarily used by gensr-driven workflows to materialize DBus/Polkit and file-permission enforcement artifacts.

They represent discovered execution requirements and are useful in IaC/security automation pipelines.

9) Recommended workflow

1. Initialize/modify policy with chsr.
2. For multi-field edits, prefer chsr editor so invalid policies are rejected before write.
3. Validate expected execution with dosr -i ....
4. Convert storage format with chsr convert only when required.
5. Keep policy in version control and review changes like code.

See also:

• chsr command overview
• File Format Conversion

File Format Conversion

This section needs rewriting.

chsr convert converts RootAsRole policy storage between JSON and CBOR.

Supported formats

• json
• cbor

Command forms

chsr convert [--from <from_type> <from_file>] <to_type> <to_file>
chsr convert -r [--from <from_type> <from_file>] <to_type> <to_file>

• --from: explicitly select source format and source file.
• -r / --reconfigure: update /etc/security/rootasrole.json so storage points to the new file.

Common examples

Convert current policy storage to CBOR and reconfigure runtime:

chsr convert -r cbor /etc/security/rootasrole.bin

Convert back to JSON and reconfigure runtime:

chsr convert -r json /etc/security/rootasrole.json

Explicit source/target conversion:

chsr convert --from json /etc/security/rootasrole.json cbor /etc/security/rootasrole.bin

Operational notes

• Keep target files in protected system paths.
• If policy content changes during migration prep, prefer chsr editor to catch invalid policies before write.
• Validate policy execution after conversion with dosr -i <command>.
• Use version control and backups before large migrations.

For policy field details, see Configuration File Format.

Architecture Overview

Binaries

• dosr: policy lookup, authentication flow, and command execution uner a restricted context.
• chsr: policy editing and conversion interface.
• capable: policy discovery, available in its own repository.
• gensr: fully automated policy generation, available in its own repository

Internal crates

• rar-common: shared policy model, storage handling, migrations, utility logic.
• rar-exec: execution pipeline primitives (runner, terminal/pty, pipe, signals).

Did you know that there are two approaches for secure execution?

• The openBSD one is about calling execve() directly for minimal code implementation. Less features, more robust is the software.
• The sudo one is about adding a intermediary process in order to oversee the communication between user and privileged process.

The version 4.0 of RaR is switching from the first to second design! We believe that the risk taken by implementation error is worth the security feature to protect against innapropriate user inputs.

Security Model

This section needs rewriting.

A software security model is a conceptual framework that defines the rules, boundaries, and access controls a system must follow to protect its data and resources from unauthorized use or tampering.

In the RaR context, it describes the security mechanisms that secures the program from its own usage.

Security controls

• PAM-based authentication for dosr
• Capability-oriented privilege model
• Optional timestamp/timeout behavior
• Immutable policy file workflow
• Hardened policy editor path in chsr editor (landlock/seccomp)

Operational safeguards

• Grant only required capabilities.
• Prefer explicit command allow-lists.
• Use dedicated roles for automation.
• Force explicit role/task selection in scripts.
• Review and test policy changes before deployment.

Typical risks

• Over-broad command patterns
• Unnecessary capability grants
• Ambiguous task overlap
• Reusing interactive roles for unattended jobs

Minimal hardening checklist

1. Keep /etc/security/rootasrole.json protected and immutable in production.
2. Restrict chsr usage to a small admin set :

• Implement review processes for policy changes.
• Implement segregation of duties for policy management and execution.

3. Use dosr -i during policy validation (requires to allow dosr -i in policy for testing).
4. Add CI checks for policy syntax and expected command paths.
5. Track policy changes in version control.

Research & Publications

• PhD Thesis (2025): Orchestrating and enforcing the principle of least administrative privileges in Linux systems — E. Billoir
• Conference (2025): No Root, No Problem: Automating Linux Least Privilege and Securing Ansible Deployments — ESORICS 2025
• Conference (2024): Enhancing Secure Deployment with Ansible: A Focus on Least Privilege and Automation for Linux — ARES 2024
• Journal Article (2024): Implementing the Principle of Least Administrative Privilege on Operating Systems: Challenges and Perspectives — Annals of Telecommunications
• Conference (2023): Implementing the Principle of Least Privilege Using Linux Capabilities: Challenges and Perspectives — CSNet 2023
• Journal Article (2022): RootAsRole: a security module to manage the administrative privileges for Linux — Computers & Security
• Conference (2021): RootAsRole: Towards a Secure Alternative to sudo/su Commands for Home Users and SME Administrators — SACMAT 2021

FAQ

Why not cargo install rootasrole?

cargo install targets user-local binaries. dosr requires system-level deployment (PAM files, capabilities, policy file location/permissions). For that reason, use distro packages or the project installer flow.

capable does not work on my host

capable depends on eBPF and kernel features that are not always available or enabled.

Check:

• kernel support for required eBPF features
• security profile restrictions in your environment
• memory/resource limits

If it still fails, open an issue with kernel version, distro, and reproducible steps.

Why are capable results different from expected behavior?

Possible causes:

1. Access is granted by normal ACL/ownership, so no capability is needed.
2. Program exits before capability checks happen.
3. Program behavior changes based on UID/GID.

Treat output as a starting point for iterative testing, not final ground truth.

Why does chsr editor refuse to save my changes?

chsr editor validates policy consistency before writing.

Typical causes are:

• invalid field type (for example string vs object)
• unsupported values in command/capability sets
• broken inheritance/option structure

Review the reported error, fix the corresponding field, and retry. For schema examples, see Configuration File Format.

Why does chsr convert fail?

Common causes:

• source path is wrong or unreadable
• target path is not writable
• --from format does not match the actual source content

Retry with explicit --from and verify file permissions. See File Format Conversion for command forms.

Is a Linux system without a root user possible?

Short answer: not really.

Practical answer: you can design operations so daily work does not require logging in as root. That is exactly the RootAsRole objective with Linux capabilities.

Example: preparing Apache management without root processes.

First, create the service account:

dosr adduser apache2

Then create a task to install Apache with that account:

dosr chsr r r_root t install_apache2 add
dosr chsr r r_root t install_apache2 cmd whitelist add /usr/sbin/apt install apache2
dosr chsr r r_root t install_apache2 cmd whitelist add "/usr/sbin/apt ^upgrade( -y)? apache2$"
dosr chsr r r_root t install_apache2 cred set --caps CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_NET_BIND_SERVICE,CAP_SETUID --setuid apache2 --setgid apache2

Add another task to start/stop Apache:

dosr chsr r r_root t start_apache2 add
dosr chsr r r_root t start_apache2 cmd whitelist add "/usr/sbin/systemctl ^((re)?start|stop) apache2$"
dosr chsr r r_root t start_apache2 cmd whitelist add "/usr/bin/service ^apache2 ((re)?start|stop)$"
dosr chsr r r_root t install_apache2 cred set --caps CAP_NET_BIND_SERVICE,CAP_SETUID --setuid apache2 --setgid apache2

Now installation can be delegated through policy:

dosr apt install apache2

Then service control can also run through delegated tasks:

dosr systemctl start apache2

What is eBPF?

An eBPF program is a kernel-based virtual machine that allows the execution of user-defined bytecode in a secure and high-performance manner. Kprobe is a kernel debugging mechanism that enables the attachment of our eBPF program to the cap_capable kernel function entry point, which provides a dynamic way to trace and monitor Linux capabilities requests. [Sharaf et al. 2022] [Billoir 2025]

In RaR, eBPF is used by capable to observe capability checks during command execution. Therefore, it can determine the effective requested capabilities of a command. However, that does not mean that the command needs these capabilities to run. Or even mean that the command is requesting all possible capabilities of its use-case.

Even if we used to analyse the source code of a command to try finding the capabilities it needs, it is not a reliable method. This is for two main reasons:

1. The privileges are requested given the context of the execution. For example, ls command does not need any capabilities to run but if you want to show the content of a folder that is not accessible by the user, then it needs CAP_DAC_READ_SEARCH to bypass the access control.
2. The capabilities requests are only made inside the kernel. So reading the source code does not give any direct information about the capabilities that might request a program. Again, if you read the source code of ls, you will not find any explicit request for CAP_DAC_READ_SEARCH capaibility.

There are other purely practical reasons such as the fact that some progams are closed-source, but that is not a real issue, while annoying.

Linux capabilities

Linux implements a fine-grained privilege model through capabilities [Miller et al. 2003] (known as capability module), which partition the comprehensive power of the superuser (root) into distinct, manageable units. This mechanism allows specific privileges to be delegated to processes on an as-needed basis, obviating the requirement for them to operate with full root permissions. This design philosophy enhances system security by adhering to PoLP.

The concept was originally derived from the IEEE POSIX 1003.1e draft standard [IEEE and The Open Group 2024], [Security Working Group 1997]. Although this draft was ultimately withdrawn, its concepts were adopted and have since been independently maintained and significantly enhanced by the Linux kernel development community. The result is a LSM for defining discrete and mandatory access control policy for privileges on a per-thread basis. [Wazan et al. 2022] [Billoir et al. 2023] [Billoir et al. 2024]

In other terms, Linux capabilities switch from an Identity based access control with the root user to a set of privileges that can be granted to processes. It is an interesting features as long it allows to rely on a new mechanism to create organisational policies, such as Roles. This is where all started with this project.

For kernel-level capability documentation, see capabilities(7).

The RBAC model and access control model history

PoLP has its first implementation in access control theory, by managing the interaction (e.g., read, write) between subjects (e.g., users, processes) and objects (e.g., files, databases) within a system referred to as the SOA (Subject, Object, Action) matrix [Lampson 1974],[Sandhu & Samarati 1994]. This matrix was both resource-intensive for humans and computationally demanding to fully implement, as it required exhaustive enumeration and continuous maintenance of all possible subject-object-action combinations within the system. The resulting complexity is \(O(n_s \cdot n_o \cdot n_a)\), where \(n_s\), \(n_o\), and \(n_a\) represent the number of subjects, objects, and actions, respectively, just to define the matrix.

The sudo policy model is describing one line per subject, object and action. While we can use wildcards and aliases to reduce the number of lines, it is still a model that lacks of organisational means to manage it. In other words, sudo is not implementing any access control model.

Then, We are skipping the history of access control models. But to make it short, many engineering-focused access control models have been proposed to solve purely technical problems, such as the Object Capability Model for solving the Confused Deputy problem (or a Runtime Safety problem).

Now, I’ll dive a bit into the Role-Based Access Control (RBAC) model. Role-based access control (RBAC) is an access control model that assigns permissions to roles rather than directly to individual users [Sandhu et al. 1995]. Permissions are the foundation of the model, defining the allowed interactions within the system. These permissions are not assigned directly to individuals. Instead, a Permission Assignment links them to a new entity called Role. A role is a logical grouping of permissions that corresponds to a specific job function or authority level within an organization (e.g., System Administrator or Guest User). By being assigned to a role, they inherit all the permissions associated with it, enabling them to perform their designated tasks. Finally, the model introduces Sessions. A User Session is an active connection between a user and the system. During a session, a user can activate one or more of their assigned roles, and the system uses a Role Session to grant them the corresponding permissions. This allows users to operate under different roles for different tasks within the same login.

This model is particularly useful and highly representing how our society is organized. If you want to learn more about it, you can read the PhD thesis [Billoir 2025] at section 1.2.5 where it makes a link with bees, ants as an example.

RootAsRole uses a RBAC model because admin delegation is first an assignment organisational problem. [Billoir 2025], [Sandhu et al. 1996], [Ferraiolo et al. 2001], [Wazan et al. 2021],[Wazan et al. 2022], [Billoir et al. 2023]

Separation of duties

This section needs rewriting.

Separation of duties (SoD) is essential for administrative privilege governance in RBAC systems [Ferraiolo et al. 2001] [Kuhn 1997].

Static Separation of Duties (SSD)

SSD prevents users from holding conflicting roles at assignment time.

In RootAsRole, SSD is supported through role-level exclusions (ssd array). Use it for high-impact role pairs (for example operations vs audit).

Dynamic Separation of Duties (DSD)

DSD prevents conflicting role activation in the same session or runtime context [Kuhn 1997].

RootAsRole currently focuses on SSD. If your workflow needs DSD-like guarantees, design role/task boundaries so sensitive combinations are structurally impossible, and keep execution review strict.

Command matching

A command entry in RootAsRole has two parts: command path and command arguments.

The command path is the executable path. It can be exact (for example /usr/bin/ls) or wildcarded (for example /usr/bin/*). A complete wildcard (**) is possible but usually too permissive.

Arguments can be:

• a regular expression that starts with ^ and ends with $ so the full argument string is matched (for example ^-l( -a)?$ matches -l or -l -a, but not -a -l),
• an exact space-separated argument list.

RaR distinguishes ^.*$ from a constrained regex such as ^reg.*ex$: the first means “any arguments”, the second is more specific. That specificity matters during conflict resolution.

Role Conflict resolution

With RBAC, multiple roles can match the same command for the same actor. Because role selection is implicit by default, RaR applies a deterministic least-privilege policy and a partial-order comparison [Abedin et al. 2006] to select a candidate.

If multiple tasks match a command, RaR automatically:

1. chooses the most specific match,
2. if still ambiguous, selects the least-privileged one,
3. and only requires the user for clarification (using options in cli) if ambiguity remains.

When ambiguity remains, it is usually a policy design smell and worth refactoring.

Contributing to RootAsRole

First off, thanks for taking the time to contribute! ❤️

All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉

And if you like the project, but just don’t have time to contribute, that’s fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:

• Star the project
• Use dosr in your daily work
• Document your scripts with dosr usage
• Mention the project at local meetups and tell your friends/colleagues

Table of Contents

• Code of Conduct
• I Have a Question
• I Want To Contribute
• Reporting Bugs
• Suggesting Enhancements
• Your First Code Contribution
• Improving The Documentation
• Styleguides
• Commit Messages
• Join The Project Team

Code of Conduct

This project and everyone participating in it is governed by the RootAsRole Code of Conduct. By participating, you are expected to uphold this code. For now, we are too few to be able to enforce it.

I Have a Question

If you want to ask a question, we assume that you have read the available Documentation.

Before you ask a question, it is best to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.

If you then still feel the need to ask a question and need clarification, we recommend the following:

• Open an Issue.
• Provide as much context as you can about what you’re running into.
• Provide project and platform versions, depending on what seems relevant.

We will then take care of the issue as soon as possible.

I Want To Contribute

Legal Notice

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Reporting Bugs

Before Submitting a Bug Report

A good bug report shouldn’t leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.

• Make sure that you are specified the version correctly.
• Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the documentation. If you are looking for support, you might want to check this section).
• To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the bug tracker.
• Collect information about the bug:
• Stack trace (Traceback)
• OS, Platform and Version (Ubuntu 20.04, Debian 10, RedHat 8, etc.)
• Version of Rust (e.g. rustc --version)
• Possibly your input and the output
• Can you reliably reproduce the issue? And can you also reproduce it with older versions?

How Do I Submit a Good Bug Report?

For security issues, please read the Security Policy.

We use GitHub issues to track bugs and errors. If you run into an issue with the project:

• Open an Issue. (Since we can’t be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
• Explain the behavior you would expect and the actual behavior.
• Please provide as much context as possible and describe the reproduction steps that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
• Provide the information you collected in the previous section.

Once it’s filed:

• The project team will label the issue accordingly.
• A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as needs-repro. Bugs with the needs-repro tag will not be addressed until they are reproduced.
• If the team is able to reproduce the issue, it will be marked needs-fix, as well as possibly other tags (such as critical), and the issue will be left to be implemented by someone.

To help you to fill out the issue, please follow the templates provided by GitHub when you open a new issue.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for RootAsRole, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.

Before Submitting an Enhancement

• Make sure that you are using the latest version.
• Read the documentation carefully and find out if the functionality is already covered, maybe by an individual configuration.
• Perform a search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
• Find out whether your idea fits with the scope and aims of the project. It’s up to you to make a strong case to convince the project’s developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you’re just targeting a minority of users, consider writing an add-on/plugin library.

How Do I Submit a Good Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues.

• Use a clear and descriptive title for the issue to identify the suggestion.
• Provide a step-by-step description of the suggested enhancement in as many details as possible.
• Describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives do not work for you.
• Explain why this enhancement would be useful to most RootAsRole users. You may also want to point out the other projects that solved it better and which could serve as inspiration.

Again, to help you to fill out the enhancement, please follow the templates provided by GitHub when you open a new issue.

Improving The Documentation

The documentation needs to be improved. If you find a typo, error, or something that is not clear, please help us by correcting it. If you have a suggestion for improving the documentation, please follow the steps below:

• Open an Issue
• If you want to make the change yourself, fork the repository and make the changes in your fork. Then open a pull request with the changes. We will review the changes and merge them if they are good.

Attribution

This guide is based on the contributing-gen. Make your own!

RootAsRole Code of Conduct

Our Pledge

We pledge to make our community welcoming, safe, and equitable for all.

We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.

Encouraged Behaviors

While acknowledging differences in social norms, we all strive to meet our community’s expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.

With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:

1. Respecting the purpose of our community, our activities, and our ways of gathering.
2. Engaging kindly and honestly with others.
3. Respecting different viewpoints and experiences.
4. Taking responsibility for our actions and contributions.
5. Gracefully giving and accepting constructive feedback.
6. Committing to repairing harm when it occurs.
7. Behaving in other ways that promote and sustain the well-being of our community.

Restricted Behaviors

We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.

1. Harassment. Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
2. Character attacks. Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
3. Stereotyping or discrimination. Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
4. Sexualization. Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
5. Violating confidentiality. Sharing or acting on someone’s personal or private information without their permission.
6. Endangerment. Causing, encouraging, or threatening violence or other harm toward any person or group.
7. Behaving in other ways that threaten the well-being of our community.

Other Restrictions

1. Misleading identity. Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
2. Failing to credit sources. Not properly crediting the sources of content you contribute.
3. Promotional materials. Sharing marketing or other commercial content in a way that is outside the norms of the community.
4. Irresponsible communication. Failing to responsibly present content which includes, links or describes any other restricted behaviors.

Enforcement

For now, our Code of Conduct is a set of values that we voluntarily agree to follow. As the project is growing, we may need to enforce this Code of Conduct by following the Contributor Covenant CoC.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at https://www.contributor-covenant.org/version/3/0/.

Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/

For answers to common questions about Contributor Covenant, see the FAQ at https://www.contributor-covenant.org/faq. Translations are provided at https://www.contributor-covenant.org/translations. Additional enforcement and community guideline resources can be found at https://www.contributor-covenant.org/resources. The enforcement ladder was inspired by the work of Mozilla’s code of conduct team.

The RootAsRole history

1.0 (2018)

The project is initiated by SIERA IRIT CNRS research team with Ahmad Samer WAZAN as owner of the proof of concept. It is presented for the first time at “Le capitole du libre” in Toulouse. A paper is published[Wazan et al. 2021].

2.0 (2019)

RootAsRole is still a proof of concept but now proposes an eBPF subprogram to obtain the capabilities of a generic command. A paper is published at Computer and Security[Wazan et al. 2022]

3.0 (2024)

RootAsRole direction is delegated to Eddie BILLOIR, a SIERA PhD student that contributed to the project all along its courses. It is now entirely rewritten in Rust, the eBPF subprogram is now in a separate project called RootAsRole-capable. The project takes a new direction and aims to be production ready with a massive reconception of every tools, a new configuration file format and complete documentation.

4.0 (2026)

RootAsRole reaches a major stabilization milestone with the modernized execution stack crate rar-exec for managing a secure execution for commands, thus handling signals and pty completely, introducing a way to monitor and curtail the execution in the future, exactly like sudo tool. It also introduces more configuration capabilities, such as folder-based configuration and CBOR-only format for even more performance. It also enhances the execution context, by adding the working directory management in the policy.

Documentation is refocused on operational usage, policy clarity, and contributor architecture. A comprehensive PhD thesis [Billoir 2025] consolidates the research foundation and design rationale for the project.

A new mascot, CaRoot, is introduced to personify the project and make it fancy. CaRoot was designed by EvaLaFougère, a talented artist! Her work is available on her website.

References