8000 bpo-37363: Add audit events for a range of modules (GH-14301) · python/cpython@60419a7 · GitHub
[go: up one dir, main page]
Skip to content

Commit 60419a7

Browse files
zoobazooba
authored
bpo-37363: Add audit events for a range of modules (GH-14301)
1 parent 9bbf4d7 commit 60419a7

37 files changed

+165
-18
lines changed

‎Doc/library/ctypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2046,7 +2046,7 @@ Data types
20462046
.. audit-event:: ctypes.cdata address
20472047

20482048
This method, and others that indirectly call this method, raises an
2049-
:func:`auditing event <sys.audit>` ``ctypes.cdata`` with argument
2049+
:ref:`auditing event <auditing>` ``ctypes.cdata`` with argument
20502050
``address``.
20512051

20522052
.. method:: from_param(obj)

‎Doc/library/ensurepip.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ Module API
119119
*verbosity* controls the level of output to :data:`sys.stdout` from the
120120
bootstrapping operation.
121121

122+
.. audit-event:: ensurepip.bootstrap root
123+
122124
.. note::
123125

124126
The bootstrapping process has side effects on both ``sys.path`` and

‎Doc/library/ftplib.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
190190
*source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
191191
its source address before connecting.
192192

193+
.. audit-event:: ftplib.FTP.connect "self host port"
194+
193195
.. versionchanged:: 3.3
194196
*source_address* parameter was added.
195197

@@ -223,13 +225,17 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
223225

224226
Send a simple command string to the server and return the response string.
225227

228+
.. audit-event:: ftplib.FTP.sendcmd "self cmd"
229+
226230

227231
.. method:: FTP.voidcmd(cmd)
228232

229233
Send a simple command string to the server and handle the response. Return
230234
nothing if a response code corresponding to success (codes in the range
231235
200--299) is received. Raise :exc:`error_reply` otherwise.
232236

237+
.. audit-event:: ftplib.FTP.sendcmd "self cmd"
238+
233239

234240
.. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
235241

‎Doc/library/functions.rst

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,8 @@ are always available. They are listed here in alphabetical order.
128128
:func:`breakpoint` will automatically call that, allowing you to drop into
129129
the debugger of choice.
130130

131+
.. audit-event:: builtins.breakpoint "sys.breakpointhook"
132+
131133
.. versionadded:: 3.7
132134

133135
.. _func-bytearray:
@@ -277,7 +279,7 @@ are always available. They are listed here in alphabetical order.
277279

278280
.. audit-event:: compile "source filename"
279281

280-
Raises an :func:`auditing event <sys.audit>` ``compile`` with arguments
282+
Raises an :ref:`auditing event <auditing>` ``compile`` with arguments
281283
``source`` and ``filename``. This event may also be raised by implicit
282284
compilation.
283285

@@ -490,8 +492,8 @@ are always available. They are listed here in alphabetical order.
490492

491493
.. audit-event:: exec code_object
492494

493-
Raises an :func:`auditing event <sys.audit>` ``exec`` with the code object as
494-
the argument. Code compilation events may also be raised.
495+
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
496+
as the argument. Code compilation events may also be raised.
495497

496498
.. index:: builtin: exec
497499

@@ -525,8 +527,8 @@ are always available. They are listed here in alphabetical order.
525527

526528
.. audit-event:: exec code_object
527529

528-
Raises an :func:`auditing event <sys.audit>` ``exec`` with the code object as
529-
the argument. Code compilation events may also be raised.
530+
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
531+
as the argument. Code compilation events may also be raised.
530532

531533
.. note::
532534

@@ -779,7 +781,7 @@ are always available. They are listed here in alphabetical order.
779781

780782
.. audit-event:: builtins.input prompt
781783

782-
Raises an :func:`auditing event <sys.audit>` ``builtins.input`` with
784+
Raises an :ref:`auditing event <auditing>` ``builtins.input`` with
783785
argument ``prompt`` before reading input
784786

785787
.. audit-event:: builtins.input/result result

‎Doc/library/glob.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ For example, ``'[?]'`` matches the character ``'?'``.
5252
more directories and subdirectories. If the pattern is followed by an
5353
``os.sep``, only directories and subdirectories match.
5454

55+
.. audit-event:: glob.glob "pathname recursive"
56+
5557
.. note::
5658
Using the "``**``" pattern in large directory trees may consume
5759
an inordinate amount of time.
@@ -65,6 +67,8 @@ For example, ``'[?]'`` matches the character ``'?'``.
6567
Return an :term:`iterator` which yields the same values as :func:`glob`
6668
without actually storing them all simultaneously.
6769

70+
.. audit-event:: glob.glob "pathname recursive"
71+
6872

6973
.. function:: escape(pathname)
7074

‎Doc/library/imaplib.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,8 @@ An :class:`IMAP4` instance has the following methods:
361361
:meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
362362
this method.
363363

364+
.. audit-event:: imaplib.IMAP4.open "self host port"
365+
364366

365367
.. method:: IMAP4.partial(message_num, message_part, start, length)
366368

@@ -430,6 +432,8 @@ An :class:`IMAP4` instance has the following methods:
430432

431433
Sends ``data`` to the remote server. You may override this method.
432434

435+
.. audit-event:: imaplib.IMAP4.send "self data"
436+
433437

434438
.. method:: IMAP4.setacl(mailbox, who, what)
435439

‎Doc/library/io.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ High-level Module Interface
122122

123123
.. audit-event:: open "path mode flags"
124124

125-
This function raises an :func:`auditing event <sys.audit>` ``open`` with
125+
This function raises an :ref:`auditing event <auditing>` ``open`` with
126126
arguments ``path``, ``mode`` and ``flags``. The ``mode`` and ``flags``
127127
arguments may have been modified or inferred from the original call.
128128

‎Doc/library/nntplib.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,11 @@ The module itself defines the following classes:
7979
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
8080
>>>
8181

82+
.. audit-event:: nntplib.NNTP "self host port"
83+
84+
All commands will raise an :ref:`auditing event <auditing>`
85+
``nntplib.NNTP.putline`` with arguments ``self`` and ``line``,
86+
where ``line`` is the bytes about to be sent to the remote host.
8287

8388
.. versionchanged:: 3.2
8489
*usenetrc* is now ``False`` by default.
@@ -100,6 +105,12 @@ The module itself defines the following classes:
100105
STARTTLS as described below. However, some servers only support the
101106
former.
102107

108+
.. audit-event:: nntplib.NNTP "self host port"
109+
110+
All commands will raise an :ref:`auditing event <auditing>`
111+
``nntplib.NNTP.putline`` with arguments ``self`` and ``line``,
112+
where ``line`` is the bytes about to be sent to the remote host.
113+
103114
.. versionadded:: 3.2
104115

105116
.. versionchanged:: 3.4

‎Doc/library/os.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1801,6 +1801,8 @@ features:
18011801
This function can also support :ref:`specifying a file descriptor
18021802
<path_fd>`; the file descriptor must refer to a directory.
18031803

1804+
.. audit-event:: os.listdir path
1805+
18041806
.. note::
18051807
To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`.
18061808

@@ -2178,6 +2180,8 @@ features:
21782180
This function can also support :ref:`specifying a file descriptor
21792181
<path_fd>`; the file descriptor must refer to a directory.
21802182

2183+
.. audit-event:: os.scandir path
2184+
21812185
The :func:`scandir` iterator supports the :term:`context manager` protocol
21822186
and has the following method:
21832187

‎Doc/library/pdb.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,8 @@ access further features, you have to do this yourself:
181181

182182
import pdb; pdb.Pdb(skip=['django.*']).set_trace()
183183

184+
.. audit-event:: pdb.Pdb
185+
184186
.. versionadded:: 3.1
185187
The *skip* argument.
186188

‎Doc/library/poplib.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ The :mod:`poplib` module provides two classes:
3939
connection attempt (if not specified, the global default timeout setting will
4040
be used).
4141

42+
.. audit-event:: poplib.POP3 "self host port"
43+
44+
All commands will raise an :ref:`auditing event <auditing>`
45+
``poplib.POP3.putline`` with arguments ``self`` and ``line``,
46+
where ``line`` is the bytes about to be sent to the remote host.
47+
4248

4349
.. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None, timeout=None, context=None)
4450

@@ -54,6 +60,12 @@ The :mod:`poplib` module provides two classes:
5460
point to PEM-formatted private key and certificate chain files,
5561
respectively, for the SSL connection.
5662

63+
.. audit-event:: poplib.POP3 "self host port"
64+
65+
All commands will raise an :ref:`auditing event <auditing>`
66+
``poplib.POP3.putline`` with arguments ``self`` and ``line``,
67+
where ``line`` is the bytes about to be sent to the remote host.
68+
5769
.. versionchanged:: 3.2
5870
*context* parameter added.
5971

‎Doc/library/shutil.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,8 @@ Directory and files operations
249249
  as arguments. By default, :func:`~shutil.copy2` is used, but any function
250250
  that supports the same signature (like :func:`~shutil.copy`) can be used.
251251

252+
.. audit-event:: shutil.copytree "src dst"
253+
252254
.. versionchanged:: 3.3
253255
Copy metadata when *symlinks* is false.
254256
Now returns *dst*.
@@ -296,6 +298,8 @@ Directory and files operations
296298
*excinfo*, will be the exception information returned by
297299
:func:`sys.exc_info`. Exceptions raised by *onerror* will not be caught.
298300

301+
.. audit-event:: shutil.rmtree path
302+
299303
.. versionchanged:: 3.3
300304
Added a symlink attack resistant version that is used automatically
301305
if platform supports fd-based functions.
@@ -558,6 +562,8 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
558562

559563
The *verbose* argument is unused and deprecated.
560564

565+
.. audit-event:: shutil.make_archive "base_name format root_dir base_dir"
566+
561567
.. versionchanged:: 3.8
562568
The modern pax (POSIX.1-2001) format is now used instead of
563569
the legacy GNU format for archives created with ``format="tar"``.

‎Doc/library/smtplib.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,10 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
5555
(250, b'Ok')
5656
>>>
5757

58+
All commands will raise an :ref:`auditing event <auditing>`
59+
``smtplib.SMTP.send`` with arguments ``self`` and ``data``,
60+
where ``data`` is the bytes about to be sent to the remote host.
61+
5862
.. versionchanged:: 3.3
5963
Support for the :keyword:`with` statement was added.
6064

@@ -242,6 +246,8 @@ An :class:`SMTP` instance has the following methods:
242246
2-tuple of the response code and message sent by the server in its
243247
connection response.
244248

249+
.. audit-event:: smtplib.SMTP.connect "self host port"
250+
245251

246252
.. method:: SMTP.helo(name='')
247253

‎Doc/library/sqlite3.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,8 @@ Module functions and constants
224224
More information about this feature, including a list of recognized options, can
225225
be found in the `SQLite URI documentation <https://www.sqlite.org/uri.html>`_.
226226

227+
.. audit-event:: sqlite3.connect "database"
228+
227229
.. versionchanged:: 3.4
228230
Added the *uri* parameter.
229231

‎Doc/library/subprocess.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -585,6 +585,13 @@ functions.
585585
with Popen(["ifconfig"], stdout=PIPE) as proc:
586586
log.write(proc.stdout.read())
587587

588+
.. audit-event:: subprocess.Popen "executable args cwd env"
589+
590+
Popen and the other functions in this module that use it raise an
591+
:ref:`auditing event <auditing>` ``subprocess.Popen`` with arguments
592+
``executable``, ``args``, ``cwd``, ``env``. The value for ``args``
593+
may be a single string or a list of strings, depending on platform.
594+
588595
.. versionchanged:: 3.2
589596
Added context manager support.
590597

‎Doc/library/telnetlib.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,8 @@ Telnet Objects
141141

142142
Do not try to reopen an already connected instance.
143143

144+
.. audit-event:: telnetlib.Telnet.open "self host port"
145+
144146

145147
.. method:: Telnet.msg(msg, *args)
146148

@@ -176,6 +178,8 @@ Telnet Objects
176178
block if the connection is blocked. May raise :exc:`OSError` if the
177179
connection is closed.
178180

181+
.. audit-event:: telnetlib.Telnet.write "self buffer"
182+
179183
.. versionchanged:: 3.3
180184
This method used to raise :exc:`socket.error`, which is now an alias
181185
of :exc:`OSError`.

‎Doc/library/tempfile.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ The module defines the following user-callable items:
6262
The :py:data:`os.O_TMPFILE` flag is used if it is available and works
6363
(Linux-specific, requires Linux kernel 3.11 or later).
6464

65+
.. audit-event:: tempfile.mkstemp "full-path"
66+
6567
.. versionchanged:: 3.5
6668

6769
The :py:data:`os.O_TMPFILE` flag is now used if available.
@@ -85,6 +87,8 @@ The module defines the following user-callable items:
8587
attribute is the underlying true file object. This file-like object can
8688
be used in a :keyword:`with` statement, just like a normal file.
8789

90+
.. audit-event:: tempfile.mkstemp "full-path"
91+
8892
.. versionchanged:: 3.8
8993
Added *errors* parameter.
9094

@@ -130,6 +134,8 @@ The module defines the following user-callable items:
130134
The directory can be explicitly cleaned up by calling the
131135
:func:`cleanup` method.
132136

137+
.. audit-event:: tempfile.mkdtemp "full-path"
138+
133139
.. versionadded:: 3.2
134140

135141

@@ -177,6 +183,8 @@ The module defines the following user-callable items:
177183
file (as would be returned by :func:`os.open`) and the absolute pathname
178184
of that file, in that order.
179185

186+
.. audit-event:: tempfile.mkstemp "full-path"
187+
180188
.. versionchanged:: 3.5
181189
*suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
182190
obtain a bytes return value. Prior to this, only str was allowed.
@@ -198,6 +206,8 @@ The module defines the following user-callable items:
198206

199207
:func:`mkdtemp` returns the absolute pathname of the new directory.
200208

209+
.. audit-event:: tempfile.mkdtemp "full-path"
210+
201211
.. versionchanged:: 3.5
202212
*suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
203213
obtain a bytes return value. Prior to this, only str was allowed.

‎Doc/library/urllib.request.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ The :mod:`urllib.request` module defines the following functions:
9797

9898
.. audit-event:: urllib.Request "fullurl data headers method"
9999

100-
The default opener raises an :func:`auditing event <sys.audit>`
100+
The default opener raises an :ref:`auditing event <auditing>`
101101
``urllib.Request`` with arguments ``fullurl``, ``data``, ``headers``,
102102
``method`` taken from the request object.
103103

‎Doc/library/webbrowser.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ The following functions are defined:
6464
may work and start the operating system's associated program. However, this
6565
is neither supported nor portable.
6666

67+
.. audit-event:: webbrowser.open "url"
68+
6769

6870
.. function:: open_new(url)
6971

‎Doc/tools/extensions/suspicious.py

Lines changed: 5 additions & 5 deletions
< 9999 td data-grid-cell-id="diff-7f970e610bbba2772f382f36ee03bcb5e5c3506bd46a0f1f6db85fab1cfd5b64-120-120-2" data-line-anchor="diff-7f970e610bbba2772f382f36ee03bcb5e5c3506bd46a0f1f6db85fab1cfd5b64R120" data-selected="false" role="gridcell" style="background-color:var(--bgColor-default);padding-right:24px" tabindex="-1" valign="top" class="focusable-grid-cell diff-text-cell right-side-diff-cell left-side">
for rule in unused_rules:
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,8 @@ def write_doc(self, docname, doctree):
115115
def finish(self):
116116
unused_rules = [rule for rule in self.rules if not rule.used]
117117
if unused_rules:
118-
self.warn('Found %s/%s unused rules:' %
119-
(len(unused_rules), len(self.rules)))
118+
self.logger.warn('Found %s/%s unused rules:' %
119+
(len(unused_rules), len(self.rules)))
120120
121121
self.logger.info(repr(rule))
122122
return
@@ -151,10 +151,10 @@ def report_issue(self, text, lineno, issue):
151151
self.any_issue = True
152152
self.write_log_entry(lineno, issue, text)
153153
if py3:
154-
self.warn('[%s:%d] "%s" found in "%-.120s"' %
155-
(self.docname, lineno, issue, text))
154+
self.logger.warn('[%s:%d] "%s" found in "%-.120s"' %
155+
(self.docname, lineno, issue, text))
156156
else:
157-
self.warn('[%s:%d] "%s" found in "%-.120s"' % (
157+
self.logger.warn('[%s:%d] "%s" found in "%-.120s"' % (
158158
self.docname.encode(sys.getdefaultencoding(),'replace'),
159159
lineno,
160160
issue.encode(sys.getdefaultencoding(),'replace'),

0 commit comments

Comments
 (0)
0