Unverified Commit 8c1494a5 authored by Shawn Webb's avatar Shawn Webb
Browse files

Add secadm.rules(5) manpage.



Signed-off-by: Shawn Webb's avatarShawn Webb <shawn.webb@hardenedbsd.org>
github-issue:	#28
parent 6d2f4f68
......@@ -16,6 +16,6 @@ WANTS_PIE= yes
CFLAGS+= -I${.CURDIR}/../libsecadm -I/usr/local/include
LDFLAGS+= -L${.CURDIR}/../libsecadm/obj -L/usr/local/lib
MAN= secadm.8
MAN= secadm.rules.5 secadm.8
.include <bsd.prog.mk>
.\"-
.\" Copyright (c) 2016 Shawn Webb <shawn.webb@hardenedbsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd March 06, 2016
.Dt SECADM.RULES 5
.Os
.Sh NAME
.Nm secadm.rules
.Nd secadm Ruleset Configuration
.SH DESCRIPTION
The file
.Nm
contains rules that make up a ruleset, describing how a HardenedBSD
system should apply exploit mitigations to a given application.
The file is parsed with
.Xr libucl 3
and therefore uses its syntax.
.Nm
should be deployed to
.Dq /usr/local/etc .
.Pp
Two types of rules exist in
.Nm :
pax rules and integriforce rules.
Pax rules toggle exploit mitigation features on a per-executable basis
while integriforce rules enforce the integrity of executables along
with the shared objects they depend on.
.Pp
If integriforce is set in whitelisting mode, integriforce acts as an
application whitelisting utility.
In this mode, all the shared objects an executable depends on, the
.Xr rtld 1 ,
and the executable must have rules.
If one file is missing,
.Xr execve 2
will return EPERM.
This also impacts
.Xr dlopen 3 ,
as that function will return NULL in case of failure.
Whitelisting mode is only active when enabled and when at least one
integriforce rule is loaded.
.Pp
A given pax rule is contained within a single pax object.
Multiple pax objects can be active within a given ruleset.
.Pp
Pax options and features that can be set:
.Bl -bullet
.It
Option: path
.Bl -dash -compact
.It
Type: String
.It
Requirement: Required
.It
Description: Fully-qualified path of the executable.
.El
.It
Feature: aslr
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle
.Xr aslr 4 .
.El
.It
Feature: pageexec
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle pageexec restrictions (do not allow
mmap(PROT_WRITE|PROT_EXEC)).
.El
.It
Feature: mprotect
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle mprotect restrictions (do not allow
mprotect(PROT_WRITE|PROT_EXEC)).
.It
Special Notes: This feature is disabled wwhen pageexec is disabled.
.El
.It
Feature: shlibrandom
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle shared library load order randomization in the
.Xr rtld 1 .
.El
.It
Feature: segvguard
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle segfault guard protection (protects against
.Xr aslr 4
bruteforce attacks).
.El
.It
Feature: disallow_map32bit
.Bl -dash -compact
.It
Type: Boolean
.It
Requirement: Optional
.It
Description: Toggle mmap(MAP_32BIT) protections on 64-bit systems.
.El
.El
.Pp
A given integriforce rule is contained within a single integriforce
object.
Multiple integriforce objects can be active within a given ruleset.
.Pp
Integriforce rules contain the following options:
.Bl -bullet
.It
path
.Bl -dash -compact
.It
Type: String
.It
Requirement: Required
.It
Description: Fully-qualified path of the file.
.El
.It
hash
.Bl -dash -compact
.It
Type: String
.It
Requirement: Required
.It
Description:
.Xr sha1 1
or
.Xr sha256 1
hash of the file.
.El
.It
type
.Bl -dash -compact
.It
Type: String
.It
Requirement: Required
.It
Description: Type of hash.
Either
.Dq sha1
or
.Dq sha256
.El
.It
mode
.Bl -dash -compact
.It
Type: String
.It
Requirement: Required
.It
Description: Either
.Dq soft
or
.Dq hard .
In soft mode, if the hash doesn't match, a warning is printed in
syslog and execution is allowed.
In hard mode, if the hash doesn't match, an error is printed in syslog
and execution is denied.
.El
.El
.Pp
.Sh EXAMPLES
Disable pageexec and mprotect for
.Dq /usr/local/share/chromium/chrome :
.Bd -literal -offset indent
secadm {
pax {
path: "/usr/local/share/chromium/chrome",
pageexec: false,
mprotect: false
}
}
.Ed
.Pp
Enforce sha1 hash for
.Dq /usr/local/share/chromium/chrome :
.Bd -literal -offset indent
secadm {
integriforce {
path: "/usr/local/share/chromium/chrome",
hash: "61de67ca0251e85f3495f232762562d086a7cd11",
type: "sha1",
mode: "hard"
}
}
.Ed
.Pp
Combine both rules into one ruleset:
.Bd -literal -offset indent
secadm {
pax {
path: "/usr/local/share/chromium/chrome",
pageexec: false,
mprotect: false
},
integriforce {
path: "/usr/local/share/chromium/chrome",
hash: "61de67ca0251e85f3495f232762562d086a7cd11",
type: "sha1",
mode: "hard"
}
}
.Ed
.Pp
Enable integriforce whitelisting mode:
.Bd -literal -offset indent
secadm {
whitelist_mode: true
}
.Ed
.Sh SEE ALSO
.Xr sha1 1,
.Xr sha256 1 ,
.Xr execve 2 ,
.Xr secadm 8 ,
.Xr mac 9
.Sh AUTHORS
.An Shawn Webb
wrote the first iteration of
.Nm
and
.An Brian Salcedo
rewrote major portions.
This manual page was written by
.An Shawn Webb .
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment