Execute o Codex Security no GitLab CI/CD

Execute o Codex Security no GitLab CI/CD para analisar alterações registradas em commits e branches protegidas, publicar os problemas encontrados no GitLab Security e, se quiser, propor correções verificadas em merge requests em rascunho.

O fluxo de trabalho mantém as credenciais de análise separadas das permissões de gravação no repositório. As alterações geradas sempre exigem revisão humana antes do merge.

Comece apenas com os relatórios de análise. Só habilite a correção automática depois de verificar o runner, os problemas encontrados e os limites de acesso de cada credencial do projeto.

Antes de começar

Você precisa de:

• Um projeto GitLab com um runner confiável que ofereça suporte ao namespace de usuário do sandbox do Codex.
• A função Maintainer ou Owner no projeto GitLab para configurar as variáveis de CI/CD do projeto e os recursos protegidos.
• Uma chave de API da OpenAI com acesso ao Codex Security. Organizações que usam chaves de API da plataforma podem solicitar o Trusted Access for Cyber. Quem usa a autenticação do ChatGPT pode seguir o fluxo de Trusted Access para pessoas físicas. Algumas contas ou repositórios exigem esse acesso para análises do repositório inteiro.
• GitLab Ultimate 19.2 ou posterior para importar relatórios SARIF 2.1.0.
• O histórico completo do Git para que os jobs de merge request possam calcular a base do merge.

A imagem do pipeline instala Node.js 26, Python 3, Git, rg e a versão fixada da CLI do Codex Security. A correção automática também exige um teste de regressão existente e um runner capaz de executar comandos definidos no repositório sem credenciais protegidas.

Comece com um pipeline apenas de análise

Crie uma variável de CI/CD do GitLab mascarada, oculta e protegida chamada CODEX_SECURITY_API_KEY. Use uma chave de API da plataforma OpenAI com acesso ao Codex Security e restrinja o escopo da variável ao ambiente codex-security/openai. Consulte a documentação sobre variáveis de CI/CD com escopo de ambiente.

Adicione este pipeline primeiro a um projeto de teste. Ele analisa as alterações registradas nos commits de merge requests protegidas que atendem aos critérios, publica o relatório SARIF quando o job de relatório termina com sucesso e reaplica o resultado da análise em uma etapa de controle separada:

stages:
  - security_scan
  - security_gate

.codex-security-merge-request:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID && $CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED == "true" && $CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED == "true"'

codex-security:
  extends: .codex-security-merge-request
  stage: security_scan
  image: node:26-bookworm-slim
  environment:
    name: codex-security/openai
    action: access
  variables:
    GIT_DEPTH: "0"
  before_script:
    - apt-get update -qq
    - apt-get install -y -qq --no-install-recommends ca-certificates git python3 ripgrep
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.8.1
  script:
    - |
      set -eu
      test -n "${CODEX_SECURITY_API_KEY:-}"

      CODEX_SECURITY_BIN="/tmp/codex-security-cli/node_modules/.bin/codex-security"
      RESULTS_DIR="/tmp/codex-security-results-$CI_JOB_ID"
      ARTIFACT_DIR="codex-security-artifacts"
      BASE_REVISION="$(git merge-base \
        "$CI_MERGE_REQUEST_DIFF_BASE_SHA" "$CI_COMMIT_SHA")"
      install -d -m 700 "$RESULTS_DIR" "$ARTIFACT_DIR/results"

      codex_security_api_key="$CODEX_SECURITY_API_KEY"
      unset CODEX_SECURITY_API_KEY
      set +e
      OPENAI_API_KEY="$codex_security_api_key" \
        "$CODEX_SECURITY_BIN" scan . \
          --diff "$BASE_REVISION" \
          --head "$CI_COMMIT_SHA" \
          --auth api-key \
          --output-dir "$RESULTS_DIR" \
          --fail-on-severity high \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1) ;;
        *) exit "$scan_exit" ;;
      esac

      "$CODEX_SECURITY_BIN" export "$RESULTS_DIR" \
        --export-format sarif \
        --source-root "$CI_PROJECT_DIR" \
        --output "$ARTIFACT_DIR/results.sarif"
      test -s "$ARTIFACT_DIR/results.sarif"
      cp -R "$RESULTS_DIR"/. "$ARTIFACT_DIR/results/"
      printf '%s\n' "$scan_exit" > "$ARTIFACT_DIR/scan-exit-code.txt"
      exit 0
  artifacts:
    when: always
    access: maintainer
    expire_in: 7 days
    paths:
      - codex-security-artifacts/
    reports:
      sarif: codex-security-artifacts/results.sarif

codex-security-gate:
  extends: .codex-security-merge-request
  stage: security_gate
  image: alpine:3.20
  needs:
    - job: codex-security
      artifacts: true
  script:
    - exit "$(cat codex-security-artifacts/scan-exit-code.txt)"

Revise cada alteração em .gitlab-ci.yml antes de executar um job com acesso a segredos. Este exemplo não inclui análises completas nem correção automática.

Adote o pipeline de produção

1. Baixe o pipeline completo do GitLab e salve-o como .gitlab-ci.yml na raiz do repositório. Se o repositório já tiver um pipeline, incorpore as etapas, os modelos ocultos e os jobs do exemplo ao arquivo existente.
2. Preserve as etapas existentes de build, teste e implantação. Se o projeto usar workflow: rules, confirme que as regras permitem os eventos de pipeline para os quais você quer executar análises.

O exemplo adiciona as etapas security_scan, security_remediation, security_publish e security_gate. Para gerar apenas relatórios de análise, basta configurar CODEX_SECURITY_API_KEY.

Por padrão, o job de análise só é executado em merge requests entre branches protegidas do mesmo projeto. Defina CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true para executar análises em pushes e pipelines manuais na branch padrão protegida. Defina CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true e configure limites explícitos de tempo e custo para habilitar análises aprofundadas agendadas nessa branch.

Um pipeline de merge request só pode acessar variáveis e runners protegidos quando todas estas condições são atendidas:

• As branches de origem e de destino estão protegidas e pertencem ao mesmo projeto.
• O projeto permite que pipelines de merge request acessem variáveis e runners protegidos.
• O usuário que inicia o pipeline pode fazer push ou merge na branch de destino.

Pipelines de forks e merge requests desprotegidas não recebem a credencial de análise. Revise cada alteração em .gitlab-ci.yml antes de executar um job com acesso a segredos. Mascarar e ocultar uma variável não torna seguro executar código de CI que não seja confiável.

Execute uma análise e revise os problemas encontrados

Crie uma merge request protegida que atenda aos critérios ou execute o pipeline na branch padrão protegida. Comece com um diff pequeno antes de executar uma análise paga do repositório inteiro.

Abra o job codex-security e confirme que os artefatos incluem:

• results/scan-manifest.json
• results/findings.json
• results/report.md
• results.sarif
• scan-exit-code.txt

Em seguida, abra a aba Security do pipeline, revise os avisos de importação e confira os identificadores dos problemas, os níveis de gravidade e os locais correspondentes no código-fonte. As análises da branch padrão também criam registros de vulnerabilidade no projeto. Os problemas encontrados em merge requests aparecem na aba Security do pipeline ou no widget de segurança da merge request, mas não geram registros de vulnerabilidade para o projeto como um todo.

Restrinja o acesso aos artefatos, pois os resultados da análise podem conter trechos vulneráveis do código-fonte, evidências e detalhes de correção.

Escolha um perfil de análise

O pipeline seleciona o perfil de acordo com o evento que o inicia:

As análises de merge requests concentram o feedback nas alterações registradas nos commits. As análises da branch padrão examinam o repositório após a integração das alterações. As análises aprofundadas agendadas oferecem cobertura mais ampla em intervalos regulares. Uma análise de diff concluída vale apenas para a alteração examinada e não comprova que o restante do repositório esteja livre de problemas.

O fluxo de trabalho instala a CLI fora do repositório e a executa pelo caminho absoluto. A verificação preliminar simula a execução usando a chave de API restrita ao processo. Ela não inicia uma análise paga nem verifica a autenticação na API, o acesso ao Codex Security, a cota ou a disponibilidade do modelo.

O fluxo de trabalho grava o estado e os resultados da análise fora da árvore de trabalho e restringe OPENAI_API_KEY ao processo de análise. A CLI recebe um conjunto reduzido de variáveis de ambiente definidas explicitamente, em vez de herdar todas as variáveis do GitLab. Nas análises de diff, o fluxo calcula a base do merge e vincula a análise às revisões de base e de ponta usadas na revisão do código.

O exemplo fixa a versão de @openai/codex-security em 0.8.1. Antes de alterar a versão, teste novamente a autenticação, os artefatos, a importação de SARIF e a etapa de controle da política.

Separe a publicação de relatórios da aplicação da política

O GitLab importa o SARIF quando o job de relatório termina com sucesso. O pipeline publica o relatório primeiro e reaplica o código de saída da análise em um job separado, codex-security-gate.

O job de relatório só exporta os problemas encontrados quando a análise retorna o código de saída 0 ou 1. Qualquer outro código impede a exportação do SARIF e bloqueia o pipeline. Uma falha na exportação também bloqueia o pipeline.

O job de relatório propaga erros de execução e interrupções. Quando ele termina com sucesso, a etapa de controle final reaplica o resultado da política retornado pela análise:

O exemplo usa --fail-on-severity high, portanto problemas de gravidade alta ou crítica fazem a etapa de controle falhar. Sem um limite de gravidade, as análises concluídas retornam 0 por padrão. Em results/scan-manifest.json, consulte scan.scope para ver o escopo configurado e scan.review.excludedPaths para ver os caminhos excluídos das comparações entre problemas encontrados. Consulte results/report.md para saber o que fazer em seguida.

A correção e a publicação ocorrem antes da etapa final de controle da política. Um problema que atenda aos critérios pode gerar uma merge request em rascunho com uma correção verificada, mesmo que a etapa de controle bloqueie o pipeline depois.

Habilite a correção automática com verificação

A correção automática é opcional e só é executada em pipelines da branch padrão protegida. Nem o processo de correção do Codex nem os comandos de verificação definidos no repositório recebem o token de acesso ao projeto GitLab ou as credenciais injetadas pelo runner.

O fluxo de trabalho:

1. Exige o manifesto de uma análise concluída da revisão atual e um problema de gravidade high ou critical.
2. Confirma que o teste de regressão configurado falha antes de aplicar a correção.
3. Gera um patch e rejeita alterações em arquivos de CI, arquivos de credenciais, binários ou outros arquivos protegidos.
4. Executa o teste de regressão sem credenciais da OpenAI, do GitLab, do registro ou de implantação e sem o token do job.
5. Usa verify-fix para obter um dos resultados fixed, still_vulnerable ou inconclusive. O job só publica o patch quando verify-fix retorna fixed e o processo de verificação mantém o patch intacto.

Configure estas variáveis protegidas para habilitar a correção automática:

• Defina CODEX_SECURITY_ENABLE_REMEDIATION como true.
• Defina CODEX_SECURITY_VERIFICATION_COMMAND como o comando de um teste de regressão existente que retorne 1 antes da correção e 0 depois.
• Se necessário, defina CODEX_SECURITY_SETUP_COMMAND como um comando não interativo para configurar as dependências.

Escolha um teste de regressão que verifique a propriedade de segurança que deve permanecer válida independentemente da implementação. Revise com o mesmo rigor as alterações geradas nos testes e no código-fonte.

Publique uma merge request em rascunho

Crie um token de acesso ao projeto GitLab com a função Developer e os escopos api e write_repository. Armazene o token na variável protegida, mascarada e oculta GITLAB_REMEDIATION_TOKEN e restrinja seu escopo ao ambiente codex-security/publish.

Defina CODEX_SECURITY_CREATE_MR=true para habilitar a publicação. Defina também a variável não secreta CODEX_SECURITY_MR_TEST_COMMAND como o comando do teste de regressão de segurança específico do projeto. Todas as branches de correção geradas precisam passar nesse teste. Mantenha a variável desprotegida para que a merge request desprotegida gerada possa ler o comando. O fluxo de publicação:

• Recebe o token com permissão de gravação no repositório, mas nenhuma credencial da OpenAI.
• Cria uma branch codex-security/fix-<finding-hash>.
• Abre uma merge request em rascunho ou reutiliza um rascunho já aberto para evitar duplicatas.
• Executa o teste de regressão da branch de correção desprotegida como um usuário sem privilégios, em uma cópia que contém apenas os arquivos rastreados e sem acesso a credenciais protegidas.
• Nunca faz merge automático da alteração gerada.

Não use CI_JOB_TOKEN no lugar do token de acesso ao projeto. O token do job não permite criar a merge request, operação necessária para a publicação. Antes do merge, revise o patch proposto, as evidências da verificação e o problema encontrado.

Configure as variáveis opcionais

Configure apenas as variáveis necessárias para os recursos que você habilitar:

O GitLab fornece as variáveis CI_*. O pipeline gerencia CODEX_SECURITY_BIN, CODEX_SECURITY_EFFORT, CODEX_SECURITY_MODE, CODEX_SECURITY_STATE_DIR e CODEX_SECURITY_TARGET. Não as configure como variáveis do projeto. Nas análises de diff, a CLI determina a identidade canônica do alvo a partir das revisões de base e de ponta normalizadas.

Ajuste a aplicação da política e o custo

Use análises de diff para obter feedback nas merge requests, análises padrão do repositório para a branch padrão e análises aprofundadas agendadas para ampliar a cobertura. Os dois perfis de análise do repositório inteiro ficam desabilitados por padrão. Uma análise aprofundada agendada também exige CODEX_SECURITY_DEEP_MAX_TIME_MINUTES e CODEX_SECURITY_DEEP_MAX_COST. Mantenha o limite de tempo da CLI abaixo do prazo de oito horas do job. Ao adotar o novo YAML, converta para minutos os valores existentes expressos em horas. Meça o tempo e o custo de execuções representativas antes de definir os limites. Use --max-cost como referência para limitar o custo estimado. Ele não impõe um teto de cobrança.

Neste exemplo, problemas de gravidade alta ou crítica bloqueiam o pipeline. Para análises que apenas geram relatórios, remova --fail-on-severity high. Escolha um limite de gravidade depois de avaliar os problemas encontrados em execuções representativas, a cobertura, o custo e o tempo de execução. Consulte a visão geral de CI/CD para conhecer as políticas de gravidade e a referência da CLI para obter detalhes sobre os códigos de saída.

Quando um job falhar:

• Se faltarem artefatos da análise, investigue a configuração e o runner.
• Se houver exclusões inesperadas, confira o escopo e os detalhes da revisão em results/scan-manifest.json.
• Se os problemas encontrados não aparecerem no GitLab, verifique se o job de relatório SARIF terminou com sucesso e se o GitLab aceitou o relatório.
• Se a etapa de correção for ignorada, confira a branch protegida, o manifesto da análise, a gravidade do problema, o comando de verificação e as variáveis de ativação.
• Se houver erros de publicação, confira a função e os escopos do token do projeto, além da restrição de ambiente.

Para consultar todos os comandos, opções e artefatos, veja a referência da CLI do Codex Security.