Merge commit from fork

Author: stsewd

readthedocs/api/v2/serializers.py

@@ -94,6 +94,7 @@ class Meta(ProjectSerializer.Meta):
             "max_concurrent_builds",
             "readthedocs_yaml_path",
             "clone_token",
+            "has_ssh_key_with_write_access",
         )
 
 

readthedocs/doc_builder/director.py

@@ -28,6 +28,7 @@
 from readthedocs.projects.constants import BUILD_COMMANDS_OUTPUT_PATH_HTML
 from readthedocs.projects.constants import GENERIC
 from readthedocs.projects.exceptions import RepositoryError
+from readthedocs.projects.notifications import MESSAGE_PROJECT_SSH_KEY_WITH_WRITE_ACCESS
 from readthedocs.projects.signals import after_build
 from readthedocs.projects.signals import before_build
 from readthedocs.projects.signals import before_vcs
@@ -205,6 +206,23 @@ def checkout(self):
         log.info("Cloning and fetching.")
         self.vcs_repository.update()
 
+        # Check if the key has write access to the repository (RTD Business only).
+        # This check is done immediately after clone step, and before running any
+        # commands that make use of user given input (like the post_checkout job).
+        has_ssh_key_with_write_access = False
+        if settings.ALLOW_PRIVATE_REPOS:
+            has_ssh_key_with_write_access = self.vcs_repository.has_ssh_key_with_write_access()
+            if has_ssh_key_with_write_access != self.data.project.has_ssh_key_with_write_access:
+                self.data.api_client.project(self.data.project.pk).patch(
+                    {"ssh_key_with_write_access": has_ssh_key_with_write_access}
+                )
+            if has_ssh_key_with_write_access:
+                self.attach_notification(
+                    attached_to=f"project/{self.data.project.pk}",
+                    message_id=MESSAGE_PROJECT_SSH_KEY_WITH_WRITE_ACCESS,
+                    dismissable=True,
+                )
+
         identifier = self.data.build_commit or self.data.version.identifier
         log.info("Checking out.", identifier=identifier)
         self.vcs_repository.checkout(identifier)
@@ -262,6 +280,13 @@ def checkout(self):
 
         self.vcs_repository.update_submodules(self.data.config)
 
+        # If the config has a post_checkout job, we stop the build,
+        # as it could be abused to write to the repository.
+        if has_ssh_key_with_write_access and get_dotted_attribute(
+            self.data.config, "build.jobs.post_checkout", None
+        ):
+            raise BuildUserError(BuildUserError.SSH_KEY_WITH_WRITE_ACCESS)
+
     # System dependencies (``build.apt_packages``)
     # NOTE: `system_dependencies` should not be possible to override by the
     # user because it's executed as ``RTD_DOCKER_USER`` (e.g. ``root``) user.
@@ -794,20 +819,26 @@ def store_readthedocs_build_yaml(self):
 
     def attach_notification(
         self,
+        attached_to,
         message_id,
         format_values=None,
         state="unread",
         dismissable=False,
         news=False,
     ):
-        """Attach a notification to build in progress using the APIv2."""
+        """
+        Attach a notification to build in progress using the APIv2.
+
+        :param attached_to: The object to which the notification is attached.
+         It should have the form of `project/{project_id}` or `build/{build_id}`.
+        """
 
         format_values = format_values or {}
         # NOTE: we are using APIv2 here because it uses BuildAPIKey authentication,
         # which is not currently supported by APIv3.
         self.data.api_client.notifications.post(
             {
-                "attached_to": f"build/{self.data.build['id']}",
+                "attached_to": attached_to,
                 "message_id": message_id,
                 "state": state,  # Optional
                 "dismissable": dismissable,

readthedocs/doc_builder/exceptions.py

@@ -52,6 +52,8 @@ class BuildUserError(BuildBaseException):
     BUILD_EXCESSIVE_MEMORY = "build:user:excessive-memory"
     VCS_DEPRECATED = "build:vcs:deprecated"
 
+    SSH_KEY_WITH_WRITE_ACCESS = "build:user:ssh-key-with-write-access"
+
 
 class BuildMaxConcurrencyError(BuildUserError):
     LIMIT_REACHED = "build:user:concurrency-limit-reached"

readthedocs/notifications/messages.py

@@ -218,6 +218,21 @@ def get_rendered_body(self):
         ),
         type=ERROR,
     ),
+    Message(
+        id=BuildUserError.SSH_KEY_WITH_WRITE_ACCESS,
+        header=_("Build aborted due to SSH key with write access."),
+        body=_(
+            textwrap.dedent(
+                """
+                This build has failed because the current deploy key on the repository was created with write permission.
+                For protection against abuse we've restricted use of these deploy keys.
+                A read-only deploy key will need to be set up <b>before July 31, 2025</b> to continue building this project.
+                Read more about this in our <a href="https://about.readthedocs.com/blog/2025/05/ssh-keys-with-write-access/">blog post</a>.
+                """
+            ).strip(),
+        ),
+        type=ERROR,
+    ),
     Message(
         id=BuildAppError.BUILD_DOCKER_UNKNOWN_ERROR,
         header=_("Build terminated due to unknown error."),

readthedocs/projects/migrations/0149_add_ssh_key_with_write_access.py

@@ -0,0 +1,30 @@
+# Generated by Django 4.2.20 on 2025-05-06 22:55
+
+from django.db import migrations
+from django.db import models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy()
+
+    dependencies = [
+        ("projects", "0148_remove_unused_indexes"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="historicalproject",
+            name="has_ssh_key_with_write_access",
+            field=models.BooleanField(
+                default=False, help_text="Project has an SSH key with write access", null=True
+            ),
+        ),
+        migrations.AddField(
+            model_name="project",
+            name="has_ssh_key_with_write_access",
+            field=models.BooleanField(
+                default=False, help_text="Project has an SSH key with write access", null=True
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -4,6 +4,7 @@
 import hashlib
 import hmac
 import os
+import re
 from shlex import quote
 from urllib.parse import urlparse
 
@@ -619,6 +620,14 @@ class Project(models.Model):
         ),
     )
 
+    # Keep track if the SSH key has write access or not (RTD Business),
+    # so we can take further actions if needed.
+    has_ssh_key_with_write_access = models.BooleanField(
+        help_text=_("Project has an SSH key with write access"),
+        default=False,
+        null=True,
+    )
+
     # Property used for storing the latest build for a project when prefetching
     LATEST_BUILD_CACHE = "_latest_build"
 
@@ -897,6 +906,17 @@ def clean_repo(self):
             return self.repo.replace("http://github.com", "https://github.com")
         return self.repo
 
+    @property
+    def repository_html_url(self):
+        if self.remote_repository:
+            return self.remote_repository.html_url
+
+        ssh_url_pattern = re.compile(r"^(?P<user>.+)@(?P<host>.+):(?<repo>.+)$")
+        match = ssh_url_pattern.match(self.repo)
+        if match:
+            return f"https://{match.group('host')}/{match.group('repo')}"
+        return self.repo
+
     # Doc PATH:
     # MEDIA_ROOT/slug/checkouts/version/<repo>
 

readthedocs/projects/notifications.py

@@ -17,6 +17,8 @@
 
 MESSAGE_PROJECT_SKIP_BUILDS = "project:invalid:skip-builds"
 MESSAGE_PROJECT_ADDONS_BY_DEFAULT = "project:addons:by-default"
+MESSAGE_PROJECT_SSH_KEY_WITH_WRITE_ACCESS = "project:ssh-key-with-write-access"
+
 messages = [
     Message(
         id=MESSAGE_PROJECT_SKIP_BUILDS,
@@ -176,5 +178,20 @@
         ),
         type=INFO,
     ),
+    Message(
+        id=MESSAGE_PROJECT_SSH_KEY_WITH_WRITE_ACCESS,
+        header=_("SSH key with read-only access is required"),
+        body=_(
+            textwrap.dedent(
+                """
+                This project has a deploy key with write access to the repository.
+                For protection against abuse we've restricted use of these deploy keys.
+                A read-only deploy key will need to be set up <b>before July 31, 2025</b> to continue building this project.
+                Read more about this in our <a href="https://about.readthedocs.com/blog/2025/05/ssh-keys-with-write-access/">blog post</a>.
+                """
+            ).strip(),
+        ),
+        type=WARNING,
+    ),
 ]
 registry.add(messages)

readthedocs/projects/tasks/builds.py

@@ -496,10 +496,15 @@ def on_failure(self, exc, task_id, args, kwargs, einfo):
         # It may happens the director is not created because the API failed to retrieve
         # required data to initialize it on ``before_start``.
         if self.data.build_director:
+            self.data.build_director.attach_notification(
+                attached_to=f"build/{self.data.build['id']}",
+                message_id=message_id,
+                format_values=format_values,
+            )
+        else:
             log.warning(
                 "We couldn't attach a notification to the build since it failed on an early stage."
             )
-            self.data.build_director.attach_notification(message_id, format_values)
 
         # Send notifications for unhandled errors
         if message_id not in self.exceptions_without_notifications:
@@ -709,7 +714,8 @@ def on_retry(self, exc, task_id, args, kwargs, einfo):
             # Grab the format values from the exception in case it contains
             format_values = exc.format_values if hasattr(exc, "format_values") else None
             self.data.build_director.attach_notification(
-                BuildMaxConcurrencyError.LIMIT_REACHED,
+                attached_to=f"build/{self.data.build['id']}",
+                message_id=BuildMaxConcurrencyError.LIMIT_REACHED,
                 format_values=format_values,
             )
             self.update_build(state=BUILD_STATE_TRIGGERED)

readthedocs/rtd_tests/tests/test_api.py

@@ -3441,6 +3441,7 @@ def test_get_version_by_id(self):
                 "users": [1],
                 "custom_prefix": None,
                 "clone_token": None,
+                "has_ssh_key_with_write_access": False,
             },
             "privacy_level": "public",
             "downloads": {},

readthedocs/vcs_support/backends/git.py

@@ -155,6 +155,98 @@ def clone(self):
                 message_id = RepositoryError.CLONE_ERROR_WITH_PRIVATE_REPO_ALLOWED
             raise RepositoryError(message_id=message_id) from exc
 
+    def has_ssh_key_with_write_access(self) -> bool:
+        """
+        Check if the SSH key has write access to the repository.
+
+        This is done by trying to push to the repository in dry-run mode.
+
+        We create a temporary remote to test the SSH key,
+        since we need the remote to be in the SSH format,
+        which isn't always the case for projects that are public,
+        and changing the URL of the default remote may be a breaking
+        change for some projects.
+
+        .. note::
+
+           This check is better done just after the clone step,
+           to ensure that no commands controled by the user are run.
+        """
+        remote_name = "rtd-test-ssh-key"
+        ssh_url = re.sub("https?://github.com/", "[email protected]:", self.project.repo, 1)
+
+        try:
+            cmd = ["git", "remote", "add", remote_name, ssh_url]
+            self.run(*cmd, record=False)
+
+            cmd = ["git", "push", "--dry-run", remote_name]
+            code, stdout, stderr = self.run(*cmd, record=False, demux=True)
+
+            if code == 0:
+                return True
+
+            # NOTE: if the command fails, it doesn't necessarily mean the key
+            # doesn't have write access, there are a couple of other reasons
+            # why this may fail, so we check for the error message.
+
+            # This error is shown when the repo is archived, but the key has write access.
+            if "ERROR: This repository was archived so it is read-only" in stderr:
+                return True
+
+            # This error is shown when the repo is empty, but we don't know if the key has write access or not.
+            # We assume it has write access just to be safe, future steps will fail after the repo is cloned anyway.
+            # Example: error: src refspec refs/heads/master does not match any
+            pattern = r"error: src refspec refs/heads/\w does not match any"
+            if re.search(pattern, stderr):
+                return True
+
+            # Example: ERROR: Permission to user/repo denied to deploy key
+            pattern = r"ERROR: Permission to .* denied to deploy key"
+            if re.search(pattern, stderr):
+                return False
+
+            errors_read_access_only = [
+                "ERROR: The key you are authenticating with has been marked as read only",
+                "ERROR: Write access to repository not granted",
+                # This error is shown when the key isn't registered in GH at all.
+                "[email protected]: Permission denied (publickey).",
+                # We don't know if the key has write access or not,
+                # but since the key can't be used from the builders,
+                # it should be safe to return False.
+                "ERROR: The repository owner has an IP allow list enabled",
+            ]
+            for pattern in errors_read_access_only:
+                if pattern in stderr:
+                    return False
+
+            # This is an error when the repo URL is not a git+ssh URL,
+            # we don't know if the key has write access or not, as the URL is invalid.
+            # Log and return False for now.
+            if "fatal: could not read Username for" in stderr:
+                log.error(
+                    "Invalid repo URL for SSH key check.",
+                    project_slug=self.project.slug,
+                    repo_url=self.project.repo,
+                    ssh_url=ssh_url,
+                    exit_code=code,
+                    stdout=stdout,
+                    stderr=stderr,
+                )
+                return False
+
+            # Log any other errors that we don't know about.
+            log.error(
+                "Unknown error when checking SSH key access.",
+                project_slug=self.project.slug,
+                exit_code=code,
+                stdout=stdout,
+                stderr=stderr,
+            )
+            return False
+        finally:
+            # Always remove the temporary remote.
+            self.run("git", "remote", "remove", remote_name, record=False)
+
     def fetch(self):
         # --force: Likely legacy, it seems to be irrelevant to this usage
         # --prune: Likely legacy, we don't expect a previous fetch command to have run