本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 S3 运行差分代码扫描
<a name="run-diff-scan-s3"></a>

运行差异（差异）代码扫描，仅分析源代码中更改的行，而不是执行完整的存储库扫描。差异扫描比完全扫描更快，可以生成针对特定代码更改的结果，因此非常适合开发工作流程中的合并前验证。

与由第三方源代码控制提供商事件自动触发的基于拉取请求的代码审查不同（参见[查看拉取请求中的代码安全发现](review-code-findings-github.md)），差异扫描是通过 AWS Security Agent API 或 SDK 以编程方式启动的。您可以将统一的差异文件上传到 S3，并在开始代码审查任务时引用该文件。

## 差异扫描的工作原理
<a name="_how_differential_scans_work"></a>

差异扫描会在仓库的完整上下文中分析您的代码更改。当您使用源代码上传到 S3 创建代码审查资源时，差异扫描会使用完整的存储库作为上下文，同时将发现的重点放在差异中更改的行上。这使扫描能够识别您的更改与现有代码的交互方式所产生的安全问题，例如身份验证流程中断、跨模块的数据处理不安全或暴露现有漏洞的更改。

扫描过程:. 您将统一的差异文件（的输出`git diff`）上传到连接到代理空间的 S3 存储桶。您使用指向差异的 S3 位置的`diffSource`参数调用 `StartCodeReviewJob` API。AWS Security Agent 仅分析差异中已更改的代码，以确定是否存在安全漏洞以及是否符合贵组织的安全要求。调查结果仅限于更改后的行，包括严重性等级、代码位置和补救指南。

## 先决条件
<a name="_prerequisites"></a>

在开始之前，请确保您满足以下条件：
+ 启用了代码审查的代理空间（请参阅[启用代码审查](enable-code-review-scan.md)）
+ 已为目标存储库创建的代码审查资源，其完整源代码已上传到连接到代理空间的 S3 存储桶。完整的存储库提供了上下文，可以更深入地分析您的更改与现有代码的交互方式。有关创建代码审查和上传源代码的说明，请参阅[创建代码审查](perform-code-review-scan.md)。
+ 连接到您的代理空间的 S3 存储桶
+ 上传到 S3 存储桶并调用的 IAM 权限 `securityagent:StartCodeReviewJob` 
+ 根据您的代码更改生成的统一差异文件（例如，的`git diff main..feature-branch`输出）

**提示**  
为了获得最准确的结果，请确保您的代码审查资源已将完整源代码的最新版本上传到 S3。差异扫描使用这个完整的存储库作为上下文，在分析更改的行时了解您的应用程序架构、数据流和现有的安全控制措施。

## 步骤 1：生成差异文件
<a name="_step_1_generate_a_diff_file"></a>

生成一个表示要扫描的代码更改的统一差异。

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

或者，为分阶段的更改生成差异：

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

**提示**  
差异文件应采用标准的统一差异格式。AWS Security Agent 会解析文件路径并更改差异标头中的行以确定其分析范围。

## 第 2 步：将差异上传到 S3
<a name="_step_2_upload_the_diff_to_s3"></a>

将差异文件上传到连接到您的代理空间的 S3 存储桶。

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

**重要**  
S3 存储桶必须是已连接到您的代理空间的存储桶。与您的代理空间关联的 IAM 服务角色必须对该位置具有读取权限。有关连接 S3 存储桶的说明，请参阅[启用代码审查](enable-code-review-scan.md)。

## 第 3 步：开始差异代码审查作业
<a name="_step_3_start_a_differential_code_review_job"></a>

使用`diffSource`参数调用 `StartCodeReviewJob` API 以启动差异扫描。

### 使用 Amazon 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"
```

每项调查发现包括：
+ 对安全问题的描述
+ 严重性级别（严重、高、中或低）
+ 引用差异中特定行的代码位置
+ 解释潜在影响的风险推理
+ 补救指南

有关了解和根据发现采取行动的更多信息，请参阅[查看代码审查的结果](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)）