[Utils] Tools for marking things unsafe for general use (#2326)

* Tools for marking things unsafe for general use

* I'm facepalming so much...

Actually, make the two do something different 
instead of getting distracted writing different docs for both based on intended usage.

* local scopes mmkay + tests

* Move file to adress feedback

* typo fix

* Update __init__.py

* Fix issue with exported names in __init__

* changelog

docs/changelog_3_1_0.rst

@@ -66,6 +66,7 @@ Audio
 Core
 ----
 
+ * Warn on usage of ``yaml.load`` (`#2326`_)
  * New Event dispatch: ``on_message_without_command`` (`#2338`_)
  * Improve output format of cooldown messages (`#2412`_)
  * Delete cooldown messages when expired (`#2469`_)
@@ -173,6 +174,7 @@ Utility Functions
  * ``Tunnel`` - fixed behavior of ``react_close()``, now when tunnel closes message will be sent to other end (`#2507`_)
  * ``chat_formatting.humanize_list`` - Improved error handling of empty lists (`#2597`_)
 
+.. _#2326: https://github.com/Cog-Creators/Red-DiscordBot/pull/2326
 .. _#2328: https://github.com/Cog-Creators/Red-DiscordBot/pull/2328
 .. _#2338: https://github.com/Cog-Creators/Red-DiscordBot/pull/2338
 .. _#2412: https://github.com/Cog-Creators/Red-DiscordBot/pull/2412

redbot/core/__init__.py

@@ -1,8 +1,10 @@
 import colorama as _colorama
 import discord as _discord
+import yaml as _yaml
 
 from .. import __version__, version_info, VersionInfo
 from .config import Config
+from .utils.safety import warn_unsafe as _warn_unsafe
 
 __all__ = ["Config", "__version__", "version_info", "VersionInfo"]
 
@@ -10,3 +12,6 @@ _colorama.init()
 
 # Prevent discord PyNaCl missing warning
 _discord.voice_client.VoiceClient.warn_nacl = False
+
+# Warn on known unsafe usage of dependencies
+_yaml.load = _warn_unsafe(_yaml.load, "Use yaml.safe_load instead. See CVE-2017-18342")

redbot/core/utils/safety.py

@@ -0,0 +1,49 @@
+import warnings
+import functools
+
+
+def unsafe(f, message=None):
+    """
+    Decorator form for marking a function as unsafe.
+
+    This form may not get used much, but there are a few cases
+    we may want to add something unsafe generally, but safe in specific uses.
+
+    The warning can be supressed in the safe context with warnings.catch_warnings
+    This should be used sparingly at most.
+    """
+
+    def wrapper(func):
+        @functools.wraps(func)
+        def get_wrapped(*args, **kwargs):
+            actual_message = message or f"{func.__name__} is unsafe for use"
+            warnings.warn(actual_message, stacklevel=3, category=RuntimeWarning)
+            return func(*args, **kwargs)
+
+        return get_wrapped
+
+    return wrapper
+
+
+def warn_unsafe(f, message=None):
+    """
+    Function to mark function from dependencies as unsafe for use.
+
+    Warning: There is no check that a function has already been modified.
+    This form should only be used in init, if you want to mark an internal function
+    as unsafe, use the decorator form above.
+
+    The warning can be suppressed in safe contexts with warnings.catch_warnings
+    This should be used sparingly at most.
+    """
+
+    def wrapper(func):
+        @functools.wraps(func)
+        def get_wrapped(*args, **kwargs):
+            actual_message = message or f"{func.__name__} is unsafe for use"
+            warnings.warn(actual_message, stacklevel=3, category=RuntimeWarning)
+            return func(*args, **kwargs)
+
+        return get_wrapped
+
+    return wrapper(f)