Grsecurity/The Administration Utility

Gradm, the administration utility for the role-based access control system, is a powerful tool that parses your ACLs (Access Control Lists), performs the enforcement of a secure base policy, optimizes the ACLs, as well as handles parsing of the learning logs, merges them with your ACL set and outputs the final ACLs.

Before you install gradm, boot into your patched grsecurity kernel. You can compile gradm in any kernel you wish, but the installation will fail if the kernel does not support grsecurity.

Installation

If your Linux distribution provides ready-made grsecurity kernel packages, they will very likely provide a package for gradm too. If that is the case you should consider using it before compiling gradm yourself.

Before compiling and installing gradm, make sure you have the following applications installed in your system: lex or flex and byacc or bison. If you need Pluggable Authentication Modules (PAM) support, install the header files for your system; The package containing them will very likely be called libpam-dev or similar.

A note should be added to say that if you are compiling gradm on your default linux kernel without grsecurity support the compile will fail and that you will only be able to compile after you reboot into your new grsecurity enabled kernel.

Change to the directory you downloaded gradm and grsecurity to earlier. In this document the name of the compressed package is gradm-3.1-201503211320.tar.gz. Decompress the package and change to the gradm directory by executing the following commands:

$ tar xzf gradm-3.1-201503211320.tar.gz
$ cd gradm

To install gradm with PAM support, as a non-root user run:

$ make

NOTE: Look at the output from make. Make sure you do not see a line near the end that says "Unable to detect PAM headers, disabling PAM support." If you do, install the PAM header files and run the make command again.

To install gradm without PAM support, run:

$ make nopam

Finally, as root, run:

# make install

The installation process does the following:

• Installs the gradm and grlearn programs to /sbin.
• Creates a directory /etc/grsec and two files in it (if they are not already present): learn_config and policy.
• Installs gradm's man pages to /usr/share/man/man8.
• (grlearn does not come with a man page. It is used internally by gradm.)
• Finally, and most importantly, if this is the first time you are installing gradm on your system you will be asked to provide the administrative password for the RBAC system. Choose a long password, but one that you will remember (especially if you start gradm from an initscript). Do not use the same password as your root password.

If you need to change any of the binary or man page locations, modify the Makefile.

Usage

To display all available command-line switches, run gradm --help.

# gradm --help
gradm 3.1
grsecurity RBAC administration and policy analysis utility

Usage: gradm [option] ... 

Examples:
	gradm -P
	gradm -F -L /etc/grsec/learning.logs -O /etc/grsec/policy
Options:
	-E, --enable	Enable the grsecurity RBAC system
	-D, --disable	Disable the grsecurity RBAC system
	-C, --check	Check RBAC policy for errors
	-S, --status	Check status of RBAC system
	-F, --fulllearn Enable full system learning
	-P [rolename], --passwd
			Create password for RBAC administration
			or a special role
	-R, --reload	Reload the RBAC system while in admin mode
                        Reloading will happen atomically, preserving
                        special roles and inherited subjects
	-r, --oldreload Reload the RBAC system using the old method that
                        drops existing special roles and inherited subjects
	-L <filename>, --learn
			Specify the pathname for learning logs
	-O <filename|directory>, --output
			Specify where to place policies generated from
                        learning mode.  Should be a directory only if
                        "split-roles" is specified in learn_config and
                        full-learning is used.
	-M <filename|uid>, --modsegv
			Remove a ban on a specific file or UID
	-a <rolename> , --auth
			Authenticates to a special role that requires auth
	-u, --unauth    Remove yourself from your current special role
	-n <rolename> , --noauth
			Transitions to a special role that doesn't
                        require authentication
	-p <rolename> , --pamauth
			Authenticates to a special role through PAM
	-V, --verbose   Display verbose policy statistics when enabling system
	-h, --help	Display this help
	-v, --version	Display version and GPLv2 license information

Learning Mode

The learning mode is different than anything found in other security systems. Grsecurity's learning mode can be used on a per-subject or per-role basis, as well as system-wide. When using the learning mode on a single process or role, the rest of the system remains protected as defined by the policy. The learning mode can learn all things that the RBAC system supports: files, capabilities, resources, what IP addresses make use of each role, and socket usage. The learning system performs intelligent reduction of filesystem and network access to reduce policy size, increase readability, and reduce the amount of manual tweaking needed later. Furthermore, the learning system enforces a secure base that is configurable. The /etc/grsec/learn_config file gives the administrator the ability to specify files/directories that should be considered protected resources by the learning system. The learning system will ensure that regardless of any rule reduction done, only the processes that access those protected resources through normal usage will be granted access through the generated policy. Furthermore, it will create new subjects for the processes that access the protected resources, creating privilege boundaries that grant those processes additional protection.

Full System Learning

To enable full system learning, run gradm as root with the following options:

# gradm -F -L /etc/grsec/learning.logs

This will enable the Role-based Access Control (RBAC) system and initiate full system learning. That is, gradm will monitor and log what your system does. The log can then be used to build a least privilege policy for your system.

Run and use the application(s) that you normally do, several times. This is important, since the learning mode uses a threshold–based system to determine when access should be given to a file or whether it should be given to a directory. If four or more similar accesses are made in a single directory (such as writing to several files in /tmp), access is granted to that directory instead of the individual files. This reduces the amount of rules you have and ensures that the application will work correctly after the final ACLs are compiled.

Do not perform any administrative tasks outside of the admin role while full system learning is enabled.

To perform administrative tasks while full system learning is enabled, authenticate to the admin role with:

# gradm -a admin

Remember to exit your shell or unauthenticated from the admin role with gradm -u when you are done performing administrative tasks.

Once you feel you've given the system the normal usage it would see in real life, disable the RBAC system with gradm -D. Disabling RBAC is a necessary step, as it forces the learning daemon to flush its buffers to disk. Using learning logs obtained before RBAC has been disabled will produce incomplete results. Once RBAC is disabled, execute:

# gradm -F -L /etc/grsec/learning.logs -O /etc/grsec/policy

This will place the new learned ACLs at the end of your ruleset. You can test the policy by enabling grsecurity (run gradm -E), and making sure all applications are functioning the way they're supposed to.

Process and Role-Based Learning

Using this learning mode is very simple. All you have to do is add "l" (the small letter L, not the number 1) to the subject mode of the process, you want to enable learning for. To learn all necessary access for a given binary that does not yet have an established policy, add the following subject:

subject /path/of/binary ol
    / h
    -CAP_ALL
    connect disabled
    bind disabled

To learn on a given role, add "l" to the role mode. For both of these, to enable learning, enable the system by executing:

# gradm -L /etc/grsec/learning.logs -E

When you are done, disable the ACL system with gradm -D (or alternatively, go into admin mode with gradm -a), and use:

# gradm -L /etc/grsec/learning.logs -O /etc/grsec/policy

This will place the new learned ACLs at the end of your ruleset. Simply remove the old ACLs and you are ready to go.

/etc/grsec/learn_config

This configuration file aids the learning process by tweaking the learning algorithm for specific files and directories. It accepts lines in the form of:

<command> <pathname>

Where <command> can be inherit-learn, no-learn, inherit-no-learn, high-reduce-path, dont-reduce-path, protected-path, high-protected-path, and always-reduce-path. inherit-learn, no-learn, and inherit-no-learn only affect full system learning, while the others work on all modes of learning.

inherit-learn changes the learning process for the specified path by throwing all learned accesses for every binary executed by the processes contained in the pathname into the subject specified by the pathname. This is useful for cron in the case of full system learning, so that scripts that eventually end up executing mv or rm with privilege don't cause the root policy to grant that privilege to mv or rm in all cases.

no-learn allows processes within the path to perform any operation that normal system usage would allow without restriction. If a process is generating a huge number of learning logs, it may be best to use this command on that process and configure its policy manually.

inherit-no-learn combines the above two cases, such that processes within the specified path will be able to perform any normal system operation without restriction as will any binaries executed by these processes.

high-reduce-path modifies the heuristics of the learning process to weigh in favor of reducing accesses for this path.

dont-reduce-path modifies the heuristics of the learning process so that it will never reduce accesses for this path.

always-reduce-path modifies the heuristics of the learning process so that the path specified will always have all files and directories within it reduced to the path specified.

protected-path specifies a path on your system that is considered an important resource. Any process that modifies one of these paths is given its own subject in the learning process, facilitating a secure policy.

read-protected-path specifies a path on your system that contains sensitive information. Any process that reads one of these paths is given its own subject in the learning process, facilitating a secure policy.

high-protected-path specifies a path that should be hidden from all processes but those that access it directly. It is recommended to use highly sensitive files for this command.

Note that regular expressions are not supported for pathnames in this configuration file.