FOFA scan workflow (prepare vulnerability/PoC commands)

# FofaMap MCP server (v2.0.0) — tool reference

## Global notes from server code
- `FastMCP("Fofamap-Platinum-Full-Expert")` defines the MCP app name.
- Logging/print is redirected to stderr via a “MCP 协议防污染补丁” (prints forced to `sys.stderr`).
- `generate_nuclei_command` explicitly **generates only** commands; it does **not execute** scans inside MCP.

---

## Tool 1: `search_assets`
**Signature**: `search_assets(query: str, fields: str = None, pages: int = 1, full: bool = False, display_rows: int = 25)`

**Purpose**: Execute a FOFA query and return a Markdown table.

**Parameters**
- `query` (required): FOFA query syntax (examples shown in docstring):
  - `(app="xxx" || app="yyy") && country="CN"`
  - `app="ThinkPHP" && country="CN"`
- `fields` (optional): comma-separated FOFA fields to return.
  - If not set, server selects defaults based on login VIP level.
  - To include cert/body/fid/icon_hash etc., explicitly add those fields (examples: `"host,ip,cert,body"`).
- `pages` (default `1`): query page count.
- `full` (default `False`): whether to search historical data.
- `display_rows` (default `25`): max rows displayed in returned Markdown table.
  - If user asks for more, can be increased, but not “too high” to avoid output limits.

**Default field selection logic (server-side)**
- Base defaults always include:
  - `"host", "ip", "port", "protocol", "title", "server", "domain", "country_name"`
- Additional defaults added when `vip_level >= 12` OR `vip_level == 2` OR `vip_level == 5`:
  - `"product", "lastupdatetime"`

**Returns (string)**
- On exception: `❌ FOFA 请求异常: {error}`
- If no results: `🔍 未发现资产，实际查询字段: `{effective_fields}``
- Otherwise: `### 🔍 FOFA 检索结果: `{query}`\n` + Markdown table
  - Table headers are derived from `target_fields` and each header is truncated to 10 chars (`h[:10]`).
  - Each cell is cleaned: newline to space and `|` escaped; long cells truncated (over 50 chars -> keep first 47 + `...`).

**FOFA syntax gotchas (as stated in docstring)**
- Geographic values must use pinyin (server warns):
  - ❌ `city="上海"`
  - ✅ `city="Shanghai"`, `region="Zhejiang"`

---

## Tool 2: `get_host_aggregation`
**Signature**: `get_host_aggregation(host: str)`

**Purpose**: Get a single target (IP/domain) “aggregation/portrait”, including open ports and products.

**Parameters**
- `host` (required): an IP or domain.

**Returns (string)**
- On exception: `❌ 查询异常: {e}`
- If data missing or `data.get('error')`: `❌ 查询失败: {data.get('errmsg', '目标不存在')}`
- Otherwise:
  - Header section including:
    - `data.get('host', host)`
    - `- **基本信息**: `{data.get('ip')}` | {data.get('country_name')} | {data.get('org')}`
    - `- **ASN**: {data.get('asn')} | **更新时间**: {data.get('update_time')}`
  - If ports exist:
    - Ports are sorted by `port`.
    - A table `Port | Protocol | Products` where `Products` is `", ".join([x.get('product','') for x in p.get('products', [])])`.

---

## Tool 3: `get_stats_aggregation`
**Signature**: `get_stats_aggregation(query: str, fields: str = "country,title,org")`

**Purpose**: Perform a FOFA stats aggregation and return Top-N tables.

**Parameters**
- `query` (required): FOFA query for stats aggregation.
- `fields` (optional): must be one of the fields listed below.
  - Supported fields (as stated):
    - `protocol`, `domain`, `port`, `title`, `os`, `server`, `country`, `asn`, `org`, `asset_type`, `fid`, `icp`

**Returns (string)**
- If exception: `❌ 统计异常: {e}`
- If no data: `⚠️ 无统计数据。`
- Otherwise:
  - `### 📊 资产统计分布 (总量: {data.get('size', 0)})\n`
  - For each aggregated field with items:
    - `#### 🏆 {field.upper()} Top 10`
    - table `名称 | 数量` using `i.get('name')` and `i.get('count')`.

---

## Tool 4: `calculate_icon_hash`
**Signature**: `calculate_icon_hash(url: str)`

**Purpose**: Extract favicon from the target website and compute `icon_hash`.

**Parameters**
- `url` (required): website URL.

**Returns (string)**
- On success: `✅ 计算成功！\n请使用: `{hash_query}``
- If favicon fetch fails: `❌ 获取 favicon 失败。`
- On exception: `❌ 异常: {e}`

---

## Tool 5: `ai_security_consultant`
**Signature**: `ai_security_consultant(user_intent: str)`

**Purpose**: Produce an AI tactical plan (query suggestions, routing, and whether to run nuclei).

**Parameters**
- `user_intent` (required): user’s intent (free text).

**Returns (string)**
- If AI plan fails: `⚠️ AI 思考失败。`
- Otherwise a formatted block:
  - `### 🧠 AI 专家战术规划`
  - `- **推荐查询语句**: `{plan.get('queries')}``
  - `- **动作路由**: `{plan.get('action')}``
  - `- **扫描决策**: ✅ 建议开启` if `plan.get('run_nuclei')` else `❌ 不建议执行`

**Stated AI decision logic (docstring highlights)**
- “拼音优先”: converts Chinese locations (e.g., “上海”) to pinyin (e.g., `Shanghai`).
- “权限感知”: strictly limits fields based on VIP level.
- Lists example categories of fields it might choose, including high-risk fields such as:
  - `body`, `icon_hash`, `fid`, `icon`, `structinfo`

---

## Tool 6: `check_assets_alive`
**Signature**: `check_assets_alive(hosts: list[str])`

**Purpose**: HTTP/HTTPS liveness check.

**Parameters**
- `hosts` (required list): list of host URLs/targets to check.

**Hard-coded behavior in docstring/code**
- Uses `FastChecker.check_alive(hosts, timeout=5)`.

**Returns (string)**
- On exception: `❌ 检测异常: {e}`
- Otherwise:
  - `### 🟢 存活资产 ({len(alive_data)}/{len(hosts)})\n`
  - table headers: `URL | 状态码`
  - Includes entries where status code is digit (`str(code).isdigit()`).

---

## Tool 7: `generate_nuclei_command`
**Signature**: `generate_nuclei_command(targets: list[str], severity: str = "medium,high,critical")`

**Purpose**: Generate a Nuclei command string and a `targets.txt` payload. **Does not execute scans**.

**Parameters**
- `targets` (required list[str]): targets to be written into `targets.txt`.
- `severity` (optional): defaults to `"medium,high,critical"`.

**Returns (string)**
- If `targets` empty: `❌ 目标列表为空。`
- Otherwise:
  - Shows `targets.txt 内容` in a code block.
  - Provides a bash snippet:
    - `cat > targets.txt << 'EOF'`
    - then each target line
    - then scan command using variables:
      - `nuclei -l targets.txt -severity {severity} -stats -o result.txt`

**Docstring decision rules (used to craft recommendations)**
- Technical stack identification based on Title/Server/Header/Port.
- For specific vulnerabilities (example: “Log4j”), recommends including tags or `-id CVE-2021-44228`.
- For broad probing, recommends `-as` and `-severity critical,high` (though the returned command shown in code is: it only includes `-severity`, `-stats`, `-o`, and `-l targets.txt`).
- For target count tuning:
  - fewer important targets: add `-bs 25 -rl 150`
  - many mixed targets: add `-tags cves,misconfig`

(Warning: The returned command in this version does not visibly incorporate those extra tuning flags; it only uses `-severity {severity} -stats -o result.txt`.)