当前位置：首页 > news >正文

Natlas API开发详解：自动化扫描任务与数据查询接口使用指南

news 2026/8/15 19:18:55

Natlas API开发详解：自动化扫描任务与数据查询接口使用指南

【免费下载链接】natlasAttack Surface Management since before Attack Surface Management was a thing项目地址: https://gitcode.com/gh_mirrors/na/natlas

Natlas是一款强大的攻击面管理工具，其API接口为开发者提供了自动化扫描任务与数据查询的能力。通过Natlas API，您可以轻松地集成扫描功能到自己的应用中，实现高效的网络安全管理。

一、API基础信息

1.1 API规范与认证

Natlas API遵循Swagger 2.0规范，详细定义了所有可用接口。您可以在项目的spec/swagger.yaml文件中查看完整的API文档。

API认证采用bearer {agent_id}:{auth_token}的方式，在请求头中添加Authorization字段进行身份验证。这种认证方式确保了API访问的安全性，只有拥有有效令牌的代理才能与服务器进行通信。

1.2 基础路径与数据格式

API的基础路径为/api，支持HTTP和HTTPS两种协议。所有请求和响应的数据格式均为JSON，便于开发者进行解析和处理。

二、核心API接口详解

2.1 获取扫描服务列表

接口路径：/natlas-services
请求方法：GET
功能描述：返回最新版本的所有扫描服务列表，供nmap使用。

该接口返回的服务列表是一个文本 blob，包含换行分隔的服务信息，直接用于nmap的--servicedb参数。通过定期调用此接口，您可以确保扫描工具使用最新的服务定义，提高扫描准确性。

2.2 获取扫描任务

接口路径：/getwork
请求方法：GET
功能描述：获取一个扫描任务，包括目标IP、扫描配置等信息。

响应中包含scan_id、target、tags和agent_config等关键信息。agent_config提供了详细的扫描参数，如版本检测、OS检测、脚本超时时间等，您可以根据这些配置执行相应的扫描操作。

2.3 提交扫描结果

接口路径：/submit
请求方法：POST
功能描述：提交扫描结果到服务器。

提交的数据需要包含scan_id、ip、scan_reason以及nmap生成的xml、nmap和gnmap格式数据。此外，还可以包含扫描开始和结束时间、端口数量、截图等信息。服务器在成功解析并处理结果后，会返回相应的状态信息。

2.4 查询服务器状态

接口路径：/status
请求方法：GET
功能描述：获取服务器的当前状态信息。

通过该接口，您可以了解服务器已完成的扫描周期数、当前周期开始时间、有效范围大小、服务器启动时间等重要状态数据。这些信息对于监控扫描进度和系统健康状况非常有用。

三、API使用示例

3.1 认证示例

在请求头中添加认证信息：

Authorization: bearer your_agent_id:your_auth_token

3.2 获取扫描任务示例

发送GET请求到/api/getwork，您将收到类似以下的响应：

{ "scan_id": "7v8emfj4ux2vutmn", "scan_reason": "automatic", "target": "127.34.23.56", "tags": ["corpnet-a", "marketing"], "agent_config": { "versionDetection": true, "osDetection": true, "scanTimeout": 660 } }

3.3 提交扫描结果示例

发送POST请求到/api/submit，请求体包含扫描结果数据：

{ "scan_id": "7v8emfj4ux2vutmn", "ip": "127.34.23.56", "scan_reason": "automatic", "xml_data": "...", "nmap_data": "...", "gnmap_data": "...", "scan_start": "2023-07-01T10:00:00Z", "scan_stop": "2023-07-01T10:10:00Z", "is_up": true, "port_count": 5 }