Уведомление о прекращении поддержки: Hawkeye достиг конца своего жизненного цикла.

Существуют более современные варианты для вас и вашего проекта. Если вы хотите взять на себя поддержку проекта, пожалуйста, свяжитесь со мной. Вы найдете способы связаться со мной на моей личной странице.

.

.

.

.

.

.

Hawkeye scanner-cli — это инструмент для выявления проблем безопасности, уязвимостей и общих рисков в проекте. Он предназначен для интеграции в ваши pre-commit хуки и пайплайны.

Запуск и настройка сканера

Hawkeye scanner-cli предполагает, что структура вашего каталога такова, что файлы инструментария находятся на верхнем уровне. Примерно это сводится к следующему:

• Node.js проекты имеют package.json на верхнем уровне
• Ruby проекты будут иметь Gemfile на верхнем уровне
• Python проекты будут иметь requirements.txt на верхнем уровне
• PHP проекты будут иметь composer.lock на верхнем уровне
• Java проекты будут иметь папку build (gradle) или target (maven) и содержать файлы .java и .jar
• Kotlin проекты будут иметь папку build (gradle) или target (maven) и содержать файлы .kt и .jar
• Scala проекты будут иметь папку target (sbt с плагинами sbt-native-packager или sbt-assembly) и содержать файлы .scala и .jar. Пример работающего демо можно найти в этом репозитории.
• Rust проекты будут иметь Cargo.toml на верхнем уровне

Это не исчерпывающий список, так как иногда инструментам требуются дополнительные файлы. Чтобы понять, как модули принимают решение о том, могут ли они обработать проект, пожалуйста, ознакомьтесь с разделом Как это работает и папкой модули.

Docker (рекомендуется)

Docker-образ — это самый простой способ использования сканера. Обратите внимание, что корень вашего проекта (например, $PWD) должен быть смонтирован в /target.

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

Если вы используете сканер для записи JSON (с помощью флагов CLI -j и --json и настройки json в .hawkeyerc), убедитесь, что он использует правильные UID и GID с помощью docker run -u $(id -u):$(id -g). В противном случае это может привести к появлению неудаляемых файлов, например, при запуске в Jenkins.

Сборка Docker также является рекомендуемым способом запуска сканера в ваших CI-пайплайнах. Вот пример запуска Hawkeye против одного из ваших проектов в 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

Вы можете установить и запустить hawkeye в Node.js проекте с помощью

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

Этот метод рекомендуется в Node.js проектах, где другие инструментальные цепочки (например, python, ruby) не требуются.

При использовании этого метода также рекомендуется вызывать сканер в git pre-commit хуке (например, с помощью пакета pre-commit), чтобы отклонить коммит при обнаружении проблем.

Файлы конфигурации (рекомендуется)

Вы можете настроить сканер с помощью файлов .hawkeyerc и .hawkeyeignore в корне вашего проекта.

Файл .hawkeyerc — это JSON-файл, который позволяет настроить ...

• модули для запуска,
• используемые писатели (writers), и
• порог ошибки

{
    "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
}

Файл .hawkeyeignore — это набор регулярных выражений, соответствующих путям и кодам ошибок модулей, которые следует исключить из сканирования. Он эквивалентен использованию флага --exclude. Строки, начинающиеся с #, считаются комментариями.

Обратите внимание, что любые специальные символы, зарезервированные в регулярных выражениях (-[]{}()*+?.,^$|#\s), должны быть экранированы при использовании в качестве литералов!

Также обратите внимание, что коды ошибок модулей обычно не отображаются, так как они не являются первостепенно важными для пользователя. Если вы хотите исключить определенное ложное срабатывание, вы можете отобразить коды ошибок модулей с помощью флага --show-code или свойства showCode в файле .hawkeyerc.

^test/

# это комментарий

^README.md

CLI

Используйте hawkeye modules, чтобы вывести список доступных модулей и их статус.

> 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

Используйте hawkeye scan, чтобы запустить сканирование:

> 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

Результаты

Коды завершения

Сканер-cli отвечает следующими кодами завершения:

• Код завершения 0 означает, что не было найдено результатов, превышающих или равных минимальному порогу.
• Код завершения 1 означает, что были найдены проблемы, превышающие или равные минимальному порогу.
• Код завершения 42 означает, что в какой-то части программы произошла неожиданная ошибка. Это, вероятно, ошибка и не должно происходить. Пожалуйста, проверьте вывод журнала и сообщите об ошибке.

Перенаправление вывода консоли

Если вы хотите перенаправить вывод консольного логгера, рекомендуется использовать захват stdout. В этом примере мы используем как JSON, так и вывод в stdout:

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

Вывод в консоль

По умолчанию сканер выводит результаты в консоль в табличной форме.

Sumologic

Результаты могут быть отправлены в выбранный вами коллектор SumoLogic. В этом примере у нас есть коллектор с одним HTTP-источником.

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

В SumoLogic ищите _collector="hawkeye" | json auto:

Любая HTTP-конечная точка

Аналогично примеру с SumoLogic, сканер может отправлять результаты на любую HTTP-конечную точку, принимающую POST-сообщения.

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

Результаты будут отправлены с User-Agent: hawkeye. Аналогично выводу в консоль, для каждого обнаружения будет отправлен следующий JSON:

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

Как это работает

Hawkeye спроектирован так, чтобы быть расширяемым за счет добавления модулей и писателей (writers).

• Добавляйте модули в папку modules.
• Добавляйте писателей в папку writers.

Модули

Модули — это, по сути, небольшие фрагменты кода, которые либо реализуют собственную логику, либо оборачивают сторонний инструмент и стандартизируют вывод. Они запускаются только в том случае, если выполнены необходимые критерии. Например: Модуль npm outdated запустится только в том случае, если в цели сканирования обнаружен package.json — в результате вам не нужно сообщать Hawkeye, какой тип проекта вы сканируете.

Общие модули

• files-ccnumber: Ищет подозрительное содержимое файлов, которое может содержать номера кредитных карт.
• files-contents: Ищет подозрительное содержимое файлов, которое может содержать секреты.
• files-entropy: Сканирует файлы на наличие строк с высокой энтропией, которые могут содержать пароли. Сканирование энтропии отключено по умолчанию из-за большого количества ложных срабатываний. Полезно время от времени сканировать кодовые базы на наличие ключей, в этом случае, пожалуйста, запускайте его с помощью переключателя -m files-entropy.
• files-secrets: Ищет подозрительные имена файлов, которые могут содержать секреты.

Java / Kotlin / Scala

• java-find-secbugs: Находит распространенные проблемы безопасности в Java-коде с помощью findsecbugs.
• java-owasp: Сканирует Java-проекты на наличие зависимостей gradle/maven с известными уязвимостями с помощью OWASP dependency checker.

Node.js

• node-npmaudit: Проверяет node-проекты на наличие зависимостей с известными уязвимостями с помощью npm audit.
• node-npmoutdated: Проверяет node-проекты на устаревшие npm-модули с помощью npm outdated.
• node-yarnaudit: Проверяет yarn-проекты на наличие зависимостей с известными уязвимостями с помощью yarn audit.
• node-yarnoutdated: Проверяет node-проекты на устаревшие yarn-модули с помощью yarn outdated.

PHP

• php-security-checker: Проверяет, содержит ли composer.lock зависимости с известными уязвимостями, с помощью security-checker.

Python

• python-bandit: Сканирует Python-код на наличие распространенных проблем безопасности с помощью bandit.
• python-piprot: Сканирует python-зависимости на наличие устаревших пакетов с помощью piprot.
• python-safety: Проверяет python-зависимости на наличие известных уязвимостей безопасности с помощью инструмента safety.

Ruby

• ruby-brakeman: Статически анализирует Rails-код на наличие проблем безопасности с помощью Brakeman.
• ruby-bundler-scan: Сканирует Ruby-гемы на наличие известных уязвимостей с помощью bundler.

Rust

• rust-cargoaudit: Проверяет, содержит ли Cargo.lock зависимости с известными уязвимостями, с помощью cargo audit.

Добавление модуля

Если у вас есть идея для модуля, пожалуйста, не стесняйтесь открыть запрос на добавление функции (feature request) в разделе issues. Если у вас есть немного свободного времени, пожалуйста, рассмотрите возможность отправки нам pull request. Чтобы увидеть, как работают модули, перейдите в папку modules, чтобы узнать, как всё устроено.