42crunch/api-security-audit-actionAutomatiza a auditoria estática de segurança de APIs em contratos OpenAPI em CI/CD, executando mais de 300 verificações de autenticação, autorização e restrições de dados, com limiares de pontuação mínima e saída SARIF.
A ação Teste estático de segurança de API REST localiza contratos de API REST que seguem a OpenAPI Specification (OAS, anteriormente conhecida como Swagger) e executa verificações de segurança minuciosas neles. São suportadas tanto a OAS v2 como a v3.0.x, nos formatos JSON e YAML.
Você pode usar esta ação nos seguintes cenários:
A ação é baseada no API Security Audit da 42Crunch. O Security Audit realiza uma análise estática da definição da API que inclui mais de 300 verificações de boas práticas e potenciais vulnerabilidades relacionadas com autenticação, autorização, bem como restrições de dados.
Por padrão, esta ação irá:
.json e .yaml no repositório.Dessa forma, você pode localizar quaisquer contratos de API novos ou alterados no repositório.
Você pode refinar o comportamento da ação especificando partes específicas do repositório ou máscaras de nomes de arquivo a serem incluídas ou excluídas na descoberta de APIs. Você pode até desativar completamente a descoberta e, em vez disso, listar apenas arquivos de API específicos para verificação e mapeá-los para suas APIs existentes na 42Crunch API Security Platform. Você define todas essas configurações no arquivo de configuração 42c-conf.yaml. Para exemplos avançados, veja aqui.
Todas as APIs descobertas são carregadas em uma coleção de APIs na 42Crunch Platform. Por padrão, a ação usa as variáveis de ambiente GITHUB_REPOSITORY e GITHUB_REF para nomear o repositório e o nome do branch/tag/PR de onde a coleção de APIs se originou. Você pode substituir o nome usando o parâmetro de ação default-collection-name. Durante as execuções subsequentes, as APIs na coleção são mantidas sincronizadas com as alterações no seu repositório.
Adicione esta ação aos seus workflows de CI/CD no GitHub e faça com que ela falhe em definições de API que contenham problemas de segurança.
O Security Audit atribui a cada contrato de API uma pontuação de auditoria de 0 a 100 que reflete a superfície de segurança das suas APIs. Você pode usar o parâmetro min-score da GitHub Action para definir o limite da pontuação de auditoria em que a ação falha (o padrão é 75, se nenhum outro valor for especificado). Isso ajuda a detectar definições de API de má qualidade e a resolver os problemas o mais cedo possível, já na fase de design.
Condições de falha mais avançadas podem ser definidas no arquivo de configuração 42c-conf.yaml, como pontuação de auditoria por categoria (segurança ou validação de dados), nível de gravidade dos problemas, ou até mesmo problemas específicos, identificados pelo seu ID de problema. Para exemplos avançados, veja aqui.
Além disso, o plugin aplica security quality gates definidos no nível da plataforma (padrão ou orientados por tags). Os security quality gates aplicam os requisitos de segurança de aplicações definidos na empresa.
Cada vez que a ação é executada, ela inclui um link para o relatório detalhado, priorizado e acionável de cada um dos seus arquivos OpenAPI:
Siga os links para ler o relatório detalhado na 42Crunch Platform:
Você também pode acompanhar os problemas que a auditoria da 42Crunch encontrou diretamente no GitHub, na guia Security, em Code scanning alerts.
Para ativar isso, basta incluir upload-to-code-scanning:true nos parâmetros da ação no seu workflow do GitHub.
Clique em qualquer um dos alertas para ver a localização exata no seu código e obter os detalhes da vulnerabilidade e as etapas de correção recomendadas.
Esta ação usa o serviço de API Security Audit da 42Crunch. Antes de usar a ação, você precisará ter uma conta na plataforma 42Crunch. Se você não for cliente da 42Crunch, pode solicitar uma conta gratuita nesta página: https://42crunch.com/get-started/.
Em seguida, siga os passos descritos na documentação para criar um token de API para que a ação autentique na 42Crunch Platform e salve-o como um segredo no GitHub.
api-tokenObrigatório O token de API que a GitHub Action usa para autenticar na 42Crunch Platform. Não coloque seu token de API diretamente no arquivo de workflow! Em vez disso, crie um segredo do GitHub nas configurações do seu repositório e faça referência a ele conforme mostrado no exemplo abaixo.
min-scoreA pontuação mínima de auditoria que os arquivos OpenAPI devem atingir; caso contrário, a ação falha. O padrão é 75.
upload-to-code-scanningEnvie os resultados da auditoria para o Github Code Scanning. O padrão é false. Observe que o workflow deve ter permissões específicas para que esta etapa seja bem-sucedida.
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failuresSe definido como true, força a conclusão da execução com sucesso mesmo que as condições de falha (como min-score ou critérios SQG) que você definiu sejam atendidas. O padrão é false.
Este parâmetro pode ser útil se você quiser detectar cenários de falha de SQG sem aplicá-los (ou seja, dar um período de carência às equipes de desenvolvimento antes de começar a quebrar os builds).
ignore-network-errorsSe definido como true, força a conclusão da execução com sucesso mesmo se ocorrer um erro de rede (como uma falha ao conectar à 42Crunch Platform, etc.). O padrão é false.
skip-local-checksSe definido como true, desativa todas as condições de falha (como pontuação mínima) definidas no arquivo 42c-conf.yaml e só faz a execução falhar se os critérios definidos nos SQGs não forem atendidos. O padrão é false.
platform-urlA URL onde você acessa a 42Crunch Platform. O padrão é https://us.42crunch.cloud.
Se você for um cliente enterprise, informe a URL que usa para acessar sua plataforma de produção.
root-directoryO diretório raiz que contém o arquivo de configuração 42c-conf.yaml. Se não for especificado, o diretório de trabalho atual do plugin é usado em seu lugar, que normalmente corresponde à raiz do repositório verificado (checkout).
default-collection-nameO nome de coleção padrão usado ao criar coleções para as APIs descobertas. Se nenhum nome for fornecido, um nome padrão é criado a partir das informações do repositório e do branch/PR.
log-levelNível de detalhes nos logs, um de: FATAL, ERROR, WARN, INFO, DEBUG. O padrão é INFO.
share-everyoneCompartilha automaticamente as coleções de APIs criadas pela tarefa de CI/CD com todos na sua organização na 42Crunch Platform. Os valores aceitos são: OFF, READ_ONLY, READ_WRITE. O padrão é OFF. Observe que a identidade sob a qual a ação é executada (o proprietário do token de API) deve ter a permissão Share with Everyone; caso contrário, a tarefa falhará com um erro 403.
json-reportGrava um relatório de execução da auditoria em formato JSON no arquivo especificado. Um relatório de execução detalha a lista de APIs que foram criadas, atualizadas e excluídas. Isso é útil se você quiser consumir automaticamente os resultados da execução da auditoria em uma etapa subsequente do pipeline. Por padrão, nenhum relatório é gravado.
api-tagsA tarefa de CI/CD pode atribuir automaticamente tags às APIs recém-criadas. As tags são especificadas no seguinte formato: category1:name1 category2:name2. Esta flag é opcional.
sarif-reportConverte o formato JSON bruto da auditoria para SARIF e salva os resultados no arquivo especificado. Por padrão, nenhum relatório é gravado.
audit-timeoutDefine o tempo máximo de espera (em segundos) para o relatório de auditoria. A tarefa falhará se o resultado não estiver pronto dentro desse intervalo. Padrão: 600
Crie um token de API na 42Crunch Platform e copie seu valor para um segredo do repositório chamado API_TOKEN.
Uma nova etapa típica em um workflow existente teria a seguinte aparência:
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
Um workflow típico que verifica o conteúdo do repositório, executa o Security Audit em cada um dos arquivos OpenAPI encontrados no projeto e salva o arquivo de execução como artefato teria a seguinte aparência:
name: "42crunch-audit-workflow"
# follow standard Code Scanning triggers
on:
push:
branches: [ "main" ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ "main" ]
schedule:
- cron: '19 9 * * 6'
env:
PLATFORM_URL: https://us.42crunch.cloud
jobs:
run_42c_audit:
environment: QA
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
- name: 42crunch-static-api-testing
uses: 42Crunch/api-security-audit-action@v4
with:
api-token: ${{ secrets.API_TOKEN }}
platform-url: ${{ env.PLATFORM_URL}}
default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
# Upload results to Github code scanning
upload-to-code-scanning: false
log-level: info
json-report: audit-action-report-${{ github.run_id }}
sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
- name: save-audit-report
if: always()
uses: actions/upload-artifact@v3
with:
name: auditaction-report-${{ github.run_id }}
path: audit-action-report-${{ github.run_id }}.json
if-no-files-found: error
A ação é mantida pela equipe de Ecossistemas da 42Crunch. Se você encontrar um problema ou tiver uma pergunta não respondida aqui, pode criar um ticket de suporte em support.42crunch.com.
Ao relatar um problema, inclua: