PEP 551 v2 (#363)

* Adds socket.getaddrinfo and socket.getnameinfo to list of hooks.

* Updates post-history
Adds note about allowing -i in debug builds
Clarifies some recommendations and wraps the text.

pep-0551.rst

@@ -8,7 +8,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 23-Aug-2017
 Python-Version: 3.7
-Post-History:
+Post-History: 24-Aug-2017 (security-sig)
 
 Abstract
 ========
@@ -135,6 +135,7 @@ On Linux, some specific features that may be integrated are:
 * sd_journal [9]_
 * OpenBSM [10]_
 * syslog [11]_
+* auditd [12]_
 * check execute bit on imported modules
 
 
@@ -357,9 +358,9 @@ rationale for including the hook.
    ``_PyEval_SetSwitchInterval``, ``sys.setswitchinterval``, "``(interval_us,)``
    ", "Detect changes to the switching interval."
    "``socket.bind``, ``socket.connect``, ``socket.connect_ex``,
-   ``socket.sendmsg``, ``socket.sendto``", ``socket.address``, "``(address,)``
-   ", "Detect access to network resources. The address is unmodified from the
-   original call."
+   ``socket.getaddrinfo``, ``socket.getnameinfo``, ``socket.sendmsg``,
+   ``socket.sendto``", ``socket.address``, "``(address,)``", "Detect access to
+   network resources. The address is unmodified from the original call."
    ``socket.__init__``, "socket()", "``(family, type, proto)``", "Detect
    creation of sockets. The arguments will be int values."
    ``socket.gethostname``, ``socket.gethostname``, "", "Detect attempts to
@@ -408,6 +409,11 @@ If a file with the same full path as the process with a ``._pth`` suffix
 used to initialize ``sys.path`` following the rules currently described `for
 Windows <https://docs.python.org/3/using/windows.html#finding-modules>`_.
 
+When built with ``Py_DEBUG``, the ``spython`` entry point will allow a ``-i``
+option with no other arguments to enter into interactive mode, with log messages
+being written to standard error rather than a file. This is intended for testing
+and debugging only.
+
 **Log security events to a file**
 
 Before initialization, ``spython`` will set a log hook that writes events to a
@@ -456,23 +462,76 @@ here, since this is considered opt-in functionality.
 Recommendations
 ===============
 
-Specific recommendations are difficult to make, as the ideal configuration for any environment will depend on the user's ability to manage, monitor, and respond to activity on their own network. However, many of the proposals here do not appear to be of value without deeper illustration. This section provides recommendations using the terms **should** (or **should not**), indicating that we consider it dangerous to ignore the advice, and **may**, indicating that for the advice ought to be considered for high value systems. The term **sysadmins** refers to whoever is responsible for deploying Python throughout your network, though different organizations may have different titles for the relevant person.
+Specific recommendations are difficult to make, as the ideal configuration for
+any environment will depend on the user's ability to manage, monitor, and
+respond to activity on their own network. However, many of the proposals here do
+not appear to be of value without deeper illustration. This section provides
+recommendations using the terms **should** (or **should not**), indicating that
+we consider it dangerous to ignore the advice, and **may**, indicating that for
+the advice ought to be considered for high value systems. The term **sysadmins**
+refers to whoever is responsible for deploying Python throughout your network;
+different organizations may have an alternative title for the responsible
+people.
 
-Sysadmins **should** build their own entry point, likely starting from ``spython``, and directly interface with the security systems available in their environment. The more tightly integrated, the less likely a vulnerability will be found allowing an attacker to bypass those systems. In particular, the entry point **should not** obtain any settings from the current environment, such as environment variables, unless those settings are otherwise protected from modification.
+Sysadmins **should** build their own entry point, likely starting from the
+``spython`` source, and directly interface with the security systems available
+in their environment. The more tightly integrated, the less likely a
+vulnerability will be found allowing an attacker to bypass those systems. In
+particular, the entry point **should not** obtain any settings from the current
+environment, such as environment variables, unless those settings are otherwise
+protected from modification.
 
-The default ``python`` entry point **should not** be deployed to production machines, but could be given to developers to use and test Python on non-production machines. Sysadmins **may** consider deploying a less restrictive version of their entry point to developer machines, since any system connected to your network is a potential target.
+Log messages **should not** be written to a local file. The ``spython`` entry
+point does this for example and testing purposes. On production machines, tools
+such as ETW [7]_ or auditd [12]_ that are intended for this purpose should be
+used.
 
-Python deployments **should** be made read-only using any available platform functionality after deployment and during use.
+The default ``python`` entry point **should not** be deployed to production
+machines, but could be given to developers to use and test Python on
+non-production machines. Sysadmins **may** consider deploying a less restrictive
+version of their entry point to developer machines, since any system connected
+to your network is a potential target.
 
-On platforms that support it, sysadmins **should** include signatures for every file in a Python deployment, ideally verified using a private certificate. For example, Windows supports embedding signatures in executable files and using catalogs for others, and can use DeviceGuard [4]_ to validate signatures either automatically or using an ``open_for_exec`` hook.
+Python deployments **should** be made read-only using any available platform
+functionality after deployment and during use.
 
-Sysadmins **should** collect as many logged events as possible, and **should** copy them off of local machines frequently. Even if logs are not being constantly monitored for suspicious activity, once an attack is detected it is too late to enable logging. Log hooks **should not** attempt to preemptively filter events, as even benign events are useful when analyzing the progress of an attack. (Watch the "No Easy Breach" video under `Further Reading`_ for a deeper look at this side of things.)
+On platforms that support it, sysadmins **should** include signatures for every
+file in a Python deployment, ideally verified using a private certificate. For
+example, Windows supports embedding signatures in executable files and using
+catalogs for others, and can use DeviceGuard [4]_ to validate signatures either
+automatically or using an ``open_for_exec`` hook.
 
-Log hooks **should** write events to logs before attempting to abort. As discussed earlier, it is more important to record malicious actions than to prevent them. Very few actions should be aborted, as most will occur during normal use. Sysadmins **may** audit their Python code and abort operations that are known to never be used deliberately.
+Sysadmins **should** collect as many logged events as possible, and **should**
+copy them off of local machines frequently. Even if logs are not being
+constantly monitored for suspicious activity, once an attack is detected it is
+too late to enable logging. Log hooks **should not** attempt to preemptively
+filter events, as even benign events are useful when analyzing the progress of
+an attack. (Watch the "No Easy Breach" video under `Further Reading`_ for a
+deeper look at this side of things.)
 
-On production machines, the first log hook **should** be set in C code before ``Py_Initialize`` is called, and that hook **should** unconditionally abort the ``sys.addloghook`` event. The Python interface is mainly useful for testing.
+Log hooks **should** write events to logs before attempting to abort. As
+discussed earlier, it is more important to record malicious actions than to
+prevent them.
 
-On production machines, a non-validating ``open_for_exec`` hook **may** be set in C code before ``Py_Initialize`` is called. This prevents later code from overriding the hook, however, logging the ``setopenforexecutehandler`` event is useful since no code should ever need to call it. Using at least the sample ``open_for_exec`` hook implementation from ``spython`` is recommended.
+Most actions **should not** be aborted if they could ever occur during normal
+use or if preventing them will encourage attackers to work around them. As
+described earlier, awareness is a higher priority than prevention. Sysadmins
+**may** audit their Python code and abort operations that are known to never be
+used deliberately.
+
+On production machines, the first log hook **should** be set in C code before
+``Py_Initialize`` is called, and that hook **should** unconditionally abort the
+``sys.addloghook`` event. The Python interface is mainly useful for testing.
+
+To prevent log hooks being added on non-production machines, the entry point
+**may** add a log hook that aborts the ``sys.addloghook`` event but otherwise
+does nothing.
+
+On production machines, a non-validating ``open_for_exec`` hook **may** be set
+in C code before ``Py_Initialize`` is called. This prevents later code from
+overriding the hook, however, logging the ``setopenforexecutehandler`` event is
+useful since no code should ever need to call it. Using at least the sample
+``open_for_exec`` hook implementation from ``spython`` is recommended.
 
 [TODO: more good advice; less bad advice]
 
@@ -545,6 +604,8 @@ References
 
 .. [11] `<https://linux.die.net/man/3/syslog>`_
 
+.. [12] `<http://security.blogoverflow.com/2013/01/a-brief-introduction-to-auditd/>`_
+
 Acknowledgments
 ===============