用 cscli explain 逐阶段看懂 CrowdSec 日志处理

原页未列个人署名。本文译自 CrowdSec 官方文档 Understand logs processing，由未完纪翻译、整理并补充安全说明。

一条日志为什么没有被 CrowdSec 识别？字段到底在哪个阶段产生？它又能进入哪些检测场景？cscli explain 把这些问题拆成一条可阅读的处理路径。它依赖本机正常工作的 CrowdSec 环境，以及已经安装的解析器与场景；在另一台机器上执行，结果可能不同。

未完纪原创技术示意图，依据 CrowdSec 官方文档绘制。图中“进入场景”不代表已经触发告警或封禁。

把一行日志或一个日志文件交给 explain

可以指定文件、直接传入一行日志，或使用数据源名称（DSN）。--type 用来说明输入类型，下面分别以 Nginx 和 syslog 为例：

cscli explain --file ./myfile.log --type nginx
cscli explain --log 'Sep 19 18:33:22 scw-d95986 sshd[24347]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost=192.168.1.1' --type syslog
cscli explain --dsn "file://myfile.log" --type nginx

官方未版本化指南记载，可以在类 Unix 环境中用 cscli explain --file /dev/fd/0 --type nginx 引用标准输入；同日保存的版本化 CLI 参考则示范 tail -n 5 myfile.log | cscli explain --type nginx -f -。链接到的当前 CrowdSec 主线实现会先把 -f - 管道内容暂存到临时文件，处理后默认清理。不同版本和运行环境的输入方式可能有差异；本文未运行命令，请按目标安装版本的官方参考确认。

编辑安全说明：上面的固定 syslog 示例改用了 shell 单引号。对于真实、不可信的日志，优先通过样本文件或标准输入传入，不要把日志内容拼成待执行的 shell 命令。输出可能包含 IP、账户、请求路径或其他敏感字段，分享前应脱敏。先截取少量有代表性的行；不宜把大型历史日志直接送入用于排查的 explain，以免内存占用过高。

读懂默认输出

下面保留原文的一份历史示例输出。它说明输出结构，不是本次执行记录；IP 占位符来自原文的脱敏展示。

▶ sudo cscli explain --file ./x.log --type nginx
line: xx.xx.xx.xx - - [05/Nov/2017:07:23:41 +0100] "GET /Og9vl1%0d%2019s58%3Atest HTTP/1.1" 404 136 "-" "Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko" "-"
    ├ s00-raw
    |   ├ 🟢 crowdsecurity/non-syslog (first_parser)
    |   └ 🔴 crowdsecurity/syslog-logs
    ├ s01-parse
    |   └ 🟢 crowdsecurity/nginx-logs (+22 ~2)
    ├ s02-enrich
    |   ├ 🟢 crowdsecurity/dateparse-enrich (+1 ~1)
    |   ├ 🟢 crowdsecurity/geoip-enrich (+12)
    |   ├ 🟢 crowdsecurity/http-logs (+7)
    |   └ 🟢 crowdsecurity/whitelists (unchanged)
    ├-------- parser success 🟢
    ├ Scenarios
        ├ 🟢 crowdsecurity/http-crawl-non_statics
        └ 🟢 crowdsecurity/http-probing

每一行都表示某个解析器是否以及如何处理了这条事件。+ 表示新增字段数，~ 表示修改字段数，- 表示删除字段数。unchanged 表示该解析器没有改变事件；这本身不等于整个处理链失败。[whitelisted] 则表示事件命中了白名单。

开始处理。最上方的 line: 是输入日志。
进入 s00-raw。先判断原始格式。此例显示 crowdsecurity/non-syslog 成功，而 crowdsecurity/syslog-logs 未成功。具有 onsuccess: next_stage 行为的成功解析器可以把事件推进下一阶段。编辑校正：原文这一步的叙述把成功者写成 syslog-logs，与其上方输出矛盾；这里按展示输出说明。
进入 s01-parse。该输入不适用于 Apache 或 MySQL 日志解析器，而是由 Nginx 解析器成功解析，然后通过 onsuccess: next_stage 进入事件增强阶段。
进入 s02-enrich。dateparse-enrich 解析时间戳，使场景能处理历史“冷日志”；geoip-enrich 根据提取出的 IP 补充地理信息；http-logs 继续处理通用 HTTP 信息，例如标记静态资源、拆分 URI。白名单解析器负责筛选包括本地 IP 在内的白名单事件；这一份默认输出没有显示命中。
列出可进入的场景。http-crawl-non_statics 接收面向非静态资源的 HTTP 请求；http-probing 也匹配，因为该请求访问非静态资源且返回 4XX。

这里的场景列表只回答“该事件能否进入场景”，不追踪场景桶是否溢出（overflow）。因此它不是某个阈值已经触发、已生成告警或已经实施处置的证据。需要分析完整历史检测行为时，可另读官方的 Replay Mode 文档；不要把 explain 的单行解析结果当作完整重放。

用详细模式找到字段变化的来源

排查解析器时，加上 --verbose 或 -v。每次对事件的修改都会显示在对应解析器下面。以下仍是原文历史输出，配置路径、样本路径与字段内容只用于解释：

▶ ./cscli -c dev.yaml explain --file /tmp/xx --type nginx --verbose
line: 10.42.42.42 - - [23/Oct/2017:10:46:06 +0200] "GET /admin/2019p1mnsa8q1ktU HTTP/1.1" 404 136 "-" "Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko (Wallarm DirBuster)" "-"
    ├ s00-raw
    |   ├ 🟢 crowdsecurity/non-syslog (first_parser)
    |   └ 🔴 crowdsecurity/syslog-logs
    ├ s01-parse
    |   └ 🟢 crowdsecurity/nginx-logs (+22 ~2)
    |       └ update Stage : s01-parse -> s02-enrich
    |       └ create Parsed.body_bytes_sent : 136
    |       └ create Parsed.http_referer : -
    |       └ create Parsed.http_user_agent : Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko (Wallarm DirBuster)
    |       └ create Parsed.status : 404
    |       └ create Parsed.target_fqdn :
    |       └ create Parsed.proxy_alternative_upstream_name :
    |       └ create Parsed.request_time :
    |       └ create Parsed.time_local : 23/Oct/2017:10:46:06 +0200
    |       └ create Parsed.proxy_upstream_name :
    |       └ create Parsed.remote_user : -
    |       └ create Parsed.request : /admin/2019p1mnsa8q1ktU
    |       └ create Parsed.http_version : 1.1
    |       └ create Parsed.remote_addr : 10.42.42.42
    |       └ create Parsed.request_length :
    |       └ create Parsed.verb : GET
    |       └ update StrTime :  -> 23/Oct/2017:10:46:06 +0200
    |       └ create Meta.http_user_agent : Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; rv:11.0) like Gecko (Wallarm DirBuster)
    |       └ create Meta.service : http
    |       └ create Meta.source_ip : 10.42.42.42
    |       └ create Meta.http_verb : GET
    |       └ create Meta.log_type : http_access-log
    |       └ create Meta.http_path : /admin/2019p1mnsa8q1ktU
    |       └ create Meta.http_status : 404
    ├ s02-enrich
    |   ├ 🟢 crowdsecurity/dateparse-enrich (+1 ~1)
    |   |   ├ create Enriched.MarshaledTime : 2017-10-23T10:46:06+02:00

这一层视图能区分“原始字段提取错了”和“下游元数据生成错了”。例如先检查 Parsed.remote_addr 是否正确，再检查 Meta.source_ip；先检查 Parsed.time_local 和 StrTime，再检查标准化后的 Enriched.MarshaledTime。如果一个字段始终为空，就回到创建它的解析器检查输入格式与过滤条件。