mpgn/NetExec-mcp

# netexec-mcp 一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI agent 驱动 **[NetExec](https://github.com/Pennyw0rth/NetExec)** (`nxc`)，**仅限授权的** 安全测试使用。 它是一个**纯粹的 subprocess 包装器**：它以 argv 列表的形式调用 `nxc` CLI （从不使用 `shell=True`，也从不在 Python 中将 NetExec 作为库导入），并且声明 **没有** nxc 依赖。nxc 本身如何安装（PATH / uv / pipx / docker）完全取决于你。 recon 模式： full 模式： ## 状态 **v1 — 全部 10 种 nxc 协议，131 个工具**（117 个协议工具 + 9 个发现/元工具 + 5 个离线 workspace-DB 读取器）。SMB、LDAP、WinRM、MSSQL、SSH、RDP、WMI、FTP、NFS 和 VNC 均已构建（原生 flags、凭据转储/收集、命令执行、文件传输、推广的高价值 `-M` 模块以及结构化输出）。前七种已针对真实的 AD 实验室完成了端到端验证；FTP/NFS/VNC 已完成源码验证 + 单元测试（尚无实验室）。3 级安全模型控制着一切；大量剩余的 nxc `-M` 模块可通过元工具访问。 ## 专为小型 / 本地模型构建 由于有 131 个工具，在开始任何工作之前，向模型列出每一个工具将消耗约 46k token 的上下文，这足以撑爆小型上下文（≤8B / 32k）模型，并使得大型模型上的每次调用都产生不必要的昂贵开销。因此，默认的 `NXC_TOOL_MODE` 是 **`dynamic`**：仅暴露少数几个元工具（`nxc_catalog`、 `nxc_find_tool`、`nxc_describe_tool`、`nxc_call`、`nxc_health`），模型会按需 发现并调度真实的工具。这使得工具表面积保持在运行小型本地模型所需的 上下文窗口之外，并在大型模型上变得更便宜（质量相同）。设置 `NXC_TOOL_MODE=static` 可选择退出并列出所有工具。请参阅 [配置](#configuration-env-vars) 下的 `NXC_TOOL_MODE` 行及其下方的 步骤预算说明。 ## 环境要求 - Python ≥ 3.10, [`uv`](https://docs.astral.sh/uv/) 或 [`pipx`](https://pipx.pypa.io/) - **单独安装的 NetExec** —— 它不是 pip 依赖项，也不在 PyPI 上。 请参阅[官方安装指南](https://www.netexec.wiki/getting-started/installation)。 只要可以通过 `PATH` 或 `NXC_COMMAND` 找到 `nxc` / `netexec`，任何安装方式均可； 服务器在启动时会运行 `nxc --version`，如果找不到它则拒绝启动。 ## 快速开始 ### 选项 A：uv（从源码检出运行） ``` uv sync # 指向你的 nxc 安装路径（示例：一个由 uv 管理的源码 checkout） export NXC_COMMAND="uv run --directory ~/NetExec netexec" export NXC_SCOPE="10.0.0.0/24" # required to target anything (fail-closed) uv run netexec-mcp ``` MCP 客户端配置（`command`/`args` 用于启动服务器本身）： ``` { "command": "uv", "args": ["run", "--directory", "/path/to/netexec-mcp", "netexec-mcp"] } ``` ### 选项 B：从 PyPI 安装（独立的 `netexec-mcp` CLI） ``` # 选择一个 installer —— 它们都会将 `netexec-mcp` 放到 PATH 上： pipx install netexec-mcp # pipx uv tool install netexec-mcp # uv # 或者在不安装的情况下运行： uvx netexec-mcp # uv, one-shot export NXC_COMMAND="nxc" # or however your nxc install is invoked export NXC_SCOPE="10.0.0.0/24" netexec-mcp ``` MCP 客户端配置 —— `netexec-mcp` 已在 `PATH` 中，因此无需 `uv`/`--directory` 包装器： ``` { "command": "netexec-mcp", "args": [] } ``` 启动时，服务器会运行 ` --version`，如果失败则**拒绝启动** （除非模式为 `suggest`，这会降级为警告）。请参阅 `.mcp.json.example` 以获取可直接编辑的 MCP 客户端配置（uv 变体）。 ## 操作模式 (`NXC_MODE`) 服务器被允许*执行*的操作的四个递增级别： | 模式 | 执行的内容 | 适用场景 | | --- | --- | --- | | `suggest` | **不执行任何操作。** 工具返回解析后的 nxc 命令，供人类（审计员）运行。范围仍被强制执行；可以预览攻击性命令。 | 你希望 agent 规划出你自己去运行的命令。 | | `recon` _(默认)_ | 只读枚举；拒绝执行、转储凭据和更改状态的操作。 | 日常授权侦察。 | | `loot` | 侦察**外加**只读凭据转储 (sam/lsa/ntds/gpp/roasting) —— 目标上没有状态更改，但会收集凭据材料。 | 授权的凭据收集。 | | `full` | 执行所有操作，包括状态更改 / 权限提升操作（执行、写入、密码喷洒、带有监听器的强制操作、漏洞利用）。 | 授权的主动测试。 | `NXC_MODE` 是规范性控制；未设置时默认为 `recon`。 ## 配置 (环境变量) | 变量 | 用途 | 默认值 | | --- | --- | --- | | `NXC_COMMAND` | 基础命令（通过 shlex 解析）。回退到 `PATH` 上的 `nxc`/`netexec`。 | 自动检测 | | `NXC_PROTOCOLS` | 要启用的以逗号分隔的协议列表（例如 `smb,ldap`）。 | 所有已实现的协议 | | `NXC_TOOL_MODE` | 工具表面积呈现方式 —— `dynamic`（**默认**：仅暴露元工具；约 100 个工具的表面积通过 `nxc_find_tool`/`nxc_catalog` 发现，并通过 `nxc_call` 运行）或 `static`（列出每个工具）。Dynamic 将约 46k token 的表面积保持在上下文窗口之外 —— 对于小型上下文模型是必需的，在大型模型上便宜约 8 倍（质量相同）。设置 `static` 以选择退出（最适合决定性模型，或避免在大型上下文模型上进行发现往返）。 | `dynamic` | | `NXC_SCOPE` | 以逗号分隔的目标白名单 (IP/CIDR/range/hostname)。**失败即关闭 (Fail-closed)**：没有 scope 的目标会被拒绝。 | _(无)_ | | `NXC_MODE` | 操作级别 —— `suggest` / `recon` / `loot` / `full`。 | `recon` | | `NXC_TIMEOUT` | 每次调用超时时间（秒）。 | `300` | | `NXC_MAX_TARGETS` | 每次调用的最大目标 token 数。 | `256` | | `NXC_AUDIT_LOG` | 仅追加的 JSONL 审计日志路径。 | _(无)_ | | `NXC_WORKSPACE` | 要读取的 nxc workspace，以获得更丰富的结果。 | _(无 —— 读取 nxc.conf 的 `workspace`，否则为 `default`)_ | | `NXC_PATH` | 覆盖 nxc 的主目录（镜像 nxc 自身的 `NXC_PATH`）；读取 `nxc.conf` 和 `workspaces/` 的位置。 | `~/.nxc` | ## 资源 服务器将速查表作为 MCP 资源发布，以便 agent 能够以此为基础： - `netexec://guide/operating-modes` - `netexec://guide/auth` - `netexec://guide/workflows` （包含跨协议的 gMSA 链） - `netexec://guide/workspace` （缓存召回 vs. 实时 —— 何时使用哪个） - `netexec://guide/safety` - `netexec://catalog/tools` （实时的、自动生成的工具清单） - `netexec://workspace/credentials`, `/admins`, `/loggedin`, `/hosts` （workspace DB 数据， 与 `workspace_*` 工具来源相同，无过滤） ## 安全与防护栏 在任何命令运行之前，在唯一的阻塞点强制执行： - **Scope 白名单** (`NXC_SCOPE`) —— 检查每个目标；**失败即关闭 (fail-closed)**。 - **模式控制** (`NXC_MODE`) —— 在 `full` 之外拒绝攻击性操作。 - **目标上限** + 每次调用**超时**。 - **审计日志** —— 每个命令（执行 / 模拟运行 / 拒绝）均以 JSON 格式追加。 - **无 shell** —— nxc 作为 argv 列表被调用；没有任何内容被 shell 解释。 ## 示例：gMSA 凭据链 ``` smb_lsa (full) -> secrets[] incl. { type: "gmsa_id", gmsa_id, ntlm } ldap_gmsa_convert_id -> resolves the gmsa_id to an account name (gmsa-robin$) -> replay with username="gmsa-robin$", ntlm_hash= ``` ## 开发说明 ``` uv run pytest -q # mocked-subprocess unit tests (no nxc/network needed) ``` 架构和里程碑历史记录在 `PLAN.md` 中。工具/flags 已根据 nxc 源码（`nxc/protocols//proto_args.py`）进行验证 —— `--help` 列出的参数会被 处理程序拒绝。 ### nxc 版本 此 MCP 是一个 subprocess 包装器，不固定任何 nxc 依赖，但其工具/flags 已根据 特定的 nxc 构建版本进行了验证： 使用 `nxc --version` 检查你的本地构建版本（它会打印 `version - codename - commit - build`）。 nxc 更新很快，偶尔会移动/移除 flags，因此当你升级 nxc 时，请重新验证受影响协议的 `proto_args.py` + 处理程序，并重新运行测试。

标签：AI代理, Blue Team, MCP, PE 加载器, Web报告查看器, XXE攻击, 凭据提取, 插件系统, 横向移动, 编程规范, 网络安全, 逆向工具, 隐私保护