shellfirm Documentation

Shellfirm implements Git-strict checks to prevent potentially destructive or irreversible Git operations from executing without explicit user confirmation. When these checks are active, the following commands are flagged and will prompt for confirmation before proceeding:

• History Rewriting: git rebase (rewrites commit history by moving commits to a new base).
• Stash Management: git stash pop or git stash drop (applies or removes stashed changes).
• Submodule Operations: git submodule update or git submodule deinit (updates or deinitializes submodules).
• Annotated Tagging: git tag -a {TAG} (creates an annotated tag).

Note that non-destructive commands like git add . and git commit --all/* are not subject to these strict checks.

shellfirm includes specialized checks to detect high-risk Terraform commands that bypass confirmation prompts or manipulate state in potentially destructive ways. These checks monitor for commands that could lead to accidental resource destruction or state corruption if executed without manual oversight.

Detected high-risk patterns include:

• Auto-approving a Terraform plan (-auto-approve).
• Replacing or moving providers in the state without confirmation.
• Force-deleting a Terraform workspace.
• Deleting a workspace while bypassing the state lock.
• Force-unlocking a state file.

Shellfirm includes a set of 'Base Checks' designed to identify and prevent the execution of highly destructive or system-altering shell commands. These checks act as a safety layer against common patterns that can lead to resource exhaustion, accidental data loss, or unexpected system state changes.

Key patterns covered by Base Checks include:

• Fork Bombs: Detecting recursive function definitions that replicate processes to exhaust CPU and memory (e.g., :(){ :|: & };:).
• History Execution: Detecting attempts to pipe the entire command history directly into a shell (e.g., history | bash).
• Task Removal: Detecting commands that wipe scheduled tasks (e.g., crontab -r).
• System Power Commands: Detecting commands that trigger reboots or shutdowns (e.g., reboot, shutdown).

To add a new group of patterns, create a new YAML file in the shellfirm/checks directory. The filename of the YAML file will serve as the group_name. Each file contains a list of patterns using the following schema:

• from: Must match the name of the group YAML file.
• test: The Regex pattern used for matching.
• description: A human-readable description of the pattern.
• id: A unique identifier following the format {group_name}:{pattern_id}.

- from: "group_name"
  test: "regex_pattern"
  description: "description of pattern"
  id: "group_name:pattern_id"

To enable automatic interception of risky commands in your terminal, follow these steps:

1. Run the initialization command, which auto-detects your current shell:

   shellfirm init

2. Restart your shell or source your shell's configuration file (e.g., .zshrc, .bashrc) to apply the changes.

Once installed, shellfirm will intercept commands matching its risk patterns and prompt you to solve a challenge before execution.

Every new pattern requires a corresponding unit test to validate its Regex.

1. Navigate to the shellfirm/tests/checks/ directory.
2. Create a new test file named after the pattern's id. Important: Replace the : character in the ID with a - character for the filename.
3. The test file must contain a list of test cases in the following format:

• test: The command or string to be tested.
• description: A description of what the test case is checking.

- test: crontab -r
  description: match command

After adding patterns and their corresponding test files, use the following commands to verify them:

• Validate Snapshots: Use cargo insta test --review to validate the regex matches and approve any snapshot changes.
• Integration Testing: To test how a specific command integrates with the shellfirm binary, use the pre-command runner: cargo run pre-command --command "COMMAND"

# Validate and approve snapshots
cargo insta test --review

# Check integration for a specific command
cargo run pre-command --command "COMMAND"

To build your own Docker image from the local source and immediately start an interactive zsh session, use the docker build and docker run commands.

docker build -t shellfirm . && docker run -it shellfirm zsh

You can set up both automatic safety hooks and on-demand analysis for Claude Code with a single command. This enables Claude to use shellfirm's Model Context Protocol (MCP) tools to explain risks and suggest safer alternatives while also ensuring that any Bash commands Claude attempts to run are checked against shellfirm's safety rules.

shellfirm connect claude-code