Should we officially "deprecate" Invoke-Expression?

[sdwheeler]

Summary of the new feature/enhancement

Opening issue to get feedback per our shiproom conversation.

We have publicly stated that Invoke-Expression should be avoided. There are too many inherent security risks built into it. We continue to get questions in the Docs repo about how and why it should be used, and asks for useful examples.

We have the ability, in code, to set an attribute on the cmdlet that marks it as deprecated. Should this change be made? Are there compelling cases for the use of this cmdlet?

[mklement0]

In the linked issue @sdwheeler states:

Invoke-Expression is maintained for historical purposes but is effectively deprecated

From @rjmholt's response ibidem:

My personal feeling (worth also talking to @SteveL-MSFT, @joeyaiello, @JamesWTruher and @BrucePay) is that it’s not so much historical as an important part of an interpreted language. It’s dangerous, and shouldn’t be used in production, but all scripting languages have an eval() equivalent.

Also of interest: his comment with specific invocation scenarios, MicrosoftDocs/PowerShell-Docs#4897 (comment), where he concludes:

I think the uses are quite obscure and Invoke-Expression needs no encouragement. We should just warn against it..

[lukeb1961]

As someone who does use Invoke-Expression for good reason, in a small number of scripts, I'm damned if I can see why you want to take away this functionality. It exists in Powershell and exists in some form in every other scripting language. There are plenty of compatibility and performance issues with PS core that need to be addressed before you start breaking my existing scripts.

[doctordns]

I feel deprecating like this is not all that helpful. There are, as @lukeb1961 and others point out, useful reasons for using IEX. Not many, but some are certainly 'valid'.

I feel that to document the issue and warn against it is probably enough.

[danijeljw]

I do not see the use in removing this, when I use it in so many scripts, and have been taught how to use this effectively in so many scripts for API calls too. Please don't remove it.

[sdwheeler]

To be clear, we are not talking about removing Invoke-Expression. We are talking about marking it as "deprecated" and more emphatically warning against its use.

If you have compelling use cases, please share them so we can see WHY it is needed.

[rjmholt]

I'm damned if I can see why you want to take away this functionality

Nobody is talking about removing Invoke-Expression. It’s an important primitive in PowerShell (as in any scripting language).

Here and in a few other places there has been some confusion about the meaning of the term deprecate. It simply means to express disapproval of, to disrecommend. Obsolescence is one reason to do so, but another is unnecessary danger. Invoke-Expression lies in the second category; it’s not going anywhere but it’s dangerous to use non-interactively, both from a security standpoint and an efficiency one (the whole parser/compiler toolchain has to be run again at execution time).

What we mean, on a technical level, by deprecation in this case is still not clear to me (just in documentation, or with code attributes as well?), but you’ll always be able to use Invoke-Expression (even though you shouldn’t).

As someone who does use Invoke-Expression for good reason, in a small number of scripts

Would you be able to share those scenarios/usages or adaptations of them? I think @sdwheeler in particular is looking for examples of iex usage.

[sdwheeler]

@rjmholt Thanks. Well said. The purpose of this issue was to discuss whether we should add the "deprecated" attribute to the code to enhance the warning about use of the cmdlet. This is separate from the question of how should this be documented.

I am also looking for good example for how and why you are using IEX instead of the the &-operator. If someone can provide a useful example then we can add that to the documentation. Otherwise, I will just update the documentation with a more direct recommendation for not using the cmdlet.

[SeeminglyScience]

Here and in a few other places there has been some confusion about the meaning of the term deprecate. It simply means to express disapproval of, to disrecommend.

Yeah literally every time the term is used. Y'all may want to adopt a template for using the term in a public space, something like:

IMPORTANT NOTE: This is not about removing ___. (Link to doc on what deprecation means)

The actual post content.

Actually I don't know if anyone would read that. Maybe a different term with less connotation needs to be used instead.

@rjmholt Thanks. Well said. The purpose of this issue was to discuss whether we should add the "deprecated" attribute to the code to enhance the warning about use of the cmdlet. This is separate from the question of how should this be documented.

Do you mean ObsoleteAttribute? If so, the runtime warnings would get really annoying. A PSSA rule is where this would need to live imo.

[mklement0]

whether we should add the "deprecated" attribute to the code to enhance the warning about use of the cmdlet. This is separate from the question of how should this be documented.

Thanks for that clarification, @sdwheeler; the distinction wasn't obvious to me, and it seems that these aspects have already been conflated here, which is just as well, because I think discussing them in tandem makes sense.

---

As for the attribute: I agree with @SeeminglyScience that a PSSA rule is the right place to warn programmatically, if desired; certainly not at runtime, as that amounts to a quasi-breaking change.

---

As for documentation and use cases:

In the Invoke-Expression help topic, I think a general warning is sufficient, as @rjmholt proposes, along the following lines (adapted from the original MicrosoftDocs/PowerShell-Docs#2679 issue):

---

As a matter of habit, avoid use of Invoke-Expression, because there are usually more secure and robust alternatives.

If you do find that Invoke-Expression is your only choice, carefully consider the security implications: if a string from an (untrusted) outside source (e.g., user input) is passed directly to Invoke-Expression, arbitrary commands may be executed.

---

I think that is sufficient for this particular help topic, but separately, perhaps in a new about_Invoke-Expression conceptual help topic, we could focus on when not to use Invoke-Expression.

Specifically, we could take widespread current and historical (mis)uses of Invoke-Expression and show superior, safer alternatives.

If we do end up agreeing on legitimate public uses worth advertising (other than during PowerShell tests, as described by @rjmholt in MicrosoftDocs/PowerShell-Docs#4897 (comment)), we can add them there as well.

Even in the perhaps most seductive use case - direct execution of script text downloaded from the web (e.g, iwr https://aka.ms/install-powershell.ps1 | iex) - Invoke-Expression is ultimately ill-advised, and enhancing Invoke-Command to operate on Invoke-WebRequest output should be favored - see #5909 (comment)

[rjmholt]

In fact PSSA has had a rule to disrecommend Invoke-Expression for a few years now

[rjmholt]

certainly not at runtime, as that amounts to a quasi-breaking change

While I agree that adding an ObsoleteAttribute would be annoying and probably not what we want here, I strongly disagree that it would be a breaking change.

If adding ObsoleteAttribute to anything is a breaking change, then that attribute is pointless. The whole idea of attributes is that they behave as additive metadata.

Anyway, that’s a tangent.