It has been decided to publicly disclose specific details of how an application that setsGit.USE_SHELL toTrue can become vulnerable, because this information is already widely known by security researchers yet may not always be obvious to application developers.

TheGit.USE_SHELL class attribute has the default value ofFalse. Setting it toTrue makes applications vulnerable toOS command injection, if untrusted text ever makes its way into any part of any argument that GitPython passes to any git command.

• This is hard to prevent except by refraining from settingUSE_SHELL toTrue, and it applies even to text used as paths passed to a command after--, and in other cases where it may be unintuitive.
• It happens both when running git commands explicitly through dynamic attributes of aGit object, and implicitly through functionality provided byRepo and other classes.

For this reason, settingUSE_SHELL toTrue should be avoided. Although theUSE_SHELL attribute is retained for backward compatibility because removing it would be a breaking change, it has been deprecated. Its docstring has been updated to warn about this, though specific details of the risks are not given there, and are instead presented below.

It is likewise unsafe to passshell=True to any GitPython function that accepts it, but in the case ofUSE_SHELL, the effect is much broader, affecting all function calls whereshell could have been passed but was not.

AlthoughGit.USE_SHELL is available on all platforms, it is in practice unlikely to be set toTrue except on Windows. Setting it toTrue had at one time been recommended to work around a Windows-related bug that wasfixed properly in GitPython 2.0.8. Furthermore, most GitPython functionality visibly breaks if it is set toTrue on other systems, as it is only on Windows thatsubprocess.Popen accepts a sequence of separate arguments (rather than a single string) as a command even whenshell=True.

Therefore, examples of how it can be exploited are presented here only for the Windowscmd.exe shell. These examples are not exhaustive. WhenUSE_SHELL is set toTrue...

• This creates or truncatesoutfile, which can be any path that the user running the application has write access to:

  g=Git()g.diff("HEAD>outfile")

  Other redirection operators, including< to read files and>> to append to them, can also be used.

• This runs the Windows calculator program (a useful choice because it is easy to observe), and can be trivially modified to run any command that can be expressed without spaces:

  g=Git()g.diff("HEAD&&calc")

  That spaces may induce quoting in thePopen call that, while not intended to suppress special shell syntax, sometimes does so, is not a significant mitigation. Even if that cannot be overcome, redirection can be used to pass quoted commands to a scripting runtime, or parts of a command can be passed through as (all or part of) multiple arguments.

• This likewise runs the Windows calculator program or, when modified, any program:

  r=Repo()r.iter_commits("||calc")

  Either the&& and|| operators can be used on dynamicGit attributes, calls toRepo methods, and elsewhere, and can be combined with arbitrary redirection.

• The^ character is acmd.exe escape character, as well as being syntactically significant in Git commands. This is likely to cause problemsby accident, and may also aid in exploitation. An example of an accidental malfunction due to it is:

  g=Git()g.diff("HEAD^","HEAD")

  This returns an empty string, even outside the rare case that theHEAD commit makes no changes. Its effect is the same asg.diff("HEAD", "HEAD").

As mentioned above, these examples not exhaustive, and there are other forms of shell syntax that can be injected.

These examples, and the risk they represent,apply only when GitPython is made to run commands through a shell, whichUSE_SHELL does. In the absence of aTrue value forUSE_SHELL or the optionalshell argument to functions that accept it, this risk of OS command injection is absent.