Configurando seu harness de vulnerabilidades com IA, Parte 2: o arquivo de steering

O problema com modelos de IA sem configuração

A AWS publicou a segunda parte de sua série sobre harness de vulnerabilidades com IA, e desta vez o foco é a peça que realmente determina a qualidade das análises: o arquivo de steering. Se a primeira parte da série cobriu a arquitetura do harness, esta parte cobre a configuração — e a distinção importa muito mais do que parece.

A lição central do post é direta: o mesmo modelo de fronteira que produz uma avaliação de segurança rigorosa e baseada em evidências com um conjunto de instruções vai produzir cadeias de ataque alucinadas e classificações de severidade infladas com outro. A capacidade do modelo é fixa. O que você configura é o julgamento dele.

As iterações iniciais da equipe da AWS produziram achados que soavam autoritativos mas desmoronavam sob escrutínio. O modelo reportava uma injeção SQL em uma função que não existia, afirmava confiança ALTA sem nenhuma base estrutural, ou ignorava um AWS WAF em modo de bloqueio diretamente no caminho da requisição. A correção não foi um modelo melhor — foi uma direção melhor.

O que é um arquivo de steering

Um arquivo de steering é um conjunto de instruções que um assistente de codificação com IA carrega no início de cada sessão. Ferramentas diferentes usam convenções diferentes: o Kiro lê arquivos markdown do diretório .kiro/steering/, o Claude Code usa CLAUDE.md, o Cursor usa .cursorrules, e o GitHub Copilot usa .github/copilot-instructions.md. A função é a mesma em todos os casos: instruções persistentes que moldam como o modelo aborda o trabalho no repositório.

Aplicado à análise de segurança, um arquivo de steering codifica a metodologia de triagem da equipe como instruções executáveis pelo modelo. Em vez de depender de engenheiros individuais para aplicar essa metodologia de forma consistente, você a codifica uma vez e o modelo a aplica uniformemente em todas as análises.

Por que configuração supera prompting pontual

Um prompt de turno único — “encontre vulnerabilidades neste código” — produz o que o comportamento padrão do modelo gera. Esse padrão é otimizado para utilidade, não para rigor. O modelo vai encontrar coisas para reportar porque você pediu para encontrar coisas.

Um arquivo de steering muda o padrão. Ele estabelece três pilares fundamentais:

O que conta como evidência: sem instruções explícitas, um modelo trata seu próprio raciocínio como evidência suficiente. O arquivo de steering exige verificação estrutural — fluxo de dados confirmado, existência de função confirmada e caminho de chamada confirmado — antes de um achado ser reportado.
O que confiança significa: por conta própria, um modelo atribui confiança com base em quão plausível sua narrativa soa para si mesmo. O arquivo de steering substitui essa confiança auto-reportada por uma fórmula calculada a partir de sinais estruturais binários.
Como a infraestrutura afeta a prioridade: deixado aos seus padrões, um modelo avalia vulnerabilidades isoladas do contexto de implantação. O arquivo de steering exige a análise de Infraestrutura como Código (IaC) e a aplicação de multiplicadores específicos por controle antes de atribuir prioridade.

O objetivo é reprodutibilidade: a mesma base de código deve produzir os mesmos achados avaliados independentemente de quem executa a análise ou quando.

As cinco seções que importam

1. Verificação estrutural antes de confiar no modelo

Esta é descrita como a instrução mais importante do arquivo. A regra é simples: nunca confie na confiança auto-reportada de um modelo sobre uma vulnerabilidade. Verifique as afirmações contra a estrutura do código: os arquivos referenciados existem? As funções referenciadas existem? O fluxo de dados confirma a afirmação? Existe um caminho de chamada?

Se um achado falha em todas as verificações estruturais, ele é rejeitado independentemente de quão convincente a narrativa soa. Sem essa instrução, o modelo gera cadeias de ataque plausíveis que referenciam funções renomeadas três commits atrás, arquivos em pacotes diferentes, ou fluxos de dados que passam por sanitização que o modelo não percebeu. Nos testes da AWS, aproximadamente 30% dos achados de modelos sem steering referenciavam estruturas de código que não existiam no repositório alvo. Com o arquivo de steering, esse número caiu a zero.

2. Pontuação de confiança baseada em evidências

A fórmula abaixo substitui a confiança intuitiva do modelo por uma pontuação calculada a partir de sinais observáveis. Cada fator é binário: confirmado ou não confirmado.

confidence = 0.30 * taint_confirms_flow
           + 0.25 * no_sanitization_found
           + 0.20 * entry_point_is_public
           + 0.15 * call_graph_confirms_path
           + 0.10 * sink_type_matches_category

A confirmação de taint recebeu o maior peso (0,30) porque um caminho de fluxo de dados confirmado — evidência de que dados controlados pelo usuário chegam a uma operação sensível à segurança — é o preditor mais forte de que um achado é real. Na validação da AWS contra aplicações vulneráveis conhecidas, achados com taint confirmado e sem sanitização eram exploráveis em 89% das vezes. Achados onde o modelo reportou confiança ALTA sem confirmação estrutural eram exploráveis em apenas 34% das vezes.

A fórmula é um ponto de partida, não um padrão fixo. Os pesos devem refletir os dados de validação de cada equipe.

3. Avaliação com consciência de infraestrutura

Esta seção endereça uma categoria comum de superpriorização: reportar uma vulnerabilidade com severidade total quando controles compensatórios já estão em vigor.

score_after_controls = max(0.15, score * block_1 * block_2 * ... * block_n)

Os controles são mapeados para classes específicas de vulnerabilidade. Um AWS WAF com regras de injeção SQL em modo de bloqueio é um controle FORTE (multiplicador de 0,25x) contra injeção SQL. É irrelevante para ataques de desserialização. O arquivo de steering especifica esse mapeamento explicitamente em vez de deixar o modelo adivinhar.

O empilhamento multiplicativo de controles com um piso de 0,15 codifica o pensamento de defesa em profundidade. Múltiplos controles reduzem o risco mais do que qualquer controle único, mas nenhuma combinação reduz o risco a zero.

Uma sutileza importante aprendida durante a validação: controles de acesso (autenticação e autorização) e controles de bloqueio de ataque (regras de WAF e validação de entrada) servem funções diferentes. Autenticação limita quem pode tentar um exploit — não limita o que acontece quando um usuário autenticado tenta um. Uma injeção de comando atrás de autenticação IAM ainda é uma injeção de comando; o pool de atacantes é menor, mas o impacto quando explorado é inalterado.

4. Integração de inteligência de ameaças

O arquivo de steering incorpora sinais do catálogo Catálogo de Vulnerabilidades Exploradas Conhecidas (KEV) da CISA e do Sistema de Pontuação de Previsão de Exploits (EPSS) para aumentar a prioridade quando a inteligência de ameaças indica risco ativo.

Os sinais reconhecidos e seus boosts são:

Explorada ativamente (CISA KEV): +0,30
Associada a ransomware (CISA KEV): +0,15
EPSS >= 0,5: +0,20
Prova de conceito pública existente: +0,10

Há um limite de +0,50 de boost total para evitar que a inteligência de ameaças domine a pontuação. A lógica é separar urgência de severidade: uma vulnerabilidade de dependência de severidade média sob exploração ativa por grupos de ransomware exige resposta mais rápida do que um achado crítico em nível de código que requer precondições complexas e não tem ferramental conhecido.

5. Classificação de prioridade

A pontuação produz um número, e a classificação de prioridade transforma esse número em uma decisão — que é o que um desenvolvedor precisa ao receber um achado. O arquivo de steering define quatro níveis de ação:

P0 — Pontuação >= 0,8, sem mitigação efetiva de bloqueio de ataque: corrigir imediatamente
P1 — Pontuação >= 0,6 OU inteligência de ameaça ativa: corrigir neste sprint
P2 — Pontuação >= 0,4, evidência parcial: investigar quando houver capacidade
P3 — Pontuação < 0,4 ou efetivamente mitigado: aceitar risco ou backlog

A instrução mais controversa do arquivo: não registre achados P3 como issues de segurança. O raciocínio é sólido — registrar achados de baixa confiança ou totalmente mitigados como tickets treina equipes a ignorar as ferramentas de segurança. Um pipeline que produz dez achados confirmados recebe mais atenção de engenharia do que um que produz duzentos “talvez”.

Resultados da validação

A AWS testou o arquivo de steering contra uma aplicação vulnerável construída especificamente para o teste, contendo dez vulnerabilidades conhecidas: oito exploráveis e duas mitigadas por controles de infraestrutura. A aplicação incluía um AWS WAF com regras de injeção SQL em modo de bloqueio, funções AWS Lambda isoladas em Amazon VPC, e autenticação IAM em cada endpoint.

Sem o arquivo de steering: o modelo encontrou todas as dez vulnerabilidades e identificou corretamente os dois achados mitigados como menor prioridade. No entanto, atribuiu severidade por intuição e não produziu verificação estrutural de suas afirmações.

Com o arquivo de steering: o modelo encontrou nove das dez vulnerabilidades (não sinalizando uma credencial hardcoded intencionalmente embutida em código de teste unitário que estava definida mas nunca chamada), rebaixou corretamente os dois achados mitigados para P3 com justificativa documentada, mostrou o cálculo de confiança para cada achado, e verificou cada fluxo de dados afirmado contra o código real.

A calibração de pontuação exigiu uma iteração: a versão inicial aplicava autenticação como multiplicador genérico que suprimia todos os achados atrás de IAM para P2, independentemente do impacto. A correção separou controles de limitação de acesso dos controles de bloqueio de ataque. A versão atual classifica corretamente uma injeção de comando atrás de autenticação IAM como P0.

Como usar o arquivo de steering

Opção 1: Como steering file do Kiro

Coloque o arquivo no repositório em .kiro/steering/vuln-triage.md. Qualquer sessão usando o agente padrão do Kiro carrega as instruções automaticamente. Se sua equipe usa um agente customizado, você precisa adicionar o arquivo explicitamente aos recursos do agente:

{ "resources": ["file://.kiro/steering/**/*.md"] }

A estrutura do repositório fica assim:

your-repo/
├── .kiro/
│   └── steering/
│       └── vuln-triage.md  ← steering file
├── src/
├── cdk/
└── ...

Também é possível colocá-lo em ~/.kiro/steering/ para aplicar a metodologia em todos os workspaces da máquina.

Opção 2: Como skill do Kiro

Se você quer a metodologia disponível sob demanda em vez de consumir espaço de contexto em cada turno, use-a como skill. O Kiro carrega apenas o nome e a descrição da skill na inicialização e puxa as instruções completas quando a skill é ativada.

Uma skill é uma pasta contendo um arquivo SKILL.md. O nome da pasta deve corresponder ao nome no cabeçalho YAML:

name: vuln-triage
description: Structured vulnerability triage methodology with evidence-based scoring and infrastructure-aware prioritization. Use when analyzing code for security vulnerabilities.

A estrutura fica assim:

your-repo/
├── .kiro/
│   └── skills/
│       └── vuln-triage/
│           └── SKILL.md  ← skill file
├── src/
└── ...

Uma skill chamada vuln-triage se torna o comando /vuln-triage, permitindo que um engenheiro execute uma avaliação sob demanda: /vuln-triage focus on the authentication changes. Para disponibilizar em todos os projetos da máquina, coloque em ~/.kiro/skills/.

Opção 3: Adaptado para outras ferramentas

A metodologia não é específica do Kiro. O repositório também disponibiliza o mesmo conteúdo como arquivo CLAUDE.md para o Claude Code, e os princípios se aplicam a qualquer assistente que carregue instruções persistentes do repositório.

O que o arquivo de steering não substitui

Um arquivo de steering é metodologia, não maquinário. Ele diz ao modelo como pensar sobre achados, mas não fornece:

Rastreamento programático de taint: o modelo aproxima o fluxo de dados lendo o código. Um rastreador de taint dedicado confirma o fluxo contra a árvore de sintaxe abstrata (AST) de forma determinística.
Verificação de infraestrutura em tempo real: o arquivo de steering instrui o modelo a analisar arquivos de IaC, mas ele não pode fazer chamadas de API para verificar se uma regra do AWS WAF está realmente anexada ao Amazon API Gateway no ambiente implantado.
Feeds de inteligência de ameaças ao vivo: o modelo inclui entradas históricas do KEV da CISA em seus dados de treinamento, mas não pode consultar feeds em tempo real. Para status atual de exploração, é necessária uma integração via API.
Verificação baseada em execução: confirmar explorabilidade executando uma prova de conceito contra um ambiente real requer ferramental adicional.

Cada uma dessas capacidades adiciona confiança ao pipeline. O arquivo de steering sem elas ainda produz resultados mensuravelmente melhores do que um modelo sem direção — achados estruturados, evidências citadas e priorização com consciência de infraestrutura. Mas representa a primeira camada de um harness maduro, não o sistema completo.

Disponibilidade

O arquivo de steering está disponível no repositório GitHub da AWS. A recomendação é usá-lo, adaptá-lo ao ambiente específico e compartilhar os resultados com a comunidade.

Fonte

Configuring your AI vulnerability harness, Part 2: The steering file (https://aws.amazon.com/blogs/security/configuring-your-ai-vulnerability-harness-part-2-the-steering-file/)