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 不會被當作已驗證的爬蟲。想關閉時,在設定的「分析」中選擇「不使用」。也可以選擇使用從右數起第一個不是可信中繼的位址,或最左邊的位址;這個值可以被用戶端改寫,所以只能在自己管理的可信中繼之後使用。從下一次診斷開始生效。