Summary
When Backstage TechDocs is configured with runIn: local, a malicious contributor who can modify a repository's mkdocs.yml file may configure MkDocs hooks that execute arbitrary Python code on the TechDocs build server.
This becomes risky in environments where untrusted or partially trusted users can influence mkdocs.yml for projects processed by TechDocs.
Affected context
The vulnerability appears in Backstage deployments using the @backstage/plugin-techdocs-node package with TechDocs configured to run builds locally (runIn: local), rather than inside a fully isolated environment.
It is relevant when:
- TechDocs automatically processes documentation from source repositories, and
- Contributors are able to submit or change
mkdocs.ymlfiles that TechDocs consumes.
The risk is most pronounced in multi-tenant or large engineering organizations where documentation repositories may be writable by many users or external contributors.
Exploit preconditions
- Attack surface: TechDocs build process on the Backstage backend or associated build server.
- Required access: Ability to submit, push, or modify a repository's
mkdocs.ymlfile that TechDocs will process. - Trigger point: A TechDocs build gets initiated for the affected repository (e.g., via scheduled build, manual trigger, or on-demand preview).
- Why exploitation is possible: The TechDocs Node plugin passes user-controlled
mkdocs.ymlconfiguration, including thehookssection, directly to MkDocs, which executes configured Python hooks during the build lifecycle. This effectively allows user-controlled configuration to introduce and run arbitrary Python code.
Why this happens
The root cause is the lack of strict validation and filtering of MkDocs configuration data originating from repository-controlled mkdocs.yml files.
In affected versions, the TechDocs Node plugin treated the configuration file as trusted and forwarded all keys, including hooks, to MkDocs. MkDocs hooks are effectively executable code entry points, enabling arbitrary Python statements to run when they are loaded and invoked.
This maps to CWE-94: Improper Control of Generation of Code ('Code Injection'), because data from a non-trusted configuration file influences what code executes on the server (through hooks), without appropriate restriction or allowlisting of safe configuration keys.
Potential impact
- Execution of arbitrary Python code on the TechDocs build server.
- Access to environment variables, credentials, or tokens available to the TechDocs process.
- Lateral movement from the documentation build environment to other internal services, depending on network and credential exposure.
- Tampering with generated documentation artifacts, including inserting malicious content or misleading technical information.
- Use of the TechDocs infrastructure as a foothold for further attacks (e.g., establishing persistence, exfiltrating data, or staging supply-chain compromises).
General mitigation guidance
Mitigation generally focuses on treating documentation configuration as untrusted input and constraining what the build pipeline is allowed to execute.
Recommended defensive patterns include:
- Configuration allowlisting: Only pass a known-safe subset of
mkdocs.ymlkeys into the build toolchain; strip or reject unsupported or high-risk fields such ashooksbefore execution. - Execution isolation: Prefer running documentation builds in strongly isolated environments (e.g., containers or sandboxed workers with limited privileges, restricted file system access, and tightly scoped network policies).
- Principle of least privilege: Ensure the TechDocs build process runs under a minimally privileged account with no unnecessary access to secrets, internal services, or host resources.
- Repository governance: Treat
mkdocs.ymlas security-sensitive; apply strict access controls and review processes for changes to documentation configuration. - Secure defaults: Configure the documentation system so that risky features are disabled by default, requiring explicit opt-in under controlled conditions.
How teams detect issues like this
Effective detection strategies focus on both code-level patterns and repository-level configuration scanning.
Potential approaches:
- Static analysis / configuration linting: Scan
mkdocs.ymlfiles for disallowed or risky keys (such ashooks) and flag them during CI before TechDocs processes the repository. - Code review checks: In Backstage and TechDocs-related code, look for paths where external configuration is forwarded to build tools without validation; specifically, watch for direct use of full configuration objects passed into MkDocs without filtering.
- Policy enforcement: Use repository management or CI policies to require review and approval for modifications to
mkdocs.ymland other build-related configuration files. - Runtime monitoring: Log TechDocs build invocations and anomalous build behavior (e.g., unexpected network calls or filesystem access during documentation generation) and feed logs into centralized monitoring for alerting.

