| name | security-audit |
| description | Use this skill when auditing shell escaping logic, testing against command injection attack vectors, or verifying POSIX shell safety guarantees. |
Security Audit Procedures for shellescape
This skill guides security audits, invariant checks, and edge-case testing for shell injection vulnerabilities in shellescape.
1. Security Invariants Checklist
Verify that every one of the following dangerous characters forces single-quote wrapping:
- Shell metacharacters:
;, &, |, &&, ||, ( , ), {, }
- Redirection symbols:
<, >, >>, >&, <<
- Expansions:
$, ${...}, $(...), `...`
- Wildcards:
*, ?, [, ]
- Whitespace: Spaces, tabs
\t, newlines \n, carriage returns \r, form feeds \f
- Quotes:
' (escaped as '"'"'), "
- Escape sequences:
\
2. Adversarial Test Cases
When auditing or adding tests, include these test cases in shellescape_test.go:
| Payload Category | Example Input | Expected Output | Rationale |
|---|
| Command Injection | test; rm -rf / | 'test; rm -rf /' | Semicolon must be inside single quotes |
| Subshell Execution | $(cat /etc/passwd) | '$(cat /etc/passwd)' | Subshell syntax must not expand |
| Backticks | `whoami` | ''whoami' | Backticks must not execute |
| Single Quote Breakout | '; id; ' | ''"'"'; id; '"'"'' | Quote must not allow closing string context |
| Environment Variable | $PATH | '$PATH' | Must not expand environment variable |
| Newline Injection | foo\nbar | 'foo\nbar' | Multiline arguments must be safely enclosed |
| Empty String | "" | '' | Prevents argument vanishing in shell argv |
3. Verifying Escaping with Shell Lexers
Use github.com/google/shlex or subshell execution to confirm that the parsed command produces exactly one argument token with the unescaped content.
Example verification snippet in Go:
package main
import (
"fmt"
"github.com/google/shlex"
"al.essio.dev/pkg/shellescape"
)
func verifyPayload(input string) bool {
escaped := shellescape.Quote(input)
cmd := "echo " + escaped
tokens, err := shlex.Split(cmd)
if err != nil || len(tokens) != 2 {
return false
}
return tokens[1] == input
}
4. Unicode & Control Character Audit
Verify that StripUnsafe and StripSpaces function properly:
StripUnsafe removes non-printable runes (\u0000, \u001f, \u0081) while preserving all printable ASCII and Unicode.StripSpaces removes all whitespace according to unicode.IsSpace.
