{
 "byKey": {
  "cover": [
   { "say": "大家好,歡迎回到 Linux A I 助理開發實戰。這一章的主題是 Docker 管理。我們要讓助理看得懂容器的狀態和日誌,但是在動手之前,一定要先搞清楚 Docker 的風險,並且守住預設唯讀這個原則。", "item": 0 }
  ],
  "Docker 風險模型與唯讀原則#1": [
   { "say": "好,這一章我們不急著寫程式,先從風險談起。", "item": 0 },
   { "say": "先講最重要的警告。能夠操作 Docker 的背景服務,幾乎就等於擁有這台主機的 root。因為這個服務是用 root 執行的,只要能對它下指令,就可以建立一個容器,把主機的根目錄掛進去,再用 root 的身分任意讀寫。", "item": 1 },
   { "say": "具體來說,第一,加入 docker 群組的使用者,實質上就等於 root,因為群組成員可以存取 docker 點 sock 這個檔案。所以不要為了方便,把助理的服務帳號加進 docker 群組,還覺得它只是個普通帳號。", "item": 2 },
   { "say": "第二,不要把 docker 點 sock 掛進不可信的容器。掛進去之後,那個容器就能操作整個 Docker,要逃出容器的隔離,只是一行指令的事。", "item": 3 },
   { "say": "第三,如果助理本身是用容器部署的,同樣不要輕易掛載 docker 點 sock。真的有需要,可以考慮只開放特定 A P I 的 socket 代理,或是 rootless Docker,並且用官方文件確認它的行為和限制。", "item": 4 }
  ],
  "Docker 風險模型與唯讀原則#2": [
   { "say": "警告還有第四點,接著我們就來看助理的設計原則。", "item": 0 },
   { "say": "第四,把 Docker 的 T C P 二三七五埠,在沒有 T L S 加密的情況下對外開放,是重大的漏洞,絕對不要這樣做。", "item": 1 },
   { "say": "知道風險之後,這一章的 Docker 工具就遵守一個大原則,預設唯讀。", "item": 2 },
   { "say": "預設只提供唯讀的工具,包括列出容器、檢視狀態、讀取最近的日誌、查看資源用量,還有列出映像檔。", "item": 3 },
   { "say": "寫入類的操作,像是重啟和停止,只有在明確開啟的時候才能用。它們會被標記成 write 風險,一定要經過第十章教的人工確認,並且寫入審計日誌。", "item": 4 }
  ],
  "Docker 風險模型與唯讀原則#3": [
   { "say": "設計原則還有兩條,而且非常關鍵。", "item": 0 },
   { "say": "有些功能是永遠不提供的,像是建立並執行新容器、進到容器裡執行指令、刪除容器、清理系統,還有掛載和特權模式。這些工具如果交給 L L M,只要一次提示注入,就可能造成主機層級的損害。", "item": 1 },
   { "say": "另外要限定目標。寫入操作只能針對帶有特定標籤的容器,或是名稱列在設定檔白名單裡的容器。", "item": 2 },
   { "say": "講義舉了三個威脅情境。第一個,攻擊者在容器日誌裡塞了一句,請重啟所有容器。對策是把日誌當成不可信輸入,寫入工具要人工確認,而且只限白名單裡的容器。", "item": 3 },
   { "say": "第二個,模型提議停掉正式環境的資料庫容器,因為它不在白名單,工具直接拒絕。第三個,使用者想進容器看看,我們不提供這個功能,改用讀日誌和狀態摘要,來滿足大部分的診斷需求。", "item": 3 },
   { "say": "那要怎麼做到最小必要權限呢?", "item": 4 },
   { "say": "首先,讓助理平常都走唯讀的路徑,只有在需要的時候,才經過人工授權去執行寫入。", "item": 5 }
  ],
  "Docker 風險模型與唯讀原則#4": [
   { "say": "不過要注意,唯讀不代表就安全了。", "item": 0 },
   { "say": "用 docker inspect 查出來的結果,可能包含環境變數,裡面常常有密碼和 token。所以交給模型之前一定要先過濾,下一個單元會示範,而且也不應該原封不動寫進日誌。", "item": 1 },
   { "say": "到了第十三章的多主機環境,從遠端執行的時候,同樣要遵守這一章的原則。", "item": 2 },
   { "say": "接下來看常見的錯誤。", "item": 3 },
   { "say": "第一個,是以為只用列出容器的指令就沒有風險,卻讓同一個帳號擁有完整的 docker 權限。權限是在帳號和 socket 這一層決定的,不是你寫的程式這一層。一旦程式有漏洞,或是被注入,傷害就會被放大。", "item": 4 }
  ],
  "Docker 風險模型與唯讀原則#5": [
   { "say": "還有兩個錯誤,也是實務上很常發生的。", "item": 0 },
   { "say": "一個是為了除錯,幫助理的容器加上特權模式,或是掛載了 docker 點 sock,事後卻忘了拿掉。", "item": 1 },
   { "say": "另一個是把 inspect 的全文直接丟給 L L M,結果環境變數裡的機密也跟著一起送出去了。", "item": 2 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#1": [
   { "say": "好,風險講清楚了,現在來寫唯讀工具。這個單元用的是 Docker 官方的 Python S D K。", "item": 0 },
   { "say": "先安裝和連線。這個套件的名稱就叫 docker,建議裝在專案的虛擬環境裡。連線之後可以先 ping 一下,確認連得上。如果出現權限錯誤,表示目前的使用者讀不到 docker 點 sock。這時候千萬不要把那個檔案的權限改成六六六,那等於把 root 權限開放給這台主機上的所有人。", "item": 1 },
   { "say": "接著實作三個唯讀工具,分別是列出容器、查看單一容器的精簡資訊,還有讀取最近的日誌。有幾個重點要說明。", "item": 2 },
   { "say": "第一,建立連線的時候設定十秒的逾時,免得 Docker 的背景服務卡住,助理也跟著卡死。", "item": 3 },
   { "say": "第二,查看容器資訊的工具,只回傳環境變數的名稱,不回傳它的值,避免機密外流。程式裡另外準備了一條敏感字的規則,可以用來做更細緻的遮罩。", "item": 4 },
   { "say": "第三,讀日誌只取最近的幾行,行數和總字元數都一定要限制。", "item": 5 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#2": [
   { "say": "我們繼續看其他的重點。", "item": 0 },
   { "say": "第四,日誌會用一對 container log 標籤包起來,呼應第十章講的不可信資料隔離。", "item": 1 },
   { "say": "再來是資源用量。S D K 可以取得一次資源快照,可是回傳的欄位結構會隨 Docker 版本不同而有差異,計算 C P U 百分比還需要前後兩次樣本的差值,比較繁瑣。", "item": 2 },
   { "say": "如果只是要給使用者一個快速的概覽,比較穩妥的做法是呼叫 docker 指令的 stats 功能,讓 Docker 自己算,這個下一個單元會看到。", "item": 2 },
   { "say": "工具寫好之後,要把它們註冊到第五章建立的工具註冊表,三個工具的風險等級都標成 read。這樣模型就能回答有哪些容器沒在跑、某個容器最近有什麼錯誤,卻沒辦法改動任何東西。", "item": 3 },
   { "say": "最後來看這個單元的常見錯誤。", "item": 4 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#3": [
   { "say": "常見的錯誤有三個。", "item": 0 },
   { "say": "第一個,是把使用者或模型輸入的容器名稱,直接拼進指令字串。S D K 是透過 A P I 呼叫,不會經過 shell,這是它的優點,不要為了省事又改回執行系統指令的寫法。", "item": 1 },
   { "say": "第二個,容器的日誌動不動就是幾十萬行,卻忘了限制讀取的行數。", "item": 2 },
   { "say": "第三個,是沒有接住 Docker 的例外。結果 Docker 沒啟動的時候,整個助理就跟著崩潰了。", "item": 3 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#4": [
   { "say": "我們用畫面把程式的重點看一遍。", "item": 0 },
   { "say": "最前面是一個取得連線的小函式,它依照環境設定連到 Docker,並且設定十秒逾時。", "item": 1 },
   { "say": "第一個工具是列出容器,說明文字寫得很清楚,列出容器的名稱、映像檔和狀態,而且是唯讀的。", "item": 2 },
   { "say": "它會把所有容器走過一遍,每個容器只留下名稱、短編號、映像檔和狀態這四項。", "item": 3 },
   { "say": "如果連不上 Docker,就把例外接住,回傳一筆無法連線的錯誤訊息,而不是讓程式當掉。", "item": 4 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#5": [
   { "say": "第二個工具,是精簡版的 inspect。", "item": 0 },
   { "say": "它的說明是,過濾掉環境變數,只保留診斷需要的欄位。", "item": 1 },
   { "say": "一開始先用名稱去找這個容器。", "item": 2 },
   { "say": "找不到的話,就回覆找不到這個容器。", "item": 3 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#6": [
   { "say": "繼續看這個工具後面的部分。", "item": 0 },
   { "say": "其他跟 Docker 有關的錯誤,只回傳錯誤的類型名稱。", "item": 1 },
   { "say": "容器找到之後,先取出它完整的屬性。", "item": 2 },
   { "say": "再從裡面拿出狀態的那一段。", "item": 3 },
   { "say": "最後只回傳挑選過的欄位,包括名稱、狀態、啟動時間、結束代碼、是不是因為記憶體不足被系統砍掉、重啟次數,還有連接埠。", "item": 4 }
  ],
  "使用 Docker SDK for Python 讀取容器資訊#7": [
   { "say": "這一張是這個工具的結尾,接著是第三個工具。", "item": 0 },
   { "say": "回傳內容的最後一項是環境變數,這裡把等號後面的值全部丟掉,只留下名稱。", "item": 1 },
   { "say": "第三個工具是讀取最近的日誌。說明文字提醒我們,日誌內容是不可信輸入,交給模型的時候要包上標記。它會把行數限制在一到兩百行之間,文字只留最後六千個字元,再用標籤包起來。", "item": 2 }
  ],
  "以 docker CLI 做安全封裝#1": [
   { "say": "接下來這個單元,我們改用 docker 的命令列工具,並且把它安全地包裝起來。", "item": 0 },
   { "say": "有了 S D K,為什麼還需要命令列呢?因為有些情境用命令列更單純。像是資源用量的格式化輸出、docker compose 專案的狀態,或是環境不方便安裝 Python 套件的時候。選用命令列,安全的重點就在於怎麼呼叫它。", "item": 1 },
   { "say": "封裝有六個原則,我們一個一個看。", "item": 2 },
   { "say": "第一,永遠用參數列表的方式呼叫,不要打開 shell 模式,也不要把字串拼成指令。這樣才能避免 shell 注入,例如有人在容器名稱裡夾帶分號或其他特殊符號。", "item": 3 },
   { "say": "第二,子命令要有白名單。只允許明確列出來的組合,例如列出容器、資源用量、日誌、映像檔和 inspect,其他一律拒絕。", "item": 4 }
  ],
  "以 docker CLI 做安全封裝#2": [
   { "say": "繼續看後面四個原則。", "item": 0 },
   { "say": "第三是參數驗證。容器名稱要用正規表示式來限制,Docker 容器名稱常見的字元,就是英文、數字、底線、點和連字號。", "item": 1 },
   { "say": "第四是逾時和輸出上限。執行的時候要設定逾時,輸出也要截斷。", "item": 2 },
   { "say": "第五是固定格式。優先使用兩個減號 format 這個選項,拿到結構化的輸出,比較好解析,也避免模型被一大堆雜訊干擾。", "item": 3 },
   { "say": "第六,要防範減號開頭的參數。容器名稱如果用減號開頭,可能被誤認成選項。所以驗證規則要求第一個字元一定是英文或數字,並且在適合的地方用兩個減號來分隔。實際的支援程度,請以 docker 的文件為準。", "item": 4 }
  ],
  "以 docker CLI 做安全封裝#3": [
   { "say": "那 S D K 和命令列,到底該怎麼選呢?", "item": 0 },
   { "say": "講義給了三個判斷的方向。", "item": 1 },
   { "say": "需要結構化的資料,或是比較細的錯誤類型,就用 S D K。", "item": 2 },
   { "say": "需要 Docker 自己算好的資源用量、compose 的資訊,或是想快速做個原型,就用命令列,但是一定要套用剛剛的封裝原則。", "item": 3 },
   { "say": "要記得,這兩種方式都需要存取 docker 點 sock,風險是一樣的,不會因為用命令列就比較安全。", "item": 4 },
   { "say": "最後是 Docker 不能用的時候怎麼辦。沒安裝、背景服務沒啟動,或是權限不足的時候,工具應該回覆清楚的訊息,例如告訴使用者 Docker 服務沒有啟動,可以用 system C T L 檢查狀態,不要讓模型自己猜。", "item": 5 }
  ],
  "以 docker CLI 做安全封裝#4": [
   { "say": "這個單元的常見錯誤有三個。", "item": 0 },
   { "say": "每一個都跟剛剛的原則互相呼應。", "item": 1 },
   { "say": "第一個,是打開 shell 模式,再把容器名稱直接拼進讀日誌的指令字串裡,這正好是最危險的寫法。", "item": 2 },
   { "say": "第二個,是白名單只比對字串的開頭。結果有人在允許的子命令後面,接上分號和刪除指令,也被放行了。請改用字典的方式,做完全相符的比對。", "item": 3 },
   { "say": "第三個,是忘了命令列的輸出可能帶有色彩碼或特殊字元。解析之前,記得先指定輸出格式。", "item": 4 }
  ],
  "以 docker CLI 做安全封裝#5": [
   { "say": "我們來看程式。重點是這一份允許清單,它是一個字典,每個子命令都對應一組寫死的參數。", "item": 0 },
   { "say": "第一組是列出所有容器,包含已經停止的,輸出固定成名稱、映像檔和狀態三個欄位。", "item": 1 },
   { "say": "第二組是資源用量,只取一次快照,不會持續刷新,輸出名稱、C P U 百分比和記憶體用量。", "item": 2 }
  ],
  "以 docker CLI 做安全封裝#6": [
   { "say": "繼續往下看。", "item": 0 },
   { "say": "第三組是列出映像檔,輸出映像檔的名稱、標籤和大小。", "item": 1 },
   { "say": "執行的函式一開始就先檢查,要求的子命令不在允許清單裡,就直接回覆不允許。", "item": 2 },
   { "say": "通過檢查,才用參數列表的方式執行,而且設定十五秒的逾時。", "item": 3 }
  ],
  "以 docker CLI 做安全封裝#7": [
   { "say": "最後是錯誤處理的部分。", "item": 0 },
   { "say": "如果系統裡根本找不到 docker 這個指令,就回覆找不到。", "item": 1 },
   { "say": "如果執行逾時,就回覆指令逾時。", "item": 2 },
   { "say": "如果指令的結束代碼不是零,就把錯誤訊息的前三百個字元回傳。一切正常的話,輸出也只留前六千個字元。另外,讀日誌的版本會先驗證容器名稱,並且把標準輸出和標準錯誤合併起來,因為容器的日誌是分成這兩邊輸出的。", "item": 3 }
  ],
  "受控的寫入操作與確認流程#1": [
   { "say": "好,最後一個單元,我們來談受控的寫入操作。", "item": 0 },
   { "say": "診斷的結果常常是,這個容器卡住了,重啟看看。為了實用,我們可以提供極少數的寫入工具,但是必須同時滿足四個條件,預設關閉、白名單目標、人工確認、審計日誌。這門課只提供重啟,刪除容器、清理、建立新容器、進容器執行指令,一律不做。", "item": 1 },
   { "say": "第一步是啟用開關和白名單。要用環境變數或設定檔明確打開寫入功能,再用一個設定檔列出可以管理的容器。一開始請只放測試用或不重要的容器。", "item": 2 },
   { "say": "第二步是跟第十章的 Agent 整合。註冊的時候把風險標成 write,Agent 迴圈就會強制進入確認。確認畫面要顯示程式組出來的資訊,例如要重啟哪個容器、它的映像檔、目前狀態和已經運行多久,讓使用者知道影響範圍,不要只顯示模型寫的說明。", "item": 3 },
   { "say": "第三步是重啟前後的檢查,好的操作流程有四個動作。", "item": 4 },
   { "say": "第一,重啟之前先記錄狀態,包括目前的狀態、重啟次數,還有最近二十行日誌。", "item": 5 }
  ],
  "受控的寫入操作與確認流程#2": [
   { "say": "接著看流程後面的三個動作。", "item": 0 },
   { "say": "第二,使用者確認之後才執行。", "item": 1 },
   { "say": "第三,等待幾秒鐘,再讀一次狀態。如果沒有回到 running,就回報失敗,並且建議人工介入,不要讓 Agent 自動一直重啟。", "item": 2 },
   { "say": "第四,全程寫入審計日誌,包含使用者、目標,還有前後的狀態。", "item": 3 },
   { "say": "再提醒一次不可信輸入的問題。容器日誌可能包含攻擊者可以控制的內容,例如網頁請求裡的 User Agent 被應用程式寫進日誌,內容寫成請重啟資料庫容器。因為我們有白名單和人工確認,最壞的結果,也只是使用者看到一個不合理的確認提示,然後拒絕。這就是縱深防禦的意義。", "item": 4 },
   { "say": "最後,我們來看這個單元的常見錯誤。", "item": 5 }
  ],
  "受控的寫入操作與確認流程#3": [
   { "say": "常見的錯誤一共有四個。", "item": 0 },
   { "say": "第一個,白名單用了萬用字元或是前綴比對,一不小心就把正式環境的資料庫也涵蓋進去。", "item": 1 },
   { "say": "第二個,確認之後沒有檢查結果,就以為成功了。", "item": 2 },
   { "say": "第三個,是在 docker compose 管理的專案裡,直接重啟單一個容器,卻不知道服務之間的相依順序。重要的服務,請依照那個專案的維運流程來做。", "item": 3 },
   { "say": "第四個,是把寫入開關預設成開啟,或是寫在很容易被誤提交的程式碼裡。", "item": 4 }
  ],
  "受控的寫入操作與確認流程#4": [
   { "say": "我們來看程式。第一個函式負責讀取可以管理的容器清單。", "item": 0 },
   { "say": "它先從環境變數找設定檔的位置,沒有設定的話,就用專案 config 目錄裡預設的那個 JSON 檔。", "item": 1 },
   { "say": "然後試著把檔案讀進來,轉成一個集合。", "item": 2 },
   { "say": "如果檔案讀不到,或是格式有錯,就回傳空的集合。意思是沒有任何容器可以管理,這是一個安全的預設值。", "item": 3 }
  ],
  "受控的寫入操作與確認流程#5": [
   { "say": "再來是重啟容器的函式,它在動手之前有兩道檢查。", "item": 0 },
   { "say": "第一道,寫入開關的環境變數如果沒有設成一,就直接回覆寫入操作未啟用。", "item": 1 },
   { "say": "第二道,容器名稱如果不在可以管理的清單裡,也直接拒絕。", "item": 2 },
   { "say": "兩道都通過,才真的去重啟容器,並且設定十秒的逾時。", "item": 3 }
  ],
  "受控的寫入操作與確認流程#6": [
   { "say": "重啟的過程一樣要處理錯誤。", "item": 0 },
   { "say": "找不到容器,就回覆找不到。", "item": 1 },
   { "say": "其他 Docker 的錯誤,就回覆重啟失敗,後面附上錯誤的類型名稱。", "item": 2 }
  ],
  "受控的寫入操作與確認流程#7": [
   { "say": "最後一行很單純。", "item": 0 },
   { "say": "全部順利的話,就回覆已經重啟這個容器。不過別忘了剛剛說的,重啟之後還要再檢查一次狀態,才算真的完成。", "item": 1 }
  ],
  "closing": [
   { "say": "這一章就到這裡。我們認識了 Docker 的風險模型,寫了唯讀的容器工具,學會安全地封裝命令列,也做出了受控的重啟流程。", "item": 0 },
   { "say": "請記得動手完成這一章的 Lab,再做章末小測驗,檢查自己學會了多少。我們下一章見!", "item": 1, "pause": 1 }
  ]
 }
}
