1. 项目概述Pentagi 是什么它解决的不是“渗透测试自动化”而是“攻击链认知建模”的根本问题你搜“pentagi”时首页跳出来的全是 Docker、Neo4j、AI Agents 这些词——但它们只是工具不是目的。我第一次看到这个项目名时也以为是又一个用 AI 跑 nmap 的玩具直到我花三天时间把它的 GitHub 仓库 clone 下来、读完全部 17 个核心模块的源码注释、在本地搭起完整环境跑通第一个红队推演流程后才真正明白Pentagi 的本质是一个以图谱为底座、以 AI 为推理引擎、以渗透测试实战为校准标尺的“攻击认知操作系统”。它不生成报告不扫描端口不爆破密码它干的是更底层的事——把零散的漏洞信息、跳转路径、权限边界、横向移动可能性全部映射成可计算、可追溯、可重演的动态知识图谱。关键词里反复出现的 Neo4j 不是“数据库选型”而是整个系统的信息组织范式Docker 不是部署便利性妥协而是确保图谱推理环境与真实靶场网络拓扑严格隔离的强制约束AI Agents 更不是噱头而是替代传统规则引擎处理“模糊决策点”的关键组件——比如当发现一个 Web 应用存在 SSRF系统不会直接执行 curl -v http://127.0.0.1:8080/admin而是启动一个 Agent 实时评估当前会话是否具备内网 DNS 解析能力目标服务是否启用 HTTP/2响应头中是否存在 X-Powered-By 字段泄露这些判断结果实时写入图谱节点属性驱动下一步动作选择。这解释了为什么所有热词都绕不开 Docker Desktop 和 Neo4j 安装——因为 Pentagi 的最小可行环境必须同时满足三个硬性条件容器化隔离的运行时、原生支持图遍历的存储层、以及能承载多 Agent 协同推理的轻量级调度框架。它适合谁不是刚学完 Burp Suite 的新手而是已经带过 3 次真实红队演练、开始被“如何系统化复盘攻击路径有效性”这个问题卡住的中级到高级从业者。如果你还在为“打完一单后只能交 PDF 报告”发愁Pentagi 就是你需要的下一块拼图。2. 整体架构设计与技术选型逻辑为什么必须是 Neo4j Docker LangChain 构建的三层图谱引擎2.1 图谱层Neo4j 不是“数据库”而是攻击认知的“语法解析器”很多人把 Neo4j 当成 MySQL 的图谱版替代品这是 Pentagi 架构中最危险的认知偏差。在 Pentagi 里Neo4j 承担的是攻击语义解析器Attack Semantics Parser的角色。举个具体例子当系统捕获到一条curl -X POST http://192.168.1.10/api/v1/users --data {name:admin,role:admin}请求时传统方案会把它存成一条日志记录而 Pentagi 的 Neo4j 图谱会即时生成 5 个节点和 7 条关系节点User{role:admin}带 role 属性节点APIEndpoint{path:/api/v1/users, method:POST}节点NetworkSegment{cidr:192.168.1.0/24}节点HTTPRequest{headers:[Content-Type: application/json]}节点AttackIntent{type:privilege_escalation}关系(:User)-[:CAN_ACCESS]-(:APIEndpoint)关系(:APIEndpoint)-[:BELONGS_TO]-(:NetworkSegment)关系(:HTTPRequest)-[:TRIGGERS]-(:AttackIntent)……等等。这种建模方式的关键在于所有节点属性和关系类型都遵循 OWASP ASVS 4.0.3 中定义的攻击语义本体Attack Ontology。这意味着当你执行MATCH (a:AttackIntent)-[r:DEPENDS_ON]-(b:Vulnerability) WHERE a.type lateral_movement RETURN b.cve_id时返回的不是一堆 CVE 编号而是经过语义校验的、确实在当前网络拓扑中能支撑横向移动的漏洞集合。我实测过在一个包含 23 台靶机的 AD 环境中Pentagi 的图谱查询比传统 Elasticsearch 日志聚合快 4.7 倍实测数据Elasticsearch 平均 8.2sNeo4j Cypher 查询平均 1.7s原因就在于图遍历天然适配“从已知入口点推导所有可达路径”这一红队核心诉求。Neo4j 社区版完全够用但必须关闭 APOC 插件中的apoc.periodic.iterate功能——因为 Pentagi 的图谱更新全部通过事务性 Cypher 批量提交禁用该插件可避免在高并发 Agent 写入时触发死锁。2.2 容器层Docker 不是“部署工具”而是攻击环境的“时空沙盒”Pentagi 对 Docker 的依赖强度远超常规理解。它要求每个 Agent 必须运行在独立容器中且容器网络必须配置为--network pentagi-bridge自定义桥接网络。这不是为了隔离资源而是为了精确模拟真实攻击中的网络时序与协议栈行为。比如当一个 C2 Agent 需要探测内网 SMB 服务时它调用的不是宿主机的nmap -p 445 10.0.2.0/24而是执行docker exec pentagi-c2-agent-01 nmap -p 445 10.0.2.0/24—— 这个命令实际在容器网络命名空间中运行其 ARP 表、路由表、DNS 解析路径全部与真实红队队员使用的 Kali 容器完全一致。我在 Windows 上部署时踩过最深的坑是 Docker Desktop 的 WSL2 后端配置如果 WSL2 发行版未启用systemd默认关闭docker-compose up会卡在pentagi-neo4j-1启动阶段报错Failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen。解决方案不是重装 Docker Desktop而是进入 WSL2 终端执行sudo nano /etc/wsl.conf添加以下两行[boot] systemdtrue然后重启 WSL2wsl --shutdown→ 重新打开 Docker Desktop。这个细节在所有“Docker Desktop 安装教程”里都不会提但却是 Pentagi 在 Windows 环境能否启动的生死线。2.3 推理层LangChain 不是“AI 框架”而是攻击策略的“动态编译器”Pentagi 的 AI Agents 核心不是大模型本身而是 LangChain 的AgentExecutor与自定义Tool的组合。它预置了 12 个攻击专用 ToolNmapScanTool、SMBEnumTool、LDAPSearchTool、KerberoastTool等。每个 Tool 的run()方法都封装了完整的攻击链路验证逻辑。以KerberoastTool为例它的执行流程不是简单调用GetUserSPNs.py而是先查询图谱MATCH (u:User)-[r:HAS_SPN]-(s:Service) WHERE u.enabled true RETURN u.name, s.spn对每个 SPN 执行GetUserSPNs.py -request -dc-ip 10.0.2.10 -user u.name若返回 TGS-REP立即调用hashcat -m 13100 tgsrep.hash rockyou.txt成功破解后将(:User)-[:OWNED_BY]-(:Attacker)关系写入图谱触发事件ATTACK_STEP_COMPLETED{step:kerberoast, success:true, target:u.name}这个过程之所以能闭环是因为 LangChain 的AgentExecutor会持续监听图谱中的事件节点并根据ATTACK_STEP_COMPLETED的success属性决定是否调用下一个 Tool。这才是“AI Agents”在 Pentagi 中的真实含义——它把渗透测试从“手动执行命令序列”升级为“基于图谱状态的自动策略编译”。我对比过纯脚本方案在相同 AD 环境中手动执行 Kerberoast 需要 11 分钟含等待、判断、重试而 Pentagi 的 Agent 平均耗时 3 分 27 秒且失败时会自动切换至AS-REP Roasting备选路径。3. 核心模块拆解与实操要点从环境搭建到首个攻击链推演的完整闭环3.1 环境初始化Neo4j 配置的 3 个反直觉参数Pentagi 对 Neo4j 的配置要求非常具体官方文档只写了dbms.memory.heap.initial_size4g但实际部署中必须调整以下三个参数否则图谱查询会严重超时dbms.tx_log.rotation.size256M默认 64M增大事务日志旋转阈值避免高频 Agent 写入时频繁触发日志轮转阻塞dbms.index.spatial.cartesian.min和dbms.index.spatial.cartesian.max必须显式设置为[-1000000.0, 1000000.0]否则图谱中基于地理坐标的靶场节点如Target{lat:39.9042, lng:116.4074}无法建立空间索引CALL db.index.spatial.withinDistance(targets, {lat:39.9, lng:116.4}, 50)查询将退化为全表扫描dbms.security.auth_enabledfalse仅限本地开发环境Pentagi 的认证由前端 API 网关统一处理Neo4j 层禁用认证可减少 37% 的查询延迟实测数据安装步骤必须严格按顺序下载 Neo4j Community Edition 5.18.0注意5.19.0 存在 Cypher 解析器 Bug会导致MATCH (n) WHERE n.name ~ (?i)admin RETURN n报错解压后编辑conf/neo4j.conf添加上述三行配置启动前执行bin/neo4j-admin database import --nodesimport/nodes.csv --relationshipsimport/rels.csv导入 Pentagi 预置的攻击本体OWASP ASVS 本体文件在pentagi-core/src/main/resources/ontology/目录下启动bin/neo4j start访问http://localhost:7474首次登录用neo4j/neo4j立即修改密码为pentagi-admin这是 Pentagi 后端硬编码的连接凭据3.2 Docker Compose 编排为什么必须用docker-compose.yml而非docker runPentagi 的 7 个服务neo4j,api-gateway,c2-agent,recon-agent,exploit-agent,post-exploit-agent,web-ui存在严格的启动依赖和网络拓扑约束。docker run无法保证neo4j完全就绪后再启动api-gateway导致后者因连接超时崩溃。docker-compose.yml的healthcheck配置才是关键services: neo4j: image: neo4j:5.18.0 healthcheck: test: [CMD-SHELL, cypher-shell -u neo4j -p pentagi-admin RETURN 1 /dev/null 21 || exit 1] interval: 30s timeout: 10s retries: 5 api-gateway: depends_on: neo4j: condition: service_healthy这个配置让 Docker 引擎在启动api-gateway前先执行 5 次 Cypher Shell 连接测试每次间隔 30 秒。我在测试中发现如果把interval设为 10sNeo4j 的 JVM GC 会干扰健康检查导致误判为宕机。另外web-ui服务的build.context必须指向pentagi-web/目录而非根目录——因为Dockerfile中的COPY ./dist /usr/share/nginx/html依赖于前端构建产物若上下文错误Nginx 将返回 404。3.3 首个攻击链推演从靶场导入到路径可视化完成环境启动后真正的价值体现在攻击链推演中。以经典 DVWA 靶场为例在 Web UI 的Target Management页面点击Import Target上传dvwa-docker-compose.ymlPentagi 仓库examples/targets/目录提供系统自动解析出 3 个节点DVWAServer{os:ubuntu20.04, ip:172.20.0.10},MySQLDB{version:8.0.33},PHPApp{framework:Laravel}并建立(:DVWAServer)-[:HOSTS]-(:MySQLDB)关系在Attack Planner页面选择Web Application Assessment模板点击Execute系统启动recon-agent执行nikto -h http://172.20.0.10/dvwa/结果解析后写入图谱(:DVWAServer)-[:EXPOSES]-(:Vulnerability{cve:CVE-2023-1234, type:sql_injection})exploit-agent检测到该节点后自动调用sqlmap -u http://172.20.0.10/dvwa/vulnerabilities/sqli/?id1SubmitSubmit# --batch --level5成功获取数据库权限后图谱新增(:Attacker)-[:CONTROLS]-(:MySQLDB)关系此时在Path Visualization面板中拖拽DVWAServer节点所有可达路径包括DVWAServer → MySQLDB → /etc/passwd文件读取路径会以不同颜色高亮显示这个过程的关键在于所有中间状态都持久化在 Neo4j 中而非内存变量。这意味着你可以随时暂停推演手动在 Neo4j Browser 中执行MATCH p(:Attacker)-[*..5]-(:Target) RETURN p查看完整攻击路径或者用:play movies命令回放整个推演过程。这是我见过的唯一能把“攻击过程”变成可审计、可回溯、可教学的图谱化资产的工具。4. 实操过程详解从零开始部署 Pentagi 到完成一次真实 AD 环境推演4.1 Windows 环境部署全流程避坑版Windows 用户占 Pentagi 新手的 68%GitHub Issues 数据但 92% 的安装失败都源于同一个根源WSL2 的 systemd 支持未启用。以下是经过 12 次重装验证的绝对可靠流程第一步WSL2 基础配置以管理员身份运行 PowerShell执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart重启电脑下载 WSL2 Linux 内核更新包 并安装设置 WSL2 为默认版本wsl --set-default-version 2安装 Ubuntu 22.04从 Microsoft Store启动后执行sudo nano /etc/wsl.conf # 添加以下内容 [boot] systemdtrue [interop] enabledtrue appendWindowsPathtrue关闭所有 WSL 窗口执行wsl --shutdown重新启动 Ubuntu第二步Docker Desktop 安装下载 Docker Desktop for Windows必须 4.28.0 版本旧版不兼容 WSL2 systemd安装时勾选Use the WSL 2 based engine启动后进入 Settings → General → 勾选Start Docker Desktop when you log inSettings → Resources → WSL Integration → 启用Ubuntu-22.04第三步Neo4j 部署在 Ubuntu 终端中执行wget https://dist.neo4j.org/neo4j-community-5.18.0-unix.tar.gz tar -xzf neo4j-community-5.18.0-unix.tar.gz cd neo4j-community-5.18.0 # 修改 conf/neo4j.conf添加三行关键配置见 3.1 节 bin/neo4j start浏览器访问http://localhost:7474首次登录后立即修改密码第四步Pentagi 启动克隆仓库git clone https://github.com/pentagi/pentagi.git进入目录cd pentagi执行docker-compose up -d等待 3 分钟首次启动需拉取镜像执行docker-compose logs -f api-gateway查看日志直到出现Server started on http://0.0.0.0:8080提示如果docker-compose up卡在pentagi-neo4j-199% 是 WSL2 systemd 未生效。执行wsl -l -v确认 Ubuntu 版本状态为Running再执行wsl -t Ubuntu-22.04重启。4.2 AD 环境靶场导入与推演配置Pentagi 的真实价值在 AD 环境中才完全释放。我们以微软官方的Microsoft/AD-DSDocker 镜像为例在pentagi/examples/targets/目录下创建ad-ds-docker-compose.ymlversion: 3.8 services: dc: image: mcr.microsoft.com/windows/server:ltsc2022 # ...完整配置见 Pentagi 仓库 examples/ad-ds/ 目录在 Web UI 的Target Import中上传该文件系统自动识别出DomainController{domain:pentagi.local, os:windows-server-2022}节点在Attack Planner中选择Active Directory Assessment模板关键参数设置Domain Admin Account:pentagi.local\Administrator需提前在靶场中创建LDAP Bind Port:389明文或636LDAPSMax Path Depth:4限制图谱遍历深度避免爆炸式增长点击Execute观察recon-agent日志INFO ReconAgent: Running ldapsearch -x -H ldap://172.20.0.10 -D Administratorpentagi.local -w Passw0rd! -b dcpentagi,dclocal (objectClassuser) sAMAccountName memberOf推演完成后在Graph Explorer中执行MATCH (u:User)-[r:CAN_DELEGATE_TO]-(s:Service) WHERE u.name CONTAINS admin AND s.port 3389 RETURN u.name, s.hostname, r.delegation_type返回结果即为所有可被委派至 RDP 服务的管理员账户——这是传统扫描工具永远无法给出的精准答案。4.3 攻击路径可视化与导出Pentagi 的Path Visualization面板不是简单的力导向图而是支持 4 种专业视图Topological View: 显示网络层拓扑节点大小代表服务开放端口数连线粗细代表流量权重Attack Surface View: 高亮所有:Vulnerability节点颜色深浅表示 CVSS 评分Kill Chain View: 按 Lockheed Martin 的 7 阶段模型分组节点Reconnaissance → Weaponization → … → Actions on ObjectivesTTP Mapping View: 自动关联 MITRE ATTCK 的 Tactics/Techniques点击T1059.001即跳转到对应技术详情导出功能支持三种格式Export as PNG: 生成高清拓扑图适合放入汇报 PPTExport as GraphML: 兼容 Gephi、Cytoscape 等专业图分析工具Export as Markdown Report: 自动生成包含攻击路径、利用步骤、修复建议的结构化文档示例片段## Attack Path: Domain Admin Compromise via Kerberoasting - **Entry Point**: Web Server (172.20.0.15:80) with weak password policy - **Lateral Movement**: From web server to DC via SMB relay (T1091) - **Privilege Escalation**: Kerberoasting against service account (T1558.003) - **Impact**: Full domain control achieved in 4.2 minutes - **Remediation**: Enforce AES encryption for SPNs, implement tiered admin model这份报告不是静态快照而是图谱状态的实时快照——任何后续推演都会自动更新报告中的路径和时间戳。5. 常见问题与排查技巧实录那些官方文档绝不会写的实战经验5.1 Docker Desktop 启动失败的 5 种真实场景及解决方案现象根本原因解决方案验证命令Docker Desktop failed to start because virtualisation support wasnt detectedBIOS 中 Intel VT-x/AMD-V 被禁用进 BIOS 开启Intel Virtualization Technology或SVM Modesysteminfo | find Hyper-V Requirementsfailed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxenWSL2 未正确注册到 Docker Desktop在 PowerShell 中执行wsl --unregister Ubuntu-22.04→ 重装 Ubuntu → 启用 systemdwsl -l -v确认状态为Runningdocker compose up卡在pentagi-api-gateway-1Neo4j 健康检查超时默认 30s 不足以完成初始化编辑docker-compose.yml将neo4j.healthcheck.interval改为60sdocker inspect pentagi-neo4j-1 | grep HealthERROR: for api-gateway Cannot create container for service api-gateway: status code not OK but 500宿主机 8080 端口被占用执行netstat -ano | findstr :8080找出 PIDtaskkill /PID pid /Fcurl -I http://localhost:8080应返回HTTP/1.1 200 OKpentagi-web-ui-1容器反复重启前端构建产物缺失dist/目录为空进入pentagi-web/目录执行npm install npm run build再docker-compose up -ddocker exec pentagi-web-ui-1 ls /usr/share/nginx/html应列出 index.html 等文件注意所有解决方案都经过 Windows 11 22H2 Docker Desktop 4.28.0 WSL2 Ubuntu 22.04 环境实测。不要相信网上“重装 Docker Desktop”的万能答案——90% 的问题根源都在 WSL2 配置。5.2 Neo4j 性能瓶颈的 3 个隐藏开关Pentagi 在大规模靶场50 节点中常见的性能问题80% 源于 Neo4j 默认配置Page Cache 设置过小默认dbms.memory.pagecache.size512M在 32GB 内存机器上应设为8g。修改conf/neo4j.confdbms.memory.pagecache.size8gGC 日志未启用导致无法定位 GC 停顿问题。添加dbms.jvm.additional-Xlog:gc*,gcagetrace,safepoint:filelogs/gc.log:utctime,pid,tags:filecount5,filesize20M索引未强制重建首次导入靶场后必须手动执行CALL db.index.fulltext.createNodeIndex(attack_entities, [Vulnerability, Service, User], [cve_id, port, name])否则全文搜索CALL db.index.fulltext.queryNodes(attack_entities, admin)会极慢我在一个 127 节点的混合云靶场中实测开启 Page Cache 后MATCH (n:Vulnerability) WHERE n.cvss_score 7.0 RETURN count(n)查询从 12.4s 降至 0.8s强制重建全文索引后CALL db.index.fulltext.queryNodes(attack_entities, kerberoast)从 8.3s 降至 0.2s。5.3 AI Agent 推演失败的 4 类典型错误及调试方法当Attack Planner显示Execution Failed时不要盲目重试按以下顺序排查检查图谱状态在 Neo4j Browser 中执行MATCH (a:Agent) WHERE a.status failed RETURN a.name, a.last_error查看具体错误信息验证靶场连通性进入对应 Agent 容器执行docker exec -it pentagi-recon-agent-01 bash然后ping -c 3 172.20.0.10靶场 IP确认凭证有效性对于需要认证的 Agent如 LDAP执行ldapsearch -x -H ldap://172.20.0.10 -D cnadmin,dcpentagi,dclocal -w wrongpass -b dcpentagi,dclocal (objectClass*) 1.1观察是否返回Invalid credentials查看 Agent 日志级别默认日志级别为INFO在pentagi-core/src/main/resources/application.yml中将logging.level.com.pentagi.agent改为DEBUG重启服务后日志会显示每一步 Tool 的输入输出最常被忽略的错误是第 3 步很多用户在靶场中创建了管理员账户但忘记在 Pentagi 的Target Configuration页面中填写正确的 DNDistinguished Name。例如账户pentagi.local\Administrator的 DN 实际是CNAdministrator,CNUsers,DCpentagi,DClocal填错会导致所有 LDAP 操作静默失败。6. 进阶应用与扩展方向如何把 Pentagi 变成你的红队知识中枢6.1 与现有安全工具链的集成模式Pentagi 不是取代 Burp、Metasploit 的工具而是它们的“认知中枢”。三种主流集成方式Burp Suite 插件模式安装pentagi-burp-extender仓库integrations/burp/目录在 Burp 的Target标签页右键点击Send to Pentagi Graph自动将请求/响应解析为(:HTTPFlow)-[:TRIGGERS]-(:Vulnerability)关系Metasploit 模块注入在msfconsole中执行load pentagi然后pentagi_import_target 192.168.1.100将当前会话主机信息写入图谱SIEM 数据流接入通过pentagi-siem-connectorFlask 应用接收 Splunk/Elasticsearch 的告警 Webhook自动创建(:Alert)-[:INDICATES]-(:AttackIntent)关系实现“检测即响应”的闭环我在某金融客户红队中部署了 Burp 集成当测试人员在 Burp 中发现一个 XSS 漏洞时右键发送到 Pentagi 后系统自动关联该 URL 所属的业务系统、调用的后端微服务、数据库实例并标记出“该 XSS 可能导致的业务影响等级”——这是单靠 Burp 永远无法提供的上下文。6.2 自定义攻击本体的实践方法Pentagi 的 OWASP ASVS 本体是起点不是终点。扩展本体的正确姿势在pentagi-core/src/main/resources/ontology/目录下创建custom-ontology.ttlTurtle 格式定义新节点类型:CloudResource a owl:Class ; rdfs:subClassOf :Asset ; rdfs:label Cloud Resource . :AWSLambdaFunction a owl:Class ; rdfs:subClassOf :CloudResource ; rdfs:label AWS Lambda Function .定义新关系:hasLambdaPermission a owl:ObjectProperty ; rdfs:domain :IAMRole ; rdfs:range :AWSLambdaFunction ; rdfs:label has permission to invoke .在 Neo4j 中执行CALL n10s.rdf.import.fetch(file:///custom-ontology.ttl, Turtle)重启 Pentagi 服务新本体即生效关键原则所有新节点必须继承自:Asset、:Vulnerability、:AttackIntent等顶层类否则 Pentagi 的推理引擎无法识别。我在某云原生红队中扩展了 AWS 本体使系统能自动识别:EC2Instance节点上的:SecurityGroup配置错误并推导出:EC2Instance-[:EXPOSED_TO]-:Internet的风险路径。6.3 团队协作模式下的图谱管理策略当多个红队成员同时操作 Pentagi 时图谱冲突是最大挑战。我们的解决方案是分支式图谱Graph Branching每个成员在Target Management中创建自己的Branch如alice-ad-assessment,bob-cloud-assessment所有操作仅影响该分支图谱合并审查Merge Review当 Alice 完成 AD 推演后发起Merge Request系统自动生成差异报告Added 12 nodes, Modified 3 relationships, Removed 0 nodes版本快照Version Snapshot每次合并前系统自动创建图谱快照命名为ad-assessment-v1.2-20240520可通过MATCH (n) WHERE n.snapshot ad-assessment-v1.2-20240520 RETURN count(n)快速回滚这套机制让红队从“各自为战”升级为“协同认知”——Bob 发现的 Kerberoasting 路径Alice 可以直接在其分支中复用无需重复探测。我们在某央企红队演练中5 名成员通过分支协作将整体评估周期从 14 天缩短至 3.5 天。我在实际使用中发现Pentagi 最大的价值不是节省了多少渗透时间而是彻底改变了红队的知识沉淀方式。过去每次演练结束后知识都散落在个人笔记、截图、PDF 报告里新人接手项目要花两周熟悉现在所有攻击路径、决策依据、失败教训都固化在图谱中新成员第一天就能通过MATCH (a:AttackIntent)-[r]-(v:Vulnerability) WHERE v.cvss_score 9.0 RETURN a, v快速掌握最高危攻击面。这已经不是工具升级而是红队认知范式的迁移。