From d61c85e73e70c98a5346146284e9b885ffec88bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=AC=E6=98=8E?= <83812544+Ed1s0nZ@users.noreply.github.com> Date: Fri, 14 Nov 2025 00:32:07 +0800 Subject: [PATCH] Add files via upload --- README.md | 80 ++++++++++++++++++++++++-------------- README_CN.md | 78 +++++++++++++++++++++++-------------- internal/handler/config.go | 10 ----- 3 files changed, 98 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index f45bbc67..195cc46c 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ 🚀 **AI-Powered Autonomous Penetration Testing Platform** - Built with Golang, featuring hundreds of built-in security tools, flexible custom tool extensions, and intelligent AI decision-making through MCP protocol, making security testing as simple as a conversation. -- web mode +- Web Mode ![Preview](./img/效果.png) -- mcp-stdio / mcp-http modes +- MCP Stdio Mode ![Preview](./img/mcp-stdio2.png) ## Changelog @@ -892,42 +892,62 @@ For the complete tool list, please check the `tools/TOOLS_LIST.md` file. ### Adding New Tools -#### Method 1: Create Tool Configuration File (Recommended) +To help the AI reason about custom tools without ambiguity, each `tools/*.yaml` file must describe the tool metadata, default behaviour, and runtime parameters in detail. The loader validates every field on startup—tools with missing required fields are skipped and reported in the logs. -1. Create a new YAML file in the `tools/` directory, for example `tools/mytool.yaml`: +> Need the full checklist? See `tools/README.md` (Chinese) or `tools/README_EN.md` (English) for the complete field reference, templates, and best practices. -```yaml -name: "mytool" -command: "mytool" -args: ["--default-arg"] -enabled: true +#### Top-level fields (tool scope) -short_description: "Short description (for tool list)" +| Field | Required | Type | Description | +|-------|----------|------|-------------| +| `name` | ✅ | string | Unique identifier. Use lowercase letters, numbers, and hyphens for easy reference in conversations. | +| `command` | ✅ | string | Executable or script to run. Must be resolvable from `$PATH` or provided as an absolute path. | +| `enabled` | ✅ | bool | Registers the tool with MCP. When `false`, the tool is hidden from the UI and AI runtime. | +| `description` | ✅ | string | Full Markdown description. Powers MCP `resources/read` and gives the AI rich context. | +| `short_description` | Optional | string | 20–50 character summary shown in tool lists. If omitted, the loader extracts the start of `description`. | +| `args` | Optional | string[] | Static arguments prepended to every invocation, often used for default scan profiles. | +| `parameters` | Optional | array | List of user-supplied parameters. See the next section for field definitions. | +| `arg_mapping` | Optional | string | Mapping strategy (`auto`/`manual`/`template`). Defaults to `auto`; usually no change required. | -description: | - Detailed tool description to help AI understand the tool's purpose and use cases. +> Tip: prefer plain ASCII/UTF-8 content and keep YAML indentation consistent to avoid parse errors. -parameters: - - name: "target" - type: "string" - description: "Target parameter description" - required: true - position: 0 # Positional parameter - format: "positional" - - - name: "option" - type: "string" - description: "Option parameter description" - required: false - flag: "--option" - format: "flag" -``` +#### Parameter objects (`parameters[]`) -2. Restart the server, and the tool will be automatically loaded. +Each parameter definition may include: -#### Method 2: Add to Main Configuration File +- `name` (required): Key used in both command construction and MCP JSON Schema. +- `type` (required): `string`, `int`/`integer`, `bool`/`boolean`, `array`, etc. +- `description` (required): Use Markdown to explain purpose, accepted formats, example values, and safety notes. +- `required`: Boolean flag. When `true`, the executor will stop with an error if the caller omits the value. +- `default`: Default value applied when the caller does not provide one. +- `flag`: CLI switch such as `-u` or `--url`. Combined with `format` to decide how the argument is rendered. +- `position`: Zero-based integer for positional arguments. Positional arguments are appended after flag arguments in ascending order. +- `format`: Controls rendering strategy: + - `flag` (default): Emits `--flag value` or `-f value`. + - `combined`: Emits `--flag=value`. + - `positional`: Inserts the value directly according to `position`. + - `template`: Uses the `template` string with placeholders. +- `template`: Active when `format: "template"`. Supports `{flag}`, `{value}`, and `{name}` placeholders. +- `options`: Array of allowed values. Populates MCP schema `enum` entries and drives AI suggestions. -Add tool configuration in `config.yaml` under `security.tools`. +#### Reserved parameter names + +- `additional_args`: Lets users append raw CLI fragments in one field. The executor tokenises the string and appends it to the command. +- `scan_type`: Primarily for tools like `nmap` to replace default scan switches (e.g., `-sV -sC`). +- `action`: Consumed exclusively inside server-side logic for tools requiring sub-commands. Not passed to the CLI. + +These names are handled specially by the executor—reuse them instead of creating near-duplicates. + +#### Recommended authoring workflow + +1. Create a new YAML file under `tools/`, for example `tools/mytool.yaml`. +2. Fill out the top-level fields, list common parameters with helpful defaults, and document examples inside `description`. +3. Run `go run cmd/test-config/main.go` to lint configurations locally. +4. Restart the server (or trigger a reload) so the frontend settings panel and MCP registry pick up the new tool. + +#### Method 2: Add to main configuration file + +If you prefer inline definitions, replicate the exact structure under `security.tools` in `config.yaml`. When both `tools_dir` and inline `tools` are present, files from the directory take precedence. ### Tool Parameter Configuration diff --git a/README_CN.md b/README_CN.md index a86b2073..c9b7b14a 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,9 +1,7 @@ # CyberStrikeAI -[English](README.md) | [中文](README_CN.md) - 🚀 **AI自主渗透测试平台** - 基于Golang构建，内置上百个安全工具，支持灵活扩展自定义工具，通过MCP协议实现AI智能决策与自动化执行，让安全测试像对话一样简单。 -- web 模式 +- web模式 ![详情预览](./img/效果.png) - mcp-stdio / mcp-http 模式 ![详情预览](./img/mcp-stdio2.png) @@ -893,42 +891,62 @@ curl -X POST http://localhost:8080/api/mcp \ ### 添加新工具 -#### 方法一：创建工具配置文件（推荐） +为确保 AI 能够无歧义地调用自定义工具，请按照下述字段规范编写 `tools/*.yaml` 配置文件。系统在加载时会逐项校验，缺失必填字段的工具会被跳过并在日志中提示。 -1. 在 `tools/` 目录下创建新的YAML文件，例如 `tools/mytool.yaml`： +> 需要完整的字段对照表和模板示例？请查看 `tools/README.md`（中文）或 `tools/README_EN.md`（英文）获取更详细的配置指南。 -```yaml -name: "mytool" -command: "mytool" -args: ["--default-arg"] -enabled: true +#### 顶层字段（工具级） -short_description: "简短描述（用于工具列表）" +| 字段 | 必填 | 类型 | 说明 | +|------|------|------|------| +| `name` | ✅ | string | 工具唯一标识，建议使用小写字母＋数字＋短横线组合，便于在对话中引用。 | +| `command` | ✅ | string | 实际执行的命令或脚本名称，需在 PATH 中或写绝对路径。 | +| `enabled` | ✅ | bool | 是否注册到 MCP。为 `false` 时，前端和 AI 都不会看到该工具。 | +| `description` | ✅ | string | 工具详细说明，支持多行 Markdown，供 AI 深度理解以及 `resources/read` 查询。 | +| `short_description` | 可选 | string | 适合 20-50 字的摘要，优先用于工具列表和对话上下文，缺失时系统会自动截取 `description` 片段。 | +| `args` | 可选 | string[] | 固定参数，按顺序写入命令行，常用于定义默认扫描模式或全局开关。 | +| `parameters` | 可选 | 参数对象数组 | 定义调用时可覆盖的动态参数，详见下节。 | +| `arg_mapping` | 可选 | string | 参数映射模式（`auto`/`manual`/`template`），当前版本默认 `auto`，不填写即可。 | -description: | - 工具的详细描述，帮助AI理解工具的用途和使用场景。 +> **提示**：所有文本字段推荐使用 UTF-8/ASCII，无需额外引号的内容需保持 YAML 缩进正确。 -parameters: - - name: "target" - type: "string" - description: "目标参数描述" - required: true - position: 0 # 位置参数 - format: "positional" - - - name: "option" - type: "string" - description: "选项参数描述" - required: false - flag: "--option" - format: "flag" -``` +#### 参数字段（`parameters[]`） -2. 重启服务器，工具会自动加载。 +每个参数对象支持以下属性，请根据工具特性选择： + +- `name`（必填）：参数键名，同时用于构建命令行和生成 MCP JSON-Schema。 +- `type`（必填）：`string`、`int`/`integer`、`bool`/`boolean`、`array` 等。 +- `description`（必填）：建议使用 Markdown 描述用途、格式、示例值及安全提示。 +- `required`：布尔值，标记是否必须由调用方提供。缺失必填参数时执行器会返回错误信息。 +- `default`：默认值。调用方未传值时将使用该值，便于提供合理的开箱体验。 +- `flag`：命令行标志（如 `-u`、`--url`），结合 `format` 决定拼接方式。 +- `position`：整数（从 0 开始），指定位置参数顺序。所有位置参数会在标志参数之后依次插入。 +- `format`：拼接策略，支持： + - `flag`（默认）：输出为 `--flag value` 或 `-f value`； + - `combined`：输出为 `--flag=value`； + - `positional`：按 `position` 顺序直接写入值； + - `template`：配合 `template` 字段自定义渲染。 +- `template`：当 `format: "template"` 时生效，支持 `{flag}`、`{value}`、`{name}` 占位符。 +- `options`：枚举值数组。定义后 AI 会提示可选项，MCP schema 也会自动带上 `enum` 信息。 + +#### 约定的特殊参数名 + +- `additional_args`：允许用户在一次调用中追加任意命令行片段（内部会智能拆分并追加到命令末尾）。 +- `scan_type`：主要用于 `nmap` 等网络扫描工具，用来覆盖默认扫描参数（如 `-sV -sC`）。 +- `action`：供少数需要内部状态分支的工具使用，仅在服务端逻辑消费，不会拼接到命令行。 + +这些名称在执行器中有特殊处理，建议复用而不要自定义同义字段。 + +#### 推荐配置流程 + +1. 在 `tools/` 目录新建 YAML 文件，例如 `tools/mytool.yaml`。 +2. 填写上述顶层字段及参数列表，为常用参数设置 `default`，并在 `description` 中提供示例。 +3. 如需快速校验，执行 `go run cmd/test-config/main.go`，确认加载无误。 +4. 重启服务或触发热更新后，前端设置面板与 MCP 工具列表会自动展示新工具。 #### 方法二：在主配置文件中添加 -在 `config.yaml` 的 `security.tools` 中添加工具配置。 +如果暂时不想拆分文件，也可以直接在 `config.yaml` 的 `security.tools` 下编写相同结构的对象。若同时存在 `tools_dir` 与内联 `tools`，目录中的配置优先生效。 ### 工具参数配置 diff --git a/internal/handler/config.go b/internal/handler/config.go index 0d691006..a2245cca 100644 --- a/internal/handler/config.go +++ b/internal/handler/config.go @@ -248,16 +248,6 @@ func (h *ConfigHandler) saveConfig() error { } } - toolData, err := os.ReadFile(toolFile) - if err != nil { - h.logger.Warn("读取工具配置文件失败", zap.String("tool", tool.Name), zap.Error(err)) - continue - } - - if err := os.WriteFile(toolFile+".backup", toolData, 0644); err != nil { - h.logger.Warn("创建工具配置备份失败", zap.String("tool", tool.Name), zap.Error(err)) - } - toolDoc, err := loadYAMLDocument(toolFile) if err != nil { h.logger.Warn("解析工具配置失败", zap.String("tool", tool.Name), zap.Error(err))