歡迎來到 Dependabot 的公共主頁。
Dependabot-Core 是 Dependabot 安全性/版本更新的核心函式庫。
使用它產生自動拉取請求,更新用 Ruby、JavaScript、Python、PHP、Dart、Elixir、Elm、Go、Rust、Java 和 .NET 編寫的專案的依賴項。它還可以更新 git 子模組、Docker 檔案和 Terraform 檔案。特點包括:
大多數人都熟悉在 GitHub.com 和 GitHub Enterprise 上運行的 Dependabot 服務。啟用它就像將dependabot.yml
設定檔簽入儲存庫的.github
目錄一樣簡單。
但是,如果您想運行 Dependabot 的自訂版本或在其他平台上運行它,您將不會被冷落。此儲存庫提供了託管您自己的獨立 Dependabot 所需的邏輯。目前,它支援針對 GitHub、Github Enterprise、Azure DevOps、GitLab、BitBucket 和 AWS CodeCommit 上託管的儲存庫開啟 Pull 請求。
Dependabot-Core 是一個函式庫,因此您需要某種入口點腳本。以下是一些幫助您入門的範例。
注意:如果您希望在本機上執行 Dependabot 以進行開發/偵錯,請參閱開髮指南。
dependentabot-script 儲存庫提供了用於配置 Dependabot-Core 庫的範例腳本集合。它旨在作為高級用戶在自己的專案中運行 Dependabot 自託管版本的起點。
注意:我們最近將 Dependabot Core 庫中使用的整體 docker 映像重構為每個生態系統一個映像。不幸的是,這破壞了 dependentabot-scripts,我們還沒有時間更新它們。我們已經意識到這個問題,並希望盡快提供解決方案。
Dependabot CLI 是一個較新的工具,最終可能會取代獨立用例的dependabot-script
。雖然它創建了依賴項差異,但目前缺少將這些差異轉化為實際 PR 的邏輯。儘管如此,對於尋找如何破解 Dependabot 範例的高級用戶來說,它可能會很有用。
在 GitHub 等 Dependabot 在容器中運行的環境中,如果您想根據 Dependabot 是否檢查來更改建置或安裝過程,您可以透過DEPENDABOT
環境變數的存在來確定。
想要向我們提供有關 Dependabot 的回饋或為其做出貢獻嗎?太好了 - 非常感謝!
大多數錯誤報告都應附有重現該問題的公共儲存庫的連結。無法使用 CLI 工具或空運行腳本在公共儲存庫上重現的錯誤報告可能會關閉為「無法重現」。
我們的問題追蹤器非常活躍,因此很可能有人已經提交了相同的問題。如果是這樣,請投票支持該問題,因為我們使用 ?對問題的反應作為衡量功能請求或錯誤影響的一個訊號。
但是,請不要留下對討論沒有任何新貢獻的評論。有關詳細信息,請參閱 https://github.com/golang/go/wiki/NoPlusOne。這是開源的,如果您看到想要修復的內容,我們很樂意透過貢獻拉取請求來引導您修復它。
問題追蹤器僅適用於與 Dependabot 更新邏輯相關的問題。有關安全警報或依賴關係圖的問題應作為代碼安全討論進行歸檔。
一個好的經驗法則是,如果您對 PR 中的差異有疑問,它就屬於這裡。
如果您認為在 Dependabot 中發現了安全漏洞,請查看我們的安全政策,以了解有關向 GitHub Bug Bounty 計劃披露這些漏洞的詳細信息,以便我們能夠在問題公開之前解決該問題。
想為 Dependabot 做出貢獻嗎?太好了 - 非常感謝!
貢獻工作流程:
請參閱貢獻指南以獲取更多資訊。
如果您有興趣為新的生態系統提供支持,請參閱貢獻指南以獲取更多資訊。
調試問題或編寫新功能的第一步是啟動開發環境。我們提供了一個基於 Docker 的自訂開發外殼,可以烘焙所有必要的依賴項。在大多數情況下,這是處理專案的最佳方式。
開發人員 shell 使用磁碟區掛載將本機變更合併到 Dependabot 原始碼中。這樣,您可以使用您喜歡的編輯器在本機上進行編輯,並且變更會立即反映在 Docker 容器中,以執行試運行或執行測試。注意:請參閱編輯本機套件管理器說明程式腳本的警告。
如果在本機找不到 Docker 映像,啟動開發人員 shell 的腳本將從頭開始建置它們。這可能需要一段時間。
透過提取您想要使用的生態系統的預先建構映像來跳過等待。鏡像名稱使用YAML生態系名稱來指定生態系。例如,對於 Go 模組,YAML 名稱為gomod
:
$ docker pull ghcr.io/dependabot/dependabot-updater-gomod
注意:預建鏡像目前僅適用於 AMD64 / Intel 架構。它們將在 ARM 上運行,但比手動建置 ARM 特定映像慢 2-3 倍。
接下來,執行開發人員 shell,使用該專案中生態系統的頂級目錄名稱指定所需的生態系統。例如,對於 Go Modules,頂級目錄名為go_modules
:
$ bin/docker-dev-shell go_modules
= > running docker development shell
[dependabot-core-dev] ~ $ cd go_modules && rspec spec # to run tests for a particular package
通常,快速入門就足夠了,但有時您需要重建底層映像。
例如,雖然我們尚未發布特定於 ARM 的映像,但如果您正在基於 ARM 的平台上工作,我們建議您手動建立映像,因為生成的容器運行速度要快得多。
開發人員 shell 在 Dependabot Development docker 映像中運行,該映像建構在生態系統映像之上。
流程圖LR
A["docker-dev-shell 腳本"] --> B("Dependabot 開發 docker 映像")
B --> C("Dependabot Updater Ecosystem docker 映像(特定於生態系統)")
C --> D("Dependabot Updater Core docker 映像")
對任何這些映像的 docker 檔案進行的變更都需要在本機上建置一個或多個映像,以便反映在開發 shell 中。
簡單但緩慢的方法是刪除任何現有映像,然後執行bin/docker-dev-shell
,它會自動建立遺失的映像。
更快的方法是拉取所有預先建置的鏡像,這些鏡像是您實際需要建置的鏡像的依賴項。要(重新)建構一個特定的:
更新程式核心映像:
$ docker pull ghcr.io/dependabot/dependabot-updater-core # OR
$ docker build -f Dockerfile.updater-core . # recommended on ARM
Updater 生態系鏡像:
$ docker pull ghcr.io/dependabot/dependabot-updater-gomod # OR
$ script/build go_modules # recommended on ARM
使用--rebuild
標誌的開發容器:
$ bin/docker-dev-shell go_modules --rebuild
一些 Dependabot 軟體包使用“本機助手”,即其宿主語言的小型可執行檔。
對這些文件的更改不會自動反映在開發容器內。
對幫助程式檔案進行任何編輯後,請執行適當的建置腳本以使用您的變更更新已安裝的版本,如下所示:
$ bin/docker-dev-shell bundler
= > running docker development shell
$ bundler/helpers/v2/build
$ bin/dry-run.rb bundler dependabot/demo --dir= " /ruby "
若要從本機套件管理器說明程式查看日誌和標準輸出,請參閱偵錯本機說明程式。
調試的第一步是讓開發環境運作。
在開發環境中,您有兩個選項來模擬依賴項更新作業:您可以使用新開發的 CLI 工具或原始的 Dry-run 腳本。
Dependabot CLI 是一個新開發的工具,它結合了 GitHub Credentials Proxy,可以更真實地模擬 Dependabot-at-GitHub 服務在與私人註冊表通訊時發生的情況。
它有專門的調試指南,包括支援放入 Ruby 調試器。
注意:在執行試運行腳本之前,您需要執行開發環境。
您可以使用bin/dry-run.rb
腳本來模擬依賴項更新作業,將產生的差異列印到終端。它需要兩個位置參數:套件管理器和 GitHub 儲存庫名稱(包括帳戶):
$ bin/docker-dev-shell go_modules
= > running docker development shell
$ bin/dry-run.rb go_modules rsc/quote
= > fetching dependency files
= > parsing dependency files
= > updating 2 dependencies
...
Dry-Run 腳本支援許多其他選項,所有這些選項都記錄在腳本原始碼的頂部。例如:
LOCAL_GITHUB_ACCESS_TOKEN="fake-GitHub-PAT"
允許指定 GitHub 個人存取權杖 (PAT) 以避免速率限制。--dir="path/to/subdir/containing/manifest
。--dep="dep-name-that-I-want-to-test"
允許指定單一 dep 來嘗試更新,而所有其他 dep 將被忽略。--cache=files
允許在本地緩解遠端 dep 文件,以便在測試本地邏輯更改時更快地重新運行。--updater-options=feature_flag_name
允許傳入功能標誌。這是如何將所有這些串在一起的範例
LOCAL_GITHUB_ACCESS_TOKEN=github_pat_123_fake_string
bin/dry-run.rb docker jeffwidman/secrets-store-driver
--dir " /manifest_staging/charts/secrets-store-provider "
--cache=files
--dep= " secrets-store "
--updater-options=kubernetes_updates
您可以在 ruby 程式碼中的任何位置新增debugger
語句,例如:
def latest_resolvable_version
debugger
latest_version_finder . latest_version
end
當您執行作業時,Ruby 偵錯器將會開啟。它應該看起來像這樣:
[ 11 , 20 ] in ~/ go_modules / lib / dependabot / go_modules / update_checker . rb
11 | module GoModules
12 | class UpdateChecker < Dependabot :: UpdateCheckers :: Base
13 | require_relative "update_checker/latest_version_finder"
14 |
15 | def latest_resolvable_version
=> 16 | debugger
17 | latest_version_finder . latest_version
18 | end
19 |
20 | # This is currently used to short-circuit latest_resolvable_version,
=> #0 Dependabot::GoModules::UpdateChecker#latest_resolvable_version at ~/go_modules/lib/dependabot/go_modules/update_checker.rb:16
#1 Dependabot::GoModules::UpdateChecker#latest_version at ~/go_modules/lib/dependabot/go_modules/update_checker.rb:24
# and 9 frames (use `bt' command for all frames)
( rdbg )
出現此提示時,您可以執行偵錯器命令進行導航,或輸入方法和變數以查看它們包含的內容。嘗試輸入dependency
以查看 Dependabot 目前正在處理哪些依賴項。
注意在偵錯器中,對原始程式碼所做的變更將不會被採納。您必須結束偵錯會話並重新啟動它。
當您偵錯問題時,通常需要查看這些在單獨進程中執行的腳本。
使用DEBUG_HELPERS=true
列印本機助理的所有日誌語句:
DEBUG_HELPERS=true bin/dry-run.rb bundler dependabot/demo --dir= " /ruby "
使用DEBUG_FUNCTION=<function name>
暫停執行以偵錯單一本機輔助函數。此函數會對應到本機幫助程式函數名稱,例如, bundler/helpers/v2/lib/functions.rb
中的函數之一。
執行此函數時,會插入debugger
,暫停bin/dry-run.rb
腳本的執行,這會將目前更新tmp
目錄保留在適當的位置,讓您cd
進入該目錄並直接執行本機幫助程式函數:
DEBUG_FUNCTION=parsed_gemfile bin/dry-run.rb bundler dependabot/demo --dir= " /ruby "
= > fetching dependency files
= > dumping fetched dependency files: ./dry-run/dependabot/demo/ruby
= > parsing dependency files
$ cd /home/dependabot/dependabot-core/tmp/dependabot_TEMP/ruby && echo " { " function " : " parsed_gemfile " , " args " :{ " gemfile_name " : " Gemfile " , " lockfile_name " : " Gemfile.lock " , " dir " : " /home/dependabot/dependabot-core/tmp/dependabot_TEMP/ruby " }} " | BUNDLER_VERSION=1.17.3 BUNDLE_GEMFILE=/opt/bundler/v1/Gemfile GEM_HOME=/opt/bundler/v1/.bundle bundle exec ruby /opt/bundler/v1/run.rb
複製並運行cd...
命令:
cd /home/dependabot/dependabot-core/tmp/dependabot_TEMP/ruby && echo " { " function " : " parsed_gemfile " , " args " :{ " gemfile_name " : " Gemfile " , " lockfile_name " : " Gemfile.lock " , " dir " : " /home/dependabot/dependabot-core/tmp/dependabot_TEMP/ruby " }} " | BUNDLER_VERSION=1.17.3 BUNDLE_GEMFILE=/opt/bundler/v1/Gemfile GEM_HOME=/opt/bundler/v1/.bundle bundle exec ruby /opt/bundler/v1/run.rb
這應該會註銷parsed_gemfile
函數的輸出:
{ "result" : [ { "name" : "business" , "requirement" : "~> 1.0.0" , "groups" : [ "default" ] , "source" : null , "type" : "runtime" } , { "name" : "uk_phone_numbers" , "requirement" : "~> 0.1.0" , "groups" : [ "default" ] , "source" : null , "type" : "runtime" } ] }
請記住,與 ruby 原始程式碼的變更不同,主機上對本機幫助程式原始程式碼的變更不會同步到開發容器。因此,您有兩種編輯本機助理的選擇:
vi /opt/bundler/v1/lib/functions/file_parser.rb
。然後重新運行cd...
命令。這是最快的調試方法,但任何更改都不會保存在容器外部。Dependabot-Core 中的大多數生態系統都支援ignore
允許使用者指定要從升級中排除的依賴項名稱或版本的條件。 GitHub 上的 Dependabot 服務文件更詳細地描述了該功能。
Dependabot CLI 支援將忽略條件作為作業定義的一部分傳遞。請參閱範例。
dry-run 腳本支援透過環境變數IGNORE_CONDITIONS
傳入一個或多個忽略條件:
IGNORE_CONDITIONS= ' [{"dependency-name":"*","update-types": ["version-update:semver-major"]}] '
bin/dry-run.rb docker test_org/test-dependabot `
Dependabot-Core 中的許多生態系統都支援安全性更新。這是一種特殊形式的版本更新,其中會傳入依賴項名稱和易受攻擊版本的範圍。這與嘗試更新到最新版本的正常版本更新形成對比。
環境變數SECURITY_ADVISORIES
允許將一個或多個安全警報通知傳遞給試運行腳本,以模擬安全更新:
SECURITY_ADVISORIES= ' [{"dependency-name":"buffer","patched-versions":[],"unaffected-versions":[],"affected-versions":["<= 2.0.0"]}] '
bin/dry-run.rb pub dart-lang/pub-dev --dir " /app " --cache=files --dep= " buffer "
內建支援利用 Visual Studio Code 在 Docker 容器內進行偵錯的功能。安裝建議的Dev Containers
擴充功能後,只需按Ctrl+Shift+P
(在 macOS 上為⇧⌘P
)並選擇Dev Containers: Reopen in Container
。您也可以透過點擊編輯器左下角的綠色按鈕來存取下拉清單。如果您的電腦上不存在開發 Docker 映像,它將自動建置。完成後,啟動Debug Dry Run
配置(F5)
,系統將提示您選擇套件管理器和儲存庫來執行試運行。請隨意在程式碼上放置斷點。
也支援透過執行Debug Tests
配置(F5)
來偵錯單一測試運行,系統將提示您選擇生態系統並提供 rspec 路徑。
Clone Repository ...
命令目前缺少某些功能,因此不受支援。您必須手動複製儲存庫並使用Reopen in Container
或Open Folder in Container...
命令。
一旦您獲得特定生態系統的開發環境,請透過在該生態系統的資料夾中執行rspec spec
來執行該生態系統的測試,例如
$ cd go_modules
$ rspec spec
您也可以將測試限制為僅您正在處理的文件,或僅測試先前失敗的測試,例如:
$ rspec spec/dependabot/file_updaters/elixir --only-failures
樣式由 RuboCop 強制執行。要檢查樣式違規,只需在每個包中運行rubocop
,例如
$ cd go_modules
$ rubocop
您可以透過在執行時間傳遞--profile
標誌來分析試運行,或使用:profile
標記rspec
測試。這將在tmp/
資料夾中產生stackprof-<datetime>.dump
文件,您可以透過執行以下命令來產生火焰圖:
stackprof --d3-flamegraph tmp/stackprof- < data or spec name > .dump > tmp/flamegraph.html
Dependabot-Core 是 Ruby 套件(gems)的集合,其中包含更新多種語言的依賴關係的邏輯。
dependabot-common
common
包包含所有通用/共享功能。例如,為不同支援的平台建立拉取請求的程式碼位於此處,處理 Git 依賴項的大多數邏輯也是如此(因為大多數語言都以一種或另一種方式支援 Git 依賴項)。也為實現對語言或套件管理器的支援所需的每個主要問題定義了基類。
dependabot-{package-manager}
Dependabot 支援的每種套件管理器或語言都有一個 gem。至少,這些 gem 中的每一個都將實現以下類別:
服務 | 描述 |
---|---|
FileFetcher | 取得專案的相關依賴檔案(例如Gemfile 和Gemfile.lock )。有關更多詳細信息,請參閱自述文件。 |
FileParser | 解析依賴項檔案並提取項目的依賴項清單。有關更多詳細信息,請參閱自述文件。 |
UpdateChecker | 檢查給定的依賴項是否是最新的。有關更多詳細信息,請參閱自述文件。 |
FileUpdater | 更新依賴項檔案以使用給定依賴項的最新版本。有關更多詳細信息,請參閱自述文件。 |
MetadataFinder | 尋找有關依賴項的元數據,例如其 GitHub URL。有關更多詳細信息,請參閱自述文件。 |
Version | 描述比較依賴版本的邏輯。有關範例,請參閱十六進位 Version 類別。 |
Requirement | 描述依賴關係要求的格式(例如>= 1.2.3 )。有關範例,請參閱十六進位要求類別。 |
進階流程如下所示:
dependabot-omnibus
這是一個“元”寶石,它完全依賴所有其他寶石。如果您想自動包含對所有語言的支持,您只需包含此 gem,即可獲得所需的一切。
對於許多生態系統,Dependabot-Core 支援私有註冊表。有時,這種情況是透過將私人註冊表憑證直接傳遞到本機套件管理器( npm
、 pip
、 bundler
等)來實現的,有時則發生在 Dependabot-Core Ruby 程式碼中。
序列圖
私有註冊表憑證->>Dependabot-Core:<br />
Dependabot-Core->>本機套件管理器:<br />
本機包管理器->>包註冊表:<br />
Dependabot-Core->>軟體包註冊表:<br />
雖然簡單明了,但這對於允許在清單檔案中運行不受信任的程式碼的生態系統來說是一個安全風險。例如setup.py
和.gemspec
允許執行本機 Python 和 Ruby 程式碼。如果依賴關係樹中的套件被駭客攻擊,攻擊者可以推送惡意清單,迫使本機套件管理器公開信用。
為了防止這種情況,對於 Github 運行的 Dependabot 服務,我們使用憑證代理包裝 Dependabot-Core,以便這些私有註冊表機密永遠不會暴露給 Dependabot-Core。
序列圖
Dependabot-Core->>憑證代理:所有請求均未經身份驗證
Credentials Proxy->>Package Registries:Creds 由代理人注入
注意 Dependabot-Core 左側:GitHub 運行的 Dependabot 服務<br />
包註冊表->>憑證代理:憑證被代理刪除
憑證代理->>Dependabot-Core:Dependabot-Core 永遠看不到私有註冊表憑證
這也意味著,如果 Dependabot-Core 有安全漏洞,這些信用資訊仍然不會面臨暴露的風險。
該項目可能包含項目、產品或服務的商標或標誌。 GitHub 商標或標誌的授權使用受制於且必須遵循 GitHub 標誌和使用。在此專案的修改版本中使用 GitHub 商標或標誌不得造成混淆或暗示 GitHub 贊助。任何對第三方商標或標誌的使用均須遵守這些第三方的政策。
Dependabot 和 dependentabot-core 最初是作為 Bump 和 Bump Core 誕生的,當時 @hmarr 和 @greysteil 在 GoCardless 工作。
Dependabot 於 2019 年成為 GitHub 的一部分!
透過執行Gems - Bump Version
工作流程並按照作業摘要中的說明進行操作,將新版本發佈到 RubyGems。
簡而言之,該過程將是:
v1.2.3
格式將合併提交標記為新版本。作業摘要包含一個預先填入了標題和標籤的正確版本的 URL。