debug option to write all server communication to persistent tempfiles

CHANGELOG.md

@@ -10,11 +10,26 @@ The format of this file should adhere to [Keep a Changelog](https://keepachangel
 
 This project should more or less adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [x.x.x] - unreleased
+## [1.4.0] - unreleased
+
+* Georges Toth did a lot of efforts lifting up the project to more modern standards.
+* A hook for collecting debug information has been in the pull request for ages.  I've decided to include it in 1.4.0.
+
+### Added
 
 * Initial work at integrating typing information. Details in https://github.com/python-caldav/caldav/pull/358
 * Remove dependency on pytz. Details in https://github.com/python-caldav/caldav/issues/231
 * Use setuptools-scm / pyproject.toml (modern packaging). Details in https://github.com/python-caldav/caldav/pull/364
+* Debugging tool - an environment variable can be set, causing the library to spew out server communications into files under /tmp.  Details in https://github.com/python-caldav/caldav/pull/249 and https://github.com/python-caldav/caldav/issues/248
+
+### Security
+
+The debug information gathering hook has been in the limbo for a long time, due to security concerns:
+
+* An attacker that has access to alter the environment the application is running under may cause a DoS-attack, filling up available disk space with debug logging.
+* An attacker that has access to alter the environment the application is running under, and access to read files under /tmp (files being 0600 and owned by the uid the application is running under), will be able to read the communication between the server and the client, communication that may be private and confidential.
+
+Thinking it through three times, I'm not too concerned - if someone has access to alter the environment the process is running under and access to read files run by the uid of the application, then this someone should already be trusted and will probably have the possibility to gather this communication through other means.
 
 ## [1.3.9] - 2023-12-12
 

caldav/davclient.py

@@ -744,4 +744,38 @@ def request(
                 reason = "None given"
             raise error.AuthorizationError(url=str(url_obj), reason=reason)
 
+        if error.debug_dump_communication:
+            from tempfile import NamedTemporaryFile
+            import datetime
+
+            with NamedTemporaryFile(prefix="caldavcomm", delete=False) as commlog:
+                commlog.write(b"=" * 80 + b"\n")
+                commlog.write(f"{datetime.datetime.now():%FT%H:%M:%S}".encode("utf-8"))
+                commlog.write(b"\n====>\n")
+                commlog.write(f"{method} {url}\n".encode("utf-8"))
+                commlog.write(
+                    b"\n".join([to_wire(f"{x}: {headers[x]}") for x in headers])
+                )
+                commlog.write(b"\n\n")
+                commlog.write(to_wire(body))
+                commlog.write(b"<====\n")
+                commlog.write(f"{response.status} {response.reason}".encode("utf-8"))
+                commlog.write(
+                    b"\n".join(
+                        [
+                            to_wire(f"{x}: {response.headers[x]}")
+                            for x in response.headers
+                        ]
+                    )
+                )
+                commlog.write(b"\n\n")
+                ct = response.headers.get("Content-Type", "")
+                if response.tree is not None:
+                    commlog.write(
+                        to_wire(etree.tostring(response.tree, pretty_print=True))
+                    )
+                else:
+                    commlog.write(to_wire(response._raw))
+                commlog.write(b"\n")
+
         return response

caldav/lib/error.py

@@ -7,9 +7,11 @@
 
 from caldav import __version__
 
+debug_dump_communication = False
 try:
     import os
 
+    debug_dump_communication = os.environ.get("PYTHON_CALDAV_COMMDUMP", False)
     ## one of DEBUG_PDB, DEBUG, DEVELOPMENT, PRODUCTION
     debugmode = os.environ["PYTHON_CALDAV_DEBUGMODE"]
 except:

caldav/objects.py

@@ -235,7 +235,10 @@ def _query(
         if root:
             if hasattr(root, "xmlelement"):
                 body = etree.tostring(
-                    root.xmlelement(), encoding="utf-8", xml_declaration=True
+                    root.xmlelement(),
+                    encoding="utf-8",
+                    xml_declaration=True,
+                    pretty_print=error.debug_dump_communication,
                 )
             else:
                 body = root