Merge lp:~jdstrand/snappy/15.04-docs into lp:~snappy-dev/snappy/15.04-deprecated

[Jamie Strandboge]

[lp:~jdstrand/snappy/15.04-docs]

441. By Jamie Strandboge on 2015-05-26

clarify sentence regarding frameworks and origin

[David Callé (davidc3)]

lgtm!

review: Approve

=== modified file 'docs/frameworks.md'
--- docs/frameworks.md	2015-04-23 15:07:47 +0000
+++ docs/frameworks.md	2015-05-26 14:35:48 +0000
@@ -8,7 +8,8 @@
 * Frameworks provide a significant benefit for many users
 * Frameworks are delivered via snaps
 * Frameworks can be installed on the same system without conflicts
-* Frameworks typically will use a toplevel namespace
+* Frameworks are unique and multiple origins for a framework are not supported
+  (therefore frameworks must always be referred to without an `origin`)
 * Framework `binaries` may be used without appending the package name and
   these binary names are governed by the framework onboarding process (below)
 * Frameworks must not depend on other frameworks
@@ -65,15 +66,17 @@
 ## Usage
 ### framework yaml
 
-For frameworks, meta/package.yaml should contain something like:
+For frameworks, meta/package.yaml might contain something like:
 
     name: foo
     version: 1.1.234
+    vendor: "Some Person <[e-mail]>"
     type: framework
     services:
       - name: bar
         description: "desc for bar service"
         start: bin/bar
+        bus-name: com.example.foo
     binaries:
       - name: bin/baz
         description: "desc for baz binary"
@@ -82,6 +85,21 @@
 
 * `type: framework` - defines the type of snap this is
 
+#### DBus connection name
+For framework services that provide a DBus interface, use `bus-name` to specify
+the DBus connection name the service will bind to on the system bus (only
+`^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9][A-Za-z0-9_-]*)+$` is allowed). To
+preserve coinstallability, the `bus-name` should typically use the form of one
+of the following: `<name>`, `<name>.<service name>`, `<reverse domain>.<name>`
+or `<reverse domain>.<name>.<service name>`. In the above yaml, any of the
+following can be used:
+
+* `bus-name: foo`
+* `bus-name: foo.bar`
+* `bus-name: com.example.foo`
+* `bus-name: com.example.foo.bar`
+
+#### Security policy
 Frameworks will typically need specialized security policy. See `security.md`
 for details.
 

=== modified file 'docs/meta.md'
--- docs/meta.md	2015-04-22 13:42:03 +0000
+++ docs/meta.md	2015-05-26 14:35:48 +0000
@@ -1,7 +1,7 @@
 # Package metadata
 
 This document describes the meta data of a snappy package. All files
-are located under the `meta/` directory. 
+are located under the `meta/` directory.
 
 The following files are supported:
 
@@ -50,7 +50,7 @@
    * `caps`: (optional) list of additional security policies to add.
              See `security.md` for details
    * `security-template`: (optional) alternate security template to use
-                          instead of `default`. See `security.md` for details 
+                          instead of `default`. See `security.md` for details
    * `security-override`: (optional) high level overrides to use when
                           `security-template` and `caps` are not
                           sufficient.  See security.md for details
@@ -68,7 +68,8 @@
          * `port`: (optional) see above
          * `negotiable`: (optional) see above
    * `bus-name`: (optional) message bus connection name for the service.
-     May only be specified for snaps of 'type: framework' (see above).
+     May only be specified for snaps of 'type: framework' (see above). See
+     frameworks.md for details.
 
  * `binaries`: the binaries (executables) that the snap provides
    * `name`: (required) the name of the binary, the user will be able to
@@ -78,8 +79,8 @@
    * `caps`: (optional) see entry in `services` (above)
    * `security-template`: (optional) see entry in `services` (above)
    * `security-override`: (optional) see entry in `services` (above)
-   * `security-policy`: (optional) see entry in `services` (above)   
- 
+   * `security-policy`: (optional) see entry in `services` (above)
+
 ## license.txt
 
 A license text that the user must accept before the snap can be

=== modified file 'docs/security.md'
--- docs/security.md	2015-04-23 15:02:16 +0000
+++ docs/security.md	2015-05-26 14:35:48 +0000
@@ -8,16 +8,18 @@
 packages and builds upon the packaging declaration as defined in `meta.md`.
 
 ## How policy is applied
-Security policy is typically defined by declaring a security template and any
-additional security groups to extend the policy provided by the template. If
+Application authors should not have to know about or understand the lowlevel
+implementation details on how security policy is enforced. Instead, security
+policy is typically defined by declaring a security template to use and any
+additional security caps to extend the policy provided by the template. If
 unspecified, default confinement allows the snap to run as a network client.
 
 Applications are tracked by the system by using the concept of an
 ApplicationId. The `APP_ID is` the composition of the package name, the app's
-origin namespace from the store (if applicable-- only snaps of `type: app` (the
-default) have an origin namespace as part of their `APP_ID`), the
+origin from the store if applicable -- only snaps of `type: app` (the
+default) use an origin to compose the `APP_ID`), the
 service/binary name and package version. The `APP_ID` takes the form of
-`<pkgname>.<namespace>_<appname>_<version>`. For example, if this is in
+`<pkgname>.<origin>_<appname>_<version>`. For example, if this is in
 `package.yaml`:
 
     name: foo
@@ -27,23 +29,34 @@
       - name: bar
         start: bin/bar
 
-and the app was uploaded to the `myorigin` namespace in the store, then the
+and the app was uploaded to the `myorigin` origin in the store, then the
 `APP_ID` for the `bar` service is `foo.myorigin_bar_0.1`. The `APP_ID` is used
 throughout the system including in the enforcement of security policy by the
-app launcher. The launcher will:
-
-* setup various environment variables (eg, `SNAP_APP_ARCH`,
+app launcher.
+
+Under the hood, the launcher:
+
+* sets up various environment variables (eg, `SNAP_APP_ARCH`,
   `SNAP_APP_DATA_PATH`, `SNAP_APP_PATH`, `SNAP_APP_TMPDIR`,
   `SNAP_APP_USER_DATA_PATH`, `SNAP_OLD_PWD`, `HOME` and `TMPDIR` (set to
   `SNAP_APP_TMPDIR`). See the
    [snappy FHS](https://developer.ubuntu.com/en/snappy/guides/filesystem-layout/) for details.
-* chdir to `SNAP_APP_PATH` (the install directory)
-* setup a device cgroup and add any devices which are assigned to this app
-* setup the seccomp filter
-* exec the app under AppArmor profile under a default nice value
-
-The launcher will be used when launching both services and when using CLI
-binaries. The launcher enforces application isolation as per the snappy FHS.
+* changes directory to `SNAP_APP_PATH` (the install directory)
+* sets up a device cgroup with default devices (eg, /dev/null, /dev/urandom,
+  etc) and any devices which are assigned to this app via OEM snaps or
+  `snappy hw-assign` (eg, `snappy hw-assign foo.myorigin /dev/bar`).
+* sets up the seccomp filter
+* executes the app under an AppArmor profile under a default nice value
+
+The launcher is used when launching both services and CLI binaries. The
+security policy and launcher enforce application isolation as per the snappy
+FHS.
+
+This combination of restrictive AppArmor profiles (which mediate file access,
+application execution, Linux capabilities(7), mount, ptrace, IPC, signals,
+coarse-grained networking), clearly defined application-specific filesystem
+areas, whitelist syscall filtering via seccomp and device cgroups provides for
+strong application confinement and isolation (see below for future work).
 
 ### AppArmor
 Upon snap package install, `package.yaml` is examined and AppArmor profiles are
@@ -68,14 +81,14 @@
   Specify `caps: []` to indicate no additional `caps`.  When `caps` and
   `security-template` are not specified, `caps` defaults to client networking.
   Not compatible with `security-override` or `security-policy`.
- * AppArmor access is deny by default and apps are restricted to their
-   app-specific directories, libraries, etc (enforcing ro, rw, etc).
-   Additional access beyond what is allowed by the declared `security-template`
-   is declared via this option
- * seccomp is deny by default. Enough safe syscalls are allowed so that apps
-   using the declared `security-template` should work. Additional access
-   beyond what is allowed by the `security-template` is declared via this
-   option
+    * AppArmor access is deny by default and apps are restricted to
+      their app-specific directories, libraries, etc (enforcing ro,
+      rw, etc).  Additional access beyond what is allowed by the
+      declared `security-template` is declared via this option
+    * seccomp is deny by default. Enough safe syscalls are allowed so
+      that apps using the declared `security-template` should
+      work. Additional access beyond what is allowed by the
+      `security-template` is declared via this option
 * `security-template`: (optional) alternate security template to use instead of
   `default`. When specified without `caps`, `caps` defaults to being empty. Not
   compatible with `security-override` or `security-policy`.
@@ -84,13 +97,13 @@
   [advanced usage](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement)
   for details. Not compatible with `caps`, `security-template` or
   `security-policy`
- * `apparmor: path/to/security.override`
- * `seccomp: path/to/filter.override`
+    * `apparmor: path/to/security.override`
+    * `seccomp: path/to/filter.override`
 * `security-policy`: (optional) hand-crafted low-level raw security policy to
   use instead of using default template-based security policy. Not compatible
   with `caps`, `security-template` or `security-override`.
- * `apparmor: path/to/profile`
- * `seccomp: path/to/filter`
+    * `apparmor: path/to/profile`
+    * `seccomp: path/to/filter`
 
 Eg, consider the following:
 
@@ -116,7 +129,7 @@
       - name: cli-exe
         caps: []
 
-If this package is uploaded to the store in the `myorigin` namespace, then:
+If this package is uploaded to the store in the `myorigin` origin, then:
 
 * `APP_ID` for `bar` is `foo.myorigin_bar_1.0`. It uses the `default` template
   and `network-client` (default) cap
@@ -157,24 +170,51 @@
 The available templates and policy groups of the target system can be seen by
 running `snappy-security list` on the target system.
 
+## Debugging
+To check to see if you have any denials:
+
+    $ sudo grep audit /var/log/syslog
+
+An AppArmor denial will look something like:
+
+    audit: type=1400 audit(1431384420.408:319): apparmor="DENIED" operation="mkdir" profile="foo_bar_0.1" name="/var/lib/foo" pid=637 comm="bar" requested_mask="c" denied_mask="c" fsuid=0 ouid=0
+
+If there are no AppArmor denials, AppArmor isn't blocking the app.
+
+A seccomp denial will look something like:
+
+    audit: type=1326 audit(1430766107.122:16): auid=1000 uid=1000 gid=1000 ses=15 pid=1491 comm="env" exe="/bin/bash" sig=31 arch=40000028 syscall=983045 compat=0 ip=0xb6fb0bd6 code=0x0
+
+The `syscall=983045` can be resolved with the `scmp_sys_resolver` command:
+
+    $ scmp_sys_resolver 983045
+    set_tls
+
+If there are no seccomp denials, seccomp isn't blocking the app.
+
+For more information, please see
+[debugging](https://wiki.ubuntu.com/SecurityTeam/Specifications/SnappyConfinement#Debugging).
+
 ## Future
 The following is planned:
 
 * launcher:
- * setup additional cgroups (tag network traffic, memory)
- * setup iptables using cgroup tags (for internal app access)
- * drop privileges to uid of service
+    * utilize syscall argument filtering
+    * setup additional cgroups (tag network traffic, memory)
+    * setup iptables using cgroup tags (for internal app access)
+    * drop privileges to uid of service
+* fine-grained network mediation via AppArmor
 * `sockets`: (optional) `AF_UNIX` abstract socket definition for coordinated
   snap communications. Abstract sockets will be namespaced and yaml is such
   that (client) apps wanting to use the socket don't have to declare anything
   extra, but they don't have access unless the (server) binary declaring the
   socket says that app is ok).
- * `names`: (optional) list of abstract socket names (`<name>_<binaryname>` is
-   prepended)
- * `allowed-clients`: `<name>.<namespace>` or `<name>.<namespace>_<binaryname>`
-   (ie, omit version and `binaryname` to allow all from snap
-   `<name>.<namespace>` or omit version to allow only `binaryname` from snap
-   `<name>`)
+    * `names`: (optional) list of abstract socket names
+      (`<name>_<binaryname>` is prepended)
+    * `allowed-clients`: `<name>.<origin>` or
+     `<name>.<origin>_<binaryname>` (ie, omit version and
+     `binaryname` to allow all from snap `<name>.<origin>` or omit
+     version to allow only `binaryname` from snap `<name>`)
 
  Eg: