cartography-cncf/cartography：README 來源編輯指南

Cartography：專案定位

cartography-cncf/cartography 的 README 將專案描述為「Cartography is a Python tool that pulls infrastructure assets and their relationships into a Neo4j graph database.」。本文只整理倉庫可直接核對的內容，不把 star、Fork 或宣傳語當成品質證明。README 在「README」下寫到：Cartography is a Python tool that pulls infrastructure assets and their relationships into a Neo4j graph database.。這說明的是專案邊界，不是已完成的生產驗證。 針對 cartography 的實際資料流，README 明確把 AWS、GCP、Azure、Kubernetes、GitHub、Okta、Entra ID 與 CrowdStrike 列為可連接平台，並指出還有三十多個平台。同步程序把基礎設施資產及其關係寫入 Neo4j，使用者再以 Cypher 查詢資產、身分、資料庫與網路暴露狀態。這個定位很適合需要跨雲端關係圖的盤點工作，但它不是資產本身，也不會替組織決定哪些權限應被撤銷。README 的 AWS 範例要求先配置 AWS_PROFILE、AWS_DEFAULT_REGION 或 ~/.aws/config，再以 cartography --neo4j-uri bolt://localhost:7687 --selected-modules aws 啟動同步。若改用 Docker 啟動 Neo4j，範例公開 7474 與 7687 埠，並以 NEO4J_AUTH=none 建立無驗證環境，這只能作為快速開始的測試條件。圖資料建立後，README 另提供 cartography-rules list、cartography-rules list object_storage_public 與 cartography-rules run object_storage_public，讓使用者檢查物件儲存公開暴露規則。正式環境若啟用 Neo4j 驗證，文件要求使用 NEO4J_PASSWORD 或規則文件列出的安全密碼選項。這些命令與設定鍵構成最小核對範圍，跨雲端權限是否被完整同步，仍要按各模組文件逐項確認。 另外，Cartography 的價值取決於圖中的關係是否能對應組織真正管理的帳號與資源。AWS 模組的 RDS、EC2、S3、IAM、EKS、Lambda、Secrets Manager、Security Hub 等節點若缺少必要權限，圖上呈現的結果就可能是不完整的子集；README 沒有承諾任何特定 IAM 策略都能成功抓取全部欄位。因此試跑時要分別核對 AWS 帳號、區域、模組選擇、Neo4j 節點數量，以及 Cypher 查詢回傳的資源識別碼。對暴露網際網路的 EC2，README 使用 exposed_internet:true 查詢；對未加密 RDS，則以 storage_encrypted:false 過濾。這兩個欄位是具體的觀察點，不能把查詢結果直接解讀成完整風險清單。規則命令同樣只在圖已被同步後才有意義，若資料源尚未完成，object_storage_public 的結果可能只是資料缺口。README 還提供資料結構與查詢教學連結，應以該結構核對標籤、關係名稱和同步時間。Neo4j 版本、Bolt 驅動與 Rust codec 的差異也會影響執行條件；README 稱 neo4j-rust 可讓同步時間減少約二至三成，這是 README 自述，不是本次實測數據。

Cartography：適用場景

從 README 的「README」與相關條目，可以先判斷它是否處理你的實際問題：Am I affected by any critical vulnerabilities or compromised software packages?。若需求不同，不應只因專案熱度就採用。本文保留原始專案名、命令與元件名，方便回到一手來源核對。 README 另外列出一項可核對的資訊：Which identities have access to which datastores? How about across multiple tenants, or providers?。這類原文條目可用來設計試跑步驟，但不能取代實際環境測試。 選型時還要區分資產盤點與即時監控。README 描述的是拉取資產及關係到 Neo4j 的工具，並沒有宣稱持續串流、即時告警或自動修復。資料更新週期、模組失敗時的重試和刪除舊節點方式，素材沒有說明，不能自行補成系統保證。 實際核對還應保存 Neo4j 查詢結果、Cartography 版本、selected-modules 參數與 AWS 設定檔來源。如此才能分辨空結果是環境沒有資產，還是模組沒有取得權限。跨租戶與跨雲端關係尤其需要確認節點命名和帳戶邊界，否則圖形看似完整，實際上可能混合了不同同步範圍。README 的問題清單可以協助設計查詢，但不能替代組織自己的資料分類和存取審查。

Cartography：運作方式

README 將運作方式分散在「Sync your first data source (AWS example)」等段落。可確認的線索包括：Ensure your AWS credentials and default region are configured (e.g. via AWSPROFILE, AWSDEFAULTREGION, or /.aws/config). See AWS credentials docs for reference.。本文不把未寫出的架構、效能或安全邊界補成結論；真正的執行鏈仍要配合目錄、設定檔與版本標籤檢查。 Neo4j 圖資料庫是 Cartography 的必要邊界，7474 網頁介面與 7687 Bolt 連線都應限制在測試網路。同步完成後先查詢 AWSAccount、AWSEC2Instance 與 AWSRDSInstance，再比較原始雲端清單，觀察資產識別碼、關係和加密欄位是否一致。 也要記錄同步前後的節點數與關係數，並把查詢結果和 0.140.0 版本分開保存，以便升級後比較。 另外可用同一條 Cypher 查詢重複執行，確認 AWSRDSInstance 的 storage_encrypted 欄位與 AWSEC2Instance 的 exposed_internet 欄位在同步後仍能被正確讀取，並將 Neo4j 連線錯誤和模組輸出一併保存。 測試記錄還應包含 AWS_PROFILE、AWS_DEFAULT_REGION、selected-modules 與 Neo4j 版本，這些值會直接影響圖中的資產範圍、查詢結果和規則判讀。 這些差異要在同一版本下比較，並檢查完整查詢輸出結果。完成好。

Cartography：安裝與第一次執行

第一次安裝應從 README 指出的入口開始。目前可核對的命令是：

pip install cartography

如果倉庫沒有命令，本文不會自行編造步驟，而是建議先閱讀「Install Cartography」，確認系統依賴、預設埠與首次初始化。

Cartography：設定與日常使用

日常使用取決於專案文件。README 的「Sync your first data source (AWS example)」段落提到：See the full install guide for other platforms.。設定檔、環境變數、權限與資料目錄只在來源明確時才會記錄；沒有寫出的預設值，應在測試環境驗證並保留回滾副本。 同一部分也提到：What are the network paths in and out of my environment?。

Cartography：README 能確認的限制

README 能確認的限制比宣傳頁更重要。現有來源沒有證明cartography-cncf/cartography具備固定相容矩陣、服務等級、效能基準或長期支援承諾。README 只明確寫到「See the querying tutorial for more use-cases.」。這些未知項應列入選型紀錄，不要改成肯定句。

Cartography：安全、隱私與授權

授權資訊來自倉庫資料與 LICENSE：目前 SPDX 標識為 Apache-2.0。這代表分發和修改要依授權處理，但不等於完成安全審查。憑證管理、網路暴露、日誌保存與第三方依賴若未在 README 說明，仍需逐項檢查。

Cartography：維護與升級觀察點

維護判斷只能引用可追溯訊號：預設分支為 master，快照記錄 3994 個 star、546 個 fork、108 個開放 issue。README 的「Run security rules」寫到：Once Cartography has populated the reachable Neo4j graph, list, inspect, and run security rules. This quickstart uses the no-auth Neo4j container started above, so no password is required:。這可用來安排升級複核，不能取代變更測試。 維護時也應對照 README 的「Run security rules」段落：For authenticated Neo4j, set NEO4JPASSWORD or use one of the other secure password options in the rules docs.。

編輯結論

編輯結論：cartography-cncf/cartography 是否適合採用，取決於 README 覆蓋的任務是否符合你的環境。本文適合做安裝前閱讀和核驗清單，不把倉庫統計包裝成親自試用報告。先在隔離環境試跑，再決定是否進入正式流程。 選型前也可回看 README 的「Who uses Cartography?」段落：If your organization uses Cartography, please file a PR and update this list. Say hi on Slack too!。 未明列的內容不應視為預設行為，先在隔離環境記錄版本、設定與輸出，再回到來源核對。

官方來源

1. Official documentation
2. Official README
3. Project repository
4. Release notes