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

Ativando um Runner do Syhunt
Adicionando o Syhunt ao seu script YML no Actions
Start-DynamicScan - Iniciando uma varredura dinâmica
Start-CodeScan - Iniciando uma varredura de código-fonte
Condições de aprovação / reprovação
Integrando com o Issues do GitHub

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.

  1. Primeiro, instale com suas configurações padrão o Git for Windows, que pode ser baixado em https://gitforwindows.org/
  2. Em segundo lugar, instale com suas configurações padrão o Syhunt Hybrid (syhunt-hybrid-7.0.12.0.exe)
  3. Por fim, no GitHub.com, navegue até a página principal do repositório:
    1. Sob o nome do seu repositório, clique em Settings (Configurações).
    2. Na barra lateral esquerda, clique em Actions (Ações).
    3. Na barra lateral esquerda, em Actions, clique em Runners
    4. Clique em New self-hosted runner (Novo executor auto-hospedado).
    5. Selecione o sistema operacional Windows e a arquitetura x64
    6. Você verá instruções mostrando como baixar o aplicativo runner e instalá-lo em sua máquina.
  4. Siga as instruções fornecidas para ativar o runner com o token do repositório.
    1. 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.
    2. Digite um nome para identificar o runner. Exemplo: syhunt
    3. Insira um rótulo para o runner. Exemplo: syhunt
    4. Por fim, você verá as mensagens abaixo, que indicam sucesso:
    5. v Runner successfully added (Executor adicionado com sucesso)
    6. v Runner connection is good (A conexão com o executor é boa)
    7. Agora pressione enter para manter _work como o diretório de trabalho.
    8. Especifique se deseja executar o runner como um serviço do Windows (SIM ou NÃO)
  5. Agora você deve executar run.cmd. Você deverá ver a seguinte mensagem:
    1. v Connected to GitHub (Conectado ao GitHub)
    2. 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

Exemplos adicionais: 


# 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 ou fail-if:risk=high - Falha se for encontrada uma vulnerabilidade ou ameaça de alto risco
  • medium ou fail-if:risk=mediumup - Falha se for encontrada uma vulnerabilidade ou ameaça de risco Médio ou Alto
  • low ou fail-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

Fale Conosco

Contato