Aviso de Descontinuação: Hawkeye chegou ao fim de sua vida útil.

Existem opções mais modernas disponíveis para você e seu projeto. Se desejar assumir a manutenção do projeto, sinta-se à vontade para entrar em contato comigo. Você encontrará formas de me contatar na minha página pessoal.

.

.

.

.

.

.

O scanner-cli do Hawkeye é uma ferramenta de segurança de projeto, vulnerabilidade e destaque de risco geral. Ele é destinado a ser integrado em seus hooks de pré-commit e em suas pipelines.

Executando e configurando o scanner

O scanner-cli do Hawkeye assume que sua estrutura de diretórios mantém os arquivos da toolchain no nível superior. Basicamente, é isso que se resume a:

• Node.js projetos têm um package.json no nível superior
• Ruby projetos terão um Gemfile no nível superior
• Python projetos terão um requirements.txt no nível superior
• PHP projetos terão um composer.lock no nível superior
• Java projetos terão uma pasta build (gradle) ou target (maven) e incluirão arquivos .java e .jar
• Kotlin projetos terão uma pasta build (gradle) ou target (maven) e incluirão arquivos .kt e .jar
• Scala projetos terão uma pasta target (sbt com plugins sbt-native-packager ou sbt-assembly) e incluirão arquivos .scala e .jar. Confira este repositório para uma demonstração em execução.
• Rust projetos terão um Cargo.toml no nível superior

Isso não é exaustivo, pois às vezes as ferramentas exigem que outros arquivos existam. Para entender como os módulos decidem se podem lidar com um projeto, consulte a seção Como funciona e a pasta módulos.

Docker (recomendado)

A imagem docker é de longe a maneira mais fácil de usar o scanner. Observe que a raiz do seu projeto (ex.: $PWD) precisa ser montada em /target.

docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest

Se você está usando o scanner para escrever um JSON (através das flags de CLI -j e --json e da configuração json no .hawkeyerc), certifique-se de que ele usa o UID e GID corretos via docker run -u $(id -u):$(id -g). Caso contrário, isso pode deixar arquivos indeletáveis, por exemplo, ao executar no Jenkins.

A build docker também é a maneira recomendada de executar o scanner em suas pipelines de CI. Este é um exemplo de execução do Hawkeye em um de seus projetos no GoCD:

<pipeline name="security-scan">
  <stage name="Hawkeye" cleanWorkingDir="true">
    <jobs>
      <job name="scan">
        <tasks>
          <exec command="docker">
            <arg>pull</arg>
            <arg>hawkeyesec/scanner-cli</arg>
            <runif status="passed" />
          </exec>
          <exec command="bash">
            <arg>-c</arg>
            <arg>docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest</arg>
            <runif status="passed" />
          </exec>
        </tasks>
      </job>
    </jobs>
  </stage>
</pipeline>

npm

Você pode instalar e executar o hawkeye em um projeto Node.js através de

npm install --save-dev @hawkeyesec/scanner-cli
npx hawkeye scan

Este método é recomendado em um projeto Node.js, onde as outras toolchains (ex.: python, ruby) não são necessárias.

Com este método, também é recomendado invocar o scanner em um hook de pré-commit do git (ex.: através do pacote pre-commit) para falhar o commit se forem encontrados problemas.

Arquivos de Configuração (recomendado)

Você pode configurar o scanner através dos arquivos .hawkeyerc e .hawkeyeignore na raiz do seu projeto.

O arquivo .hawkeyerc é um arquivo JSON que permite configurar ...

• os módulos a serem executados,
• os escritores a serem usados,
• e o limite de falha

{
    "all": true|false,
    "staged": true|false,
    "modules": ["files-ccnumber", "java-owasp", "java-find-secbugs"],
    "sumo": "http://your.sumologic.foobar/collector",
    "http": "http://your.logger.foobar/collector",
    "json": "log/results.json",
    "failOn": "low"|"medium"|"high"|"critical",
    "showCode": true|false
}

O arquivo .hawkeyeignore é uma coleção de expressões regulares que correspondem a caminhos e códigos de erro do módulo para excluir da verificação, e é equivalente a usar a flag --exclude. Linhas começando com # são consideradas comentários.

Por favor, observe que quaisquer caracteres especiais reservados em expressões regulares (-[]{}()*+?.,^$|#\s) precisam ser escapados quando usados como literal!

Observe também que os códigos de erro do módulo geralmente não são exibidos, pois não são principalmente relevantes para o usuário. Se você quiser excluir um determinado falso positivo, pode exibir os códigos de erro do módulo com a flag --show-code ou a propriedade showCode no .hawkeyerc.

^test/

# isto é um comentário

^README.md

A CLI

Use hawkeye modules para listar os módulos disponíveis e seu status.

> npx hawkeye modules
[info] Version: v1.4.0
[info] Module Status
[info] Enabled:   files-ccnumber
[info]            Scans for suspicious file contents that are likely to contain credit card numbers
[info] Enabled:   files-contents
[info]            Scans for suspicious file contents that are likely to contain secrets
[info] Disabled:  files-entropy
[info]            Scans files for strings with high entropy that are likely to contain passwords
[info] Enabled:   files-secrets
[info]            Scans for suspicious filenames that are likely to contain secrets
[info] Enabled:   java-find-secbugs
[info]            Finds common security issues in Java code with findsecbugs
[info] Enabled:   java-owasp
[info]            Scans Java projects for gradle/maven dependencies with known vulnerabilities with the OWASP dependency checker
[info] Enabled:   node-npmaudit
[info]            Checks node projects for dependencies with known vulnerabilities
[info] Enabled:   node-npmoutdated
[info]            Checks node projects for outdated npm modules
[info] Enabled:   node-yarnaudit
[info]            Checks yarn projects for dependencies with known vulnerabilities
[info] Enabled:   node-yarnoutdated
[info]            Checks node projects for outdated yarn modules
[info] Enabled:   php-security-checker
[info]            Checks whether the composer.lock contains dependencies with known vulnerabilities using security-checker
[info] Enabled:   python-bandit
[info]            Scans for common security issues in Python code with bandit.
[info] Enabled:   python-piprot
[info]            Scans python dependencies for out of date packages
[info] Enabled:   python-safety
[info]            Checks python dependencies for known security vulnerabilities with the safety tool.
[info] Enabled:   ruby-brakeman
[info]            Statically analyzes Rails code for security issues with Brakeman.
[info] Enabled:   ruby-bundler-scan
[info]            Scan for Ruby gems with known vulnerabilities using bundler

Use hawkeye scan para iniciar uma varredura:

> npx hawkeye scan --help
[info] Version: v1.3.0
Usage: hawkeye-scan [options]

Options:
  -a, --all                                       Scan all files, regardless if a git repo is found. Defaults to tracked files in git repositories.
  -t, --target [/path/to/project]                 The location to scan. Defaults to $PWD.
  -f, --fail-on [low|medium|high|critical]        Set the level at which hawkeye returns non-zero status codes. Defaults to low.
  -m, --module [module name]                      Run specific module. Defaults to all applicable modules.
  -e, --exclude [pattern]                         Specify one or more exclusion patterns (eg. test/*). Can be specified multiple times.
  -j, --json [/path/to/file.json]                 Write findings to file.
  -s, --sumo [https://sumologic-http-connector]   Write findings to SumoLogic.
  -H, --http [https://your-site.com/api/results]  Write findings to a given url.
  --show-code                                     Shows the code the module uses for reporting, useful for ignoring certain false positives
  -g, --staged                                    Scan only git-staged files.
  -h, --help                                      output usage information

Resultados

Códigos de Saída

O scanner-cli responde com os seguintes códigos de saída:

• Código de saída 0 indica que não foram encontradas descobertas acima ou iguais ao limite mínimo.
• Código de saída 1 indica que foram encontrados problemas acima ou iguais ao limite mínimo.
• Código de saída 42 indica que ocorreu um erro inesperado em algum lugar do programa. Provavelmente é um bug e não deveria acontecer. Verifique a saída do log e relate um bug.

Redirecionando a saída do console

Se você deseja redirecionar a saída do logger do console, o método recomendado é capturar a saída padrão. Neste exemplo, estamos usando tanto resultados JSON quanto stdout:

docker run --rm -v $PWD:/target hawkeyesec/scanner-cli:latest -j hawkeye-results.json -f critical 2>&1 | tee hawkeye-results.txt

Saída do console

Por padrão, o scanner exibe seus resultados no console em formato tabular.

Sumologic

Os resultados podem ser enviados para um coletor SumoLogic de sua escolha. Neste exemplo, temos um coletor com uma única fonte HTTP.

hawkeye scan --sumo https://collectors.us2.sumologic.com/receiver/v1/http/your-http-collector-url

No SumoLogic, pesquise por _collector="hawkeye" | json auto:

Qualquer endpoint HTTP

Semelhante ao exemplo do SumoLogic, o scanner pode enviar os resultados para qualquer endpoint HTTP que aceite mensagens POST.

hawkeye scan --http http://your.logging.foobar/endpoint

Os resultados serão enviados com User-Agent: hawkeye. Semelhante à saída do console, o seguinte JSON será POSTado para cada descoberta:

{
  "module": "files-contents",
  "level": "critical",
  "offender": "testfile3.yml",
  "description": "Private key in file",
  "mitigation": "Check line number: 3"
}

Como funciona

O Hawkeye é projetado para ser extensível adicionando módulos e escritores.

• Adicione módulos na pasta módulos.
• Adicione escritores na pasta escritores.

Módulos

Módulos são basicamente pequenos trechos de código que implementam sua própria lógica ou encapsulam uma ferramenta de terceiros e padronizam a saída. Eles só são executados se os critérios necessários forem atendidos. Por exemplo: O módulo npm outdated só seria executado se um package.json for detectado no alvo da varredura - como resultado, você não precisa dizer ao Hawkeye que tipo de projeto você está escaneando.

Módulos Genéricos

• files-ccnumber: Escaneia conteúdos de arquivos suspeitos que provavelmente contêm números de cartão de crédito
• files-contents: Escaneia conteúdos de arquivos suspeitos que provavelmente contêm segredos
• files-entropy: Escaneia arquivos por strings com alta entropia que provavelmente contêm senhas. A varredura de entropia está desabilitada por padrão devido ao alto número de falsos positivos. É útil escanear bases de código de vez em quando em busca de chaves; nesse caso, execute-o usando a opção -m files-entropy.
• files-secrets: Escaneia nomes de arquivos suspeitos que provavelmente contêm segredos

Java / Kotlin / Scala

• java-find-secbugs: Encontra problemas comuns de segurança em código Java com findsecbugs
• java-owasp: Escaneia projetos Java por dependências gradle/maven com vulnerabilidades conhecidas com o verificador de dependências da OWASP

Node.js

• node-npmaudit: Verifica projetos Node por dependências com vulnerabilidades conhecidas com npm audit
• node-npmoutdated: Verifica projetos Node por módulos npm desatualizados com npm outdated
• node-yarnaudit: Verifica projetos Yarn por dependências com vulnerabilidades conhecidas com yarn audit
• node-yarnoutdated: Verifica projetos Node por módulos Yarn desatualizados com yarn outdated

PHP

• php-security-checker: Verifica se o composer.lock contém dependências com vulnerabilidades conhecidas usando security-checker

Python

• python-bandit: Escaneia problemas comuns de segurança em código Python com bandit.
• python-piprot: Escaneia dependências Python por pacotes desatualizados com piprot
• python-safety: Verifica dependências Python por vulnerabilidades de segurança conhecidas com a ferramenta safety.

Ruby

• ruby-brakeman: Analisa estaticamente código Rails por problemas de segurança com Brakeman.
• ruby-bundler-scan: Escaneia gems Ruby com vulnerabilidades conhecidas usando bundler

Rust

• rust-cargoaudit: Verifica se o Cargo.lock contém dependências com vulnerabilidades conhecidas usando cargo audit

Adicionando um módulo

Se você tem uma ideia para um módulo, sinta-se à vontade para abrir uma solicitação de funcionalidade na seção de issues. Se tiver um tempinho livre, considere nos enviar um pull request. Para ver como os módulos funcionam, vá para a pasta módulos para descobrir como as coisas estão funcionando.