Executar o Codex Security no GitLab CI/CD

Execute o Codex Security no GitLab CI/CD para analisar alterações confirmadas e ramos protegidos, publicar resultados no GitLab Security e, opcionalmente, propor correções verificadas em pedidos de integração de rascunho.

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

Comece por criar relatórios apenas de análise. Ative a remediação apenas depois de verificar o executor, os resultados e os limites das credenciais do seu projeto.

Antes de começar

Necessita de:

• Um projeto GitLab com um executor fidedigno compatível com o espaço de nomes de utilizador do sandbox do Codex.
• A função Maintainer ou Owner no projeto GitLab, para poder configurar variáveis de CI/CD do projeto e recursos protegidos.
• Uma API key da OpenAI com acesso ao Codex Security. As organizações que utilizem Platform API keys podem solicitar o Trusted Access para Cyber. As pessoas que utilizem autenticação do ChatGPT podem utilizar o fluxo de Trusted Access pessoal. Algumas contas ou alguns repositórios necessitam deste acesso para análises de todo o repositório.
• GitLab Ultimate 19.2 ou posterior para a ingestão de SARIF 2.1.0.
• O histórico completo do Git, para que as tarefas dos pedidos de integração possam calcular a base de integração.

A imagem do pipeline instala Node.js 26, Python 3, Git, rg e a versão fixa da CLI do Codex Security. A remediação automatizada também requer um teste de regressão existente e um executor capaz de executar comandos controlados pelo repositório sem credenciais protegidas.

Começar com um pipeline apenas de análise

Crie uma variável de CI/CD do GitLab protegida, mascarada e oculta denominada CODEX_SECURITY_API_KEY. Utilize uma OpenAI Platform API key com acesso ao Codex Security e defina o respetivo âmbito de ambiente como codex-security/openai. Consulte variáveis de CI/CD com âmbito de ambiente.

Adicione primeiro este pipeline mínimo a um projeto de teste. Este analisa alterações confirmadas em pedidos de integração protegidos elegíveis, publica SARIF a partir de uma tarefa de relatório bem-sucedida e repõe o resultado do analisador numa barreira 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:
    - npm install --prefix /tmp/codex-security-cli --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.20
  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" \
          --json
      scan_exit="$?"
      set -e
      unset codex_security_api_key

      case "$scan_exit" in
        0|1|2) ;;
        *) 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)"

Reveja todas as alterações a .gitlab-ci.yml antes de executar uma tarefa com segredos. O exemplo mínimo omite intencionalmente as análises completas e a remediação.

Adotar o pipeline de produção

1. Transfira o pipeline completo do GitLab e guarde-o como .gitlab-ci.yml na raiz do repositório. Se o seu repositório já tiver um pipeline, combine as fases, os modelos ocultos e as tarefas do exemplo com o ficheiro existente.
2. Preserve as fases existentes de compilação, teste e implementação. Se o projeto utilizar workflow: rules, confirme que este permite os eventos de pipeline que pretende analisar.

O exemplo adiciona as fases security_scan, security_remediation, security_publish e security_gate. Os relatórios apenas de análise requerem apenas CODEX_SECURITY_API_KEY.

Por predefinição, a tarefa de análise só é executada para pedidos de integração do mesmo projeto entre ramos protegidos. Defina CODEX_SECURITY_FULL_SCAN_DEFAULT_BRANCH=true para analisar pushes no ramo predefinido protegido e pipelines manuais. Defina CODEX_SECURITY_SCHEDULED_DEEP_SCAN=true e configure limites explícitos de tempo e custo para ativar análises aprofundadas agendadas no ramo predefinido protegido.

Um pipeline de pedido de integração só pode aceder a variáveis e executores protegidos quando:

• Protege os ramos de origem e de destino no mesmo projeto.
• O projeto permite que os pipelines de pedidos de integração acedam a variáveis e executores protegidos.
• O utilizador que inicia o pipeline pode efetuar push ou integrar no ramo de destino.

Os pipelines de forks e os pedidos de integração não protegidos não recebem a credencial de análise. Reveja todas as alterações a .gitlab-ci.yml antes de executar uma tarefa com segredos. Mascarar e ocultar uma variável não torna seguro o código de CI não fidedigno.

Executar uma análise e rever os resultados

Crie um pedido de integração protegido elegível ou execute o pipeline no ramo predefinido protegido. Comece com uma pequena diferença antes de executar uma análise paga de todo o repositório.

Abra a tarefa codex-security e confirme que os respetivos artefactos incluem:

• scan-manifest.json
• findings.json
• coverage.json
• results.sarif
• scan-exit-code.txt

Em seguida, abra o separador Security do pipeline, reveja os avisos de ingestão e confirme os identificadores dos resultados, os níveis de gravidade e as localizações no código-fonte. As análises do ramo predefinido também criam registos de vulnerabilidades do projeto. Os resultados dos pedidos de integração aparecem no separador Security do pipeline ou no widget de segurança do pedido de integração, mas não criam registos de vulnerabilidades para todo o projeto.

Restrinja o acesso aos artefactos, pois os resultados da análise podem conter excertos de código-fonte vulnerável, provas e detalhes de remediação.

Escolher um perfil de análise

O pipeline seleciona um perfil com base no acionador:

As análises de pedidos de integração centram o feedback na alteração confirmada. As análises do ramo predefinido examinam o repositório integrado. As análises aprofundadas agendadas proporcionam uma cobertura periódica mais ampla. Uma análise de diferenças concluída aplica-se apenas a essa alteração e não demonstra que todo o repositório está isento de problemas.

O fluxo de trabalho instala a CLI fora do repositório e executa-a através do caminho absoluto. A pré-verificação em modo de simulação utiliza a API key com âmbito de processo, mas não inicia uma análise paga nem verifica a autenticação da API, o acesso ao Codex Security, a quota ou a disponibilidade do modelo.

O fluxo de trabalho grava o estado e os resultados da análise fora da árvore de trabalho e limita OPENAI_API_KEY ao processo de análise. A CLI recebe um ambiente pequeno e explícito, em vez de herdar todas as variáveis do GitLab. Para análises de diferenças, o fluxo de trabalho calcula a base de integração e associa a análise às revisões da base e do cabeçalho revistas.

O exemplo fixa @openai/codex-security em 0.1.20. Volte a testar a autenticação, os artefactos, a ingestão de SARIF e a imposição de políticas antes de alterar a versão fixa.

Separar os relatórios da imposição de políticas

O GitLab ingere SARIF a partir de uma tarefa de relatório bem-sucedida. O pipeline publica primeiro o relatório e repõe o estado de saída do analisador numa tarefa codex-security-gate separada.

A tarefa de relatório aceita resultados dos códigos de saída 0 e 1. Aceita o código de saída 2 apenas quando o manifesto de análise demonstra que a análise foi concluída, a cobertura é explicitamente partial e existe um relatório SARIF não vazio. Outras falhas de execução, configuração ou exportação continuam a ser bloqueantes.

A barreira final preserva estes códigos de saída do analisador:

O exemplo permite temporariamente a saída 2 enquanto calibra a cobertura parcial. Remova essa permissão quando a cobertura incompleta tiver de bloquear o pipeline.

A remediação e a publicação são executadas antes da barreira final da política. Um resultado elegível pode produzir um pedido de integração de rascunho verificado, mesmo que a barreira posteriormente cause a falha do pipeline.

Ativar a remediação verificada

A remediação automatizada é opcional e só é executada em pipelines do ramo predefinido protegido. O processo de remediação do Codex e os comandos de verificação controlados pelo repositório não recebem o token de acesso ao projeto GitLab nem credenciais injetadas pelo executor.

O contrato de segurança tem três partes: os comandos controlados pelo repositório nunca recebem credenciais da OpenAI ou do GitLab, apenas a tarefa de publicação recebe acesso de escrita no repositório e todas as alterações geradas permanecem em rascunho até serem revistas e integradas por uma pessoa.

O fluxo de trabalho:

1. Exige uma cobertura de análise completa e um resultado de gravidade high ou critical.
2. Confirma que o teste de regressão configurado falha antes da aplicação da correção.
3. Gera uma correção específica e rejeita alterações a ficheiros de CI, credenciais, binários ou outros ficheiros protegidos.
4. Executa o teste de regressão sem credenciais da OpenAI, GitLab, registo, implementação ou token da tarefa.
5. Utiliza verify-fix para devolver fixed, still_vulnerable ou inconclusive. A tarefa só publica uma correção quando verify-fix devolve fixed e o processo de verificação não altera a correção.

Defina estas variáveis protegidas para ativar a remediação:

• Defina CODEX_SECURITY_ENABLE_REMEDIATION como true.
• Defina CODEX_SECURITY_VERIFICATION_COMMAND como um teste de regressão existente que termine com 1 antes da correção e 0 depois dela.
• Opcionalmente, defina CODEX_SECURITY_SETUP_COMMAND como um comando não interativo de preparação de dependências.

Escolha um teste de regressão que verifique a propriedade de segurança subjacente, e não uma implementação específica. Aplique o mesmo rigor às alterações geradas nos testes e no código-fonte.

Publicar um pedido de integração de rascunho

Crie um token de acesso ao projeto GitLab com a função Developer e os âmbitos api e write_repository. Guarde-o como GITLAB_REMEDIATION_TOKEN protegido, mascarado e oculto, limitado apenas ao ambiente codex-security/publish.

Defina CODEX_SECURITY_CREATE_MR=true para ativar a publicação. Defina também o valor não secreto CODEX_SECURITY_MR_TEST_COMMAND como o teste de regressão de segurança específico do projeto que todos os ramos de remediação gerados têm de passar. Mantenha esta variável não protegida, para que o pedido de integração não protegido gerado possa ler o comando. O fluxo de trabalho de publicação:

• Recebe o token de escrita no repositório, mas nenhuma credencial da OpenAI.
• Cria um ramo codex-security/fix-<finding-hash>.
• Abre um pedido de integração de rascunho e reutiliza um rascunho aberto existente, em vez de criar um duplicado.
• Executa o teste de regressão do ramo de remediação não protegido como um utilizador sem privilégios, numa cópia apenas dos ficheiros controlados e sem credenciais protegidas.
• Nunca integra automaticamente a alteração gerada.

Não substitua o token de acesso ao projeto por CI_JOB_TOKEN. Este não consegue realizar a operação necessária de criação do pedido de integração. Reveja a correção proposta, as provas de verificação e o resultado antes de integrar.

Configurar variáveis opcionais

Configure apenas as variáveis necessárias para as funcionalidades que ativar:

O GitLab fornece as variáveis CI_*. O pipeline gere 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 diferenças, a CLI deriva a identidade canónica do destino a partir das revisões normalizadas da base e do cabeçalho.

Ajustar a imposição e os custos

Utilize análises de diferenças específicas para obter feedback sobre pedidos de integração, análises padrão do repositório para o ramo predefinido e análises aprofundadas agendadas para uma cobertura mais ampla. Ambos os perfis de repositório completo estão desativados por predefinição. Uma análise aprofundada agendada também requer CODEX_SECURITY_DEEP_MAX_TIME_HOURS e CODEX_SECURITY_DEEP_MAX_COST; mantenha o limite de tempo da CLI abaixo do tempo limite de oito horas da tarefa. Meça execuções representativas antes de definir um limite. Trate --max-cost como um limite de custo estimado, e não como um limite máximo de faturação rígido.

Comece com análises apenas de relatório. Adicione --fail-on-severity depois de a sua equipa ter revisto resultados representativos, a cobertura, o custo e o tempo de execução. Consulte Executar o Codex Security em CI para obter detalhes sobre políticas de gravidade e códigos de saída.

Quando uma tarefa falhar:

• A ausência de artefactos de análise indica um problema de configuração ou do executor.
• A existência de artefactos com cobertura parcial exige a revisão de coverage.json.
• A ausência de resultados no GitLab exige verificar se a tarefa de relatório SARIF foi bem-sucedida e se o GitLab aceitou o relatório.
• Uma remediação ignorada exige verificar o ramo protegido, a cobertura completa, a gravidade do resultado, o comando de verificação e as variáveis de adesão.
• Os erros de publicação exigem verificar a função, os âmbitos e a restrição de ambiente do token do projeto.

Para todos os comandos, sinalizadores e artefactos, consulte a referência da CLI do Codex Security.