Integrando o Syhunt no GitHub
As informações contidas neste documento se aplicam a versão 6.9.8.2 do Syhunt Hybrid.
Table of Contents
Introdução
Iniciar varreduras Syhunt de dentro de um script YML do GitHub Actions é simples e direto, permitindo que você integre as ferramentas de teste de segurança Syhunt Dynamic, Syhunt Code e Syhunt Mobile em seu pipeline de entrega contínua. Você também pode configurar os rastreadores de problemas do GitHub no Syhunt, permitindo que as vulnerabilidades sejam enviadas para a área de problemas dos projetos.
O script a seguir de exemplo é um YML para o GitHub Actions que verifica o código-fonte do repositório atual, falhando o trabalho se vulnerabilidades médias ou altas forem identificadas. Além disso, anexa um relatório de vulnerabilidade em PDF aos artefatos de trabalho do pipeline.
name: syhunt test
on:
push:
branches:
- main
jobs:
build:
runs-on: [self-hosted, Windows, X64]
steps:
- uses: actions/checkout@v2
- run: Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf'
- name: 'Syhunt Report'
uses: actions/upload-artifact@v2
if: failure()
with:
name: syhunt-report
path: report.pdf
if-no-files-found: error
Ativando um Runner do Syhunt
O Syhunt Runner é um serviço de CI que receberá solicitações de varredura, executará varreduras e comunicará os resultados da varredura com o GitHub.
IMPORTANTE: Por motivos de segurança e desempenho, é aconselhável que o Runner seja instalado em uma máquina virtual separada ou máquina física dedicada.
- Primeiro, instale com suas configurações padrão o Git for Windows, que pode ser baixado em https://gitforwindows.org/
- Em segundo lugar, instale com suas configurações padrão o Syhunt Hybrid (syhunt-hybrid-7.0.14.0.exe)
- Por fim, no GitHub.com, navegue até a página principal do repositório:
- Sob o nome do seu repositório, clique em Settings (Configurações).
- Na barra lateral esquerda, clique em Actions (Ações).
- Na barra lateral esquerda, em Actions, clique em Runners
- Clique em New self-hosted runner (Novo executor auto-hospedado).
- Selecione o sistema operacional Windows e a arquitetura x64
- Você verá instruções mostrando como baixar o aplicativo runner e instalá-lo em sua máquina.
- Siga as instruções fornecidas para ativar o runner com o token do repositório.
- Ao executar config.cmd, será solicitado a digitar o nome do grupo ao qual o runner será adicionado. Pressione enter para o grupo padrão.
- Digite um nome para identificar o runner. Exemplo: syhunt
- Insira um rótulo para o runner. Exemplo: syhunt
- Por fim, você verá as mensagens abaixo, que indicam sucesso:
- v Runner successfully added (Executor adicionado com sucesso)
- v Runner connection is good (A conexão com o executor é boa)
- Agora pressione enter para manter _work como o diretório de trabalho.
- Especifique se deseja executar o runner como um serviço do Windows (SIM ou NÃO)
- Agora você deve executar run.cmd. Você deverá ver a seguinte mensagem:
- v Connected to GitHub (Conectado ao GitHub)
- 2022-02-04 19:50:21Z: Listening for Jobs (Ouvindo por Trabalhos)
O Syhunt agora está pronto para ser chamado de scripts GitHub Actions! Veja exemplos abaixo
Observação: um executor auto-hospedado é removido automaticamente do GitHub se não estiver conectado ao GitHub Actions por mais de 30 dias. Além disso, cada execução de fluxo de trabalho é limitada a 72 horas. Se uma execução de fluxo de trabalho atingir esse limite, a execução de fluxo de trabalho será cancelada.
Adicionando o Syhunt ao seu script YML do Actions
Se você não tiver um arquivo YML de fluxo de trabalho em seu repositório, crie um arquivo como “.github/workflows/blank.yml” no caminho raiz do seu projeto.
Exemplo de SAST - O exemplo de script YML para o Actions do Github a seguir verificará o código-fonte do repositório atual, falhando o trabalho se vulnerabilidades médias ou altas forem identificadas. Além disso, ele anexa um relatório de vulnerabilidade em PDF aos artefatos de trabalho do pipeline.
name: syhunt test
on:
push:
branches:
- main
jobs:
build:
runs-on: [self-hosted, Windows, X64]
steps:
- uses: actions/checkout@v2
- run: Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf'
- name: 'Syhunt Report'
uses: actions/upload-artifact@v2
if: failure()
with:
name: syhunt-report
path: report.pdf
if-no-files-found: error
Exemplo de DAST - O exemplo de script YML para o Github Actions a seguir verificará a aplicação da Web ativo após entrar em produção, falhando o trabalho se vulnerabilidades médias ou altas forem identificadas. Além disso, ele anexa um relatório de vulnerabilidade em PDF aos artefatos de trabalho do pipeline.
name: syhunt test
on:
push:
branches:
- main
jobs:
build:
runs-on: [self-hosted, Windows, X64]
steps:
- uses: actions/checkout@v2
- run: Start-DynamicScan -target 'www.productionurl.com' -pfcond 'fail-if:risk=mediumup' -output 'report.pdf'
- name: 'Syhunt Report'
uses: actions/upload-artifact@v2
if: failure()
with:
name: syhunt-report
path: report.pdf
if-no-files-found: error
# Exemplo de SAST - Analisar diretório / repositório local
Start-CodeScan -pfcond "medium"
# Exemplo de SAST - Analisar um repositório GIT remoto
$MyProject = @{
target = 'https://github.com/syhunt/vulnphp.git';
branch = 'main';
pfcond = 'medium';
output = 'report.pdf'
}
Start-CodeScan @MyProject
# Exemplo de DAST - Analisar um URL
$MyWebsite= @{
target = 'https://www.somewebsite.com';
pfcond = 'medium';
output = 'report.pdf'
}
Start-DynamicScan @MyWebsite
A Função Start-DynamicScan
O Syhunt Dynamic deve ser iniciado através da função Start-DynamicScan(). Os seguintes parâmetros devem ser fornecidos ao chamar a função Start-DynamicScan():
- target (obrigatório) - o URL alvo a ser analisado (ex. http://www.somesite.com)
- huntmethod (opcional) - o Método de Varredura a ser usado durante a análise. Se omitido, o método padrão será usado.
- pfcond (opcional) - permite que o script falhe com o código de saída adequado se uma determinada condição for atendida. Veja abaixo uma lista das condições de aprovação / reprovação disponíveis.
- tracker (opcional) - o nome do rastreador criado anteriormente ou um rastreador gerado dinamicamente para o qual será enviado um resumo das vulnerabilidades identificadas ao final da varredura. Exemplos
- output (opcional) - permite definir um nome de arquivo de relatório (por exemplo, report.pdf ou report.html).
- outputex (opcional) - permite definir um segundo nome de arquivo de saída (por exemplo, export.json).
- verbmode (opcional) - $ false por padrão. Se alterado para true, ativa o modo detalhado, permitindo que informações de erro e informações básicas sejam adicionadas ao console.
- genrep (opcional) - $ true por padrão. Se alterado para false, o Syhunt não gerará um arquivo de relatório.
- redirIO (opcional) - $ true por padrão. Se alterado para false, informações de status em tempo-real do scanner Syhunt não serão redirecionadas para o console.
- timelimit (opcional) - define o tempo máximo da varredura (padrão: sem limite). Caso o tempo seja atingido, a varredura é cancelada. Exemplos: 1d, 3h, 2h30m, 50m
Ao usar os parâmetros output ou outputex, todos os formatos de saída suportados pelo Syhunt estão disponíveis. O relatório ou exportação será salvo no diretório de trabalho atual, a menos que seja fornecido um nome de caminho completo.
Exemplos:
# Exemplo 1 - Analisar um URL com uma única linha
Start-DynamicScan -target 'https://www.somewebsite.com' -pfcond 'fail-if:risk=mediumup'
# Exemplo 2 - Analisar um URL
$MyWebsite= @{
target = 'https://www.somewebsite.com';
pfcond = 'medium';
output = 'report.pdf'
}
Start-DynamicScan @MyWebsite
A Funçao Start-CodeScan
O Syhunt Code deve ser iniciado através da função Start-CodeScan(). Os seguintes parâmetros podem ser fornecidos ao chamar a função Start-CodeScan(), sendo todas eles opcionais:
- target - o URL de um repositório GIT ou um diretório ou arquivo de código-fonte local a ser verificado. Se o parâmetro target for omitido, o diretório de trabalho atual será verificado.
- branch - a ramificação do repositório a ser analisada. Se o parâmetro branch for omitido, o branch padrão será analisado.
- huntmethod - o Método de Varredura a ser usado durante a análise. Se omitido, o método padrão será usado.
- pfcond - permite que o script falhe com o código de saída adequado se uma determinada condição for atendida. Veja abaixo uma lista das condições de aprovação / reprovação disponíveis.
- output - permite definir um nome de arquivo de relatório (por exemplo, report.pdf ou report.html).
- outputex - permite definir um segundo nome de arquivo de saída (por exemplo, export.json).
- verbmode - $ false por padrão. Se alterado para true, ativa o modo detalhado, permitindo que informações de erro e informações básicas sejam adicionadas ao console.
- genrep - $ true por padrão. Se alterado para false, o Syhunt não gerará um arquivo de relatório.
- redirIO - $ true por padrão. Se alterado para false, informações de status em tempo-real do scanner Syhunt não serão redirecionadas para o console.
- timelimit (opcional) - define o tempo máximo da varredura (padrão: sem limite). Caso o tempo seja atingido, a varredura é cancelada. Exemplos: 1d, 3h, 2h30m, 50m
Ao usar os parâmetros output ou outputex, todos os formatos de saída suportados pelo Syhunt estão disponíveis. O relatório ou exportação será salvo no diretório de trabalho atual, a menos que seja fornecido um nome de caminho completo.
Exemplos:
# Exemplo 1 - Analisando o diretório / repositório atual
Start-CodeScan -pfcond "medium"
# Exemplo 2 - Analisando um projeto GIT remoto
Start-CodeScan -target "https://github.com/someuser/somerepo.git" -huntmethod "normal" -pfcond "medium"
# Exemplo 3 - Analisando um diretório local específico
Start-CodeScan -target "C:\www\" -huntmethod "normal" -pfcond "medium"
Condições de Aprovação/Reprovação
A seguir estão as condições de aprovação / reprovação atualmente suportadas pelo Syhunt:
high
oufail-if:risk=high
- Falha se for encontrada uma vulnerabilidade ou ameaça de alto riscomedium
oufail-if:risk=mediumup
- Falha se for encontrada uma vulnerabilidade ou ameaça de risco Médio ou Altolow
oufail-if:risk=lowup
- Falha se for encontrada uma vulnerabilidade ou ameaça de risco Baixo, Médio ou Alto
Integração com o Issues do GitHub
Configurar um rastreador de problemas é uma tarefa fácil e as vulnerabilidades podem ser enviadas para um projeto específico com o clique de um botão.
Para obter mais detalhes sobre como enviar vulnerabilidades ao rastreador do GitHub, consulte: Enviando vulnerabilidades para um rastreador.
Para documentação adicional do produto, visite syhunt.com/docs/br