* '''Launchpad entry''': UbuntuSpec:security-p-app-isolation
 * '''Created''': 2012-02-07
 * '''Contributors''': jdstrand
 * '''Packages affected''': apparmor

To support the ARB and other projects, AppArmor should include a a standalone CLI application which can also be imported into developer SDKs.

== Rationale ==
Confining applications is desirable for many reasons, including security, protection from misbehaving applications, malicious software and reducing the burden of application review. The ARB have [[https://wiki.ubuntu.com/AppConfinement|discussed this to some extent]], but other projects including AppArmor's users would also benefit.

== User stories ==
 * Dan develops applications for Ubuntu and would like to add !AppArmor protection to his application. He would like to be able to state 'my application uses X but does not use networking' without having to know all the details about !AppArmor profiling.
 * Regina reviews packages for the ARB. Most applications currently require extensive code review, but if she receives an application with an !AppArmor profile, it could reduce some of the code review (eg, reduce it to networking and DBus interactions).

== Documentation ==
=== Usage ===
`aa-easyprof` is a standalone CLI application which can also be imported into developer SDKs. `aa-easyprof` supports the use of templates and policy groups to quickly profile an application. In essence, aa-easyprof takes a different view on policy generation and is useful when you already know how the application should behave and want to create an initial policy based on this behavior. As such, one can use a template and any appropriate policy groups (groupings of !AppArmor policy rules) then use aa-easyprof to generate a policy.
Currently the combination of the `user-application` template along with the `opt-application` and `user-application` policygroups should achieve a [[http://developer.ubuntu.com/publish/my-apps-packages/|working policy for Ubuntu's Application Review Board]]. Specify multiple arguments as desired (see `man aa-easyprof`), then the policy is generated, verified and sent to stdout. Eg:
{{{
$ aa-easyprof --template=user-application \
              --policy-groups=opt-application,user-application \
              --abstractions="python,audio" \
              --read-path="@{HOME}/Downloads/" \
              --write-path="/opt/@{APPNAME}/tmp/" \
              --write-path="/opt/@{APPNAME}/log/" \
              --template-var="@{APPNAME}=foo" \
              --author="Dan Doodongle" \
              --copyright="Copyright 2012, Dangling Doodongles Inc" \
              --comment="AppArmor is easy with aa-easyprof" \
              /opt/foo/bin/foo
# vim:syntax=apparmor
# AppArmor policy for foo
# Author: Dan Doodongle
# Copyright: Copyright 2012, Dangling Doodongles Inc
# Comment: AppArmor is easy with aa-easyprof

#include <tunables/global>

# Specified profile variables
@{APPNAME}=foo

/opt/foo/bin/foo {
  #include <abstractions/base>

  # Specified abstractions
  #include <abstractions/python>
  #include <abstractions/audio>

  # Rules specified via policy groups
  # Policy group for applications installed in /opt
  /opt/@{APPNAME}/ r,
  /opt/@{APPNAME}/** mrk,

  # Policy group allowing various writes to standard directories in @{HOMEDIRS}
  owner @{HOMEDIRS}/.cache/@{APPNAME}/ rw,
  owner @{HOMEDIRS}/.cache/@{APPNAME}/** rwkl,
  owner @{HOMEDIRS}/.config/@{APPNAME}/ rw,
  owner @{HOMEDIRS}/.config/@{APPNAME}/** rwkl,
  owner @{HOMEDIRS}/.local/share/@{APPNAME}/ rw,
  owner @{HOMEDIRS}/.local/share/@{APPNAME}/** rwkl,

  # Specified read permissions
  @{HOME}/Downloads/ r,
  owner @{HOME}/Downloads/** r,

  # Specified write permissions
  /opt/@{APPNAME}/tmp/ rwk,
  /opt/@{APPNAME}/tmp/** rwk,
  /opt/@{APPNAME}/log/ rwk,
  /opt/@{APPNAME}/log/** rwk,
}
}}}

Templates can also be specified using an absolute path like `aa-easyprof --template=~/my-cool-template ...`.
Also see `man aa-easyprof` for more information.

=== SDK integration ===
 
While `aa-easyprof` is a CLI application which outputs its policy on stdout. It is written in python and implemented as a library and requires no special privileges to use. This means that SDKs can either use `aa-easyprof` directly or import `aparmor.easyprof`. Eg:{{{
import apparmor.easyprof
from apparmor.easyprof import AppArmorException, error
...
class FooSDK(...):
    ...
    def __init__(self, binary):
        ...
        self.conffile = "<path>/sdk/aa-easyprof.conf"
        ...

    def cmd(self, template, pgroups, abstractions, ...):
        ...
        args = ['-c', self.conffile, '-t', template, '-p', pgroups, '-a', abstractions, ...]
        try:
            (options, args) = apparmor.easyprof.parse_args(args + [binary])
        except AppArmorException:
            raise
        except Exception:
            raise

        easyp = apparmor.easyprof.AppArmorEasyProfile(binary, options)
        params = apparmor.easyprof.gen_policy_params(binary, options)
        policy = easyp.gen_policy(**params)
        ...
}}}
See `utils/test/test-aa-easyprof.py` for examples on some of the ways easyprof.py can be used.

SDKs can simply drop files into the system wide `/usr/share/apparmor/easyprof/templates` and `/usr/share/apparmor/easyprof/policygroups` to make them readily available, or they can setup their own templates and policygroups directories and pass '--templates-dir' and '--policy-groups-dir' as arguments to `-aa-easyprof` or `apparmor.easyprof.parse_args`.

----
CategorySpec