Metadata-Version: 2.4
Name: safe-flask
Version: 1.0.2
Summary: A plug-and-play firewall library for Flask applications.
Author-email: CodeGuardianSOF <securex39@gmail.com>
License: MIT License
        
        Copyright (c) 2025 CodeGuardianSOF
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/CodeGuardianSOF/FlaskGuard
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Flask
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask>=1.1.2
Dynamic: license-file

# FlaskGuard 🚀

FlaskGuard is a plug-and-play firewall library for Flask applications. It protects your application from common web vulnerabilities such as SQL injection, XSS, path traversal, and more.

## Features ✨

- 🔒 Detects and blocks malicious requests.
- ⚙️ Configurable rules and whitelist.
- 🛠️ Easy integration with Flask applications.
- 📜 Logging for blocked requests with color-coded output.
- 🧠 Advanced detection for SQL injection, XSS, path traversal, command injection, and more.

## Installation 🛠️

### From PyPI

Install FlaskGuard directly from PyPI:

```bash
pip install safe-flask
```

### From GitHub

Install FlaskGuard from the GitHub repository:

```bash
pip install git+https://github.com/username/FlaskGuard.git
```

### From Source

Clone the repository and install FlaskGuard locally:

```bash
git clone https://github.com/username/FlaskGuard.git
cd FlaskGuard
pip install .
```

## Usage 🚀

### Basic Integration

```python
from flask import Flask
from flask_guard import init_app

app = Flask(__name__)
init_app(app)

@app.route("/")
def home():
    return "Welcome to FlaskGuard-protected app!"

if __name__ == "__main__":
    app.run()
```

### Custom Rules and Whitelist

```python
from flask_guard.rules import load_user_config

custom_rules = {
    "custom_rule": {
        "enabled": True,
        "pattern": r"custom_pattern",
        "target": "query_string",
    }
}

custom_whitelist = {
    "query_string": [r"safe_custom_param=value"],
}

load_user_config(user_rules=custom_rules, user_whitelist=custom_whitelist)
```

## Rules 🛡️

FlaskGuard includes the following built-in rules:

1. **SQL Injection**: Detects SQL injection patterns such as `' OR 1=1`, `UNION SELECT`, `SLEEP()`, and more.
2. **XSS Attack**: Detects Cross-Site Scripting (XSS) patterns in `<script>` tags, event handlers, and encoded payloads.
3. **Suspicious User-Agent**: Blocks requests from tools commonly used in attacks, such as `sqlmap`, `curl`, `wget`, and more.
4. **Path Traversal**: Detects attempts to access sensitive files using patterns like `../../etc/passwd`.
5. **Remote and Local File Inclusion (RFI/LFI)**: Detects attempts to include remote or local files.
6. **Command Injection**: Detects shell command injection patterns and common commands like `ls`, `cat`, and `rm`.
7. **Email Injection**: Detects email header injection attempts using `BCC`, `CC`, and newline characters.
8. **HTTP Header Injection**: Detects HTTP header injection attempts with patterns like `Set-Cookie` and `Content-Length`.
9. **CSRF Token Missing** (Optional): Detects requests missing CSRF tokens. This rule is disabled by default to avoid false positives. Enable it only if your app uses CSRF tokens.

### Enabling the `csrf_token_missing` Rule

If your app uses CSRF tokens, you can enable the `csrf_token_missing` rule by updating the configuration:

```python
from flask_guard.rules import load_user_config

custom_rules = {
    "csrf_token_missing": {
        "enabled": True,
    }
}

load_user_config(user_rules=custom_rules)
```

## Testing the Firewall 🧪

You can test the firewall using `curl` commands. Below are examples of malicious requests:

### SQL Injection

```bash
curl "http://127.0.0.1:5000/malicious?query=%27%20OR%201%3D1%20--"
```

### XSS Attack

```bash
curl "http://127.0.0.1:5000/malicious?query=%3Cscript%3Ealert%281%29%3C%2Fscript%3E"
```

### Path Traversal

```bash
curl "http://127.0.0.1:5000/malicious?query=../../etc/passwd"
```

### Command Injection

```bash
curl "http://127.0.0.1:5000/malicious?query=ls%20-al"
```

### Email Injection

```bash
curl "http://127.0.0.1:5000/malicious?query=TO:%20victim@example.com%0ABCC:%20attacker@example.com"
```

### HTTP Header Injection

```bash
curl "http://127.0.0.1:5000/malicious?query=%0D%0ASet-Cookie:%20malicious=true"
```

### Legitimate Request

```bash
curl "http://127.0.0.1:5000/safe?query=safe_param=value"
```

## Contributing 🤝

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License 📄

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