skip to content
Back to
Home Research Advisories CodeQL Wall of Fame Get Involved Events
December 21, 2023

GHSL-2023-208: Unsafe deserialization in MkDocs

Jorge Rosillo

Coordinated Disclosure Timeline


MkDocs is vulnerable to an unsafe deserialization when parsing configuration files.

Note: After a private discussion with the maintainer, we agreed that a complete fix was not possible given the nature of the project. Instead, there were some partial fixes and documentation updates done on the project.



Tested Version



Unsafe deserialization of configuration files (GHSL-2023-208)

MkDocs uses the YAML format for configuration files such as mkdocs.yml and mkdocs_theme.yml. They are loaded using mkdocs.utils.yaml_load (see how mkdocs.yml and mkdocs_theme.yml are loaded), which, if not provided a loader, will use yaml.Loader, known to be able to instantiate arbitrary constructors.

def get_yaml_loader(loader=yaml.Loader, config: MkDocsConfig | None = None):
    """Wrap PyYaml's loader so we can extend it to suit our needs."""

    class Loader(loader):
        Define a custom loader derived from the global loader to leave the
        global loader unaltered.

    # ...

    return Loader

def yaml_load(source: IO | str, loader: type[yaml.BaseLoader] | None = None) -> dict[str, Any]:
    """Return dict of source YAML file using loader, recursively deep merging inherited parent."""
    loader = loader or get_yaml_loader()
        result = yaml.load(source, Loader=loader)
    except yaml.YAMLError as e:
        raise exceptions.ConfigurationError(
            f"MkDocs encountered an error parsing the configuration file: {e}"

This issue was found using the Unsafe deserialization CodeQL query for python.


This issue may lead to Remote Code Execution.

Proof of concept



Even though the unsafe deserialization of mkdocs.yml has already been discussed and noted as a Won’t Fix given the downsides for the project, there’s still a huge risk in the unsafe deserialization of mkdocs_theme.yml. An attacker may be able to hijack a popular theme, or widely-spread one, and gain access to CI/CD systems and/or developer machines.


This issue was discovered and reported by GHSL team member @jorgectf (Jorge Rosillo).


You can contact the GHSL team at, please include a reference to GHSL-2023-208 in any communication regarding this issue.