PERSONALSOC 0.1.14 · 最后更新:2026-10-17

PersonalSOC 操作手册

本手册介绍如何使用这款应用:只需点一下按钮,即可以只读方式汇总本设备的日志与防护状况,生成一目了然的报告。先按顺序说明界面操作,命令行集中放在后面的章节。

1. 什么是 PersonalSOC

PersonalSOC 是一款应用,会汇总本设备的日志与防护状况,整理成检出事项和报告。它面向没有专职安全人员的个人,让大家能有依据地了解自己的设备上发生了什么,并决定下一步该做什么。

它是只读的,不会更改设置、删除文件或阻断通信。日志分析由既不使用 LLM 也不使用网络的固定流程分析器完成。LLM 联动是可选的,初始为关闭。

不能做的事

它是为正在运行它的这一台设备准备的工具,没有同时查看多台设备的功能。
它不会提升权限。只有 root 才能读取的日志会显示为“无法读取”,也不会使用 sudo。
“未检出”并不等于安全的证明。综合风险也只是 0 到 100 的参考值,不是概率。
它只读取固定的来源。无法在界面中指定要读取的文件或命令。

2. 安装与启动

PersonalSOC 是与 RoamSwitch 分开的独立应用,拥有自己的图标,随 RoamSwitch 的发行包一起提供。RoamSwitch 的菜单里没有它的入口,需要作为独立应用打开。

环境	安装与打开方式
Mac	RoamSwitch 的 DMG 中包含 PersonalSOC.app。将它移到“应用程序”文件夹,然后打开“PersonalSOC”。需要 macOS 12 或更高版本。
Linux(客户端版)	它随 RoamSwitch 的 deb、rpm、tarball 和 AUR 软件包一起提供。在应用列表中打开“PersonalSOC”,或在终端中运行 `personalsoc-app`。界面需要 WebKitGTK 4.1,deb 和 rpm 会自动安装。在 AUR 中,请将 `webkit2gtk-4.1` 作为可选依赖安装。
Linux Server Edition	只包含命令。在终端中运行 `personalsoc`(不含界面应用 `personalsoc-app`)。服务器版的运维请参阅运维手册 (Linux Server)。

没有 RoamSwitch 也能使用

PersonalSOC 也可以单独使用。在装有 RoamSwitch 的设备上,它还会从 RoamSwitch 的只读 MCP 中获取未解决的检测和配置诊断结果等,与日志的检出事项一起汇总成一份报告。没有安装时,不会使用该来源。

3. 第一次状况检查

只有在您按下“检查状态”时，才会读取固定的收集源。不想让它读取的收集源，可以在设置中关闭。

操作步骤

打开应用,点击右上角的“设置”。
其下会列出在此操作系统上读取的来源。如果有不想让它读取的,请取消勾选。
点击“保存”,再点击“← 返回”回到主页。
点击“检查状况”。会出现进度条,完成后会显示结果标签页。

完成后会显示件数,例如“检查完成。检出 3 条 / IOC 2 条”。标签页的查看方法见下一章。

环境	读取的内容
Mac	macOS 统一日志(最近 24 小时的 sudo 和 sshd)以及 MCP 设置(Claude Code、Claude Desktop、opencode、Cursor)。也会读取 Web 服务器访问日志(macOS 自带的 Apache、Homebrew 的 nginx 和 httpd)。Gatekeeper 拒绝的记录读取需要约 10 秒,因此初始为关闭。
Linux	认证日志(sshd)、auditd、Web 访问日志(nginx / apache，包括按虚拟主机分开的日志)、DNS 查询日志(dnsmasq / named)以及 MCP 设置。
共通	如果装有 RoamSwitch,则还有其 MCP(只读)。可通过“从 RoamSwitch 的 MCP(只读)获取检测历史和配置诊断”这一勾选项关闭。

4. 如何查看结果

标签页	显示的内容
仪表板	通过图表可以查看综合风险(参考值)仪表、按严重程度统计的数量、按分类统计的发生数量、发生趋势以及 MITRE ATT&CK 的数量。
报告	这是汇总了来源、按分类的检出事项和 IOC 的 Markdown 报告。点击“复制 Markdown”可整份复制,点击“显示 Markdown 源码”可切换为原始文本。
发现事项	可以逐条查看检出结果,每条都带有严重程度、置信度、ATT&CK 编号、数量以及作为依据的日志行号。
来源	这是已检查内容的列表。状态为“已读取”“无对应项”“无法读取(权限)”“失败”“已禁用”之一,“无法读取”和“失败”的来源未能检查。
IOC	这是从日志中发现的 IP、域名、URL 和哈希的列表。为避免误点开,会以 198[.]51[.]100[.]7 这样的无害化写法显示。
供 LLM 使用的摘要输入	仅在 LLM 联动关闭时才会出现的标签页。这是供手动交给 LLM 的摘要,不含日志的原始行。使用“复制”即可。

关于综合风险的数字

综合风险是把每种检测按严重程度和置信度加权后相加得到的 0 到 100 的参考值。它不是概率,同一种检测出现多少次也不会增加。置信度分为“确定”“有力”“假设”三级。

5. 设置与定期运行

打开主页右上角的“设置”,内容按功能分为多个标签页。更改后点击“保存”,再点击“← 返回”回到主页。

显示语言 除“自动(跟随系统)”外,还可以选择日本語、English、Deutsch、Español、Français、Italiano、한국어、Português (Portugal)、简体中文、繁體中文。

定期运行(可选)

勾选“定期自动检查”并保存后,Mac 上会登记为 launchd 用户代理,Linux 上会登记为 systemd 用户定时器。间隔可在 15 分钟到 24 小时之间的 7 档中选择,初始为 1 小时。

运行的只有 personalsoc scan --notify,不使用 root。仅当出现上次没有的检测结果时才会通知,通知内容只有件数(Linux 上需要 notify-send)。也可以通过“仅当出现上次没有的检测结果时才通知”来关闭通知。

取消勾选并保存，注册即被解除。

6. LLM 联动(可选)

LLM 联动是可选的,初始为关闭。启用后,在状况检查之后,您选择的 LLM 命令会进行追加调查,并以审计员的身份撰写报告。可使用的命令有 opencode、claude、codex 和 agy。

操作步骤

勾选“启用 LLM 联动”。
选择“使用的 LLM”。显示“(未安装)”的,表示此设备上没有该命令。
如有需要,可更改模型和超时(秒)。模型留空时,将使用该 LLM 的默认值。
点击“保存”回到主页,再点击“检查状况”。检查结束后,会接着运行 LLM 调查。

会交给 LLM 的内容

交给 LLM 的有检出内容、作为依据的日志行、MCP 返回值中的字符串以及来源的备注。为了准确调查情况,会交出这些内容。
交出之前,会把密钥、令牌、密码等机密内容打码,并去除不可见字符。
PersonalSOC 既不会把 shell 也不会把文件交给 LLM。LLM 只能提出“想调查的事项”,由 PersonalSOC 运行其允许的只读工具并返回结果。调查最多进行 6 轮。
不会信任 LLM 的输出,在报告中将其作为引用处理。LLM 有时会把检测解读得过于严重,因此结论务必对照“检出事项”确认。

关于限制工具

在设置的表格“状态”一栏中,opencode 和 claude 会显示“已限制其工具”。启动 claude 时会停用其内置工具、MCP 服务器和技能,也不加载用户自己的设置。启动 opencode 时会拒绝所有权限。
codex 和 agy 无法用这种方法停用其工具,因此会显示“无法限制其工具”。

使用无法限制工具的 LLM 时

调查期间,LLM 可能自行判断读取文件,读取的内容会发送到该 LLM 的服务。要使用它,需要勾选“使用的 LLM”下方的确认项。确认按每个 LLM 分别进行,没有勾选则既无法保存也无法执行调查。

与 Zero Telemetry 的关系

RoamSwitch 的“Zero Telemetry”(不向外部发送通信内容和日志)是针对 RoamSwitch 本体的说明。启用 PersonalSOC 的 LLM 联动后产生的通信不包含在内。发送目的地和处理方式遵循所选 LLM 及其提供方的条款。只要保持 LLM 联动关闭,PersonalSOC 就不会把日志内容发送到设备之外。

7. 使用命令行

命令是 personalsoc。在 Linux 上位于 /usr/bin/personalsoc,在 Mac 上位于 PersonalSOC.app/Contents/MacOS/ 中。

命令	作用
`personalsoc scan`	自动检查本机的日志和 RoamSwitch（MCP），并以列表显示检测结果。只有 root 才能读取的日志（认证、Web 服务器、auditd），请加上 `sudo` 运行。
`personalsoc scan --report`	显示 Markdown 报告(不使用 LLM)。
`personalsoc scan --llm <name>`	显示 LLM 使用只读工具调查后、以审计员身份撰写的报告。`name` 为 opencode、claude、codex、agy 等。
`personalsoc scan --notify`	仅当出现上次没有的检测结果时才通知。这是定期运行所调用的形式。
`personalsoc <type> <file>`	分析指定的文件。`type` 为 sshd、auditd、web、dns、unified、mcp、inject、ioc 之一。将 `file` 指定为 `-` 时读取标准输入,也可以加上 `--report`、`--brief`、`--llm`。
`--lang <lang>`	可附加在任何命令上,指定显示语言,优先于设置。代码为 ja、en、de、es、fr、it、ko、pt-PT、zh-Hans、zh-Hant。

命令行中的 LLM

在命令行中,带上 --llm 运行本身就是把内容交给 LLM 的明确操作,因此即使设置中的“启用 LLM 联动”处于关闭状态也会运行。对于无法限制工具的 LLM,也不会要求确认,因此使用 codex 或 agy 时,请在了解调查期间文件可能被读取并发送的前提下使用。

8. 保存位置与更新

会保存的内容

项目	位置
设置	`~/.config/personalsoc/settings.json`(以仅本人可读写的权限保存)
上次检出的记录(用于判断是否通知)	`~/.local/state/personalsoc/last.json`(只保存相当于检出指纹的哈希,不保留日志文本)
定期运行的登记	Mac 上为 `~/Library/LaunchAgents/dev.personalsoc.scan.plist`(输出写入 `~/Library/Logs/personalsoc-scan.log`)。Linux 上为 `~/.config/systemd/user/` 中的 `personalsoc-scan.timer` 和 `personalsoc-scan.service`。

PersonalSOC 不会把报告或收集到的日志保存为文件。想留存时,请使用界面中的“复制 Markdown”或命令行的输出。想增加 LLM 时,需手动编辑设置文件中的 profiles,无法在界面中更改。

更新

Mac 上通过设置中的“更新”进行更新。仅在点击“检查更新”时才会连接 lafine.net,接收最新版本的信息(公开的 JSON)。不会发送本设备或日志的任何信息。如果有新版本,点击“下载并安装”。下载的文件会用内置于应用中的公钥验证签名,验证失败则不会安装任何内容。完成后应用会重新启动。

在 Mac 上,更新 RoamSwitch 本体并不会更新 PersonalSOC。Linux 上没有更新功能,PersonalSOC 包含在 RoamSwitch 软件包的更新中。

9. 遇到问题时

症状	原因与处理
某个来源显示“无法读取(权限)”	认证日志、Web 服务器日志和 auditd 日志，没有管理员权限就无法读取。PersonalSOC 不会自行提升权限，请加上 `sudo` 运行。这与“没有检测到”是不同的状态：该日志尚未检查。
无法保存定期运行	在 Mac 上如果提示应用正从隔离的临时位置运行,请把 PersonalSOC.app 移到“应用程序”文件夹,重新打开后再保存一次。如果提示找不到 personalsoc 命令,则需要把 `personalsoc` 放在与应用本体相同的位置。
claude 的调查因“Not logged in”而失败	PersonalSOC 启动 claude 时不会加载用户自己的设置(如 `~/.claude/settings.json` 中的 env 和 apiKeyHelper 等)。通过代理、Bedrock、Vertex 等依赖这些设置进行认证的配置会因此失败。在设置文件中手动加入 `"llm_user_settings": ["claude"]` 后,启动 claude 时会加载用户的设置。工具和 MCP 仍保持停用。

← PersonalSOC 产品页面前往 Mac 版操作手册 →