PersonalSOC 操作手冊
本手冊介紹如何使用這款應用程式:只要按一下按鈕,即可以唯讀方式彙整本裝置的日誌與防護狀況,產生一目了然的報告。先依序說明畫面操作,命令列集中放在後面的章節。
1. 什麼是 PersonalSOC
PersonalSOC 是一款應用程式,會彙整本裝置的日誌與防護狀況,整理成檢出事項和報告。它面向沒有專職資安人員的個人,讓大家能有依據地了解自己的裝置上發生了什麼,並決定下一步該做什麼。
它是唯讀的,不會變更設定、刪除檔案或阻斷通訊。日誌分析由既不使用 LLM 也不使用網路的固定流程分析器完成。LLM 串接是選用的,初始為關閉。
不能做的事
- 它是為正在執行它的這一台裝置準備的工具,沒有同時查看多台裝置的功能。
- 它不會提升權限。只有 root 才能讀取的日誌會顯示為「無法讀取」,也不會使用 sudo。
- 「未檢出」並不等於安全的證明。綜合風險也只是 0 到 100 的參考值,不是機率。
- 它只讀取固定的來源。無法在畫面中指定要讀取的檔案或命令。
2. 安裝與啟動
PersonalSOC 是與 RoamSwitch 分開的 App,包含在 RoamSwitch 的發行檔中。它有自己的圖示,RoamSwitch 選單中沒有入口,以 App 的形式單獨開啟。
| 環境 | 安裝與開啟方式 |
|---|---|
| Mac | RoamSwitch 的 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)。 |
3. 第一次狀況檢查
只有在您按下「檢查狀態」時,才會讀取固定的收集來源。不想讓它讀取的收集來源,可以在設定中關閉。
操作步驟
- 開啟應用程式,按右上角的「設定」。
- 其下會列出在此作業系統上讀取的來源。如果有不想讓它讀取的,請取消勾選。
- 按「儲存」,再按「← 返回」回到首頁。
- 按「檢查狀況」。會出現進度列,完成後會顯示結果分頁。
完成後會顯示筆數,例如「檢查完成。檢出 3 筆 / IOC 2 筆」。分頁的查看方法見下一章。
| 環境 | 讀取的內容 |
|---|---|
| Mac | macOS 統一日誌(最近 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 的摘要,不含日誌的原始行。使用「複製」即可。 |
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。
操作步驟
- 勾選「啟用 LLM 串接」。
- 選擇「使用的 LLM」。顯示「(未安裝)」的,表示此裝置上沒有該命令。
- 如有需要,可變更模型和逾時(秒)。模型留空時,將使用該 LLM 的預設值。
- 按「儲存」回到首頁,再按「檢查狀況」。檢查結束後,會接著執行 LLM 調查。
會交給 LLM 的內容
- 傳遞的內容是偵測內容、作為依據的記錄行、MCP 回傳值以及收集來源的備註。當 LLM 提出要求時,還會傳遞處理程序的執行記錄和設定檔中相符行附近的內容(最多 200 個字元)。還會取得 PathScope 的封鎖點(最多 3 處,每處最多 80 個字元)、AccessScope 的偵測類型和數量、Sensor 的威脅摘要(最多 200 個字元)。所有內容都會遮蔽機密並限制字數。檔案本身、shell、AccessScope 的依據行和說明、Sensor 的 detail 不會傳遞。
- 交出之前,會把金鑰、權杖、密碼等機密內容遮蔽,並移除不可見字元。
- PersonalSOC 既不會把 shell 也不會把檔案交給 LLM。LLM 只能提出「想調查的事項」,由 PersonalSOC 執行其允許的唯讀工具並回傳結果。調查最多進行 6 輪。
- 不會信任 LLM 的輸出,在報告中將其作為引用處理。LLM 有時會把偵測解讀得過於嚴重,因此結論務必對照「檢出事項」確認。
- LLM 寫出的 IP 位址、網域、CVE 編號、雜湊值、PID 與行程名稱,會與交給它的資料(日誌內文、分析摘要、工具結果)核對。資料中任何地方都沒有的值,會列在報告的「收集的資料中沒有出現的值」,視為可能是捏造的。只比對字串,不詢問 LLM。報告末尾會把交給 LLM 的調查結果,依原樣作為附錄附上。
關於限制工具
- 在設定表格的「狀態」欄中,
opencode和claude會顯示「已限制其工具」。啟動 claude 時會停用其內建工具、MCP 伺服器和技能,也不載入使用者自己的設定。啟動 opencode 時會拒絕所有權限。 codex和agy無法用這種方法停用其工具,因此會顯示「無法限制其工具」。
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,也不會要求確認,所以使用 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 仍保持停用。 |