As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Execute uma varredura de código diferencial com o S3
<a name="run-diff-scan-s3"></a>

Execute uma varredura de código diferencial (diff) para analisar somente as linhas alteradas em seu código-fonte, em vez de realizar uma verificação completa do repositório. As varreduras diferenciais são mais rápidas do que as varreduras completas e produzem descobertas direcionadas a alterações de código específicas, tornando-as ideais para validação pré-mesclagem em fluxos de trabalho de desenvolvimento.

Diferentemente da revisão de código baseada em pull request, que é acionada automaticamente por eventos terceirizados do provedor de controle de origem (consulte[Analise as descobertas de segurança do código em pull requests](review-code-findings-github.md)), as varreduras diferenciais são iniciadas programaticamente por meio da API ou do SDK do AWS Security Agent. Você carrega um arquivo diff unificado para o S3 e faz referência a ele ao iniciar um trabalho de revisão de código.

## Como funcionam os escaneamentos diferenciais
<a name="_how_differential_scans_work"></a>

Uma varredura diferencial analisa suas alterações de código no contexto completo do seu repositório. Quando você cria um recurso de revisão de código com seu código-fonte carregado no S3, a verificação diferencial usa o repositório completo como contexto enquanto concentra as descobertas especificamente nas linhas alteradas em seu diff. Isso permite que a verificação identifique problemas de segurança decorrentes da forma como suas alterações interagem com o código existente, como fluxos de autenticação interrompidos, tratamento inseguro de dados entre módulos ou alterações que expõem vulnerabilidades existentes.

O processo de digitalização:. Você carrega um arquivo diff unificado (a saída de`git diff`) em um bucket do S3 conectado ao seu Agent Space. Você chama a `StartCodeReviewJob` API com um `diffSource` parâmetro apontando para a localização do seu diff no S3. O AWS Security Agent analisa somente o código alterado no diff para verificar as vulnerabilidades de segurança e a conformidade com os requisitos de segurança da sua organização. As descobertas têm como escopo as linhas alteradas, com classificações de severidade, localizações de códigos e orientações de remediação.

## Pré-requisitos
<a name="_prerequisites"></a>

Antes de começar, verifique se você tem:
+ Um espaço do agente com a revisão de código ativada (consulte[Ativar revisão de código](enable-code-review-scan.md))
+ Um recurso de revisão de código já criado para o repositório de destino, com o código-fonte completo carregado no bucket do S3 conectado ao seu Agent Space. O repositório completo fornece um contexto que permite uma análise mais profunda de como suas alterações interagem com o código existente. Consulte [Crie uma revisão de código](perform-code-review-scan.md) para obter instruções sobre como criar uma revisão de código e fazer o upload do código-fonte.
+ Um bucket S3 conectado ao seu Agent Space
+ Permissões do IAM para fazer upload para o bucket do S3 e chamar `securityagent:StartCodeReviewJob` 
+ Um arquivo diff unificado gerado a partir de suas alterações de código (por exemplo, a saída de`git diff main..feature-branch`)

**dica**  
Para obter resultados mais precisos, certifique-se de que seu recurso de revisão de código tenha a versão mais recente do código-fonte completo enviada para o S3. O diff scan usa esse repositório completo como contexto para entender a arquitetura do aplicativo, os fluxos de dados e os controles de segurança existentes ao analisar as linhas alteradas.

## Etapa 1: gerar um arquivo diff
<a name="_step_1_generate_a_diff_file"></a>

Gere uma comparação unificada que represente as alterações de código que você deseja verificar.

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

Como alternativa, gere uma diferença para mudanças em etapas:

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

**dica**  
O arquivo diff deve estar no formato diff unificado padrão. O AWS Security Agent analisa os caminhos do arquivo e as linhas alteradas dos cabeçalhos diff para definir o escopo de sua análise.

## Etapa 2: faça o upload do diff para o S3
<a name="_step_2_upload_the_diff_to_s3"></a>

Faça upload do arquivo diff em um bucket do S3 conectado ao seu Espaço do Agente.

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

**Importante**  
O bucket do S3 deve ser um que já esteja conectado ao seu Espaço do Agente. A função de serviço do IAM associada ao seu espaço do agente deve ter acesso de leitura a esse local. Consulte [Ativar revisão de código](enable-code-review-scan.md) para obter instruções sobre como conectar buckets S3.

## Etapa 3: iniciar um trabalho de revisão de código diferencial
<a name="_step_3_start_a_differential_code_review_job"></a>

Chame a `StartCodeReviewJob` API com o `diffSource` parâmetro para iniciar uma verificação diferencial.

### Usar o 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"}'
```

### Usando o AWS SDK (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']}")
```

### Usando o AWS SDK () 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}`);
```

A API retorna imediatamente com um `codeReviewJobId` e `status` de`IN_PROGRESS`.

## Etapa 4: monitorar a digitalização
<a name="_step_4_monitor_the_scan"></a>

Pesquise o status do trabalho de revisão de código até que ele seja concluído.

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

O trabalho avança nas mesmas fases de uma revisão completa do código: Preflight → Análise estática → Finalização. As varreduras diferenciais geralmente são concluídas mais rapidamente do que as varreduras completas porque analisam menos linhas de código.

## Etapa 5: Analisar as descobertas
<a name="_step_5_review_findings"></a>

Depois que o trabalho for concluído, liste as descobertas do trabalho de revisão de código.

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

Cada descoberta inclui:
+ Uma descrição do problema de segurança
+ O nível de severidade (crítico, alto, médio ou baixo)
+ Localizações de código referenciando linhas específicas no diff
+ Raciocínio de risco explicando o impacto potencial
+ Orientação de remediação

Para obter mais informações sobre como entender e agir de acordo com as descobertas, consulte[Analise os resultados de uma revisão de código](review-code-scan-findings.md).

## Cotas e limites
<a name="_quotas_and_limits"></a>
+ Número máximo de arquivos alterados em um diff: 3.000 arquivos ou 5 MB de tamanho total de diff
+ As descobertas são limitadas a 30 por varredura, priorizadas por gravidade (Crítica > Alta > Média > Baixa)

## Próximas etapas
<a name="_next_steps"></a>

Depois de executar uma verificação diferencial:
+ Analise as descobertas e aplique a orientação de remediação (consulte[Analise os resultados de uma revisão de código](review-code-scan-findings.md))
+ Ative os comentários do pull request para a revisão automática do código em cada pull request (consulte[Habilitar revisão de código de pull request para GitHub repositórios](enable-code-review.md))
+ Faça uma revisão completa do código periodicamente para detectar problemas fora das alterações individuais (consulte[Crie uma revisão de código](perform-code-review-scan.md))
+ Use a integração do IDE para executar varreduras diferenciais diretamente do seu ambiente de desenvolvimento (consulte) [Execute escaneamentos de segurança de código a partir do seu IDE](code-review-ide-integration.md)