doc/sudo_plugin_python: document approval plugin and PluginReject
This commit is contained in:
Robert Manner
committed by
Todd C. Miller
Todd C. Miller
parent
06b1f58e9f
commit
95dce8cbe6
@@ -17,6 +17,7 @@
|
||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "SUDO_PLUGIN_PYTHON" "5" "December 21, 2019" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
|
||||
.TH "SUDO_PLUGIN_PYTHON" "5" "February 19, 2020" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
|
||||
.nh
|
||||
.if n .ad l
|
||||
.SH "NAME"
|
||||
@@ -120,23 +121,28 @@ If a function returns
|
||||
(for example, if it does not call return),
|
||||
it will be considered to have returned
|
||||
\fRsudo.RC.OK\fR.
|
||||
If an exception is raised (other than sudo.PluginError), the backtrace will be
|
||||
If an exception is raised (other than sudo.PluginException), the backtrace will be
|
||||
shown to the user and the plugin function will return
|
||||
\fRsudo.RC.ERROR\fR.
|
||||
If that is not acceptable, you must catch the exception and handle it yourself.
|
||||
.PP
|
||||
Instead of just returning
|
||||
\fRsudo.RC.ERROR\fR
|
||||
or
|
||||
\fRsudo.RC.REJECT\fR
|
||||
result code the plugin can also provide a message describing the problem.
|
||||
This can be done by raising the special exception:
|
||||
This can be done by raising one of the special exceptions:
|
||||
.nf
|
||||
.sp
|
||||
.RS 6n
|
||||
raise sudo.PluginError("Message")
|
||||
raise sudo.PluginReject("Message")
|
||||
.RE
|
||||
.fi
|
||||
.PP
|
||||
This added message will be used by the audit plugins.
|
||||
Both exceptions inherit from
|
||||
\fRsudo.PluginException\fR
|
||||
.SS "Python Plugin Loader"
|
||||
Running the Python interpreter and bridging between C and Python is
|
||||
handled by the
|
||||
@@ -156,6 +162,7 @@ sudo.conf(@mansectform@):
|
||||
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>
|
||||
.RE
|
||||
.fi
|
||||
.PP
|
||||
@@ -1105,6 +1112,148 @@ Plugin python_audit python_plugin.so \e
|
||||
.fi
|
||||
.PP
|
||||
It will log the plugin accept / reject / error results to the output.
|
||||
.SS "Approval plugin API"
|
||||
Approval plugins must be registered in
|
||||
sudo.conf(@mansectform@).
|
||||
For example:
|
||||
.nf
|
||||
.sp
|
||||
.RS 6n
|
||||
Plugin python_approval python_plugin.so ModulePath=<path> ClassName=<class>
|
||||
.RE
|
||||
.fi
|
||||
.PP
|
||||
Sudo supports loading multiple approval plugins.
|
||||
Currently only 8 python approval plugins can be loaded at once.
|
||||
.PP
|
||||
An approval plugin may have the following member functions:
|
||||
.TP 6n
|
||||
\fBconstructor\fR
|
||||
.nf
|
||||
.RS 6n
|
||||
__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, ...])
|
||||
.RE
|
||||
.fi
|
||||
.RS 6n
|
||||
.sp
|
||||
Optional.
|
||||
The default constructor will set the keyword arguments it receives
|
||||
as member variables in the object.
|
||||
.sp
|
||||
The constructor matches the
|
||||
\fBopen\fR()
|
||||
function in the C sudo plugin API.
|
||||
.sp
|
||||
The function arguments are as follows:
|
||||
.TP 6n
|
||||
\fIuser_env\fR
|
||||
The user's environment as a tuple of strings in
|
||||
\(lqkey=value\(rq
|
||||
format.
|
||||
.TP 6n
|
||||
\fIsettings\fR
|
||||
A tuple of user-supplied
|
||||
\fIsudo\fR
|
||||
settings in the form of
|
||||
\(lqkey=value\(rq
|
||||
strings.
|
||||
.TP 6n
|
||||
\fIversion\fR
|
||||
The version of the Python Approval Plugin API.
|
||||
.TP 6n
|
||||
\fIuser_info\fR
|
||||
A tuple of information about the user running the command in the form of
|
||||
\(lqkey=value\(rq
|
||||
strings.
|
||||
.TP 6n
|
||||
\fIplugin_options\fR
|
||||
The plugin options passed as arguments in the
|
||||
sudo.conf(@mansectform@)
|
||||
plugin registration.
|
||||
This is a tuple of strings, usually (but not necessarily) in
|
||||
\(lqkey=value\(rq
|
||||
format.
|
||||
.TP 6n
|
||||
\fIsubmit_optind\fR
|
||||
The index into
|
||||
\fIsubmit_argv\fR
|
||||
that corresponds to the first entry that is not a command line option.
|
||||
.TP 6n
|
||||
\fIsubmit_argv\fR
|
||||
The argument vector sudo was invoked with, including all command line options.
|
||||
.PD 0
|
||||
.PP
|
||||
.RE
|
||||
.PD
|
||||
.TP 6n
|
||||
\fBshow_version\fR
|
||||
.nf
|
||||
.RS 6n
|
||||
show_version(self, is_verbose: int) -> int
|
||||
.RE
|
||||
.fi
|
||||
.RS 6n
|
||||
.sp
|
||||
Display the version. (Same as for all the other plugins.)
|
||||
.RE
|
||||
.TP 6n
|
||||
\fBcheck\fR
|
||||
.br
|
||||
.nf
|
||||
.RS 6n
|
||||
check(self, command_info: Tuple[str, ...], run_argv: Tuple[str, ...],
|
||||
run_env: Tuple[str, ...]) -> int
|
||||
.RE
|
||||
.fi
|
||||
.RS 6n
|
||||
.sp
|
||||
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:
|
||||
.nf
|
||||
.sp
|
||||
.RS 12n
|
||||
raise sudo.PluginReject("some message")
|
||||
.RE
|
||||
.fi
|
||||
.sp
|
||||
with the message describing the problem.
|
||||
In the latter case, the audit plugins will get the description.
|
||||
.sp
|
||||
The function arguments are as follows:
|
||||
.TP 6n
|
||||
command_info
|
||||
A vector of information describing the command that will run.
|
||||
See the
|
||||
sudo_plugin(@mansectform@)
|
||||
manual for possible values.
|
||||
.TP 6n
|
||||
run_argv
|
||||
Argument vector describing a command that will be run.
|
||||
.TP 6n
|
||||
run_env
|
||||
The environment the command will be run with.
|
||||
.PD 0
|
||||
.PP
|
||||
.RE
|
||||
.PD
|
||||
.SS "Approval plugin example"
|
||||
Sudo ships a Python Approval plugin example.
|
||||
To try it, register it by adding the following lines to
|
||||
\fI@sysconfdir@/sudo.conf\fR:
|
||||
.nf
|
||||
.sp
|
||||
.RS 6n
|
||||
Plugin python_approval python_plugin.so \e
|
||||
ModulePath=@prefix@/share/doc/sudo/examples/example_approval_plugin.py \e
|
||||
ClassName=BusinessHoursApprovalPlugin
|
||||
.RE
|
||||
.fi
|
||||
.PP
|
||||
It will only allow execution of commands in the "business hours" (from Monday
|
||||
to Friday between 8:00 and 17:59:59).
|
||||
.SS "Sudoers group provider plugin API"
|
||||
A group provider plugin is registered in the
|
||||
sudoers(@mansectform@)
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
.\" 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
|
||||
.Dd February 19, 2020
|
||||
.Dt SUDO_PLUGIN_PYTHON @mansectform@
|
||||
.Os Sudo @PACKAGE_VERSION@
|
||||
.Sh NAME
|
||||
@@ -101,20 +101,25 @@ If a function returns
|
||||
(for example, if it does not call return),
|
||||
it will be considered to have returned
|
||||
.Dv sudo.RC.OK .
|
||||
If an exception is raised (other than sudo.PluginError), the backtrace will be
|
||||
If an exception is raised (other than sudo.PluginException), 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.
|
||||
.Pp
|
||||
Instead of just returning
|
||||
.Dv sudo.RC.ERROR
|
||||
or
|
||||
.Dv sudo.RC.REJECT
|
||||
result code the plugin can also provide a message describing the problem.
|
||||
This can be done by raising the special exception:
|
||||
This can be done by raising one of the special exceptions:
|
||||
.Bd -literal -offset indent
|
||||
raise sudo.PluginError("Message")
|
||||
raise sudo.PluginReject("Message")
|
||||
.Ed
|
||||
.Pp
|
||||
This added message will be used by the audit plugins.
|
||||
Both exceptions inherit from
|
||||
.Dv sudo.PluginException
|
||||
.Ss Python Plugin Loader
|
||||
Running the Python interpreter and bridging between C and Python is
|
||||
handled by the
|
||||
@@ -132,6 +137,7 @@ Example usage in
|
||||
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>
|
||||
.Ed
|
||||
.Pp
|
||||
Example group provider plugin usage in the
|
||||
@@ -875,6 +881,113 @@ Plugin python_audit python_plugin.so \e
|
||||
.Ed
|
||||
.Pp
|
||||
It will log the plugin accept / reject / error results to the output.
|
||||
.Ss Approval plugin API
|
||||
Approval plugins must be registered in
|
||||
.Xr sudo.conf @mansectform@ .
|
||||
For example:
|
||||
.Bd -literal -offset indent
|
||||
Plugin python_approval python_plugin.so ModulePath=<path> ClassName=<class>
|
||||
.Ed
|
||||
.Pp
|
||||
Sudo supports loading multiple approval plugins.
|
||||
Currently only 8 python approval plugins can be loaded at once.
|
||||
.Pp
|
||||
An approval 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, ...],
|
||||
submit_optind: int, submit_argv: Tuple[str, ...])
|
||||
.Ed
|
||||
.Pp
|
||||
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 Approval 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.
|
||||
.It Fa submit_optind
|
||||
The index into
|
||||
.Fa submit_argv
|
||||
that corresponds to the first entry that is not a command line option.
|
||||
.It Fa submit_argv
|
||||
The argument vector sudo was invoked with, including all command line options.
|
||||
.El
|
||||
.It Sy show_version
|
||||
.Bd -literal -compact
|
||||
show_version(self, is_verbose: int) -> int
|
||||
.Ed
|
||||
.Pp
|
||||
Display the version. (Same as for all the other plugins.)
|
||||
.It Sy check
|
||||
.Bd -literal -compact
|
||||
check(self, command_info: Tuple[str, ...], run_argv: Tuple[str, ...],
|
||||
run_env: Tuple[str, ...]) -> int
|
||||
.Ed
|
||||
.Pp
|
||||
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:
|
||||
.Bd -literal -offset indent
|
||||
raise sudo.PluginReject("some message")
|
||||
.Ed
|
||||
.Pp
|
||||
with the message describing the problem.
|
||||
In the latter case, the audit plugins will get the description.
|
||||
.Pp
|
||||
The function arguments are as follows:
|
||||
.Bl -tag -width 4n
|
||||
.It command_info
|
||||
A vector of information describing the command that will run.
|
||||
See the
|
||||
.Xr sudo_plugin @mansectform@
|
||||
manual for possible values.
|
||||
.It run_argv
|
||||
Argument vector describing a command that will be run.
|
||||
.It run_env
|
||||
The environment the command will be run with.
|
||||
.El
|
||||
.El
|
||||
.Ss Approval plugin example
|
||||
Sudo ships a Python Approval plugin example.
|
||||
To try it, register it by adding the following lines to
|
||||
.Pa @sysconfdir@/sudo.conf :
|
||||
.Bd -literal -offset indent
|
||||
Plugin python_approval python_plugin.so \e
|
||||
ModulePath=@prefix@/share/doc/sudo/examples/example_approval_plugin.py \e
|
||||
ClassName=BusinessHoursApprovalPlugin
|
||||
.Ed
|
||||
.Pp
|
||||
It will only allow execution of commands in the "business hours" (from Monday
|
||||
to Friday between 8:00 and 17:59:59).
|
||||
.Ss Sudoers group provider plugin API
|
||||
A group provider plugin is registered in the
|
||||
.Xr sudoers @mansectform@
|
||||
|
||||
Reference in New Issue
Block a user