1. 项目概述一个AI驱动的渗透测试助手最近在安全圈子里一个名为HackerAI的开源项目引起了我的注意。简单来说它就是一个用AI来辅助渗透测试和安全研究的智能助手。想象一下你不再需要一个人埋头苦读那些复杂的漏洞报告或者一遍遍地在命令行里敲打重复的侦察命令而是有一个“懂行”的AI伙伴能帮你分析目标、生成攻击载荷、甚至解释一个复杂漏洞的利用原理。HackerAI就是奔着这个目标去的。它不是一个玩具而是一个架构相当完整、设计思路清晰的生产级工具旨在将大语言模型的推理能力与安全专家的实战经验结合起来提升安全评估的效率和深度。无论你是刚入门的安全爱好者想有个“师傅”带着你理解各种攻击手法还是经验丰富的红队成员希望有个智能副驾来处理繁琐的侦察和信息整理工作这个项目都值得你花时间研究一下。它的核心定位很明确AI-Powered Penetration Testing Assistant。这意味着它不仅仅是调用API生成一些文本而是构建了一个能够理解安全上下文、执行特定任务比如端口扫描结果分析、漏洞POC生成、并在受控环境中安全运行代码的智能体系统。项目采用了当前非常流行的技术栈包括Next.js、React、TypeScript作为前端和全栈基础并深度集成了Convex作为实时后端数据库以及WorkOS处理企业级身份认证。更关键的是它通过OpenRouter或OpenAI接入大模型并利用E2B提供的安全沙箱环境来执行AI生成的代码这解决了AI代理执行不可信代码时的核心安全隐患。接下来我就结合官方文档和我的实际搭建体验为你深度拆解这个项目的设计思路、核心模块以及如何从零开始部署和定制属于你自己的AI安全助手。2. 核心架构与设计思路拆解2.1 为什么是“AI代理”架构HackerAI没有做成一个简单的聊天机器人问你“有什么可以帮您”然后生成一些通用的安全建议。它采用的是AI代理架构。这两者有本质区别。传统的聊天交互是“一问一答”模型基于你的输入生成一段文本回复。而代理架构赋予了AI“行动”的能力。在这个框架下AI模型扮演一个“大脑”它可以规划任务、决定调用什么工具比如执行一个Nmap命令、搜索CVE数据库、执行工具、分析工具返回的结果并根据结果决定下一步行动直到达成目标。举个例子你给HackerAI一个目标域名example.com。一个简单的聊天模型可能会回复“你可以尝试进行子域名枚举、端口扫描、目录爆破等。” 而一个AI代理则会自主执行以下链条1. 调用子域名枚举工具如subfinder2. 分析枚举结果选取活跃子域名3. 对活跃子域名发起端口扫描如nmap -sS4. 分析开放的端口识别运行的服务如发现80端口运行Nginx 1.185. 基于服务版本搜索公开漏洞库6. 如果发现相关漏洞尝试生成一个简单的验证脚本。这一系列动作在HackerAI的代理模式下可以由AI自主或半自主地完成。这种设计思路极大地扩展了AI在安全运维中的实用性使其从一个“知识库”升级为一个“虚拟工程师”。2.2 技术栈选型背后的逻辑项目选择Next.js、React、TypeScript这套组合拳在今天的全栈开发中几乎是“黄金标准”。Next.js提供了服务端渲染、API路由、文件路由等开箱即用的能力非常适合构建这种兼具复杂交互和实时数据要求的Web应用。React的组件化让前端UI比如聊天消息流、任务状态展示、工具调用列表等可以模块化地开发和维护。TypeScript的强类型检查对于这样一个涉及多种外部API集成、数据流复杂的项目来说是保障代码质量和开发体验的基石能有效避免许多低级错误尤其是在处理AI返回的非结构化数据时。后端和数据层选择Convex是一个颇具匠心的决定。Convex不是一个传统的ORM或数据库驱动而是一个实时数据库与后端函数一体化的平台。它最大的优势是简化了全栈开发中最繁琐的部分实时数据同步和服务器端逻辑。在HackerAI中用户的聊天会话、AI执行的任务状态、工具调用的历史记录等都需要实时地在前端展示。使用Convex开发者只需要定义数据模型和查询/变更函数前端通过订阅subscribe就能自动获得数据的实时更新无需自己搭建WebSocket或轮询逻辑。这大大降低了实现一个复杂、交互式AI应用的开发门槛。认证选择WorkOS而非常见的Auth.js或Clerk暗示了项目对企业级部署和团队协作的考量。WorkOS专注于为企业应用提供SSO、目录同步、合规性等功能如果HackerAI的目标是成为企业安全团队内部的协作工具这个选择就非常合理。对于个人使用或小团队你完全可以考虑替换为更轻量级的方案。2.3 安全沙箱AI代理的“安全带”让AI生成并执行代码是AI代理能力飞跃的关键也是最大的风险点。一个恶意的提示词或者模型的一个“幻觉”可能导致生成rm -rf /这样的危险命令。HackerAI通过集成E2B来解决这个问题。E2B提供了一个隔离的、临时的云沙箱环境。当AI模型决定要执行一段代码比如一个Python脚本来检查HTTP头时HackerAI的后端不会直接在主机上运行它而是将代码发送到E2B创建一个短暂的沙箱在沙箱内执行代码并将结果返回。沙箱生命周期结束后所有资源被销毁确保了主机环境的安全。这是构建可信AI代理不可或缺的一环。2.4 模块化与可扩展性设计从项目的依赖和配置看它采用了高度模块化的设计。AI模型提供商不绑定于一家通过OpenRouter可以灵活切换GPT、Claude、DeepSeek等多种模型。文件存储支持Convex原生存储和Amazon S3。搜索功能可以接入Perplexity或Jina AI。这种设计意味着你可以根据自身需求、预算和网络环境像搭积木一样组装你的HackerAI实例。如果你不需要网页搜索功能就不配置Perplexity的API如果你觉得OpenAI的API太贵可以通过OpenRouter切换到性价比更高的模型。这种灵活性对于开源项目的长期生态和用户适配至关重要。3. 环境准备与初始配置详解3.1 前置账户与API密钥申请在动手克隆代码之前你需要准备好一系列服务的账户和API密钥。这看起来繁琐但每一步都有其必要性和替代方案我会逐一解释。核心必需项OpenRouter 或 OpenAI这是AI的“大脑”。OpenRouter是一个聚合平台让你可以用一个API密钥访问众多模型包括GPT-4、Claude-3等通常价格更灵活有时还有免费额度。OpenAI则是直接源头。对于个人学习和测试我强烈建议先使用OpenRouter因为它新用户通常有免费额度足够你完成初步的探索。获取密钥后记下它我们称之为OPENROUTER_API_KEY或OPENAI_API_KEY。E2BAI代理的“安全执行层”。去E2B官网注册创建一个API密钥。这个密钥将允许你的应用创建和管理安全沙箱。记作E2B_API_KEY。Convex项目的数据库和后台逻辑层。访问Convex官网用GitHub账号登录非常方便。登录后你需要创建一个新项目ProjectConvex会为你自动生成一个部署环境通常是dev。在项目的设置Settings里你会找到两个关键信息CONVEX_DEPLOYMENT类似your-project-name和CONVEX_URL类似https://unique-name.convex.cloud。更重要的是你需要生成一个CONVEX_AUTH_KEY这个密钥用于在本地开发时你的Next.js应用能够安全地与Convex后端通信。WorkOS身份认证网关。注册WorkOS创建一个项目。在项目设置中你需要获取WORKOS_CLIENT_ID和WORKOS_API_KEY。此外你还需要配置一个重定向回调URLRedirect URI对于本地开发通常是http://localhost:3000/auth/callback。这个配置在WorkOS的“SSO Directory”设置里完成。可选但推荐项Upstash Redis用于速率限制。在高频使用或防止滥用时很重要。注册Upstash创建一个Redis数据库获取其REDIS_URL通常以redis://开头。Amazon S3如果你需要存储用户上传的文件如扫描报告、截图且希望独立于Convex存储可以配置S3。你需要AWS的ACCESS_KEY_ID和SECRET_ACCESS_KEY以及一个桶名BUCKET_NAME。Perplexity / Jina AI为AI代理添加联网搜索能力。Perplexity提供强大的搜索APIJina AI的Reader API可以高效提取网页正文内容。如果你希望AI能获取最新漏洞资讯或分析特定网页建议配置其中一个。3.2 本地开发环境搭建实操假设你已经安装了Node.js建议LTS版本和Git我们开始一步步操作。# 1. 克隆仓库到本地 git clone https://github.com/hackerai-tech/hackerai.git cd hackerai # 2. 安装依赖。项目使用 pnpm 作为包管理器速度更快磁盘空间利用更高效。 # 如果你没有pnpm先安装npm install -g pnpm pnpm install这一步会安装所有前端、后端以及Convex相关的依赖。如果网络不畅可以尝试配置国内镜像源。# 3. 运行设置脚本。这是最关键的一步它会引导你交互式地填写上面提到的所有环境变量。 pnpm run setup运行这个命令后终端会启动一个交互式命令行界面依次询问你各个API密钥和配置项。请将之前准备好的值逐一填入。这个脚本最终会在项目根目录生成一个.env.local文件。务必检查这个文件是否生成成功并且内容是否正确。这是连接所有外部服务的枢纽。注意.env.local文件包含你的所有敏感密钥绝对不要将其提交到Git仓库中。项目已经在.gitignore中排除了它但你自己也需再三确认。3.3 启动服务与初步验证配置完成后就可以启动开发服务器了。# 方式一使用便捷命令同时启动Next.js前端和Convex后端开发服务器 pnpm run dev# 方式二分别启动便于观察各自的日志推荐尤其调试时 # 终端1启动Convex后端 pnpm run dev:convex # 终端2启动Next.js前端 pnpm run dev:next启动成功后打开浏览器访问http://localhost:3000。你应该能看到HackerAI的登录界面。由于我们配置了WorkOS第一次访问会跳转到WorkOS的认证页面。你可以使用测试邮箱在WorkOS仪表板可以添加测试用户或者配置好的企业SSO进行登录。登录成功后你就进入了HackerAI的主界面。通常是一个聊天界面。至此基础环境搭建完成。你可以尝试和AI打个招呼比如输入“Hello”看看它是否正常响应。这验证了从前端到Convex再到AI模型API的整个链路是否通畅。4. 核心功能模块深度解析4.1 智能会话与上下文管理HackerAI的聊天界面并非简单的历史记录堆叠。其背后是Convex数据库对会话、消息、线程的精细化管理。每一次对话开启一个新的“会话”在一个会话中用户的每次输入和AI的每次回复组成一条“消息”。Convex的实时订阅能力使得任何一方的新消息都能立刻出现在所有客户端如果你在多标签页打开。更重要的是上下文管理。大模型有令牌Token数限制。HackerAI需要智能地维护对话历史将最相关的历史信息作为上下文传递给模型同时不能超出限制。项目很可能实现了以下几种策略滑动窗口只保留最近N条对话。关键信息总结当对话历史过长时调用模型对之前的对话进行总结将总结文本作为新的上下文替代冗长的原始历史。工具调用历史嵌入将之前工具如Nmap扫描的执行结果摘要化后嵌入上下文让AI记住它已经做过什么。你可以在convex/目录下的schema文件中查看数据表设计在convex/chat.ts或类似命名的函数中查看消息处理与上下文组装的逻辑。理解这部分对于你后续定制对话行为或集成自己的知识库至关重要。4.2 工具调用框架与安全执行这是AI代理的核心。HackerAI预定义了一系列安全测试相关的“工具”供AI调用。这些工具本质上是一系列函数每个函数有清晰的名称、描述、参数列表。例如可能有一个名为nmap_scan的工具描述是“对指定目标进行TCP SYN端口扫描”参数是target: string, ports: string。当用户提出“扫描一下example.com的开放端口”时AI模型会根据对话历史和工具描述决定调用nmap_scan工具并生成符合要求的参数{target: example.com, ports: 1-1000}。这个请求从前端发送到Convex。Convex的后端函数Action接收到调用请求后不会直接执行nmap命令。因为Convex的函数运行在Serverless环境中权限受限。此时项目设计会通过E2B的SDK在安全沙箱中执行一个安装了Nmap的容器并运行相应的命令。执行流程如下// 伪代码示意 async function executeToolInSandbox(toolName: string, args: any) { // 1. 根据工具名准备要在沙箱中执行的脚本或命令 const command prepareCommand(toolName, args); // 例如: nmap -sS -p 1-1000 example.com // 2. 创建E2B沙箱环境可能是一个预装了安全工具的镜像 const sandbox await e2b.sandbox.create(security-tools-image); // 3. 在沙箱内执行命令 const result await sandbox.process.run({ cmd: command }); // 4. 销毁沙箱清理资源 await sandbox.close(); // 5. 将标准输出、错误、退出码等结果返回 return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, // 可能还会对结果进行初步解析如将Nmap的XML输出解析为结构化JSON parsedResult: parseNmapOutput(result.stdout) }; }执行结果返回给Convex函数Convex函数将其作为一条新的“工具调用结果”消息存入数据库并触发前端更新。AI模型会看到这个结果并基于结果生成下一步的自然语言回复或工具调用决策。实操心得工具的定义质量直接决定AI代理的能力上限。工具的描述必须清晰、无歧义参数格式要明确。在自定义工具时要像设计API接口一样严谨。同时要仔细考虑沙箱环境的基础镜像确保包含了所有你希望AI能使用的命令行工具。4.3 文件处理与存储策略在渗透测试中上传下载文件是常事比如上传一个自定义的字典进行爆破或者下载扫描生成的报告。HackerAI通过Convex的原生文件存储或可选的S3来处理文件。当用户上传文件时前端将文件数据发送到Convex的一个文件上传接口Mutation。Convex会将其存储在自己的Blob存储中并返回一个唯一的文件ID和存储URL。这个文件ID会与聊天消息关联。当AI需要分析文件内容比如分析一个包含子域名的文本文件时后端函数可以根据文件ID读取文件内容并将其作为上下文的一部分发送给AI模型。如果配置了S3流程类似只是存储位置换成了你指定的S3桶。选择S3的优势在于存储容量更大、成本可能更低并且便于与其他AWS服务集成。4.4 搜索与知识增强配置了Perplexity或Jina AI后AI代理就具备了“联网”能力。当用户的问题涉及最新事件如“昨天披露的XXX漏洞有什么影响”或需要分析某个特定网页时AI可以自主调用搜索工具。例如工具search_web的描述可能是“使用搜索引擎获取最新信息”。AI调用该工具参数为查询词。后端函数调用Perplexity API进行搜索将返回的摘要或链接内容整理后返回给AI。AI再基于这些实时信息进行回答。这极大地扩展了AI的知识时效性和应用场景。5. 自定义与高级配置指南5.1 如何添加自定义工具这是将HackerAI适配到你自身工作流的关键。假设你想添加一个内部使用的漏洞验证工具check_internal_vuln。定义工具接口在Convex后端通常有一个统一管理工具的地方比如convex/tools.ts。你需要在这里添加新工具的定义。// convex/tools.ts export const tools { // ... 已有工具 check_internal_vuln: { description: “检查目标系统是否存在已知的内部漏洞库中的漏洞。需要目标IP和漏洞ID。”, parameters: z.object({ targetIp: z.string().describe(“目标系统的IP地址”), vulnId: z.string().describe(“内部漏洞库中的漏洞标识符如 INT-2024-001”) }), execute: async ({ targetIp, vulnId }) { // 这里是工具的执行逻辑 // 1. 可以调用内部API // 2. 或者在E2B沙箱中运行一个自定义脚本 const result await yourInternalVulnCheckerAPI(targetIp, vulnId); return { success: result.isVulnerable, message: result.details, rawData: result }; } } } as const;这里用了Zod进行参数验证确保AI传入的参数格式正确。更新AI系统提示词AI模型需要知道这个新工具的存在。系统提示词System Prompt定义了AI的角色和能力。你需要在提示词模板中将新工具的描述和用法加入到工具列表里。这个提示词可能位于app/api/chat/下的某个文件或Convex的函数中。处理工具执行上述execute函数是关键。对于涉及代码执行或外部调用的工具你需要在其中集成E2B沙箱调用或HTTP请求。确保错误处理完善将任何执行失败的信息清晰地返回给AI以便它能理解并回复用户。测试在UI中发起对话尝试用自然语言触发你的新工具比如“用内部漏洞库检查一下192.168.1.10的INT-2024-001漏洞”。观察AI是否能正确识别并调用工具以及工具执行和结果返回是否正常。5.2 模型切换与性能调优通过OpenRouter你可以轻松切换模型。在环境变量或配置文件中可以指定模型ID例如openrouter:openai/gpt-4-turbo-preview或openrouter:anthropic/claude-3-opus-20240229。不同的模型在理解能力、工具调用准确性和成本上差异巨大。对于安全领域的复杂推理和精确的工具调用GPT-4或Claude-3 Opus这类顶级模型效果更好但价格昂贵。对于一般性的问答和简单任务可以考虑成本更低的模型如GPT-3.5-Turbo或Claude-3 Haiku。调优建议系统提示词工程精心设计系统提示词是提升AI表现性价比最高的方式。明确告诉AI它的角色“你是一个专业的渗透测试助手”、行为准则“只提供符合伦理的安全建议”、“在采取潜在破坏性行动前请求确认”、可用的工具以及工具使用的格式。温度Temperature设置降低温度值如0.1-0.3可以使AI的输出更确定、更专注于工具调用减少“胡言乱语”。在需要创造性生成如编写钓鱼邮件模板时可以适当调高。令牌限制合理设置max_tokens防止生成过长的无关内容同时也要给足AI输出完整工具调用和解释的空间。5.3 部署到生产环境本地开发完成后你可能想部署一个团队可用的版本。Convex部署在Convex Dashboard中将你的项目从开发环境dev推送到生产环境prod。通常使用命令npx convex deploy --prod。这会部署所有后端函数和schema。Next.js部署你可以选择Vercel与Next.js同源体验最佳、AWS、GCP或任何支持Node.js的托管平台。将代码仓库连接到部署平台并设置好生产环境的环境变量注意不是.env.local而是在平台提供的环境变量配置界面中填入。环境变量配置在生产环境确保所有API密钥OpenRouter, E2B, WorkOS等都替换为生产可用的密钥。特别是WorkOS需要将重定向URI更新为你的生产域名。域名与HTTPS配置自定义域名并启用HTTPS这是安全应用的基本要求。监控与日志利用Convex Dashboard的日志查看器、Vercel的日志功能或集成PostHog项目已支持来监控应用运行状态和用户行为。6. 常见问题与故障排查实录在实际搭建和使用过程中你几乎一定会遇到下面这些问题。这里记录了我的踩坑实录和解决方案。6.1 环境变量配置错误问题启动pnpm run dev后前端或后端报错提示某个API密钥无效或服务连接失败。排查首要检查确认.env.local文件是否在项目根目录且内容格式正确每行KEYVALUE没有多余空格特别是值里如果有特殊字符要正确处理。逐一验证OpenAI/OpenRouter可以写一个简单的Node.js脚本或用curl命令测试API密钥是否有效。Convex运行npx convex status检查本地环境是否能连通你的Convex项目。确保CONVEX_DEPLOYMENT和CONVEX_AUTH_KEY正确。WorkOS登录WorkOS仪表板检查客户端ID和API密钥是否对应以及回调URL是否精确匹配包括http/https和端口。E2B访问E2B控制台确认API密钥有权限并且额度未用完。重启服务修改.env.local后必须完全重启开发服务器CtrlC后重新运行pnpm run dev因为环境变量通常在启动时加载。6.2 Convex 函数同步失败问题运行pnpm run dev:convex时提示函数同步错误或schema验证失败。排查检查Convex CLI登录状态运行npx convex whoami确保你已登录且是当前项目所属账号。检查Schema定义错误信息通常会指向具体的表和字段。检查convex/schema.ts文件确保表名、字段名、类型定义正确没有语法错误。Convex对数据类型要求比较严格。检查函数导出所有在convex/目录下定义的函数Query, Mutation, Action都必须通过convex/_generated/api.js文件统一导出。确保你的新函数已正确添加。查看Convex Dashboard日志在Convex项目的Dashboard中查看“Logs”和“Errors”通常有更详细的错误堆栈信息。6.3 AI代理不调用工具或调用错误问题AI只会聊天当明确要求它执行扫描等操作时它回答“我无法执行此操作”或调用了错误的工具。排查检查系统提示词这是最常见的原因。AI是否在提示词中被清晰地告知了可用的工具列表及其用法提示词中工具的描述是否准确、无歧义你可以尝试在对话中直接问AI“你现在可以调用哪些工具” 看它是否能正确列出。检查工具定义格式确保工具定义符合模型预期的格式如OpenAI的Function Calling格式或ReAct格式。参数schema使用Zod定义是否正确。模型能力确认你使用的模型支持工具调用Function Calling。GPT-3.5-Turbo和GPT-4系列都支持但一些通过OpenRouter接入的较小模型可能不支持或支持不好。尝试切换到GPT-4看问题是否解决。上下文长度如果对话历史过长工具定义可能被从上下文中截断。确保你的系统提示词包含工具定义在每次请求时都被包含在内或者实现上文提到的上下文总结策略。6.4 E2B沙箱执行超时或失败问题AI调用了工具但前端一直显示“执行中”最后超时或报错。排查沙箱资源限制E2B的免费套餐或某些配置可能有执行时间或资源的限制。检查E2B控制台的用量和日志。复杂的扫描命令如全端口扫描可能耗时过长导致超时。网络连通性沙箱需要从互联网下载工具如nmap或访问目标。确保你的命令在沙箱网络环境下是可行的。对于内网目标E2B沙箱显然无法访问。命令构造错误AI生成的命令参数可能有误导致命令执行失败。查看Convex或E2B的日志找到工具执行函数返回的具体错误信息stderr。根据错误信息调整工具的参数验证逻辑或AI的提示词。镜像缺失工具你定制的E2B沙箱镜像是否包含了所需的所有命令行工具默认的“安全工具”镜像可能没有某个特定工具。你需要在工具执行的代码中要么先安装工具apt-get install -y tool要么使用一个预装好的自定义镜像。6.5 认证失败或循环跳转问题访问localhost:3000时在WorkOS登录页面和本地应用间循环跳转无法进入主界面。排查回调URL不匹配这是99%的原因。请一字不差地核对WorkOS仪表板中配置的“Redirect URI”和你的应用实际使用的回调地址。本地开发通常是http://localhost:3000/auth/callback。确保没有多余的斜杠协议是http本地开发通常不用https。WorkOS客户端配置确保在.env.local中配置的WORKOS_CLIENT_ID和WORKOS_API_KEY来自同一个WorkOS项目。前端路由检查Next.js中认证回调的处理页面通常是app/auth/callback/page.tsx逻辑是否正确是否成功从URL参数中提取了code并交换了access_token以及是否正确处理了错误。6.6 性能优化与成本控制随着使用深入你可能会关心响应速度和API花费。响应慢模型响应换用更快的模型如Claude-3 Haiku通常比Opus快或降低模型的max_tokens。工具执行优化工具逻辑避免在AI循环中执行耗时极长的操作如全网段扫描。可以考虑异步执行先返回“任务已提交”再通过后台任务执行并通知结果。流式输出确保前端实现了流式响应Streaming让用户能边生成边看到内容提升感知速度。项目基于Next.js App Router应已支持。成本高模型选择在非关键任务中使用廉价模型。缓存对常见的、结果不变的工具调用如对某个知名站点的基本信息查询进行结果缓存。速率限制严格配置Upstash Redis进行API调用速率限制防止误操作或恶意调用导致账单爆炸。监控告警在OpenRouter、OpenAI等平台设置用量告警接近限额时收到通知。这个项目就像一个功能强大的乐高套装提供了基础框架和核心部件。真正的价值在于你如何根据自己的安全工作流去拼装和定制它。无论是集成内部扫描平台、添加专属的漏洞库查询还是训练一个专注于Web安全的微调模型作为其核心可能性都非常多。 AI代理架构在渗透测试中的应用：HackerAI项目深度解析
1. 项目概述一个AI驱动的渗透测试助手最近在安全圈子里一个名为HackerAI的开源项目引起了我的注意。简单来说它就是一个用AI来辅助渗透测试和安全研究的智能助手。想象一下你不再需要一个人埋头苦读那些复杂的漏洞报告或者一遍遍地在命令行里敲打重复的侦察命令而是有一个“懂行”的AI伙伴能帮你分析目标、生成攻击载荷、甚至解释一个复杂漏洞的利用原理。HackerAI就是奔着这个目标去的。它不是一个玩具而是一个架构相当完整、设计思路清晰的生产级工具旨在将大语言模型的推理能力与安全专家的实战经验结合起来提升安全评估的效率和深度。无论你是刚入门的安全爱好者想有个“师傅”带着你理解各种攻击手法还是经验丰富的红队成员希望有个智能副驾来处理繁琐的侦察和信息整理工作这个项目都值得你花时间研究一下。它的核心定位很明确AI-Powered Penetration Testing Assistant。这意味着它不仅仅是调用API生成一些文本而是构建了一个能够理解安全上下文、执行特定任务比如端口扫描结果分析、漏洞POC生成、并在受控环境中安全运行代码的智能体系统。项目采用了当前非常流行的技术栈包括Next.js、React、TypeScript作为前端和全栈基础并深度集成了Convex作为实时后端数据库以及WorkOS处理企业级身份认证。更关键的是它通过OpenRouter或OpenAI接入大模型并利用E2B提供的安全沙箱环境来执行AI生成的代码这解决了AI代理执行不可信代码时的核心安全隐患。接下来我就结合官方文档和我的实际搭建体验为你深度拆解这个项目的设计思路、核心模块以及如何从零开始部署和定制属于你自己的AI安全助手。2. 核心架构与设计思路拆解2.1 为什么是“AI代理”架构HackerAI没有做成一个简单的聊天机器人问你“有什么可以帮您”然后生成一些通用的安全建议。它采用的是AI代理架构。这两者有本质区别。传统的聊天交互是“一问一答”模型基于你的输入生成一段文本回复。而代理架构赋予了AI“行动”的能力。在这个框架下AI模型扮演一个“大脑”它可以规划任务、决定调用什么工具比如执行一个Nmap命令、搜索CVE数据库、执行工具、分析工具返回的结果并根据结果决定下一步行动直到达成目标。举个例子你给HackerAI一个目标域名example.com。一个简单的聊天模型可能会回复“你可以尝试进行子域名枚举、端口扫描、目录爆破等。” 而一个AI代理则会自主执行以下链条1. 调用子域名枚举工具如subfinder2. 分析枚举结果选取活跃子域名3. 对活跃子域名发起端口扫描如nmap -sS4. 分析开放的端口识别运行的服务如发现80端口运行Nginx 1.185. 基于服务版本搜索公开漏洞库6. 如果发现相关漏洞尝试生成一个简单的验证脚本。这一系列动作在HackerAI的代理模式下可以由AI自主或半自主地完成。这种设计思路极大地扩展了AI在安全运维中的实用性使其从一个“知识库”升级为一个“虚拟工程师”。2.2 技术栈选型背后的逻辑项目选择Next.js、React、TypeScript这套组合拳在今天的全栈开发中几乎是“黄金标准”。Next.js提供了服务端渲染、API路由、文件路由等开箱即用的能力非常适合构建这种兼具复杂交互和实时数据要求的Web应用。React的组件化让前端UI比如聊天消息流、任务状态展示、工具调用列表等可以模块化地开发和维护。TypeScript的强类型检查对于这样一个涉及多种外部API集成、数据流复杂的项目来说是保障代码质量和开发体验的基石能有效避免许多低级错误尤其是在处理AI返回的非结构化数据时。后端和数据层选择Convex是一个颇具匠心的决定。Convex不是一个传统的ORM或数据库驱动而是一个实时数据库与后端函数一体化的平台。它最大的优势是简化了全栈开发中最繁琐的部分实时数据同步和服务器端逻辑。在HackerAI中用户的聊天会话、AI执行的任务状态、工具调用的历史记录等都需要实时地在前端展示。使用Convex开发者只需要定义数据模型和查询/变更函数前端通过订阅subscribe就能自动获得数据的实时更新无需自己搭建WebSocket或轮询逻辑。这大大降低了实现一个复杂、交互式AI应用的开发门槛。认证选择WorkOS而非常见的Auth.js或Clerk暗示了项目对企业级部署和团队协作的考量。WorkOS专注于为企业应用提供SSO、目录同步、合规性等功能如果HackerAI的目标是成为企业安全团队内部的协作工具这个选择就非常合理。对于个人使用或小团队你完全可以考虑替换为更轻量级的方案。2.3 安全沙箱AI代理的“安全带”让AI生成并执行代码是AI代理能力飞跃的关键也是最大的风险点。一个恶意的提示词或者模型的一个“幻觉”可能导致生成rm -rf /这样的危险命令。HackerAI通过集成E2B来解决这个问题。E2B提供了一个隔离的、临时的云沙箱环境。当AI模型决定要执行一段代码比如一个Python脚本来检查HTTP头时HackerAI的后端不会直接在主机上运行它而是将代码发送到E2B创建一个短暂的沙箱在沙箱内执行代码并将结果返回。沙箱生命周期结束后所有资源被销毁确保了主机环境的安全。这是构建可信AI代理不可或缺的一环。2.4 模块化与可扩展性设计从项目的依赖和配置看它采用了高度模块化的设计。AI模型提供商不绑定于一家通过OpenRouter可以灵活切换GPT、Claude、DeepSeek等多种模型。文件存储支持Convex原生存储和Amazon S3。搜索功能可以接入Perplexity或Jina AI。这种设计意味着你可以根据自身需求、预算和网络环境像搭积木一样组装你的HackerAI实例。如果你不需要网页搜索功能就不配置Perplexity的API如果你觉得OpenAI的API太贵可以通过OpenRouter切换到性价比更高的模型。这种灵活性对于开源项目的长期生态和用户适配至关重要。3. 环境准备与初始配置详解3.1 前置账户与API密钥申请在动手克隆代码之前你需要准备好一系列服务的账户和API密钥。这看起来繁琐但每一步都有其必要性和替代方案我会逐一解释。核心必需项OpenRouter 或 OpenAI这是AI的“大脑”。OpenRouter是一个聚合平台让你可以用一个API密钥访问众多模型包括GPT-4、Claude-3等通常价格更灵活有时还有免费额度。OpenAI则是直接源头。对于个人学习和测试我强烈建议先使用OpenRouter因为它新用户通常有免费额度足够你完成初步的探索。获取密钥后记下它我们称之为OPENROUTER_API_KEY或OPENAI_API_KEY。E2BAI代理的“安全执行层”。去E2B官网注册创建一个API密钥。这个密钥将允许你的应用创建和管理安全沙箱。记作E2B_API_KEY。Convex项目的数据库和后台逻辑层。访问Convex官网用GitHub账号登录非常方便。登录后你需要创建一个新项目ProjectConvex会为你自动生成一个部署环境通常是dev。在项目的设置Settings里你会找到两个关键信息CONVEX_DEPLOYMENT类似your-project-name和CONVEX_URL类似https://unique-name.convex.cloud。更重要的是你需要生成一个CONVEX_AUTH_KEY这个密钥用于在本地开发时你的Next.js应用能够安全地与Convex后端通信。WorkOS身份认证网关。注册WorkOS创建一个项目。在项目设置中你需要获取WORKOS_CLIENT_ID和WORKOS_API_KEY。此外你还需要配置一个重定向回调URLRedirect URI对于本地开发通常是http://localhost:3000/auth/callback。这个配置在WorkOS的“SSO Directory”设置里完成。可选但推荐项Upstash Redis用于速率限制。在高频使用或防止滥用时很重要。注册Upstash创建一个Redis数据库获取其REDIS_URL通常以redis://开头。Amazon S3如果你需要存储用户上传的文件如扫描报告、截图且希望独立于Convex存储可以配置S3。你需要AWS的ACCESS_KEY_ID和SECRET_ACCESS_KEY以及一个桶名BUCKET_NAME。Perplexity / Jina AI为AI代理添加联网搜索能力。Perplexity提供强大的搜索APIJina AI的Reader API可以高效提取网页正文内容。如果你希望AI能获取最新漏洞资讯或分析特定网页建议配置其中一个。3.2 本地开发环境搭建实操假设你已经安装了Node.js建议LTS版本和Git我们开始一步步操作。# 1. 克隆仓库到本地 git clone https://github.com/hackerai-tech/hackerai.git cd hackerai # 2. 安装依赖。项目使用 pnpm 作为包管理器速度更快磁盘空间利用更高效。 # 如果你没有pnpm先安装npm install -g pnpm pnpm install这一步会安装所有前端、后端以及Convex相关的依赖。如果网络不畅可以尝试配置国内镜像源。# 3. 运行设置脚本。这是最关键的一步它会引导你交互式地填写上面提到的所有环境变量。 pnpm run setup运行这个命令后终端会启动一个交互式命令行界面依次询问你各个API密钥和配置项。请将之前准备好的值逐一填入。这个脚本最终会在项目根目录生成一个.env.local文件。务必检查这个文件是否生成成功并且内容是否正确。这是连接所有外部服务的枢纽。注意.env.local文件包含你的所有敏感密钥绝对不要将其提交到Git仓库中。项目已经在.gitignore中排除了它但你自己也需再三确认。3.3 启动服务与初步验证配置完成后就可以启动开发服务器了。# 方式一使用便捷命令同时启动Next.js前端和Convex后端开发服务器 pnpm run dev# 方式二分别启动便于观察各自的日志推荐尤其调试时 # 终端1启动Convex后端 pnpm run dev:convex # 终端2启动Next.js前端 pnpm run dev:next启动成功后打开浏览器访问http://localhost:3000。你应该能看到HackerAI的登录界面。由于我们配置了WorkOS第一次访问会跳转到WorkOS的认证页面。你可以使用测试邮箱在WorkOS仪表板可以添加测试用户或者配置好的企业SSO进行登录。登录成功后你就进入了HackerAI的主界面。通常是一个聊天界面。至此基础环境搭建完成。你可以尝试和AI打个招呼比如输入“Hello”看看它是否正常响应。这验证了从前端到Convex再到AI模型API的整个链路是否通畅。4. 核心功能模块深度解析4.1 智能会话与上下文管理HackerAI的聊天界面并非简单的历史记录堆叠。其背后是Convex数据库对会话、消息、线程的精细化管理。每一次对话开启一个新的“会话”在一个会话中用户的每次输入和AI的每次回复组成一条“消息”。Convex的实时订阅能力使得任何一方的新消息都能立刻出现在所有客户端如果你在多标签页打开。更重要的是上下文管理。大模型有令牌Token数限制。HackerAI需要智能地维护对话历史将最相关的历史信息作为上下文传递给模型同时不能超出限制。项目很可能实现了以下几种策略滑动窗口只保留最近N条对话。关键信息总结当对话历史过长时调用模型对之前的对话进行总结将总结文本作为新的上下文替代冗长的原始历史。工具调用历史嵌入将之前工具如Nmap扫描的执行结果摘要化后嵌入上下文让AI记住它已经做过什么。你可以在convex/目录下的schema文件中查看数据表设计在convex/chat.ts或类似命名的函数中查看消息处理与上下文组装的逻辑。理解这部分对于你后续定制对话行为或集成自己的知识库至关重要。4.2 工具调用框架与安全执行这是AI代理的核心。HackerAI预定义了一系列安全测试相关的“工具”供AI调用。这些工具本质上是一系列函数每个函数有清晰的名称、描述、参数列表。例如可能有一个名为nmap_scan的工具描述是“对指定目标进行TCP SYN端口扫描”参数是target: string, ports: string。当用户提出“扫描一下example.com的开放端口”时AI模型会根据对话历史和工具描述决定调用nmap_scan工具并生成符合要求的参数{target: example.com, ports: 1-1000}。这个请求从前端发送到Convex。Convex的后端函数Action接收到调用请求后不会直接执行nmap命令。因为Convex的函数运行在Serverless环境中权限受限。此时项目设计会通过E2B的SDK在安全沙箱中执行一个安装了Nmap的容器并运行相应的命令。执行流程如下// 伪代码示意 async function executeToolInSandbox(toolName: string, args: any) { // 1. 根据工具名准备要在沙箱中执行的脚本或命令 const command prepareCommand(toolName, args); // 例如: nmap -sS -p 1-1000 example.com // 2. 创建E2B沙箱环境可能是一个预装了安全工具的镜像 const sandbox await e2b.sandbox.create(security-tools-image); // 3. 在沙箱内执行命令 const result await sandbox.process.run({ cmd: command }); // 4. 销毁沙箱清理资源 await sandbox.close(); // 5. 将标准输出、错误、退出码等结果返回 return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, // 可能还会对结果进行初步解析如将Nmap的XML输出解析为结构化JSON parsedResult: parseNmapOutput(result.stdout) }; }执行结果返回给Convex函数Convex函数将其作为一条新的“工具调用结果”消息存入数据库并触发前端更新。AI模型会看到这个结果并基于结果生成下一步的自然语言回复或工具调用决策。实操心得工具的定义质量直接决定AI代理的能力上限。工具的描述必须清晰、无歧义参数格式要明确。在自定义工具时要像设计API接口一样严谨。同时要仔细考虑沙箱环境的基础镜像确保包含了所有你希望AI能使用的命令行工具。4.3 文件处理与存储策略在渗透测试中上传下载文件是常事比如上传一个自定义的字典进行爆破或者下载扫描生成的报告。HackerAI通过Convex的原生文件存储或可选的S3来处理文件。当用户上传文件时前端将文件数据发送到Convex的一个文件上传接口Mutation。Convex会将其存储在自己的Blob存储中并返回一个唯一的文件ID和存储URL。这个文件ID会与聊天消息关联。当AI需要分析文件内容比如分析一个包含子域名的文本文件时后端函数可以根据文件ID读取文件内容并将其作为上下文的一部分发送给AI模型。如果配置了S3流程类似只是存储位置换成了你指定的S3桶。选择S3的优势在于存储容量更大、成本可能更低并且便于与其他AWS服务集成。4.4 搜索与知识增强配置了Perplexity或Jina AI后AI代理就具备了“联网”能力。当用户的问题涉及最新事件如“昨天披露的XXX漏洞有什么影响”或需要分析某个特定网页时AI可以自主调用搜索工具。例如工具search_web的描述可能是“使用搜索引擎获取最新信息”。AI调用该工具参数为查询词。后端函数调用Perplexity API进行搜索将返回的摘要或链接内容整理后返回给AI。AI再基于这些实时信息进行回答。这极大地扩展了AI的知识时效性和应用场景。5. 自定义与高级配置指南5.1 如何添加自定义工具这是将HackerAI适配到你自身工作流的关键。假设你想添加一个内部使用的漏洞验证工具check_internal_vuln。定义工具接口在Convex后端通常有一个统一管理工具的地方比如convex/tools.ts。你需要在这里添加新工具的定义。// convex/tools.ts export const tools { // ... 已有工具 check_internal_vuln: { description: “检查目标系统是否存在已知的内部漏洞库中的漏洞。需要目标IP和漏洞ID。”, parameters: z.object({ targetIp: z.string().describe(“目标系统的IP地址”), vulnId: z.string().describe(“内部漏洞库中的漏洞标识符如 INT-2024-001”) }), execute: async ({ targetIp, vulnId }) { // 这里是工具的执行逻辑 // 1. 可以调用内部API // 2. 或者在E2B沙箱中运行一个自定义脚本 const result await yourInternalVulnCheckerAPI(targetIp, vulnId); return { success: result.isVulnerable, message: result.details, rawData: result }; } } } as const;这里用了Zod进行参数验证确保AI传入的参数格式正确。更新AI系统提示词AI模型需要知道这个新工具的存在。系统提示词System Prompt定义了AI的角色和能力。你需要在提示词模板中将新工具的描述和用法加入到工具列表里。这个提示词可能位于app/api/chat/下的某个文件或Convex的函数中。处理工具执行上述execute函数是关键。对于涉及代码执行或外部调用的工具你需要在其中集成E2B沙箱调用或HTTP请求。确保错误处理完善将任何执行失败的信息清晰地返回给AI以便它能理解并回复用户。测试在UI中发起对话尝试用自然语言触发你的新工具比如“用内部漏洞库检查一下192.168.1.10的INT-2024-001漏洞”。观察AI是否能正确识别并调用工具以及工具执行和结果返回是否正常。5.2 模型切换与性能调优通过OpenRouter你可以轻松切换模型。在环境变量或配置文件中可以指定模型ID例如openrouter:openai/gpt-4-turbo-preview或openrouter:anthropic/claude-3-opus-20240229。不同的模型在理解能力、工具调用准确性和成本上差异巨大。对于安全领域的复杂推理和精确的工具调用GPT-4或Claude-3 Opus这类顶级模型效果更好但价格昂贵。对于一般性的问答和简单任务可以考虑成本更低的模型如GPT-3.5-Turbo或Claude-3 Haiku。调优建议系统提示词工程精心设计系统提示词是提升AI表现性价比最高的方式。明确告诉AI它的角色“你是一个专业的渗透测试助手”、行为准则“只提供符合伦理的安全建议”、“在采取潜在破坏性行动前请求确认”、可用的工具以及工具使用的格式。温度Temperature设置降低温度值如0.1-0.3可以使AI的输出更确定、更专注于工具调用减少“胡言乱语”。在需要创造性生成如编写钓鱼邮件模板时可以适当调高。令牌限制合理设置max_tokens防止生成过长的无关内容同时也要给足AI输出完整工具调用和解释的空间。5.3 部署到生产环境本地开发完成后你可能想部署一个团队可用的版本。Convex部署在Convex Dashboard中将你的项目从开发环境dev推送到生产环境prod。通常使用命令npx convex deploy --prod。这会部署所有后端函数和schema。Next.js部署你可以选择Vercel与Next.js同源体验最佳、AWS、GCP或任何支持Node.js的托管平台。将代码仓库连接到部署平台并设置好生产环境的环境变量注意不是.env.local而是在平台提供的环境变量配置界面中填入。环境变量配置在生产环境确保所有API密钥OpenRouter, E2B, WorkOS等都替换为生产可用的密钥。特别是WorkOS需要将重定向URI更新为你的生产域名。域名与HTTPS配置自定义域名并启用HTTPS这是安全应用的基本要求。监控与日志利用Convex Dashboard的日志查看器、Vercel的日志功能或集成PostHog项目已支持来监控应用运行状态和用户行为。6. 常见问题与故障排查实录在实际搭建和使用过程中你几乎一定会遇到下面这些问题。这里记录了我的踩坑实录和解决方案。6.1 环境变量配置错误问题启动pnpm run dev后前端或后端报错提示某个API密钥无效或服务连接失败。排查首要检查确认.env.local文件是否在项目根目录且内容格式正确每行KEYVALUE没有多余空格特别是值里如果有特殊字符要正确处理。逐一验证OpenAI/OpenRouter可以写一个简单的Node.js脚本或用curl命令测试API密钥是否有效。Convex运行npx convex status检查本地环境是否能连通你的Convex项目。确保CONVEX_DEPLOYMENT和CONVEX_AUTH_KEY正确。WorkOS登录WorkOS仪表板检查客户端ID和API密钥是否对应以及回调URL是否精确匹配包括http/https和端口。E2B访问E2B控制台确认API密钥有权限并且额度未用完。重启服务修改.env.local后必须完全重启开发服务器CtrlC后重新运行pnpm run dev因为环境变量通常在启动时加载。6.2 Convex 函数同步失败问题运行pnpm run dev:convex时提示函数同步错误或schema验证失败。排查检查Convex CLI登录状态运行npx convex whoami确保你已登录且是当前项目所属账号。检查Schema定义错误信息通常会指向具体的表和字段。检查convex/schema.ts文件确保表名、字段名、类型定义正确没有语法错误。Convex对数据类型要求比较严格。检查函数导出所有在convex/目录下定义的函数Query, Mutation, Action都必须通过convex/_generated/api.js文件统一导出。确保你的新函数已正确添加。查看Convex Dashboard日志在Convex项目的Dashboard中查看“Logs”和“Errors”通常有更详细的错误堆栈信息。6.3 AI代理不调用工具或调用错误问题AI只会聊天当明确要求它执行扫描等操作时它回答“我无法执行此操作”或调用了错误的工具。排查检查系统提示词这是最常见的原因。AI是否在提示词中被清晰地告知了可用的工具列表及其用法提示词中工具的描述是否准确、无歧义你可以尝试在对话中直接问AI“你现在可以调用哪些工具” 看它是否能正确列出。检查工具定义格式确保工具定义符合模型预期的格式如OpenAI的Function Calling格式或ReAct格式。参数schema使用Zod定义是否正确。模型能力确认你使用的模型支持工具调用Function Calling。GPT-3.5-Turbo和GPT-4系列都支持但一些通过OpenRouter接入的较小模型可能不支持或支持不好。尝试切换到GPT-4看问题是否解决。上下文长度如果对话历史过长工具定义可能被从上下文中截断。确保你的系统提示词包含工具定义在每次请求时都被包含在内或者实现上文提到的上下文总结策略。6.4 E2B沙箱执行超时或失败问题AI调用了工具但前端一直显示“执行中”最后超时或报错。排查沙箱资源限制E2B的免费套餐或某些配置可能有执行时间或资源的限制。检查E2B控制台的用量和日志。复杂的扫描命令如全端口扫描可能耗时过长导致超时。网络连通性沙箱需要从互联网下载工具如nmap或访问目标。确保你的命令在沙箱网络环境下是可行的。对于内网目标E2B沙箱显然无法访问。命令构造错误AI生成的命令参数可能有误导致命令执行失败。查看Convex或E2B的日志找到工具执行函数返回的具体错误信息stderr。根据错误信息调整工具的参数验证逻辑或AI的提示词。镜像缺失工具你定制的E2B沙箱镜像是否包含了所需的所有命令行工具默认的“安全工具”镜像可能没有某个特定工具。你需要在工具执行的代码中要么先安装工具apt-get install -y tool要么使用一个预装好的自定义镜像。6.5 认证失败或循环跳转问题访问localhost:3000时在WorkOS登录页面和本地应用间循环跳转无法进入主界面。排查回调URL不匹配这是99%的原因。请一字不差地核对WorkOS仪表板中配置的“Redirect URI”和你的应用实际使用的回调地址。本地开发通常是http://localhost:3000/auth/callback。确保没有多余的斜杠协议是http本地开发通常不用https。WorkOS客户端配置确保在.env.local中配置的WORKOS_CLIENT_ID和WORKOS_API_KEY来自同一个WorkOS项目。前端路由检查Next.js中认证回调的处理页面通常是app/auth/callback/page.tsx逻辑是否正确是否成功从URL参数中提取了code并交换了access_token以及是否正确处理了错误。6.6 性能优化与成本控制随着使用深入你可能会关心响应速度和API花费。响应慢模型响应换用更快的模型如Claude-3 Haiku通常比Opus快或降低模型的max_tokens。工具执行优化工具逻辑避免在AI循环中执行耗时极长的操作如全网段扫描。可以考虑异步执行先返回“任务已提交”再通过后台任务执行并通知结果。流式输出确保前端实现了流式响应Streaming让用户能边生成边看到内容提升感知速度。项目基于Next.js App Router应已支持。成本高模型选择在非关键任务中使用廉价模型。缓存对常见的、结果不变的工具调用如对某个知名站点的基本信息查询进行结果缓存。速率限制严格配置Upstash Redis进行API调用速率限制防止误操作或恶意调用导致账单爆炸。监控告警在OpenRouter、OpenAI等平台设置用量告警接近限额时收到通知。这个项目就像一个功能强大的乐高套装提供了基础框架和核心部件。真正的价值在于你如何根据自己的安全工作流去拼装和定制它。无论是集成内部扫描平台、添加专属的漏洞库查询还是训练一个专注于Web安全的微调模型作为其核心可能性都非常多。