# Shell Safe Validator

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-red)](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