AppArmor prompting

permission prompts for users for administrators for snapd developers

With the experimental apparmor-prompting feature on the home and camera rules ask the user instead of allowing outright and audio-record is asked through snapd. snapd answers each request from the user's stored rules or records a prompt that a client snap in the session answers. A reply can become a rule for the session or for a set time or forever.

On the map: desktop district

▶ Watch this deck — 8 scenes, ~6 min

01 An allow that asks first

PROMPTING feature offphoto-editorhome: allowed at oncecat.jpg in Pictures feature onphoto-editorcat.jpg in Picturesthe open call waits Allow photo-editorto read cat.jpg? onceuntil you log outfor a set timealways an answer that lasts becomes a rule; the next request is answered without asking experimental, and off unless you switch it on
Two rows: with the feature off photo-editor reads cat.jpg in Pictures at once through the home interface; with the feature on the same read stops at a question, Allow photo-editor to read cat.jpg?, whose answer can last once, until you log out, for a set time or always; an answer that lasts becomes a rule

With AppArmor prompting on, access that the home interface would allow at once becomes a question to the user. An answer can apply once, until logout, for a set time or always; the last three are stored as rules.

You've just installed photo-editor and you open a picture of your cat. Normally it just opens, because with the home interface connected the app may read every non-hidden file in your home folder. It's all or nothing. What if it had to ask first? With AppArmor prompting, the rule that would allow the read asks you instead, and photo-editor's open call simply waits while you decide. Your answer can last once, until you log out, for a set time, or always. An answer that lasts is kept as a rule, so the next read is answered without asking. The feature is experimental, and off unless you switch it on.

02 Turning it on for administrators for snapd developers

SWITCHING IT ON $ sudo snap set systemexperimental.apparmor-prompting=true cannot enable prompting feature: no interfacesrequests handler services are installed, considerinstalling the 'prompting-client' snap $ sudo snap install prompting-client$ sudo snap set systemexperimental.apparmor-prompting=truea client: a snap-interfaces-requests-control plugwhose handler-service is a user service handler service startedin each user sessionchange: service-control snapd restartswhenever the flag changes, on or offAppArmor probed again,profiles regenerated Ubuntu Core: refused. Classic and Core Desktop only.snapd starts with the flag on and no client: a warning; requests no rule settles are denied
A terminal: snap set system experimental.apparmor-prompting=true fails because no interfaces requests handler services are installed; after snap install prompting-client the same command works. snapd then starts handler services in each user session, restarts, and probes AppArmor and regenerates profiles. Ubuntu Core refuses the setting; with the flag on and no client snapd warns, and requests no stored rule settles are denied

snap set system experimental.apparmor-prompting=true needs a client snap with a handler service, starts that service in user sessions and restarts snapd. It is refused on Ubuntu Core. If snapd starts with the flag on and no client it warns, and requests that no stored rule settles are denied.

So you want the questions. It's one setting, snap set system experimental.apparmor-prompting=true, and the first try usually fails. Read the error: nobody is there to answer yet. Answers come from a client snap whose connected snap-interfaces-requests-control plug names a user service as its handler. Run snap install prompting-client and try again. snapd starts that service in each logged-in session, then restarts itself, as it does whenever the flag changes, because support is probed and profiles are regenerated at startup. And if snapd starts with the flag on but no client, it warns, and every request its stored rules don't settle is denied.

03 Three interfaces take part

WHO CAN ASK files in your homehomeread · write · execute the cameracameraaccess snapdAppArmor pauses the accessand asks snapd recording soundaudio-recordaccess sound serverasks on the app's behalf every other interface: allowed or denied as before, no question · each one must still be connected
Three interfaces can ask: home for files in your home with read, write and execute, and camera with access, both paused by AppArmor which asks snapd; audio-record with access, asked by the sound server on the app's behalf; every other interface is unchanged

home (read, write, execute) and camera (access) are mediated by AppArmor. audio-record (access) is asked through snapd by another process, expected to be the sound server. Other interfaces are unchanged, and prompting only narrows an interface that is already connected.

Which apps will ask you things? Three interfaces take part, and not all in the same way. Files in your home can be asked about for read, write and execute. The camera has one permission, access. For both, AppArmor in the kernel holds the access and passes the question to snapd. Recording sound is different: it isn't a file access AppArmor can hold. So the process that hands out audio, expected to be the sound server, asks snapd for the app and waits for allow or deny. snapd checks that the app has audio-record connected. Every other interface behaves as before, and each still has to be connected first.

04 The marker in the profile for snapd developers

ONE MARKER home.go, connected plug snippet###PROMPT### owner @{HOME}/ r,###PROMPT### owner @{HOME}/[^s.]** rwkl…,… flag offowner @{HOME}/ r, flag onprompt owner @{HOME}/ r, audit deny @{HOME}/bin/{,**} wl,no marker: unchanged camera.go###PROMPT### /dev/video[0-9]* rwk,###PROMPT### /dev/vchiq rw, decided once at startup: the flag and AppArmor support togetherthe system key records apparmor-prompting, so a change regenerates every profile
The home interface snippet starts its allow rules with the marker ###PROMPT###; with the flag off the backend removes it, with the flag on it becomes prompt; deny rules carry no marker; camera marks its two device rules the same way; the system key records apparmor-prompting

Rules that may ask start with ###PROMPT### in the interface's snippet. The AppArmor backend replaces it with prompt when prompting is in use and with nothing otherwise. The system key carries apparmor-prompting.

You might expect two home profiles, one that allows and one that asks. There's one, with a marker in it. In home.go, every owner rule that opens your home starts with the word PROMPT between three hash signs on each side. When the AppArmor backend writes the profile, it replaces that marker with the word prompt and a space if prompting is in use, and with nothing if it isn't. The deny rules carry no marker. Camera marks its two device rules the same way. Whether prompting is in use is decided once, at startup, and the system key records it, so a change regenerates every profile.

05 From request to prompt for administrators for snapd developers

ONE REQUEST photo-editorkernel (AppArmor)read cat.jpgthe call waits snapduid 0: denied, no prompt rules of uid 1000allowed · denied · outstanding a deny rule matched, or nothing outstanding:reply now, with the allowed permissions only prompt0000000000000012an identical waiting promptabsorbs the request prompting-clientinterfaces-requests-prompta notice; the client then fetches the promptno client has fetched prompts:expired within 10 seconds, denied
photo-editor reads cat.jpg; the kernel's AppArmor holds the call and asks snapd; requests from uid 0 are denied; snapd checks the rules of uid 1000, each permission allowed, denied or outstanding; a deny rule or nothing outstanding means an answer at once; otherwise a prompt is recorded or merged into an identical one, and an interfaces-requests-prompt notice tells prompting-client; with no client fetching, the prompt expires within 10 seconds

snapd denies requests from uid 0, answers at once when the user's rules settle every permission or a deny rule matches, and otherwise records a prompt and an interfaces-requests-prompt notice for the client.

Let's slow one read down. photo-editor asks for cat.jpg, and the kernel doesn't say yes or no. It asks snapd. A request from root is denied. For anyone else, snapd checks each requested permission against that user's rules, and each comes back allowed, denied or outstanding. If a deny rule matched, or nothing is outstanding, the kernel gets its answer at once: only the allowed permissions. Otherwise snapd records a prompt, or folds the request into an identical one already waiting. A notice keyed by the prompt's ID tells the client. If no client has fetched prompts, the prompt expires within ten seconds and the read is denied.

06 Your answer, and how long it lasts for users in place of the general version

YOUR ANSWER nowyou log outlater oncethis request only; nothing is remembered until you log out for a set time2 hours, for example alwaysthese three are remembered for you and for this app, allow or deny an answer for the whole Pictures folderalso settles other waiting questions always allow Pictures, deny cat.jpg:the more specific answer decides
A time line from now through you log out to later, with four answers: once remembers nothing, until you log out ends at log-out, for a set time ends after a chosen time such as two hours, always continues; an answer for a whole folder settles other waiting questions; when answers overlap the more specific one decides

An answer can apply once, until you log out, for a set time or always. Lasting answers are kept per user and per app, can cover a whole folder, and settle other waiting questions they cover. The more specific answer wins.

The question is on your screen. You're choosing two things: yes or no, and how long that answer should stand. Once answers this one request and leaves nothing behind, so the next open asks again. The others last until you log out, for a time you choose, or always. Those three are remembered for you and for this app, whether you allowed or denied. An answer can cover more than one file, say the whole Pictures folder, and then it also settles other questions already waiting. When two remembered answers overlap, the more specific one wins, so always allow Pictures and deny this one file can live side by side.

07 A reply becomes a rule general version

ONE REPLY $ snap debug api -X POST -H 'Content-Type: application/json' \/v2/interfaces/requests/prompts/0000000000000012 # the body, on stdin{"action": "allow", "lifespan": "forever", "constraints": {"path-pattern": "/home/alex/Pictures/**","permissions": ["read"]}} two checkspattern matches the pathall outstanding permissions 1 · rule addedrequest-rules.json 2 · kernel answeredthe read returns3 · other promptssatisfiedinterfaces-requests-rule-update lifespan single: no rule is stored, only the answerone file holds the rules of every user; each permission has its own outcome and lifespan
snap debug api posts a reply to /v2/interfaces/requests/prompts/0000000000000012 with action allow, lifespan forever and constraints path-pattern /home/alex/Pictures/** and permissions read; snapd checks it, adds a rule to request-rules.json, answers the kernel, then satisfies other waiting prompts; with lifespan single no rule is stored

POST /v2/interfaces/requests/prompts/{id} carries action, lifespan and constraints. snapd checks it against the prompt, adds a rule unless the lifespan is single, answers the kernel and applies the rule to other prompts.

Here's the same answer as the client snap sends it. There's no snap command for it, so by hand you use snap debug api, as snapd's own tests do. It's one POST to the prompt's own path, with an action, a lifespan and constraints. For home, those are a path pattern and a list of permissions. A reply can't answer a different question: the pattern must match the path that was asked for, and the permissions must include every outstanding one. The rule is added first, the kernel is answered second, and the rule is applied to your other waiting prompts last. With single, nothing is stored.

08 Where to go from here

ROADS The home interfacewhat prompting narrowsConfinementthe profile that carries the prompt rules What snapd tells desktop servicesa file from a file chooser: no second question Desktop files, icons and D-Bus activationhow photo-editor's launcher got theresnap userd: opening links and filesother questions a desktop snap can raiseThe user session agenthow the client's service starts in your session Warnings and noticeswhat a client waits for; the missing-client warningThe snapd REST APIsockets and access behind the endpoints
Roads from AppArmor prompting: the home interface, confinement, what snapd tells desktop services, desktop files, snap userd, the user session agent, warnings and notices, and the snapd REST API

Roads: the home interface, confinement, the four other desktop decks, warnings and notices, and the REST API.

That's a question, an answer and a rule. A few roads lead on from here. The home interface deck shows what prompting narrows, and confinement shows the profile the prompt rules live in. If you pick a file in a file chooser and no question appears, the deck on what snapd tells desktop services explains why. Desktop files, snap userd and the user session agent cover the rest of the desktop district, including how the client's service starts in your session. Warnings and notices covers what a client waits for, and the REST API deck covers the sockets behind it all.

Read more

for administrators for snapd developers

When prompting is supported

ConditionWhere it is checked
AppArmor kernel features contain policy:permstable32:promptsandbox/apparmor/apparmor.go:451-491
AppArmor parser features contain promptsame
when the kernel features contain policy:notify, they also contain policy:notify:user:filesame
/sys/kernel/security/apparmor/.notify existssame
kernel permissions table version is at least 2same
classic or Core Desktop, not Ubuntu Coreoverlord/configstate/configcore/prompting.go:120-122

The setting is experimental.apparmor-prompting. GET /v2/system-info reports features."apparmor-prompting" with supported and enabled. Prompting is in use when the flag is on and the system supports it; snapd decides this once, at startup.

for administrators for snapd developers

Messages when switching it on

TextMeaning
cannot enable prompting feature as it is not supported on Ubuntu Core systemsneither classic nor Core Desktop
cannot enable prompting feature as it is not supported by the system: <reason>a condition above failed, for example apparmor parser does not support the prompt qualifier
cannot enable prompting feature: no interfaces requests handler services are installed, consider installing the 'prompting-client' snapno connected plug names a handler service
cannot enable prompting, unable to start prompting handlers: …the service-control change that starts the handler services failed
warning: "apparmor-prompting" feature flag enabled but no prompting client is present; requests will be auto-denied until a prompting client is installedrecorded at snapd startup

Any change of the flag, on or off, restarts snapd, which probes AppArmor again and regenerates every profile.

for snapd developers

The client snap

  • Interface snap-interfaces-requests-control. Base declaration: plugs allow-installation: false and deny-auto-connection: true; the slot is on the system snap only. A snap needs a snap-declaration to plug it.
  • Plug attribute handler-service names an app of the same snap. It must be a service with daemon-scope: user, else declared handler service "<name>" is not a user service.
  • The connected plug may talk to com.canonical.Shell.PermissionPrompting at /com/canonical/Shell/PermissionPrompting on the session bus.
  • The same interface lets a snap read the two notice types and the icons endpoint (see what snapd tells desktop services).

for administrators for snapd developers

Interfaces and permissions

InterfacePermissionsMediated byAppArmor permissions
homereadAppArmorread, getattr
homewriteAppArmorwrite, append, create, delete, rename, setattr, chmod, lock, link
homeexecuteAppArmorexec, exec-mmap
cameraaccessAppArmorread, getattr, write, append
audio-recordaccessPOST /v2/interfaces/requests action ask-
  • In the home and camera snippets the rules that may ask start with ###PROMPT###. The AppArmor backend replaces the marker with prompt when prompting is in use and removes it otherwise. The system key carries apparmor-prompting.
  • When a kernel message has no tag that maps to an interface, the path decides: /dev/video* and /dev/vchiq are camera, everything else is home.
  • ask body: {"action":"ask","interface":"audio-record","pid":N}. snapd finds the snap from the PID's tracking cgroup, requires a connected audio-record plug of that snap, blocks until a reply and returns {"outcome":"allow"} or {"outcome":"deny"}. The code comment names WirePlumber as the expected caller; snapd does not yet check who the caller is.
  • The extra read rules that home adds for read: all carry no marker; how they combine with prompt rules was not determined (interfaces/builtin/home.go:89-101).

for administrators for snapd developers

A prompt

FieldValue
id16 hexadecimal digits
timestamp, snap, pid, cgroup, interfacewhere the request came from
constraintsfor home: path, requested-permissions, available-permissions

Lifespans

lifespanRule storedEnds
singlenowith the reply
sessionyeswhen you log out
timespanyesafter duration, a positive Go duration string such as 2h; required here and refused for the others
foreveryeswhen removed

for administrators for snapd developers

A rule

  • A reply is POST /v2/interfaces/requests/prompts/{id} with action (allow or deny), lifespan, duration for timespan, and constraints. Its path pattern must match the prompt's path and its permissions must include every outstanding permission.
  • Unless the lifespan is single, snapd adds the rule, then answers the kernel, then applies the rule to the user's other outstanding prompts. The response lists the prompt IDs the rule satisfied.
  • Fields: id, timestamp, user, snap, interface, constraints. For home the constraints are path-pattern and permissions; each permission has its own outcome, lifespan and expiration or session-id.
  • Path patterns start with /, contain no /./ or /../, no unescaped [ or ], and may expand through {a,b} groups to at most 1000 variants.
  • When several variants match a path the most specific one decides.
  • A session rule ends when /run/user/<uid> or its trusted.snapd_user_session_id attribute is gone.
  • A new rule with the same pattern and compatible outcomes is merged into the old one, the broader lifespan winning. The same variant and permission with a different outcome is a conflict: status 409 with a list conflicts of permission, variant, conflicting-id.

for administrators for snapd developers

Limits and timers

WhatValue
Requests from uid 0denied, no prompt
Outstanding prompts per user1000; further ones are denied
Prompt expiry when no client has fetched promptswithin 10 seconds: one timer per user, started with the user's first prompt and re-armed every 10 seconds, clears all of that user's prompts
Prompt expiry otherwise10 minutes after the last fetch
After a snapd restartprompts the kernel does not re-send within 5 seconds are dropped

At this snapd version every read of the prompts endpoints counts as a fetch by the client, including one made by hand with snap debug api.

for administrators for snapd developers

Endpoints

EndpointMethods and actionsAccess
/v2/interfaces/requestsPOST askopen for ask
/v2/interfaces/requests/promptsGETopen on snapd.socket; on snapd-snap.socket only with snap-interfaces-requests-control
/v2/interfaces/requests/prompts/{id}GET; POST allow, denysame
/v2/interfaces/requests/rulesGET; POST add, removesame
/v2/interfaces/requests/rules/{id}GET; POST patch, removesame
  • Every call acts on the caller's uid. Root may add ?user-id=N; others get only admins may use the "user-id" parameter.
  • Prompting not running: status 500, AppArmor Prompting is not running.
  • POST remove on rules needs a selector with snap, interface or both. patch changes constraints; a permission mapped to null is removed.
  • ask is open to every local user and the asking process is not yet checked; the prompt is recorded for the caller's uid.
  • There is no snap subcommand for prompts or rules; see snap debug for snap debug api.

for administrators for snapd developers

Notices and files

ItemContent
notice interfaces-requests-promptkey is the prompt ID; resolved prompts carry resolved = replied, satisfied or expired
notice interfaces-requests-rule-updatekey is the rule ID; removals carry removed = removed, expired, merged or dropped
/var/lib/snapd/interfaces-requests/request-rules.jsonthe rules of every user; request-rule-max-id beside it
/run/snapd/interfaces-requests/request-key-mapping.jsonoutstanding prompts across a snapd restart; request-prompt-max-id beside it

for snapd developers

Spread tests

  • tests/main/apparmor-prompting-smoke: 24 scenarios, three interfaces by allow or deny by four lifespans.
  • tests/main/apparmor-prompting-flag-restart, -support, -snapd-startup, -prompt-restoration, -integration-tests.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

  • The home interface — what the home interface grants before any question is asked
  • Confinement — the AppArmor profile that carries the prompt rules

ADMINISTRATION · managing a system of snaps

  • Warnings and notices — the notices a prompting client waits for and the warning about a missing client

DESKTOP · snaps in a user session

INSIDE SNAPD · the daemon itself