parsazolfaghar/grin

``` curl -fsSL https://raw.githubusercontent.com/parsazolfaghar/grin/main/scripts/install.sh | bash ``` ## 为什么它能真正落地 大多数“AI 替你黑客攻击”的演示在模型运气不好的那一刻就会停滞。Grin 不会，因为 *模型并不是最后一公里* —— 代码才是。 - **确定性的收尾工具。** 当模型想要放弃时，grin 的代码会通过 spine 接管并 完成任务：默认凭据扫描、命令注入、sudo 和 SUID privesc、LFI→破解、SQLi 以及 SSH-key 横向移动。胜利不靠运气。 - **能够学习的大脑。** 持久化的跨任务记忆能识别当前情况，并每次 应用经过验证的行动方案 —— 并从每一次成功和碰壁中学习。 - **双重武器库。** 自我配置的 **Kali + BlackArch** 容器，在设计上互补 —— 一台 装有 Docker 的笔记本电脑就是一个完整的装备。 - **失败关闭的 spine。** 每一个动作：解析 → 授权 → 闸门 → 执行 → 审计。范围外的动作会被 *拒绝*，而不是执行。模型无法绕过它。 - **广泛的覆盖范围。** 集成的 nuclei 带来了数千种 CVE/配置错误检查；每一次命中都是 一个有证据支持的发现。 - **一键更新。** 一键拉取代码，重新部署容器内的助手，并同步 大脑 —— 三个层级，保持最新。 ## 快速开始 1. **安装** —— 使用上方的单行命令 (Kali/Debian；需要 `git` + `docker`)。或者 `pip install -e ".[app]"`。 2. **自带大脑** —— 在 `~/.grin/deepseek.env` 中放入一个密钥 (任何 OpenAI 兼容的 endpoint； 推荐 DeepSeek-V3)，或者使用 Ollama 运行本地模型，完全跳过云端： GRIN_MODEL_BACKEND=openai GRIN_MODEL_URL=https://api.deepseek.com/v1 GRIN_MODEL_API_KEY=sk-... # 你的密钥。grin 绝不会代理它。 3. **开始** —— 启动应用程序，在 Engage 栏中输入目标 + 目的，看着它工作。或者使用下方的 CLI。 ## 平台 可以在 **macOS、Windows 和 Linux** 上运行。桌面应用程序 + 引擎是跨平台的 Python； **武器库可以在任何 Docker 运行的地方运行**，因此相同的任务可以在 Kali 笔记本电脑上（原生工具）以及 Mac 或 Windows 机器上（Docker Kali/BlackArch）运行。`curl | bash` 单行命令针对 Kali/Debian；在 macOS/Windows 上使用 `pip install -e ".[app]"` + Docker Desktop 安装。 ## 完整功能集

它所做的一切 —— 真实的机制。

**失败关闭的 spine** - 单一执行路径：解析 → 授权 → 闸门 → 执行 → 审计（没有其他代码运行命令） - 范围 + 排除执行 —— 范围外的动作会被*拒绝* - 动作类别：被动 / 主动扫描 / exploit / 后渗透；ROE 时间窗口执行 - 每次允许和拒绝的仅追加审计日志；自托管销毁保护 **自主性与控制** - 模式：自主 / 动作闸门 / 阶段闸门 - 针对每个动作的批准/拒绝闸门；暂停和 `--resume` - 在每个新 flag 上捕获检查点（aggressive 模式）；运行中协作停止 - 授权内无摩擦默认设置（自动安装工具，无弹窗提示） **Multi-agent 核心** - **Orchestrator** 规划目标、追踪线索、重新规划 · **Executor** 针对每个目标的 observe→act 循环 - **Analyst** 阅读发现并提出后续行动 · **Medic** 拯救停滞状态 + 记录教训 · **Reporter** 撰写交付物 **Grin Brain（学习）** - 持久化的跨任务记忆；检测实时情况并注入经过验证的行动方案 - Playbook（执行）+ pitfalls（避免），通过真实结果强化；初始内置；更新时同步新方案 **确定性的收尾工具**（不依赖模型的最后一公里，全部通过 spine 运行） - `cred-sweep` 默认/弱 SSH 凭据 · `web-rce` 命令注入/SSTI RCE · `sudo-gtfo` sudo-NOPASSWD GTFOBins - `suid-hijack` SUID PATH 劫持 · `lfi-crack` 目录遍历→离线破解→SSH · `ssh-loot` SSH-key 横向移动 **Recon 与 exploit** - nmap · gobuster/ffuf fuzzing · **nuclei**（数千个 CVE/配置错误模板 → 有证据支持的发现） - `web-scan` 反射型-XSS 发现 · sqlmap SQLi 测试/转储 · subfinder/httpx 外部攻击面 - `grin-shell` 驱动交互式工具（msfconsole/meterpreter/ssh） · john + rockyou 离线破解 **武器库与环境** - 自我配置的 **Kali + BlackArch** 容器，在两个发行版上实现互补的工具拆分 - 自动安装缺失工具（询问/自动/从不） · 环境：local / ssh / docker / arsenal / auto · 一台装有 Docker 的笔记本电脑 = 一个完整的装备 **大脑与模型** - 任何 OpenAI 兼容的云端 (DeepSeek/Groq/OpenRouter) 或本地 Ollama - 按角色进行模型路由 (planner/recon/exploit) · 云端→云端备用层级 · **自带密钥，从不代理** **强度与隐蔽性** - 强度：recon / normal / aggressive (全面 ATT&CK 扫描) / max - 隐蔽性：off / quiet / paranoid — 出口代理/Tor、慢速时间、UA 轮换，以及在生效处的 MAC/主机名欺骗 **输出与证据** - 报告：**Markdown / SARIF / HTML** · 完整的战利品捕获 (creds, keys, flags) · 有证据把关的发现 - ATT&CK 覆盖范围映射 · 确定性的“发现”视图 · **CI 模式** (`grin ci`，发现严重程度 ≥ 指定级别时则构建失败) **桌面应用程序与工作流** - 自然语言 Engage 栏（目标+目的 → 范围锁定的运行） · MODE/STRENGTH/STEALTH/TOOLS 开关 - 实时发现/战利品/审计/发现 · 批准/拒绝动作 + 工具安装 · 导出报告按钮 - 渗透任务 Playbook：仅 recon / external-asm / internal-network / bug-bounty / ctf-solver **平台与运维** - macOS · Windows · Linux · 一键全面更新（代码 + 助手 + 大脑） · `grin doctor` 预检 - `grin --version` + CHANGELOG · 完整 CLI (engage/ci/report/loot/arsenal/brain/doctor/lab/labbench/…) · 内置分级实验室与基准测试

## 安装 (CLI / 开发) ``` pip install -e ".[dev]" # add ",docker" for the docker/arsenal runners, ",app" for the GUI ``` ## Spine（授权核心） ``` grin engagement validate examples/acme-extnet.yaml grin run examples/acme-extnet.yaml # submit: tool | command | target [| class] grin gate examples/acme-extnet.yaml # approve/deny pending intrusive actions grin audit examples/acme-extnet.yaml # print the evidence trail ``` 每个动作都运行 `resolve_class → authorize → gate → execute → audit`，失败关闭。spine 设置 动作类别（防欺骗）；范围外的、被排除的、不允许的类别、时间窗口外的，以及 非活动任务的动作都会被拒绝并记录。没有其他代码路径可以运行命令 或写入允许行。 ## Executor 在一个目标上运行 AI agent（通过 spine 驱动 Kali/BlackArch 工具）： ``` grin execute examples/lab-recon.yaml --task "find web services" --target 10.0.0.5 grin execute --resume ./audit/home-lab-recon..journal.json # after `grin gate` ``` Executor 向模型请求下一个动作，spine 授权/拦截/在绑定的 武器库上运行它，循环继续直到达成目标、步骤预算耗尽，或者被拦截的 动作需要 `grin gate` 批准（然后使用 `--resume`）。**有证据把关的发现：** 只有在该任务中 确实运行了真实命令时，才会报告一个发现。 ## Orchestrator 从一个高级目标运行整个渗透任务（自适应，追踪线索）： ``` grin engage examples/external-net.yaml --goal "assess the external network" grin engage examples/external-net.yaml --goal "find and verify web vulns" --seeds 10.0.0.5 ``` Orchestrator 规划目标，通过 Executor 运行每一个目标，Analyst 阅读发现并 提出后续行动，循环一直运行直到达成目标或触及目标预算 （`--max-objectives`，默认为 10）。受拦截的（客户端）任务会暂停侵入性目标，以 等待 `grin gate` 批准，并在最后报告它们。 **来自 CLI 的强度与隐蔽性**（也是仪表盘开关 / YAML 字段）： ``` grin engage examples/external-net.yaml --goal "..." --strength aggressive --stealth quiet ``` - `--strength recon|normal|aggressive|max` — recon（仅扫描，无 exploit） → normal → aggressive （全面 ATT&CK 扫描） → max（扫描 + 更深的预算）。 - `--stealth off|quiet|paranoid` — 在 spine 处应用：出口代理/Tor、慢速时间、轮换的 UA， 以及在生效处的 MAC/主机名欺骗。详见 [隐蔽性](#stealth)。 **恢复被拦截的渗透任务：** ``` grin engage examples/external-net.yaml --goal "..." # pauses intrusive objectives grin gate examples/external-net.yaml # approve/deny grin engage examples/external-net.yaml --resume # continue the approved ones ``` **按角色分配模型** —— 根据目标类型进行路由（`--recon-model`、`--exploit-model`、 `--planner-model`），每一个都回退到 `--model`。动作类别标签仅驱动模型选择； spine 仍然会授权每一个命令。 ## Reporter ``` grin report examples/external-net.yaml -o report.md ``` 按严重程度对发现进行分组（包含证据、确切的命令、修复建议），列出方法论， 并附上审计追踪 + 被阻止动作的摘要。执行摘要是确定性的，或者如果 大脑启动了，则是一段简短的模型叙述。 ## Loot —— 捕获的机密 Executor 获取的机密（凭据、密钥、token、flag）将被完整捕获到 `audit/.loot/`（`secrets.jsonl` + 可读的 `secrets.md`）以及报告的机密 部分。不进行脱敏 —— 目的是获取暴露的具体证据。使用 `grin loot ` 打印。（Loot 以明文形式保存实时机密；请作为敏感信息 处理。所有内容都保留在本地。） ## 模型后端 配置后默认使用云端：设置 `GRIN_MODEL_BACKEND=openai`、`GRIN_MODEL_URL` 和 `GRIN_MODEL_API_KEY` 以使用任何 OpenAI 兼容的 endpoint（DeepSeek、Groq、OpenRouter、…）。如果未设置 → 则使用本地 Ollama。显式的 `GRIN_MODEL_BACKEND`（ollama|openai）始终优先。客户端模式的渗透任务在 云后端处于活动状态时会发出警告并进行审计。 ## 武器库 攻击性工具运行在与每个任务绑定的**环境**中（YAML 中的 `env.kind`）： - `local` — 本主机上的工具。`ssh` — 远程机器。`docker` — 一个指定的容器。 - `arsenal` — Grin **自动配置的** Kali + BlackArch 容器（`grin arsenal up/down/status/add`） 在任何本地 Docker 上。缺失的工具可以自动安装或**请求安装**（参见 TOOLS 开关）。 - `auto` — 运行**在**渗透测试主机上（Kali/Parrot/BlackArch，或 PATH 中存在攻击 工具）时使用本地工具，否则回退到 Docker 武器库。应用程序启动的渗透任务默认使用此项， 因此相同的任务可以在 Kali 笔记本电脑上本地运行，也可以在 Mac 上的 Docker 中运行。 ## 桌面应用程序 `grin app` 打开原生 PyQt6 仪表盘。将其安装为可点击、带图标的应用程序： - **macOS:** `scripts/build-macapp.sh` → `dist/Grin.app`（PyInstaller，未签名）。拖到 `/Applications`；首次启动 **右键点击 → 打开**（Gatekeeper）。 - **Linux:** `scripts/install-desktop.sh` 安装一个 `.desktop` 条目 + 图标（需要 `grin` 在 PATH 上； NixOS 是声明式的）。 通过启动器点击的应用程序没有 shell 环境 —— 将云端配置放在 `/.grin/env` 中（它永远不会覆盖 已经设置的变量）。大脑是云端/本地的，武器库是 Docker/主机的 —— 两者都没有打包进应用程序中。 ### 仪表盘 - **Engage 栏** —— 输入一个任务（`bypass login page for www.test.com`）或纯粹的目标 （`www.test.com`）；Grin 解析目标 + 目的，显示每个目标的技术/工具菜单，并 启动范围锁定的渗透任务。输入提示即是你的授权（逐字记录在 审计日志中）。 - **MODE** — Cloud / Local / Split(rig)：大脑 + 工具拓扑结构。 - **STRENGTH** — Recon / Normal / Aggressive / Max。 - **STEALTH** — Off / Quiet / Paranoid（见下文）。 - **TOOLS** — Ask / Auto / Never：当运行需要不在武器库中的工具时，Ask 会弹出 允许/拒绝提示（然后在允许时安装），Auto 按需安装，Never 则失败。 - **Capture checkpoints** — 在 aggressive 运行中，每个新 flag 都会暂停扫描并询问：继续 扫描 / 聚焦此目标 / 下一个目标 / 停止。 ## 隐蔽性 默认关闭，选择性加入，仅针对目标；每个命令仍然会在运行时进行审计，并记录当前生效的级别。 级别：`quiet`（出口 + 轮换的 UA + 较慢的时间）和 `paranoid`（+ nmap 诱饵、非常 慢/低的时间，以及在生效处的 MAC/主机名欺骗 —— 在 NAT 后自动跳过）。源 IP 出口使用 `GRIN_PROXY=socks5://…` 或 `GRIN_EGRESS=tor`；如果两者都未设置，将跳过出口并且 doctor 会发出警告 （Grin 绝不会假装你被隐藏了）。隐蔽性只会改变已经授权的命令的*执行方式* —— 永远不会 改变*允许的内容*。 ## Doctor ``` grin doctor [engagement.yaml] [--fix] [--yes] ``` 对 Grin 的运行环境进行预检：引擎依赖、模型后端、武器库容器、环境可达性、 所需工具，以及处于活动状态的隐蔽性/出口配置。默认只读；`--fix` 仅在 获得单项同意的情况下安装可自动修复的缺失项。 ## 开发 / 测试 ``` ruff check grin/ tests/ QT_QPA_PLATFORM=offscreen pytest -q ``` CI 会在每次 push/PR 时运行 ruff + 完整测试套件（`.github/workflows/ci.yml`）。

标签：AI风险缓解, PE 加载器, Web报告查看器, 协议分析, 权限提升, 横向移动, 红队自动化, 编程规范, 自动化漏洞利用, 请求拦截, 逆向工具