REST API

開始之前

註：要求速率限制：每分鐘最多可發出 500 個要求（滑動視窗）。此限制會針對每位已鑑別之使用者分別計算，未鑑別的要求則依每個唯一 IP 位址分別計算。若超過此限制，AppScan 會回傳 429 狀態碼，並附上回應訊息：「過多要求。」

執行這項作業的原因和時機

遵循這個範例，使用 /api/v4/Apps/ImportFile REST API 來匯入應用程式庫存，以瞭解如何使用互動式架構。

程序

移至 Swagger 頁面並將其加入書籤供日後參考：
- 北美資料中心使用者： https://cloud.appscan.com/swagger/index.html
- 西歐資料中心使用者： https://eu.cloud.appscan.com/swagger/index.html
  註：若要存取舊版 (v2)，請從「選取定義」下拉式功能表中選取 "API v2"。
使用您的 HCL ID 登入 Swagger。
1. 展開「帳戶」API，然後按一下 POST api/v4/Account/ApiKeyLogin 以展開作業詳細資料。
2. 以您的 API 金鑰 ID 與 API 金鑰密碼取代 "string" 參數。保留引號。
3. 按一下「執行」。
4. 從「回應主體」複製 "Token" 值。
5. 將它貼至 Swagger 介面頂端的「存取記號」欄位。
  從現在起，記號會自動套用到所有 API 呼叫。
建立資產群組：
1. 展開資產群組 API，然後按一下 POST /api/v4/AssetGroups。
2. 以資產群組的名稱和說明來取代 "string" 參數。保留引號。
3. 按一下「執行」。
4. 請記下「回應主體」區段中的 ID；您必須在下一個 API 中使用該 ID。
匯入應用程式庫存檔：
1. 展開應用程式 API，然後按一下 POST /api/v4/Apps/ImportFile。
  在「實作」區段中，有一個範例檔案可供下載，讓您瞭解要併入您檔案的屬性類型。
2. 將步驟 3d 的 assetGroupId 輸入「參數」區段的 Value 欄位。
3. 按一下 uploadedFile 區段中的「瀏覽」，以尋找要匯入的應用程式 CSV 檔。
4. 按一下「執行」。
  系統會顯示如下所示的成功匯入：

範例

使用 REST API 匯入掃描檔案，包括其結果

您可以匯入掃描檔案（包括其結果）但不在 AppScan on Cloud 執行掃描。請按下列步驟操作：

確認您已使用以下 API 登入 Swagger：api/v4/Account/ApiKeyLogin。
使用以下 API 上傳掃描檔案：api/v4/FileUpload；然後記下「FileId」供稍後使用。例如，
"FileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"
展開「掃描」API，然後按一下 POST /api/v4/Scans/Dast。更新下列參數，以僅產生報告而不執行掃描。
1. 「ScanOrTemplateFileId:」：更新在步驟 2 複製的「FileId」。
  "ScanOrTemplateFileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"
2. 「TestOperation」：將此項設定為 ReportOnly
  "TestOperation": "ReportOnly"
註：請確定您已將 AppID、ScanName 及其他必要參數對應完成，才能執行 API POST /api/v4/Scans/Dast。

使用直接 API 金鑰進行鑑別

透過在自訂 HTTP 標頭中傳送您的 API 金鑰 ID 和密碼，即可鑑別 API 要求。直接 API 金鑰方法會略過將金鑰交換為階段作業記號的步驟。這可簡化自動化指令碼與 CI/CD 整合，因為您不再需要管理記號的生命週期或期限。主要優點包括：

簡化的自動化過程：無需撰寫「登入」、「獲取記號」或「重新整理記號」的邏輯。
類似無狀態的體驗：針對每個要求傳送金鑰；系統會在背景中管理階段作業。
降低複雜度：適用於簡單指令碼、單次作業，或難以維護階段作業狀態的整合情況。

技術規格：

若要使用此功能，請在您的 HTTP 要求中加入以下標頭：

標頭名稱：X-Api-Key
標頭值格式：此值必須包含您的金鑰 ID 和金鑰密碼（以冒號 (:) 分隔）。KeyID:KeySecret
範例：如果您的認證為：
- Key ID: b0977ee5-c9df-0c8a-5909-184c690cbfa5
- Key Secret: UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
  標頭應如下所示：
```
X-Api-Key: b0977ee5-c9df-0c8a-5909-184c690cbfa5:UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
```

實作範例：

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>"

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 和密碼正確無誤，且金鑰並未遭撤銷或刪除。
格式錯誤：確認金鑰 ID、冒號及金鑰密碼之間沒有空格（例如，ID:Secret，而不是 ID : Secret）。