Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pbrisbin/hs-shellwords
Parse a string into words, like a shell would
https://github.com/pbrisbin/hs-shellwords
Last synced: 2 months ago
JSON representation
Parse a string into words, like a shell would
- Host: GitHub
- URL: https://github.com/pbrisbin/hs-shellwords
- Owner: pbrisbin
- License: mit
- Created: 2018-04-13T15:12:30.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2022-12-15T20:42:09.000Z (about 2 years ago)
- Last Synced: 2024-04-24T15:19:10.338Z (8 months ago)
- Language: Haskell
- Homepage:
- Size: 75.2 KB
- Stars: 4
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ShellWords
[](https://hackage.haskell.org/package/shellwords)
[](http://stackage.org/nightly/package/shellwords)
[](http://stackage.org/lts/package/shellwords)
[](https://github.com/pbrisbin/hs-shellwords/actions/workflows/ci.yml)
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:
```hs
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:
```hs
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:
```hs
let userInput = "push origin main"
callProcess "git" $ words userInput
-- Forward output of the push command...
```
Now, there's no vulnerability:
```hs
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
```hs
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:
```hs
Right (cmd:args) <- parse userInput
callProcess cmd args
```
However, if:
1. `userInput` is un-trusted, and
1. 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
- [`python-shellwords`][python-shellwords], which was itself inspired by
- [`go-shellwords`][go-shellwords], which was itself inspired by
- [`Parser::CommandLine`][parser-commandline]
[python-shellwords]: https://github.com/mozillazg/python-shellwords
[go-shellwords]: https://github.com/mattn/go-shellwords
[parser-commandline]: https://github.com/Songmu/p5-Parse-CommandLine
---
[CHANGELOG](./CHANGELOG.md) | [LICENSE](./LICENSE)