theHarvester 貢獻(xiàn)與安全指南從開發(fā)環(huán)境搭建到漏洞披露的完整工作流【免費(fèi)下載鏈接】theHarvesterE-mails, subdomains and names Harvester - OSINT項(xiàng)目地址: https://gitcode.com/GitHub_Trending/th/theHarvester導(dǎo)讀本文以 theHarvester 倉庫的官方協(xié)作文檔 docs/wiki/Contributing-and-Security.md 為核心骨架系統(tǒng)整理貢獻(xiàn)者從搭建開發(fā)環(huán)境、提交聚焦變更、安全測試到開啟 Pull Request 的完整流程并串聯(lián)倉庫內(nèi) CONTRIBUTING.md、SECURITY.md 以及 docs/wiki/How-to-add-a-new-module.md 的細(xì)節(jié)同時(shí)結(jié)合pyproject.toml、tests/conftest.py等源碼與測試文件進(jìn)行印證。讀完本文你將掌握 theHarvester 的貢獻(xiàn)規(guī)范、無網(wǎng)絡(luò)測試策略、provider-contract 覆蓋門禁機(jī)制以及發(fā)現(xiàn)安全漏洞后應(yīng)遵循的私密披露流程能夠安全、合規(guī)地參與到這個(gè) OSINT 開源項(xiàng)目中。一、協(xié)作文檔速覽權(quán)威指引在哪里theHarvester 的 wiki 協(xié)作頁本身非常精簡它是一份導(dǎo)航原則文檔Canonical repository guidance lives with the code權(quán)威倉庫指引與代碼共存即項(xiàng)目不把貢獻(xiàn)規(guī)范復(fù)制到 wiki而是將權(quán)威版本與代碼放在一起維護(hù)避免文檔漂移。其指向的權(quán)威文件包括CONTRIBUTING.md開發(fā)環(huán)境搭建、聚焦變更、安全測試與 Pull Request 規(guī)范SECURITY.md漏洞私密上報(bào)的指引與范圍界定GitHub Issues可復(fù)現(xiàn)的 Bug 與聚焦的功能請求需移除憑據(jù)、賬戶信息、私有目標(biāo)數(shù)據(jù)與原始 API 響應(yīng)。此外wiki 頁明確了兩條紅線不得在公開 Issue 或 wiki 頁面披露疑似漏洞、憑據(jù)、私有目標(biāo)數(shù)據(jù)或利用細(xì)節(jié)若必須聯(lián)系維護(hù)者獲取私密上報(bào)渠道請遵循 SECURITY.md且不要附帶任何漏洞細(xì)節(jié)。同時(shí)wiki 頁提示如果你要新增一個(gè) discovery provider發(fā)現(xiàn)源適配器還應(yīng)閱讀 How to add a new discovery module下文第四節(jié)會結(jié)合該文檔深入展開。關(guān)鍵事實(shí)來自 docs/wiki/Contributing-and-Security.md 第 3 行項(xiàng)目明確權(quán)威倉庫指引與代碼共存這解釋了為何 wiki 頁只做導(dǎo)航、規(guī)范細(xì)節(jié)全部沉淀在根目錄文檔中。二、開始之前貢獻(xiàn)前的準(zhǔn)備工作CONTRIBUTING.md 的 Before you start 章節(jié)給出了提交貢獻(xiàn)前的四條紀(jì)律先檢索搜索現(xiàn)有的 issues 與 pull requests避免重復(fù)勞動先開 Issue在投入開發(fā)大型功能、依賴變更或用戶可見行為變更之前先打開一個(gè) Issue 說明意圖單 PR 單一邏輯變更每個(gè) Pull Request 只包含一個(gè)邏輯變更無關(guān)的清理與格式化改動請另開 PR基于dev分支貢獻(xiàn)分支應(yīng)以當(dāng)前上游dev分支為基線。對于 Bug 報(bào)告必須包含最小復(fù)現(xiàn)、預(yù)期與實(shí)際行為、操作系統(tǒng)、Python 版本以及僅用于診斷所必需的輸出同時(shí)移除憑據(jù)、賬戶信息、私有目標(biāo)數(shù)據(jù)與原始 API 響應(yīng)——這一點(diǎn)在整份文檔中被反復(fù)強(qiáng)調(diào)是 theHarvester 貢獻(xiàn)文化的核心安全要求。為什么是dev分支從項(xiàng)目結(jié)構(gòu)可以推斷theHarvester 采用主干穩(wěn)定、開發(fā)分支匯聚的發(fā)布模型SECURITY.md 明確安全修復(fù)針對master分支開發(fā)而功能開發(fā)匯聚到dev。因此貢獻(xiàn)者基于dev切分支能最大程度避免與主線沖突也便于維護(hù)者合入。三、搭建開發(fā)環(huán)境Python 3.14 uvCONTRIBUTING.md 明確theHarvester要求 Python 3.14并使用 uv 完全吻合requires-python 3.14且[tool.uv]段聲明python-preference managed、[tool.uv.pip]段固定python-version 3.14意味著 uv 會優(yōu)先拉取受管解釋器并按 3.14 解析依賴。標(biāo)準(zhǔn)開發(fā)環(huán)境搭建流程如下fork 后操作git clone https://github.com/YOUR-GITHUB-USERNAME/theHarvester.git cd theHarvester git remote add upstream https://github.com/laramies/theHarvester.git git fetch upstream git switch -c fix/short-description upstream/dev uv sync --all-groups要點(diǎn)分支名應(yīng)簡短且描述變更例如fix/certspotter-pagination或feature/source-nameuv sync --all-groups會同步 pyproject.toml 中聲明的全部依賴組包括dev組從而獲得 pytest、ruff、ty 等開發(fā)工具dev組包含pytest9.1.1、pytest-asyncio1.4.0、pytest-playwright0.8.0、ruff0.16.3、ty0.0.72等[project.scripts]定義了三個(gè)入口theHarvester、harvestview、harvest-yields。四、做出聚焦的變更Focused Change4.1 通用原則CONTRIBUTING.md 要求復(fù)用現(xiàn)有設(shè)施匹配周邊代碼風(fēng)格復(fù)用現(xiàn)有的配置、傳輸、解析與結(jié)果歸一化輔助模塊而非另起爐灶測試不是必須但強(qiáng)烈鼓勵(lì)Bug 修復(fù)與新增行為最好帶測試可從最近的既有測試開始命名與類型標(biāo)注使用描述性命名在能提升可讀性的地方添加類型注解不隨意加依賴/配置項(xiàng)除非變更確實(shí)需要否則不要新增依賴或配置選項(xiàng)為每一行代碼負(fù)責(zé)包括 AI 輔助生成的代碼——提交 PR 前必須通讀、理解并測試。4.2 Discovery Provider 的注冊約束來自源碼對于新增或修改 discovery providerCONTRIBUTING.md 給出了明確的架構(gòu)約束不要改動 CLI 編排、持久化或輸出代碼。普通 provider 只需兩處注冊一條SourceSpec目錄條目在 theHarvester/lib/source_catalog.py一條SOURCE_FACTORIES工廠條目在 theHarvester/lib/source_runner.py。從 theHarvester/lib/source_catalog.py 的源碼可以看到SourceSpec是一個(gè) frozen dataclass包含name、routes結(jié)果路由集合、activity活動類別默認(rèn) PASSIVE與retains_unresolved_hostnames字段_spec()工廠函數(shù)用于聲明式構(gòu)建目錄條目例如_spec(baidu, ResultRoute.SUBDOMAINS, ResultRoute.EMAILS), _spec(criminalip, ResultRoute.SUBDOMAINS, ResultRoute.IPS, ResultRoute.ASNS, activityActivityClass.DIRECT),而 theHarvester/lib/source_runner.py 中的SOURCE_FACTORIES: dict[str, SourceFactory]負(fù)責(zé)把源名映射到適配器構(gòu)造器runner 統(tǒng)一負(fù)責(zé)構(gòu)造、采集與 completed-result 輸出。核心思路目錄catalog驅(qū)動源的選擇 / 幫助文本 / 活動元數(shù)據(jù)共享 runner 擁有源的構(gòu)造 / 采集 / 結(jié)果輸出生命周期。貢獻(xiàn)者只需面向目錄與工廠編程不必侵入 CLI 與持久化層。4.3 離線契約測試與 provider-contract 覆蓋門禁這是 theHarvester 測試體系中最具特色的機(jī)制每個(gè) canonical provider 必須有一個(gè)離線契約模塊用pytest.mark.provider_contract(source-name)標(biāo)記見 pyproject.toml 中的 markers 聲明provider_contract(source): deterministic offline contract for one canonical discovery source目錄派生catalog-derived的覆蓋門禁會在以下情況失敗目錄條目沒有對應(yīng)契約契約點(diǎn)名了未知源兩個(gè)模塊聲稱同一個(gè)源。從 tests/test_provider_contract_coverage.py 的測試函數(shù)名test_every_canonical_source_has_one_offline_provider_contract、test_provider_contract_failures_name_unknown_duplicate_and_missing_sources可以直接印證這三條失敗規(guī)則。實(shí)際用法是把 marker 加在 provider 的確定性契約模塊上例如 tests/discovery/test_baidusearch.py 末尾的pytestmark pytest.mark.provider_contract(baidu)tests/discovery/test_apisguru.py 的pytestmark pytest.mark.provider_contract(apis-guru)等。不要在測試中維護(hù)第二份源列表——契約標(biāo)記就是唯一的源清單來源。測試編寫建議來自 CONTRIBUTING.md盡量為新增/變更的 provider 添加聚焦測試mock HTTP、DNS 與 provider 響應(yīng)測試不得要求 API Key 或外部網(wǎng)絡(luò)訪問推薦覆蓋的場景缺失憑據(jù)與配置、非成功響應(yīng)/超時(shí)/畸形或空數(shù)據(jù)、分頁與重試終止、歸一化與去重后的結(jié)果。實(shí)現(xiàn)事實(shí)tests 目錄下每個(gè) discovery provider 的契約測試都通過模塊級pytestmark聲明一個(gè)唯一的 canonical 源名覆蓋門禁據(jù)此校驗(yàn)?zāi)夸浲暾远沤^目錄有源但無契約或契約與目錄不同步的漂移。五、安全測試無網(wǎng)絡(luò)測試防線與 live_network 通道5.1 默認(rèn)全面封鎖外部網(wǎng)絡(luò)theHarvester 的測試體系在常規(guī)測試中默認(rèn)禁用一切外部網(wǎng)絡(luò)訪問。這是通過 tests/conftest.py 的pytest_sessionstart鉤子實(shí)現(xiàn)的使用pytest.MonkeyPatch替換socket模塊的 7 個(gè)關(guān)鍵 API——getaddrinfo、gethostbyaddr、gethostbyname、gethostbyname_ex、getnameinfosocket.socket.connect、socket.socket.connect_ex、socket.socket.sendto任何針對非回環(huán)地址的解析或連接都會拋出AssertionError錯(cuò)誤信息明確提示External networking through Python socket APIs is disabled in routine tests. Mock the boundary or mark the test withpytest.mark.live_networkand pass--run-live-network -m live_network.tests/test_harness.py 專門驗(yàn)證了這道防線test_python_socket_network_is_blocked_by_default對example.com的 DNS 解析、TCPconnect_ex、UDPsendto全部被攔截test_http_client_cannot_escape_network_guardhttpx.get(https://example.com)也無法繞過守衛(wèi)因?yàn)榈讓尤宰?sockettest_loopback_network_remains_availablelocalhost、::1、Unix socket 等回環(huán)通信保持可用——即本地測試基礎(chǔ)設(shè)施不受影響。5.2 精確放行l(wèi)ive_network 標(biāo)記 雙參數(shù)只有同時(shí)滿足以下條件測試才會真正觸網(wǎng)見 tests/conftest.pyuv run pytest --run-live-network -m live_network且 pyproject.toml 的addopts默認(rèn)是--no-header --strict-markers -m not harvestview_e2e意味著默認(rèn)運(yùn)行不包含 live_network 與 harvestview_e2e 標(biāo)記的用例。conftest 還強(qiáng)制約束--run-live-network必須與-m live_network同時(shí)出現(xiàn)否則直接pytest.UsageError。關(guān)鍵限制live 標(biāo)記的測試永遠(yuǎn)不滿足 provider-contract 覆蓋門禁——即契約覆蓋只看離線確定性測試不能靠真實(shí)網(wǎng)絡(luò)測試湊數(shù)。5.3 日常驗(yàn)證 vs 發(fā)布前驗(yàn)證CONTRIBUTING.md 給出的本地驗(yàn)證命令uv run pytest tests/path/to/test_file.py # 先跑最窄的受影響測試 uv run ruff check . # lint uv run ruff format --check . # 格式檢查 uv run pytest # 全量測試 uv run ty check # 類型檢查ty 是倉庫選用的類型檢查器發(fā)布前的Release validation工作流需由維護(hù)者手動派發(fā)針對精確的發(fā)布分支或標(biāo)簽gh workflow run provider-smoke.yml --ref dev -f run_livefalse該工作流在干凈的 GitHub-hosted runner 上組合運(yùn)行 Python 檢查、真實(shí)瀏覽器 HarvestView 檢查、打包檢查與容器檢查。只有獲得明確授權(quán)的維護(hù)者才能設(shè)置run_livetrue為mozilla.org增加受限的 P0 provider 檢查live 通道永遠(yuǎn)不會啟用 DNS 或直接目標(biāo)交互。5.4 第三方目標(biāo)的紅線不得對第三方目標(biāo)運(yùn)行廣泛或主動的偵察若必須做真實(shí)驗(yàn)證只能使用自己擁有或獲得明確授權(quán)的目標(biāo)限制請求范圍并且不得把采集的數(shù)據(jù)帶進(jìn) commit、issue 或 PR手動派發(fā)的 provider 工作流使用mozilla.org做小規(guī)模被動 CLI 崩潰冒煙這類運(yùn)行用于發(fā)現(xiàn)打包、憑據(jù)或 provider 漂移不是一致性測試不應(yīng)為了拿到更多結(jié)果而反復(fù)重試。實(shí)現(xiàn)事實(shí)網(wǎng)絡(luò)守衛(wèi)在 tests/conftest.py 的pytest_sessionstart中全局安裝、pytest_collection_finish/pytest_sessionfinish中移除回環(huán)地址與 AF_UNIX 被_is_loopback_host/_is_loopback_address白名單放行。這套機(jī)制把測試必須是離線、確定、無憑據(jù)從口頭約定變成了強(qiáng)制約束。六、開啟 Pull Request貢獻(xiàn)分支推送到自己的 fork 后向laramies/theHarvester:dev打開 PR。PR 應(yīng)包含問題描述與相關(guān) Issue 編號變更前后的行為差異精確運(yùn)行的測試與檢查清單僅在有助于展示結(jié)果時(shí)提供脫敏輸出或截圖需要審查者知曉的兼容性、provider、限速或運(yùn)維風(fēng)險(xiǎn)。若工作未完成或驗(yàn)證未結(jié)束請用draft PR保持分支與上游同步、及時(shí)回應(yīng)評審意見并在請求最終評審前確保必需檢查全部通過。七、Security漏洞披露的私密流程7.1 上報(bào)渠道SECURITY.md 是漏洞上報(bào)的權(quán)威文件核心原則與 CONTRIBUTING.md 完全一致不要在公開 Issue 或 PR 中披露疑似漏洞、利用細(xì)節(jié)、憑據(jù)、私有目標(biāo)數(shù)據(jù)或原始 API 響應(yīng)。具體渠道為若倉庫Security標(biāo)簽頁提供Report a vulnerability私有表單請使用該表單若無私有表單則打開一個(gè)最小化 Issue向維護(hù)者索取私密上報(bào)聯(lián)系方式——該 Issue 中不得包含任何漏洞細(xì)節(jié)。7.2 私有報(bào)告中應(yīng)提供的信息受影響的版本或 commit安全影響與受影響組件最小復(fù)現(xiàn)步驟或概念驗(yàn)證PoC建議的緩解方案是否希望公開署名致謝。7.3 測試邊界與范圍界定只能使用自己擁有或明確授權(quán)的系統(tǒng)與賬戶進(jìn)行測試若測試可能訪問、修改、留存或暴露第三方數(shù)據(jù)必須立即停止不得用第三方目標(biāo)演示 theHarvester 的漏洞范圍覆蓋 theHarvester 的代碼、依賴、打包與倉庫自動化第三方數(shù)據(jù) provider 或服務(wù)的漏洞應(yīng)通過其自身的渠道上報(bào)不屬于安全漏洞provider 中斷、限速、數(shù)據(jù)質(zhì)量與普通功能 Bug——這些請走常規(guī) Issue 渠道同時(shí)移除憑據(jù)、賬戶信息、私有目標(biāo)數(shù)據(jù)與不必要的響應(yīng)內(nèi)容。7.4 披露節(jié)奏允許維護(hù)者獲得合理時(shí)間進(jìn)行調(diào)查并發(fā)布修復(fù)后再公開披露項(xiàng)目可能在適當(dāng)時(shí)機(jī)協(xié)調(diào)安全公告或 CVE并對請求署名者致謝。當(dāng)前項(xiàng)目不提供漏洞賞金也不保證金錢獎勵(lì)。事實(shí)邊界以上均出自倉庫根目錄 SECURITY.md是當(dāng)前倉庫實(shí)際生效的安全策略。八、從貢獻(xiàn)文檔到實(shí)踐如何新增一個(gè) discovery providerwiki 協(xié)作頁明確指向 How to add a new discovery module 作為新增 provider 的完整操作手冊這里把它與 CONTRIBUTING.md 的要求對齊形成一個(gè)可執(zhí)行的六步清單確認(rèn) provider 契約閱讀 provider 官方 API 文檔與條款確定認(rèn)證字段、請求限制、分頁/重試/終止行為、可穩(wěn)定解析為主機(jī)/郵箱/IP/ASN/URL/人名的響應(yīng)字段以及完成單域名查詢的最小請求序列不要把 provider 價(jià)格或配額寫進(jìn)倉庫文檔實(shí)現(xiàn)適配器在theHarvester/discovery/下創(chuàng)建適配器復(fù)用共享 fetcher、配置、解析與結(jié)果歸一化能力。適配器通常提供目標(biāo)與本地結(jié)果集的初始化器、異步process()方法返回SourceExecutionReport | None以及其實(shí)際支持的 getter如get_hostnames()、get_emails()、get_ips()、get_asns()、get_urls()、get_results()不要返回 provider 未提供的字段返回前先歸一化與去重注冊源在 theHarvester/lib/source_catalog.py 添加一條SourceSpec目錄條目在 theHarvester/lib/source_runner.py 添加一條SOURCE_FACTORIES工廠條目保持公共源標(biāo)識符穩(wěn)定且拼寫一致按需添加憑據(jù)若源接受 API Key則補(bǔ)充憑據(jù)字段、在Core._API_KEY_FIELDS注冊、添加適配器使用的Core訪問器并在缺失必需憑據(jù)時(shí)清晰報(bào)錯(cuò)可選 Key 則保留文檔化的無 Key 行為絕不記錄憑據(jù)添加聚焦覆蓋參考 tests/discovery/test_baidusearch.py 的寫法用monkeypatch替換網(wǎng)絡(luò)獲取并斷言歸一化結(jié)果覆蓋成功解析、缺失必需憑據(jù)、非成功/超時(shí)/空/畸形響應(yīng)、分頁與終止、返回的執(zhí)行報(bào)告不完整工作返回報(bào)告、正常完成返回None、歸一化與去重結(jié)果測試不得依賴外部網(wǎng)絡(luò)或真實(shí)憑據(jù)更新操作者文檔在 README 的源矩陣中加入該源及其結(jié)果路由、活動類別與憑據(jù)要求矩陣契約測試會與目錄條目交叉校驗(yàn)并在 PR 中鏈接 provider 的 API 文檔、解釋任何對共享傳輸行為的刻意例外。其中process()的返回值語義與SourceExecutionReport的類型定義可直接在源碼中印證theHarvester/lib/source_runner.py 對SourceExecutionReport分支的處理以及 theHarvester/lib/source_execution.py 中的定義。process()返回值的完整語義如下返回值含義Noneprovider 會話正常完成包括合法的零結(jié)果響應(yīng)SourceExecutionReport(completed, reason)源在自然結(jié)束前成功停止如達(dá)到請求的結(jié)果上限SourceExecutionReport(failed, reason)provider 或傳輸故障終止了源SourceExecutionReport(rate-limited, reason)終態(tài)限速終止了源SourceExecutionReport(partial, reason)provider 確認(rèn)覆蓋不完整注意必須使用穩(wěn)定的 provider 特定 reason不得定義可變的execution_status或stop_reason字段——source runner 會在執(zhí)行前與證據(jù)采集前拒絕這類字段并由它統(tǒng)一負(fù)責(zé)收尾、將保留歸一化證據(jù)的不完整報(bào)告提升為partial、把正常零結(jié)果完成記錄為completed/no-results。九、總結(jié)協(xié)作與安全的一體兩面回顧整個(gè)協(xié)作體系可以發(fā)現(xiàn) theHarvester 的貢獻(xiàn)與安全策略是同一套原則的兩種表達(dá)層面原則落地機(jī)制變更組織單 PR 單一邏輯變更、先開 IssueCONTRIBUTING.md Before you start架構(gòu)邊界provider 只面向目錄與工廠編程不侵入 CLI/持久化SourceSpec目錄source_catalog.pySOURCE_FACTORIESsource_runner.py測試確定性默認(rèn)無網(wǎng)絡(luò)、離線、無憑據(jù)tests/conftest.py socket 守衛(wèi) provider_contract標(biāo)記 --run-live-network -m live_network雙參數(shù)覆蓋完整性目錄與契約一一對應(yīng)杜絕漂移provider-contract 覆蓋門禁tests/test_provider_contract_coverage.py數(shù)據(jù)安全憑據(jù)/私有目標(biāo)數(shù)據(jù)/原始響應(yīng)永不進(jìn)入公開渠道貫穿 CONTRIBUTING.md、SECURITY.md 與 docs/wiki/Contributing-and-Security.md 的統(tǒng)一紅線漏洞披露私密優(yōu)先、范圍明確、合理時(shí)間窗口SECURITY.md 的私有表單/最小 Issue、Scope 與 Disclosure 章節(jié)對于任何希望向 theHarvester 提交代碼或報(bào)告問題的開發(fā)者最穩(wěn)妥的起點(diǎn)是依次閱讀 CONTRIBUTING.md、SECURITY.md新增 provider 時(shí)再對照 How to add a new discovery module并以 tests/discovery/test_baidusearch.py 作為測試范本——這三份文檔與一個(gè)測試文件就足以覆蓋從提一個(gè)想法到合入一個(gè)安全、可驗(yàn)證的變更的全部路徑。【免費(fèi)下載鏈接】theHarvesterE-mails, subdomains and names Harvester - OSINT項(xiàng)目地址: https://gitcode.com/GitHub_Trending/th/theHarvester創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考