===============================================================================

Trusted Path Execution (TPE) Linux Kernel Module, Version 2

===============================================================================

About this module

Trusted Path Execution is a security feature that denies users from executing
programs that are not owned by root, or are writable. This closes the door on a
whole category of exploits where a malicious user tries to execute his or her
own code to attack the system.

Since this module doesn't use any kind of ACLs, it works out of the box with no
configuration. It isn't complicated to test or deploy to current production
systems. Just install it and you're done!

===============================================================================

Supported Kernels

Version 2 has been tested on the following systems (x86_64 only):

 - RHEL/CentOS 7 (linux-3.10.0)
 - Ubuntu 16.04 LTS (linux-4.8.0-39-generic)

Version 1 works on older kernels, as far back as RHEL/CentOS 5 (linux-2.6.18)

This module *should* work on most linux kernels version 3.10 and above, but has
only been verified on the above systems. If you get a compile error or a kernel
oops, please contact this module's author.

===============================================================================

Features

* Trusted Path Execution; deny execution of non-root owned or writable binaries

  $ gcc -o exploit exploit.c
  $ chmod 755 exploit
  $ ./exploit
  -bash: ./exploit: Permission denied

  $ dmesg | tail -n1
  tpe: Denied untrusted exec of /home/corey/exploit (uid:500) by /bin/bash
  (uid:500), parents: /usr/sbin/sshd (uid:500), /usr/sbin/sshd (uid:0),
  /sbin/init (uid:0). Deny reason: directory uid not trusted

See the "Configuration" section below for how to tweak configuration.

Extras features, also ported from grsecurity (but not TPE related):

* Restrict non-root users from viewing loaded kernel modules

  $ cat /proc/modules
  cat: /proc/modules: Operation not permitted

* Restrict non-root users from viewing the kernel symbol table

  $ cat /proc/kallsyms
  cat: /proc/kallsyms: Operation not permitted

* Restrict non-root users from viewing processes they don't own

  $ ps auxf
  USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
  corey    22450  0.0  0.7  97780  1804 ?        S    14:12   0:00 sshd: corey @pts/1
  corey    22451  0.0  0.7 108288  1884 pts/1    Ss   14:12   0:00  \_ -bash
  corey    22474  0.0  0.4 110184  1044 pts/1    R+   14:12   0:00      \_ ps auxf

* Restrict users from getting the kernel version

  $ uname -a
       GNU/Linux

* Restrict uses from running ptrace operations against their own processes

  $ strace -p $$
    strace: attach: ptrace(PTRACE_ATTACH, ...): Permission denied

Most of these are just kernel protections, and the user may be able to get the
info via other means if you don't take additional precautions.

See the "Configuration" section below for how to enable these extras.

===============================================================================

How it works

This module makes use of the kernel ftrace framework. In a nutshell, ftrace is
in charge of the first few bytes of most kernel symbols, and can redirect them
to other addresses. TPE instructs ftrace to redirect certain security handlers
to TPE code, which then decides whether it's appropriate to continue or not.

===============================================================================

Installation

See the INSTALL file for installation instructions.

===============================================================================

FAQ

See the FAQ file for frequently asked questions.

===============================================================================

Configuration

Although most people will find they don't need to change the default values,
you have the option to configure various things in this module at runtime using
the sysctl interface to tighten or lax the TPE restrictions. You can see the
values in this proc directory:

/proc/sys/tpe/

softmode	- log what would be denied but don't actually deny. default off
strict		- enforce some TPE features even on trusted users. default on
check_file	- check file owner/mode in addition to directory. default on
group_writable  - check if the file/directory is group writable. default on
kill		- kill the offending process and its parent when it gets denied
		  execution from TPE, unless it's root. default off
log		- whether to log denied execs to the ring buffer. default on
log_verbose	- log what can be done to allow what was denied. default on
log_max		- maximum parent processes in a single log entry. default 50
log_floodburst	- number of log entries before logging is disabled. default 5
log_floodtime	- seconds until re-enabling logging after floodburst. default 5
xattr_soften	- check extended attributes for a soften flag. default on
paranoid	- enforce the trusted path restrictions on root too. default off
trusted_apps	- a list of files, separated by commas, that would otherwise
		  have had been denied an exec/mmap/mprotect, are instead
		  allowed to proceed. default to empty (off)
hardcoded_path	- use with caution! a list of directories, separated by colons,
		  that the trusted path will be restricted to; nothing outside
		  this path may be executed/mmaped. default to empty (off)
trusted_gid	- gid of trusted users whom TPE is not enforced (see strict)
		  default 0 (off)
trusted_invert	- changes what "trusted_gid" means; if set, users in the gid
		  will be the only ones whom TPE is enforced. default 0 (off)
admin_gid	- files belonging to this group are treated as if they're owned
		  by root; TPE is not enforced on them. default 0 (off)
dmz_gid		- users in this gid can't exec anything at all. default 0 (off)

extras/         - directory for additional protections that aren't TPE related.

ignore_softmode	- enable extra features even if softmode is on. default off
log		- whether to log when extra features are denied. default on
lsmod           - denies non-root users from viewing loaded kernel modules
proc_kallsyms   - denies non-root users from viewing /proc/kallsyms
harden_ptrace	- denies non-root users from running ptrace operations
hide_uname	- denies non-root users from asking the kernel its version
ps              - denies non-root users from viewing processes they don't own
ps_gid          - gid of users who aren't restricted by ps. default 0 (off)
restrict_setuid - users not in the trusted_gid are denied calls to setuid()


Edit the /etc/sysctl.d/tpe.conf file to change the defaults of these various
features.

===============================================================================

Compatibility Issues

Test this module before deploying to a critical system, especially if you're
not using a kernel in the above "Supported Kernels" list.

Trusted Path Execution will cause some programs to stop functioning correctly.
If it doesn't result in a kernel BUG or other stack-trace to show up in dmesg,
it's the program that needs fixing, not this module. There are several ways
to work around this problem:

  1) Set a file attribute on the offending binary to soften the checks
    or
  2) Tune the module config with the "sysctl" command (see the admin_gid,
     trusted_gid, and trusted_apps options)

For example:

$ sudo setfattr -n security.tpe -v "soften_mmap" /usr/bin/gnome-session
    or
$ sudo sysctl tpe.trusted_apps="/usr/bin/gnome-session"

The file attributes "soften_<check>" (where <check> is one of the checks,
i.e.; mmap, exec, etc) is the preferred solution as it only disables that
specific check, and not anything else.

Programs that have been reported to need such measures are:

* wine
* Dropbox
* Gnome Desktop

You can persist these changes by editing the /etc/sysctl.conf file, or adding
a conf file of your own in /etc/sysctl.d/

A few notes:

Kernel modules that make use of kernel tracing (ftrace, kprobes, etc) may
conflict with this module if they touch the same kernel symbols. The only one
I know of is "kpatch".

This module will not work on systems where loadable kernel module support is
disabled at compile time (CONFIG_MODULES not being set).

This module requires many LSM hooks in order to work, and will error out when
security is disabled at compile time (CONFIG_SECURITY not being set).

If you custom compile your own kernel and want TPE, consider using grsecurity
instead of this module.

===============================================================================

BUGS

There are currently no known bugs. If you discover one, please report it to the
author.

===============================================================================

Acknowledgements

 - kpatch - https://github.com/dynup/kpatch

Looking at the kpatch implementation, I was able to simplify this module.

 - Brad Spengler - http://grsecurity.net/

Trusted Path Execution is a feature of grsecurity, and I originally pulled code
from that project to make this module.

===============================================================================

About the Author

website: http://cormander.com/
github: https://github.com/cormander/
email: corman /AT/ cormander /DOT/ com

===============================================================================