Manifest

Differences between revisions 13 and 14
Revision 13 as of 2013-07-05 13:29:26
Size: 9509
Editor: jdstrand
Comment:
Revision 14 as of 2013-07-05 20:34:15
Size: 9963
Editor: jdstrand
Comment:
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:
with each subkey being the name of a profile object (also a dictionary). The '''aa-easyprof''' tool is used to
parse the security section of the manifest and generate an !AppArmor profile.
'''aa-easyprof''' will be used by click via a hook to install !AppArmor policy.
For more details on '''aa-easyprof''', see `man 8 aa-easyprof`. An example
manifest representing all possible keys is: {{{
with currently only one key defined: 'profiles'. The profiles object is a
dictionary each of its keys
being the name of a profile object
(also a dictionary). The '''aa-easyprof''' tool is used to parse the security
section of the manifest and generate an !AppArmor profile.  '''aa-easyprof'''
will be used by click via a hook to install !AppArmor policy.  For more details
on '''aa-easyprof''', see `man 8 aa-easyprof`. An example manifest representing
all possible keys is: {{{
Line 15: Line 17:
  "name": "Name used by click",
  "version": "Version used by click>",
  "name": "Name used by click (reverse domain name)",
  "version": "Version used by click",
  "maintainer": "Your Name <email@example.com
>",
  "title": "Display name (translatable)",
Line 19: Line 23:
    "com.example.foo": {
      "abstractions": [
        "audio",
        "gnome"
      ],
      "author": "Your Name",
      "binary": "/opt/foo/**",
      "comment": "Unstructured single-line comment",
      "copyright": "Unstructured single-line copyright statement",
      "name": "My Foo App",
      "policy_groups": [
        "networking",
        "user-application"
      ],
      "policy_vendor": "somevendor",
      "policy_version": 1.0,
      "read_path": [
        "/tmp/foo_r",
        "/tmp/bar_r/"
      ],
      "template": "user-application",
      "template_variables": {
        "APPNAME": "foo",
        "APPVERSION": "0.1",
        "VAR1": "bar",
        "VAR2": "baz"
      },
      "write_path": [
        "/tmp/foo_w",
        "/tmp/bar_w/"
      ]
    "profiles": {
  
"com.example.foo": {
        "abstractions": [
          "audio",
          "gnome"
        ],
        "author": "Your Name",
   "binary": "/opt/foo/**",
        "comment": "Unstructured single-line comment",
   "copyright": "Unstructured single-line copyright statement",
        "name": "My Foo App",
        "policy_groups": [
          "networking",
          "user-application"
        ],
        "policy_vendor": "somevendor",
   "policy_version": 1.0,
        "read_path": [
          "/tmp/foo_r",
          "/tmp/bar_r/"
        ],
        "template": "user-application",
        "template_variables": {
   "APPNAME": "foo",
   "APPVERSION": "0.1",
          "VAR1": "bar",
          "VAR2": "baz"
        },
        "write_path": [
          "/tmp/foo_w",
          "/tmp/bar_w/"
        ]
      }
Line 56: Line 62:
aa-easyprof is a general purpose tool and all of the security keys within a profile object are optional.
 * '''profile name''': keys to the 'security' dictionary are the profile names for each profile object. Therefore in the above example, "com.example.foo" is the profile name and the contents of the "com.example.foo" dictionary represent the profile. The profile name may specify the normalized absolute path to the binary (with AARE (see `apparmor.d(8)`) or an name that contains '[a-zA-Z0-9 \.\-_]'.
aa-easyprof is a general purpose tool and all of the keys within a profile object are optional.
 * '''profile name''': keys to the 'profiles' dictionary are the profile names for each profile object. Therefore in the above example, "com.example.foo" is the profile name and the contents of the "com.example.foo" dictionary represent the profile. The profile name may specify the normalized absolute path to the binary (with AARE (see `apparmor.d(8)`) or an name that contains '[a-zA-Z0-9 \.\-_]'.
Line 74: Line 80:
Click packages in Ubuntu are required to run under application confinement and therefore the manifest file must contain a security section. As such, some fields are required, some unused and some are technically supported but dangerous and will red flag the package for manual review.
 * Required fields
  * JSON profile object (ie, the '''profile name''' key and its corresponding dictionary). In click on Ubuntu, the profile name shall be of the form '''<reverse domain>-<version>'''. The only exception is if the profile name is used to specify path-based attachment (where the version of the app is expected to be part of the absolute path)
  * '''policy_vendor''' should be set to '''ubuntu'''
Click packages in Ubuntu are required to run under application confinement and therefore the manifest file must contain a security section. When a click package is installed, a hook will be invoked on the package to process the manifest file and output an !AppArmor profile. This hook will setup some `aa-easyprof` fields automatically (such as policy_vendor). As such, some fields are required, some handled automatically, some unused and some are technically supported but dangerous and will red flag the package for manual review.
 * Required fields for each profile object in the profiles dictionary of the security object:
  * JSON profile object (ie, the '''profile name''' key and its corresponding dictionary). In click on Ubuntu, the profile name should specify the name of the desktop that launches the program that this profile is meant to protect. The only exception is if the profile name is used to specify path-based attachment (where the version of the app is expected to be part of the absolute path)
Line 79: Line 84:
  * '''binary''' - should be set as a '''recursive glob on the toplevel installation directory'''. Eg, if the app is installed to `/opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp`, then binary should be set to `/opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp/**`
Line 81: Line 85:
  * '''template_variables''' - the Ubuntu templates support setting the following variables:
   * '''APPNAME''' - typically the '''reverse domain''' (eg, com.ubuntu.developer.username.appname)
   * '''APPVERSION''' - application version
  * '''policy_groups''' - these are used to grant permissions to the app, such as networking, online accounts, content picking, etc. See `aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-policy-groups` for a complete list
  * '''policy_vendor''' - automatically set to '''ubuntu'''
  * '''template_variables''' - automatically sets the following:
   * '''APPNAME''' - set to '''name''' from the toplevel click manifest (eg, '''"APPNAME": "com.ubuntu.developer.username.myapp"''')
   * '''APPVERSION''' - set to '''version''' from the toplevel click manifest (eg, '''"APPVERSION": "0.1"''')
Line 85: Line 91:
  These are used to differentiate application paths. Eg, the resulting !AppArmor policy will have something like:{{{   These template variables are used to differentiate application paths. Eg, the resulting !AppArmor policy will have something like:{{{
Line 93: Line 99:
  * '''policy_groups''' - these are used to grant permissions to the app, such as networking, online accounts, content picking, etc. Some policy groups might always be used (and therefore pre-filled), such as `qmlscene` while others will only be used by some apps (eg, `qmlscene-webview` for HTML5 apps). See `aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-policy-groups` for a complete list
Line 103: Line 108:
  * binary may be set as a recursive glob on the toplevel installation directory. Eg, if the app is installed to `/opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp`, then binary could be legitimately set to `/opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp/**`. Not typically necessary
Line 107: Line 113:
     "com.ubuntu.developer.myusername.MyCoolApp-0.1": {
       "policy_groups": [
         "qmlscene",
         "qmlscene-sqlite",
         "sdk-base"
       ],
       "policy_vendor": "ubuntu",
       "policy_version": 1.0,
       "template": "ubuntu-sdk",
       "template_variables": {
         "APPNAME": "MyCoolApp"
         "APPVERSION": "0.1"
     "profiles": {
       "com.ubuntu.developer.myusername.MyCoolApp-0.1": {
         "policy_groups": [
           "networking",
         ],
         "policy_version": 1.0,
         "template": "ubuntu-sdk"

Manifest file - security (draft)

http://bazaar.launchpad.net/~click-hackers/click/trunk/view/head:/doc/file-format.rst discusses the manifest file format for click packages in general. This page discusses the security section of the JSON manifest. Click packages will contain the toplevel 'security' key, and the 'security' object is a dictionary with currently only one key defined: 'profiles'. The profiles object is a dictionary each of its keys being the name of a profile object (also a dictionary). The aa-easyprof tool is used to parse the security section of the manifest and generate an AppArmor profile. aa-easyprof will be used by click via a hook to install AppArmor policy. For more details on aa-easyprof, see man 8 aa-easyprof. An example manifest representing all possible keys is:

{
  "name": "Name used by click (reverse domain name)",
  "version": "Version used by click",
  "maintainer": "Your Name <email@example.com>",
  "title": "Display name (translatable)",
  "framework": "Framework used by click",
  "security": {
    "profiles": {
      "com.example.foo": {
        "abstractions": [
          "audio",
          "gnome"
        ],
        "author": "Your Name",
        "binary": "/opt/foo/**",
        "comment": "Unstructured single-line comment",
        "copyright": "Unstructured single-line copyright statement",
        "name": "My Foo App",
        "policy_groups": [
          "networking",
          "user-application"
        ],
        "policy_vendor": "somevendor",
        "policy_version": 1.0,
        "read_path": [
          "/tmp/foo_r",
          "/tmp/bar_r/"
        ],
        "template": "user-application",
        "template_variables": {
          "APPNAME": "foo",
          "APPVERSION": "0.1",
          "VAR1": "bar",
          "VAR2": "baz"
        },
        "write_path": [
          "/tmp/foo_w",
          "/tmp/bar_w/"
        ]
      }
    }
  }
}

Security keys

aa-easyprof is a general purpose tool and all of the keys within a profile object are optional.

  • profile name: keys to the 'profiles' dictionary are the profile names for each profile object. Therefore in the above example, "com.example.foo" is the profile name and the contents of the "com.example.foo" dictionary represent the profile. The profile name may specify the normalized absolute path to the binary (with AARE (see apparmor.d(8)) or an name that contains '[a-zA-Z0-9 \.\-_]'.

  • binary: path to binary for this policy when using path-based attachment. Should not be specified when the profile name is an absolute path

  • author: author of the policy

  • comment: comment for the policy

  • copyright: copyright of the policy

  • name: name of policy. If not specified, use the name of the binary. Note, this is not the AppArmor profile name.

  • policy_vendor: vendor of policy groups and templates ([a-zA-Z_0-9\-\.])

  • policy_version: version of the vendor policy (float)

  • template: template to use ([a-zA-Z_0-9\-\.])

  • template_variables: list of template variable assignments. Supported template variables are template-specific

  • abstractions: list of AppArmor abstractions to include (typically from /etc/apparmor.d)

  • policy_groups: list of AppArmor policy groups to include ([a-zA-Z_0-9\-\.])

  • read_path: list of paths to allow read access

  • write_path: list of paths to allow write access

Use in Ubuntu

Click

Click packages in Ubuntu are required to run under application confinement and therefore the manifest file must contain a security section. When a click package is installed, a hook will be invoked on the package to process the manifest file and output an AppArmor profile. This hook will setup some aa-easyprof fields automatically (such as policy_vendor). As such, some fields are required, some handled automatically, some unused and some are technically supported but dangerous and will red flag the package for manual review.

  • Required fields for each profile object in the profiles dictionary of the security object:
    • JSON profile object (ie, the profile name key and its corresponding dictionary). In click on Ubuntu, the profile name should specify the name of the desktop that launches the program that this profile is meant to protect. The only exception is if the profile name is used to specify path-based attachment (where the version of the app is expected to be part of the absolute path)

    • policy_version should be set. 1.0 is the first supported Ubuntu policy version. For other versions, see /usr/share/apparmor/easyprof/templates/ubuntu/ and /usr/share/apparmor/easyprof/policygroups/ubuntu/

    • template - defaults to 'default' which is a symlink to ubuntu-sdk. See aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-templates (using the appropriate vendor version) for a list of other templates

    • policy_groups - these are used to grant permissions to the app, such as networking, online accounts, content picking, etc. See aa-easyprof --policy-vendor=ubuntu --policy-version=1.0 --list-policy-groups for a complete list

    • policy_vendor - automatically set to ubuntu

    • template_variables - automatically sets the following:

      • APPNAME - set to name from the toplevel click manifest (eg, "APPNAME": "com.ubuntu.developer.username.myapp")

      • APPVERSION - set to version from the toplevel click manifest (eg, "APPVERSION": "0.1")

      These template variables are used to differentiate application paths. Eg, the resulting AppArmor policy will have something like:

       @{APPNAME}="com.ubuntu.developer.username.myapp"
       @{APPVERSION}="0.1"
       ...
         /opt/click.ubuntu.com/@{APPNAME}/@{APPVERSION}/    r,
         /opt/click.ubuntu.com/@{APPNAME}/@{APPVERSION}/**  r,
         /opt/click.ubuntu.com/@{APPNAME}/@{APPVERSION}/**/ r,
  • Unused/ignored
    • name
    • author
    • comment
    • copyright
  • Red-flagged for manual review (use should actively be discouraged with updates made to policy groups and templates)
    • abstractions
    • read_path
    • write_path
    • binary may be set as a recursive glob on the toplevel installation directory. Eg, if the app is installed to /opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp, then binary could be legitimately set to /opt/com.ubuntu.developer/com.ubuntu.developer.username.myapp/**. Not typically necessary

An example manifest for an Ubuntu click package might be:

 {
   "security": {
     "profiles": {
       "com.ubuntu.developer.myusername.MyCoolApp-0.1": {
         "policy_groups": [
           "networking",
         ],
         "policy_version": 1.0,
         "template": "ubuntu-sdk"
       }
     }
   }
 }

Traditional packaging

Traditional packaging can also leverage aa-easyprof, but the process is slightly more involved. In general, the following need to happen (see man dh_apparmor for details):

  • the manifest file (only the security section is needed) is added to debian/. Because traditional packaging has different governance rules for including in a distribution, the manifest may contain any of the supported fields
  • aa-easyprof is given the manifest file to generate a profile
  • the profile is installed into a package
  • the postinst loads the AppArmor policy into the kernel

The process is made easier with dh_apparmor. Create a manifest file following the above instructions then:

  1. put the manifest file in debian/manifest.json
  2. adjust debian/control to Build-Depends on dh-apparmor >= 2.8.0-0ubuntu14

  3. update debian/rules to call dh_apparmor. Eg:

    override_dh_install:
            dh_apparmor -p<deb binary> --profile-name=<profile name from the manifest> --manifest=manifest.json
            dh_install

    and then to clean up:

    override_dh_clean:
            dh_clean
            rm -rf debian/apparmor
  4. install the files. Eg, add to debian/<deb binary>.install:

    debian/apparmor/<profile name> etc/apparmor.d

The remaining consideration is making sure that the app runs confined. You'll know you have it right if when the application is running, the output of aa-status shows that the application is confined. If the application provides an executable (eg, ELF binary, executable python script), then specifying the 'binary' in the manifest is enough. If instead a helper such as qmlscene is being used, there are several choices:

  • use the new Ubuntu application lifecycle and start the application via an Upstart job (preferred, pending but not available as of 2013/07/02)
  • add XCanonicalAppArmorProfile=<profile name> to the .desktop file until Ubuntu application lifecycle is finished (not available as of 2013/07/02)

  • update the .desktop file so use aa-exec -p <profile name> ... in the Exec line. Unfortunately there is an issue using aa-exec in .desktop files, which may be related to glib

  • Create a shell script to use aa-exec -p <profile name> ... and have the .desktop file use Exec=<path to shell script>

Bugs

When filing bugs dealing with the manifest file or resulting permissions, please use one of the below and use the 'application-confinement' tag:

SecurityTeam/Specifications/ApplicationConfinement/Manifest (last edited 2014-03-17 13:57:55 by jdstrand)