ODbeke/gen-repo-scan
GitHub: ODbeke/gen-repo-scan
基于 GenLayer 构建的去中心化链上代码审计协议，利用 AI 验证者网络检测 GitHub 仓库中暴露的凭据和密钥。
Stars: 0 | Forks: 0
# GenLayer Smart Repo 扫描器
一个基于 GenLayer 构建的去中心化链上安全审计协议。它利用 AI 验证者网络（通过 GenVM）扫描公开的 GitHub 代码库以及近期提交历史的 diff，以检测暴露的凭据、密钥、API token 和数据库连接 URI。
## 里程碑提交详情
- **项目名称：** GenLayer Smart Repo Scanner
- **开发者：** ODbeke
- **在线演示链接：** [https://gen-repo-scan.vercel.app/](https://gen-repo-scan.vercel.app/)
- **已部署合约地址 (StudioNet)：** `0xDBFaC2b4027786bC423382288ABBfb442Da26a82`
- **提交类型：** 里程碑项目
通过利用 GenLayer 的 **Optimistic Democracy** 共识机制，多个验证者运行独立的大语言模型（LLM），并通过浏览器渲染在链下获取文件，从而就代码的安全状态达成链上的、去信任的共识。
## 核心功能
1. **AI 驱动的漏洞审计：** 超越了简单的正则表达式检查。AI 验证者能够理解代码语义，忽略安全的占位符值（如 `'YOUR_API_KEY'` 或 `'TODO'`），同时标记出真正的、硬编码的密钥。
2. **多文件与提交历史扫描：** 自动抓取仓库目录树以定位高风险文件（如 `.env`、`secret`、`config`、`.ts`、`.py`），并获取最新提交的 `.diff` URL 以扫描近期更改中添加或删除的密钥。
3. **对比式 Prompt 共识：** 配置 `gl.eq_principle.prompt_comparative` 从语义上对比验证者的 LLM 输出，确保共识机制对措辞或格式的细微差异具有鲁棒性，同时对安全裁决执行严格的判定标准。
4. **链上共识证明检查器：** 在 UI 中可视化展示验证者投票、签名、gas 费用和 leader 收据，并附带一个编码的 base64 输出作为共识的加密证明。
5. **故障安全 UI 警报：** 在数据获取失败时（例如私有仓库或无效的 URL）进行报告，以免用户被“安全（SECURE）”的假阴性报告所误导。
## 目录结构
```
├── contracts/
│ └── repo_scan.py # GenLayer Intelligent Contract (prompt_comparative, nondet fetches)
├── scripts/
│ └── deploy.py # Python script to compile and deploy to StudioNet
├── tests/
│ ├── conftest.py # Pytest bootstrap and path configurations
│ └── test_contract.py # Unit tests running in direct (mocked) mode
├── src/
│ ├── hooks/
│ │ └── useWallet.ts # React Web3 wallet connection hook (supports MetaMask + StudioNet)
│ ├── App.tsx # Main dashboard UI & contract integration
│ ├── index.css # Styling configuration (Tailwind V4)
│ └── main.tsx # Application entry point
├── gltest.config.yaml # Testing configurations mapping to StudioNet
├── package.json # Node.js frontend dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Documentation
```
## 设置与安装
### 前置条件
- **Python 3.12+**
- **Node.js 18+** & npm
- 一个配置了 **GenLayer StudioNet** 的 Web3 钱包（如 **MetaMask**）（Chain ID: `61999`，RPC: `https://studio.genlayer.com/api`）
### 1. Python 环境设置
安装 GenLayer 测试套件和 Python SDK 依赖项：
```
pip install genlayer-test python-dotenv eth-account
```
### 2. Node.js 前端设置
克隆仓库并安装 Node 依赖项：
```
npm install
```
## 运行单元测试
本项目包含为 `gltest` 编写的单元测试（以 Direct Mode 运行，该模式会 mock 网络获取和 LLM 输出，从而实现快速、免费的执行）。
使用 `pytest` 运行测试：
```
pytest tests/ -v
```
这些测试涵盖：
- 部署状态
- 对空 URL 的即时拒绝
- 对干净文件的正确识别（`SECURE`）
- 对凭据泄露的正确识别（`NOT SECURE`）
- 文件下载失败时错误的正确传播（`FETCH_FAILED`）
## 智能合约部署
将智能合约部署到 **GenLayer StudioNet**：
1. 在根目录下创建一个 `.env` 文件。
2. 添加您已注入资金的 StudioNet 私钥：
PRIVATE_KEY=0xyour_funded_private_key_here
3. 运行自动化部署脚本：
python scripts/deploy.py
4. 从终端复制打印出的 **CONTRACT ADDRESS**，并将其添加到前端的 `.env` 文件中：
VITE_CONTRACT_ADDRESS=0xdeployed_contract_address_here
## 在本地运行前端
启动 Vite 开发服务器：
```
npm run dev
```
在浏览器中打开 [http://localhost:3000](http://localhost:3000)。连接您的 MetaMask 钱包，切换到 **GenLayer StudioNet**，并粘贴一个 GitHub 仓库链接进行扫描！
验证前端生产环境构建是否成功：
```
npm run build
```
## 里程碑升级与更新日志
本项目在初始提交的基础上进行了大幅升级，以达到 GenLayer 里程碑审查的生产级标准。以下是详细的更改日志：
### 1. 架构重组
- 将代码库重组为专业的目录结构：`contracts/`（智能合约）、`tests/`（单元测试）和 `scripts/`（部署脚本）。
- 规范了文件命名：将合约文件名从 `contract.py` 重命名为 `repo_scan.py`。
- 添加了标准的 `.gitignore` 配置，以过滤 Python 编译产物、linter 文件和构建目录。
### 2. 智能合约升级（`contracts/repo_scan.py`）
- **语义共识（`prompt_comparative`）：** 将死板的 `strict_eq` 检查替换为 `gl.eq_principle.prompt_comparative`。共识不再需要验证者之间输出二进制完全一致的 JSON 字符串（这经常因为 LLM 格式或空白的微小变化而失败），而是现在能够稳健地基于安全日志的语义一致性进行评估。
- **故障安全的 Web 处理：** 用稳健的错误边界取代了松散的网络下载方式。如果目标 URL 获取失败（例如私有仓库的 404 错误），合约将确定性地中止并记录 `FETCH_FAILED`，而不是静默扫描空文件并错误地将其声明为 `SECURE`。
- **已扫描目标审计日志：** 合约现在会在其 JSON payload 中返回成功获取的文件路径列表，允许客户端验证具体审计了哪些内容。
- **提交历史与 Diff 支持：** 添加了专门的 prompt 逻辑，允许验证者检查 git diff 文件（检测 `+` 新增内容以发现新密钥，并忽略 `-` 删除的内容）。
### 3. 前端升级（`src/App.tsx` & `src/hooks/useWallet.ts`）
- **多文件抓取：** 配置了前端，通过 GitHub REST API 动态查找仓库中风险最高的 2 个文件，并将它们与最新提交的 `.diff` URL 结合，作为逗号分隔的查询发送给合约。
- **共识收据检查器：** 构建了一个发光的玻璃拟态“共识证明（Consensus Proof）”查看模态框。该模态框显示原始的 base64 编码收据 payload，并解析出验证者签名、投票、使用的 gas 和 leader 输出。
- **改进的 UX 状态：** 为 `FETCH_FAILED` 错误添加了自定义渲染器，并在结果卡片中动态列出了已审计的目标。
### 4. 单元测试与自动化
- 创建了 `gltest.config.yaml` 和 `tests/conftest.py`，设置了路径注入和网络配置。
- 实现了一套包含 5 个 direct-mode 单元测试的测试套件（`tests/test_contract.py`），涵盖了干净扫描、漏洞审计、空字符串、下载失败和部署状态。
- 创建了 `scripts/deploy.py`，用于自动化的合约编译和 StudioNet 部署。
标签：GenLayer, LLM大语言模型, LLM应用, StruQ, Web3安全, 区块链共识, 安全规则引擎, 对称加密, 自动化审计, 自动化攻击, 逆向工具