🛡️ koishi-plugin-raysec

raysec 是一个跨平台的 Koishi 安全情报、Nmap 和 Masscan 扫描插件。扫描指令由当前部署机器上的可配置执行器运行，支持 Windows、macOS 和 Linux，后续可替换为远程扫描执行器。

📦 安装与开发

直接安装 npm 上发布的版本，可选择 npm 或 Yarn：

# 进入 Koishi 项目根目录
cd ~/koishi/koishi-app

# 安装插件到当前koishi实例
npm install koishi-plugin-raysec
# 使用 npm 或 Yarn，二选一
yarn add koishi-plugin-raysec

也可以在 Koishi 插件市场搜索 raysec，直接安装并启用插件。

本地开发时，进入 Koishi 项目根目录，将源码克隆到 external/raysec，然后安装依赖并启动开发模式：

# 进入 Koishi 项目根目录
cd ~/koishi/koishi-app

# 克隆插件源码
git clone https://github.com/ra1nyxin/koishi-plugin-raysec.git external/raysec

# 安装依赖并开发模式启动当前koishi实例
npm install
npm run dev
# 使用 npm 或 Yarn，二选一
yarn install
yarn dev

🚀 快速开始

1. virustotalKey 和 nvdKey 均为可选配置，API Key 只从插件配置读取，不会从聊天消息读取。不填写密钥仍可使用无需密钥的数据源；填写后可启用对应情报源或提高请求配额。
2. proxyMode 可选择 config、environment 或 none：config 使用插件配置的 proxyUrl，environment 读取 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 等环境变量，none 不使用代理。默认使用 none；选择 config 时必须填写 proxyUrl。
3. 需要使用 Nmap 时，部署者必须开启 acceptNmapRisk。该配置默认关闭；关闭时只注册 raysec.nmap 状态入口，开启并重载插件后才会注册实际扫描子指令。开启代表部署者已确认并接受扫描风险、责任和后果。
4. 需要使用 Masscan 时，部署者必须开启 acceptMasscanRisk。该配置默认关闭；关闭时只注册 raysec.masscan 状态入口，开启并重载插件后才会注册实际扫描子指令。开启代表部署者已确认并接受高速扫描风险、责任和后果。

想了解更多信息，可以继续阅读下方文档或查看项目源代码。

📋 指令一览

🌳 根指令

raysec

raysec 是所有 Raysec 指令的根节点。

🔎 基础指令

raysec.ip <address> [--json]
raysec.domain <domain> [--json]
raysec.url <url> [--analyze] [--json]
raysec.hash <hash> [--json]
raysec.cve <CVE-ID> [--json]
raysec.osv <ecosystem> <package> [version] [--json]
raysec.help

--json 可缩写为 -j，用于返回结构化 JSON。

raysec.url 的 --analyze 用于向上游提交 URL 分析任务，需先在插件配置中开启 enableUrlAnalyze。

插件通过子指令请求对应数据源，单个数据源失败不会影响其它结果，并会明确显示失败来源。外部 API 支持超时、429/5xx 退避重试，以及 HTTP、HTTPS、SOCKS 代理。

# IP 情报查询
raysec.ip 8.8.8.8
raysec.ip 8.8.8.8 -j

# 域名情报查询
raysec.domain example.com
raysec.domain example.com --json

# URL 情报查询与分析
raysec.url https://example.com
raysec.url https://example.com --json
raysec.url https://example.com --analyze

# 文件哈希情报查询
raysec.hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
raysec.hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 -j

# CVE 情报查询
raysec.cve CVE-2024-3094
raysec.cve CVE-2024-3094 --json

# OSV 软件包漏洞查询
raysec.osv npm lodash 4.17.20
raysec.osv npm axios 1.10.0 -j

# 显示指令总览
raysec.help

🛰️ Nmap 指令

raysec.nmap
raysec.nmap.basic <target>
raysec.nmap.quick <target>
raysec.nmap.version <target>
raysec.nmap.vuln <target>
raysec.nmap.discover <target>
raysec.nmap.safe <target>
raysec.nmap.intrusive <target>
raysec.nmap.dos <target>
raysec.nmap.external <target>
raysec.nmap.auth <target>
raysec.nmap.exploit <target>
raysec.nmap.malware <target>
raysec.nmap.fuzzer <target>
raysec.nmap.default <target>
raysec.nmap.sshrun <address:port> <username:password> <command>

scanme.nmap.org 是 Nmap 官方提供的授权测试目标，仅用于下方低风险示范；请遵守其使用说明，避免频繁扫描。192.0.2.10 属于 TEST-NET 文档保留地址，仅用于展示高风险指令格式，通常不会返回有效结果；实际执行时必须替换为自有或明确授权的实验目标。

# 显示 Nmap 指令总览或禁用状态
raysec.nmap

# 低风险扫描示范
raysec.nmap.basic scanme.nmap.org
raysec.nmap.quick scanme.nmap.org
raysec.nmap.version scanme.nmap.org
raysec.nmap.discover scanme.nmap.org

# NSE 分类与深入扫描格式示范
raysec.nmap.vuln 192.0.2.10
raysec.nmap.safe 192.0.2.10
raysec.nmap.intrusive 192.0.2.10
raysec.nmap.dos 192.0.2.10
raysec.nmap.external 192.0.2.10
raysec.nmap.auth 192.0.2.10
raysec.nmap.exploit 192.0.2.10
raysec.nmap.malware 192.0.2.10
raysec.nmap.fuzzer 192.0.2.10
raysec.nmap.default 192.0.2.10

# SSH 远程命令格式示范，账户和密码仅为占位内容
raysec.nmap.sshrun 192.0.2.10:22 demo:change-me whoami

⚠️ 风险确认与指令注册

raysec.nmap 始终注册，用于显示 Nmap 禁用状态或完整子指令帮助。acceptNmapRisk 默认关闭；关闭时不注册任何实际扫描子指令，开启并重载插件后才注册全部 raysec.nmap.* 扫描指令。勾选代表部署者确认：机器人不进行目标授权校验、安全提醒或二次确认，扫描风险、责任和后果由部署者及操作者自行承担。

🔍 扫描方式

默认端口扫描使用 -T4 -Pn；vuln 使用 -sV --script vuln，discover 使用 -T4 -sn -PE。safe、intrusive、dos、external、auth、exploit、malware、fuzzer、default 分类统一使用 -T4 -Pn -sV --script <category>。目标 URL 会自动提取 hostname。插件通过参数数组调用 Nmap，不经过 shell。

raysec.nmap.sshrun 11.22.33.44:1234 user:password ls -lah 使用 -sV -p 1234 --script=ssh-run 调用 Nmap NSE，通过 SSH 在目标服务上执行指定命令。账户、密码和命令会作为脚本参数传递，不经过本机 shell。redactNmapCredentials 默认开启，会在聊天回复和错误详情中隐藏 SSH 密码；关闭可能导致密码泄露到群聊或私聊。

📂 路径与安装

Nmap 路径配置：nmapPath 填写自定义命令、可执行文件或目录，会优先尝试；留空或自定义路径失败时，仅按可编辑的 nmapDefaultPaths 顺序继续查找。默认列表覆盖 Linux、Linuxbrew、Android Termux、Homebrew、MacPorts、Scoop shims/current、%SCOOP%、D 盘常见 Scoop 与 Program Files 目录、Program Files、Program Files (x86)、ProgramW6432 与 Chocolatey 常用路径。Windows 环境变量占位符会在查找前展开，无法展开的候选会被跳过；候选为目录或 Scoop 的 current 目录时，会同时检查目录根部和 bin 子目录；清空 nmapDefaultPaths 后不会自动补充任何平台路径。

插件不按操作系统拒绝执行，而是依次运行候选程序的 nmap --version 确认可用性。

🪟 Windows

前置依赖: Windows 使用 Nmap 前应先从 Npcap 官方下载页面 下载并安装 Npcap。

Scoop：

scoop install nmap

WinGet：

winget install --id Insecure.Nmap -e

🐧 Linux

Debian / Ubuntu 系发行版：

sudo apt update
sudo apt install nmap

Fedora / RHEL 系发行版：

sudo dnf install nmap

Arch Linux 系发行版：

sudo pacman -Syu nmap

Alpine Linux：

sudo apk add nmap

Android Termux：

pkg update
pkg install nmap

🍎 macOS

Homebrew：

brew install nmap

MacPorts：

sudo port install nmap

⏱️ 超时与结果

nmapTimeout 默认和最大均为 60 分钟。命令启动时会先发送预计耗时提示；nmapReplyMaxChars 最大为 3700，Markdown 围栏也会计入长度。结果超出此上限时，正文会截断并同时附带完整的 .txt 扫描结果文件。

📡 Masscan 指令

raysec.masscan
raysec.masscan.basic <target> [--rate <packets-per-second>] [--wait <seconds>] [--reply-max-chars <chars>]
raysec.masscan.quick <target> [--rate <packets-per-second>] [--wait <seconds>] [--reply-max-chars <chars>]
raysec.masscan.full <target> [--rate <packets-per-second>] [--wait <seconds>] [--reply-max-chars <chars>]
raysec.masscan.banner <target> [--rate <packets-per-second>] [--wait <seconds>] [--reply-max-chars <chars>]
raysec.masscan.discover <target> [--rate <packets-per-second>] [--wait <seconds>] [--reply-max-chars <chars>]

192.0.2.0/24 是 TEST-NET 文档保留网段，仅用于展示 Masscan 指令格式，通常不会返回有效结果；实际执行时必须替换为自有或明确授权的实验目标，并根据目标环境设置保守的扫描速率。

# 显示 Masscan 指令总览或禁用状态
raysec.masscan

# 扫描单个文档保留地址的 TCP 1-1024 端口
raysec.masscan.basic 192.0.2.10 --rate 100 --wait 5

# 扫描单个文档保留地址的常见服务端口
raysec.masscan.quick 192.0.2.10 --rate 100

# 扫描全部 TCP 端口并限制回复正文长度
raysec.masscan.full 192.0.2.10 --rate 100 --wait 10 --reply-max-chars 3700

# 扫描 TCP 1-1024 端口并收集服务横幅
raysec.masscan.banner 192.0.2.10 --rate 100 --wait 5

# 对文档保留网段执行主机发现
raysec.masscan.discover 192.0.2.0/24 --rate 100 --wait 5

acceptMasscanRisk 默认关闭。仅在部署者开启该风险确认并重载插件后，才会注册实际 raysec.masscan.* 扫描指令。扫描使用参数数组调用 Masscan，不经过 shell。

basic 扫描 TCP 1-1024；quick 扫描常见服务端口；full 扫描 TCP 1-65535；banner 使用 --banners；discover 使用 --ping。每个 raysec.masscan.* 指令可按需传入 --rate、--wait 和 --reply-max-chars；三个选项不设人为上限。未传 --rate 或 --wait 时不向 Masscan 传对应参数，由 Masscan 使用自身默认值；未传 --reply-max-chars 时不截断回复正文。

📂 路径与安装

插件依次探测 masscanPath 和 masscanDefaultPaths。探测时先执行不会发起扫描的 masscan --echo 并检查配置输出，必要时再通过 masscan --version 的版本特征兼容返回非零退出码的实现。默认路径覆盖常见系统路径、Scoop、D 盘常见 Scoop 与 Program Files 布局；候选为目录或 Scoop 的 current 目录时，会同时检查目录根部和 bin 子目录。

🪟 Windows

前置依赖： Windows 使用 Masscan 前必须先从 Npcap 官方下载页面 下载并安装 Npcap。专用 Scoop 包不捆绑或重新分发 Npcap。

推荐使用专用 Scoop bucket 安装可复现的 Windows x64 构建：

scoop bucket add masscan-windows https://github.com/VincentZyu233/masscan-windows-builds
scoop install masscan-windows/masscan

也可以使用 Scoop 安装构建工具后，从 Masscan 官方 1.3.2 源码编译：

scoop install git gcc make
git clone --branch 1.3.2 --depth 1 https://github.com/robertdavidgraham/masscan.git
cd masscan
make

🐧 Linux

Debian / Ubuntu 系发行版：

sudo apt update
sudo apt install masscan

Fedora / RHEL 系发行版：

sudo dnf install masscan

Arch Linux 系发行版：

sudo pacman -Syu masscan

Alpine Linux：

sudo apk add masscan

🍎 macOS

Homebrew：

brew install masscan

MacPorts：

sudo port install masscan

🎯 目标与结果

masscanTimeout 默认及最大为 60 分钟。使用 --reply-max-chars 时，输出超出指定长度会附带完整 .txt 文件。

Masscan 仅接受单个 IPv4 或 IPv4 CIDR，不解析域名、URL 或 IPv6。目标格式无效时，插件会在探测可执行文件或启动扫描前直接返回错误。

⚙️ 完整配置

💬 消息回复

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | enableQuote | boolean | true | Bot 回复指令时引用触发消息。 | | enableMarkdown | boolean | true | 使用 Koishi 消息元素优化情报结果、帮助、状态提示、Nmap、Masscan 结果和 JSON 的显示；关闭后使用纯文本和裸 JSON。 |

🔐 情报数据源

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | virustotalKey | string | 未设置 | VirusTotal API Key，用于 IP、域名、URL 和文件哈希情报。 | | nvdKey | string | 未设置 | NVD API Key，填写后可获得更高请求配额。 | | enableOsv | boolean | true | 启用无需 API Key 的 OSV 漏洞查询。 | | enableCisaKev | boolean | true | 启用 CISA KEV 已知利用漏洞目录查询。 | | enableUrlAnalyze | boolean | false | 允许向 VirusTotal 提交 URL 分析任务。 | | cisaKevUrl | string | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json | CISA KEV 数据地址，可替换为镜像。 |

🌐 网络请求

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | requestTimeout | number | 15000 | 外部情报 API 请求超时时间，单位为毫秒；范围为 1000 至 60000。 | | requestRetries | number | 2 | 遇到限流、超时或服务错误后的重试次数；范围为 0 至 5。 | | proxyMode | config \| environment \| none | none | 选择插件配置代理、环境变量代理或不使用代理。 | | proxyUrl | string | 未设置 | proxyMode 为 config 时使用的代理地址，支持 HTTP、HTTPS 和 SOCKS。 |

💾 缓存与日志

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | cacheTtlMinutes | number | 10 | 情报结果内存缓存时间，单位为分钟；设为 0 时关闭缓存。 | | logLevel | off \| error \| debug | error | 插件日志级别。 |

🛰️ Nmap 扫描

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | acceptNmapRisk | boolean | false | Nmap 扫描总开关及风险确认；关闭时不注册实际扫描子指令。 | | redactNmapCredentials | boolean | true | 在 ssh-run 回复和错误中隐藏 SSH 密码，建议保持开启。 | | nmapPath | string | 空字符串 | 优先尝试的 Nmap 命令、可执行文件或目录；失败后继续尝试默认候选路径。 | | nmapDefaultPaths | string[] | nmap、Scoop shim、Windows 安装路径、Linux 与 macOS 常用路径 | 依次尝试的 Nmap 命令、可执行文件或目录。 | | nmapTimeout | number | 3600000 | 单次扫描超时时间，单位为毫秒；默认及最大值均为 60 分钟。 | | nmapReplyMaxChars | number | 3700 | Nmap 结果正文最大字符数；超出时截断正文并附带完整结果文件。 |

📡 Masscan 扫描

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | acceptMasscanRisk | boolean | false | Masscan 扫描总开关及风险确认；关闭时不注册实际扫描子指令。 | | masscanPath | string | 空字符串 | 优先尝试的 Masscan 命令、可执行文件或目录；失败后继续尝试默认候选路径。 | | masscanDefaultPaths | string[] | masscan、Linux、macOS 与 Windows 常用路径 | 依次尝试的 Masscan 命令、可执行文件或目录。 | | masscanTimeout | number | 3600000 | 单次扫描超时时间，单位为毫秒；默认及最大值均为 60 分钟。 |