Сценарий 21: Структурный поиск шаблонов

Сценарий 21: Структурный поиск шаблонов

Разработчик или инженер по безопасности ищет код, соответствующий структурным шаблонам с CPG-ограничениями.

Быстрый старт

/select pattern_search

Или через CLI:

# Ad-hoc поиск шаблона
python -m src.cli patterns search "malloc($x)" --lang c

# Сканирование по всем правилам
python -m src.cli patterns scan

# Сканирование по конкретному правилу
python -m src.cli patterns scan --rule unchecked-return

Обзор

Структурный поиск шаблонов использует CST-парсинг tree-sitter в сочетании с CPG-ограничениями (поток данных, граф вызовов, типы, доменные аннотации) для поиска кода, соответствующего сложным шаблонам. В отличие от regex-поиска, он понимает структуру кода и может находить совпадения через границы AST.

Типы шаблонов

Синтаксические шаблоны

CST-шаблоны tree-sitter с метапеременными:

Метапеременная Что соответствует
$VAR Любое выражение или идентификатор
$$ARGS Ноль или более аргументов
$_ Любой узел (подстановка) 
# Найти вызовы malloc
python -m src.cli patterns search "malloc($x)" --lang c

# Найти if-return без else
python -m src.cli patterns search "if ($cond) { return $val; }" --lang c

Шаблоны с CPG-ограничениями

Шаблоны с ограничениями на поток данных, граф вызовов, типы и домен:

id: unchecked-return
pattern: "$ret = $func($$args)"
language: c
constraints:
  - type: data_flow
    from: "$ret"
    not_reaches: "if ($ret"
  - type: call_graph
    callee: "$func"
    returns: "int"
message: "Возвращаемое значение $func не проверяется"
severity: warning

YAML-правила

Предопределённые правила в configs/rules/ — 190 правил для 14 языков.

# Список всех доступных правил
python -m src.cli patterns list

# Статистика правил
python -m src.cli patterns stats

Примеры запросов

Найти непроверенные возвращаемые значения
Найти malloc без free
Показать функции с антишаблонами обработки ошибок
Найти конструирование SQL-запросов без параметризации
Найти все функции с цикломатической сложностью >20

Использование

CLI

# Поиск по шаблону
python -m src.cli patterns search "malloc($x)" --lang c --max-results 50

# Сканирование по всем правилам
python -m src.cli patterns scan --db data/projects/postgres.duckdb

# Сканирование по уровню серьёзности
python -m src.cli patterns scan --severity error

# Генерация правила из описания на естественном языке
python -m src.cli patterns generate "найти непроверенные возвращаемые значения" --lang c --output rule.yaml

# Валидация правила
gocpg validate-rule --file rule.yaml

# Автоисправление (предпросмотр)
python -m src.cli patterns fix --dry-run

# Автоисправление (применение)
python -m src.cli patterns fix --rule unchecked-return

Программное использование

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Найти непроверенные возвращаемые значения", scenario="pattern_search")

for finding in result.get('findings', []):
    print(f"{finding['rule_id']}: {finding['file']}:{finding['line']}")
    print(f"  {finding['message']}")

API

# Поиск шаблонов
POST /api/v1/patterns/search
{
  "pattern": "malloc($x)",
  "language": "c",
  "max_results": 50
}

# Получить результаты по правилу
POST /api/v1/patterns/findings
{
  "rule_id": "unchecked-return"
}

# Сгенерировать правило по описанию
POST /api/v1/patterns/generate
{
  "description": "найти непроверенные возвращаемые значения",
  "language": "c"
}

MCP

Доступно как MCP-инструменты: codegraph_pattern_search, codegraph_pattern_findings, codegraph_pattern_stats, codegraph_pattern_fix, codegraph_pattern_generate, codegraph_pattern_test.

Связанное