Add section on file access to AppArmor guide

MAC-DAC-example.png figure added to the AppArmor guideline.

Signed-of-by:  <samir.jasarevic@se.bosch.com>

Introduction to file access in AppArmor.
An example of MAC and DAC file access permissions is shown.

Signed-off-by:  <samir.jasarevic@se.bosch.com>

Apply 4 suggestion(s) to 1 file(s)

Apply 1 suggestion(s) to 1 file(s)

Apply 1 suggestion(s) to 1 file(s)

Apply 2 suggestion(s) to 1 file(s)

Updated file access based on the review comments.

Signed-off-by:  <samir.jasarevic@se.bosch.com>

Update file access with 4 spaces for code

Signed-off-by:  <samir.jasarevic@se.bosch.com>

content/guides/apparmor.md

@@ -551,3 +551,83 @@ read and write permissions to a specific mount point.
   path/to/executable r,
 }
 ```
+## File access
+
+Since the AppArmor security model is a MAC implementation, it can only confine access to resources that the executable’s owner already has access to, according to the DAC access permission rules.
+
+As an example, the diagram below shows the contents of `/home/user` directory and the files’ owner, which is "user", has read/write access to the first three files in the green DAC box. On the other hand, the owner "user" does not have acces to the last file, as defined by the DAC permission rules.
+
+![](/images/MAC-DAC-example.png)
+
+AppArmor can only create permission rules to the files in the green DAC box, and cannot give more access than what is already accessible for "user". In this example, AppArmor could create rules for an executable owned by "user" that allows **read only** access to **only** two files, i.e. files within the purple MAC box. Despite the fact that "user" would normally be able to have both read/write permissions on all three files in the green DAC box, in this case, the access would be denied to the first file due to confinement by AppArmor. In the table below, it is shown what access an executable owned by "user" would have before and after AppArmor access rules are applied.
+
+| Files in "user" directory | Access given by DAC | Access given by MAC / AppArmor |
+| :--------: | :-----: | :-----: |
+| file_1.txt | **Yes** | No      |
+| file_2.txt | **Yes** | **Yes** |
+| file_3.txt | **Yes** | **Yes** |
+| file_4.txt | No      | No      |
+
+
+Based on the above example of DAC and MAC access permissions, the following bash script reads two files that the script’s owner has access to and nothing else. Note that the script does not need to write anything to the files, even though the user could do that. 
+
+In order to achieve the desired behavior an AppArmor profile for the executable needs to be created using the `aa-genprof` tool. Before running the `aa-genprof` tool, make sure the file_access.sh script has execute permission for the owner.
+
+Below is the content of the directory with four text files and the bash script. There is also content of the bash script / executable (file_access.sh) and the created profile (home.user.file_access.sh).
+
+Listed files in the `/home/user` directory:
+    
+    $ ls -al /home/user
+    -rw-r--r-- user grp … file_1.txt
+    -rw-r--r-- user grp … file_2.txt
+    -rw-r--r-- user grp … file_3.txt
+    -rw-r--r-- usr2 gr2 … file_4.txt
+    -rwxr--r-- user grp … file_access.sh
+
+Below is the content of `file_access.sh`:
+
+    #!/bin/bash
+    
+    cat file_2.txt
+    cat file_3.txt
+
+Below is the content of `/etc/apparmor.d/home.user.file_access.sh`:
+    
+    #include <tunables/global>
+    
+    /home/user/file_access.sh {
+        #include <abstractions/base>
+        #include <abstractions/bash>
+        #include <abstractions/consoles>
+ 
+        /home/user/files_access.sh r,
+        /usr/bin/bash ix,
+        /usr/bin/cat mrix,
+        owner /home/*/file_2.txt r,
+        owner /home/*/file_3.txt r,
+    }
+
+Description of the above profile:
+
+- #include <tunables/global>     :   Includes statements from other files, so there is no need to duplicate the common rules. 
+- /home/user/file_access.sh      :   Path to the profiled executable.
+- #include <abstractions/*>      :   Includes common variables and libraries.
+- /home/user/files_access.sh r,  :   Allows the read access to the files_access.sh script.
+- /usr/bin/bash ix,              :   Inherit execute, i.e. the executed bash program will inherit the current profile.
+- /usr/bin/cat mrix ,            :   Allows the cat application read and write access to a file mapped in memory. Also, inherits the current profile.
+- owner /home/*/file_2.txt r,    :   Allows the read access to file_2.txt, which could be placed in any directory under /home/ owned by the owner.
+
+When the `file_access.sh` script is run by "user", it will show the content of the two files that "user" has read permissions for in the created profile.
+
+Now we change the `file_access.sh` to include reading of two additional files, the one that the user has access to (file_1.txt) and the one that the user doesn’t have access to (file_4.txt), according to the DAC permission rules. After the change, the executable should look like this:
+
+Below is the content of updated `file_access.sh`:
+
+    #!/bin/bash
+    
+    cat file_1.txt
+    cat file_2.txt
+    cat file_3.txt
+    cat file_4.txt
+
+When the updated script above is run again, AppArmor (assuming it is in enforce mode) will deny access to the both newly added files. The reason is simply because the profile of the executable has not been updated. The profile only allows read access to the files mentioned in the profile, i.e. file_2.txt and file_3.txt, and everything else will be implicitly denied. If we would add read access to file_1.txt and file_4.txt to the existing profile, i.e. same as for the other two files, the result this time would be that reading of all files, except the file_4.txt file, would be allowed. The access to the file_4.txt file would still be denied, because the owner of the executable does not have access to that file. In this case, the DAC read permission rule would kick in and deny the access, and as we already know, AppArmor cannot grant more permissions than the owner of the executable already has.