Skip to content

feat: add nsfocus-rsas-v6#483

Open
K6gg wants to merge 5 commits into
chaitin:mainfrom
K6gg:feat/add-nsfocus-rsas-service
Open

feat: add nsfocus-rsas-v6#483
K6gg wants to merge 5 commits into
chaitin:mainfrom
K6gg:feat/add-nsfocus-rsas-service

Conversation

@K6gg

@K6gg K6gg commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Closes #482

变更概述

  • 新增基于 @chaitin-ai/octobus-sdk 开发的绿盟 RSAS（网络安全漏洞扫描系统）V6.0R04F04SP09 Service Package。
  • 实现 URL 参数认证（username/password），统一附加 format=json 与 curr_lang，上游标准信封 {ret_code, ret_msg, data} 解封，参数校验及 gRPC 错误映射。
  • 覆盖任务生命周期、模板与字典、系统状态与审计日志、报表生成/下载、Agent 管理，共 42 个能力。
  • 将该服务注册到多服务调度器及 npm 软件包中。

接入设备信息

  • 厂商：绿盟科技（NSFOCUS）
  • 产品：RSAS 网络安全漏洞扫描系统（Remote Security Assessment System）
  • 已验证版本：V6.0R04F04SP09（依据产品《API 接口文档》）
  • 认证方式：URL 参数 username/password（RSAS 原生方式），凭据经 secret 绑定注入
  • 运行模式：常驻运行
  • 操作类型：读写混合（任务下发 / 报表生成 / 任务删除等为写；状态 / 列表 / 结果 / 模板查询等为读）

已实现方法

任务生命周期（21）

  • CreateTask / CreateVulnTask / CreateBaselineTask / CreatePwdTask / CreateWebTask / CreateOfflineTask / CreateDockerTask / CreateCodeauditTask / CreateHostAssetsTask / CreateWebAssetsTask：漏洞 / 配置核查 / 口令猜测 / Web / 离线 / 镜像 / 代码审计 / 主机资产 / Web 资产等各类扫描任务下发
  • GetTaskStatus：按 task_id 查询任务状态
  • PauseTask / ResumeTask / StopTask / DeleteTask / BatchDeleteTasks：任务暂停 / 续扫 / 停止 / 删除 / 批量删除
  • ListTasks / ListActiveTasks：任务列表 / 运行中任务列表
  • GetTaskResult：获取扫描结果
  • CreateAuthInfo：下发扫描认证数据
  • LoginVerify：扫描登录认证校验（支持跳板机、http/https 登录）

模板与字典（9）

  • ListSysvulnTemplate / ListWebvulnTemplate / ListBaselineTemplate / ListCodeauditTemplate / ListAssetTemplate：系统漏洞 / Web 漏洞 / 配置核查 / 代码审计 / 资产模板列表
  • GetBaselineParams：配置模板参数获取
  • CreateBaselineTemplate：配置模板下发
  • ListUserpwd / CreateUserpwd：密码字典获取 / 下发

系统与审计（2）

  • GetSystemStatus：系统状态、证书、资源使用率
  • GetLogInfo：审计日志查询

报表（5）

  • ListReportTemplate：报表模板列表
  • GenerateReport / GetReportProgress / DownloadReport：报表生成 / 进度查询 / zip 下载
  • DeleteReports：批量删除报表

Agent（5）

  • GetAgentMethodConfig / SetAgentMethodConfig：Agent 方案配置获取 / 设置
  • GetAgentAuth：Agent 授权与注册数
  • GetAgentPackageUrl：Agent 安装包下载链接
  • DownloadAgent：Agent 安装包下载（linux / windows）

本地验证

cd services
npm run validate -- --service-dir nsfocus__rsas_v6-0r04f04sp09
npm test -- --service-dir nsfocus__rsas_v6-0r04f04sp09

验证结果：

  • 服务包单测 18 项全部通过，覆盖系统状态、任务下发 / 状态 / 列表 / 结果、批量删除、报表生成 / 进度 / 下载、Agent 配置与安装包下载、模板列表，以及 TLS / 超时 / 认证与 HTTP 错误映射
  • SDK 严格校验通过，共注册 42 个一元 RPC 方法
  • 命名、proto、schema 及 4 处注册（调度器 + npm bin / files / 服务目录）校验通过

真实设备联调验证

已在绿盟 RSAS 测试设备上完成核心方法的真实调用验证（联调截图见下）。

联调验证部分截图

image image image image image image image image image image

安全说明

  • 代码、测试与文档中未提交真实设备地址、账号、口令或认证凭据。
  • 认证凭据通过 secret 绑定注入，不硬编码、不落盘。
  • 联调截图使用经授权的非生产测试数据，密码 / token / 内网 IP 均打码处理。
  • 破坏性操作（删除 / 停止任务、删除报表）仅在测试任务上验证。
  • 参数校验在 handler 侧完成，非法值返回 INVALID_ARGUMENT；接口限流返回 RESOURCE_EXHAUSTED（HTTP 429）。

已知限制

  • 3 个文件类接口（CreateTask 的 config.xml、CreateOfflineTask 离线结果文件、CreateBaselineTemplate 导出模板）需调用方提供文件内容（xml 明文或 base64），字段格式详见产品文档附录 A。
  • 上游 data 多态结构以 google.protobuf.Value 原样透传，不做强类型化。
  • 列表 / 结果接口未做自动翻页，由调用方传 page / page_size 控制。
  • RSAS 接口限流（全局 600、任务状态 / 报表进度各 300、其余 150 次/分）由设备侧执行，超限返回 HTTP 429。

@K6gg
feat: add nsfocus-rsas-v6-0r04f04sp09 service package
962e558 
Add OctoBus adapter for NSFOCUS RSAS (Remote Security Assessment System)
V6.0R04F04SP09, covering the scan task lifecycle, templates and password
dictionaries, system status and audit logs, report generation and download,
and agent management (42 RPCs).
@monkeyscan

monkeyscan Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Title: feat: add nsfocus-rsas-v6-0r04f04sp09 service pack...

Commit: 962e558

本次 PR 新增了一个 NSFOCUS RSAS V6.0R04F04SP09 的 OctoBus 服务包，包含完整的 proto 定义、服务配置、JS 实现和测试。核心实现文件 nsfocus-rsas-v6-0r04f04sp09.js 通过 undici/fetch 与 RSAS REST API 交互，实现了任务生命周期、模板管理、报告下载、Agent 管理等 42 个 RPC handler。整体代码结构清晰，测试覆盖较全，但存在两个需要关注的问题：(1) protobuf3 原始类型默认值导致可选 int64 字段始终被发送为 0；(2) pickCredential 从 config 回退读取 password 的潜在凭证泄露风险。

monkeyscan[bot]
monkeyscan Bot reviewed Jul 9, 2026
View reviewed changes
Comment thread services/nsfocus__rsas_v6-0r04f04sp09/src/nsfocus-rsas-v6-0r04f04sp09.js
monkeyscan[bot]
monkeyscan Bot reviewed Jul 9, 2026
View reviewed changes
Comment thread services/nsfocus__rsas_v6-0r04f04sp09/src/nsfocus-rsas-v6-0r04f04sp09.js
@K6gg
fix(nsfocus-rsas): read password from secret only and omit proto3-def…
f3519ca 
…ault int fields

- pickCredential no longer falls back to config/bindings for password;
  it is resolved from secret exclusively to avoid credential exposure via
  config, which permits arbitrary extra properties and is more easily logged.
- Optional int64 request fields (template_id, port, type, page, page_size)
  decode as proto3 default 0 when unset, so the previous === undefined guard
  always sent 0. Treat 0/unset alike via toOptionalPositiveInt and omit them,
  preventing invalid page=0/port=0 from reaching the RSAS API.
@monkeyscan

monkeyscan Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Title: feat: add nsfocus-rsas-v6-0r04f04sp09 service pack...

Commit: f3519ca

本次 PR 是对 nsfocus-rsas 服务的两项关键修复：

  1. 凭证作用域收紧：pickCredential 新增 scopeKeys 参数，将 password 的搜索范围显式限制为仅 secret，消除了从 config 或 bindings 回退读取密码导致的凭证泄露风险。username 仍保持原有回退策略，兼顾开发便利性。

  2. proto3 默认 int64 值处理：新增 toOptionalPositiveInt 辅助函数，解决 proto3 中未设置的 int64 标量字段解码后值为 0 而非 undefined 的问题。对于 template_id、port、type、page、page_size 等不存在有效业务值 0 的可选字段，统一将 0/unset 视为 omitted，避免将默认值错误地发送给下游 RSAS API。

变更覆盖了所有受影响的可选 int64 字段，并补充了单元测试与集成测试，测试用例对密码隔离和 proto3 默认值省略均有断言。历史发现的两个问题均已得到正确修复，整体评估为安全、正确的修复提交。

@K6gg

K6gg commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

感谢评审，两处问题已在 f3519ca 修复：

  1. 凭证泄露风险（pickCredential）：pickCredential 增加 scopeKeys 参数，password 的读取范围严格限定为 secret，不再回退到 config/bindings；username 保留回退以便开发调试。新增单测验证 config/bindings 中的 password 不被采用。

  2. proto3 int64 默认值（可选字段发送 0）：新增 toOptionalPositiveInt，将 0 与未设置一并视为省略，应用于 template_id、port、type、page、page_size 等可选 int64 字段，避免把 page=0/port=0 等无效值下发给 RSAS。新增单测在 wire 层验证 ListTasks 不再发送 type/page/page_size，CreatePwdTask 不再发送 port。

服务包单测由 18 项增至 22 项，全部通过；SDK 校验通过。

@K6gg
fix(nsfocus-rsas): normalize camelCase request keys from the proto ru…
d424f70 
…ntime

The SDK serializes request fields with protobuf jsonName (camelCase), so the
runtime delivers snake_case proto fields as e.g. taskId/templateUuid. Handlers
read snake_case, so on a real device every such field resolved to undefined.
Add normalizeRequest to mirror camelCase keys to snake_case recursively
(covering nested messages like jumparray), applied at requestFromContext.

Also default RSAS 1-based pagination (page/page_size) to sane values instead
of a proto3 0 for ListTasks and GetTaskResult.

Verified against a real RSAS device.
@monkeyscan

monkeyscan Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Title: feat: add nsfocus-rsas-v6-0r04f04sp09 service pack...

Commit: d424f70

本次 PR 对 nsfocus-rsas 服务包做了两项核心改动：

  1. 引入 normalizeRequest：由于 SDK 使用 protobuf jsonName（camelCase）序列化请求字段，运行时传入的 key 如 task_id 会变成 taskId。新增 normalizeRequest 递归函数，将 camelCase key 映射为 snake_case key（如 taskId → task_id），并在不覆盖已有 snake_case key 的前提下镜像到同一对象。该函数被接入 requestFromContext，使所有 handler 都能同时兼容 camelCase 与 snake_case 的请求字段。

  2. 分页参数默认值调整：针对 proto3 中未设置的 int64 字段默认解码为 0 的情况，将 ListTasks 与 GetTaskResult 的 page/page_size 由“0 时省略”改为“0 时赋予 1-based 默认值（1/10 或 1/20）”，避免把 proto3 的 0 默认值直接透传给下游 RSAS 接口。

测试侧补充了 normalizeRequest 的单元测试以及 camelCase 端到端测试，并对原有 ListTasks 测试断言进行了更新。

整体评估：改动思路清晰，解决了 camelCase/snake_case 不匹配与 proto3 默认值语义两个实际问题，测试覆盖到位，代码实现正确，未发现引入明显缺陷或安全隐患。

@K6gg
chore: restore executable bit on octobus-tentacles dispatcher
e353ece 
The root dispatcher bin lost its executable bit on main, which the package
validator flags. Restore mode 100755 so the validate job passes for this
entry.
@monkeyscan

monkeyscan Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Title: feat: add nsfocus-rsas-v6-0r04f04sp09 service pack...

Commit: e353ece

本次PR仅修改了单个文件 services/bin/octobus-tentacles.js 的文件权限（恢复可执行位），diff中无代码内容变更。根据commit message "chore: restore executable bit on octobus-tentacles dispatcher"，这是一个纯粹的运维/权限修复变更，不涉及任何逻辑、安全或行为层面的改动。整体评估：低风险，无需额外修改。

@K6gg

K6gg commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

关于 validate CI 的说明：

本包（nsfocus-rsas）自身校验通过，两个 bin 均为可执行位（100755）。

当前 validate 失败的报错均为可执行位问题，且与本包无关，是 upstream main 的历史遗留（main 分支自身近期 CI 亦为 failure）：

@K6gg
chore: restore executable bit on m01-intelligence bin entries
4388c16 
The m01 dispatcher wrapper and package entry lost their executable bit on
main, which the package validator flags. Restore mode 100755 (no content
change) so the validate job passes.
@monkeyscan

monkeyscan Bot commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Title: feat: add nsfocus-rsas-v6-0r04f04sp09 service pack...

Commit: 4388c16

本次变更仅恢复了两个 m01-intelligence 可执行文件的文件权限（executable bit），未涉及任何代码内容的修改。两个文件分别为 services/bin/m01-intelligence.js 和 services/m01__intelligence/bin/m01-intelligence.js。diff 中显示 +0/-0 行变更，确认是纯权限调整。该变更风险极低，无可操作性问题。

@K6gg

K6gg commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

补充：已随 commit 4388c16 恢复 m01 两个 bin 入口（bin/m01-intelligence.js、m01__intelligence/bin/m01-intelligence.js）的可执行位（100755，纯 mode、无内容改动）。至此 validate 此前报的 3 个可执行位问题全部修复，CI 应可通过。

@K6gg K6gg changed the title feat: add nsfocus-rsas-v6-0r04f04sp09 service package feat: add nsfocus-rsas-v6 Jul 9, 2026
@K6gg

K6gg commented Jul 10, 2026

Copy link
Copy Markdown
Contributor Author

@eetoc 请评审

@K6gg

K6gg commented Jul 14, 2026

Copy link
Copy Markdown
Contributor Author

@innomentats 请查查并合并

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@monkeyscan monkeyscan[bot] monkeyscan[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

绿盟 RSAS（网络安全漏洞扫描系统）

1 participant

@K6gg