shell-safe-validator/README.md

Shell Safe Validator

A CLI tool that validates shell scripts and commands for safety issues before execution. It detects dangerous patterns like rm -rf with variables, unquoted variables, potential injection vulnerabilities, and missing error handling, suggesting safer alternatives with explanations.

Features

• Pattern-based dangerous command detection: Identifies risky commands like rm -rf with variables, sudo without full path, cp without -i
• Security vulnerability scanning: Detects command injection, path traversal, and shell metacharacter injection
• Best practices validation: Checks for set -e, set -u, proper error handling, and quoted variables
• Interactive safe-mode execution: Execute validated commands safely with confirmation prompts
• Configurable rule customization: Load custom rules from YAML/JSON config files

Installation

From Source

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
cd shell-safe-validator
pip install -e .

From PyPI (coming soon)

pip install shell-safe-validator

Usage

Validate a Shell Script

shell-safe-validator validate script.sh

Check a Single Command

shell-safe-validator check "rm -rf $VAR"

Execute Safely with Confirmation

shell-safe-validator safe-exec "rm -rf /tmp/old_files"

Use Custom Configuration

shell-safe-validator validate script.sh --config custom_rules.yaml

Commands

validate

Validate a shell script file for safety issues.

shell-safe-validator validate [OPTIONS] FILE

Options:

• --config: Path to custom rules YAML file
• --severity: Minimum severity level to report (low, medium, high, critical)
• --output-format: Output format (text, json, compact)

check

Check a single shell command for safety issues.

shell-safe-validator check [OPTIONS] COMMAND

Options:

• --severity: Minimum severity level to report
• --output-format: Output format (text, json, compact)

safe-exec

Execute a command safely with validation and confirmation.

shell-safe-validator safe-exec [OPTIONS] COMMAND

Options:

• --dry-run: Show what would be executed without running
• --force: Skip confirmation prompt

Configuration

Default Rules

The tool comes with comprehensive default rules stored in config/default_rules.yaml. These rules cover:

• Critical: Dangerous deletion commands, eval with variables, unrestricted sudo
• High: Unquoted variables, command injection patterns, path traversal
• Medium: Missing safety flags, improper error handling
• Low: Style suggestions and best practices

Custom Rules

You can create custom rule files in YAML format:

rules:
  - id: CUSTOM001
    name: Custom Rule Name
    pattern: rm -rf \$\w+
    severity: critical
    message: Custom message
    suggestion: Use a safer alternative

Configuration File Precedence

1. .shell-safe-validator.yaml (project-level)
2. ~/.config/shell-safe-validator/rules.yaml (user-level)
3. config/default_rules.yaml (built-in defaults)

Examples

Basic Validation

$ shell-safe-validator check "rm -rf $DIR"
[CRITICAL] Dangerous deletion with variable
  Command: rm -rf $DIR
  Suggestion: Avoid using variables with rm -rf. Use absolute paths or verify the variable content first.

Script Validation

$ shell-safe-validator validate deploy.sh
Validating deploy.sh...

[HIGH] ? Line 15:
  Command: cp $SRC_DIR/* $DEST_DIR/
  Matched: $SRC_DIR
  Unquoted variable can cause word splitting and glob expansion
  Suggestion: Always quote variables: "$VAR" instead of $VAR

[MEDIUM] ? Line 23:
  Command: npm install
  Matched: npm install
  Command without error handling
  Suggestion: Add error handling with '|| exit 1' or '&&' operator

Validation complete: 2 issue(s) found (0 critical, 1 high, 1 medium, 0 low)

Safe Execution

$ shell-safe-validator safe-exec "mkdir -p /tmp/test"
Warning: Command has 1 issue(s)
  [LOW] Script missing shebang line
Execute: mkdir -p /tmp/test
⚠️  This command will create a directory. Proceed? [y/N]: y
Command executed successfully

Development

Setup

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
cd shell-safe-validator
pip install -e ".[dev]"

Running Tests

pytest tests/ -v
pytest tests/ --cov=src

Project Structure

shell-safe-validator/
├── src/
│   ├── __init__.py           # Package root
│   ├── cli.py                # CLI entry point
│   ├── models/               # Data models
│   │   ├── __init__.py
│   │   ├── finding.py        # Finding model
│   │   ├── rule.py           # Rule model
│   │   └── severity.py       # Severity enum
│   ├── validators/           # Validation modules
│   │   ├── __init__.py
│   │   ├── patterns.py       # Pattern-based detection
│   │   ├── security.py       # Security vulnerability scanning
│   │   └── best_practices.py # Best practices validation
│   ├── config/               # Configuration loading
│   │   ├── __init__.py
│   │   └── loader.py         # Config loader
│   └── utils/                # Utility functions
│       ├── __init__.py
│       └── shell_parser.py   # Shell parsing utilities
├── tests/
│   ├── __init__.py
│   ├── test_cli.py
│   ├── test_config.py
│   ├── test_utils.py
│   └── test_validators/
│       ├── __init__.py
│       ├── test_patterns.py
│       ├── test_security.py
│       └── test_best_practices.py
├── config/
│   └── default_rules.yaml
├── pyproject.toml
├── LICENSE
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by shellcheck and similar static analysis tools
• Built with Click for CLI and PyYAML for configuration