[net-next,RFC,v2,9/9] doc: Add LSM / BPF Checmate docs

Commit Message

Sargun Dhillon Aug. 29, 2016, 11:47 a.m. UTC

This adds documentation on how to operate, and develop against the
Checmate LSM and Cgroup controller.

Signed-off-by: Sargun Dhillon <[e-mail]>
---
 Documentation/security/Checmate.txt | 54 +++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 Documentation/security/Checmate.txt

Comments

Randy Dunlap Aug. 29, 2016, 4:50 p.m. UTC | #1

On 08/29/16 04:47, Sargun Dhillon wrote:
> This adds documentation on how to operate, and develop against the
> Checmate LSM and Cgroup controller.
> 
> Signed-off-by: Sargun Dhillon <[e-mail]>
> ---
>  Documentation/security/Checmate.txt | 54 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 54 insertions(+)
>  create mode 100644 Documentation/security/Checmate.txt
> 
> diff --git a/Documentation/security/Checmate.txt b/Documentation/security/Checmate.txt
> new file mode 100644
> index 0000000..d409785
> --- /dev/null
> +++ b/Documentation/security/Checmate.txt
> @@ -0,0 +1,54 @@
> +--- What is Checmate? ---
> +
> +Checmate is a flexible programmable, extensible minor LSM that's coupled with
> +cgroups and BPF. It is designed to enforce container-specific policies. By
> +default, it does not enforce any policies. It is selectable at build time
> +with CONFIG_SECURITY_CHECMATE, and it is controlled through the unified cgroups
> +controller hierarchy.
> +
> +# How to use Checmate
> +In order to use Checmate, you have to enable the controller on the cgroup2
> +hierarchy. In order to prevent a centralized configuration daemon from mounting
> +Checmate on the V1 hierarchy you may want to add 'cgroup_no_v1=checmate' to your
> +boot command line.
> +
> +Enabling the controller:
> +	mount -t cgroup2 none $MOUNT_POINT
> +	cd $MOUNT_POINT
> +	echo +checmate > cgroup.subtree_control
> +
> +Once you do this, immediate children of this node on the hierarchy will have a
> +number of control files that begin with 'checmate.'. Each of these is mapped
> +to an LSM hook by the same name. If you read the file, it will return the
> +number of filters attached to that given hook. Details of the hooks can be
> +found in lsm_hooks.h.
> +
> +All tasks which are members of a cgroup will have no only the checmate filters

s/no/not/

> +at that level enforced, but all levels above as well. If there is a need
> +to exempt a specific sub-cgroup, a program can use current_task_under_cgroup
> +along with a bpf map.
> +
> +## Adding filters:
> +If you would like to add a filter, you must compile a BPF_PROG_TYPE_CHECMATE BPF
> +program. You can then write the '%d\n' formatted version of the BPF program
> +file descriptor to the relevant control file.
> +
> +## Removing filters:
> +If you would like to remove a specific filter, you can write the negative file
> +descriptor of the BPF program to the control file (a la '-%d\n'). If you would
> +like to do this, then it is recommended that you pin your programs.
> +
> +If you would like to remove all filters from a specific hook, simply write '0'
> +to the control file. During normal operation, you shouldn't have the bpf syscall
> +return '0' for a given program, please take proper precautions to work around
> +this.
> +
> +# Caveats
> +## Hook Limit:
> +Each hook is limited to having MAX_CHECMATE_INSTANCES (32) hooks per level
> +in the hierarchy. The write call will return ENOSPC if you hit this condition.
> +
> +## CGroup v2 interaction with CGroup v1:
> +Because the cgroups subsystem is in transition, using the net_prio or the
> +net_classid v1 cgroups will render Checmate inoperable on all network
> +hooks that inspect sockets.
> \ No newline at end of file

Patch

diff --git a/Documentation/security/Checmate.txt b/Documentation/security/Checmate.txt
new file mode 100644
index 0000000..d409785
--- /dev/null
+++ b/Documentation/security/Checmate.txt
@@ -0,0 +1,54 @@ 
+--- What is Checmate? ---
+
+Checmate is a flexible programmable, extensible minor LSM that's coupled with
+cgroups and BPF. It is designed to enforce container-specific policies. By
+default, it does not enforce any policies. It is selectable at build time
+with CONFIG_SECURITY_CHECMATE, and it is controlled through the unified cgroups
+controller hierarchy.
+
+# How to use Checmate
+In order to use Checmate, you have to enable the controller on the cgroup2
+hierarchy. In order to prevent a centralized configuration daemon from mounting
+Checmate on the V1 hierarchy you may want to add 'cgroup_no_v1=checmate' to your
+boot command line.
+
+Enabling the controller:
+	mount -t cgroup2 none $MOUNT_POINT
+	cd $MOUNT_POINT
+	echo +checmate > cgroup.subtree_control
+
+Once you do this, immediate children of this node on the hierarchy will have a
+number of control files that begin with 'checmate.'. Each of these is mapped
+to an LSM hook by the same name. If you read the file, it will return the
+number of filters attached to that given hook. Details of the hooks can be
+found in lsm_hooks.h.
+
+All tasks which are members of a cgroup will have no only the checmate filters
+at that level enforced, but all levels above as well. If there is a need
+to exempt a specific sub-cgroup, a program can use current_task_under_cgroup
+along with a bpf map.
+
+## Adding filters:
+If you would like to add a filter, you must compile a BPF_PROG_TYPE_CHECMATE BPF
+program. You can then write the '%d\n' formatted version of the BPF program
+file descriptor to the relevant control file.
+
+## Removing filters:
+If you would like to remove a specific filter, you can write the negative file
+descriptor of the BPF program to the control file (a la '-%d\n'). If you would
+like to do this, then it is recommended that you pin your programs.
+
+If you would like to remove all filters from a specific hook, simply write '0'
+to the control file. During normal operation, you shouldn't have the bpf syscall
+return '0' for a given program, please take proper precautions to work around
+this.
+
+# Caveats
+## Hook Limit:
+Each hook is limited to having MAX_CHECMATE_INSTANCES (32) hooks per level
+in the hierarchy. The write call will return ENOSPC if you hit this condition.
+
+## CGroup v2 interaction with CGroup v1:
+Because the cgroups subsystem is in transition, using the net_prio or the
+net_classid v1 cgroups will render Checmate inoperable on all network
+hooks that inspect sockets.
\ No newline at end of file