# URL_Guardian

**Repository Path**: liu-bi0388/URL_Guardian

## Basic Information

- **Project Name**: URL_Guardian
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTTP安全检测工具

基于机器学习的HTTP安全检测工具，通过装饰器模式为Python函数提供安全检测能力。

## 功能特性

- **多攻击类型检测**：支持SQL注入、XSS、路径遍历、命令注入等15种攻击类型
- **装饰器封装**：一行代码即可为函数添加安全检测
- **多种检测模式**：规则检测、模型检测、混合检测
- **日志存储**：检测结果存储到SQLite数据库
- **可视化报告**：生成HTML、PNG、JSON格式报告
- **自定义规则**：支持自定义检测规则

## 安装

```bash
pip install onnxruntime numpy
pip install matplotlib  # 可选，用于生成图片报告
```

## 快速开始

### 基本使用

```python
from security_detector import detect_http, SecurityError

@detect_http(mode="rule", action="block")
def process_query(query: str):
    return f"处理结果: {query}"

# 正常请求
result = process_query("Hello, World!")  # 正常执行

# 恶意请求
try:
    process_query("' OR '1'='1")  # 抛出SecurityError
except SecurityError as e:
    print(f"检测到{e.attack_type}攻击")
```

### 混合模式（推荐）

```python
@detect_http(
    mode="hybrid",           # 模型+规则混合检测
    action="block",
    model_path="models"
)
def api_handler(request: dict):
    return {"status": "ok"}
```

### 数据库存储

```python
@detect_http(
    mode="rule",
    action="block",
    db_path="data/logs.db",
    log_to_db=True
)
def api_endpoint(request: dict):
    return {"status": "success"}
```

## 装饰器参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| mode | str | "hybrid" | 检测模式: rule/model/hybrid |
| threshold | float | 0.7 | 置信度阈值 |
| action | str | "block" | 处理动作: block/warn/allow |
| db_path | str | None | 数据库路径 |
| log_to_db | bool | True | 是否存储到数据库 |
| generate_report | bool | False | 是否生成报告 |
| report_dir | str | "reports" | 报告输出目录 |
| report_format | list | ["html", "png", "json"] | 报告格式 |
| model_path | str | "models" | 模型路径 |
| custom_rules | dict | None | 自定义规则 |

## 检测模式

| 模式 | 说明 |
|------|------|
| rule | 纯规则检测，使用内置或自定义规则 |
| model | 纯模型检测，使用ONNX嵌入模型+向量相似度 |
| hybrid | 混合模式，模型检测是否恶意 + 规则检测具体类型 |

## 支持的攻击类型

| 类型 | 名称 | 严重程度 |
|------|------|---------|
| sqli | SQL注入 | High |
| xss | 跨站脚本 | High |
| path_traversal | 路径遍历 | High |
| command_injection | 命令注入 | Critical |
| credential_stuffing | 凭证填充 | High |
| spam_bot | 垃圾机器人 | Medium |
| scanner | 漏洞扫描 | Medium |
| ssrf | 服务端请求伪造 | High |
| xxe | XML外部实体注入 | High |
| log4shell | Log4j漏洞 | Critical |
| ssti | 服务端模板注入 | High |
| nosql_injection | NoSQL注入 | High |
| open_redirect | 开放重定向 | Medium |
| prototype_pollution | 原型污染 | Medium |

## 自定义规则

```python
custom_rules = {
    'sqli': [
        (r"'\s*OR\s+'", "OR条件绕过"),
        (r"UNION\s+SELECT", "UNION查询注入"),
    ],
    'custom_attack': [
        (r"malicious_pattern", "自定义攻击模式"),
    ]
}

@detect_http(mode="rule", custom_rules=custom_rules)
def my_handler(data: str):
    return data
```

## 异常处理

```python
from security_detector import SecurityError

try:
    process_query(malicious_input)
except SecurityError as e:
    print(f"错误信息: {e.message}")
    print(f"攻击类型: {e.attack_type}")
    print(f"置信度: {e.confidence}")
    print(f"详细信息: {e.details}")
```

## 生成报告

```python
from security_detector import SecurityDetector, ReportGenerator

detector = SecurityDetector(mode="rule")
reporter = ReportGenerator(output_dir="reports", formats=["html", "json", "png"])

result = detector.detect("test input")
# ... 收集检测结果 ...

files = reporter.generate("report_name")
```

## 项目结构

```
security_detector/
├── __init__.py          # 导出接口
├── detector.py          # 核心检测器
├── decorator.py         # 装饰器实现
├── model_loader.py      # ONNX模型加载器
├── database.py          # 数据库操作
├── reporter.py          # 报告生成器
└── exceptions.py        # 自定义异常

models/                  # 模型文件目录
├── embedding_model.onnx # 嵌入模型
├── vectors.bin          # 预计算向量库
├── labels.json          # 标签文件
├── vocab.json           # 词表
└── config.json          # 配置

tests/                   # 单元测试
examples/                # 使用示例
```

## 运行测试

```bash
pytest tests/ -v
```

## 运行示例

```bash
python examples/basic_usage.py      # 基本使用
python examples/model_test.py       # 模型测试
python examples/database_example.py # 数据库示例
python examples/report_example.py   # 报告示例
python examples/advanced_usage.py   # 高级用法
```

## 模型说明

本项目使用 [AI-Bouncer](https://huggingface.co/khasinski/ai-bouncer) 模型：

- **架构**: Model2Vec (distilled from MiniLM)
- **格式**: ONNX
- **大小**: ~33MB
- **推理速度**: ~2ms/请求
- **嵌入维度**: 256
- **训练数据**: 3,053个标注攻击模式

## 许可证

MIT License