DevSecOps Toolchain Map

---

Салют 👋,

MkDocs Material - фреймворк для создания документации, работающий в связке со статическим генератором сайтов MkDocs.

Лицензия MCDocs Material: MIT License.

Карта дает возможность выбрать выгодные для себя инструменты под все необходимые ситуации: когда нет денег, когда не можем интегрировать большой инструмент, когда никого нет и приходится делать все одному и тд.

Отмечу основные моменты:

• Карта инструментов показывает какие есть классы и типы инструментов
• Карта является прототипом и находится на стадии доработки
• Предыдущая версия карты находится тут
• Агрегируются 'meta' данные о наличии сертификации, типе лицензии ПО, может ли быть импортозамещено, какой язык программирования, какие виды отчетов и иное
• вся верстка натянута на 'material'
• Мы принимаем 'pull requeste' на изменения для того, что бы эта карта шарилась и мы могли работать в едином поле с комьюнити
• Имеется фильтрация по 'meta' данным
• Убрали некоторые инструменты, которые не поддерживаются или пользуются меньшей популярностью, вследствие чего они не обновляются
• Актуализировали списки инструментов, на сейчас готовятся правки по ткстам и добавление материалов описания

---

Структура репозитория

├── __pycache__
│   └── main.cpython-314.pyc
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── docs
│   ├── about.md
│   ├── appsec_tt.md
│   ├── assets
│   │   ├── logotype
│   │   │   ├── logotypemd.jpg
│   │   │   └── site
│   │   │       ├── favicon.ico
│   │   │       ├── LANIT_logo.png
│   │   │       ├── logo_pdf.png
│   │   │       └── logo.png
│   │   └── search
│   │       └── tools.json
│   ├── codeofconduct.md
│   ├── index.md
│   ├── javascripts
│   │   ├── custom-title.js
│   │   ├── menu-logo.js
│   │   ├── tools-interpretator.js
│   │   ├── tools-overlay.js
│   │   ├── tools-search_pagging.js
│   │   ├── tools-search_style.js
│   │   ├── tools-search.js
│   │   ├── tools-table.js
│   │   └── typewriter-target.js
│   ├── licenses.md
│   ├── liders.md
│   ├── map.md
│   ├── materials_iso.md
│   ├── OSS.md
│   ├── pdf_table
│   │   └── tools-map.pdf
│   ├── release-notes.md
│   ├── rules.md
│   ├── search.md
│   ├── stylesheets
│   │   ├── burger.css
│   │   ├── clipboard.css
│   │   ├── footer.css
│   │   ├── header.css
│   │   ├── layout.css
│   │   ├── menu.css
│   │   ├── mobile-heder.css
│   │   ├── mobile-logo.css
│   │   ├── search.css
│   │   ├── sidebar.css
│   │   ├── tools-overlay.css
│   │   ├── tools-pdf.css
│   │   ├── tools-table.css
│   │   └── typeset.css
│   ├── toolchain_map.md
│   ├── tools
│   │   ├── AppSec
│   │   │   ├── API
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── Attack_Surface_Analysis
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── BCA
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── DAST
│   │   │   │   ├── DAST
│   │   │   │   │   ├── OSS_tools.yaml
│   │   │   │   │   └── PS_tools.yaml
│   │   │   │   └── Whitbox_fuzzing
│   │   │   │       ├── OSS_tools.yaml
│   │   │   │       └── PS_tools.yaml
│   │   │   ├── IAST
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── MAST
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── RASP
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   ├── SAST
│   │   │   │   ├── OSS_tools.yaml
│   │   │   │   └── PS_tools.yaml
│   │   │   └── SCA_OSA
│   │   │       ├── Analizator
│   │   │       │   ├── OSS_tools.yaml
│   │   │       │   └── PS_tools.yaml
│   │   │       └── SBOM
│   │   │           ├── OSS_tools.yaml
│   │   │           └── PS_tools.yaml
│   │   ├── ASPM
│   │   │   ├── OSS_tools.yaml
│   │   │   └── PS_tools.yaml
│   │   ├── codecoverage
│   │   │   ├── OSS_tools.yaml
│   │   │   └── PS_tools.yaml
│   │   ├── Container_Security
│   │   │   ├── OSS_tools.yaml
│   │   │   └── PS_tools.yaml
│   │   ├── MLSecOps
│   │   │   ├── OSS_tools.yaml
│   │   │   └── PS_tools.yaml
│   │   └── Secrets_Management
│   │       ├── OSS_tools.yaml
│   │       └── PS_tools.yaml
│   ├── vendor_external.md
│   └── vendor_rf.md
├── eslint.config.js
├── LICENSE.md
├── main.py
├── mkdocs.yml
├── mypy.ini
├── NOTICE.md
├── README.md
├── RELEASE_NOTES.md
├── requirements.txt
├── ruff.toml
├── scripts
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── __init__.cpython-314.pyc
│   │   ├── build_search_data.cpython-314.pyc
│   │   ├── export_tools_pdf.cpython-314.pyc
│   │   ├── render_tools_popups_from_table.cpython-314.pyc
│   │   ├── render_tools_with_popups.cpython-314.pyc
│   │   ├── table_data.cpython-314.pyc
│   │   └── table_render.cpython-314.pyc
│   ├── build_search_data.py
│   ├── export_tools_pdf.py
│   ├── render_tools_popups_from_table.py
│   ├── table_data.py
│   └── table_render.py
├── SECURITY.md
└── stylelint.config.cjs

---

Tutorial

• Подготовка окружения

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt
$ python scripts/build_search_data.py
$ python -m mkdocs build -v > build.log 2>&1 # debug
$ python -m mkdocs serve --livereload
# or
$ mkdocs serve -a 127.0.0.1:8001 # прямое обозначение адреса

• Генерация карты в PDF

$ python -m scripts.export_tools_pdf

• Очистка локального репозитория

$ rm -rf __pycache__ scripts/__pycache__  # etc.
$ lsof -i :8000
$ kill <PID>

• Release

$ git tag -a v1.0.0 -m “Основные изменения: …” 
$ git push origin v1.0.0

# Альтернатива для использования - это RELEASE_NOTES
$ git tag -a v1.0.0 -m "v1.0.0"
$ git add "Release Notes.md" && git commit -m "Update notes for v1.0.0" 

$ git tag -a v1.1.0 -m "v1.1.0" # текущий релиз
$ git push origin v1.1.0
$ git tag -d v0.1.0 # удалить локальный тег
$ git push origin :refs/tags/v0.1.0 # удалить тот же тег на GitHub

• Локальное тестирование ci.yml

$ act -l
$ act -j имя_job #  или общий act push
$ act push -b -v

$ act push -j build -b
$ act pull_request -j ххх # конкретный job
$ act pull_request -j docs-preview -b # docs-preview и все зависимые job

• Тестирование

$ abandit -r labs
$ aruff check .

$ anpx eslint "docs/**/*.js" "javascripts/**/*.js"
npx stylelint "docs/**/*.css" "stylesheets/**/*.css"

$ agit ls-files '*.sh' \
  | grep -v 'labs/lab08/dast/zap_scan.sh' \
  | grep -v 'labs/lab07/sca/dependency-check.sh' \
  | grep -v 'labs/lab06/audit.sh' \
  | xargs -r shellcheck -e SC2086,SC1090,SC1091

$ ayamllint .github/workflows mkdocs.yml
$ anpx markdownlint-cli2 "docs/**/*.md" "labs/**/*.md" "README.md"

$ mkdocs build --strict --clean --config-file mkdocs.yml --site-dir /tmp/mkdocs-check

---

Troubleshoot

• "GET /.well-known/appspecific/com.chrome.devtools.json HTTP/1.1" code 404 игнорируем
• flake 8:
  • E501: разбить длинные строки
  • E302/E305: перед каждой функцией/классом – две пустые строки; после определения функций/классов – тоже нужное число пустых строк.
  • W292: добавить перевод строки в конец файла.
  • E203: убрать пробел перед двоеточием в срезах/аннотациях.

---

CI/CD

• Для PR‑ов будет собираться сайт и прикрепляться как артефакт  site-preview
• job build:
  • собирает search JSON: python scripts/build_search_data.py
  • mkdocs build — в раннере создаёт артефакт сборки site
  • upload-pages-artifact упаковывает
• job deploy:
  • actions/deploy-pages разворачивает артефакт на GitHub Pages
• site только в раннере
• при каждом push в master GitHub:
  • запустит workflow ci
  • соберёт site;
  • задеплоит на Pages через Actions
  • ставит зависимости из requirements.txt
  • прогоняет ruff (линтинг)
  • прогоняет bandit
  • билдит search data
  • билдит mkdocs
  • проверяет ссылки в сгенерированном сайте (lychee)
  • сохраняет сайт как артефакт для Pages
  • отдельный job deploy GitHub Pages только push (не при PR)
• release:
  • собрать MkDocs
  • упаковать site в ZIP
  • создать GitHub Release

---

Copyright (c) 2025 Elijah S Shmakov