secadm
======
Author: Shawn Webb <shawn.webb@hardenedbsd.org>
Copyright (c) 2014 Shawn Webb
License: 2-Clause BSD License
https://github.com/HardenedBSD/secadm

Introduction
============

secadm is a project to replace the mac_bsdextended(4)/ugidfw(8)
integration the HardenedBSD project has done for ASLR, SEGVGUARD, and
PTrace hardening. The secadm project will be implemented as a custom
ports entry in the HardenedBSD/freebsd-ports repo. The port will
consist of three parts: a kernel module that integrates with the MAC
framework, a shared library that communicates between kernel and
userland, and an application that consumes the shared library.

The MAC module will work on a per-jail basis. It will communicate
with userland via a sysctl node. The MAC module should hook into the
execve() call to set per-process security/hardening flags, such as
toggling ASLR or SEGVGUARD. Each jail manages its own rules. Rules
applied in one jail do not interact or impact other jails.

The shared library will be named libsecadm and will simply act as a
communication layer between userland applications and the sysctl.
The shared library will perform the same sanitization and sanity
checking on all rule changes, including the removal of rules, that the
MAC module performs.

The userland application will be named secadm. It will consume libsecadm
and libucl. Rules will be written in json to allow for a
configuration file format that is readable and parseable by both
humans and machines. Using the json format will also allow for
additional flexibility and dynamic content. One can imagine secadm
deployed in a security appliance where the rulesets are created and
updated via a web service API.

secadm will initially support toggling ASLR, SEGVGUARD, and PTrace
hardening. It will work on a per-jail and per-file basis.

Requirements
============

* HardenedBSD version 9 or greater:
  - `sysctl hardening.version` should show 9
* textproc/libucl

Installation And Usage
======================

# make
# make depend all install

To list which per-applicatin features your version of secadm supports:
# secadm list features

To load the secadm kernel module:
# kldload secadm

Edit your rules:
# vi secadm/config.conf.sample

Activate them. Please note that setting a new ruleset will flush your
previously-loaded rules.
# secadm -c secadm/config.conf.sample set

To verify that your ruleset loaded successfully:
# secadm list

To flush rules:
# secadm flush

Writing Application Rules
=========================

secadm currently supports toggling ASLR, SEGVGUARD, mprotect(exec)
hardening, and on certain HardenedBSD builds, PAGEEXEC hardening. In
the secadm directory, you will find config.conf.sample, which shows
how to write rules.

secadm uses libucl for parsing its config file. As it stands right
now, the order of the rules do not matter, but that could change with
time as we add new features. The sample config file is in a relaxed
JSON format, though libucl supports different syntaxes. Please refer
to libucl's documentation for help in learning the different possible
syntaxes.

In the root object, secadm expects an applications array. Each entry
in the applications array must be an object. That object must have the
following fields:

	1. path (string): The fully-qualified path of the program
	2. features (object): An object that describes each of the
	   features we are toggling. Supported features:
	   a. aslr (boolean): toggles ASLR
	   b. segvguard (boolean): toggles SEGVGUARD
	   c. mprotect (boolean): toggles mprotect(exec) hardening
	   d. pageexec (boolean): toggles PAGEEXEC

When you combine that all together, you should get the following
example. Let's say we want to force ASLR and SEGVGUARD off with
/bin/ls and force mprotect(exec) hardening and PAGEEXEC on with
/bin/pwd. This is what you would write:

==== Start of Example ====
{
	"applications": [
		{
			"path": "/bin/ls",
			"features": {
				"aslr": false,
				"segvguard": false
			}
		},
		{
			"path": "/bin/pwd",
			"features": {
				"mprotect": true,
				"pageexec": true
			}
		}
	]
}
==== End of Example ====

Note About libsecadm
====================

libsecadm is under heavy development. Though care has been taken to
keep future changes and features in minde, the API and ABI are not
stable and may change from release to release. If you plan to develop
third-party applications that consume libsecadm, please do so at your
own risk. If you feel you need added features or a change to an
existing feature, please file a bug report at secadm's issue tracker
on github.