gbkomi-filter 1.0.0

# 🔒 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)

git clone https://github.com/yourusername/gbkomi-filter.git
cd gbkomi-filter
pip install -e .

🚀 Quick Start

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)

engine.filter(input, expected_type, schema)

🧪 Running Tests

# 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

📄 License

This project is licensed under the MIT License – see the 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.