sensepost/depscanner
GitHub: sensepost/depscanner
扫描 GitHub 公开仓库的依赖文件，检测在公共包注册表中不存在的孤立依赖包，帮助发现潜在的供应链安全风险。
Stars: 22 | Forks: 1
# Depscanner
## 概述
该工具旨在检测 GitHub 上某些组织的公开代码库依赖项中是否存在孤立（orphan）的必需库。也就是说，该库在对应语言的公开代码库中不存在。例如，一个 GitHub 项目可能会在 `requirements.txt` 中定义一个名为 'internal-package' 的包名。该工具会遍历每个组织下的公开项目，试图寻找对应语言的依赖库定义文件。接着，它会尝试在相应的代码库中搜索该包，例如，对于 Python 包，它会在 pypi.org 上搜索，而对于 Golang，它会在 "pkg.go.dev" 上搜索该包。
有两种使用方式：CLI 或 Web 界面。但首先，你需要安装该工具。
它需要一个 mongodb 数据库来存储结果，因此最佳方法是使用 docker compose 运行基础设施。
# 工作流程
该工具接收组织名称、域名或代码库名称列表作为输入。它通过 GitHub API 列出组织的代码库，并尝试查找该代码库是否包含众所周知的依赖文件，例如 requirements.txt、Pipenv、Gemfile、go.mod、package.json 等。然后，解析该文件并列出该代码库运行所需的每个库/模块。它会访问公开的包注册表并查找该库是否存在。
如果该库不存在，它会根据配置通过 webhook 选择性地通知你的 Discord 频道，并将结果保存在数据库中：
# 设置
## 使用 Docker Compose
要首次启动该工具，只需运行脚本 `./launch.sh`。
或者，你可以通过执行以下命令进行安装（**免责声明**：请修改 Mongo 数据库密码）：
```
git clone https://github.com/sensepost/depscanner
cd depscanner
./launch.sh
# ===========
# 或者手动执行 docker compose：
MONGODB_PASSWD=Test123 docker compose up -d # or execute ./launch.sh
# ===========
# 或者如果你使用 Windows，请使用 .env 文件
echo 'MONGODB_PASSWD=Test123' > .env
docker compose up -d
```
基础设施部署完成后，你可以像这样运行 CLI：
```
# 获取帮助
docker exec -it depscanner-web depscanner -h
usage: usage: depscan.py [-h] (-d DOMAINS | -o ORGS | -r REPOS) [-s STARS] [-t TOKEN] [-P PROXY] [-W WEBHOOK] [-F] [-L {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
Find missing dependencies in Python, JavaScript, TypeScript, Ruby, and Golang projects
optional arguments:
-h, --help show this help message and exit
-s STARS, --stars STARS
Filter the repositories by the number of stars (default: 0)
-t TOKEN, --token TOKEN
GitHub PAT token for the API
-P PROXY, --proxy PROXY
Proxy for HTTP connections (debugging purposes)
-W WEBHOOK, --webhook WEBHOOK
Discord webhook to receive missing packages details
-F, --force Force query GitHub and repositories API to refresh the database (default: False)
-L {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Log level
sources:
Files containing domains, organisations names or repository names
-d DOMAINS, --domains DOMAINS
File containing domain names
-o ORGS, --orgs ORGS File containing GitHub organisation names
-r REPOS, --repos REPOS
File containing GitHub repository names
# 运行基本扫描并将状态发送到你的 Discord 频道
docker exec -it depscanner-web depscanner -d input/domains.txt -t github_pat_[...] -L DEBUG --webhook https://discord.com/api/webhooks/[...]
```
## 从 requirements.txt 安装（不推荐）：
如果你清楚自己在做什么，并希望使用自己的 mongo db，请修改 `config.yml` 文件中的 "mongo" 部分以连接到你的数据库。
然后，你可以安装该工具的依赖项：
```
pip install -r requirements.txt
```
如果你拥有自己的 Mongo 实例并正确配置了文件 "config.yml"，你现在可以使用 CLI，结果应保存在你自己的数据库中。
可选地，如果你想启动 Web 界面，请执行：
```
cd web
flask run --port 8015
```
## CLI
如果你通过 `docker compose up -d` 安装了该工具，可以像这样运行 CLI（提供你自己的待扫描域名列表）：
```
mkdir mylists
cp mydomains.txt mylists/
docker exec -it depscanner-web depscanner -d input/domains.txt -t github_pat_[...] -L DEBUG --webhook https://discord.com/api/webhooks/[...]
```
唯一的强制性标志是：
* 输入文件，可以是域名列表（`-d`）、组织名称列表（`-o`）或 GitHub 代码库列表（`-r`）
* 用于访问其 API 的 GitHub PAT token（它可以在没有 GitHub PAT 的情况下工作，但速率限制会更严格）
你可以使用 `-o` 标志指定组织名称，而不是 `-d`。
如果你想改为探索 GitHub 代码库列表，可以使用 `-r` 标志。
结果将存储在 Mongo 数据库中。可以通过 `mongosh` 或访问 http://localhost:8081/ 上的 Mongo Express 界面进行访问（如果你是通过 docker compose up 运行的）。
终端将显示有关扫描状态的信息：
如果 Depscanner 发现 404 响应，它会将该包报告为缺失。
如果发现 429 Rate Limit Exceeded（超过速率限制）响应，它会暂停一段时间：
可选地，你可以使用 `-W` 标志提供 Discord 的 webhook，以接收关于孤立包的通知。
出于调试目的，你还可以指定一个 HTTP proxy，通过参数 `-P` 发送请求。
为了加快分析速度并减少触发 GitHub API 速率限制的次数，你可以使用参数 `-s ` 按星标数量过滤要分析的代码库。任何星标数少于 的代码库将不被分析。
## Web 界面
Web 界面基于 Python 的 Flask 包。
如果你通过 `launch.sh` 或 `mongo compose` 安装了该工具，Web 界面应该已经在 http://localhost:8015/ 上运行。
如果你是通过 requirements.txt 手动安装的此工具（不推荐），则必须像这样手动启动 Web 界面：
```
# 进入 web 文件夹并启动 flask server
cd web && flask run --port 8015
# 或者运行脚本：
./web.sh
```
应用运行后，访问 http://localhost:8015。
你需要从 "Upload"（上传）标签页上传你的域名/组织/代码库列表源文件。
选择你要上传的文件类型和你的文件：
上传源文件后，转到 "Run"（运行）并提供你的 GitHub PAT token，以及可选的用于在扫描期间接收通知的 Discord webhook：
根据输入的大小，扫描可能需要很长时间。你可以在 "Logs"（日志）中查看正在运行的扫描日志。
扫描完成后，你可以在 "Missing packages"（缺失的包）标签页中查看孤立的包：
## 缓存能力
由于 GitHub API 严格的速率限制，该工具经过编程以避免任何对 GitHub API 或公开注册表（例如 npmjs.org、pypi.org）的不必要请求。为此，它使用一个 MongoDB 来存储最近从 GitHub 检索的代码库信息和来自注册表的包/依赖项信息。如果你想分析的代码库或包已经在本地数据库中，该工具将使用数据库中的信息，而不是发送 HTTP 请求。
本地数据库中存储的信息会频繁刷新。刷新速率取决于 `config.yml` 文件中指定的小时数。属性 `db_refresh_hours` 指定何时数据被视为过时，应再次从 GitHub API 或公开注册表检索。数据库中的每个文档都有一个 `updated` 属性，用于将今天的日期与该文档上次更新的时间进行比较。然后，应用程序会决定是下载/刷新数据还是不刷新。
如果你想查看存储在 MongoDB 中的信息，请导航至 http://localhost:8081/，那里应该有一个 Mongo Express 正在监听。
标签：DNS枚举, Docker, ESC4, GitHub安全, Go安全, IPv6支持, MongoDB, OSINT, Typosquatting检测, 企业安全, 依赖扫描, 依赖混淆, 包管理安全, 孤儿依赖, 安全防御评估, 文档安全, 模型提供商, 网络安全工具, 网络资产管理, 请求拦截, 软件开发工具包, 逆向工具