[01/11] S.A.R.A. Documentation
diff mbox

Message ID 1497286620-15027-2-git-send-email-s.mesoraca16@gmail.com
State Superseded
Headers show

Commit Message

Salvatore Mesoraca June 12, 2017, 4:56 p.m. UTC
Adding documentation for S.A.R.A. LSM.

Signed-off-by: Salvatore Mesoraca <s.mesoraca16@gmail.com>
---
 Documentation/admin-guide/kernel-parameters.txt |  40 +++++
 Documentation/security/00-INDEX                 |   2 +
 Documentation/security/SARA.rst                 | 192 ++++++++++++++++++++++++
 3 files changed, 234 insertions(+)
 create mode 100644 Documentation/security/SARA.rst

Comments

Jann Horn June 12, 2017, 5:49 p.m. UTC | #1
On Mon, Jun 12, 2017 at 6:56 PM, Salvatore Mesoraca
<s.mesoraca16@gmail.com> wrote:
> Adding documentation for S.A.R.A. LSM.
>
> Signed-off-by: Salvatore Mesoraca <s.mesoraca16@gmail.com>
[...]
> +/proc/PID/attr/sara/wxprot interface
> +------------------------------------
> +The `procattr` interface can be used by a program to discover which
> +WX Protection features are enabled and/or to tighten them: protection
> +can't be softened via procattr.
> +The interface is simple: it's a text file with an hexadecimal
> +number in it representing enabled features (more information can be
> +found in the `Flags values`_ section). Via this interface it is also
> +possible to perform a complete memory scan to remove the write permission
> +from pages that are both writable and executable.
> +
> +Protections that prevent the runtime creation of executable code
> +can be troublesome for all those programs that actually need to do it
> +e.g. programs shipping with a JIT compiler built-in.
> +Given that it's possible to segregate the part that runs untrusted
> +code from the rest through a fork, this feature can be use to run the JIT
> +compiler with few restrictions while enforcing full WX Protection in the
> +rest of the program.

As far as I can tell, the wxprot interface in procfs, when used as
/proc/PID/attr/sara/wxprot, actually only sets restrictions on one of the
threads.
The documentation doesn't seem to mention this.


> +.. [3] `saralib                <https://github.com/smeso/saralib>`_

This link is broken.
Salvatore Mesoraca June 13, 2017, 7:43 a.m. UTC | #2
2017-06-12 19:49 GMT+02:00 Jann Horn <jannh@google.com>:
> On Mon, Jun 12, 2017 at 6:56 PM, Salvatore Mesoraca
> As far as I can tell, the wxprot interface in procfs, when used as
> /proc/PID/attr/sara/wxprot, actually only sets restrictions on one of the
> threads.
> The documentation doesn't seem to mention this.

Yes, you are right. I'll change it.

>> +.. [3] `saralib                <https://github.com/smeso/saralib>`_
>
> This link is broken.

Oops, the correct link is https://github.com/smeso/libsara

Thank you very much for your time.
Kees Cook June 27, 2017, 10:51 p.m. UTC | #3
On Mon, Jun 12, 2017 at 9:56 AM, Salvatore Mesoraca
<s.mesoraca16@gmail.com> wrote:
> Adding documentation for S.A.R.A. LSM.
>
> Signed-off-by: Salvatore Mesoraca <s.mesoraca16@gmail.com>
> ---
>  Documentation/admin-guide/kernel-parameters.txt |  40 +++++
>  Documentation/security/00-INDEX                 |   2 +
>  Documentation/security/SARA.rst                 | 192 ++++++++++++++++++++++++
>  3 files changed, 234 insertions(+)
>  create mode 100644 Documentation/security/SARA.rst
>
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 0f5c3b4..f3ee12d 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -3702,6 +3702,46 @@
>                         1 -- enable.
>                         Default value is set via kernel config option.
>
> +       sara=           [SARA] Disable or enable S.A.R.A. at boot time.
> +                       If disabled this way S.A.R.A. can't be enabled
> +                       again.
> +                       Format: { "0" | "1" }
> +                       See security/sara/Kconfig help text
> +                       0 -- disable.
> +                       1 -- enable.
> +                       Default value is set via kernel config option.
> +
> +       sara_usb_filtering= [SARA]
> +                       Disable or enable S.A.R.A. USB Filtering at boot
> +                       time.
> +                       Format: { "0" | "1" }
> +                       See security/sara/Kconfig help text
> +                       0 -- disable.
> +                       1 -- enable.
> +                       Default value is 1.
> +
> +       sara_usb_filtering_default= [SARA]
> +                       Set S.A.R.A. USB Filtering default action.
> +                       Format: { "a" | "d" }
> +                       See security/sara/Kconfig help text
> +                       a -- allow.
> +                       d -- deny.
> +                       Default value is set via kernel config option.
> +
> +       sara_wxprot=    [SARA] Disable or enable S.A.R.A. WX Protection
> +                       at boot time.
> +                       Format: { "0" | "1" }
> +                       See security/sara/Kconfig help text
> +                       0 -- disable.
> +                       1 -- enable.
> +                       Default value is 1.
> +
> +       sara_wxprot_default_flags= [SARA]
> +                       Set S.A.R.A. WX Protection default flags.
> +                       Format: <integer>
> +                       See S.A.R.A. documentation.
> +                       Default value is set via kernel config option.
> +

As an organizational note, I would suggest making these all regular
"module parameters", which would let them be automatically namespaced
under "sara". For example "sara.enabled", "sara.wxprot", etc. For
example, this is how LoadPin does it for "loadpin.enabled":

/* Should not be mutable after boot, so not listed in sysfs (perm == 0). */
module_param(enabled, int, 0);
MODULE_PARM_DESC(enabled, "Pin module/firmware loading (default: true)");

> +S.A.R.A. (S.A.R.A. is Another Recursive Acronym) is a stacked Linux Security
> +Module that aims to collect heterogeneous security measures, providing a common
> +interface to manage them.
> +As of today it consists of two main submodules:
> +
> +- USB Filtering
> +- WX Protection

The USB Filtering of SARA seems kind of out of place. Does it have
infrastructure in common with the WX protections? Should it be its own
stackable LSM?

-Kees
Kees Cook June 27, 2017, 10:54 p.m. UTC | #4
On Tue, Jun 27, 2017 at 3:51 PM, Kees Cook <keescook@chromium.org> wrote:
> The USB Filtering of SARA seems kind of out of place. Does it have
> infrastructure in common with the WX protections? Should it be its own
> stackable LSM?

Oops, I was reading v1. I see USB has been dropped from v2 --
switching to reading the v2 now. :)

-Kees
Salvatore Mesoraca July 4, 2017, 10:12 a.m. UTC | #5
2017-06-28 0:51 GMT+02:00 Kees Cook <keescook@chromium.org>:
> On Mon, Jun 12, 2017 at 9:56 AM, Salvatore Mesoraca
> <s.mesoraca16@gmail.com> wrote:
>> Adding documentation for S.A.R.A. LSM.
>>
>> Signed-off-by: Salvatore Mesoraca <s.mesoraca16@gmail.com>
>> ---
>>  Documentation/admin-guide/kernel-parameters.txt |  40 +++++
>>  Documentation/security/00-INDEX                 |   2 +
>>  Documentation/security/SARA.rst                 | 192 ++++++++++++++++++++++++
>>  3 files changed, 234 insertions(+)
>>  create mode 100644 Documentation/security/SARA.rst
>>
>> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
>> index 0f5c3b4..f3ee12d 100644
>> --- a/Documentation/admin-guide/kernel-parameters.txt
>> +++ b/Documentation/admin-guide/kernel-parameters.txt
>> @@ -3702,6 +3702,46 @@
>>                         1 -- enable.
>>                         Default value is set via kernel config option.
>>
>> +       sara=           [SARA] Disable or enable S.A.R.A. at boot time.
>> +                       If disabled this way S.A.R.A. can't be enabled
>> +                       again.
>> +                       Format: { "0" | "1" }
>> +                       See security/sara/Kconfig help text
>> +                       0 -- disable.
>> +                       1 -- enable.
>> +                       Default value is set via kernel config option.
>> +
>> +       sara_usb_filtering= [SARA]
>> +                       Disable or enable S.A.R.A. USB Filtering at boot
>> +                       time.
>> +                       Format: { "0" | "1" }
>> +                       See security/sara/Kconfig help text
>> +                       0 -- disable.
>> +                       1 -- enable.
>> +                       Default value is 1.
>> +
>> +       sara_usb_filtering_default= [SARA]
>> +                       Set S.A.R.A. USB Filtering default action.
>> +                       Format: { "a" | "d" }
>> +                       See security/sara/Kconfig help text
>> +                       a -- allow.
>> +                       d -- deny.
>> +                       Default value is set via kernel config option.
>> +
>> +       sara_wxprot=    [SARA] Disable or enable S.A.R.A. WX Protection
>> +                       at boot time.
>> +                       Format: { "0" | "1" }
>> +                       See security/sara/Kconfig help text
>> +                       0 -- disable.
>> +                       1 -- enable.
>> +                       Default value is 1.
>> +
>> +       sara_wxprot_default_flags= [SARA]
>> +                       Set S.A.R.A. WX Protection default flags.
>> +                       Format: <integer>
>> +                       See S.A.R.A. documentation.
>> +                       Default value is set via kernel config option.
>> +
>
> As an organizational note, I would suggest making these all regular
> "module parameters", which would let them be automatically namespaced
> under "sara". For example "sara.enabled", "sara.wxprot", etc. For
> example, this is how LoadPin does it for "loadpin.enabled":
>
> /* Should not be mutable after boot, so not listed in sysfs (perm == 0). */
> module_param(enabled, int, 0);
> MODULE_PARM_DESC(enabled, "Pin module/firmware loading (default: true)");

I apologize to be so late to answer you.
I completely missed this email.
I'll follow your suggestion in v3, thank you.

Patch
diff mbox

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 0f5c3b4..f3ee12d 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3702,6 +3702,46 @@ 
 			1 -- enable.
 			Default value is set via kernel config option.
 
+	sara=		[SARA] Disable or enable S.A.R.A. at boot time.
+			If disabled this way S.A.R.A. can't be enabled
+			again.
+			Format: { "0" | "1" }
+			See security/sara/Kconfig help text
+			0 -- disable.
+			1 -- enable.
+			Default value is set via kernel config option.
+
+	sara_usb_filtering= [SARA]
+			Disable or enable S.A.R.A. USB Filtering at boot
+			time.
+			Format: { "0" | "1" }
+			See security/sara/Kconfig help text
+			0 -- disable.
+			1 -- enable.
+			Default value is 1.
+
+	sara_usb_filtering_default= [SARA]
+			Set S.A.R.A. USB Filtering default action.
+			Format: { "a" | "d" }
+			See security/sara/Kconfig help text
+			a -- allow.
+			d -- deny.
+			Default value is set via kernel config option.
+
+	sara_wxprot=	[SARA] Disable or enable S.A.R.A. WX Protection
+			at boot time.
+			Format: { "0" | "1" }
+			See security/sara/Kconfig help text
+			0 -- disable.
+			1 -- enable.
+			Default value is 1.
+
+	sara_wxprot_default_flags= [SARA]
+			Set S.A.R.A. WX Protection default flags.
+			Format: <integer>
+			See S.A.R.A. documentation.
+			Default value is set via kernel config option.
+
 	serialnumber	[BUGS=X86-32]
 
 	shapers=	[NET]
diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX
index 45c82fd..fe3583c 100644
--- a/Documentation/security/00-INDEX
+++ b/Documentation/security/00-INDEX
@@ -10,6 +10,8 @@  Yama.txt
 	- documentation on the Yama Linux Security Module.
 apparmor.txt
 	- documentation on the AppArmor security extension.
+SARA.rst
+	- documentation on the S.A.R.A. Linux Security Module.
 credentials.txt
 	- documentation about credentials in Linux.
 keys-ecryptfs.txt
diff --git a/Documentation/security/SARA.rst b/Documentation/security/SARA.rst
new file mode 100644
index 0000000..a1523033
--- /dev/null
+++ b/Documentation/security/SARA.rst
@@ -0,0 +1,192 @@ 
+========
+S.A.R.A.
+========
+
+S.A.R.A. (S.A.R.A. is Another Recursive Acronym) is a stacked Linux Security
+Module that aims to collect heterogeneous security measures, providing a common
+interface to manage them.
+As of today it consists of two main submodules:
+
+- USB Filtering
+- WX Protection
+
+
+The kernel-space part is complemented by its user-space counterpart: `saractl` [2]_.
+A test suite for WX Protection, called `sara-test` [4]_, is also available.
+More information about where to find these tools and the full S.A.R.A.
+documentation are in the `External Links and Documentation`_ section.
+
+-------------------------------------------------------------------------------
+
+S.A.R.A.'s Submodules
+=====================
+
+USB Filtering
+-------------
+USB Filtering aims to provide a mechanism to decide which USB devices should
+be authorized to connect to the system and which shouldn't. The main goal
+is to narrow the attack surface for custom USB devices designed to exploit
+vulnerabilities found in some USB device drivers.
+
+Via configuration it's possible to allow or to deny authorization, based
+on one or more of: Vendor ID, Product ID, bus name and port number. There
+is also limited support for wildcards.
+Depending on the configuration, it can work both as a white list or as a black
+list.
+With the help of `saractl` [2]_ it's also possible to completely disable new
+USB devices when the screen is "locked".
+The original idea is inspired by the Grsecurity "Deny USB" feature.
+For further information on configuration file format and user-space utilities
+please look at the full documentation [1]_.
+
+
+WX Protection
+-------------
+WX Protection aims to improve user-space programs security by applying:
+
+- `W^X enforcement`_
+- `W!->X (once writable never executable) mprotect restriction`_
+- `Executable MMAP prevention`_
+
+All of the above features can be enabled or disabled both system wide
+or on a per executable basis through the use of configuration files managed by
+`saractl` [2]_.
+
+It is important to note that some programs may have issues working with
+WX Protection. In particular:
+
+- **W^X enforcement** will cause problems to any programs that needs
+  memory pages mapped both as writable and executable at the same time e.g.
+  programs with executable stack markings in the *PT_GNU_STACK* segment.
+- **W!->X mprotect restriction** will cause problems to any program that
+  needs to generate executable code at run time or to modify executable
+  pages e.g. programs with a *JIT* compiler built-in or linked against a
+  *non-PIC* library.
+- **Executable MMAP prevention** can work only with programs that have at least
+  partial *RELRO* support. It's disabled automatically for programs that
+  lack this feature. It will cause problems to any program that uses *dlopen*
+  or tries to do an executable mmap. Unfortunately this feature is the one
+  that could create most problems and should be enabled only after careful
+  evaluation.
+
+To extend the scope of the above features, despite the issues that they may
+cause, they are complemented by **/proc/PID/attr/sara/wxprot** interface
+and **trampoline emulation**.
+
+At the moment, WX Protection (unless specified otherwise) runs on `x86_64` and
+`x86_32` (with PAE).
+
+Parts of WX Protection are inspired by some of the features available in PaX.
+
+For further information about configuration file format and user-space
+utilities please take a look at the full documentation [1]_.
+
+W^X enforcement
+----------------------
+W^X means that a program can't have a page of memory that is marked, at the
+same time, writable and executable. This also allow to detect many bad
+behaviours that make life much more easy for attackers. Programs running with
+this feature enabled will be more difficult to exploit in the case they are
+affected by some vulnerabilities, because the attacker will be forced
+to make more steps in order to exploit them.
+
+W!->X (once writable never executable) mprotect restriction
+-----------------------------------------------------------
+"Once writable never executable" means that any page that could have been
+marked as writable in the past won't ever be allowed to be marked (e.g. via
+an mprotect syscall) as executable.
+This goes on the same track as W^X, but is much stricter and prevents
+the runtime creation of new executable code in memory.
+Obviously, this feature does not prevent a program from creating a new file and
+*mmapping* it as executable, however, it will be way more difficult for attackers
+to exploit vulnerabilities if this feature is enabled.
+
+Executable MMAP prevention
+--------------------------
+This feature prevents the creation of new executable mmaps after the dynamic
+libraries have been loaded. When used in combination with **W!->X mprotect
+restriction** this feature will completely prevent the creation of new
+executable code in the current program.
+Obviously, this feature does not prevent cases in which an attacker uses an
+*execve* to start a completely new program. This kind of restriction, if
+needed, can be applied using one of the other LSM that focuses on MAC.
+Please be aware that this feature can break many programs and so it should be
+enabled after careful evaluation.
+
+/proc/PID/attr/sara/wxprot interface
+------------------------------------
+The `procattr` interface can be used by a program to discover which
+WX Protection features are enabled and/or to tighten them: protection
+can't be softened via procattr.
+The interface is simple: it's a text file with an hexadecimal
+number in it representing enabled features (more information can be
+found in the `Flags values`_ section). Via this interface it is also
+possible to perform a complete memory scan to remove the write permission
+from pages that are both writable and executable.
+
+Protections that prevent the runtime creation of executable code
+can be troublesome for all those programs that actually need to do it
+e.g. programs shipping with a JIT compiler built-in.
+Given that it's possible to segregate the part that runs untrusted
+code from the rest through a fork, this feature can be use to run the JIT
+compiler with few restrictions while enforcing full WX Protection in the
+rest of the program.
+
+The preferred way to access this interface is via `saralib` [3]_.
+If you don't want it as a dependency, you can just statically link it
+in your project or copy/paste parts of it.
+To make things simpler `saralib` is the only part of S.A.R.A. released under
+*CC0 - No Rights Reserved* license.
+
+Trampoline emulation
+--------------------
+Some programs need to generate part of their code at runtime. Luckily enough,
+in some cases they only generate well-known code sequences (the
+*trampolines*) that can be easily recognized and emulated by the kernel.
+This way WX Protection can still be active, so a potential attacker won't be
+able to generate arbitrary sequences of code, but just those that are
+explicitly allowed. This is not ideal, but it's still better than having WX
+Protection completely disabled.
+
+In particular S.A.R.A. is able to recognize trampolines used by GCC for nested
+C functions and libffi's trampolines.
+This feature is available only on x86_32 and x86_64.
+
+Flags values
+------------
+Flags are represented as a 16 bit unsigned integer in which every bit indicates
+the status of a given feature:
+
++------------------------------+----------+
+|           Feature            |  Value   |
++==============================+==========+
+| W!->X Heap                   |  0x0001  |
++------------------------------+----------+
+| W!->X Stack                  |  0x0002  |
++------------------------------+----------+
+| W!->X Other memory           |  0x0004  |
++------------------------------+----------+
+| W^X                          |  0x0008  |
++------------------------------+----------+
+| Don't enforce, just complain |  0x0010  |
++------------------------------+----------+
+| Be Verbose                   |  0x0020  |
++------------------------------+----------+
+| Executable MMAP prevention   |  0x0040  |
++------------------------------+----------+
+| Force W^X on setprocattr     |  0x0080  |
++------------------------------+----------+
+| Trampoline emulation         |  0x0100  |
++------------------------------+----------+
+| Children will inherit flags  |  0x0200  |
++------------------------------+----------+
+
+-------------------------------------------------------------------------------
+
+External Links and Documentation
+================================
+
+.. [1] `Documentation	<https://github.com/smeso/sara-doc>`_
+.. [2] `saractl		<https://github.com/smeso/saractl>`_
+.. [3] `saralib		<https://github.com/smeso/saralib>`_
+.. [4] `sara-test	<https://github.com/smeso/sara-test>`_