sakhujarohan/keel-sec-guard
GitHub: sakhujarohan/keel-sec-guard
一款结合静态分析与 Google Gemini 语义审查的双模式代码安全审计工具，支持本地 CLI 与 CI/CD 流水线中自动检测代码漏洞与凭证泄露。
Stars: 1 | Forks: 0
# 🛡️ Keel Security Guard (`keel-sec-guard`)
[](https://github.com/sakhujarohan/keel-sec-guard/releases)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](action.yml)
`keel-sec-guard` 是一款轻量级的双模式安全审计工具，可保护您的代码库免受硬编码凭证、结构性 AST 漏洞以及逻辑缺陷的影响。它将确定性的静态分析与 **Google Gemini 2.5** 语义代码分析相结合，通过免费 Google AI Studio 凭证在 **本地通过 CLI / Agent Skill 运行** 以及 **在 CI/CD 中通过 GitHub Actions 运行**，且无需任何 API 费用。
## ✨ 功能
- **⚡ 混合安全引擎**：将 100% 确定性的 secret/OWASP 扫描与 Google Gemini 语义分析相结合。
- **🤖 双执行模式**：既可作为 CLI / Agent Skill 在本地运行（`npx keel-sec-guard`），也可作为可重用的 GitHub Action 在 CI/CD 中运行。
- **💰 $0 API 费用**：使用免费的 Google AI Studio 凭证（`GEMINI_API_KEY`），以保留您的 Claude API 配额。
- **🔒 公共 Fork 保护**：在外部 PR 上以只读模式安全运行，防止 secret 窃取攻击。
- **📁 自动化 Artifacts 与 Gitignore**：自动将 Markdown 报告、JSON 诊断信息和执行日志导出到一个自动添加至 gitignore 的输出文件夹（`.keel/sec-guard/`）。
## 🏗️ 架构
## 🚀 快速开始
### 1. GitHub Action 设置 (CI/CD)
将 `.github/workflows/security-audit.yml` 添加到任何仓库中：
```
name: Security Audit
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
security-audit:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Keel Security Guard
uses: sakhujarohan/keel-sec-guard@v1
with:
gemini-api-key: ${{ secrets.GEMINI_API_KEY }}
output-dir: '.keel/sec-guard'
fail-on-severity: 'HIGH'
```
### 2. 本地开发者与 CLI 设置
从 [Google AI Studio](https://aistudio.google.com/app/apikey) 获取一个免费的 key，并将其放入您的 `.env` 文件中：
```
# .env
GEMINI_API_KEY=AIzaSy...your_gemini_key_here...
```
对您本地的 git 分支 diff 运行安全审查：
```
# 通过 npx 在本地运行
npx keel-sec-guard audit --branch main --output-dir .keel/sec-guard
```
### 3. Claude Code / AI Agent Skill 集成
将 [`SKILL.md`](SKILL.md) 包含在您的 AI Agent skills 目录中，以便本地编码 Agent（Claude Code、Gemini CLI、Cursor）在提交 PR 之前能够自主运行安全审计：
```
# 询问你的 AI Agent：
"Run a security audit on my diff before creating the PR"
```
## ⚙️ 配置与选项
### GitHub Action 输入项 (`action.yml`)
| 输入项 | 描述 | 必填 | 默认值 |
| :--- | :--- | :--- | :--- |
| `gemini-api-key` | Google AI Studio Gemini API Key | 否 | `''`（如果省略则仅进行 SAST 扫描） |
| `github-token` | 用于发布 PR 评论的 GitHub token | 否 | `${{ github.token }}` |
| `model` | 要使用的 Gemini 模型（`gemini-2.5-flash`、`gemini-2.5-pro`） | 否 | `'gemini-2.5-flash'` |
| `fail-on-severity` | 导致构建失败的阈值（`CRITICAL`、`HIGH`、`MEDIUM`、`NONE`） | 否 | `'HIGH'` |
| `output-dir` | 用于保存 Markdown 报告、日志文件和 JSON 的文件夹路径 | 否 | `''` |
### CLI 命令选项 (`npx keel-sec-guard audit`)
| 选项 | 标志 | 描述 | 默认值 |
| :--- | :--- | :--- | :--- |
| 基础分支 | `-b, --branch ` | 要进行比较 diff 的基础分支 | `main` |
| Gemini 模型 | `-m, --model ` | Gemini 模型名称 | `gemini-2.5-flash` |
| 失败阈值 | `-f, --fail-on ` | 触发退出代码 1 的严重性阈值 | `HIGH` |
| 输出目录 | `-o, --output-dir ` | 用于保存审计 artifacts 的目录 | `''` |
## 📁 输出 Artifacts 与诊断信息
当设置了 `--output-dir`（或在 CI 中设置 `output-dir`）时，`keel-sec-guard` 会将诊断文件导出到指定目录：
```
.keel/sec-guard/
├── .gitignore (auto-created with * to prevent accidental git commits)
├── audit-report.md (Formatted Markdown security review report)
├── audit-run.json (Structured JSON diagnostics, SAST stats & Gemini response)
└── audit.log (Timestamped execution trace log)
```
## 🔒 安全与 Fork 隔离
- **Pwn-Request 防御**：在评估公共仓库中来自外部 fork 的 PR 时，`keel-sec-guard` 会在安全的只读环境中运行，以防止恶意的 PR 脚本窃取 `GEMINI_API_KEY`。
- **免维护 Gitignore**：输出目录会自动写入一个包含 `*` 的本地 `.gitignore`，因此安全报告和日志永远不会被提交到您的 git 历史记录中。
## 📐 基于 Keel Agentic SDLC 构建
`keel-sec-guard` 的设计和构建遵循 **Keel Agentic Software Development Lifecycle**。所有需求、架构图和规范历史都进行了版本控制，并存放在 [`specs/`](specs/) 中。
## 📄 许可证
基于 MIT 许可证分发。查看 [`LICENSE`](LICENSE) 了解更多信息。
图表源码 (mermaid)
``` graph TB subgraph Execution Modes Dev[Developer / AI Agent] GH[GitHub Actions CI] end subgraph keel-sec-guard Core Engine CLI[CLI Adapter] Action[GitHub Action Adapter] Diff[Diff Extractor & Filter] SAST[SAST & Secret Scanner] Auditor[Gemini 2.5 Auditor] Reporter[Markdown & Log Reporter] CLI --> Diff Action --> Diff Diff --> SAST SAST --> Auditor Auditor --> Reporter end subgraph External Services Gemini[Google Gemini API] GitHubAPI[GitHub PR Comments API] end Dev -->|runs npx / SKILL.md| CLI GH -->|triggers action.yml| Action Auditor -->|semantic audit prompt| Gemini Reporter -->|post PR review comment| GitHubAPI ```标签：AI代码审计, GitHub Actions, MITM代理, TypeScript, 安全审计工具, 安全插件, 自动化攻击, 自动笔记, 静态代码扫描