dbanegasl/humble-web
GitHub: dbanegasl/humble-web
这是一个自托管的HTTP安全头分析器，通过Web界面和REST API简化网站安全配置的评估过程。
Stars: 0 | Forks: 0
# humble-web
自托管的 Docker 堆栈，将 [**humble**](https://github.com/rfc-st/humble)（HTTP头部分析器）暴露为：
- **REST API** — 可直接与 `curl`、脚本、CI/CD 或任何应用程序集成
- **Web界面** — 通过浏览器进行分析，获得可视化结果
## 要求
- [Docker](https://docs.docker.com/get-docker/) + [Docker Compose](https://docs.docker.com/compose/)
## 快速开始
```
git clone https://github.com/dbanegasl/humble-web
cd humble-web
```
**（可选）** 在启动前调整端口或其他变量：
```
cp .env.example .env
# 根据需要编辑 .env
```
然后启动堆栈：
```
docker compose up --build -d
```
此操作会克隆 humble，构建镜像并启动服务。使用以下命令查看活动端口：
```
docker compose ps
```
默认设置：
| 服务 | URL | 说明 |
|---------------|------------------------------|---------------------------------|
| Web UI | http://localhost:3000 | 用于分析的 React 界面 |
| REST API | http://localhost:8000 | 用于集成的 JSON 端点 |
| Swagger UI | http://localhost:8000/docs | 交互式文档 |
| ReDoc | http://localhost:8000/redoc | 备用文档 |
## Web界面
访问 `http://localhost:3000`，输入 URL，即可获得完整的分析结果，包括：
- 安全评级（A–F）
- 已启用、缺失、不安全和指纹头信息的摘要
- 按类别划分的详情，并附带 MDN 和官方文档的参考
- 支持英语和西班牙语
## REST API
### `GET /api/health`
```
curl http://localhost:8000/api/health
```
```
{
"status": "ok",
"humbleAvailable": true,
"humblePath": "/app/humble/humble.py"
}
```
### `GET /api/analyze`
分析一个 URL 的 HTTP 头。
| 参数 | 类型 | 必需 | 说明 |
|-----------|--------|------|------------------------------------------------|
| `url` | string | ✅ | 要分析的完整 URL（`http://` 或 `https://`） |
| `lang` | string | ❌ | 语言：`en`（默认）或 `es` |
```
# 基本分析
curl "http://localhost:8000/api/analyze?url=https://example.com"
# 西班牙语
curl "http://localhost:8000/api/analyze?url=https://example.com&lang=es"
# 将结果保存到文件
curl -s "http://localhost:8000/api/analyze?url=https://misitio.com" -o resultado.json
# 提取缺失的 headers（需要 jq）
curl -s "http://localhost:8000/api/analyze?url=https://misitio.com" \
| jq '."[2. Missing HTTP Security Headers]"[].Header'
# 查看结果摘要
curl -s "http://localhost:8000/api/analyze?url=https://misitio.com" \
| jq '."[7. Analysis Results]"'
```
### `POST /api/analyze`
```
curl -X POST http://localhost:8000/api/analyze \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "lang": "es"}'
```
## JSON 响应结构
```
{
"[0. Info]": { "Generator": "...", "Date": "...", "URL": "..." },
"[1. Enabled HTTP Security Headers]": [
{ "Header": "Content-Type", "Value": "text/html" }
],
"[2. Missing HTTP Security Headers]": [
{
"Header": "Content-Security-Policy",
"Details": "Detecta y mitiga ataques XSS y de inyección de datos.",
"References": ["https://..."]
}
],
"[3. Fingerprint HTTP Response Headers]": [...],
"[4. Deprecated HTTP Response Headers/Protocols and Insecure Values]": [...],
"[5. Empty HTTP Response Headers Values]": [...],
"[6. Browser Compatibility for Enabled HTTP Security Headers]": [...],
"[7. Analysis Results]": { "Missing": 15, "Warnings": 3, ... },
"_meta": {
"url": "https://example.com",
"lang": "es",
"exitCode": 0
}
}
```
## 代码集成
### Python
```
import httpx
resp = httpx.get(
"http://localhost:8000/api/analyze",
params={"url": "https://misitio.com"},
timeout=130,
)
resp.raise_for_status()
data = resp.json()
missing = data["[2. Missing HTTP Security Headers]"]
print(f"Headers faltantes: {len(missing)}")
for h in missing:
print(f" - {h['Header']}")
```
### JavaScript / Node.js
```
const res = await fetch(
"http://localhost:8000/api/analyze?url=https://misitio.com"
);
const data = await res.json();
console.log("Headers faltantes:", data["[2. Missing HTTP Security Headers]"].length);
console.log("Resultados:", data["[7. Analysis Results]"]);
```
### Shell — 批量域名分析
```
#!/usr/bin/env bash
DOMAINS=("https://example.com" "https://github.com" "https://google.com")
for url in "${DOMAINS[@]}"; do
echo "Analizando $url ..."
curl -s "http://localhost:8000/api/analyze?url=${url}" \
| jq -r '"URL: \(._meta.url) | Missing: \(."[7. Analysis Results]".Missing // "?")"'
done
```
## 配置（`.env`）
如果没有 `.env` 文件，堆栈将使用默认值启动。要自定义，请复制并编辑：
```
cp .env.example .env
```
| 变量 | 默认值 | 说明 |
|-------------------|---------|------------------------------------------------------|
| `FRONTEND_PORT` | `3000` | 宿主机上前端 Web 的端口 |
| `API_PORT` | `8000` | 宿主机上 REST API 的端口 |
| `HUMBLE_TIMEOUT` | `120` | 单次分析的最大秒数 |
| `ALLOWED_ORIGINS` | `*` | 用于直接访问 API 的 CORS 来源 |
## 更新 humble
humble 已包含在 Docker 镜像中。要更新到最新提交：
```
docker compose build && docker compose up -d
```
## 常用命令
```
docker compose up --build -d # build + levantar
docker compose down # detener
docker compose restart # reiniciar sin rebuild
docker compose logs -f # logs en tiempo real
docker compose ps # estado y puertos activos
docker compose build # solo reconstruir imágenes
```
还有一个 `Makefile`，包含等效的快捷命令（`make up`, `make down` 等），供喜欢使用它的人选用。
## 速率限制
API 按 IP 接受 **每分钟 10 个请求**。对于高强度使用（CI/CD、批量脚本），请在请求之间添加 `sleep`。
## 架构
```
┌──────────────────────────────────────────┐
│ Host │
│ :${FRONTEND_PORT} (web) │
│ :${API_PORT} (api) │
└────────┬──────────────────┬─────────────┘
│ │
┌────────▼───────┐ ┌───────▼────────────┐
│ frontend │ │ api │
│ nginx:alpine │ │ FastAPI :8000 │
│ React + Vite │ │ + slowapi │
│ Tailwind CSS │ └───────┬────────────┘
│ │ │ subprocess
│ /api/ proxy ──┼──────────┘
└────────────────┘ │
┌───────▼────────────┐
│ humble (en imagen)│
│ git clone en build│
└────────────────────┘
```
标签：API集成, AV绕过, Docker, Docker Compose, FastAPI, HTTP安全头, IPv6支持, React, REST API, Syscalls, Web界面, 可观测性, 头分析器, 安全扫描, 安全评分, 安全防御评估, 工具, 文档生成, 时序注入, 网络安全, 网络测绘, 网络调试, 自动化, 自动化攻击, 自托管, 请求拦截, 隐私保护