| SUDO_PLUGIN_PYTHON(5) | File Formats and Configurations | SUDO_PLUGIN_PYTHON(5) |
sudo_plugin_python —
Sudo Plugin API (Python)
Starting with version 1.9, sudo plugins
can be written in python. The API closely follows the C
sudo plugin API described by
sudo_plugin(5).
The supported plugins types are:
Python plugin support needs to be explicitly enabled at build time with the configure option “--enable-python”. Python version 3.0 or higher is required.
A plugin written in Python should be a class in a python file that inherits from sudo.Plugin. The sudo.Plugin base class has no real purpose other than to identify this class as a plugin.
The only implemented method is a constructor, which stores the keyword arguments it receives as fields (member variables) in the object. This is intended as a convenience to allow you to avoid writing the constructor yourself.
For example:
import sudo
class MySudoPlugin(sudo.Plugin):
# example constructor (optional)
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
# example destructor (optional)
def __del__(self):
pass
Both the constructor and destructor are optional and can be omitted.
The customized Plugin class should define a few plugin-specific
methods. When the plugin loads, sudo will create an
instance of this class and call the methods. The actual methods required
depend on the type of the plugin, but most return an
int result code, as documented in
sudo_plugin(5), that indicates
whether or not the method was successful. The Python sudo module defines the
following constants to improve readability:
| Define | Value |
sudo.RC.OK |
1 |
sudo.RC.ACCEPT |
1 |
sudo.RC.REJECT |
0 |
sudo.RC.ERROR |
-1 |
sudo.RC.USAGE_ERROR |
-2 |
If a function returns None (for example,
if it does not call return), it will be considered to have returned
sudo.RC.OK. If an exception is raised (other than
sudo.PluginException), the backtrace will be shown to the user and the
plugin function will return sudo.RC.ERROR. If that
is not acceptable, you must catch the exception and handle it yourself.
Instead of just returning sudo.RC.ERROR or
sudo.RC.REJECT result code the plugin can also
provide a message describing the problem. This can be done by raising one of
the special exceptions:
raise sudo.PluginError("Message")
raise sudo.PluginReject("Message")
This added message will be used by the audit plugins. Both
exceptions inherit from sudo.PluginException
Running the Python interpreter and bridging between C and Python
is handled by the sudo plugin
python_plugin.so. This shared object can be loaded
like any other dynamic sudo plugin and should
receive the path and the class name of the Python plugin it is loading as
arguments.
Example usage in sudo.conf(5):
Plugin python_policy python_plugin.so ModulePath=<path> ClassName=<class> Plugin python_io python_plugin.so ModulePath=<path> ClassName=<class> Plugin python_audit python_plugin.so ModulePath=<path> ClassName=<class> Plugin python_approval python_plugin.so ModulePath=<path> ClassName=<class>
Example group provider plugin usage in the sudoers file:
Defaults group_plugin="python_plugin.so ModulePath=<path> ClassName=<class>"
The plugin arguments are as follows:
Policy plugins must be registered in sudo.conf(5). For example:
Plugin python_policy python_plugin.so ModulePath=<path> ClassName=<class>
Currently, only a single policy plugin may be specified in sudo.conf(5).
A policy plugin may have the following member functions:
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
version: str, user_info: Tuple[str, ...],
plugin_options: Tuple[str, ...])
Implementing this function is optional. The default constructor will set the keyword arguments it receives as member variables in the object.
The constructor matches the
open()
function in the C sudo plugin API.
The function arguments are as follows:
The
sudo.options_as_dict()
convenience function can be used to convert “key=value”
pairs to a dictionary. For a list of recognized keys and their supported
values, see the policy plugin open()
documentation in
sudo_plugin(5).
check_policy(self, argv: Tuple[str, ...], env_add: Tuple[str, ...])
The
check_policy()
function is called by sudo to determine whether
the user is allowed to run the specified command. Implementing this
function is mandatory for a policy plugin.
The function arguments are as follows:
sudo.options_as_dict()
convenience function can be used to convert them to a dictionary.This function should return a result code or a tuple in the following format:
return (rc, command_info_out, argv_out, user_env_out)
The tuple values are as follows:
sudo.RC.* constants.
sudo.RC.ACCEPT if the command is allowed,
sudo.RC.REJECT if not allowed,
sudo.RC.ERROR for a general error, or
sudo.RC.USAGE_ERROR for a usage error.To accept a command, at the very minimum the plugin must set in the command, runas_uid, and runas_gid keys.
For a list of recognized keys and
supported values, see the
check_policy()
documentation in
sudo_plugin(5).
init_session(self, user_pwd: Tuple, user_env: Tuple[str, ...])
Perform session setup (optional). The
init_session()
function is called before sudo sets up the
execution environment for the command before any user-ID or group-ID
changes.
The function arguments are as follows:
None if the user is not present in the
password database.
Example conversion:
user_pwd = pwd.struct_passwd(user_pwd) if user_pwd else None
This function should return a result code or a tuple in the following format:
return (rc, user_env_out)
The tuple values are as follows:
sudo.RC.* constants.
sudo.RC.OK on success, 0 on failure, or
sudo.RC.ERROR if an error occurred.init_session()
function needs to modify the user environment, it can return the new
environment in user_env_out. If this is omitted,
no changes will be made to user_env.list(self, argv: Tuple[str, ...], is_verbose: int, user: str)
List available privileges for the invoking user.
The function arguments are as follows:
None, an argument vector
describing a command the user wishes to check against the policy.None, the plugin should list the
privileges of the invoking user.validate(self)
For policy plugins that cache authentication credentials, this function is used to validate and cache the credentials (optional).
invalidate(self, remove: int)
For policy plugins that cache authentication credentials, this function is used to invalidate the credentials (optional).
The function arguments are as follows:
show_version(self, is_verbose: int)
Display the plugin version information to
the user. The
sudo.log_info()
function should be used.
The function arguments are as follows:
sudo -V’ is run as the
root user.close(self, exit_status: int, error: int)
Called when a command finishes executing.
Works the same as the
close()
function in the C sudo plugin API, except that
it only gets called if sudo attempts to execute
the command.
The function arguments are as follows:
Sudo ships with an example Python policy plugin. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_policy python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_policy_plugin.py \
ClassName=SudoPolicyPlugin
Only one policy plugin can be enabled at a time so you must disable any other policy plugin listed in /etc/sudo.conf, such as sudoers(5).
I/O plugins must be registered in sudo.conf(5). For example:
Plugin python_io python_plugin.so ModulePath=<path> ClassName=<class>
Sudo supports loading multiple I/O plugins. Currently only 8 python I/O plugins can be loaded at once.
An I/O plugin may have the following member functions:
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
version: str, user_info: Tuple[str, ...],
plugin_options: Tuple[str, ...])
Implementing this function is optional. The default constructor will set the keyword arguments it receives as member variables in the object.
The constructor matches the
open()
function in the C sudo plugin API.
The function arguments are as follows:
The
sudo.options_as_dict()
convenience function can be used to convert “key=value”
pairs to a dictionary. For a list of recognized keys and their supported
values, see the I/O plugin open() documentation
in sudo_plugin(5).
open(self, argv: Tuple[str, ...],
command_info: Tuple[str, ...]) -> int
Receives the command the user wishes to run.
Works the same as the
open()
function in the C sudo plugin API except
that:
open()
function are received through the constructor.The function arguments are as follows:
The
sudo.options_as_dict()
convenience function can be used to convert “key=value”
pairs to a dictionary. For a list of recognized keys and their supported
values, see the I/O plugin open() documentation
in sudo_plugin(5).
The
open()
function should return a result code, one of the
sudo.RC.* constants. If the function returns
sudo.RC.REJECT, no I/O will be sent to the
plugin.
log_ttyin(self, buf: str) -> int log_ttyout(self, buf: str) -> int log_stdin(self, buf: str) -> int log_stdout(self, buf: str) -> int log_stderr(self, buf: str) -> int
Receive the user input or output of the terminal device and application standard input, standard output, or standard error. See the matching calls in sudo_plugin(5).
The function arguments are as follows:
The function should return a result code, one of the
sudo.RC.* constants.
If sudo.RC.ERROR is returned, the
running command will be terminated and all of the plugin's logging
functions will be disabled. Other I/O logging plugins will still receive
any remaining input or output that has not yet been processed.
If an input logging function rejects the data by returning
sudo.RC.REJECT, the command will be terminated
and the data will not be passed to the command, though it will still be
sent to any other I/O logging plugins. If an output logging function
rejects the data by returning sudo.RC.REJECT,
the command will be terminated and the data will not be written to the
terminal, though it will still be sent to any other I/O logging
plugins.
change_winsize(self, line: int, cols: int) -> int
Called whenever the window size of the terminal changes. The function arguments are as follows:
log_suspend(self, signo: int) -> int
The function arguments are as follows:
SIGCONT if the command was resumed.show_version(self, is_verbose: int)
sudo.log_info()
function should be used.
The function arguments are as follows:
sudo -V’ is run as the
root user.close(self, exit_status: int, error: int) -> None
Works the same as the
close()
function in the C sudo plugin API, except that
it only gets called if sudo attempts to execute
the command.
The function arguments are as follows:
Sudo ships with a Python I/O plugin example. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_io python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_io_plugin.py \
ClassName=SudoIOPlugin
Audit plugins must be registered in sudo.conf(5). For example:
Plugin python_audit python_plugin.so ModulePath=<path> ClassName=<class>
Sudo supports loading multiple audit plugins. Currently only 8 python audit plugins can be loaded at once.
An audit plugin may have the following member functions (all of which are optional):
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
version: str, user_info: Tuple[str, ...], plugin_options: Tuple[str, ...])
The default constructor will set the keyword arguments it receives as member variables in the object.
The constructor matches the
open()
function in the C sudo plugin API.
The function arguments are as follows:
open(self, submit_optind: int,
submit_argv: Tuple[str, ...]) -> int
The function arguments are as follows:
close(self, status_type: int, status: int) -> None
Called when sudo is finished, shortly before it exits.
The function arguments are as follows:
sudo.EXIT_REASON.* constants.sudo front-end.show_version(self, is_verbose: int) -> int
Display the plugin version information to
the user. The
sudo.log_info()
function should be used.
The function arguments are as follows:
sudo -V’ is run as the
root user.accept(self, plugin_name: str, plugin_type: int, command_info: Tuple[str, ...],
run_argv: Tuple[str, ...], run_envp: Tuple[str, ...]) -> int
This function is called when a command or action is accepted by a policy or approval plugin. The function arguments are as follows:
sudo
front-end.sudo.PLUGIN_TYPE.POLICY,
sudo.PLUGIN_TYPE.APPROVAL, or
sudo.PLUGIN_TYPE.SUDO. The
accept()
function is called multiple times--once for each policy or approval
plugin that succeeds and once for the sudo front-end. When called on
behalf of the sudo front-end, command_info may
include information from an I/O logging plugin as well.
Typically, an audit plugin is interested in
either the accept status from the sudo
front-end or from the various policy and approval plugins, but not
both. It is possible for the policy plugin to accept a command that
is later rejected by an approval plugin, in which case the audit
plugin's
accept()
and
reject()
functions will
both
be called.
reject(self, plugin_name: str, plugin_type: int, audit_msg: str,
command_info: Tuple[str, ...]) -> int
This function is called when a command or action is rejected by the policy plugin. The function arguments are as follows:
sudo.PLUGIN_TYPE.POLICY,
sudo.PLUGIN_TYPE.APPROVAL, or
sudo.PLUGIN_TYPE.IO.
Unlike the
accept()
function, the
reject()
function is not called on behalf of the sudo
front-end.
None.error(self, plugin_name: str, plugin_type: int, audit_msg: str,
command_info: Tuple[str, ...]) -> int
This function is called when a plugin or the
sudo front-end returns an error. The function
arguments are as follows:
sudo
front-end.SUDO_FRONT_END for the
sudo front-end.None.Sudo ships with a Python Audit plugin example. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_audit python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_audit_plugin.py \
ClassName=SudoAuditPlugin
It will log the plugin accept / reject / error results to the output.
Approval plugins must be registered in sudo.conf(5). For example:
Plugin python_approval python_plugin.so ModulePath=<path> ClassName=<class>
Sudo supports loading multiple approval plugins. Currently only 8 python approval plugins can be loaded at once.
An approval plugin may have the following member functions:
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
version: str, user_info: Tuple[str, ...], plugin_options: Tuple[str, ...],
submit_optind: int, submit_argv: Tuple[str, ...])
Optional. The default constructor will set the keyword arguments it receives as member variables in the object.
The constructor matches the
open()
function in the C sudo plugin API.
The function arguments are as follows:
show_version(self, is_verbose: int) -> int
Display the version. (Same as for all the other plugins.)
check(self, command_info: Tuple[str, ...], run_argv: Tuple[str, ...],
run_env: Tuple[str, ...]) -> int
This function is called after policy plugin's check_policy has succeeded. It can reject execution of the command by returning sudo.RC.REJECT or raising the special exception:
raise sudo.PluginReject("some message")
with the message describing the problem. In the latter case, the audit plugins will get the description.
The function arguments are as follows:
Sudo ships with a Python Approval plugin example. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_approval python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_approval_plugin.py \
ClassName=BusinessHoursApprovalPlugin
It will only allow execution of commands in the "business hours" (from Monday to Friday between 8:00 and 17:59:59).
A group provider plugin is registered in the sudoers(5) file. For example:
Defaults group_plugin="python_plugin.so ModulePath=<path> ClassName=<class>"
Currently, only a single group plugin can be registered in sudoers.
A group provider plugin may have the following member functions:
__init__(self, args: Tuple[str, ...], version: str)
Implementing this function is optional. The default constructor will set the keyword arguments it receives as member variables in the object.
The function arguments are as follows:
query(self, user: str, group: str, user_pwd: Tuple)
The
query()
function is used to ask the group plugin whether
user is a member of group.
This method is required.
The function arguments are as follows:
NULL.Sudo ships with a Python group plugin example. To try it, register it in the sudoers file by adding the following lines:
Defaults group_plugin="python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_group_plugin.py \
ClassName=SudoGroupPlugin"
The example plugin will tell
sudo that the user test is part of
the non-Unix group
mygroup. If you
add a rule that uses this group, it will affect the test
user. For example:
%:mygroup ALL=(ALL) NOPASSWD: ALL
Will allow user test to run
sudo without a password.
The hook function API is currently not supported for plugins written in Python.
A Python plugin can interact with the user using the
sudo.conv()
function which displays one or more messages described by the
sudo.ConvMessage class. This is the Python
equivalent of the
conversation()
function in the C sudo plugin API. A plugin should
not attempt to read directly from the standard input or the user's tty
(neither of which are guaranteed to exist).
The sudo.ConvMessage class specifies how
the user interaction should occur:
sudo.ConvMessage(msg_type: int, msg: str, timeout: int)
sudo.ConvMessage member variables:
sudo.CONV.* constants below.sudo.conv()
function will raise a sudo.ConversationInterrupted
exception. The default is to wait forever (no timeout).To specify the message type, the following constants are available:
sudo.CONV.PROMPT_ECHO_OFFsudo.CONV.PROMPT_ECHO_ONsudo.CONV.ERROR_MSGsudo.CONV.INFO_MSGsudo.CONV.PROMPT_MASKsudo.CONV.PROMPT_ECHO_OKsudo.CONV.PREFER_TTYSee the sudo_plugin(5) manual for a description of the message types.
The
sudo.conv()
function performs the actual user interaction:
sudo.conv(message(s), on_suspend=suspend_function,
on_resume=resume_function)
The function arguments are as follows:
sudo.ConvMessage),
each describing a conversation. At least one message is required.The
sudo.conv()
function can raise the following exceptions:
sudo.SudoExceptionsudo.ConversationInterruptedSudo ships with an example plugin demonstrating the Python conversation API. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_io python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_conversation.py \
ClassName=ReasonLoggerIOPlugin
sudo.log_info(string(s), sep=" ", end="\n") sudo.log_error(string(s), sep=" ", end="\n")
To display information to the user, the
sudo.log_info()
function can be used. To display error messages, use
sudo.log_error().
The syntax is similar to the Python
print()
function.
The function arguments are as follows:
Debug messages are not visible to the user and are only logged
debugging is explicitly enabled in
sudo.conf(5). Python plugins can
use the
sudo.debug()
function to make use of
sudo's debug system.
Enabling debugging in sudo.conf
To enable debug messages, add a Debug line to sudo.conf(5) with the program set to python_plugin.so. For example, to store debug output in /var/log/sudo_python_debug, use a line like the following:
Debug python_plugin.so /var/log/sudo_python_debug \
plugin@trace,c_calls@trace
The debug options are in the form of multiple
“subsystem@level” strings, separated by commas
(‘,’). For example to just see the debug output of
sudo.debug()
calls, use:
Debug python_plugin.so /var/log/sudo_python_debug plugin@trace
See sudo_conf(5) for more details.
The most interesting subsystems for Python plugin development are:
sudo.debug()
API call.__init__()
function.sudo API
function.sudo calls into the python plugin
API.You can also specify “all” as the subsystem name to log debug messages for all subsystems.
The
sudo.debug()
function is defined as:
sudo.debug(level, message(s))
The function arguments are as follows:
| sudo.conf name | Python constant | description |
| crit | sudo.DEBUG.CRIT |
only critical messages |
| err | sudo.DEBUG.ERROR |
|
| warn | sudo.DEBUG.WARN |
|
| notice | sudo.DEBUG.NOTICE |
|
| diag | sudo.DEBUG.DIAG |
|
| info | sudo.DEBUG.INFO |
|
| trace | sudo.DEBUG.TRACE |
|
| debug | sudo.DEBUG.DEBUG |
very extreme verbose debugging |
Alternatively, a plugin can use the built in logging module of Python as well. Sudo adds its log handler to the root logger, so by default all output of a logger will get forwarded to sudo log system, as it would call sudo.debug.
The log handler of sudo will map each Python log level of a message to the appropriate sudo debug level. The sudo debug system will only receive messages that are not filtered out by the Python loggers. For example, the log level of the python logger will be an additional filter for the log messages, and is usually very different from what level is set in sudo.conf for the sudo debug system.
Sudo ships with an example debug plugin. To try it, register it by adding the following lines to /etc/sudo.conf:
Plugin python_io python_plugin.so \
ModulePath=/usr/share/doc/sudo/examples/example_debugging.py \
ClassName=DebugDemoPlugin
Debug python_plugin.so \
/var/log/sudo_python_debug plugin@trace,c_calls@trace
The Python plugin API includes two convenience functions to convert options in “key=value” format to a dictionary and vice versa.
options_as_dict(options)
The function arguments are as follows:
The function returns the resulting dictionary. Each string of the passed in options will be split at the first equal sign (‘=’) into a key and value. Dictionary keys will never contain this symbol (but values may).
options_from_dict(options_dict)
The function arguments are as follows:
The function returns a tuple containing the strings in “key=value” form for each key and value in the options_dict dictionary passed in. This is how the plugin API accepts options and settings.
None yet
A maximum of 8 python I/O plugins can be loaded at once. If /etc/sudo.conf contains more, those will be rejected with a warning message.
The Event API and the hook function API is currently not accessible for Python plugins.
Many people have worked on sudo over the
years; this version consists of code written primarily by:
See the CONTRIBUTORS.md file in the sudo
distribution (https://www.sudo.ws/about/contributors/) for an exhaustive
list of people who have contributed to sudo.
Python plugin support is currently considered experimental.
If you believe you have found a bug in
sudo_plugin_python, you can either file a bug report
in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at
https://github.com/sudo-project/sudo/issues. If you would prefer to use
email, messages may be sent to the sudo-workers mailing list,
https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or
<sudo@sudo.ws> (private).
Please not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.
All Python plugin handling is implemented inside the
python_plugin.so dynamic plugin. Therefore, if no
Python plugin is registered in
sudo.conf(5) or the
sudoers file, sudo will not load
the Python interpreter or the Python libraries.
As sudo runs plugins as
root, care must be
taken when writing Python plugins to avoid creating security
vulnerabilities, just as one would when writing plugins in C.
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.
sudo is provided “AS IS” and
any express or implied warranties, including, but not limited to, the
implied warranties of merchantability and fitness for a particular purpose
are disclaimed. See the LICENSE.md file distributed with
sudo or https://www.sudo.ws/about/license/ for
complete details.
| January 16, 2023 | Sudo 1.9.16p2 |