jiwoochris/artex-ko · 上手攻略

  • 仓库：jiwoochris/artex-ko
  • 链接：https://github.com/jiwoochris/artex-ko
  • 分类：AI 安全 / 自主渗透测试 / 多智能体
  • 作者：spark
  • 更新：2026-10-07

§0. 它是什么 / 一句话定位

jiwoochris/artex-ko 是中国开源项目 Autumn-27/ARTEX 的官方韩语本地化分支（AGPL-3.0）。上游 ARTEX 是一个"LLM 多智能体驱动的自主渗透测试系统"：Go 单体后端 + Next.js 前端 + PostgreSQL，agent 通过双图（资产图 + 探索图）自行规划与执行侦察—渗透—资料外带全链路。韩语版不改 agent 的判断逻辑，只把"对用户暴露的产物"（探测结果、报告、UI 对话）强制改用韩语输出，目的是让韩国安全工程师能复盘这种"自主 AI 攻击"的工作机制并构建防御检测能力。⚠️ 该仓库明确要求仅限授权目标与本地隔离沙箱使用，并指出 2026 年 10 月韩国媒体披露其上游版本被用于针对本土金融机构的数据窃取攻击，调查正在进行中。

§1. 解决什么问题 / 与同类对比

ARTEX 的设计目标是"把渗透测试工程师的'规划—执行—复盘'三段循环交给 LLM 自治"。同类工具一般分三类：

类别 代表 与 artex-ko 的差异
传统自动扫描器 nuclei、w3af 规则/签名驱动，无 LLM 编排能力
单 agent 安全工具 BurpGPT、PentestGPT 的衍生插件 单 agent，缺多 agent 协作与持久化探索状态
多 agent 渗透平台 ARTEX 自身、Strix（部分实现）、开源 VariantPenTestKit artex-ko 与 ARTEX 等价，唯一区别是产物语言为韩语

韩语版的真正意义不是新能力，而是降低韩国本地安全团队的学习与复盘成本：侦察日志与最终报告用韩语渲染，团队成员不必再跨语言审阅，演练复盘更高效。

§2. 快速安装（推荐源码编译韩语版）

⚠️ 重要：截至本文更新时（2026-10-07），仓库还没有发布 Releases；直接 docker compose up 拉到的仍是上游 autumn27/artex 镜像（中文 UI + 中文报告）。要拿到真正的韩语 UI/报告，必须走源码编译单二进制路径：

git clone https://github.com/jiwoochris/artex-ko.git
cd artex-ko

# 1) 前端静态导出
cd web && npm ci && npm run build:static && cd ..
# 2) 把前端产物拷进 Go 嵌入目录
mkdir -p server/webui && cp -r web/out server/webui/dist
# 3) 编译单二进制（-tags embedui 才会把前端打进去）
CGO_ENABLED=0 go build -tags embedui -o artex ./cmd/artex
# 4) 用守护脚本启动（不要直接 ./artex，否则"一键更新"会失效）
cp config.example.json config.json  # 填好 database 段
./start.sh

启动后访问 http://localhost:8787，首次进入 /setup 设置管理员密码。

如果要快速跑一次中文版（仅用于对比学习）：

docker compose up -d   # 拉 autumn27/artex + postgres

数据库（config.json 或环境变量 ARTEX_PG_DSN）：

{
  "database": { "host": "127.0.0.1", "port": 5432,
                "user": "artex", "password": "yourpass",
                "dbname": "artex", "sslmode": "disable" }
}

§3. 核心用法

3.1 LLM 配置

export ANTHROPIC_API_KEY=sk-...      # 或 OPENAI_API_KEY
# 可选：切换国产 / 开源模型（OpenAI 兼容端点）
export ARTEX_LLM_PROVIDER=openai
export ARTEX_LLM_MODEL=qwen-...
export ARTEX_LLM_BASE_URL=https://your-openai-compatible-endpoint

UI 里也可在「LLM 配置」页面直接填写。⚠️ 韩语版使用 agent/prompt.go 的 langDirective() 提示强制韩语输出，但输出语言的稳定度直接取决于模型能力：

  • claude-opus-4-8：planner / worker / reporter / 复测四角色对用户输出稳定韩语，无拒绝
  • gpt-4o：同场景可保持韩语，但偶尔 planner 摘要会回退到中文
  • gpt-4o-mini：报告会回退到中文（上游原文）

3.2 启动与常用开关

./start.sh -addr :8787 -proxy :8788   # -addr 前端+API，-proxy 流量录制代理

并发：每个任务的 worker 数在「系统设置」里配置，默认 3。

3.3 双重图架构（理解自治的关键）

图 作用域 节点 边
资产图（Asset Graph） 全任务共享 root_domain / subdomain / ip / service / app / endpoint 父子、去重键由程序计算
探索图（Exploration Graph） 每任务独立 goal / intent / fact / finding / hint spawns / derived_from / yields / proves

exploration_anchors(node_id, asset_id) 把两边连起来——所以你能从某个 intent 找到它攻击的资产，也能从某个 endpoint 找到它被打的所有 intent。

3.4 事件循环（planner → worker → DB → 唤醒）

graph 变更 (debounce)
  → planner 醒来，读 graph_overview + coverage/scope
  → planner 把 0..N 个 intent 投到 frontier（多数为空，意味着没有新方向）
  → worker 领取一个 intent
  → worker 调真实工具（Bash / HTTP / Kali），走 MITM 代理全程记录
  → 写回 fact / asset / finding 到双图 → debounce 再次唤醒 planner
  → 循环，直到 prove_goal

⚠️ 这是一个事件驱动闭环，不是轮询；planner 只在"有新方向"时下达意图。

3.5 远程 MCP（可选）

UI 的系统设置里可选 http（Streamable HTTP） 或 sse（旧版 SSE）。旧版 SSE 通常用 GET /sse 建立事件流、通过 /message?sessionId=... 接 JSON-RPC 请求；填 URL 用 /sse，请求头 Authorization=Bearer <token>。

§4. 典型适用场景

⚠️ 再次提示，本仓库仅用于授权目标与本地隔离沙箱：

  • 蓝队演练：在 DVWA / 自建 Juice Shop 上跑 artex-ko 学习"自主 AI 攻击"的攻击链与可观测特征，构建检测签名
  • 安全产品自检：把 artex-ko 作为攻击负载，对自家 EDR / WAF / SIEM 做对抗演练
  • 教学演示：韩语 UI/报告适合本地安全课程直接演示给学生
  • 报告审计与复盘：韩语渲染的侦察日志/最终报告便于团队跨人协作

不适合：对外网真实生产系统的扫描与利用（已构成违法）。

§5. 坑与注意（≥5 个具体坑点，每点三段式）

坑 1：Docker 镜像仍是中文版，看不到韩语 UI

现象：直接按 README 跑 docker compose up -d，UI 与报告仍是中文，因为 docker-compose.yml 拉的是上游 autumn27/artex 镜像，韩语化（韩语 UI · 韩语报告 · langDirective）还没被打进镜像。 影响：以为装好韩语版，实际拿到的还是上游产物；产物语言基线判断错。 修复：用上文 §2 的"源码编译单二进制"路径构建；或等韩语版 Docker 镜像发布（README 标注"准备中"）。

坑 2：OpenAI 兼容端点 max_tokens 上限冲突

现象：用国产/开源 OpenAI 兼容模型时，默认请求带 max_tokens=32768，所有调用 400 max_tokens is too large。 影响：LLM 全线不可用，agent 启动即报错。 修复：在 LLM 配置页把对应 profile 的 max_tokens 设为 16384 以下（OpenAI 系列上限）；Anthropic（claude-opus-4-8 等）允许 32768 不受影响。

坑 3：弱模型导致报告语言回退

现象：用 gpt-4o-mini 等低价小型模型，reporter 输出回退到中文（上游原文）。 影响：韩语承诺破灭，团队无法直接复盘。 修复：①换成 claude-opus-4-8 或 gpt-4o；②在任务/agent prompt 显式加「한국어로 작성하라」指令；③在任务设置里给推理模型加大 max_tokens，避免 reasoning 模型把预算烧在内部推理上、最终回答被截断为空。

坑 4：反代未关 SSE 缓冲，活动流永远转圈

现象：Nginx/Caddy 反代后，UI 活动流一直"加载中"。 影响：看不到实时进度，看起来像 agent 没动。 修复：反代必须关缓冲、长超时、走 HTTP/1.1，示例：

location / {
  proxy_pass http://127.0.0.1:8787;
  proxy_buffering off;
  proxy_cache off;
  proxy_read_timeout 3600s;
  proxy_http_version 1.1;
  proxy_set_header Connection "";
}

坑 5：更新会中断正在运行的任务

现象：在 UI 点"一键更新"或运行 ./update.sh，进程会重启。 影响：进行中的任务被强停，需要手动恢复。 修复：①空闲时段再更新；②Docker 用户注意"换程序不换镜像"——docker compose up -d 重建容器后，镜像里的工具链（nmap、playwright 等）会退回镜像自带版本，要保留升级需 docker compose pull artex && docker compose up -d artex。

坑 6：升级失败留暂存 .new / .old / .failed

现象：新版本校验或冒烟测试失败，会留 artex.new 暂存；新版启动连续 3 次失败自动回滚到 artex.old，失败的留作 artex.failed 排查。 影响：磁盘出现多个二进制，目录状态混乱。 修复：①升级前备份 ./data 与 Postgres；②定期清理 artex.new / artex.failed；③出问题时用 UI 的"回滚到上一版本"按钮。

坑 7：直跑 ./artex 而不是 ./start.sh 导致"一键更新"失效

现象：直接 ./artex & 起来，UI 上点"更新"看起来像完成，但新版本没起来。 影响：版本实际未切换，schema 也没迁移。 修复：始终用 ./start.sh（Windows 用 start.bat）——它是退出码感知的守护者，会拉起新进程。

§6. 诚实标注 / 局限性

  • ⚠️ 截至 2026-10-07，仓库未发布任何 Release，无法直接下载预编译的韩语版二进制，必须从源码编译。
  • ⚠️ 官方 Docker 镜像仍是上游中文版，韩语化路径目前只走源码编译。
  • ⚠️ 上游 ARTEX 被报道用于针对韩国本土金融机构的真实攻击（2026-10 韩国媒体），使用该工具对外网真实目标即构成违法（韩国「信息通信网法」+「个人信息保护法」）。
  • ⚠️ 韩语输出的稳定性依赖模型能力，使用弱模型会出现语言回退；推理模型 max_tokens 设小会把回复截成空。
  • ⚠️ 当前未提供完整的 CI 状态徽章含义解析（README 仅放链接），实际 CI / detection / web 三套 workflow 是否全绿需自查 Actions 页。

§7. 一句话推荐结论

适合韩语安全团队做"自主 AI 攻击"蓝队演练与教学演示的本地化分支；理解其双图（资产图 + 探索图）+ planner/worker 闭环即可快速上手，务必在本地隔离沙箱内运行。