Checkov Scan para Terraform com Azure Pipelines

Esse post mostra como usar o Checkov para escanear seu IaC Terraform dentro de uma esteira do Azure Pipelines. O objetivo é ter um step dedicado ao scan de segurança antes de qualquer plan ou apply chegar no ambiente.

O que é o Checkov?

Checkov é uma ferramenta de análise estática para infraestrutura como código. Ela verifica configurações de recursos cloud e aponta misconfigurations antes que elas sejam provisionadas. Suporta Terraform, CloudFormation, Kubernetes, Helm, ARM Templates, Serverless e AWS CDK.

---

Etapa 1 — Criando o template do Checkov

Como vamos usar Azure Pipelines, faz sentido isolar as tasks do Checkov em um template reutilizável. O arquivo fica em:

.azuredevops/templates/terraform-build-checkov.yml

O template usa duas variáveis predefinidas do Azure DevOps para instalar o Checkov no runner de execução:

Predefined variables - Azure Pipelines | Microsoft Learn

A comprehensive list of all available predefined variables

learn.microsoft.com

• $(Agent.ToolsDirectory) — diretório de ferramentas do agente
• $(Agent.OS) — sistema operacional do agente

parameters:
  - name: CheckovVersion
    type: string
    default: ''
  - name: WorkingDir
    type: string
    default: '.'

steps:

  # Cache do Checkov para evitar reinstalação a cada run
  - task: Cache@2
    displayName: Restore checkov $(CheckovVersion) from cache
    name: checkov_restore_cache
    inputs:
      key: '"checkov $(CheckovVersion)" | $(Agent.OS)'
      path: $(Agent.ToolsDirectory)/checkov
      cacheHitVar: CACHE_RESTORED

  # Instala o Checkov apenas se o cache não existir
  - task: CmdLine@2
    displayName: Install checkov $(CheckovVersion)
    condition: and(succeeded(), ne(variables.CACHE_RESTORED, 'true'))
    inputs:
      targetType: 'inline'
      script: |
        CHECKOV_DIR=${AGENT_TOOLSDIRECTORY}/checkov
        mkdir -p $CHECKOV_DIR
        python3 -m venv $CHECKOV_DIR
        source $CHECKOV_DIR/bin/activate
        pip3 install checkov==${{ parameters.CheckovVersion }}
        echo "##vso[task.prependpath]$CHECKOV_DIR/bin"

  # Adiciona o Checkov ao PATH do agente
  - task: CmdLine@2
    displayName: Add checkov to PATH
    inputs:
      targetType: 'inline'
      script: |
        CHECKOV_DIR=${AGENT_TOOLSDIRECTORY}/checkov
        echo "##vso[task.prependpath]$CHECKOV_DIR/bin"

  # Executa o scan no diretório Terraform informado
  - task: CmdLine@2
    displayName: Run checkov
    inputs:
      targetType: 'inline'
      script: checkov --directory "${{ parameters.WorkingDir }}" --framework terraform

Por que usar cache? O Checkov tem algumas dependências Python que levam tempo para instalar. Com a task Cache@2, a instalação só acontece uma vez por versão — nas runs seguintes o agente restaura direto do cache.

---

Etapa 2 — Configurando a Pipeline principal

Na raiz do repositório, o azure-pipelines.yaml referencia o template criado acima. A variável $(System.DefaultWorkingDirectory) aponta para o diretório dos arquivos Terraform.

trigger:
  branches:
    include:
      - main
  paths:
    exclude:
      - '**/*.md'

pool:
  vmImage: ubuntu-latest

variables:
  CheckovVersion: '2.3.110'

steps:

  - task: TerraformTaskV4@4
    displayName: Terraform Init
    inputs:
      provider: 'aws'
      command: 'init'
      workingDirectory: '$(System.DefaultWorkingDirectory)/tf'

  - template: .azuredevops/templates/terraform-build-checkov.yaml

O exemplo acima tem apenas o Init e o template do Checkov para manter a demonstração simples. Na prática, você vai querer adicionar Validate, TfLint, Plan e Apply conforme a maturidade da sua esteira.

---

Etapa 3 — Executando e interpretando o resultado

Ao rodar a pipeline, o log vai mostrar:

• Quantos recursos foram verificados
• Quantos checks passaram, falharam ou foram pulados (skipped)

Se um check falhar, a pipeline quebra. Esse é o comportamento esperado — a ideia é bloquear o deploy até que a configuração seja corrigida ou explicitamente ignorada.

---

Como fazer skip de um check específico

Quando um item é avaliado como falso positivo ou está dentro de uma exceção aceitável para o contexto, você pode declarar o skip diretamente no bloco do resource Terraform:

resource "aws_eks_cluster" "cluster-eks" {

  #checkov:skip=CKV_AWS_39: "Ensure Amazon EKS public endpoint disabled"
  #checkov:skip=CKV_AWS_37: "Ensure Amazon EKS control plane logging enabled for all log types"
  #checkov:skip=CKV_AWS_38: "Ensure Amazon EKS public endpoint not accessible to 0.0.0.0/0"
  #checkov:skip=CKV_AWS_58: "Ensure EKS Cluster has Secrets Encryption Enabled"

  # ... restante da configuração

}

O comentário segue o padrão #checkov:skip=<CHECK_ID>: "<justificativa>". A justificativa é opcional mas recomendada para rastreabilidade — especialmente em auditorias.

---

Conclusão

Com esse template, o scan de segurança vira parte do ciclo normal de desenvolvimento. Qualquer misconfiguration no Terraform é bloqueada antes de chegar no plan, o que reduz bastante o risco de provisionar recursos fora de conformidade.

O Checkov suporta os seguintes frameworks:

• Terraform e Terraform Plan
• CloudFormation
• Kubernetes
• ARM Templates
• Serverless
• Helm
• AWS CDK

---