Add a warning about "dependency confusion" vulnerability

docs/html/reference/pip_install.rst

@@ -1123,37 +1123,46 @@ Examples
 
          py -m pip install --index-url http://my.package.repo/simple/ SomePackage
 
-   Search an additional index during install, in addition to `PyPI`_
+   Install from a local flat directory containing archives (and don't scan indexes):
 
    .. tab:: Unix/macOS
 
       .. code-block:: shell
 
-         python -m pip install --extra-index-url http://my.package.repo/simple SomePackage
+         python -m pip install --no-index --find-links=file:///local/dir/ SomePackage
+         python -m pip install --no-index --find-links=/local/dir/ SomePackage
+         python -m pip install --no-index --find-links=relative/dir/ SomePackage
 
    .. tab:: Windows
 
       .. code-block:: shell
 
-         py -m pip install --extra-index-url http://my.package.repo/simple SomePackage
+         py -m pip install --no-index --find-links=file:///local/dir/ SomePackage
+         py -m pip install --no-index --find-links=/local/dir/ SomePackage
+         py -m pip install --no-index --find-links=relative/dir/ SomePackage
 
-   Install from a local flat directory containing archives (and don't scan indexes):
+   Search an additional index during install, in addition to `PyPI`_
+
+   .. warning::
+
+       Using this option to search for packages which are not in the main
+       repository (such as private packages) is unsafe, per a security
+       vulnerability called
+       `dependency confusion <https://azure.microsoft.com/en-us/resources/3-ways-to-mitigate-risk-using-private-package-feeds/>`_:
+       an attacker can claim the package on the public repository in a way that
+       will ensure it gets chosen over the private package.
 
    .. tab:: Unix/macOS
 
       .. code-block:: shell
 
-         python -m pip install --no-index --find-links=file:///local/dir/ SomePackage
-         python -m pip install --no-index --find-links=/local/dir/ SomePackage
-         python -m pip install --no-index --find-links=relative/dir/ SomePackage
+         python -m pip install --extra-index-url http://my.package.repo/simple SomePackage
 
    .. tab:: Windows
 
       .. code-block:: shell
 
-         py -m pip install --no-index --find-links=file:///local/dir/ SomePackage
-         py -m pip install --no-index --find-links=/local/dir/ SomePackage
-         py -m pip install --no-index --find-links=relative/dir/ SomePackage
+         py -m pip install --extra-index-url http://my.package.repo/simple SomePackage
 
 
 #. Find pre-release and development versions, in addition to stable versions.  By default, pip only finds stable versions.

docs/html/user_guide.rst

@@ -125,7 +125,7 @@ does not come with it included.
 
    pip install keyring
    echo your-password | keyring set pypi.company.com your-username
-   pip install your-package --extra-index-url https://pypi.company.com/
+   pip install your-package --index-url https://pypi.company.com/
 
 .. _keyring: https://pypi.org/project/keyring/
 

news/9647.doc.rst

@@ -0,0 +1 @@
+Add warning about --extra-index-url and dependency confusion