Specifications and snippets
sandbox internals for snapd developers
Each security backend builds a fresh specification of one snap by letting the interface repository replay the snap's slots, plugs and connections into it. An interface contributes by having a method named after the backend and the case, such as AppArmorConnectedPlug, which adds snippets scoped to the security tags of the apps and hooks bound to that plug. The backend then fills a template with the snippets, one profile file per tag.
On the map: sandbox internals district
▶ Watch this deck — 8 scenes, ~6 min
Part of journeys
- From interfaces to AppArmor and back, step 2 of 13 · previous: Setting up a snap's security · next: The security backends
01 From a connection to a profile file
For each backend, snapd builds a specification of the snap from its plugs, slots and connections. Snippets are filed per app or hook, then fill the backend's template: one profile file per security tag.
Open the agent's AppArmor profile and most of it is boilerplate. So where does the part about the meter come from? Start with acme-agent: its network plug and its meter plug, both connected. For each security backend, snapd builds a fresh, empty specification of the snap, and lets every plug, slot and connection add its snippets. Network adds rules for sockets, then meter adds rules for serial-ports, each filed under the app it belongs to. The template is shared boilerplate with one hole. The snippets drop in, and out comes one profile per app and per hook. Change anything, and it's all built again from scratch.
02 "The repository walk: four calls" for snapd developers
SnapSpecification calls AddPermanentSlot, AddConnectedSlot, AddPermanentPlug and AddConnectedPlug on the backend's new spec, under the repository lock. The first error aborts the walk and nothing is written.
Here's the walk inside. Each backend's Setup makes one call into the repository: SnapSpecification. It finds the backend by name and asks it for a new, empty specification. Then it walks the snap, slots first. For each slot it calls AddPermanentSlot once, and AddConnectedSlot once per connection. acme-agent has no slots. Then the plugs: AddPermanentPlug for network, and AddConnectedPlug for its connection to snapd. The same for meter and its gadget slot. Two plugs, four calls. With AppArmor there are eleven backends, so one setup walks the snap eleven times. The first error ends the walk: that backend writes nothing.
03 Does the interface have the method? for snapd developers
Each Add… method type-asserts against a local definer interface, for example one with AppArmorConnectedPlug. Only ldconfig, configfiles and symlinks use an exported type, ConnectedPlugCallback. commonInterface fields such as connectedPlugAppArmor and connectedPlugSecComp become those methods; network is only such a literal.
How does a specification know what an interface contributes? It doesn't ask. Each add method declares, right in its body, a one-method interface with the name it wants, here AppArmorConnectedPlug, and checks whether the interface value has it. If it does, the spec narrows itself to the right security tags and calls it. Network is just a commonInterface value with two strings in it, and the struct's own methods add them. serial-port writes its methods by hand, and has no seccomp method at all. There's no registry and, for most backends, no exported type to implement, so a misspelled method is quietly skipped, with no error.
04 Tags decide where a snippet lands for snapd developers
Tags: snap.<instance>.<app>, snap.<instance>.hook.<hook>, snap.<instance>+<component>.hook.<hook>. The spec scopes each call to the tags bound to the plug or slot; the udev tag replaces . with _ and + with __.
Snippets don't go into one big pile. Every profile file belongs to one security tag: one for the agent, one for the configure hook, one for the remove hook. So before calling an interface, the spec narrows its scope to the tags that plug is bound to. Network is declared at the top level and listed nowhere else, so it's bound to everything: the daemon and both hooks get its rules. Meter is listed under the agent, so only the agent's profile gets the serial rule. The udev backend uses the same tag, --dots turned into underscores, to mark the meter's device for the agent alone.
05 Permanent and connected snippets for snapd developers
Permanent definers get snap.PlugInfo or snap.SlotInfo; connected ones get ConnectedPlug and ConnectedSlot with static and dynamic attributes of both sides. Current behaviour: serial-port validates filepath.Clean(path) but writes the raw path into the udev rule, so an unclean path matches no device. The vendor and product values are examples.
Snippets come in two kinds. Permanent ones depend only on a plug or slot existing. So the gadget's meter slot writes its udev symlink rule as soon as the gadget is set up, connected or not. Connected ones run once per connection and see both ends. The agent gets a serial rule in AppArmor, and a udev rule built from the gadget's vendor and product numbers. Disconnect, and the next setup finds no connection: the agent's rules are gone, the gadget's stay. One catch in serial-port: a path-only slot is checked after cleaning the path, but the rule gets it raw, so an unclean path matches no device.
06 The AppArmor template, placeholder by placeholder for snapd developers
Template by base and confinement; ###VAR###, ###PROFILEATTACH###, ###FLAGS###, then ###SNIPPETS### (sorted, then de-duplicated and parametric snippets) last before }. AddUpdateNS text goes to snap-update-ns.<instance>. Under classicTemplate interface snippets are ignored.
Watch the agent's AppArmor profile being made. First the backend picks a template by the snap's base and its confinement. For a classic snap it would pick one that ignores every interface snippet. Then it replaces each placeholder in turn. The variables get the snap's name and revision. The attach line gets the security tag, and the flags get the defaults, plus complain in devmode. Last, just before the closing brace, come the snippets, sorted as text, with de-duplicated and parametric rules after them, so their order follows the text, not the order of connections. The rules that snap-update-ns needs go to a separate profile of their own.
07 "Seccomp: concatenate, then compile" for snapd developers
<tag>.src is the version header, an optional @complain or @unrestricted, defaultTemplate, the sorted snippets, the uid/gid syscalls and workarounds. Changed sources are compiled to <tag>.bin2; snap-confine loads it at the next start.
Seccomp is simpler. There are no placeholders, just pieces put together in a fixed order. The compiler's version comes first, so a new snap-seccomp changes every file and every filter gets rebuilt. Then a mode line: complain for devmode, unrestricted for classic, nothing for a strict snap like the agent. Then the template. Then the snippets, sorted. For the agent that's network's system calls, and nothing from meter. Then the calls for switching users and groups. Only a source that changed is compiled into a binary filter, and snap-confine loads it the next time the agent starts.
08 Where to go from here
Roads: the security backends, setting up a snap's security, the home interface, interfaces by classification, buses and boards, confinement, and how hooks work.
A specification is a fresh collection of snippets, filed by tag and poured into a template. What each backend then does with its files is in the security backends. When a specification is built, and for which snaps, is in setting up a snap's security. For one interface's snippets in full, see the home interface, and interfaces by classification groups all of them by how they're built. The gadget slots are in buses and boards. Confinement shows the profiles at work, and how hooks work explains how plugs are scoped to hooks.
Read more
The four calls
interfaces.Specification has four methods. Repository.SnapSpecification calls them on the new specification that the backend returns from NewSpecification(appSet, opts), under the repository lock.
| Method | Called | Receives |
|---|---|---|
AddPermanentSlot | once for each slot of the snap | *snap.SlotInfo: static attributes from snap.yaml |
AddConnectedSlot | once for each connection of that slot | *ConnectedPlug and *ConnectedSlot: static and dynamic attributes of both ends |
AddPermanentPlug | once for each plug of the snap | *snap.PlugInfo |
AddConnectedPlug | once for each connection of that plug | *ConnectedPlug and *ConnectedSlot |
Slots are walked first, then plugs. The walk ranges over Go maps, so the order of the calls changes from one walk to the next. The first error ends the walk and the backend reports cannot obtain <backend> specification for snap "<name>": <error>; nothing is written. Every backend's Setup makes its own walk, so one setup of a snap walks it eleven times when AppArmor is available, ten times without it.
A connection whose definer always fails stays in the in-memory repository, so every later setup of that snap fails the same way until snapd restarts (comment at interfaces/repo.go:965-978).
Definers
Each Add… method declares a local one-method interface and type-asserts the interface value against it. The method name is the backend prefix followed by PermanentPlug, PermanentSlot, ConnectedPlug or ConnectedSlot.
| Backend | Prefix |
|---|---|
| apparmor | AppArmor |
| seccomp | SecComp |
| udev | UDev |
| kmod | KMod |
| mount | Mount |
| dbus | DBus |
| systemd | Systemd |
| polkit | Polkit |
| ldconfig | Ldconfig |
| configfiles | Configfiles |
| symlinks | Symlinks |
Only ldconfig, configfiles and symlinks use an exported type for the plug side, ConnectedPlugCallback; their plug-side definers are accepted only for the system snap. A misspelled method name is not called and gives no error.
commonInterface turns string fields into definers: connectedPlugAppArmor, connectedPlugSecComp, connectedPlugUDev, connectedPlugUpdateNSAppArmor, connectedPlugMount, the four …KModModules lists and flags such as suppressHomeIx and controlsDeviceCgroup. It has plug-side connected definers only for AppArmor, seccomp, udev and mount; slot-side rules need hand-written methods. network is only a commonInterface literal with connectedPlugAppArmor and connectedPlugSecComp. An interface that embeds commonInterface and writes its own AppArmorConnectedPlug hides the embedded one and must call it itself to keep the common fields.
Security tags
| Runnable | Tag | udev tag |
|---|---|---|
| app | snap.<instance>.<app> | snap_<instance>_<app> |
| hook | snap.<instance>.hook.<hook> | snap_<instance>_hook_<hook> |
| component hook | snap.<instance>+<component>.hook.<hook> | snap_<instance>__<component>_hook_<hook> |
The udev tag replaces . with _ and + with __. Before calling a definer, the spec sets its scope to the tags of the apps and hooks bound to the plug or slot, and restores it afterwards. A plug declared at the top level and listed under no app or hook is bound to every app and hook. Component hooks receive only such unscoped plugs. When the scope is empty, AddSnippet on the AppArmor, seccomp and dbus specs does nothing.
Some settings are per snap, not per tag, even when the plug is bound to one app: the AppArmor flags set by SetSuppressHomeIx, SetUsesPtraceTrace, SetSuppressPtraceTrace, SetUsesSysModuleCapability, SetSuppressSysModuleCapability and SetSuppressPycacheDeny, the udev SetControlsDeviceCgroup (which drops every udev rule of the snap), and all mount, kmod and polkit content.
for snapd developers
Recording methods
| Spec | Methods an interface may call |
|---|---|
| apparmor | AddSnippet, AddPrioritizedSnippet, AddDeduplicatedSnippet, AddParametricSnippet, AddUpdateNS, AddUpdateNSf, and the flag setters above |
| seccomp | AddSnippet |
| dbus | AddSnippet |
| udev | AddSnippet (untagged rule), TagDevice, TriggerSubsystem, SetControlsDeviceCgroup |
| mount | AddMountEntry, AddUserMountEntry, AddUserEnsureDirs |
| kmod | AddModule, SetModuleOptions, DisallowModule |
| systemd | AddService, AddDropIn |
| polkit | AddPolicy, AddRule |
| ldconfig | AddLibDirs |
| configfiles | AddPathContent |
| symlinks | AddSymlink |
The backends add more after the walk: AppArmor and mount add the parallel-instance, layout and extra-layout entries, and AppArmor adds its base prioritized snippets. These are not interface contributions.
TagDevice(snippet) adds, for each tag in scope, # <interface>, the snippet with , TAG+="<udev tag>" appended, and a rule that runs snap-device-helper for devices with that tag.
for snapd developers
Order and duplicates
| Container | Order in the output | Duplicates |
|---|---|---|
AppArmor AddSnippet, prioritized and base snippets | sorted as text | kept |
AppArmor AddDeduplicatedSnippet | insertion order, after the sorted block | merged |
AppArmor AddParametricSnippet | templates sorted; values in insertion order | values merged |
AppArmor AddUpdateNS | insertion order | merged by exact text |
seccomp AddSnippet | sorted as text | kept |
dbus AddSnippet | insertion order | kept |
udev AddSnippet, TagDevice | sorted by tag, then text | merged by exact text |
mount AddMountEntry | insertion order; a later different entry at the same mount point is renamed <dir>-2, <dir>-3 | merged if source and type match |
Insertion order is the order of the walk, which ranges over maps.
The AppArmor profile
addContent picks defaultCoreRuntimeTemplate for a core or coreNN base and defaultOtherBaseTemplate otherwise. A classic snap without jailmode gets classicTemplate, which ignores every interface snippet. The placeholders are replaced by function:
| Placeholder | Replaced by |
|---|---|
###VAR### | @{SNAP_NAME}, @{SNAP_INSTANCE_NAME}, @{SNAP_INSTANCE_DESKTOP}, @{SNAP_COMMAND_NAME}, @{SNAP_REVISION}, @{PROFILE_DBUS}, @{INSTALL_DIR} |
###PROFILEATTACH### | profile "<tag>" |
###FLAGS### | flags=(attach_disconnected,mediate_deleted), plus unconfined when requested and supported, or complain for devmode and classic without jailmode |
###SNIPPETS### | the tag's snippets, then extras such as the core snippet on Ubuntu Core and the remote-home and overlay-root snippets |
###SNIPPETS### is the last line before the closing brace. Inside the snippets, ###HOME_IX### becomes ix (or nothing if any interface of the snap suppressed it) and ###PROMPT### becomes prompt when prompting applies. The home interface's rule ###PROMPT### owner @{HOME}/[^s.]** rwkl###HOME_IX###, therefore ends up as owner @{HOME}/[^s.]** rwklix,.
One file per tag, mode 0644, in /var/lib/snapd/apparmor/profiles/. The AddUpdateNS text goes into one more profile, snap-update-ns.<instance>, which a classic snap also gets.
The seccomp source
/var/lib/snapd/seccomp/bpf/<tag>.src, mode 0644, is a concatenation:
1. # snap-seccomp version information: and the version line. 2. @unrestricted for classic without jailmode, @complain for devmode without jailmode. 3. defaultTemplate. 4. The tag's snippets, sorted, duplicates kept. A classic snap keeps its snippets here. 5. The uid and gid system calls, per system username where the snap has any. 6. The bind workaround when AppArmor support is not full, and the deprecated socketcall rules when the base needs them.
A changed .src is compiled by snap-seccomp to <tag>.bin2, which snap-confine loads when the app or hook starts. The .bin2 of a removed .src is deleted.
Other files
| Backend | File |
|---|---|
| udev | /etc/udev/rules.d/70-snap.<snap>.rules |
| mount | /var/lib/snapd/mount/snap.<snap>.fstab, one per snap |
What each backend writes and how it applies it is in The security backends.
Current behaviour to know
serial-port, hidraw, i2c and iio check the slot's path after filepath.Clean, but write the raw value into the rules. A slot with path: /dev/./ttyS1 is accepted and gives KERNEL=="./ttyS1", which matches no device. spi uses the cleaned path everywhere. These slots are limited to core and gadget snaps.
Not covered
The gateway example uses the invented snaps acme-agent and acme-gadget; the usb-vendor and usb-product values are examples. Which rules each interface adds is in the interface decks, not here.
Further reading
No published page describes how specifications are built.
- Security policies: the AppArmor and seccomp policies that the snippets fill.
- Snap confinement: strict, classic and devmode, which choose the template and the mode line.
- The network interface and the serial-port interface: the two interfaces followed in this deck.
- Debug snaps: reading the generated profiles and the denials they cause.
Roads from here
INTERFACES AND CONFINEMENT
- The home interface — one interface's AppArmor snippets in full
- Interfaces by classification — all interfaces grouped by how they are built
- Confinement — the profiles these snippets end up in
INTERFACE FAMILIES · every interface, grouped by what it touches
- Interfaces: buses and boards — the gadget slots whose attributes become rules
HOOKS · code snapd runs inside a snap
- Hooks: how they work — how plugs listed under apps and hooks are scoped
SANDBOX INTERNALS · the mount namespace
- The security backends — what each backend does with its finished specification
- Setting up a snap's security — when a specification is built and for which snaps