shellwords: Parse strings into words, like a shell would

[ library, mit, text ] [ Propose Tags ] [ Report a vulnerability ]

Modules

[Last Documentation]

  • ShellWords
    • ShellWords.Parse
    • ShellWords.Quote
  • Text
    • Megaparsec
      • Text.Megaparsec.Compat

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.1.0, 0.1.2.0, 0.1.2.1, 0.1.2.2, 0.1.3.0, 0.1.3.1, 0.1.3.2, 0.1.4.0
Change log CHANGELOG.md
Dependencies base (>=4.18.2.1 && <5), megaparsec (>=9.5.0), text (>=2.0.2) [details]
License MIT
Copyright 2018 Patrick Brisbin
Author Patrick Brisbin
Maintainer pbrisbin@gmail.com
Category Text
Home page https://github.com/pbrisbin/hs-shellwords#readme
Bug tracker https://github.com/pbrisbin/hs-shellwords/issues
Source repo head: git clone https://github.com/pbrisbin/hs-shellwords
Uploaded by PatrickBrisbin at 2024-12-14T14:54:03Z
Distributions LTSHaskell:0.1.4.0, NixOS:0.1.3.1, Stackage:0.1.4.0
Reverse Dependencies 2 direct, 7 indirect [details]
Downloads 3650 total (94 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2024-12-14 [all 2 reports]

Readme for shellwords-0.1.4.0

[back to package description]

ShellWords

Hackage Stackage Nightly Stackage LTS CI

Parse a string into words, like a shell would.

Motivation

If you want to execute a specific command with input given to you from an untrusted source, you should not give that text as-is to a shell:

let userInput = "push origin main"

callCommand $ "git " <> userInput
-- Forward output of the push command...

You may be tempted to do this because you want to correctly handle quoting and other notoriously-difficult word-splitting problems. But doing so is a severe security vulnerability:

let userInput = "push origin main; cat /etc/passwd"

callCommand $ "git " <> userInput
-- Forward output of the push command...
-- And then dump /etc/passwd. Oops.

Furthermore, any attempts to sanitize the string are unlikely to be 100% affective and should be avoided. The only safe way to do this is to not use a shell intermediary, and always exec a process directly:

let userInput = "push origin main"

callProcess "git" $ words userInput
-- Forward output of the push command...

Now, there's no vulnerability:

let userInput = "push origin main; cat /etc/passwd"

callProcess "git" $ words userInput
-- Invalid usage. :)

The new problem (but not a security-related one!) is how to correctly parse a string like "push origin main" into command arguments. The rules are complex enough that you probably want to get a library to do it.

So here we are.

Example

Right args <- parse "some -complex --command=\"Line And\" 'More'"

callProcess cmd args
--
-- Is equivalent to:
--
-- > callProcess cmd ["some", "-complex", "--command=Line And", "More"]
--

Unsafe Usage

The following is a perfectly reasonable thing one might do with this library:

Right (cmd:args) <- parse userInput

callProcess cmd args

However, if:

  1. userInput is un-trusted, and
  2. You do no further validation of what cmd can be,

Then this re-introduces the original security vulnerability and, at that point, you might as well just pass userInput to a shell.

Lineage

This package is inspired by and named after


CHANGELOG | LICENSE