Правила Semgrep

Это центральный репозиторий правил Semgrep, в котором размещены правила Semgrep для анализатора Semgrep GitLab.

Репозиторий имеет следующую структуру:

.
├── mappings
│   ├── find_sec_bugs.yml
│   ├── eslint.yml
│   └── ...
├── rules
│   ├── lpgl
│   │   ├── java
│   │   │   ├── webview
│   │   │   │   ├── rule-ignore_ssl_certificate_error.yml
│   │   │   │   ├── rule-ignore_ssl_certificate_error.java
│   │   │   │   └── ...
│   │   │   └── ...
│   │   ├── python
│   │   │   └── ...
│   │   └── ...
│   ├── lpgl-cc
│   │   ├── java
│   │   │   └── ...
│   │   └── ...
│   └── ...
├── c
│   ├── buffer
│   │   ├── rule-strcpy.yml
│   │   ├── test-strcpy.c
│   │   ├── rule-memcpy.yml
│   │   └── test-memcpy.c
│   └── ...
└── javascript
│   └── ...
└── ...

Приведённая структура следует шаблону:

rules/<license>/<language>/<ruleclass>/rule-<rulename>\.(yml|<ext>)

где:

1. <license> — лицензия всех правил в данной папке
2. <language> — целевой язык программирования
3. <ruleclass> — описательное имя для класса правил
4. <rulename> — описательное имя для конкретного правила
5. <ext> — обычное расширение файла для <language>

Более старые правила следуют шаблону <language>/<ruleclass>/rule-..., и при возможности следует предпочитать новый шаблон, указанный выше.

Каталог mappings содержит конфигурацию пакетов правил.

Makefile

Makefile определяет несколько целей, полезных при работе с правилами:

$ make help
TARGETS:
  test                  test all rules with Semgrep
  watch                 watch for file changes and auto-run affected tests
  help                  prints this message

Рекомендации по форматированию

Правила, содержащиеся в этом репозитории, должны соответствовать следующему формату:

• Используйте " для строк, иначе используйте блок YAML literal |
• Не сворачивайте элементы массива
• Максимальная длина строки/ширина текста: 100 символов
• Отступы: 2 пробела
• Каждое правило должно иметь соответствующий тестовый пример
• Если предоставляется, раздел комментариев в верхней части файла правила
• Каждый YAML-файл начинается с ---

Сопоставления (mappings)

Каталог mappings в этом репозитории содержит YAML-файлы конфигурации, которые сопоставляют идентификаторы собственных анализаторов (например, Bandit, Brakeman и т.д.) с соответствующими правилами Semgrep.

Назначение файлов сопоставлений — в первую очередь отделить информацию, специфичную для анализатора, от самих правил, а во вторую — предоставить ненавязчивый способ генерации пакетов правил (или наборов правил) для разных целей (независимо от языка или анализатора).

Файлы сопоставлений находятся в каталоге mappings/, где имя файла указывает на пакет правил и/или анализатор, который представлен набором правил, используемых в соответствующем файле. Если вы хотите, чтобы правила были включены в стандартный набор правил GitLab, и правило не подходит ни под один из пакетов правил (или анализаторов), уже доступных в каталоге mappings/, вы можете добавить свои сопоставления в файл mappings/gitlab_<license>_<language>.yml, где <license> — подходящая лицензия, определяемая источником, из которого взято правило, а <language> — заполнитель для языка, к которому относится правило.

Если вы хотите добавить новое правило, разработанное с нуля, вы можете добавить соответствующее сопоставление в файл mappings/gitlab_ee_<language>.yml. При определении того, какая лицензия должна применяться к конкретному правилу, которое вы сопоставляете, обращайтесь к этому внутреннему руководству.

Сопоставления также используются для автоматической сборки пакетов правил. Приведённый ниже фрагмент иллюстрирует пример файлов сопоставлений для анализатора bandit. Раздел native_id содержит некоторую информацию об идентификаторе собственного анализатора, то есть метаинформацию, которую исходный анализатор (в данном случае bandit) прикрепляет к своему результату. Фактические сопоставления правил определяются в разделе mappings. Каждое сопоставление связывает идентификатор правила собственного анализатора (в примере ниже B301) с набором файлов Semgrep из этого репозитория, которые соответствуют этому конкретному собственному правилу или, в идеале, являются его де-факто эквивалентом.

bandit:
  native_id:
    type: "bandit_test_id"
    name: "Bandit Test ID: $ID"
    value: "$ID"
  mappings:
  - id: "B301"
    rules:
    - path: "python/deserialization/rule-pickle"
      primary_id: "bandit.B301-1"
      id: "bandit.B301-1"
    - path: "python/deserialization/rule-cpickle"
      primary_id: "bandit.B301-2"
      id: "bandit.B301-2"
    - path: "python/deserialization/rule-dill"
      primary_id: "bandit.B301-3"
      id: "bandit.B301-3"
    - path: "python/deserialization/rule-shelve"
      primary_id: "bandit.B301-4"
      id: "bandit.B301-4"
  # ...

Анатомия файла сопоставлений подробно описана ниже.

1. id используется для генерации стабильных и уникальных идентификаторов правил semgrep в пакете правил semgrep, соответствующем файлу сопоставления.
2. primary_id помогает генерировать стабильные первичные идентификаторы уязвимостей, которые прикрепляются к уязвимостям по мере их создания анализатором GitLab Semgrep (в gl-sast-report.json) для целей дедупликации.
3. native_id — это запись, которая в точности повторяет структуру идентификатора уязвимости, как она была бы сгенерирована собственным анализатором. Это будет добавлено в gl-sast-report.json, создаваемый анализатором GitLab Semgrep, и станет доступно в отчёте об уязвимостях.
4. mappings включает идентификатор собственного правила анализатора (в приведённом выше случае B301, который ссылается на одно из правил анализатора Python bandit). Массив rules указывает на файлы в репозитории, к которым относится это правило. Другими словами, логика B301 реализована в четырёх файлах, перечисленных в приведённом выше фрагменте.

Мы используем два разных типа идентификаторов id и primary_id для поддержки разделения правил: несколько правил semgrep (id) могут быть сопоставлены с одним правилом собственного анализатора (primary_id).

Источники данных

Правила и тестовые примеры в этом репозитории частично получены из источников, перечисленных ниже:

1. https://github.com/returntocorp/semgrep-rules
2. https://github.com/PyCQA/bandit
3. https://github.com/nodesecurity/eslint-plugin-security
4. https://github.com/jsx-eslint/eslint-plugin-react
5. https://github.com/david-a-wheeler/flawfinder/blob/master/flawfinder.py

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

Участие

Если вам известен шаблон, отсутствующий в этом репозитории, или улучшения, которые можно применить к правилам в этом репозитории, вы можете внести свой вклад, открыв issue или даже отправив улучшение файлов правил/тестовых примеров в этом репозитории.

Версионирование

К этому репозиторию применяется следующая схема семантического версионирования:

1. инкремент патч-версии: для обновлённых/исправленных/добавленных правил.
2. инкремент минорной версии: обратно совместимые изменения схемы YAML (например, добавление/удаление необязательных полей).
3. инкремент мажорной версии: несовместимые с предыдущими версиями изменения схемы YAML (например, добавление/удаление обязательных полей).

Процесс выпуска правил SAST

Новые выпуски правил SAST должны быть включены в анализатор semgrep, чтобы они вступили в силу. Чтобы запросить новый выпуск semgrep, создайте issue о выпуске, используя инструкции в шаблоне issue о выпуске SAST.

Благодарности

Мы хотели бы поблагодарить следующих авторов за их ценный вклад.