本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 S3 執行差異碼掃描
<a name="run-diff-scan-s3"></a>

執行差異 （差異） 程式碼掃描，以僅分析原始程式碼中變更的行，而不是執行完整的儲存庫掃描。差異掃描比完整掃描更快，並產生針對特定程式碼變更的調查結果，因此非常適合在開發工作流程中進行合併前驗證。

與由第三方來源控制提供者事件自動觸發的提取請求型程式碼檢閱不同 （請參閱[檢閱提取請求中的程式碼安全性問題清單](review-code-findings-github.md))，差異掃描是透過 AWS Security Agent API 或 SDK 以程式設計方式啟動。您可以將統一的 diff 檔案上傳到 S3，並在啟動程式碼檢閱任務時參考該檔案。

## 差異掃描的運作方式
<a name="_how_differential_scans_work"></a>

差異掃描會在儲存庫的完整內容中分析程式碼變更。當您使用上傳至 S3 的原始程式碼建立程式碼檢閱資源時，差異掃描會使用完整的儲存庫做為內容，同時特別將問題清單集中在 diff 中變更的行上。這可讓掃描識別您的變更與現有程式碼互動所產生的安全問題，例如驗證流程中斷、跨模組不安全的資料處理，或公開現有漏洞的變更。

掃描程序：。您可以將統一的 diff 檔案 ( 的輸出`git diff`) 上傳到連線至 Agent Space 的 S3 儲存貯體。您可以使用指向差異 S3 位置的`diffSource`參數來呼叫 `StartCodeReviewJob` API。AWS Security Agent 只會分析 diff 中變更的程式碼是否有安全漏洞，以及是否符合組織的安全需求。調查結果的範圍是已變更的行，具有嚴重性評分、程式碼位置和修復指導。

## 先決條件
<a name="_prerequisites"></a>

開始前，請確保您具備以下條件：
+ 啟用程式碼檢閱的客服人員空間 （請參閱 [啟用程式碼檢閱](enable-code-review-scan.md))
+ 已為目標儲存庫建立的程式碼檢閱資源，並將完整的原始程式碼上傳至連線至您的 Agent Space 的 S3 儲存貯體。完整的儲存庫提供內容，可讓您更深入地分析變更與現有程式碼的互動方式。[建立程式碼檢閱](perform-code-review-scan.md) 如需建立程式碼檢閱和上傳原始程式碼的說明，請參閱 。
+ 連接至客服人員空間的 S3 儲存貯體
+ 上傳到 S3 儲存貯體和呼叫的 IAM 許可 `securityagent:StartCodeReviewJob` 
+ 從程式碼產生的統一 diff 檔案變更 （例如 的輸出`git diff main..feature-branch`)

**提示**  
為了取得最準確的結果，請確定您的程式碼檢閱資源具有上傳至 S3 的最新版本完整原始程式碼。差異掃描會使用此完整儲存庫做為內容，以了解您在分析變更行時的應用程式架構、資料流程和現有安全控制。

## 步驟 1：產生 diff 檔案
<a name="_step_1_generate_a_diff_file"></a>

產生代表您要掃描之程式碼變更的統一 diff。

```
git diff main..feature-branch > changes.diff
```

或者，針對階段變更產生差異：

```
git diff --cached > changes.diff
```

**提示**  
diff 檔案應為標準統一 diff 格式。AWS Security Agent 會剖析檔案路徑，並從 diff 標頭變更行以限制其分析的範圍。

## 步驟 2：將差異上傳至 S3
<a name="_step_2_upload_the_diff_to_s3"></a>

將 diff 檔案上傳到連線至 Agent Space 的 S3 儲存貯體。

```
aws s3 cp changes.diff s3://my-security-agent-bucket/diffs/changes.diff
```

**重要**  
S3 儲存貯體必須是已連線至客服人員空間的儲存貯體。與您的 Agent Space 相關聯的 IAM 服務角色必須具有此位置的讀取存取權。如需連接 S3 儲存貯體的說明[啟用程式碼檢閱](enable-code-review-scan.md)，請參閱 。

## 步驟 3：啟動差異碼檢閱任務
<a name="_step_3_start_a_differential_code_review_job"></a>

使用 `diffSource` 參數呼叫 `StartCodeReviewJob` API 以啟動差異掃描。

### 使用 AWS CLI
<a name="_using_the_aws_cli"></a>

```
aws securityagent start-code-review-job \
  --agent-space-id "your-agent-space-id" \
  --code-review-id "your-code-review-id" \
  --diff-source '{"s3Uri": "s3://my-security-agent-bucket/diffs/changes.diff"}'
```

### 使用 AWS 開發套件 (Python)
<a name="_using_the_aws_sdk_python"></a>

```
import boto3

client = boto3.client('securityagent')

response = client.start_code_review_job(
    agentSpaceId='your-agent-space-id',
    codeReviewId='your-code-review-id',
    diffSource={
        's3Uri': 's3://my-security-agent-bucket/diffs/changes.diff'
    }
)

print(f"Job started: {response['codeReviewJobId']}")
```

### 使用 AWS 開發套件 (JavaScript/TypeScript)
<a name="_using_the_aws_sdk_javascripttypescript"></a>

```
import { SecurityAgentClient, StartCodeReviewJobCommand } from '@aws-sdk/client-securityagent';

const client = new SecurityAgentClient({ region: 'us-east-1' });

const response = await client.send(new StartCodeReviewJobCommand({
  agentSpaceId: 'your-agent-space-id',
  codeReviewId: 'your-code-review-id',
  diffSource: {
    s3Uri: 's3://my-security-agent-bucket/diffs/changes.diff',
  },
}));

console.log(`Job started: ${response.codeReviewJobId}`);
```

API 會立即傳回 `codeReviewJobId`和 `status` `IN_PROGRESS`。

## 步驟 4：監控掃描
<a name="_step_4_monitor_the_scan"></a>

輪詢程式碼檢閱任務狀態，直到完成為止。

```
aws securityagent get-code-review-job \
  --agent-space-id "your-agent-space-id" \
  --code-review-id "your-code-review-id" \
  --code-review-job-id "the-job-id"
```

任務會進行與完整程式碼檢閱相同的階段：預檢 → 靜態分析 → 完成。差異掃描通常會比完整掃描更快完成，因為它們會分析較少的程式碼行。

## 步驟 5：檢閱問題清單
<a name="_step_5_review_findings"></a>

任務完成後，列出程式碼檢閱任務的問題清單。

```
aws securityagent list-findings \
  --agent-space-id "your-agent-space-id" \
  --code-review-id "your-code-review-id" \
  --code-review-job-id "the-job-id"
```

每個調查結果包括：
+ 安全問題的描述
+ 嚴重性等級 （關鍵、高、中或低）
+ 參考 diff 中特定行的程式碼位置
+ 解釋潛在影響的風險推理
+ 修補指引

如需了解問題清單並採取行動的詳細資訊，請參閱 [檢閱程式碼檢閱的問題清單](review-code-scan-findings.md)。

## 配額和限制
<a name="_quotas_and_limits"></a>
+ 差異中變更的檔案數量上限：3，000 個檔案或總差異大小 5 MB
+ 問題清單上限為每次掃描 30 個，依嚴重性排序 （關鍵 > 高 > 中 > 低）

## 後續步驟
<a name="_next_steps"></a>

執行差異掃描之後：
+ 檢閱問題清單並套用修補指引 （請參閱 [檢閱程式碼檢閱的問題清單](review-code-scan-findings.md))
+ 針對每個提取請求啟用自動程式碼檢閱的提取請求註解 （請參閱 [啟用 GitHub 儲存庫的提取請求程式碼檢閱](enable-code-review.md))
+ 定期執行完整的程式碼檢閱，以捕捉個別變更以外的問題 （請參閱 [建立程式碼檢閱](perform-code-review-scan.md))
+ 使用 IDE 整合直接從您的開發環境執行差異掃描 （請參閱 [從 IDE 執行程式碼安全掃描](code-review-ide-integration.md))