diff --git a/Makefile b/Makefile index a76ea9a..e5262be 100644 --- a/Makefile +++ b/Makefile @@ -19,8 +19,7 @@ format: doc: $(VENV)/bin/sphinx-build . $(ACTIVATE) && \ - cd docs && \ - make html + make -C docs html clean: clean-build clean-pyc clean-test diff --git a/docs/hacking.rst b/docs/hacking.rst new file mode 100644 index 0000000..7a72eaa --- /dev/null +++ b/docs/hacking.rst @@ -0,0 +1,42 @@ +======================= +Hacking on CacheControl +======================= + +CacheControl is a pure Python library. We use uv_ to manage its development. + +Linting and Formatting +====================== + +We use Ruff_ and mypy_ for linting/formatting and type checking. You can run +them with: + +.. code-block:: console + + $ make lint + $ make format + +Tests +===== + +The tests are all in ``cachecontrol/tests`` and are runnable by ``py.test``. + +You can use ``make test`` to run the tests: + +.. code-block:: console + + $ make test + +Documentation +============= + +The documentation is built with Sphinx_. You can build it by running +``make doc``: + +.. code-block:: console + + $ make doc + +.. _uv: https://docs.astral.sh/uv/ +.. _Ruff: https://docs.astral.sh/ruff/ +.. _mypy: https://mypy-lang.org/ +.. _Sphinx: https://www.sphinx-doc.org/ diff --git a/docs/index.rst b/docs/index.rst index 4e068df..4a385b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,6 +34,10 @@ requirements. See :doc:`storage` for more info. Quick Start =========== +.. important:: + + You **must** read the :doc:`security` page before using CacheControl. + For the impatient, here is how to get started using CacheControl: .. code-block:: python @@ -52,25 +56,11 @@ For the impatient, here is how to get started using CacheControl: This uses a thread-safe in-memory dictionary for storage. -Tests -===== - -The tests are all in ``cachecontrol/tests`` and are runnable by ``py.test``. - - Disclaimers =========== -CacheControl is relatively new and might have bugs. I have made an -effort to faithfully port the tests from httplib2 to CacheControl, but -there is a decent chance that I've missed something. Please file bugs -if you find any issues! - -With that in mind, CacheControl has been used successfully in -production environments, replacing httplib2's usage. - -If you give it a try, please let me know of any issues. - +HTTP caching comes with important security considerations. Please +read the :doc:`security` page for more information. .. _httplib2: https://github.com/httplib2/httplib2 .. _requests: https://requests.readthedocs.io/en/latest/ @@ -89,12 +79,14 @@ Contents etags custom_heuristics tips + security .. toctree:: :hidden: :caption: Development :maxdepth: 2 + hacking release_notes GitHub PyPI diff --git a/docs/security.rst b/docs/security.rst new file mode 100644 index 0000000..293e973 --- /dev/null +++ b/docs/security.rst @@ -0,0 +1,77 @@ +.. + SPDX-FileCopyrightText: SPDX-FileCopyrightText: 2026 William Woodruff + + SPDX-License-Identifier: Apache-2.0 + +======================= +Security Considerations +======================= + +HTTP caching is a security-sensitive operation. Improper caching and use +of cached data can introduce security vulnerabilities into otherwise secure +applications. + +This page will help you decide if you *can* use CacheControl securely +in your application, and if so, how to do so. + +CacheControl's security model +============================= + +CacheControl's security model is based on the following assumptions: + +* CacheControl provides a **private** cache. This means that both shared + *and* private responses are cached, and the cache is assumed to be accessible only + to a single logical user. You **cannot** use CacheControl securely + in a multi-user environment where cached data may be shared between + different logical users. **Do not** use CacheControl for this; + it **will** end badly for you. + +* You **must** treat cached data as potentially sensitive. CacheControl + does not natively encrypt or otherwise protect cached data. If an attacker + can read your cache, they can read all cached responses. You must + ensure that your cache storage is protected appropriately for the + sensitivity of the data you are caching. Another framing of this is that + CacheControl **assumes** the security of your cache storage, similar to + how browsers assume the security of your local machine for the purpose + of storing history, cookies, and cached data. + +* You **must** trust the origins (i.e., servers) + you are communicating with. A malicious origin can always send + you malicious responses, which in the context of caching can mean + sending you cacheable responses that you don't expect, spamming you + with cache entries, and so on. In practice, this means that you must + also trust your transport layer; if you use HTTP, any + adversary on your network path can tamper with your connected + origin's responses, and CacheControl has no way to protect you from that. + +Conversely, here are some assumptions that CacheControl **does** attempt +to enforce; violating these assumptions would be a security vulnerability in +CacheControl itself: + +* An attacker should not be able to trick CacheControl into caching across + origins. For example, an attacker who controls ``evil.example.com`` + should not be able to trick CacheControl into caching responses for + ``bank.example.com``. + +* An attacker should not be able to trick CacheControl into serving cached + responses to requests that would not normally receive those cached + responses. For example, an attacker should not be able to trick + CacheControl into serving a cached response to an unauthenticated + request when the cached response was originally received in response + to an authenticated request. + +Reporting security issues +========================= + +.. important:: + + Please make sure to read the security model above before reporting + issues. Reports that don't take the security model into account will + be considered invalid. + +We take security reports very seriously, and aim to address them as quickly +as possible. + +Please use GitHub's `security advisory process`_ to report security issues. + +.. _security advisory process: https://github.com/psf/cachecontrol/security/advisories/new diff --git a/docs/usage.rst b/docs/usage.rst index 744d93c..03ed78a 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -7,6 +7,10 @@ Using CacheControl ==================== +.. important:: + + You **must** read the :doc:`security` page before using CacheControl. + CacheControl assumes you are using a `requests.Session` for your requests. If you are making ad-hoc requests using `requests.get` then you probably are not terribly concerned about caching.