TenableIoTAPI使用
1. TenableIoTAPI概述
TenableIoTAPI 是 Tenable IoT 安全平台提供的 RESTful API 接口,用于自动化和集成 Tenable IoT 的功能。通过 TenableIoTAPI,开发人员可以访问 Tenable IoT 平台中的各种数据和功能,例如设备管理、漏洞扫描、报告生成等,从而实现与其他系统或工具的无缝集成。
1.1 API端点
TenableIoTAPI 的端点通常位于 Tenable IoT 平台的服务器上,具体的 URL 格式如下:
https://<TenableIoT服务器地址>/api/v1/<资源路径>
1.2 认证
TenableIoTAPI 使用 API 密钥进行身份验证。在发送请求时,需要在请求头中包含 X-ApiKeys
字段,格式如下:
X-ApiKeys: accessKey=<您的访问密钥>; secretKey=<您的密钥>
1.3 响应格式
TenableIoTAPI 的响应通常为 JSON 格式,便于解析和处理。
2. 获取设备列表
2.1 请求方法
获取设备列表的请求方法为 GET
,请求路径为 /devices
。
2.2 请求参数
请求参数可以包括以下内容:
-
limit
:每页返回的设备数量,默认为 100。 -
offset
:偏移量,用于分页,默认为 0。 -
filter
:过滤条件,例如按设备类型、IP 地址等进行过滤。 -
sort
:排序字段,例如按设备名称、IP 地址等进行排序。 -
order
:排序顺序,可选值为asc
(升序)和desc
(降序)。
2.3 示例代码
以下是一个使用 Python 的 requests
库获取设备列表的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 请求参数
params = {
"limit": 50,
"offset": 0,
"filter": "type:camera",
"sort": "ip",
"order": "asc"
}
# 发送请求
response = requests.get(f"{base_url}/devices", headers=headers, params=params)
# 检查响应状态码
if response.status_code == 200:
devices = response.json()
# 打印设备列表
for device in devices["devices"]:
print(f"Device ID: {device['id']}, IP: {device['ip']}, Name: {device['name']}, Type: {device['type']}")
else:
print(f"请求失败,状态码: {response.status_code}")
2.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"devices": [
{
"id": 1,
"ip": "192.168.1.10",
"name": "Camera1",
"type": "camera",
"last_seen": "2023-10-01T12:00:00Z",
"vulnerabilities": 5
},
{
"id": 2,
"ip": "192.168.1.11",
"name": "Camera2",
"type": "camera",
"last_seen": "2023-10-01T12:05:00Z",
"vulnerabilities": 3
},
{
"id": 3,
"ip": "192.168.1.12",
"name": "Camera3",
"type": "camera",
"last_seen": "2023-10-01T12:10:00Z",
"vulnerabilities": 2
}
]
}
3. 获取设备详细信息
3.1 请求方法
获取设备详细信息的请求方法为 GET
,请求路径为 /devices/{device_id}
。
3.2 请求参数
请求参数包括设备 ID,例如:
GET /devices/1
3.3 示例代码
以下是一个使用 Python 的 requests
库获取特定设备详细信息的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 设备 ID
device_id = 1
# 发送请求
response = requests.get(f"{base_url}/devices/{device_id}", headers=headers)
# 检查响应状态码
if response.status_code == 200:
device = response.json()
# 打印设备详细信息
print(f"Device ID: {device['id']}")
print(f"IP: {device['ip']}")
print(f"Name: {device['name']}")
print(f"Type: {device['type']}")
print(f"Last Seen: {device['last_seen']}")
print(f"Vulnerabilities: {device['vulnerabilities']}")
else:
print(f"请求失败,状态码: {response.status_code}")
3.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 1,
"ip": "192.168.1.10",
"name": "Camera1",
"type": "camera",
"last_seen": "2023-10-01T12:00:00Z",
"vulnerabilities": [
{
"id": 101,
"name": "CVE-2023-1234",
"severity": "high",
"description": "A critical vulnerability in the camera's firmware.",
"solution": "Update to the latest firmware version."
},
{
"id": 102,
"name": "CVE-2023-1235",
"severity": "medium",
"description": "An issue with the camera's web interface.",
"solution": "Disable the web interface or apply the latest security patch."
}
]
}
4. 创建漏洞扫描任务
4.1 请求方法
创建漏洞扫描任务的请求方法为 POST
,请求路径为 /scans
。
4.2 请求参数
请求参数包括扫描任务的配置,例如:
-
name
:扫描任务的名称。 -
description
:扫描任务的描述。 -
targets
:扫描的目标设备列表。 -
policy_id
:扫描策略的 ID。 -
schedule_type
:扫描任务的调度类型,例如once
(一次性扫描)、daily
(每天扫描)等。
4.3 示例代码
以下是一个使用 Python 的 requests
库创建漏洞扫描任务的示例代码:
import requests
import json
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 扫描任务配置
scan_config = {
"name": "Monthly Camera Scan",
"description": "This scan checks for vulnerabilities in all camera devices.",
"targets": ["192.168.1.10", "192.168.1.11", "192.168.1.12"],
"policy_id": 1001,
"schedule_type": "monthly",
"start_date": "2023-11-01T00:00:00Z"
}
# 发送请求
response = requests.post(f"{base_url}/scans", headers=headers, data=json.dumps(scan_config))
# 检查响应状态码
if response.status_code == 201:
scan_task = response.json()
# 打印扫描任务 ID
print(f"Scan Task Created with ID: {scan_task['id']}")
else:
print(f"请求失败,状态码: {response.status_code}")
4.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 2001,
"name": "Monthly Camera Scan",
"description": "This scan checks for vulnerabilities in all camera devices.",
"status": "created",
"start_date": "2023-11-01T00:00:00Z",
"end_date": null,
"policy_id": 1001,
"schedule_type": "monthly",
"targets": ["192.168.1.10", "192.168.1.11", "192.168.1.12"]
}
5. 获取扫描任务状态
5.1 请求方法
获取扫描任务状态的请求方法为 GET
,请求路径为 /scans/{scan_id}
。
5.2 请求参数
请求参数包括扫描任务的 ID,例如:
GET /scans/2001
5.3 示例代码
以下是一个使用 Python 的 requests
库获取特定扫描任务状态的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 扫描任务 ID
scan_id = 2001
# 发送请求
response = requests.get(f"{base_url}/scans/{scan_id}", headers=headers)
# 检查响应状态码
if response.status_code == 200:
scan_task = response.json()
# 打印扫描任务状态
print(f"Scan Task ID: {scan_task['id']}")
print(f"Name: {scan_task['name']}")
print(f"Status: {scan_task['status']}")
print(f"Start Date: {scan_task['start_date']}")
print(f"End Date: {scan_task['end_date']}")
else:
print(f"请求失败,状态码: {response.status_code}")
5.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 2001,
"name": "Monthly Camera Scan",
"description": "This scan checks for vulnerabilities in all camera devices.",
"status": "running",
"start_date": "2023-11-01T00:00:00Z",
"end_date": "2023-11-01T01:00:00Z",
"policy_id": 1001,
"schedule_type": "monthly",
"targets": ["192.168.1.10", "192.168.1.11", "192.168.1.12"]
}
6. 获取扫描报告
6.1 请求方法
获取扫描报告的请求方法为 GET
,请求路径为 /scans/{scan_id}/report
。
6.2 请求参数
请求参数包括扫描任务的 ID,例如:
GET /scans/2001/report
6.3 示例代码
以下是一个使用 Python 的 requests
库获取特定扫描任务报告的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 扫描任务 ID
scan_id = 2001
# 发送请求
response = requests.get(f"{base_url}/scans/{scan_id}/report", headers=headers)
# 检查响应状态码
if response.status_code == 200:
report = response.json()
# 打印报告摘要
print(f"Scan Task ID: {report['scan_id']}")
print(f"Report Name: {report['name']}")
print(f"Total Devices: {report['total_devices']}")
print(f"Total Vulnerabilities: {report['total_vulnerabilities']}")
print(f"Start Date: {report['start_date']}")
print(f"End Date: {report['end_date']}")
else:
print(f"请求失败,状态码: {response.status_code}")
6.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"scan_id": 2001,
"name": "Monthly Camera Scan",
"start_date": "2023-11-01T00:00:00Z",
"end_date": "2023-11-01T01:00:00Z",
"total_devices": 3,
"total_vulnerabilities": 10,
"vulnerabilities": [
{
"vuln_id": 101,
"name": "CVE-2023-1234",
"severity": "high",
"description": "A critical vulnerability in the camera's firmware.",
"solution": "Update to the latest firmware version.",
"affected_devices": ["192.168.1.10", "192.168.1.11"]
},
{
"vuln_id": 102,
"name": "CVE-2023-1235",
"severity": "medium",
"description": "An issue with the camera's web interface.",
"solution": "Disable the web interface or apply the latest security patch.",
"affected_devices": ["192.168.1.10", "192.168.1.12"]
}
]
}
7. 获取漏洞详细信息
7.1 请求方法
获取漏洞详细信息的请求方法为 GET
,请求路径为 /vulnerabilities/{vuln_id}
。
7.2 请求参数
请求参数包括漏洞的 ID,例如:
GET /vulnerabilities/101
7.3 示例代码
以下是一个使用 Python 的 requests
库获取特定漏洞详细信息的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 漏洞 ID
vuln_id = 101
# 发送请求
response = requests.get(f"{base_url}/vulnerabilities/{vuln_id}", headers=headers)
# 检查响应状态码
if response.status_code == 200:
vulnerability = response.json()
# 打印漏洞详细信息
print(f"Vulnerability ID: {vulnerability['id']}")
print(f"Name: {vulnerability['name']}")
print(f"Severity: {vulnerability['severity']}")
print(f"Description: {vulnerability['description']}")
print(f"Solution: {vulnerability['solution']}")
print(f"Affected Devices: {vulnerability['affected_devices']}")
else:
print(f"请求失败,状态码: {response.status_code}")
7.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 101,
"name": "CVE-2023-1234",
"severity": "high",
"description": "A critical vulnerability in the camera's firmware.",
"solution": "Update to the latest firmware version.",
"affected_devices": ["192.168.1.10", "192.168.1.11"]
}
8. 更新设备信息
8.1 请求方法
更新设备信息的请求方法为 PUT
,请求路径为 /devices/{device_id}
。
8.2 请求参数
请求参数包括需要更新的设备信息,例如:
-
name
:设备名称。 -
description
:设备描述。 -
tags
:设备标签。
8.3 示例代码
以下是一个使用 Python 的 requests
库更新特定设备信息的示例代码:
import requests
import json
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 设备 ID
device_id = 1
# 更新的设备信息
device_update = {
"name": "UpdatedCamera1",
"description": "This is an updated description for Camera1.",
"tags": ["camera", "security", "updated"]
}
# 发送请求
response = requests.put(f"{base_url}/devices/{device_id}", headers=headers, data=json.dumps(device_update))
# 检查响应状态码
if response.status_code == 200:
updated_device = response.json()
# 打印更新后的设备信息
print(f"Device ID: {updated_device['id']}")
print(f"Updated Name: {updated_device['name']}")
print(f"Updated Description: {updated_device['description']}")
print(f"Updated Tags: {updated_device['tags']}")
else:
print(f"请求失败,状态码: {response.status_code}")
8.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 1,
"ip": "192.168.1.10",
"name": "UpdatedCamera1",
"type": "camera",
"last_seen": "2023-10-01T12:00:00Z",
"vulnerabilities": 5,
"description": "This is an updated description for Camera1.",
"tags": ["camera", "security", "updated"]
}
9. 删除设备
9.1 请求方法
删除设备的请求方法为 DELETE
,请求路径为 /devices/{device_id}
。
9.2 请求参数
请求参数包括设备 ID,例如:
DELETE /devices/1
9.3 示例代码
以下是一个使用 Python 的 requests
库删除特定设备的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 设备 ID
device_id = 1
# 发送请求
response = requests.delete(f"{base_url}/devices/{device_id}", headers=headers)
# 检查响应状态码
if response.status_code == 204:
print(f"Device with ID {device_id} has been successfully deleted.")
else:
print(f"请求失败,状态码: {response.status_code}")
9.4 示例数据
假设请求成功,返回的状态码为 204
,表示设备删除成功。如果没有设备被删除,可能会返回 404
状态码,表示设备不存在。
10. 创建报告
10.1 请求方法
创建报告的请求方法为 POST
,请求路径为 /reports
。
10.2 请求参数
请求参数包括报告的配置,例如:
-
name
:报告的名称。 -
description
:报告的描述。 -
format
:报告的格式,例如pdf
、csv
等。 -
devices
:报告中包含的设备列表。 -
vulnerabilities
:报告中包含的漏洞列表。 -
email
:接收报告的电子邮件地址(可选)。
10.3 示例代码
以下是一个使用 Python 的 requests
库创建报告的示例代码:
import requests
import json
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 报告配置
report_config = {
"name": "Monthly Security Report",
"description": "This report summarizes the vulnerabilities found in all camera devices.",
"format": "pdf",
"devices": ["192.168.1.10", "192.168.1.11", "192.168.1.12"],
"vulnerabilities": [101, 102],
"email": "admin@example.com"
}
# 发送请求
response = requests.post(f"{base_url}/reports", headers=headers, data=json.dumps(report_config))
# 检查响应状态码
if response.status_code == 201:
report = response.json()
# 打印报告 ID
print(f"Report Created with ID: {report['id']}")
else:
print(f"请求失败,状态码: {response.status_code}")
10.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 3001,
"name": "Monthly Security Report",
"description": "This report summarizes the vulnerabilities found in all camera devices.",
"status": "created",
"format": "pdf",
"devices": ["192.168.1.10", "192.168.1.11", "192.168.1.12"],
"vulnerabilities": [101, 102],
"email": "admin@example.com"
}
11. 获取报告状态
11.1 请求方法
获取报告状态的请求方法为 GET
,请求路径为 /reports/{report_id}
。
11.2 请求参数
请求参数包括报告的 ID,例如:
GET /reports/3001
11.3 示例代码
以下是一个使用 Python 的 requests
库获取特定报告状态的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 报告 ID
report_id = 3001
# 发送请求
response = requests.get(f"{base_url}/reports/{report_id}", headers=headers)
# 检查响应状态码
if response.status_code == 200:
report = response.json()
# 打印报告状态
print(f"Report ID: {report['id']}")
print(f"Name: {report['name']}")
print(f"Status: {report['status']}")
print(f"Format: {report['format']}")
print(f"Devices: {report['devices']}")
print(f"Vulnerabilities: {report['vulnerabilities']}")
print(f"Email: {report['email']}")
else:
print(f"请求失败,状态码: {response.status_code}")
11.4 示例数据
假设请求成功,返回的 JSON 数据可能如下所示:
{
"id": 3001,
"name": "Monthly Security Report",
"description": "This report summarizes the vulnerabilities found in all camera devices.",
"status": "processing",
"format": "pdf",
"devices": ["192.168.1.10", "192.168.1.11", "192.168.1.12"],
"vulnerabilities": [101, 102],
"email": "admin@example.com"
}
12. 下载报告
12.1 请求方法
下载报告的请求方法为 GET
,请求路径为 /reports/{report_id}/download
。
12.2 请求参数
请求参数包括报告的 ID,例如:
GET /reports/3001/download
12.3 示例代码
以下是一个使用 Python 的 requests
库下载特定报告的示例代码:
import requests
# Tenable IoT API 的基础 URL
base_url = "https://<TenableIoT服务器地址>/api/v1"
# API 密钥
access_key = "<您的访问密钥>"
secret_key = "<您的密钥>"
# 请求头
headers = {
"X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
"Content-Type": "application/json"
}
# 报告 ID
report_id = 3001
# 发送请求
response = requests.get(f"{base_url}/reports/{report_id}/download", headers=headers)
# 检查响应状态码
if response.status_code == 200:
# 保存报告文件
with open(f"report_{report_id}.pdf", "wb") as file:
file.write(response.content)
print(f"Report with ID {report_id} has been successfully downloaded.")
else:
print(f"请求失败,状态码: {response.status_code}")
12.4 示例数据
假设请求成功,返回的内容将是一个二进制文件,通常是 PDF 或 CSV 格式的报告文件。报告文件将被保存到本地文件系统中。
13. 总结
TenableIoTAPI 提供了一系列强大的功能,帮助开发人员自动化和集成 Tenable IoT 平台中的设备管理和漏洞扫描任务。通过本文档中的示例代码和数据,您可以快速上手使用 TenableIoTAPI 进行开发。如果您有任何问题或需要进一步的帮助,请参考 Tenable IoT 的官方文档或联系 Tenable 支持团队。
希望本文档对您有所帮助,祝您在使用 TenableIoTAPI 过程中一切顺利!