sudo/doc/sudo_plugin_python.mdoc.in

.\"
.\" SPDX-License-Identifier: ISC
.\"
.\" Copyright (c) 2019 Robert Manner <robert.manner@oneidentity.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 21, 2019
.Dt SUDO_PLUGIN_PYTHON @mansectform@
.Os Sudo @PACKAGE_VERSION@
.Sh NAME
.Nm sudo_plugin_python
.Nd Sudo Plugin API (Python)
.Sh DESCRIPTION
Starting with version 1.9,
.Nm sudo
plugins can be written in python.
The API closely follows the C
.Nm sudo
plugin API described by
.Xr sudo_plugin @mansectform@ .
.Pp
The supported plugins types are:
.Pp
.Bl -bullet -compact -offset 4n -width 1n
.It
Policy plugin
.It
I/O plugin
.It
Group provider plugin
.El
.Pp
Python plugin support needs to be explicitly enabled at build time
with the configure option
.Dq --enable-python .
Python version 3.0 or higher is required.
.Ss Sudo Python Plugin Base
A plugin written in Python should be a class in a python file that
inherits from
.Em sudo.Plugin .
The
.Em sudo.Plugin
base class has no real purpose other than to identify this class as a plugin.
.Pp
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.
.Pp
For example:
.Bd -literal -offset indent
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
.Ed
.Pp
Both the constructor and destructor are optional and can be omitted.
.Pp
The customized Plugin class should define a few plugin-specific methods.
When the plugin loads,
.Nm sudo
will create an instance of this class and call the methods.
The actual methods required depent on the type of the plugin,
but most return an
.Dq int
result code, as documented in
.Xr sudo_plugin @mansctsu@ ,
that indicates whether or not the method was successful.
The Python sudo module defines the following constants to improve readability:
.Bl -column "sudo.RC_USAGE_ERROR" "XXX" -offset 4n
.It Sy Define Ta Sy Value
.It Dv sudo.RC_OK Ta 1
.It Dv sudo.RC_ACCEPT Ta 1
.It Dv sudo.RC_REJECT Ta 0
.It Dv sudo.RC_ERROR Ta -1
.It Dv sudo.RC_USAGE_ERROR Ta -2
.El
.Pp
If a function returns
.Em None
(for example, if it does not call return),
it will be considered to have returned
.Dv sudo.RC_OK .
If an exception is raised, the backtrace will be shown to the user and
the plugin function will return
.Dv sudo.RC_ERROR .
If that is not acceptable, you must catch the exception and handle it yourself.
.Ss Python Plugin Loader
Running the Python interpreter and bridging between C and Python is
handled by the
.Nm sudo
plugin
.Li python_plugin.so .
This shared object can be loaded like any other dynamic
.Nm sudo
plugin and should receive the path and the class name of the Python
plugin it is loading as arguments.
.Pp
Example usage in
.Xr sudo.conf @mansectform@ :
.Bd -literal
Plugin python_policy python_plugin.so ModulePath=<path> ClassName=<class>
Plugin python_io python_plugin.so ModulePath=<path> ClassName=<class>
.Ed
.Pp
Example group provider plugin usage in the
.Em sudoers
file:
.Bd -literal
Defaults group_plugin="python_plugin.so ModulePath=<path> ClassName=<class>"
.Ed
.Pp
The plugin arguments are as follows:
.Bl -tag -width 4n
.It ModulePath
The path of a python file which contains the class of the sudo Python plugin.
.It ClassName
The name of the class implementing the sudo Python plugin.
.El
.Ss Policy plugin API
Policy plugins must be registered in
.Xr sudo.conf @mansectform@ .
For example:
.Bd -literal
Plugin python_policy python_plugin.so ModulePath=<path> ClassName=<class>
.Ed
.Pp
Currently, only a single policy plugin may be specified in
.Xr sudo.conf @mansectform@ .
.Pp
A policy plugin may have the following member functions:
.Bl -tag -width 4n
.It Sy constructor
.Bd -literal
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
    version: str, user_info: Tuple[str, ...],
    plugin_options: Tuple[str, ...])
.Ed
.Pp
Implementing this function is optional.
The default constructor will set the keyword arguments it receives
as member variables in the object.
.Pp
The constructor matches the
.Fn open
function in the C sudo plugin API.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa user_env
The user's environment as a tuple of strings in
.Dq key=value
format.
.It Fa settings
A tuple of user-supplied
.Em sudo
settings in the form of
.Dq key=value
strings.
.It Fa version
The version of the Python Policy Plugin API.
.It Fa user_info
A tuple of information about the user running the command in the form of
.Dq key=value
strings.
.It Fa plugin_options
The plugin options passed as arguments in the
.Xr sudo.conf @mansectform@
plugin registration.
This is a tuple of strings, usually (but not necessarily) in
.Dq key=value
format.
.El
.Pp
The
.Fn sudo.options_as_dict
convenience function can be used to convert
.Dq key=value
pairs to a dictionary.
For a list of recognized keys and their supported values,
see the policy plugin
.Fn open
documentation in
.Xr sudo_plugin @mansectform@ .
.It Sy check_policy
.Bd -literal -compact
check_policy(self, argv: Tuple[str, ...], env_add: Tuple[str, ...])
.Ed
.Pp
The
.Fn check_policy
function is called by
.Nm sudo
to determine whether the user is allowed to run the specified command.
Implementing this function is mandatory for a policy plugin.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa argv
A tuple describing the command the user wishes to run.
.It Fa env_add
Additional environment variables specified by the user on the command line in
the form of a tuple of
.Dq key=value
pairs.
The
.Fn sudo.options_as_dict
convenience function can be used to convert them to a dictionary.
.El
.Pp
This function should return a result code or a tuple in the following format:
.Bd -literal -offset 4n
return (rc, command_info_out, argv_out, user_env_out)
.Ed
.Pp
The tuple values are as follows:
.Bl -tag -width 4n
.It Fa rc
The result of the policy check, one of the
.Dv sudo.RC_*
constants.
.Dv sudo.RC_ACCEPT
if the command is allowed,
.Dv sudo.RC_REJECT
if not allowed,
.Dv sudo.RC_ERROR
for a general error, or
.Dv sudo.RC_USAGE_ERROR
for a usage error.
.It Fa command_info_out
Optional (only required when the command is accepted).
Information about the command being run in the form of
.Dq key=value
strings.
.Pp
To accept a command, at the very minimum the plugin must set in the
.Em command ,
.Em runas_uid
and
.Em runas_gid
keys.
.Pp
For a list of recognized keys and supported values,
see the
.Fn check_policy
documentation in
.Xr sudo_plugin @mansectform@ .
.It Fa argv_out
Optional (only required when the command is accepted).
The arguments to pass to the
.Xr execve 2
system call when executing the command.
.It Fa user_env_out
Optional (only required when the command is accepted).
The environment to use when executing the command in the form of a
tuple of strings in
.Dq key=value
format.
.El
.It Sy init_session
.Bd -literal -compact
init_session(self, user_pwd: Tuple, user_env: Tuple[str, ...])
.Ed
.Pp
Perform session setup (optional).
The
.Fn init_session
function is called before
.Nm sudo
sets up the
execution environment for the command before any uid or gid changes.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa user_pwd
A tuple describing the user's passwd entry.
Convertible to pwd.struct_passwd or
.Em None
if the user is not present in the password database.
.Pp
Example conversion:
.Bd -literal -compact
user_pwd = pwd.struct_passwd(user_pwd) if user_pwd else None
.Ed
.It Fa user_env
The environment the command will run in.
This is a tuple of strings in
.Dq key=value
format.
.El
.Pp
This function should return a result code or a tuple in the following format:
.Bd -literal -offset 4n
return (rc, user_env_out)
.Ed
.Pp
The tuple values are as follows:
.Bl -tag -width 4n
.It Fa rc
The result of the session init, one of the
.Dv sudo.RC_*
constants.
.Dv sudo.RC_OK
on success, 0 on failure, or
.Dv sudo.RC_ERROR
if an error occurred.
.It Fa user_env_out
Optional.
If the
.Fn init_session
function needs to modify the user environment, it can return the new
environment in
.Fa user_env_out .
If this is omitted, no changes will be made to
.Fa user_env .
.El
.It Sy list
.Bd -literal -compact
list(self, argv: Tuple[str, ...], is_verbose: int, user: str)
.Ed
.Pp
List available privileges for the invoking user.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa argv
If not set to
.Em None ,
an argument vector describing a command the user wishes to check
against the policy.
.It Fa is_verbose
Flag indicating whether to list in verbose mode or not.
.It Fa user
The name of a different user to list privileges for if the policy allows it.
If
.Em None ,
the plugin should list the privileges of the invoking user.
.El
.It Sy validate
.Bd -literal -compact
validate(self)
.Ed
.Pp
For policy plugins that cache authentication credentials, this function is used to validate and cache the credentials (optional).
.It Sy invalidate
.Bd -literal -compact
invalidate(self, remove: int)
.Ed
.Pp
For policy plugins that cache authentication credentials, this function is used to invalidate the credentials (optional).
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa remove
If this flag is set, the plugin may remove the credentials instead of simply
invalidating them.
.El
.It Sy show_version
.Bd -literal -compact
show_version(self, is_verbose: int)
.Ed
.Pp
Display the plugin version information to the user.
The
.Fn sudo.log_info
function should be used.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa is_verbose
A flag to indicate displaying more verbose information.
Currently this is 1 if
.Ql sudo -V
is run as the root user.
.El
.It Sy close
.Bd -literal -compact
close(self, exit_status: int, error: int)
.Ed
.Pp
Called when a command finishes executing.
.Pp
Works the same as the
.Fn close
function in the C sudo plugin API, except that it only gets called if
.Nm sudo
attempts to execute the command.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa exit_status
The exit status of the command if was executed, otherwise -1.
.It Fa error
If the command could not be executed, this is set to the value of
errno set by the
.Xr execve 2
system call, otherwise 0.
.El
.El
.Ss Policy plugin example
Sudo ships with an example Python policy plugin.
To try it, register it by adding the following lines to
.Pa @sysconfdir@/sudo.conf :
.Bd -literal
Plugin python_policy python_plugin.so \e
    ModulePath=/usr/share/doc/sudo/examples/example_policy_plugin.py \e
    ClassName=SudoPolicyPlugin
.Ed
.Pp
Be aware, however, that you cannot enable the Python policy plugin
in addition to another policy plugin, such as
.Xr sudoers @mansectform@ .
.Ss I/O plugin API
I/O plugins must be registered in
.Xr sudo.conf @mansectform@ .
For example:
.Bd -literal
Plugin python_io python_plugin.so ModulePath=<path> ClassName=<class>
.Ed
.Pp
Sudo supports loading multiple I/O plugins, but currently only one
of them can be written in Python.
.Pp
An I/O plugin may have the following member functions:
.Bl -tag -width 4n
.It Sy constructor
.Bd -literal -compact
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
    version: str, user_info: Tuple[str, ...],
    plugin_options: Tuple[str, ...])
.Ed
.Pp
Implementing this function is optional.
The default constructor will set the keyword arguments it receives
as member variables in the object.
.Pp
The constructor matches the
.Fn open
function in the C sudo plugin API.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa user_env
The user's environment as a tuple of strings in
.Dq key=value
format.
.It Fa settings
A tuple of user-supplied
.Em sudo
settings in the form of
.Dq key=value
strings.
.It Fa version
The version of the Python Policy Plugin API.
.It Fa user_info
A tuple of information about the user running the command in the form of
.Dq key=value
strings.
.It Fa plugin_options
The plugin options passed as arguments in the
.Xr sudo.conf @mansectform@
plugin registration.
This is a tuple of strings, usually (but not necessarily) in
.Dq key=value
format.
.El
.Pp
The
.Fn sudo.options_as_dict
convenience function can be used to convert
.Dq key=value
pairs to a dictionary.
For a list of recognized keys and their supported values,
see the I/O plugin
.Fn open
documentation in
.Xr sudo_plugin @mansectform@ .
.It Sy open
.Bd -literal -compact
open(self, argv: Tuple[str, ...],
    command_info: Tuple[str, ...]) -> int
.Ed
.Pp
Receives the command the user wishes to run.
.Pp
Works the same as the
.Fn open
function in the C sudo plugin API except that:
.Pp
.Bl -bullet -compact -offset 4n -width 1n
.It
It only gets called before the user would execute some command
(and not for a version query for example).
.It
Other arguments of the C API
.Fn open
function are received through the constructor.
.El
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa argv
A tuple of the arguments describing the command the user wishes to run.
.It Fa command_info
Information about the command being run in the form of
.Dq key=value
strings.
.El
.Pp
The
.Fn sudo.options_as_dict
convenience function can be used to convert
.Dq key=value
pairs to a dictionary.
For a list of recognized keys and their supported values,
see the I/O plugin
.Fn open
documentation in
.Xr sudo_plugin @mansectform@ .
.Pp
The
.Fn open
function should return a result code, one of the
.Dv sudo.RC_*
constants.
If the function returns
.Dv sudo.REJECT ,
no I/O will be sent to the plugin.
.It Sy log_ttyin , log_ttyout , log_stdin , log_stdout , log_stderr
.Bd -literal -compact
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
.Ed
.Pp
Receive the user input or output of the terminal device and
application standard input / output / error.
See the matching calls in
.Xr sudo_plugin @mansectform@ .
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa buf
The input (or output) buffer in the form of a string.
.El
.Pp
The function should return a result code, one of the
.Dv sudo.RC_*
constants.
.Pp
If
.Dv 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.
.Pp
If an input logging function rejects the data by returning
.Dv 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
.Dv 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.
.It Sy change_winsize
.Bd -literal -compact
change_winsize(self, line: int, cols: int) -> int
.Ed
.Pp
Called whenever the window size of the terminal changes.
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa line
The number of lines of the terminal.
.It Fa cols
The number of columns of the terminal.
.El
.It Sy log_suspend
.Bd -literal -compact
log_suspend(self, signo: int) -> int
.Ed
Called whenever a command is suspended or resumed.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa signo
The number of the signal that caused the command to be suspended or
.Dv SIGCONT
if the command was resumed.
.El
.It Sy show_version
.Bd -literal -compact
show_version(self, is_verbose: int)
.Ed
Display the plugin version information to the user.
The
.Fn sudo.log_info
function should be used.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa is_verbose
A flag to indicate displaying more verbose information.
Currently this is 1 if
.Ql sudo -V
is run as the root user.
.El
.It Sy close
.Bd -literal -compact
close(self, exit_status: int, error: int) -> None
.Ed
Called when a command execution finished.
.Pp
Works the same as the
.Fn close
function in the C sudo plugin API, except that it only gets called if
.Nm sudo
attempts to execute the command.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa exit_status
The exit status of the command if was executed, otherwise -1.
.It Fa error
If the command could not be executed, this is set to the value of
errno set by the
.Xr execve 2
system call, otherwise 0.
.El
.El
.Ss I/O plugin example
Sudo ships a Python I/O plugin example.
To try it, register it by adding the following lines to
.Pa @sysconfdir@/sudo.conf :
.Bd -literal
Plugin python_io python_plugin.so \e
    ModulePath=/usr/share/doc/sudo/examples/example_io_plugin.py \e
    ClassName=SudoIOPlugin
.Ed
.Ss Sudoers group provider plugin API
A group provider plugin is registered in the
.Xr sudoers @mansectform@
file.
For example:
.Bd -literal
Defaults group_plugin="python_plugin.so ModulePath=<path> ClassName=<class>"
.Ed
.Pp
Currently, only a single group plugin can be registered in
.Em sudoers .
.Pp
A group provider plugin may have the following member functions:
.Bl -tag -width 4n
.It Sy constructor
.Bd -literal -compact
__init__(self, args: Tuple[str, ...], version: str)
.Ed
.Pp
Implementing this function is optional.
The default constructor will set the keyword arguments it receives
as member variables in the object.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa args
The plugin options passed as arguments in the
.Em sudoers
file plugin registration.
All the arguments are free form strings (not necessarily in
.Dq key=value
format).
.It Fa version
The version of the Python Group Plugin API.
.El
.It Sy query
.Bd -literal -compact
query(self, user: str, group: str, user_pwd: Tuple)
.Ed
.Pp
The
.Fn query
function is used to ask the group plugin whether
.Fa user
is a member of
.Fa group .
This method is required.
.El
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa user
The name of the user being looked up in the external group database.
.It Fa group
The name of the group being queried.
.It Fa user_pwd
The password database entry for the user, if any.
If
.Fa user
is not present in the password database,
.Fa user_pwd
will be
.Dv NULL .
.El
.Ss Group plugin example
Sudo ships a Python group plugin example.
To try it, register it in the
.Em sudoers
file by adding the following lines:
.Bd -literal
Defaults group_plugin="python_plugin.so \e
    ModulePath=/usr/share/doc/sudo/examples/example_group_plugin.py \e
    ClassName=SudoGroupPlugin"
.Ed
.Pp
The example plugin will tell
.Nm sudo
that the user
.Em test
is part of the non-unix group
.Em mygroup .
If you add a rule that uses this group, it will affect the
.Em test
user.
For example:
.Bd -literal
%:mygroup ALL=(ALL) NOPASSWD: ALL
.Ed
.Pp
Will allow user
.Em test
to run
.Nm sudo
without a password.
.Ss Hook function API
The hook function API is currently not supported for plugins
written in Python.
.Ss Conversation API
A Python plugin can interact with the user using the
.Fn sudo.conv
function which displays one or more messages described by the
.Sy sudo.ConvMessage
class.
This is the Python equivalent of the
.Fn 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).
.Pp
The
.Sy sudo.ConvMessage
class specifies how the user interaction should occur:
.Bd -literal -offset 4n
sudo.ConvMessage(msg_type: int, msg: str, timeout: int)
.Ed
.Pp
.Sy sudo.ConvMessage
member variables:
.Bl -tag -width 4n
.It Fa msg_type
Specifies the type of the conversation.
See the
.Dv sudo.CONV_*
constants below.
.It Fa msg
The message to display to the user.
The caller must include a trailing newline in
.Li msg
if one is to be displayed.
.It Fa timeout
Optional.
The maximum amount of time for the conversation in seconds.
If the timeout is exceeded, the
.Fn sudo.conv
function will raise a
.Dv sudo.ConversationInterrupted
exception.
The default is to wait forever (no timeout).
.El
.Pp
To specify the message type, the following constants are available:
.Pp
.Bl -bullet -compact -offset 4n -width 1n
.It
sudo.CONV_PROMPT_ECHO_OFF
.It
sudo.CONV_PROMPT_ECHO_ON
.It
sudo.CONV_ERROR_MSG
.It
sudo.CONV_INFO_MSG
.It
sudo.CONV_PROMPT_MASK
.It
sudo.CONV_PROMPT_ECHO_OK
.It
sudo.CONV_PREFER_TTY
.El
.Pp
See the
.Xr sudo_plugin @mansectform@
manual for a description of the message types.
.Pp
The
.Fn sudo.conv
function performs the actual user interaction:
.Bd -literal -offset 4n
sudo.conv(message(s), on_suspend=suspend_function,
    on_resume=resume_function)
.Ed
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa messsage(s)
One of more messages (of type
.Sy sudo.ConvMessage ) ,
each describing a conversation.
At least one message is required.
.It Fa on_suspend
An optional callback function which gets called if the conversation
is suspended, for example by the user pressing control-Z.
The specified function must take a single argument which will be filled
with the number of the signal that caused the process to be suspended.
.It Fa on_resume
An optional callback function which gets called when the previously
suspended conversation is resumed.
The specified function must take a single argument which will be filled
with the number of the signal that caused the process to be suspended.
.El
.Pp
The
.Fn sudo.conv
function can raise the following exceptions:
.Bl -tag -width 4n
.It Sy sudo.SudoException
If the conversation fails, for example when the conversation function is not
available.
.It Sy sudo.ConversationInterrupted
If the conversation function returns an error, e.g., the timeout passed
or the user interrupted the conversation by pressing control-C.
.El
.Ss Conversation example
Sudo ships with an example plugin demonstrating the Python conversation API.
To try it, register it by adding the following lines to
.Pa @sysconfdir@/sudo.conf :
.Bd -literal
Plugin python_io python_plugin.so \e
    ModulePath=/usr/share/doc/sudo/examples/example_conversation.py \e
    ClassName=ReasonLoggerIOPlugin
.Ed
.Ss Information / error display API
.Bd -literal
sudo.log_info(string(s), sep=" ", end="\en")
sudo.log_error(string(s), sep=" ", end="\en")
.Ed
.Pp
To display information to the user, the
.Fn sudo.log_info
function can be used.
To display error messages, use
.Fn sudo.log_error .
The syntax is similar to the Python
.Fn print
function.
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa string(s)
One or more strings to display.
.It Fa sep
An optional string which will be used as the separator between the
specified strings.
The default is a space character,
.Pq Sq \  .
.It Fa end
An optional string which will be displayed at the end of the message.
The default is a new line character
.Pq Sq \en  .
.El
.Ss Debug API
Debug messages are not visible to the user and are only logged debugging
is explicitly enabled in
.Xr sudo.conf @mansectform@ .
Python plugins can use the
.Fn sudo.debug
function to make use of
.Nm sudo Ns No 's
debug system.
.Pp
.Em Enabling debugging in sudo.conf
.Pp
To enable debug messages, add a
.Li Debug
line to
.Xr sudo.conf @mansectform@
with the program set to
.Pa python_plugin.so .
For example, to store debug output in
.Pa /var/log/sudo_python_debug ,
use a line like the following:
.Bd -literal
Debug python_plugin.so /var/log/sudo_python_debug \e
    plugin@trace,c_calls@trace
.Ed
.Pp
The debug options are in the form of multiple
.Dq subsystem@level
strings, separated by commas
.Pq Sq \&, .
For example to just see the debug output of
.Fn sudo.debug
calls, use:
.Bd -literal
Debug python_plugin.so /var/log/sudo_python_debug plugin@trace
.Ed
.Pp
See
.Xr sudo_conf @mansectform@
for more details.
.Pp
The most interesting subsystems for Python plugin development are:
.Bl -tag -width 4n
.It Em plugin
Logs each
.Fn sudo.debug
API call.
.It Em py_calls
Logs whenever a C function calls into the python module.
For example, calling the
.Fn __init__
function.
.It Em c_calls
Logs whenever python calls into a C
.Nm sudo
API function.
.It Em internal
Logs internal functions of the python language wrapper plugin.
.It Em sudo_cb
Logs when
.Nm sudo
calls into the python plugin API.
.It Em load
Logs python plugin loading / unloading events.
.El
.Pp
You can also specify
.Dq all
as the subsystem name to log debug messages for all subsystems.
.Pp
The
.Fn sudo.debug
function is defined as:
.Bd -literal -offset 4n
sudo.debug(level, message(s))
.Ed
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa level
an integer, use one of the log level constants below
.It Fa messsage(s)
one or more messages to log
.El
.Pp
.Em Available log levels:
.Bl -column "name in sudo.conf" "Python constant" "only cricital messages"
.It Sy sudo.conf name Ta Sy Python constant Ta Sy description
.It crit Ta sudo.DEBUG_CRIT Ta only cricital messages
.It err Ta sudo.DEBUG_ERROR Ta
.It warn Ta sudo.DEBUG_WARN Ta
.It notice Ta sudo.DEBUG_NOTICE Ta
.It diag Ta sudo.DEBUG_DIAG Ta
.It info Ta sudo.DEBUG_INFO Ta
.It trace Ta sudo.DEBUG_TRACE Ta
.It debug Ta sudo.DEBUG_DEBUG Ta very extreme verbose debugging
.El
.Pp
.Ss Debug example
.Pp
Sudo ships an example debug plugin by default.
To try it, register it by adding the following lines to
.Pa @sysconfdir@/sudo.conf :
.Bd -literal
Plugin python_io python_plugin.so \e
    ModulePath=/usr/share/doc/sudo/examples/example_debugging.py \e
    ClassName=DebugDemoPlugin

Debug python_plugin.so \e
    /var/log/sudo_python_debug plugin@trace,c_calls@trace
.Ed
.Ss Option conversion API
The Python plugin API includes two convenience functions to
convert options in
.Dq key=value
format to a dictionary and vice versa.
.Bl -tag -width 4n
.It options_as_dict
.Bd -literal -compact
options_as_dict(options)
.Ed
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa options
An iterable (tuple, list, etc.) of strings, each in
.Dq key=value
format.
This is how the plugin API passes options and settings to a Python plugin.
.El
.Pp
The function returns the resulting dictionary.
Each string of the passed in
.Fa options
will be split at the first equal sign
.Pq Sq \&=
into a
.Em key
and
.Em value .
Dictionary keys will never contain this symbol (but values may).
.It options_from_dict
.Bd -literal -compact
options_from_dict(options_dict)
.Ed
.Pp
The function arguments are as follows:
.Bl -tag -width 4n
.It Fa options_dict
A dictionary where both the key and the value are strings.
Note that the key should not contain an equal sign
.Pq Sq \&= ,
otherwise the resulting string will have a different meaning.
However, this is not currently enforced.
.El
.Pp
The function returns a tuple containing the strings in
.Dq key=value
form for each key and value in the
.Fa options_dict
dictionary passed in.
This is how the plugin API accepts options and settings.
.El
.Sh PLUGIN API CHANGELOG (Python)
None yet
.Sh LIMITATIONS
Sudo supports using multiple I/O plugins, but currently only one I/O
plugin can be written in Python.
.Pp
The hook function API is currently not accessible for Python plugins.
.Pp
I/O and Group plugins written in Python do not support the
.Fn event_alloc
callback.
.Sh SEE ALSO
.Xr sudo.conf @mansectform@ ,
.Xr sudo_plugin @mansectform@ ,
.Xr sudoers @mansectform@ ,
.Xr sudo @mansectsu@
.Sh AUTHORS
Many people have worked on
.Nm sudo
over the years; this version consists of code written primarily by:
.Bd -ragged -offset indent
.An Todd C. Miller
.Ed
.Pp
See the CONTRIBUTORS file in the
.Nm sudo
distribution (https://www.sudo.ws/contributors.html) for an
exhaustive list of people who have contributed to
.Nm sudo .
.Sh BUGS
Python plugin support is currently considered experimental.
.Pp
If you feel you have found a bug in
.Nm sudo ,
please submit a bug report at https://bugzilla.sudo.ws/
.Sh SECURITY CONSIDERATIONS
All Python plugin handling is implemented inside the
.Li python_plugin.so
dynamic plugin.
Therefore, if no Python plugin is registered in
.Xr sudo.conf @mansectform@
or the
.Em sudoers
file,
.Nm sudo
will not load the Python interpreter or the Python libraries.
.Pp
By default, a Python plugin can only import Python modules which are
owned by
.Em root
and are only writable by the owner.
The reason for this is to prevent a file getting imported accidentally
which is modifiable by a non-root user.
As
.Nm sudo
plugins run as
.Em root ,
accidentally importing such file would make it possible for any user
(having write access) to execute any code with administrative rights.
.Pp
However, during development of a plugin this might not be very convenient.
The
.Xr sudo.conf @mansectform@
.Li developer_mode
option can be used to disable it.
For example:
.Dl Set developer_mode true
.Pp
Please note that this creates a security risk, so it is not recommended
on critical systems such as a desktop machine for daily use, but is intended
to be used in development environments (VM, container, etc).
Before enabling developer mode, ensure you understand the implications.
.Sh SUPPORT
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.
.Sh DISCLAIMER
.Nm sudo
is provided
.Dq 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 file distributed with
.Nm sudo
or https://www.sudo.ws/license.html for complete details.