Security

Privacy

cli-expander is 100% local and private:

• ✅ All processing happens on your machine
• ✅ No telemetry, analytics, or usage tracking
• ✅ No network requests during normal operation
• ✅ No cloud dependency
• ✅ No account or registration required

Shell Command Safety

The shell variable type executes commands with your user privileges. This is powerful but requires caution:

❌ Dangerous Patterns

# Never do this — exposes your system to any input
- trigger: ":run"
  replace: "{{result}}"
  vars:
    - name: result
      type: shell
      params:
        cmd: "{{form.command}}"  # User-controlled command!

✅ Safe Patterns

# Safe — commands are hardcoded
- trigger: ":disk"
  replace: "{{disk}}"
  vars:
    - name: disk
      type: shell
      params:
        cmd: "df -h / | tail -1"

Guidelines:

• Never pass user-provided form input directly to shell commands
• Hardcode commands in match files whenever possible
• Review community match files before adding them to your config
• Avoid matches that run destructive commands (rm, dd, mkfs)

File Permissions

Match Files

Match files are plain YAML and contain your triggers and templates. They do not contain secrets unless you put them there.

# Restrict access to your config
chmod 700 ~/.config/cli-expander/
chmod 600 ~/.config/cli-expander/matches/*.yml

System-wide Mode

System-wide mode requires special permissions:

Permission	Purpose	Risk
input group	Read keyboard events	Can log keystrokes (yours)
uinput group	Inject keystrokes	Can type as you
cap_dac_override	Override file permissions	Powerful, use with care

Only grant these to the ce binary, not to untrusted executables.

Running as Root

Do not run ce or cli-expander as root or with sudo. Running as root reduces security boundaries and is unnecessary.

# ❌ Bad
sudo ce ":hello"

# ✅ Correct
ce ":hello"

Untrusted Match Files

Only load match files from sources you trust. A malicious match file could:

• Execute arbitrary shell commands (via shell variable)
• Read files and exfiltrate content (via shell variable)
• Modify system state

Before adding community match files:

1. Read the file and understand every match
2. Check for type: shell entries with cmd: that you don't recognize
3. Verify the source is reputable (official repo, trusted contributor)

Injection Methods

Method	Scope	Security Note
stdout	Terminal output only	Safe — no system interaction
clipboard	Display server	Can access other apps' clipboard content
tmux	Tmux sessions	Limited to your tmux panes
uinput	System-wide	Requires group membership, can type anywhere

Updates and Supply Chain

cli-expander is built from source. Verify the source integrity:

# Clone from the official repository
git clone https://github.com/donnyaw/cli-expander

# Verify the commit signature if available
git verify-commit HEAD

Reporting Security Issues

If you find a security vulnerability:

1. Do not open a public GitHub issue
2. Email the maintainer directly or open a private security advisory on GitHub
3. Include steps to reproduce and potential impact