Tajaddin/owasp-secguard
GitHub: Tajaddin/owasp-secguard
一个结合 FastAPI 注入检测中间件与 pre-commit 密钥扫描器的轻量级应用安全工具，在标记语料库上实现了 100% 召回与零误报。
Stars: 0 | Forks: 0
# owasp-secguard
[](https://github.com/Tajaddin/owasp-secguard/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
## 核心指标
无需任何基础设施，即可立即复现：
```
python -m benchmarks.detection_bench
```
| 指标 | 数值 |
|---|---:|
| 恶意 payload | 25 (SQLi、XSS、路径遍历、命令注入；包含 URL 编码) |
| 良性输入 | 20 (类 SQL 描述、代码、文件路径、营销文案) |
| **Recall** | **100%** |
| **Precision** | **100%** |
| **误报率** | **0%** |
| **F1** | **1.0** |
良性数据集对简单的检测器具有蓄意的对抗性：它包含了 "Please select your database plan"、"order by date please" 和 "Drop me an email when you union the teams"，这些内容会被粗心的正则表达式标记为恶意。检测器使用单词边界和结构模式（并对 URL 解码后的形式重新扫描）来区分攻击与常规描述文本。
## 如何运行
前置条件：Python 3.10+。
```
# 安装（包含 FastAPI middleware extra）
pip install -e ".[dev,fastapi]"
# 单元测试
pytest -q
# 检测基准（F1 = 1.0 的最佳模型）
python -m benchmarks.detection_bench
# CLI：扫描文件或目录中已提交的 secrets
secguard-scan path/to/file ...
secguard-scan --staged # scan git-staged files (pre-commit usage)
```
冒烟测试：`python -c "from secguard import scan_value; print(scan_value(\"1' OR '1'='1\"))"` 应打印出一次 SQL 注入检测结果。
## 两个工具
### 1. 注入检测中间件 (FastAPI / Starlette)
```
from fastapi import FastAPI
from secguard import SecGuardMiddleware, Severity
app = FastAPI()
app.add_middleware(SecGuardMiddleware, min_severity=Severity.MEDIUM, block=True)
```
检查路径、查询参数和请求体（URL 解码后）。当检测到的严重程度达到或超过 `min_severity` 时，它会返回 `403` 并附上匹配的类别；或者在审计模式（`block=False`）下，放行请求并将检测结果记录在请求状态中以供日志记录。
### 2. 密钥扫描器 (pre-commit / CI)
```
secguard-scan path/to/file ... # scan files
secguard-scan --staged # scan git-staged files (pre-commit)
```
标记已提交的凭证：Anthropic / OpenAI / Voyage 密钥、AWS 访问密钥、GitHub / Slack token、私钥、JWT 以及包含内嵌密码的数据库 URL。它会以非零状态退出，从而导致提交或 CI 任务失败。
它会抑制明显的占位符（`your-...`、`example`、`changeme`、空值、`localhost` 数据库 URL），并将通用的 `secret = "..."` 规则置于 Shannon 熵检查之后，因此文档和模板不会触发它。
作为 pre-commit hook 运行：
```
# .pre-commit-config.yaml
repos:
- repo: https://github.com/Tajaddin/owasp-secguard
rev: v0.1.0
hooks:
- id: secguard-scan
```
## 检测类别
| 类别 | 示例特征 |
|---|---|
| SQL 注入 | `UNION SELECT`、`OR 1=1`、堆叠 `; DROP`、引号注释 `'--`、基于时间的 `pg_sleep(` / `WAITFOR DELAY` |
| XSS | `