245 lines
6.6 KiB
Markdown
245 lines
6.6 KiB
Markdown
# Shell Safe Validator
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.python.org/downloads/)
|
|
[](https://pypi.org/project/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
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
|
|
cd shell-safe-validator
|
|
pip install -e .
|
|
```
|
|
|
|
### From PyPI (coming soon)
|
|
|
|
```bash
|
|
pip install shell-safe-validator
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Validate a Shell Script
|
|
|
|
```bash
|
|
shell-safe-validator validate script.sh
|
|
```
|
|
|
|
### Check a Single Command
|
|
|
|
```bash
|
|
shell-safe-validator check "rm -rf $VAR"
|
|
```
|
|
|
|
### Execute Safely with Confirmation
|
|
|
|
```bash
|
|
shell-safe-validator safe-exec "rm -rf /tmp/old_files"
|
|
```
|
|
|
|
### Use Custom Configuration
|
|
|
|
```bash
|
|
shell-safe-validator validate script.sh --config custom_rules.yaml
|
|
```
|
|
|
|
## Commands
|
|
|
|
### validate
|
|
|
|
Validate a shell script file for safety issues.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
$ 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
|
|
|
|
```bash
|
|
$ 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
|
|
|
|
```bash
|
|
$ 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
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/shell-safe-validator.git
|
|
cd shell-safe-validator
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
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](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- Inspired by shellcheck and similar static analysis tools
|
|
- Built with Click for CLI and PyYAML for configuration
|