Danyal-Faheem/Alduin

# AppSec Agent 一个容器化的 AI 辅助应用安全代理，可扫描代码仓库、规范发现结果、执行可选的 LLM 分类/调查，并应用经过验证的保守修复方案。 ## 本项目功能 给定本地路径或 GitHub 仓库，AppSec Agent 可以： 1. 接收并识别仓库信息（语言、框架、构建系统、包管理器、安全相关文件）。 2. 在隔离的 Docker 容器中运行扫描器。 3. 将发现结果规范化为统一的内部模式。 4. 使用 CWE 元数据对发现结果进行分组/丰富。 5. 生成机器可读和人类可读的报告。 6. 可选地逐一应用低风险修复方案并设置验证关卡。 7. 创建草稿 PR 输出（当凭据可用时创建远程 GitHub 草稿 PR，否则生成本地草稿 PR 工件）。 ## 核心功能 - FastAPI 后端 + Typer CLI + RQ worker。 - 扫描器适配器：`trivy`、`gitleaks`、`semgrep`、`osv-scanner`。 - 可选的 LLM 工作流：分类（`ENABLE_LLM_TRIAGE`）、调查计划（`ENABLE_LLM_INVESTIGATION`）和沙箱中的工具箱命令（`ENABLE_LLM_TOOL_INSTALL`）。 - 安全的修复工作流，逐个修复漏洞，验证每个修复，并自动回滚失败的补丁。 - 使用常规提交消息进行已验证的修复提交。 ## 架构 - `apps/api`：FastAPI 服务和 UI。 - `apps/cli`：CLI 入口点（`appsec-agent`）。 - `apps/worker`：后台运行执行 worker。 - `packages/core/src/appsec_agent`：核心领域逻辑，包括接收/识别、扫描器、规范化和修复、报告以及 GitHub 草稿 PR 集成。 - `artifacts/runs/`：每次运行的输出和日志。 ## 前置条件 - Docker Desktop（或 Docker Engine + Compose） - Python 3.12+ - `uv` - 如果使用 LLM 功能，需要运行 LLM 端点（vLLM/OpenAI 兼容） ## 快速开始（Docker Compose） ### 1) 配置环境 ``` cp .env.example .env ``` 对于 Docker Desktop 嵌套扫描器容器，设置： ``` # Keep storage path inside containers STORAGE_PATH=/artifacts # Host path that maps to STORAGE_PATH for nested docker mounts DOCKER_HOST_STORAGE_PATH=/absolute/path/to/Alduin/artifacts ``` 如果您的模型服务器在主机上运行： ``` VLLM_BASE_URL=http://host.docker.internal:8000/v1 ``` ### 2) 启动服务 ``` docker compose up -d db redis api worker ``` ### 3) 运行数据库迁移 ``` docker compose exec api uv run alembic upgrade head ``` ### 4) 打开 UI - 仪表板：`http://localhost:8080/ui` ## UI 流程 UI 允许您： 1. 输入 GitHub URL。 2. 启动运行。 3. 查看后端阶段/事件的实时时间线。 4. 查看摘要统计。 5. 查看生成的 HTML 报告。 这对于长时间运行的演示运行非常有用，因为事件流和阶段进度会持续更新。 ## 通过 CLI 端到端运行 创建运行： ``` docker compose exec api uv run appsec-agent runs create \ --repo https://github.com/Hackman238/legion \ --source-type github ``` 同步执行： ``` docker compose exec api uv run appsec-agent runs execute --run-id ``` 查看事件： ``` docker compose exec api uv run appsec-agent runs events --run-id ``` ## 通过 API 运行 创建： ``` curl -X POST http://localhost:8080/v1/runs \ -H "content-type: application/json" \ -d '{"repo":"https://github.com/Hackman238/legion","source_type":"github"}' ``` 执行： ``` curl -X POST "http://localhost:8080/v1/runs//execute?use_queue=true" ``` 摘要： ``` curl http://localhost:8080/v1/runs//summary ``` 报告 HTML： ``` curl http://localhost:8080/v1/runs//report/html ``` ## 重要的运行时选项 在 `.env`（或容器环境）中使用这些： - 扫描和修复：`ENABLE_SCANNERS`、`ENABLE_AUTOFIX`、`MAX_FIX_PR_COUNT`、`MAX_DIFF_LINES`、`MAX_PATCH_FILES`。 - LLM 功能：`ENABLE_LLM_TRIAGE`、`ENABLE_LLM_INVESTIGATION`、`ENABLE_LLM_TOOL_INSTALL`、`VLLM_BASE_URL`、`VLLM_MODEL`。 - 扫描器容器网络：`SANDBOX_ALLOW_NETWORK=true`（建议用于真实扫描器数据库/API 访问）。 - GitHub PR 行为：`ENABLE_GITHUB_PRS`、`GITHUB_TOKEN`、`GITHUB_BASE_BRANCH`。 ## 修复和草稿 PR 行为 当启用修复且存在安全建议时： 1. 代理一次应用一个修复。 2. 验证扫描器对修改后的仓库运行。 3. 验证关卡决定通过/失败。 4. 通过的修复将被提交（常规提交格式）。 5. 失败的修复将自动回滚。 草稿 PR 输出： - 带有 GitHub token + PR 启用：创建远程草稿 PR。 - 没有 GitHub token：生成本地 markdown 草稿 PR： - `artifacts/runs//draft_pr_local.md` ## 每次运行产生的工件 在 `artifacts/runs/` 下： - `fingerprint.json` - `findings.json` - `normalized_findings.json` - `report.md` - `report.html` - `remediation_summary.json` - `event_log.jsonl` - `raw/` 扫描器工件 - `remediation/` 每个修复的验证扫描工件 - `draft_pr_local.md`（当没有创建 GitHub PR 时） ## API 端点 - `GET /healthz` - `GET /readyz` - `GET /ui` - `POST /v1/runs` - `GET /v1/runs/{run_id}` - `GET /v1/runs/{run_id}/events` - `POST /v1/runs/{run_id}/execute` - `GET /v1/runs/{run_id}/summary` - `GET /v1/runs/{run_id}/report/html` ## CLI 命令 - `uv run appsec-agent api` - `uv run appsec-agent worker` - `uv run appsec-agent runs create --repo [--source-type local|github] [--ref ]` - `uv run appsec-agent runs get --run-id ` - `uv run appsec-agent runs execute --run-id [--use-queue]` - `uv run appsec-agent runs events --run-id ` ## 开发 安装依赖： ``` uv sync --dev ``` 运行检查： ``` uv run ruff check . uv run mypy apps packages uv run pytest tests/unit tests/integration tests/e2e -q ``` ## 故障排除 - 扫描器容器在 Docker Desktop 上挂载失败： 将 `DOCKER_HOST_STORAGE_PATH` 设置为您的绝对主机 `artifacts` 目录。 - 扫描器显示 DNS/网络失败： 设置 `SANDBOX_ALLOW_NETWORK=true`。 - 没有 LLM 丰富： 验证 `ENABLE_LLM_TRIAGE` / `ENABLE_LLM_INVESTIGATION` 和 `VLLM_BASE_URL`。 - PR 未在远程创建： 验证 `ENABLE_GITHUB_PRS=true`、`GITHUB_TOKEN` 和 git remote 认证。 没有凭据时，本地草稿 PR 输出是预期的。 ## 附加文档 - 真实世界测试手册：[docs/real-world-test-playbook.md](docs/real-world-test-playbook.md) - 产品/背景规范：[docs/appsec-agent-spec.md](docs/appsec-agent-spec.md) ## 许可证 本仓库根据非商业许可证提供源代码。 请参阅 [LICENSE.md](LICENSE.md) 了解完整条款。

标签：AI安全代理, AI辅助安全, AV绕过, CI/CD安全, DAST, DevSecOps, DLL 劫持, Docker, FastAPI, GitHub集成, gitleaks, GraphQL安全矩阵, Llama, LLM, OpenAI兼容API, osv-scanner, Python, RQ任务队列, SAST, SBOM, Secret扫描, semgrep, trivy, Typer CLI, Unmanaged PE, vLLM, Web截图, 上游代理, 云安全监控, 代码指纹识别, 依赖漏洞扫描, 回滚机制, 大语言模型, 安全修复, 安全合规, 安全扫描器, 安全报告, 安全防御评估, 容器化扫描, 容器安全, 恶意软件分析, 无后门, 框架检测, 漏洞修复, 漏洞分类, 盲注攻击, 硬件无关, 网络代理, 网络安全培训, 补丁验证, 请求拦截, 跌倒检测, 软件物料清单, 逆向工具, 静态分析