mr-addams/arxsentinel

# ArxSentinel [](https://github.com/mr-addams/arxsentinel/releases) [](https://github.com/mr-addams/arxsentinel/actions/workflows/release.yml) [](LICENSE) [](go.mod) [](https://github.com/mr-addiams/arxsentinel/releases) [](https://github.com/mr-addiams/arxsentinel/releases) **适用于任何 HTTP 服务器的安全事件管道** —— 从单台 nginx VPS 到完整的 K8s 集群。 约 12 MB 内存 · 单文件二进制 · 零运行时依赖 · 通过任意语言的 exec+JSON 插件进行扩展。 ``` [nginx / Apache / Caddy / ...] [exec+JSON Source — any language] │ │ └─────────────────┬──────────────────────┘ Source (file │ stdin │ http) │ Merge & Parse │ ┌───────────────┼───────────────┐ Whitelist ChainGuard BotVerifier └───────────────┼───────────────┘ Tracker (IP state) │ Scorer + 8 Detectors │ ┌──────────────────┼──────────────────┐ Fail2Ban sink stdout JSON exec+JSON Sink (threats.log) (Loki / Splunk / ...) (any script) ``` ## 使用场景 ArxSentinel 可从传统的裸金属 VPS 扩展到分布式 Kubernetes 集群 —— 以下每个场景都是一个独立的起点。 ### 1. 经典 Web 防护 —— nginx + Fail2Ban 一个配置文件，无需 Profile。开箱即用： ``` general: log_file: /var/log/nginx/access.log output: threat_log: /var/log/arxsentinel/threats.log ``` ### 2. Docker Compose 边车模式 挂载 nginx 日志卷；ArxSentinel 作为边车读取日志。参见 [`deploy/examples/docker/`](deploy/examples/docker/)： ``` # docker-compose.yml — 摘录 services: arxsentinel: image: ghcr.io/mr-addams/arxsentinel:latest volumes: - nginx_logs:/var/log/nginx:ro environment: ARXSENTINEL_LOG_FILE: /var/log/nginx/access.log ``` ### 3. Kubernetes DaemonSet 每个节点一个 Pod，通过 `hostPath` 读取主机日志。参见 [`deploy/examples/kubernetes/`](deploy/examples/kubernetes/) 和 [Helm README](deploy/container/k8s/arxsentinel/README.md)： ``` helm install arxsentinel ./deploy/container/k8s/arxsentinel \ --set logVolume.hostPath=/var/log/nginx ``` ### 4. 多服务器聚合 在一个进程中监控多台服务器 —— 每个日志流具有完全隔离的 IP 状态： ``` streams: - name: frontend log_file: /var/log/nginx/access.log - name: api log_file: /var/log/apache2/api.log profile: apache ``` ### 5. 自定义日志格式 API 网关、自定义应用日志、任意文本格式 —— 提供带有命名捕获组的正则表达式： ``` parser: log_format: "custom" custom_regex: '(?P\S+) \S+ \S+ \[.*?\] "\S+ (?P\S+) \S+" (?P\d+) (?P\d+) "(?P[^"]*)"' ``` ### 6. 外部检测器插件 —— exec+JSON 任何脚本或二进制文件均可作为附加检测器；通过 stdin/stdout 为每个请求调用，支持任意语言。参见[插件开发](#plugin-development)： ``` detectors: plugins: - name: ml-classifier exec: /opt/plugins/classify.py score: 45 ``` ### 7. 自定义输出接收器 —— exec+JSON 将威胁路由到任何目标 —— SIEM、webhook、Telegram、自定义脚本： ``` sinks: - type: exec exec: /opt/plugins/send-to-siem.sh ``` ## 快速开始 安装软件包，启用 systemd 服务，并立即与 nginx 协同工作： ``` curl -fsSL https://raw.githubusercontent.com/mr-addams/arxsentinel/main/scripts/get.sh | sudo bash ``` 编辑服务器配置，然后无需重启即可重新加载： ``` sudo nano /etc/arxsentinel/config.yaml sudo systemctl kill -s HUP arxsentinel ``` 有关 Docker、Kubernetes 及其他安装方法 —— 请参见下方的[安装](#installation)部分。 ## 安装说明 ### 快速安装 —— 适用于任何发行版（推荐） 自动检测您的发行版和架构，从 GitHub Releases 下载正确的软件包， 使用您的包管理器进行安装，启用并启动服务： ``` curl -fsSL https://raw.githubusercontent.com/mr-addams/arxsentinel/main/scripts/get.sh | sudo bash ``` 适用于 Debian、Ubuntu、Fedora、RHEL、AlmaLinux、Rocky Linux 和 Arch Linux。 需要 `curl` 和 `sudo`。如果缺失，Fail2Ban 会自动安装。 服务会立即启动，并与 nginx 即时协同工作 —— 无需 Profile。编辑配置以切换到其他服务器（apache、caddy、traefik、haproxy-http、litespeed 或自定义正则表达式）： ``` sudo nano /etc/arxsentinel/config.yaml sudo systemctl kill -s HUP arxsentinel # reload without restart ``` ### Debian / Ubuntu —— 手动安装包 从[发布页面](https://github.com/mr-addams/arxsentinel/releases)下载适用于您架构的 `.deb` 包并进行安装： ``` # amd64 sudo apt install ./arxsentinel__linux_amd64.deb # arm64 sudo apt install ./arxsentinel__linux_arm64.deb ``` `apt install` 会自动解析依赖项（`fail2ban`），安装 systemd 单元、Fail2Ban 过滤器/监狱、logrotate 配置，并创建 `arxsentinel` 系统用户。 安装后，编辑配置并启动服务： ``` sudo nano /etc/arxsentinel/config.yaml sudo systemctl enable --now arxsentinel ``` ### Fedora / RHEL / AlmaLinux / Rocky Linux 从[发布页面](https://github.com/mr-addams/arxsentinel/releases)下载适用于您架构的 `.rpm` 包并进行安装： ``` # amd64 sudo dnf install ./arxsentinel__linux_amd64.rpm # arm64 sudo dnf install ./arxsentinel__linux_arm64.rpm ``` `dnf install` 会解析依赖项，将 systemd 单元安装到 `/usr/lib/systemd/system/`，设置 Fail2Ban 过滤器/监狱、logrotate 配置，并创建 `arxsentinel` 系统用户。 安装后，编辑配置并启动服务： ``` sudo nano /etc/arxsentinel/config.yaml sudo systemctl enable --now arxsentinel ``` ### Arch Linux / Manjaro 从[发布页面](https://github.com/mr-addams/arxsentinel/releases)下载适用于您架构的 `.pkg.tar.zst` 包并进行安装： ``` # amd64 sudo pacman -U arxsentinel__linux_amd64.pkg.tar.zst # arm64 sudo pacman -U arxsentinel__linux_arm64.pkg.tar.zst ``` 该软件包将 systemd 单元安装到 `/usr/lib/systemd/system/`，设置 Fail2Ban 配置文件、logrotate 配置，并创建 `arxsentinel` 系统用户。 安装后，编辑配置并启动服务： ``` sudo nano /etc/arxsentinel/config.yaml sudo systemctl enable --now arxsentinel ``` ### 从源代码构建 需要 Go 1.19+： ``` git clone https://github.com/mr-addams/arxsentinel cd arxsentinel sudo ./scripts/install.sh sudo systemctl enable --now arxsentinel ``` ### Docker 无发行版基础镜像（约 12 MB），以非 root 用户 UID 65532 运行，在 `:9117` 端口暴露 Prometheus 指标。 ``` docker run -d \ -v /var/log/nginx/access.log:/var/log/nginx/access.log:ro \ -v /var/log/arxsentinel:/var/log/arxsentinel \ -p 127.0.0.1:9117:9117 \ ghcr.io/mr-addams/arxsentinel:latest ``` 有关 Docker Compose 设置、卷挂载、环境变量覆盖和 Fail2Ban 集成，请参阅 [README.docker.md](deploy/container/docker/README.md)。 ### Kubernetes (Helm) DaemonSet 拓扑 —— 每个节点一个 Pod，通过 `hostPath` 读取节点的访问日志。 ``` helm install arxsentinel ./deploy/container/k8s/arxsentinel \ --set logVolume.hostPath=/var/log/nginx \ --set threatLog.hostPath=/var/log/arxsentinel ``` 有关 values 参考、Prometheus Operator 集成和云部署说明，请参阅 [README.helm.md](deploy/container/k8s/arxsentinel/README.md)。 ## 支持的 HTTP 服务器 ### 兼容性表格 | 服务器 | Profile | 所需设置 | |--------|---------|----------------| | nginx | *（默认 —— 无需 Profile）* | 无 —— nginx combined 日志格式开箱即用 | | Apache | `apache` | 无 —— 默认 CLF 格式 | | Traefik | `traefik` | 在 accessLog 中添加 `fields.headers.names.User-Agent/Referer: keep` —— 参见 [`deploy/examples/traefik/`](deploy/examples/traefik/) | | LiteSpeed / OpenLiteSpeed | `litespeed` | 无 —— 默认 CLF 格式 | | Caddy | `caddy` | 需要 [xcaddy](https://github.com/caddyserver/xcaddy) + [transform-encoder](https://github.com/caddyserver/transform-encoder) 插件 —— 参见 [`deploy/examples/caddy/`](deploy/examples/caddy/) | | HAProxy | `haproxy-http` | `http-request capture` + 带 UA 的自定义 `log-format` —— 参见 [`deploy/examples/haproxy/`](deploy/examples/haproxy/) | 内置 Profile —— 无需正则表达式或字段映射。对于 Apache、Traefik、Caddy、HAProxy、LiteSpeed 或 OpenLiteSpeed，将 `parser.profile` 设置为服务器名称即可： **示例 —— Apache：** ``` parser: profile: "apache" general: log_file: /var/log/apache2/access.log output: threat_log: /var/log/arxsentinel/threats.log ``` 适用于每种服务器的现成配置位于 [`deploy/examples/`](deploy/examples/)： ``` deploy/examples/ ├── apache/ httpd.conf + sentinel-config.yaml ├── caddy/ Caddyfile + sentinel-config.yaml ├── traefik/ traefik.yml + sentinel-config.yaml ├── haproxy/ haproxy.cfg + sentinel-config.yaml └── litespeed/ httpd_config.conf + sentinel-config.yaml ``` ## 功能特性 - **8 个检测器：** 探测扫描、速率异常、可疑 User-Agent、暴力破解（404 比率）、顺序爬虫、无资源请求的机器人、URL 溢出 / WAF 绕过、社区恶意机器人黑名单 - **链路守护：** 检测 Cloudflare/CDN 边缘 IP 和 bogon/RFC 1918/CGNAT 地址作为客户端 IP 出现 —— 在 ArxSentinel 检测器失效之前，发出代理链配置错误的信号 - **机器人 DNS 验证：** Googlebot、Bingbot、Yandex、DuckDuckGo 等通过 rDNS/fDNS 进行验证 —— 合法的爬虫永远不会被禁止 - **多流 + 多管道：** 在一个进程中监控多个日志文件；在每个流内，定义独立的管道，每个管道有自己的检测器、源、接收器和 IP 状态跟踪器（或通过 `tracker_group` 共享状态） - **白名单：** IP、CIDR、UA 子串 —— 可配置的排除列表 - **线性分数衰减：** 分数在 `observation_window` 内衰减，避免因旧流量导致误封 - **Prometheus 指标：** `/metrics` 端点在可配置端口上（默认 `:9117`），可选 bcrypt 基础认证；包含 Grafana 仪表板 - **健康检查端点：** `/health` 始终返回 `200 {"status":"ok"}` —— 无需凭据；适用于 Docker `HEALTHCHECK`、k8s 探针和负载均衡器 - **JSON 日志格式：** 通过 `parser.log_format: "json"` 切换到 JSON 日志解析 —— 无需重新编译 - **SIGHUP 热重载：** 配置、评分器、解析器和白名单在不重启守护进程的情况下重建 - **优雅关闭：** 在 SIGTERM 信号下排空行缓冲区 - **Systemd + logrotate + Fail2Ban：** 包含即用型部署配置 ## 系统要求 - 带有 systemd 的 Linux x86_64 或 arm64 - Fail2Ban - 一个以受支持格式（nginx、Apache、Caddy、Traefik、HAProxy、LiteSpeed、OpenLiteSpeed —— 或自定义正则表达式）记录访问日志的 HTTP 服务器 ## 配置说明 配置文件：`/etc/arxsentinel/config.yaml`（安装期间从 `config.yaml` 创建）。 覆盖路径：`ARXSENTINEL_CONFIG=/path/to/config.yaml`。 关键参数： ``` general: log_file: /var/log/nginx/access.log # log file to watch (nginx example; see also: streams:) stats_interval: 300s # STATS output interval to operational log parser: # profile: "apache" # set for non-nginx servers: apache | caddy | traefik | haproxy-http | litespeed # # nginx combined log format works without any profile setting scoring: alert_threshold: 50 # score → WARN in threat log ban_threshold: 80 # score → THREAT + Fail2Ban ban observation_window: 300s # score accumulation / decay window detectors: probe: enabled: true score: 25 paths: [/.env, /.git/config, /wp-config.php, ...] # probe path list rate: enabled: true threshold: 100 # requests per window window: 60s score: 25 useragent: enabled: true scanner_score: 40 # Nuclei, sqlmap, Nikto grabber_score: 20 # wget, HTTrack automation_score: 15 # python-requests, aiohttp empty_ua_score: 30 bruteforce: enabled: true min_requests: 10 ratio_threshold: 0.6 # >60% of responses are 404 score: 30 crawler: enabled: true min_sequential: 5 # /page/1, /page/2, ... N in a row score: 20 noasset: enabled: true min_page_requests: 3 asset_ratio_threshold: 0.1 # <10% of requests go to static assets score: 20 overflow: enabled: true max_url_length: 2048 suspicious_params: [bypass, shell, cmd, exec, eval] score: 30 badbot: enabled: true score: 60 check_ua: true check_referrer: false # opt-in: also match the Referer header (~7108 referrer patterns) blocklist: storage: "" # "" = in-memory; file path = bbolt (survives restarts) lists: - name: badbot-ua refresh_interval: 24h sources: - url: "https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list" format: plain_text - name: badbot-ref refresh_interval: 24h sources: - url: "https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-referrer-words.list" format: plain_text whitelist: fake_bot_score: 35 # penalty for a bot UA that fails DNS verification dns_verify_timeout: 2s # DNS verification timeout per pipeline request custom: ips: [127.0.0.1] cidrs: [10.0.0.0/8] ua_substrings: [internal-monitor] output: threat_log: /var/log/arxsentinel/threats.log operational_log: /var/log/arxsentinel/sentinel.log ``` ## 检测器 | 检测器 | 触发条件 | 默认分数 | |----------|---------|---------------| | **probe** | 对 .env、.git、wp-config.php 等的请求 | 每个请求 25 分 | | **rate** | 60 秒内 >100 次请求 | 25 分 | | **useragent** | 扫描器 / 抓取器 / 自动化工具 / 空 UA | 15–40 分 | | **bruteforce** | 超过 60% 的响应为 404 且请求数 ≥10 | 30 分 | | **crawler** | ≥5 个连续数字 URL (/page/1..N) | 20 分 | | **noasset** | 对静态资源的请求比例 <10%，且页面请求数 ≥3 | 20 分 | | **overflow** | URL >2048 字符或包含 WAF 绕过关键词 | 30 分 | | **badbot** | UA（或 Referer）匹配社区黑名单（约 685 个模式） | 60 分 | 分数在 `observation_window` 内线性衰减累积。达到 `alert_threshold` 时记录警告；达到 `ban_threshold` 时记录威胁并触发 Fail2Ban。 ## 部署指南 ### systemd —— 裸金属部署 由上述包安装程序覆盖。使用 `systemctl` 管理服务，使用 `kill -HUP` 进行实时重载。有关完整命令参考，请参见[管理](#management)。 ### Docker Compose ArxSentinel 作为边车与您的 HTTP 服务器一起运行，读取共享的日志卷。 即用型 Compose 文件和配置：[`deploy/examples/docker/`](deploy/examples/docker/)。 完整 Docker 指南：[README.docker.md](deploy/container/docker/README.md)。 ### Kubernetes DaemonSet（每个节点一个 Pod，读取主机日志）或边车（从与应用程序容器共享的 emptyDir 读取）。 即用型清单：[`deploy/examples/kubernetes/`](deploy/examples/kubernetes/)。 带 values 参考的 Helm chart：[README.helm.md](deploy/container/k8s/arxsentinel/README.md)。 ## 执行器 执行器是有状态的操作插件，在威胁评分后运行。与接收器（被动日志写入器）不同，执行器主动管理外部资源：它们维护本地去重映射，应用基于 TTL 的过期机制，并跟踪执行统计信息。 | 执行器 | 包 | 描述 | |---|---|---| | **cloudflare** | | 将威胁 IP 添加到 Cloudflare IP 列表；通过 TTL 扫描自动移除过期条目 | 有关框架概述以及如何添加自定义执行器，请参阅 [docs/executors.md](docs/executors.md)。 有关 Cloudflare 特定配置和故障排除，请参阅 [docs/executor-cloudflare.md](docs/executor-cloudflare.md)。 ## 插件开发 源、接收器和检测器插件通过 **stdin/stdout JSON** 与 ArxSentinel 通信 —— 可用任何语言编写。插件为每个日志条目（或事件）接收一个 JSON 对象，并返回一个 JSON 响应。ArxSentinel 管理子进程生命周期。 完整协议规范和示例：[`docs/PLUGIN_DEV.md`](docs/PLUGIN_DEV.md)。 ## 白名单 ArxSentinel 提供自动的机器人验证（搜索引擎）和自定义排除列表 （IP、CIDR、User-Agent 子串）。白名单中的请求将完全跳过所有检测器。 有关配置详情和示例，请参阅 [README.whitelist.md](deploy/examples/README.whitelist.md)。 ## 架构概述 ``` [Source: file] ─┐ FileSource (inotify, logrotate-aware) [Source: stdin] ─┼──→ Merge() ──→ entries chan (*LogEntry) [Source: http] ─┘ (Phase 2+) │ whitelist.Matcher ──→ custom IP/CIDR/UA? → skip │ chaincheck.Checker ──→ Cloudflare/bogon IP? → warnings.log │ whitelist.Verifier ──→ bot UA? → rDNS/fDNS → verified? → skip │ → fake bot? → +FakeBotScore tracker.Update(*IPState) ├── TotalRequests, Requests404 ├── pathBuf (ring buffer, last 64 paths) └── sliding window rate counters │ scorer.Evaluate(ipState, entry) ├── decay accumulated score ├── run 8 detectors └── determine verdict (score → level) │ [Sink: Fail2Ban file] ──→ threats.log ──→ Fail2Ban ──→ iptables ban [Sink: stdout JSON] ──→ log aggregator (Loki, Splunk, Datadog) [Sink: Splunk/Kafka] (Phase 2+) │ sentinel.log (operational) ``` 默认配置（Fail2Ban 文件接收器）完全向后兼容 —— 现有的 `general.log_file` 和 `output.threat_log` 设置可以保持不变。 后台 goroutine： - **FileSource** —— 通过 fsnotify 进行文件监控，处理 mv/copytruncate 类型的 logrotate - **GC** —— 每 `gc_interval`（默认 60 秒）移除不活跃的 IP - **Stats** —— 每 `stats_interval` 打印 `STATS processed/tracked/threats/suspicious` - **SIGHUP 监听器** —— 将信号转换为通道事件供主循环处理 完整的组件层次结构和数据流图：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 ## 多流监控 运行一个哨兵进程，同时监控多个日志文件 —— 每个域名一个管道，完全隔离。 ### 配置示例 ``` streams: - name: site1 log_file: /var/log/nginx/site1.access.log threat_log: /var/log/arxsentinel/site1.threats.log - name: site2 log_file: /var/log/apache2/site2.access.log threat_log: /var/log/arxsentinel/site2.threats.log profile: apache ``` 每个流都有自己的跟踪器、评分器、白名单状态和威胁日志。一个流的崩溃或慢速扫描不会影响其他流。 ### 向后兼容性 经典的单文件配置（`general.log_file`）继续有效 —— 它会被静默转换为单个未命名的流（在指标上使用 `stream=""` 标签）。无需进行配置迁移。 ## 多管道配置 在单个流内，定义独立的管道 —— 每个管道有自己的源、检测器、接收器和 IP 状态跟踪器。使用 `tracker_group` 在监控相关流量的管道之间共享 IP 状态。 ``` streams: - name: nginx-monitoring pipelines: - name: api-scanner tracker_group: web # pipelines with the same group share IP state inputs: - type: file path: /var/log/nginx/api.log detectors: probe: enabled: true rate: enabled: true threshold: 100 outputs: - type: file path: /var/log/arxsentinel/api-threats.log - name: admin-watcher tracker_group: web # shares IP state with api-scanner inputs: - type: file path: /var/log/nginx/admin.log detectors: bruteforce: enabled: true badbot: enabled: true outputs: - type: file path: /var/log/arxsentinel/admin-threats.log ``` **TrackerGroup 规则：** - `tracker_group: web` —— 具有相同组的管道共享一个 `*state.Tracker`；在 `api-scanner` 中被评分的攻击者也会被 `admin-watcher` 跟踪 - `tracker_group: ""`（或省略）—— 隔离的；管道的 `name` 用作隐式组键 - 旧配置（无 `pipelines:` 键）—— 自动包装为一个未命名的管道；行为与以前的版本相同 **Prometheus 指标** 在所有向量上获得 `pipeline` 标签（例如 `arx_sentinel_lines_processed_total{stream="nginx-monitoring", pipeline="api-scanner"}`）。旧管道使用 `pipeline=""`，因此现有的 Grafana 仪表板无需更改即可工作。 ### Fail2Ban 多流 每个流写入自己的 `threat_log` 文件。为每个文件创建一个 Fail2Ban 监狱： ``` # /etc/fail2ban/jail.d/arxsentinel-site1.conf [arxsentinel-site1] enabled = true filter = arxsentinel logpath = /var/log/arxsentinel/site1.threats.log maxretry = 1 bantime = 86400 [arxsentinel-site2] enabled = true filter = arxsentinel logpath = /var/log/arxsentinel/site2.threats.log maxretry = 1 bantime = 86400 ``` ### Grafana 仪表板包含一个 **Stream** 变量。选择一个或多个流来过滤所有面板。导入 `deploy/grafana/arxsentinel-dashboard.json`（v2）。 ## 日志管理 **操作日志**（`/var/log/arxsentinel/sentinel.log`）—— 守护进程的工作日志： ``` 2026-04-02 14:33:10 [STARTUP] arxsentinel v1.0.0 started 2026-04-02 14:33:12 [THREAT] 45.134.26.8 score=85 modules=probe,rate reason="..." 2026-04-02 14:38:10 [STATS] processed=14320 tracked=87 threats=3 suspicious=12 ``` 标签：`STARTUP`, `SHUTDOWN`, `CONFIG`, `THREAT`, `WHITELIST`, `STATS`, `GC`, `ERROR`, `WARN`。 调试标签（`PARSER`, `TAIL`, `DETECTOR`, `SCORER`）仅在 `logging.debug: true` 时可见。 **威胁日志**（`/var/log/arxsentinel/threats.log`）—— 由 Fail2Ban 读取： ``` 2026-04-02T14:33:12Z THREAT 45.134.26.8 score=85 modules=probe,rate reason="probe:/.env,rate:142rps" 2026-04-02T14:35:01Z WARN 92.63.104.12 score=55 modules=useragent reason="ua:Nuclei/3.1.0" ``` Fail2Ban failregex：`THREAT score=\d+`（文件 `deploy/fail2ban/filter.d/arxsentinel.conf`）。 **警告日志**（`chain_guard.warnings_log`）—— 基础设施配置错误警报： ``` 2026-05-20T12:34:56Z CHAIN_WARN cloudflare-ip-as-client ip=172.64.0.1 cidr=172.64.0.0/13 log=/var/log/nginx/access.log 2026-05-20T12:34:57Z CHAIN_WARN bogon-ip-as-client ip=10.0.0.1 cidr=10.0.0.0/8 log=/var/log/nginx/access.log ``` 警告与威胁不同：`CHAIN_WARN` 表示 ArxSentinel 无法可靠地识别 真正的攻击者 IP。修复底层基础设施问题（参见[链路守护](#chain-guard--detecting-broken-ip-extraction)） 警告就会停止。 ## 服务管理 ``` # 状态与日志 systemctl status arxsentinel journalctl -u arxsentinel -f # 重新加载配置无需重启 (SIGHUP) kill -HUP $(cat /var/run/arxsentinel.pid) # 或 systemctl kill -s HUP arxsentinel # 停止 (优雅 — 排空行缓冲区) systemctl stop arxsentinel # 通过 Fail2Ban 手动封禁/解封 fail2ban-client status arxsentinel fail2ban-client set arxsentinel unbanip 1.2.3.4 ``` **SIGHUP 时更新的内容：** 评分器（检测器 + 阈值）、白名单匹配器、调试/颜色标志、日志文件路径。 **不更新的内容：** 跟踪器（IP 状态）、DNS 缓存、TailReader（access.log 路径需要重启）。 ## 日志格式 ArxSentinel 支持三种日志格式模式：**combined**（默认 nginx）、**JSON**（无需重新编译）和适用于任意文本格式的**自定义正则表达式**。 有关完整的配置示例、字段映射和常见错误，请参阅 [README.log-formats.md](deploy/examples/README.log-formats.md)。 ## 反向代理和链路守护 有关在反向代理（HAProxy、Traefik、Caddy、nginx）后面部署的完整指南，包括 IP 提取配置和链路守护（损坏的 IP 链检测）。 参见 [`deploy/examples/reverse-proxy/README.md`](deploy/examples/reverse-proxy/README.md)。 ## CMS 特定配置 适用于最常见的 PHP 堆栈的现成 `probe.paths` 覆盖项位于 `deploy/examples/cms/`。将相关路径复制到您的 `config.yaml` 中： | 文件 | 目标 | |------|--------| | [`wordpress.yaml`](deploy/examples/cms/wordpress.yaml) | WordPress —— `wp-login.php`, `xmlrpc.php`, REST 用户枚举 | | [`laravel.yaml`](deploy/examples/cms/laravel.yaml) | Laravel —— `.env`, `/storage/`, `/vendor/`, Telescope, Horizon | | [`drupal.yaml`](deploy/examples/cms/drupal.yaml) | Drupal —— `/user/login`, `settings.php`, `update.php` | | [`joomla.yaml`](deploy/examples/cms/joomla.yaml) | Joomla —— `/administrator/`, `configuration.php` | | [`generic-php.yaml`](deploy/examples/cms/generic-php.yaml) | 自定义 PHP 应用 —— phpinfo, phpMyAdmin, Adminer, 备份文件 | **如何应用 CMS 配置：** 1. 打开 `deploy/examples/cms/.yaml` 并复制 `paths:` 列表。 2. 将其粘贴到您的 `config.yaml` 中的 `detectors.probe.paths:` 下。 3. 无需重启即可重新加载：`kill -HUP $(pgrep arxsentinel)` —— 或 `systemctl kill -s HUP arxsentinel`。 默认情况下，路径会**扩展**（而不是替换）内置的敏感路径列表。 若要仅使用您的自定义列表，请将 `detectors.probe.paths:` 设置为恰好您想要的路径。 ## Prometheus 指标 在 `config.yaml` 中启用指标，配置 Prometheus 抓取，设置 bcrypt 密码哈希，并导入 Grafana 仪表板。 完整指南：[`deploy/grafana/README.md`](deploy/grafana/README.md) ## 开发路线图 正在积极开发 v2.x 版本： - **执行器接口** —— 有状态、双向集成（对比 fire-and-forget 的 Sink）；带有请求/响应协议的持久化子进程 - **Cloudflare WAF 执行器** —— 通过 Cloudflare API 在边缘阻止 IP；无需 iptables，适用于 CDN 前置部署 - **AWS WAF 执行器** —— 为 AWS WAF 规则组更新 IP 集 ## 故障排除 **守护进程启动失败 —— 威胁日志错误：** 检查 `/var/log/arxsentinel/` 的权限 —— 该目录必须由 `arxsentinel` 用户拥有。 **Fail2Ban 未封禁 —— 检查日志格式：** ``` fail2ban-regex /var/log/arxsentinel/threats.log /etc/fail2ban/filter.d/arxsentinel.conf ``` **过多误报警告 —— 降低灵敏度：** 在配置中降低 `score` 或提高阈值（`threshold`, `ratio_threshold`），然后执行 `kill -HUP`。 **调试管道 —— 启用调试模式：** ``` logging: debug: true ``` 重启或执行 `kill -HUP`。操作日志将为每个请求显示 `[PARSER]`, `[DETECTOR]`, `[SCORER]` 行。 **内存使用过高：** 减少 `state.max_tracked_ips`（默认 100000；每个 IP 约 2.5 KB → 100k 约 250 MB）。 ## 第三方数据 **badbot** 检测器从 [nginx-ultimate-bad-bot-blocker](https://github.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker) 获取其黑名单，这是一个由 **[Mitchell Krog (@mitchellkrogza)](https://github.com/mitchellkrogza)** 及其贡献者创建和维护的杰出社区项目。该项目管理着约 685 个恶意 User-Agent 模式和约 7108 个恶意引荐词，几乎每天更新 —— 这是一项巨大的努力，惠及整个网络。 根据 [MIT](https://github.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/blob/master/LICENSE.md) 许可。这些列表在运行时下载，未与 ArxSentinel 捆绑。 衷心感谢 Mitchell Krog 和该项目的每一位贡献者 —— 您的奉献让互联网成为对所有人更安全的地方。

标签：AMSI绕过, Cloudflare集成, EVTX分析, exec执行, Fail2Ban集成, Go语言, HTTP安全, IP跟踪, JSON接口, 事件路由, 低资源占用, 单二进制, 可插拔架构, 威胁检测, 子域名突变, 安全事件管道, 安全评分系统, 无依赖运行, 日志审计, 机器人检测, 白名单管理, 程序破解, 自定义请求头, 自定义输出, 请求拦截, 调试插件, 轻量级部署, 速率限制