Inspect polkit Actions Safely with pkaction

You will finish with a repeatable way to list the polkit actions registered on this machine, inspect the rules for one action, and distinguish a lookup failure from a permission decision. The examples use pkaction 124 from Ubuntu package polkitd 124-2ubuntu1.24.04.4.

Allow about ten minutes. You need a shell and a working polkit installation. All commands in this guide are read-only and normally run as your ordinary user. This guide does not edit policy, reload a daemon or authorise an operation.

1. Check the installed command

Start by checking the executable and its local version. This confirms which implementation and option names you are about to use:

$ command -v pkaction
/usr/bin/pkaction
$ pkaction --version
pkaction version 124
$ dpkg-query -W -f='${Package} ${Version}\n' polkitd
polkitd 124-2ubuntu1.24.04.4

The manual describes pkaction as a tool for obtaining information about registered polkit actions. It has two useful display modes: without an action ID it lists action names, while --verbose adds details. The installed help also shows the short forms -a for --action-id and -v for --verbose.

2. List the registered action IDs

Run pkaction without an action ID. The output is one registered action name per line:

$ pkaction | sed -n '1,8p'
com.ubuntu.apport.apport-gtk-root
com.ubuntu.apport.root-info
com.ubuntu.release-upgrader.partial-upgrade
com.ubuntu.release-upgrader.release-upgrade
com.ubuntu.softwareproperties.applychanges
com.ubuntu.update-notifier.pkexec.cddistupgrader
com.ubuntu.update-notifier.pkexec.package-system-locked
io.snapcraft.snapd.login

Your list will differ. Packages, desktop components and locally installed applications register different actions, so do not treat the example names as a required baseline. To search the complete list without changing it, use an ordinary pipeline:

$ pkaction | grep -i snap
io.snapcraft.snapd.login

An empty result from grep means that no listed action contains that text. It does not prove that polkit is absent.

3. Inspect one action in detail

Choose an exact ID from your own list. The following action is commonly present on systems that use polkit's execution helper, but verify it first:

$ pkaction | grep -Fx 'org.freedesktop.policykit.exec'
org.freedesktop.policykit.exec

Pass that ID to --action-id and add --verbose:

$ pkaction --action-id org.freedesktop.policykit.exec --verbose
org.freedesktop.policykit.exec:
  description:       Run a program as another user
  message:           Authentication is required to run a program as another user
  vendor:            The polkit project
  vendor_url:        http://www.freedesktop.org/wiki/Software/polkit/
  icon:
  implicit any:      auth_admin
  implicit inactive: auth_admin
  implicit active:   auth_admin

The exact fields and text belong to the installed policy data. In this example, the three implicit subjects are shown with an auth_admin result. That is policy metadata for the action, not an instruction to authenticate now and not proof that a particular caller will be allowed in every context.

4. Understand the non-verbose default

When you provide an action ID without --verbose, pkaction prints only the action name. This is useful when a script needs to confirm that an ID is registered, but it is not a policy dump:

$ pkaction --action-id org.freedesktop.policykit.exec
org.freedesktop.policykit.exec

A common distraction is to run the command, see only one line and assume that the action has no description or rules. The default is intentionally terse. Repeat the lookup with --verbose when you need the description, message, vendor fields or implicit results.

For a machine-readable check that an action is present, test the exit status rather than matching a descriptive sentence:

$ if pkaction --action-id org.freedesktop.policykit.exec >/dev/null; then
>     echo 'action is registered'
> else
>     echo 'action is not registered'
> fi
action is registered

5. Diagnose a missing action

Use a deliberately invalid ID to see the failure shape without modifying anything:

$ pkaction --action-id definitely.not.an.action
No action with action id definitely.not.an.action
$ echo $?
1

The manual promises a non-zero status and a diagnostic on standard error when pkaction fails. The installed command returns status 1 here. This is a lookup problem, not a request for elevated privileges. First check spelling, then list registered IDs again. If a package recently added or removed an action, investigate that package's installation state and service logs through your normal maintenance process.

Do not add sudo as a reflex. Reading the registered action catalogue does not normally require root, and elevated privileges will not create an action that is not registered.

6. Keep inspection separate from policy changes

pkaction only reports registered actions. It does not approve a request, invoke the action, edit JavaScript or XML policy files, or reload polkit. That boundary matters when diagnosing a program that asks for authentication.

Use pkaction to answer, "What action ID and policy metadata are registered?" Use the program that made the request, and where appropriate tools such as pkcheck or system logs, to investigate an actual authorisation decision. Do not infer the caller's final result from one implicit line alone: subject state, authentication, local policy rules and the requesting process can all affect the decision.

There is no undo step for the commands in this guide because they change no persistent state. If you find instructions that ask you to edit a policy file or restart polkit while merely trying to inspect an action, stop and treat that as a separate, security-sensitive change. Back up the relevant configuration and establish a rollback plan before making it.