Справочник по тестированию Trail of Bits

Справочник по тестированию Trail of Bits — это ресурс для разработчиков и специалистов по безопасности, посвящённый настройке, оптимизации и автоматизации многих инструментов статического и динамического анализа, которые мы используем в Trail of Bits.

Предпросмотр Testing Handbook: https://appsec.guide 🌐

Зачем это нужно? ✨

• 📃 Документация по настройке и оптимизации существующих инструментов часто неудобна для разработчиков, поскольку обычно рассчитана на специалистов по безопасности. Особенно это касается утилит для фаззинга. Это может привести к разочарованию и низкому уровню внедрения инструментов безопасности, которые должны настраиваться просто.
• ⚙️ Даже если инструмент легко настроить локально, его настройка в конвейерах CI/CD может быть затруднительной. Часто инструменты безопасности разворачивают, следуя онлайн-документации, но их конфигурация редко оптимизируется. Это может привести к появлению «шумного» инструмента, который сложнее поддерживать, чем он того стоит.
• 🧠 Мы стремимся максимально упростить эффективную настройку инструментов безопасности. При этом мы также надеемся сделать менее загадочными методы статического и динамического анализа, такие как фаззинг и анализ потоков данных (taint analysis).

Главы

✅ Выпущенные

🎥 Вебинары

🚧 В разработке

• kAFL
• Rust
• Формальная верификация и Tamarin

Как внести вклад

Если вы хотите внести вклад в Testing Handbook, вот несколько рекомендаций, которые помогут вам начать:

1. Добавить новый инструмент: Если вы хотите описать новый инструмент в Testing Handbook, предложите тему в GitHub Issues. После этого вы можете работать над новым pull request.
2. Улучшить существующие главы: Если у вас есть идея, как улучшить конкретную главу, вы можете создать GitHub issue.
3. Взяться за небольшие задачи: Если у вас мало времени, но вы всё равно хотите внести вклад, вы можете выбрать любую небольшую задачу из списка GitHub issues.
4. Сообщить об ошибках: Если вы нашли небольшую техническую проблему или опечатку, создайте новый GitHub issue и/или исправьте её в новом pull request.

Быстрая настройка для удобной разработки

1. Установите Hugo в вашей системе

   root@kitploit:~

   brew install hugo
   

2. Клонируйте репозиторий

   root@kitploit:~

   git clone --recurse-submodules https://github.com/trailofbits/testing-handbook.git
   

3. Создайте новую ветку или выберите ветку, в которой хотите работать

   root@kitploit:~

   cd testing-handbook
   # then
   git checkout -b name-of-your-new-branch
   # or
   git checkout name-of-existing-branch
   

4. Запустите сервер Hugo с включёнными черновиками (-D) из корневого каталога проекта. Ваш браузер будет автоматически обновляться при сохранении изменений.

   root@kitploit:~

   hugo server -D
   

5. Добавьте новый инструмент как «doc» и выполните следующую команду из корневого каталога проекта.

   root@kitploit:~

   hugo new docs/<name of tool>
   

   Примечание: В этом проекте используется тот же шаблон Hugo, что и в zkdocs. В шаблоне каждая новая страница называется «doc», а не «post». Поэтому нужно вводить hugo new docs/<name of tool>, а не post/my-new-post.

6. Редактируйте, добавляйте изменения и создавайте pull request для слияния ваших изменений в .

Рекомендации

• Формат должен быть единообразным для каждого «doc». При добавлении нового doc (т.е. нового инструмента) следуйте шаблону в content/docs/template.md. При необходимости отправьте PR для этого файла с предлагаемыми изменениями.

• Создайте новую ветку с вашими изменениями и PR для слияния в main по завершении.

• GitHub workflow в этом репозитории проверяет корректность Markdown-файлов с помощью трёх проверок:

  1. Проверка ссылок Markdown: Этот шаг извлекает ссылки из Markdown-файлов и проверяет, являются ли они действительными и доступными. Используется lychee link checking action.
  2. Markdown Linter: Этот шаг обеспечивает соответствие Markdown-файлов желаемым правилам стиля и форматирования. Используются файл пользовательской конфигурации (.github/workflows/.markdownlint.jsonc) и markdownlint-cli2-action action. Для более удобной работы над Testing Handbook используйте расширение markdownlint в Visual Studio Code.
  3. Проверка правописания: Этот шаг проверяет орфографию в Markdown-файлах (построен на основе retext и remark). Используется tbroadley/spellchecker-cli-action action.

• Ознакомьтесь с темой Hugo Book она имеет несколько полезных возможностей (кнопки и т.д.)

• Если у вас есть вопросы, обращайтесь в #testing-handbook в Empire Hacking Slack.

Редактирование

Рекомендации по написанию

• Термин «Testing Handbook» должен писаться с заглавной буквы при каждом появлении на сайте (будь то заголовок/подзаголовок или основной текст), поскольку это название документа. Если вы хотите избежать написания с заглавной буквы, потому что это выглядит странно, вы можете заменить «Testing Handbook» на «этот справочник» (поскольку и так понятно, как называется справочник).

Рабочий процесс: из Google Docs

Вы можете экспортировать документ из Google Docs как Markdown. Откройте документ в Google Docs. Нажмите Файл > Скачать и выберите Markdown (.md).

Кастомные окружения

{{< customFigure "Caption" >}}
{{< /customFigure >}}

{{< resourceFigure "cov1.png" >}}
{{< /resourceFigure >}}

{{< hint info >}}
{{< /hint >}}