A Norma da Regra “ allow ”

Como prática padrão, seu arquivo de política do Rego deve incluir uma regra “ allow ”. No contexto desse processo, isso não é apenas uma sugestão — é uma exigência rigorosa.

O mecanismo do pipeline consulta especificamente o valor booleano allow para tomar a decisão final de prosseguir ou não com a implantação. Se você estiver definindo uma política Rego personalizada, é necessário definir explicitamente essa regra. Se a regra allow estiver ausente ou se seu resultado for false``, o pipeline é interrompido imediatamente, bloqueia a implantação e exibe as mensagens de recusa definidas por você.

Para garantir a máxima segurança, a OPA opera segundo um rigoroso modelo de “fechamento em caso de falha”. Sua política deve sempre ter como valor padrão “ false ” e só resultar em “ true ” se todas as condições de conformidade exigidas forem atendidas.

package one_pipeline.config
# Default deny
default allow := false
# Allow only if your custom checks pass
allow {
    check_sast_scans_passed
    check_secrets_scans_passed
}

Arquivos de políticas e arquivos de validação de dados

O arquivo de política (.rego) — A lógica

É aqui que você escreve suas regras e condições propriamente ditas. Por exemplo, sua política pode determinar: “Não permita essa implantação a menos que tenha sido realizada uma verificação de vulnerabilidades e os resultados mostrem zero problemas críticos.” Você pode fornecer seu arquivo de política personalizado usando a propriedade de ambiente do pipeline policy-path . Se nenhum arquivo de política for fornecido, o pipeline utiliza o arquivo de política padrão.

O arquivo de validação de dados (.json) — Os fatos

Este arquivo funciona como sua lista de referência estática. Em vez de inserir dados diretamente nas regras do Rego, você usa este arquivo para manter listas de variáveis aprovadas — como os registros de imagens permitidos (us.icr.io ou eu.icr.io) ou repositórios específicos que estão isentos de determinadas verificações. Você pode fornecer seu arquivo de validação de dados usando a propriedade de ambiente do pipeline “ evidence-checks-config-path ”. Se nenhum arquivo de validação de dados for fornecido, o pipeline utiliza o arquivo de validação de dados padrão.

Exemplo de arquivo de validação de dados:

        package one_pipeline.config
        pre_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }
        post_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }

Cada bloco da configuração define exatamente quais evidências são esperadas, de onde elas vêm e com que rigor devem ser aplicadas.

• O ID do tipo de evidência (com.ibm.prod_change_request): a chave de nível superior determina a categoria específica da evidência que está sendo avaliada. Exemplos comuns incluem com.ibm.static-scan, com.ibm.unit-tests ou com.ibm.image_signing.
• asset_type: Define o tipo de artefato ao qual esta regra se aplica. Por exemplo, isso pode se aplicar apenas a um image ou a um repo. Ao usar ["*"] , a regra é aplicada a todos os tipos de ativos.
• source (Ambientes de origem): Define de onde provêm as evidências. Pode ser um branch específico ou um ambiente de pipeline (por exemplo, ci-pipeline, stage, prod).
• target (Ambientes de destino): Define o ambiente de destino no qual essa evidência está sendo validada para implantação (por exemplo, stage, prod). Mais detalhes sobre o ambiente de origem e o de destino podem ser encontrados aqui.
• gating mode: Os últimos campos indicam qual modo de filtragem você deseja aplicar ao tipo de evidência. Mais informações sobre os modos de gating compatíveis podem ser encontradas aqui.

Observação : Todas as verificações pré-implantação devem ser definidas na matriz pre_deployment :{} e todas as verificações pós-implantação devem ser definidas na matriz post_deployment :{} . Além disso, se você estiver usando o caminho padrão da política, é necessário incluir a importação do pacote one_pipeline.config no seu arquivo de registro de validação de dados.

O script conversor de JSON para Rego

Embora o pipeline ofereça suporte nativo a arquivos legados de validação de dados JSON, talvez você queira, no futuro, modernizar suas configurações para o Rego nativo a fim de adotar plenamente o padrão de “política como código”.

Para ajudar nisso, disponibilizamos um script utilitário independente que converte automaticamente seus arquivos de validação de dados JSON existentes para o novo formato Rego.

Local do Script: /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

Como usar o script conversor

Você pode executar este script localmente ou durante a execução de um pipeline. Ao executar o script localmente, é necessário especificar explicitamente os ambientes de destino e de origem.

# Convert a JSON config to Rego using named parameters
/opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh \
  --input ./legacy-evidence-config.json \
  --output ./new-evidence-config.rego \
  --target-env prod \
  --source-env master

Configuração flexível: vários arquivos de validação

Ambientes complexos geralmente exigem conjuntos de regras modulares. Para apoiar isso, o fluxo de trabalho de validação de promoções permite que você avalie suas evidências em relação a várias configurações simultaneamente.

É possível fornecer vários arquivos de validação de dados, passando seus caminhos como uma lista separada por vírgulas ao parâmetro evidence-checks-config-path . Nesse caso, o pipeline avaliará a carga útil de evidências em relação a cada arquivo de configuração e gerará tabelas de avaliação separadas para cada arquivo. E na seção de comentários do PR, você verá as tabelas de avaliação de cada arquivo como comentários separados.

Feedback automatizado sobre relações públicas

Para garantir a máxima visibilidade, o pipeline avalia o conjunto de evidências atual em relação a cada arquivo de configuração que você fornecer. Após a conclusão da avaliação, o pipeline gera automaticamente tabelas detalhadas de resumo e avaliação, anexando-as diretamente ao PR.

Se você configurar vários arquivos de validação de dados, o pipeline publicará os resultados de cada arquivo como um comentário separado no PR. Isso oferece aos revisores uma análise clara e abrangente do status de conformidade em diferentes contextos, sem misturar os resultados.

Dentro de cada comentário de RP, você encontra:

• Três tabelas de avaliação: uma análise detalhada dos resultados da validação. Para obter mais informações sobre como interpretar essas tabelas, consulte “Entendendo a Tabela de Verificação de Evidências ”.
• Links de configuração: Links diretos para o arquivo de validação de dados e o arquivo de política específicos que foram utilizados para realizar exatamente essa avaliação, facilitando a auditoria e a solução de problemas em suas regras.

Durante a fase de validação da promoção, essa verificação de conformidade com a OPA tem como objetivo proporcionar visibilidade e feedback. Se forem detectadas questões de conformidade em relação às suas regras, o pipeline não é interrompido nem falha. Em vez disso, o pipeline conclui sua execução e publica os resultados detalhados no PR. Isso garante que os desenvolvedores recebam um relatório completo de todas as falhas de conformidade e possam corrigi-las sem que a compilação seja interrompida no meio do processo.

O objeto table_results (para feedback sobre PRs)

Para gerar as tabelas detalhadas de “ Markdown ” nos comentários do seu PR, o pipeline procura por uma estrutura de dados específica chamada “ table_results ”.

Se sua política gerar um objeto res dentro de table_results contendo exatamente esses oito campos, o pipeline assumirá o controle. Ele analisa com segurança sua saída e a transforma automaticamente na tabela limpa e detalhada Markdown que você vê no PR:

table_results contains res if {
    # ... your custom evaluation logic goes here ...
    
    # Map your findings to the contract structure
    res := {
        "RuleType":       "Required",       
        "AssetType":      "image",          
        "AssetId":        "12345678",      
        "EvidenceTypeId": "com.ibm.scan",   
        "Tool":           "zap",         
        "Status":         "failure",        
        "Source":         "ci-pipeline",    
        "Target":         "prod",           
    }
}

A regra “ allow ” (para execução em pipeline)

Conforme mencionado anteriormente, a segunda cláusula obrigatória deste contrato é a regra “ allow ”.

Por que isso é necessário?

Embora table_results seja responsável pela geração de relatórios sobre suas verificações de conformidade, a regra allow é o verdadeiro “kill switch” do pipeline. O mecanismo do pipeline está programado de forma rígida para consultar o valor booleano allow a fim de determinar a decisão final de prosseguir ou não.

Se você fornecer um arquivo de política personalizado, mas se esquecer de incluir a regra “ allow ”, o pipeline não saberá como prosseguir. Operando com base em um modelo de segurança rigoroso do tipo “fail-closed”, ele, por padrão, faz com que a execução do pipeline falhe e bloqueia a implantação.

Ativação do OPA

Para habilitar a verificação de conformidade baseada em OPA em seus pipelines de CD e CC, é necessário ativar explicitamente o sinalizador “ opt-in-rego-translation ” (defina-o como “ true ” ou “ 1 ”).

Restrições de configuração

Assim como no pipeline de promoção, você pode fornecer tanto um arquivo de política (sua lógica) quanto um arquivo de validação de dados (seus fatos). No entanto, há uma diferença fundamental: os pipelines CD e CC aceitam, atualmente, apenas um arquivo de validação de dados por vez, em vez de uma lista separada por vírgulas.

Anexos de Solicitação de Alteração (CR) e etapas finais do pipeline

Quando você executa o pipeline de CD, o mecanismo processa seu arquivo de validação de dados e o anexa à sua Solicitação de Alteração para fins de auditoria. O comportamento do anexo de arquivo depende inteiramente do formato que você fornecer:

• Se você fornecer um arquivo de validação de dados JSON antigo: o pipeline o converte automaticamente em segundo plano. Tanto o arquivo JSON original quanto o arquivo de configuração Rego gerado estão anexados à etapa “Solicitação de Alteração”.
• Se você fornecer um arquivo de validação de dados Rego nativo: o pipeline anexa diretamente apenas o arquivo Rego fornecido por você.

Esse mesmo comportamento de anexação também se aplica ao processo de reconstrução da configuração que ocorre durante a etapa “Conclusão do CD”, no final do pipeline.