Metadata-Version: 2.4
Name: gbkomi-filter
Version: 1.0.0
Summary: A high-performance input sanitization library with multi-layer threat detection
Author-email: gbkomi <qqqwwweeeshah@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: isort>=5.10; extra == "dev"
Dynamic: license-file

```markdown
# 🔒 gbkomi-filter

A lightweight yet powerful Python library for **sanitizing, validating, and blocking malicious inputs** in your applications.

---

## ✨ Features

- 🛡️ Protects against **SQL Injection, Command Injection, XSS, Prompt Injection, and Path Traversal**
- 🧹 Automatic Unicode normalization and control character removal
- 🕵️ Detects obfuscated payloads (Base64, Hex encoding, high-entropy strings)
- ⚙️ Three operation modes: `block` (default), `log` (record only), `transparent` (sanitize and pass)
- 📋 Built-in threat logging for post-mortem analysis
- 🚀 Zero external dependencies (pure Python)
- ✅ Type validation (email, URL, integer)

---

## 📦 Installation

### From PyPI (coming soon)
```bash
pip install gbkomi-filter
```

### From source (development)
```bash
git clone https://github.com/yourusername/gbkomi-filter.git
cd gbkomi-filter
pip install -e .
```

---

## 🚀 Quick Start

```python
from gbkomi_filter import FilterEngine, SecurityException

# Initialize the engine
engine = FilterEngine(mode='block')  # 'block' | 'log' | 'transparent'

# Example 1: Safe input
try:
    result = engine.filter("Hello World")
    print(f"✅ Allowed: {result}")
except SecurityException as e:
    print(f"❌ Blocked: {e}")

# Example 2: Malicious input (SQL Injection)
try:
    result = engine.filter("' ; DROP TABLE users; --")
    print(f"✅ Allowed: {result}")
except SecurityException as e:
    print(f"❌ Blocked: {e}")
    # Output: Blocked: Threat detected: sql

# Example 3: Type validation (email)
try:
    result = engine.filter("user@example.com", expected_type='email')
    print(f"✅ Valid email: {result}")
except SecurityException as e:
    print(f"❌ Invalid: {e}")

# Example 4: Log mode (monitor without blocking)
log_engine = FilterEngine(mode='log')
result = log_engine.filter("'; DROP TABLE users; --")
print(f"Result: {result}")  # Passes through
print(f"Logs: {log_engine.get_logs()}")
```

---

## ⚙️ Configuration

### `FilterEngine(mode, allowlist)`

| Parameter   | Type           | Default | Description |
|-------------|----------------|---------|-------------|
| `mode`      | `str`          | `'block'` | Operation mode: `'block'`, `'log'`, or `'transparent'` |
| `allowlist` | `list`         | `[]`    | List of exact-match inputs that bypass all filters |

### `engine.filter(input, expected_type, schema)`

| Parameter       | Type    | Default | Description |
|-----------------|---------|---------|-------------|
| `user_input`    | `Any`   | Required | The input to validate (auto-converted to string) |
| `expected_type` | `str`   | `None`  | Enforce type: `'int'`, `'email'`, `'url'`, or `'string'` |
| `schema`        | `dict`  | `None`  | JSON schema validation for structured data |

---

## 🧪 Running Tests

```bash
# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Run with coverage
pytest --cov=gbkomi_filter tests/
```

---

## 📂 Project Structure

```
gbkomi-filter/
├── src/gbkomi_filter/
│   ├── __init__.py    # Public API
│   ├── guard.py       # FilterEngine core logic
│   ├── rules.py       # All threat patterns (SQL, XSS, etc.)
│   └── utils.py       # Normalization, encoding detection, validation
├── tests/             # Unit tests
├── examples/          # Usage examples
├── README.md          # This file
├── LICENSE            # MIT License
└── pyproject.toml     # Build configuration
```

---

## 🛡️ Threat Detection Coverage

| Attack Type          | Detection Pattern Examples |
|----------------------|----------------------------|
| **SQL Injection**    | `' OR '1'='1`, `DROP TABLE`, `UNION SELECT` |
| **Command Injection**| `;`, `|`, `&&`, `rm`, `wget`, `curl` |
| **XSS**              | `<script>`, `onerror=`, `javascript:` |
| **Code Injection**   | `__import__`, `eval`, `exec`, `os.system` |
| **Path Traversal**   | `../`, `/etc/passwd`, `C:\Windows\` |
| **Prompt Injection** | `ignore previous instructions`, `act as` |

---

## 📄 License

This project is licensed under the **MIT License** – see the [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

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

**Made with ❤️ for the security community.**
```
