REST API

内置的 REST API 接口向您提供了可视化 RESTful Web 服务的方法。API 文档可使用 Swagger 构建,在其中能够测试 API 操作并立即查看结果,从而帮助您更快地扫描应用程序。

关于此任务

通过遵循该示例来了解如何使用交互式框架来通过使用 /api/v4/Apps/ImportFile REST API 导入应用程序库存。

过程

  1. 选择工具 > API
  2. 单击页面右侧的 Swagger 链接。您将自动登录到 Swagger。
  3. 创建资产组:
    1. 展开资产组 API 并单击 POST /api/v4/AssetGroups
    2. "string" 参数替换为资产组的名称和描述。保留引号。创建资产组 API
    3. 单击执行
    4. 记下响应正文部分中的标识;您需要在下一个 API 中使用该标识。
      从响应正文复制标识
  4. 导入应用程序清单文件:
    1. 展开应用程序 API 并单击 POST /api/v4/Apps/ImportFile
      实施部分中,有一个样本文件,可下载该文件以了解文件中包含的属性类型。
    2. 参数部分的 Value 字段中输入来自步骤 3d 的 assetGroupId
    3. 单击 uploadedFile 部分中的浏览,找到要导入的应用程序 CSV 文件。
    4. 单击执行
      成功导入如下所示:成功应用程序导入

示例

使用 REST API 导入扫描文件(包括结果)
您可通过以下步骤导入扫描文件(包括结果),而不在 AppScan 360° 中运行扫描:
  1. 确保您使用 API api/v4/Account/ApiKeyLogin 登录到 Swagger。
  2. 使用 API api/v4/FileUpload 上载扫描文件,并保存文件标识以备后续使用。例如,

    "FileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"

  3. 展开扫描 API 并单击 POST /api/v4/Scans/Dast。更新以下参数以仅生成报告而不运行扫描。
    1. 扫描或模板文件标识:更新您在步骤 2 中复制的文件标识

      "ScanOrTemplateFileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"

    2. 测试操作:将其设置为 ReportOnly

      "TestOperation": "ReportOnly"

    注: 确保已映射 AppID、ScanName 以及运行 API POST /api/v4/Scans/Dast 所需的其他参数。

使用直接 API 密钥进行认证

通过在定制 HTTP 标头中发送您的 API 密钥标识和密码来对 API 请求进行认证。直接 API 密钥方法省去了将密钥兑换为会话令牌的步骤。这简化了自动化脚本和 CI/CD 集成,因为您不再需要管理令牌生命周期或过期问题。主要优势包括:

  • 简化的自动化:无需编写用于“登录”、“获取令牌”或“刷新令牌”的逻辑。
  • 类似无状态的体验:每次请求时都发送密钥;系统会在后台管理会话。
  • 降低复杂性:非常适合用于简单脚本、一次性任务,或难以维护会话状态的集成。

技术规范:

要使用此功能,请在您的 HTTP 请求中包含以下标头:

  • 标头名称:X-Api-Key
  • 标头值格式:该值必须包含由冒号 (:) 分隔的密钥标识和密钥密码。KeyID:KeySecret
  • 示例:如果您的凭证为:
    • Key ID: b0977ee5-c9df-0c8a-5909-184c690cbfa5
    • Key Secret: UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
      则标头应如下所示:
      X-Api-Key: b0977ee5-c9df-0c8a-5909-184c690cbfa5:UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
实现示例:
  1. cURL
    curl -X GET "https://cloud.appscan.com/api/v4/Scans" \
                                        -H "Accept: application/json" \
                                        -H "X-Api-Key: <Your_Key_ID>:<Your_Key_Secret>"
  2. Python(请求库)
    import requests
                                            
                                            url = "https://cloud.appscan.com/api/v4/Scans"
                                            key_id = "your_key_id"
                                            key_secret = "your_key_secret"
                                            
                                            # Construct the header value
                                            header_value = f"{key_id}:{key_secret}"
                                            
                                            headers = {
                                            "Accept": "application/json",
                                            "X-Api-Key": header_value
                                            }
                                            
                                            response = requests.get(url, headers=headers)
                                            
                                            if response.status_code == 200:
                                            print("Success:", response.json())
                                            else:
                                            print("Error:", response.status_code, response.text)
                                        
安全和行为注意事项:
  • 过期和刷新:出于性能考虑,系统会维持一个 30 分钟的会话,但您无需对其进行跟踪。如果该会话过期,则您的密钥将重新进行验证,并且系统会自动创建新会话。

  • 撤销:如果您在 AppScan 门户网站中删除自己的 API 密钥,则访问权限将被立即撤销。任何使用该密钥的活动会话都将被终止,并且后续请求将返回“401 未经授权”。

  • 许可权:使用此方法认证的请求将继承拥有 API 密钥的用户帐户所具有的许可权。

故障诊断:
  • 401 未经授权:验证您的密钥标识和密码是否正确,并确认该密钥未被撤销或删除。

  • 格式错误:确保密钥标识、冒号和密钥密码之间没有任何空格(例如,ID:Secret,而不是 ID : Secret)。