PERSONALSOC · 最後更新:2026-10-28

PersonalSOC 操作手冊

本手冊介紹如何使用這款應用程式:只要按一下按鈕,即可以唯讀方式彙整本裝置的日誌與防護狀況,產生一目了然的報告。先依序說明畫面操作,命令列集中放在後面的章節。

1. 什麼是 PersonalSOC

PersonalSOC 是一款應用程式,會彙整本裝置的日誌與防護狀況,整理成檢出事項和報告。它面向沒有專職資安人員的個人,讓大家能有依據地了解自己的裝置上發生了什麼,並決定下一步該做什麼。

它是唯讀的,不會變更設定、刪除檔案或阻斷通訊。日誌分析由既不使用 LLM 也不使用網路的固定流程分析器完成。LLM 串接是選用的,初始為關閉。

不能做的事

2. 安裝與啟動

PersonalSOC 是與 RoamSwitch 分開的 App,包含在 RoamSwitch 的發行檔中。它有自己的圖示,RoamSwitch 選單中沒有入口,以 App 的形式單獨開啟。

環境安裝與開啟方式
MacRoamSwitch 的 DMG 中包含 PersonalSOC.app。將其移到「應用程式」資料夾,然後開啟「PersonalSOC」。支援 macOS 12 或更新版本。
Linux(用戶端版)它隨 RoamSwitch 的 deb、rpm、tarball 和 Arch 套件一起提供。在應用程式清單中開啟「PersonalSOC」,或在終端機中執行 personalsoc-app。畫面需要 WebKitGTK 4.1,deb 和 rpm 會自動安裝。在 Arch 中,請將 webkit2gtk-4.1 作為選用相依套件安裝。
Linux Server Edition只包含指令。在終端機執行 personalsoc(不含畫面應用程式 personalsoc-app)。伺服器版的維運請參閱維運手冊 (Linux Server)。
沒有 RoamSwitch 也能使用
PersonalSOC 也可單獨使用。在已安裝 RoamSwitch 的裝置上,它還會從 RoamSwitch 的 MCP(只使用唯讀工具)取得未解決的偵測和設定診斷結果等,與記錄檔中的發現一起彙整為一份報告。未安裝時,不使用該收集來源。

3. 第一次狀況檢查

只有在您按下「檢查狀態」時,才會讀取固定的收集來源。不想讓它讀取的收集來源,可以在設定中關閉。

操作步驟

  1. 開啟應用程式,按右上角的「設定」。
  2. 其下會列出在此作業系統上讀取的來源。如果有不想讓它讀取的,請取消勾選。
  3. 按「儲存」,再按「← 返回」回到首頁。
  4. 按「檢查狀況」。會出現進度列,完成後會顯示結果分頁。

完成後會顯示筆數,例如「檢查完成。檢出 3 筆 / IOC 2 筆」。分頁的查看方法見下一章。

環境讀取的內容
MacmacOS 統一日誌(最近 24 小時的 sudo 和 sshd)以及 MCP 設定(Claude Code、Claude Desktop、opencode、Cursor、Windsurf、Gemini CLI、VS Code、Cline、Roo Code)和 Claude Code 設定(~/.claude/settings.json 等)。也會讀取 Web 伺服器存取日誌(macOS 內建的 Apache、Homebrew 的 nginx 與 httpd)。Gatekeeper 拒絕的記錄讀取需要約 10 秒,因此初始為關閉。
Linux認證日誌(sshd)、auditd、Web 存取日誌(nginx / apache,包含依虛擬主機分開的日誌)、DNS 查詢日誌(dnsmasq / named)、MCP 設定(Claude Code、Claude Desktop、opencode、Cursor、Windsurf、Gemini CLI、VS Code、Cline、Roo Code)以及 Claude Code 設定(~/.claude/settings.json 等)。
共通如果裝有 RoamSwitch,則還有其 MCP(只使用只負責讀取的工具)。可透過「從 RoamSwitch 的 MCP(唯讀)取得偵測歷史與設定診斷」這個勾選項關閉。
隨附工具AccessScope 和 PathScope(如已安裝)的診斷摘要,以及在本裝置上執行的 RoamSwitch Sensor 發現的區域網路層威脅。用固定的參數執行固定的指令,只讀取摘要。參數無法更改。這些都可以在上面的來源清單中關閉。不存在時,該來源的備註中會註明。

4. 如何查看結果

分頁顯示的內容
儀表板透過圖表可以查看綜合風險(參考值)儀表、依嚴重程度統計的數量、依分類統計的發生數量、發生趨勢以及 MITRE ATT&CK 的數量。有相關資料時,概要框中還會顯示 RoamSwitch 防禦的涵蓋情況(目前在運作的比例與盲區)、隨附工具的診斷摘要,以及與上次檢查相比的變化。
報告彙整了收集來源、依類別劃分的發現和 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)。也可以透過「僅當出現上次沒有的偵測結果時才通知」來關閉通知。

定期執行以一般使用者權限運作,因此非 root 無法讀取的日誌(驗證、Web 伺服器、auditd)讀不到。有讀不到的日誌時,在第一次,以及讀不到的日誌組合改變時,會通知「N 個日誌無法讀取:名稱」。全部都讀得到時,不會通知。要確認這些日誌,請執行 sudo personalsoc scan。

用 personalsoc schedule status,可以確認定期執行是否已登錄、最後執行的時間,以及讀不到的日誌。設定畫面也會顯示相同內容。

在 Linux 上沒有 notify-send(Debian、Ubuntu 的套件為 libnotify-bin)時,不會顯示通知。

systemd 的使用者計時器在登出期間不會運作。在伺服器上,請執行一次 loginctl enable-linger。

取消勾選並儲存,註冊即被解除。

6. LLM 串接(選用)

LLM 串接是選用的,初始為關閉。啟用後,在狀況檢查之後,您選擇的 LLM 命令會進行追加調查,並以稽核員的身分撰寫報告。可使用的命令有 opencode、claude、codex 和 agy。

操作步驟

  1. 勾選「啟用 LLM 串接」。
  2. 選擇「使用的 LLM」。顯示「(未安裝)」的,表示此裝置上沒有該命令。
  3. 如有需要,可變更模型和逾時(秒)。模型留空時,將使用該 LLM 的預設值。
  4. 按「儲存」回到首頁,再按「檢查狀況」。檢查結束後,會接著執行 LLM 調查。

會交給 LLM 的內容

關於限制工具

使用無法限制工具的 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/ 中。

在 Mac 上,如果應用程式放在「應用程式」資料夾中,指令位於 /Applications/PersonalSOC.app/Contents/MacOS/personalsoc。若想用簡短名稱呼叫,請在終端機執行下列指令,之後只要輸入 personalsoc 即可。

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/PersonalSOC.app/Contents/MacOS/personalsoc /usr/local/bin/personalsoc
命令作用
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 scan --format <text|markdown|json|sarif>以機器可讀的格式輸出。json 和 sarif(SARIF 2.1.0)只在標準輸出上輸出結果。markdown 為 Markdown 報告。json 和 sarif 不能與 --report 或 --llm 同時使用。
personalsoc scan --fail-on <high|medium|low>只要有該嚴重程度以上的檢出,就以結束代碼 3 結束。加上 --fail-on-partial 後,存在無法讀取的來源時以結束代碼 4 結束(沒有檢出並不證明安全)。
personalsoc scan --since-last顯示與上次檢查的差異,並把本次的快照存入歷史。歷史只寫入 PersonalSOC 自己的位置(第 8 章)。
personalsoc scan --diff <file>
personalsoc scan --save-snapshot <file>
--diff 會與 --format json 的輸出或 --save-snapshot 寫出的檔案比對(不寫入任何內容,也不能與 --since-last 同時使用)。--save-snapshot 會把本次結果寫成 JSON 檔案(僅本人可讀寫的權限)。
personalsoc <type> <file>分析指定的檔案。type 為 sshd、auditd、web、dns、unified、mcp、agent、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。
以往檢查的快照(歷史)~/.local/state/personalsoc/history/snapshots.json(僅本人可讀寫的權限。只儲存檢出的種類、標題、對象、嚴重程度和數量,各防護功能的開關,MCP 伺服器的名稱,來源的狀態和綜合風險,不包含日誌行、依據、設定內容與機密。最多 60 次、每次 400 筆,2 MiB,超出時先刪除舊的,刪除該資料夾即可清除歷史。不會傳送到外部)

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 版操作手冊 →