AccessScope 操作手册

本手册介绍一款诊断工具的用法，它能从服务器的访问日志中找出攻击尝试，并附上作为依据的日志行。先说明在界面中诊断的步骤，用命令行的方法汇总在第 8 章。

1. 关于 AccessScope

AccessScope 是一款诊断工具，它读取 Web 服务器和 SSH 服务器本来就会留下的日志，查找其中的攻击尝试。找到的每一项都会附上作为依据的日志行。适合自己运营服务器、想确认日志里有没有可疑访问的用户。

它只读取日志。不会修改或删除日志，不会拦截通信，也不会提升权限。诊断本身既不使用 LLM，也不使用网络。

Mac 版包含在 RoamSwitch 的 DMG 中，Linux 版包含在 RoamSwitch 的 deb / rpm / tarball 中。它是与 RoamSwitch 分开的工具，许可证为 Apache License 2.0。启动时，在 Mac 上选择应用图标，在 Linux 上选择应用列表中的「AccessScope」。

保存的文件

AccessScope 会自动保存的有设置、找到的日志列表、排除规则，以及与上次比较用的记录。它们都放在 ~/.config/accessscope/ 下，权限设为只有本人可以读写。

更新

在 Mac 上，只有在设置的「更新」中按下「检查更新」时才会连接 lafine.net。不会发送本机和日志的信息，下载的文件会先验证签名再安装。Linux 没有应用内更新，请通过软件包更新来升级。

2. 第一次诊断

1. 选择日志。最简单的方法是「查找本机的日志」。它会自动查找 nginx、Apache、SSH 等日志，并列在「在本机找到的日志」中。知道日志位置时，可以用「选择文件」或「选择文件夹」来选择，也可以把文件或文件夹拖放到窗口上。
2. 选择「时段」。默认是「最近 7 天」，也可以改成「最近 24 小时」「最近 30 天」或「全部」。时段是从现在往前数的，想诊断较早的日志时请选「全部」。
3. 按下「开始诊断」。界面会显示「正在读取日志」「正在分析」的进度，结束后会打开结果。

3. 可读取的日志与查找位置

日志的类型会根据内容自动判别。用 gzip 压缩的已轮转日志也能直接读取。选择文件夹后，会一并读取其中看起来像日志的文件。

「查找本机的日志」会检查标准位置，以及 Web 服务器配置文件所指向的日志位置。列出来的只有已确认可作为日志读取的文件。

Docker 容器

勾选「同时检查 Docker 容器」后，本机的 Docker 日志也会成为诊断对象。诊断前，确认界面会显示将执行的命令和目标容器，只有在按下「同意并诊断」后才会读取。它只读取，不会提升权限。

用 LLM 查找日志(可选)

找不到日志时，也可以用「也用 LLM 查找」让 LLM 去找位置。传给它的只有正在运行的服务器名称、/var/log 等位置里的文件名这类环境信息，不会传文件内容。建议的位置会在确认可以读取之后，以未勾选的状态给出。设置请看第 7 章。

4. 如何查看结果

诊断结束后，可以在 4 个标签页中查看结果。

如何看检测

检测会以「SQL 注入尝试」这样的名称显示，并带有严重程度(高、中、低)和可信度。可信度表示仅凭日志能说到什么程度。

• 确认是仅凭日志就能断定的内容。
• 较可能是那次尝试很可能发生过的内容。
• 假设是仅凭日志无法确认的内容。

展开「依据的日志行」，就能原样看到该检测所依据的日志行。平时是收起的，请先读名称和理由，只展开你在意的那些。

综合风险(0 到 100)是按严重程度和可信度加权得出的参考值。它不会仅因数量多就变大，只要没有一条严重程度为高的检测，就不会变成「高」。它不是概率，请仅作为参考。

5. 减少需要查看的条数

排除规则

对于已知会出现的检测，比如本公司办公室的 IP、存活监控、本公司的漏洞扫描等，可以从报告中排除。被排除的检测不会被丢弃，而是连同理由一起保留数量。

1. 在「检测结果」标签页中，按下检测 IP 旁边的「排除此 IP…」。
2. 输入理由，按下「添加到排除规则」。理由会保留在报告中。
3. 在确认对话框中核对内容并批准。从下次诊断起生效。

设置里的「排除规则」会列出当前有效的规则。这里只用于显示，不能编辑。条件较细的规则，请写在设置文件夹里的文件(suppress.toml)中，写法见第 8 章。严重程度为「高」的检测即使被排除也不会被去掉，仍会保留在报告中。

与上次的比较

对同一组日志连续诊断时，会与上次的记录比较，给新出现的检测加上「新增」标记。在「检测结果」标签页勾选「仅新增」，就只显示新增的。第一次诊断时，全部都按新增处理。记录里只包含检测的指纹(哈希)、类型、严重程度、数量和时间，不包含日志的文字。

6. 导出结果

用结果界面上方的按钮可以把结果带出来。

在「导出…」中，屏蔽列表的格式可以选择 fail2ban-ip、nftables、ipset、nginx-deny、apache-require 和 csv。检测结果的列表可以导出为 CSV、SARIF 或 JSON。

屏蔽列表的「纳入条件」可以从「默认」「较严格」「较宽松」中选择，要导出的 IP 数量会在保存前显示。官方爬虫的 IP 和排除规则所涵盖的 IP 始终不会被纳入。

7. 用 LLM 分析(可选)

这是让 LLM 把诊断结果整理成文字的功能。默认处于关闭状态。要使用时，在设置的「LLM 联动」中勾选「启用 LLM 分析」，选择「使用的 LLM」，再按下「保存」。可选的是 claude、opencode、codex、agy 中本机已安装命令的那些。

发送的内容

• 不会发送原始日志。发送的是统计信息、检测的事实，以及每条检测最多 3 行作为依据的日志行(每行最多 300 个字符)。
• 密钥、令牌、密码等机密信息和邮件地址，在发送前会被遮蔽。
• IP 会以 203[.]0[.]113[.]9 这样经过无害化处理的形式传递。勾选「不发送真实 IP(使用化名)」后，会替换成 ip-001 这样的化名。

在「用 LLM 分析」标签页按下「显示将发送的完整内容」，就能看到要发送的全文。这个操作不会发送任何内容。按下「用 LLM 分析」时才会第一次发送。

• 日志的内容可以由攻击者来写。AccessScope 会把看起来像对 AI 下达指令的字符串作为检测报告出来，并把 LLM 的输出作为不可信的引用来显示。LLM 有时也会把检测解读得比实际更严重，所以请用作为依据的日志行来核实结论。
• 对于 claude 和 opencode，AccessScope 会在禁用其工具(执行命令和读取文件)的状态下启动它们。codex 和 agy 无法禁用工具，所以需要勾选设置中显示的确认项。在 root 下也能使用 LLM 分析,但 LLM 会以 root 权限运行,建议用无特权的用户运行(以 root 运行时,设置中会显示提示)。

8. 用命令行使用

在 Server Edition 这样只有命令行的环境，或想用 cron 定期运行时，请使用 accessscope 命令。它与界面使用相同的引擎，所以找到的检测也相同。

accessscope discover
accessscope scan --auto --since 7d --report report.md
accessscope scan /var/log/nginx/access.log /var/log/auth.log

用 cron 每天运行

accessscope scan --auto --since 24h --since-last --new-only --fail-on medium

只显示上次运行时没有的检测，只有当新增的检测为中或更高时，才会以退出码 3 结束。不带 --llm 的诊断，以 root 身份也能运行。

suppress.toml 的写法

排除规则写在 ~/.config/accessscope/suppress.toml 中。只要有这个文件，就会自动读取。

[[rule]]
reason  = "office"
ip      = ["203.0.113.0/28"]
expires = 2027-03-31

[[rule]]
reason      = "uptime monitor"
ua_prefix   = ["Mozilla/5.0 (compatible; UptimeRobot"]
path_prefix = ["/healthz"]

• 规则会作用于与所写的全部项目都一致的请求。reason 是必填项，会出现在所有报告中。超过 expires 的规则不会被应用。
• 严重程度为「高」的检测，除非规则里有 allow_high = true，否则不会被排除。
• User-Agent 和路径是客户端可以自己填写的值。不写 IP、只用它们指定的规则，无法排除攻击、认证、Web Shell 等检测。

9. 做不到的事

• 能看到的只有日志中留下的事实。请求的正文、响应的内容、应用程序的内部状态，以及因轮转而消失的时段，都无从得知。没有检测并不能证明安全。
• 检测的意思是「有过尝试」，并不是成功的证据。User-Agent 是自行声明的，可以伪造。
• 跨多个日志的关联链，只以地址相同这一事实为依据。在 NAT 或代理之后，毫不相干的人看起来也是同一个地址。内部地址（反向代理或 Docker 网关）代表许多客户端合在一起，因此不会纳入关联链。没有成功迹象的关联链，严重度为低。
• 「来自陌生来源的登录」是说对该日志而言陌生，并不一定是非法的。「与平时的差异」只表示发生了变化，并不一定是攻击。
• AWS ALB 和 CloudFront 的日志是用按 AWS 文档的定义制作的行来测试的，没有用真实的 AWS 输出测试过。

10. 遇到问题时

出现在「当前无法读取的日志」中

这是权限不足时的显示。AccessScope 不会提升权限去读取。请用下列任一方法处理。

• 文件类日志，请用有权限的用户启动，或者复制一份日志，用「选择文件」来选择。
• Linux 的 journald，请以 root，或 adm、systemd-journal、wheel 组的用户启动。
• macOS 统一日志，请以 admin 组的用户启动。

显示「在本机没有找到可以诊断的日志」

理由会以文字显示。例如会显示「没有 Web 服务器(Apache、nginx 等)的日志」。在 Mac 上，没有 SSH 记录时会显示「可能关闭了远程登录(SSH)」。可以用界面上显示的「选择文件」「用 LLM 查找」「指定其他位置」尝试下一步。查找了哪些地方，可以展开已收起的「详细的查找结果」来查看。

显示「无法读取 Docker 日志」

原因是下列之一，Docker 没有运行、找不到 Docker、没有权限，或者 Docker 返回了错误。没有权限时，请以能使用 Docker 的用户启动 AccessScope。AccessScope 不会提升权限重新读取，也不会要求或建议你加入 docker 组。因为 docker 组的权限等同于主机的 root。

显示「无法作为日志读取」

这是所选文件连一行都没能解析时的显示。该文件不会成为诊断对象，也不会被发送到任何地方。请确认它是否是支持的日志类型，然后重新选择。

无法按下「用 LLM 分析」

按钮附近会显示理由。显示「LLM 联动已关闭」时，请在设置中启用。显示「尚未选择 LLM」时，请在设置中选择。以 root 身份运行时，或者要使用的 LLM 命令没有安装在本机时，也无法使用。

访问来源全是代理的 IP

在反向代理或 CDN 之后的日志中，访问来源可能会变成代理的 IP。默认的「自动」只对记录的来源是内部地址（反向代理或 Docker 网关等）的行，从 X-Forwarded-For 确定客户端 IP。直接来自外部的行保持记录的来源不变。头部的值可以伪造，所以用这种方法确定的 IP 不会被当作已验证的爬虫。想关闭时，在设置的「分析」中选择「不使用」。也可以选择使用从右数起第一个不是可信中转的地址，或最左边的地址；这个值可以被客户端改写，所以请只在自己管理的可信中转之后使用。从下次诊断起生效。