diff --git a/ManPages.md b/ManPages.md index 2544597..53a6fb8 100644 --- a/ManPages.md +++ b/ManPages.md @@ -1,5 +1,10 @@ AppArmor manpages +# User commands +- [aa-enabled](manpage_aa-enabled.1) +- [aa-exec](manpage_aa-exec.1) +- [aa-features-abi](manpage_aa-features-abi.1) + # System calls - [aa_change_hat.2](manpage_aa_change_hat.2) - [aa_change_profile.2](manpage_aa_change_profile.2) @@ -38,7 +43,9 @@ AppArmor manpages - [aa-remove-unknown.8](manpage_aa-remove-unknown.8) - [aa-teardown.8](manpage_aa-teardown.8) - [aa-unconfined.8](manpage_aa-unconfined.8) +- [aa-status](manpage_aa-status.8) - [apparmor_parser.8](manpage_apparmor_parser.8) +- [mod_apparmor](manpage_mod_apparmor.8) diff --git a/manpage_aa-enabled.1.md b/manpage_aa-enabled.1.md new file mode 100644 index 0000000..b018b03 --- /dev/null +++ b/manpage_aa-enabled.1.md @@ -0,0 +1,75 @@ +# Navigation +Return to manpage [Index](ManPages) + + +# NAME + +aa-enabled - test whether AppArmor is enabled + +# SYNOPSIS + +**aa-enabled** \[options\] + +# DESCRIPTION + +**aa-enabled** is used to determine if AppArmor is enabled. + +# OPTIONS + +**aa-enabled** accepts the following arguments: + +- -h, --help + + Display a brief usage guide. + +- -q, --quiet + + Do not output anything to stdout. This option is intended to be used by + scripts that simply want to use the exit code to determine if AppArmor is + enabled. + +- -x, --exclusive + + Require AppArmor to have exclusive access to shared LSM interfaces to + be considered enabled. + +# EXIT STATUS + +Upon exiting, **aa-enabled** will set its exit status to the following values: + +- **0** + + if AppArmor is enabled. + +- **1** + + if AppArmor is not enabled/loaded. + +- **2** + + intentionally not used as an **aa-enabled** exit status. + +- **3** + + if the AppArmor control files aren't available under /sys/kernel/security/. + +- **4** + + if **aa-enabled** doesn't have enough privileges to read the apparmor control files. + +- **10** + + AppArmor is enabled but does not have access to shared LSM interaces. + +- **64** + + if any unexpected error or condition is encountered. + +# BUGS + +If you find any bugs, please report them at +[https://gitlab.com/apparmor/apparmor/-/issues](https://gitlab.com/apparmor/apparmor/-/issues). + +# SEE ALSO + +apparmor(7), apparmor.d(5), aa\_is\_enabled(2), and [https://wiki.apparmor.net](https://wiki.apparmor.net). diff --git a/manpage_aa-exec.1.md b/manpage_aa-exec.1.md new file mode 100644 index 0000000..c17de04 --- /dev/null +++ b/manpage_aa-exec.1.md @@ -0,0 +1,69 @@ +# Navigation +Return to manpage [Index](ManPages) + + +# NAME + +aa-exec - confine a program with the specified AppArmor profile + +# SYNOPSIS + +**aa-exec** \[options\] \[--\] \[_<command>_ ...\] + +# DESCRIPTION + +**aa-exec** is used to launch a program confined by the specified profile +and or namespace. If both a profile and namespace are specified command +will be confined by profile in the new policy namespace. If only a namespace +is specified, the profile name of the current confinement will be used. If +neither a profile or namespace is specified command will be run using +standard profile attachment (ie. as if run without the aa-exec command). + +If the arguments are to be pasted to the _<command>_ being invoked +by aa-exec then -- should be used to separate aa-exec arguments from the +command. + aa-exec -p profile1 -- ls -l + +# OPTIONS +**aa-exec** accepts the following arguments: + +- -p PROFILE, --profile=PROFILE + + confine _<command>_ with PROFILE. If the PROFILE is not specified + use the current profile name (likely unconfined). + +- -n NAMESPACE, --namespace=NAMESPACE + + use profiles in NAMESPACE. This will result in confinement transitioning + to using the new profile namespace. + +- -i, --immediate + + transition to PROFILE before doing executing _<command>_. This + subjects the running of _<command>_ to the exec transition rules + of the current profile. + +- -v, --verbose + + show commands being performed + +- -d, --debug + + show commands and error codes + +- -- + + Signal the end of options and disables further option processing. Any + arguments after the -- are treated as arguments of the command. This is + useful when passing arguments to the _<command>_ being invoked by + aa-exec. + +# BUGS + +If you find any bugs, please report them at +[https://gitlab.com/apparmor/apparmor/-/issues](https://gitlab.com/apparmor/apparmor/-/issues) + +# SEE ALSO + +aa-stack(8), aa-namespace(8), apparmor(7), apparmor.d(5), aa\_change\_profile(3), +aa\_change\_onexec(3) and [https://wiki.apparmor.net](https://wiki.apparmor.net). diff --git a/manpage_aa-features-abi.1.md b/manpage_aa-features-abi.1.md new file mode 100644 index 0000000..2a908a0 --- /dev/null +++ b/manpage_aa-features-abi.1.md @@ -0,0 +1,64 @@ +# Navigation +Return to manpage [Index](ManPages) + + +# NAME + +aa-features-abi - Extract, validate and manipulate AppArmor feature abis + +# SYNOPSIS + +**aa-features-abi** \[OPTIONS\] \[OUTPUT OPTIONS\] + +# DESCRIPTION + +**aa-features-abi** is used to extract a features abi and output to +either stdout or a specified file. A SOURCE\_OPTION must be specified. +If an output option is not specified the features abi is writen to +stdout. + +# OPTIONS + +**aa-features-abi** accepts the following arguments: + +- -h, --help + + Display a brief usage guide. + +- -d, --debug + + show messages with debugging information + +- -v, --verbose + + show messages with stats + +# SOURCE + +- -x, --extract + + Extract the features abi for the kernel + +- -f FILE, --file=FILE + + Load the features abi from FILE and send it to OUTPUT OPTIONS. + +# OUTPUT OPTIONS + +- --stdout + + Write the features abi to _stdout_, this is the default if no output option + is specified. + +- -w FILE, --write FILE + + Write the features abi to _FILE_. + +# BUGS + +If you find any bugs, please report them at +[https://gitlab.com/apparmor/apparmor/-/issues](https://gitlab.com/apparmor/apparmor/-/issues). + +# SEE ALSO + +apparmor(7), apparmor.d(5), aa\_features(3), and [https://wiki.apparmor.net](https://wiki.apparmor.net). diff --git a/manpage_aa-status.8.md b/manpage_aa-status.8.md new file mode 100644 index 0000000..a78d42a --- /dev/null +++ b/manpage_aa-status.8.md @@ -0,0 +1,125 @@ +# Navigation +Return to manpage [Index](ManPages) + + +# NAME + +aa-status - display various information about the current AppArmor +policy. + +# SYNOPSIS + +**aa-status** \[option\] + +# DESCRIPTION + +**aa-status** will report various aspects of the current state of +AppArmor confinement. By default, it displays the same information as if +the _--verbose_ argument were given. A sample of what this looks like +is: + + apparmor module is loaded. + 110 profiles are loaded. + 102 profiles are in enforce mode. + 8 profiles are in complain mode. + Out of 129 processes running: + 13 processes have profiles defined. + 8 processes have profiles in enforce mode. + 5 processes have profiles in complain mode. + +Other argument options are provided to report individual aspects, to +support being used in scripts. + +# OPTIONS + +**aa-status** accepts only one argument at a time out of: + +- --enabled + + returns error code if AppArmor is not enabled. + +- --profiled + + displays the number of loaded AppArmor policies. + +- --enforced + + displays the number of loaded enforcing AppArmor policies. + +- --complaining + + displays the number of loaded non-enforcing AppArmor policies. + +- --kill + + displays the number of loaded enforcing AppArmor policies that will kill tasks on policy violations. + +- --special-unconfined + + displays the number of loaded non-enforcing AppArmor policies that are in the special unconfined mode. + +- --process-mixed +displays the number of processes confined by profile stacks with +profiles in different modes. +- --verbose + + displays multiple data points about loaded AppArmor policy + set (the default action if no arguments are given). + +- --json + + displays multiple data points about loaded AppArmor policy + set in a JSON format, fit for machine consumption. + +- --pretty-json + + same as --json, formatted to be readable by humans as well + as by machines. + +- --help + + displays a short usage statement. + +# EXIT STATUS + +Upon exiting, **aa-status** will set its exit status to the +following values: + +- **0** + + if apparmor is enabled and policy is loaded. + +- **1** + + if apparmor is not enabled/loaded. + +- **2** + + if apparmor is enabled but no policy is loaded. + +- **3** + + if the apparmor control files aren't available under /sys/kernel/security/. + +- **4** + + if the user running the script doesn't have enough privileges to read + the apparmor control files. + +- **42** + + if an internal error occurred. + +# BUGS + +**aa-status** must be run as root to read the state of the loaded +policy from the apparmor module. It uses the /proc filesystem to determine +which processes are confined and so is susceptible to race conditions. + +If you find any additional bugs, please report them at +[https://gitlab.com/apparmor/apparmor/-/issues](https://gitlab.com/apparmor/apparmor/-/issues). + +# SEE ALSO + +apparmor(7), apparmor.d(5), and +[https://wiki.apparmor.net](https://wiki.apparmor.net). diff --git a/manpage_mod_apparmor.8.md b/manpage_mod_apparmor.8.md new file mode 100644 index 0000000..cb3f503 --- /dev/null +++ b/manpage_mod_apparmor.8.md @@ -0,0 +1,100 @@ +# Navigation +Return to manpage [Index](ManPages) + + +# NAME + +mod\_apparmor - fine-grained AppArmor confinement for Apache + +# DESCRIPTION + +An AppArmor profile applies to an executable program; if a portion of +the program needs different access permissions than other portions, +the program can "change hats" via aa\_change\_hat(2) to a different role, +also known as a subprofile. The mod\_apparmor Apache module uses the +aa\_change\_hat(2) mechanism to offer more fine-grained confinement of dynamic +elements within Apache such as individual php and perl scripts, while +still allowing the performance benefits of using mod\_php and mod\_perl. + +To use mod\_apparmor with Apache, ensure that mod\_apparmor is configured to +be loaded into Apache, either via a2enmod, yast or manual editing of the +apache2(8)/httpd(8) configuration files, and restart Apache. Make sure that +apparmor is also functioning. + +Once mod\_apparmor is loaded within Apache, all requests to Apache will +cause mod\_apparmor to attempt to change into a hat that matches the +ServerName for the server/vhost. If no such hat is found, it will +first fall back by attempting to change into a hat composed of the +ServerName-URI (e.g. "www.example.com-/app/some.cgi"). If that hat +is not found, it will fall back to attempting to use the hat named +by the URI (e.g. "/app/some.cgi"). If that hat is not found, it will +fall back to attempting to use the hat DEFAULT\_URI; if that also does +not exist, it will fall back to using the global Apache profile. Most +static web pages can simply make use of the DEFAULT\_URI hat. + +Additionally, before any requests come in to Apache, mod\_apparmor +will attempt to change hat into the HANDLING\_UNTRUSTED\_INPUT hat. +mod\_apparmor will attempt to use this hat while Apache is doing the +initial parsing of a given http request, before its given to a specific +handler (like mod\_php) for processing. + +Because defining hats for every URI/URL often becomes tedious, mod\_apparmor +provides the AAHatName and AADefaultHatName Apache configuration options. + +- **AAHatName** + + AAHatName allows you to specify a hat to be used for a given Apache + , , or + directive (see the Apache documentation for more + details). Note that mod\_apparmor behavior can become confused if + and directives are intermingled + and it is recommended to use one type of directive. If the hat specified by + AAHatName does not exist in the Apache profile, then it falls back to the + behavior described above. + +- **AADefaultHatName** + + AADefaultHatName allows you to specify a default hat to be used for + virtual hosts and other Apache server directives, so that you can have + different defaults for different virtual hosts. This can be overridden + by the AAHatName directive and is checked for only if there isn't + a matching AAHatName. The default value of AADefaultHatName is the + ServerName for the server/vhost configuration. If the AADefaultHatName + hat does not exist, then it falls back to the behavior described above. + +# URI REQUEST SUMMARY + +When profiling with mod\_apparmor, it is helpful to keep the following order +of operations in mind: + +On each URI request, mod\_apparmor will first aa\_change\_hat(2) into +^HANDLING\_UNTRUSTED\_INPUT, if it exists. + +Then, after performing the initial parsing of the request, mod\_apparmor +will: + +1. try to aa\_change\_hat(2) into a matching AAHatName hat if it exists and +applies, otherwise it will +2. try to aa\_change\_hat(2) into an AADefaultHatName hat, either the +ServerName (the default) or the configuration value specified by the +AADefaultHatName directive, for the server/vhost, otherwise it will +3. try to aa\_change\_hat(2) into the ServerName-URI, otherwise it will +4. try to aa\_change\_hat(2) into the URI itself, otherwise it will +5. try to aa\_change\_hat(2) into the DEFAULT\_URI hat, if it exists, otherwise it +will +6. fall back to the global Apache policy + +# BUGS + +mod\_apparmor() currently only supports apache2, and has only been tested +with the prefork MPM configuration -- threaded configurations of Apache +may not work correctly. For Apache 2.4 users, you should enable the mpm\_prefork +module. + +There are likely other bugs lurking about; if you find any, please report +them at [https://gitlab.com/apparmor/apparmor/-/issues](https://gitlab.com/apparmor/apparmor/-/issues). + +# SEE ALSO + +apparmor(7), apparmor\_parser(8), aa\_change\_hat(2) and +[https://wiki.apparmor.net](https://wiki.apparmor.net).