Каталог контента

Каталог — это источник истины для идентификаторов категории, модуля и темы, используемых везде в публичном API. Ищите идентификаторы здесь, прежде чем вызывать POST /assignments, строить элементы пользовательского курса или интерпретировать ответы о соответствии. Требуемая область: content:read.

Конечные точки

Метод	Путь	Область действия	Назначение
`GET`	`/api/public/v1/content/categories`	`content:read`	Все категории верхнего уровня.
`GET`	`/api/public/v1/content/categories/{'{'}categoryId{'}'}/topics`	`content:read`	Все темы внутри категории с информацией о модуле и CWE.
`GET`	`/api/public/v1/content/cwes/{'{'}cweId{'}'}/topics`	`content:read`	Разрешить id CWE в список тем, которые его покрывают.

Список категорий

Возвращает каждую видимую категорию для Вашей организации. Категории зеркалят четыре семейства OWASP, используемые в эндпоинтах соответствия — web, api, mobile, client.

GET /api/public/v1/content/categories
Authorization: Bearer scs_live_…

Ответ

{
  "count": 4,
  "categories": [
    { "categoryId": "web",    "title": "OWASP Top 10 (Web)" },
    { "categoryId": "api",    "title": "OWASP API Security Top 10" },
    { "categoryId": "mobile", "title": "OWASP Mobile Top 10" },
    { "categoryId": "client", "title": "OWASP Client-Side Top 10" }
  ]
}

Пример

curl -sS \
  -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/content/categories

Список тем в категории

Возвращает каждую тему, которая агрегируется в данную категорию, каждая аннотирована родительским модулем и набором CWE, используемым для сопоставления SARIF. Возвращает 404 category_not_found, если categoryId не один из четырёх выше.

GET /api/public/v1/content/categories/web/topics
Authorization: Bearer scs_live_…

Ответ

{
  "categoryId": "web",
  "categoryTitle": "OWASP Top 10 (Web)",
  "count": 2,
  "topics": [
    {
      "topicId": "sql-injection",
      "title": "SQL Injection",
      "moduleId": "a03-injection",
      "moduleTitle": "A03: Injection",
      "cwes": ["CWE-89"]
    },
    {
      "topicId": "xss-reflected",
      "title": "Reflected Cross-Site Scripting",
      "moduleId": "a03-injection",
      "moduleTitle": "A03: Injection",
      "cwes": ["CWE-79", "CWE-80"]
    }
  ]
}

topicId — это значение, которое Вы передаёте в POST /assignments и в элементы пользовательского курса.
moduleId совпадает с moduleId, используемым в ответах деталей фреймворка соответствия, поэтому Вы можете объединить два эндпоинта на стороне клиента.
moduleTitle может быть null для тем, которые не сгруппированы под модулем OWASP (редко; зарезервировано для специального контента).

Пример

curl -sS \
  -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/content/categories/api/topics

Разрешить CWE в темы

Учитывая идентификатор CWE, возвращает каждую тему, которая его покрывает. Это тот же поиск, который приём SARIF использует внутренне — вызывайте его напрямую, когда хотите сопоставить находку с обучением без приёма полного отчёта.

GET /api/public/v1/content/cwes/CWE-89/topics
Authorization: Bearer scs_live_…

Принимаемые форматы CWE

Сегмент пути {'{'}cweId{'}'} нормализуется на стороне сервера. Все следующие разрешаются идентично:

89
cwe-89
CWE-89
external/cwe/cwe-89

Поле cwe ответа всегда отражает нормализованную каноническую форму (CWE-89). Неизвестные CWE возвращают 200 с count: 0 и пустым массивом topics — а не 404 — поэтому клиенту не нужно специально обрабатывать несопоставленные ID.

Ответ

{
  "cwe": "CWE-89",
  "count": 1,
  "topics": [
    {
      "topicId": "sql-injection",
      "title": "SQL Injection",
      "moduleId": "a03-injection",
      "moduleTitle": "A03: Injection",
      "categoryId": "web",
      "categoryTitle": "OWASP Top 10 (Web)"
    }
  ]
}

Пример

curl -sS \
  -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/content/cwes/external/cwe/cwe-79/topics

Стабильность идентификаторов

Идентификаторы категории, модуля и темы — это стабильные строки — они не изменятся после публикации. Новые темы могут быть добавлены под существующими модулями, и новые модули под существующими категориями, но переименований избегают, чтобы держать интеграции устойчивыми. Если тема когда-либо отменяется, идентификатор сохраняется, и тема скрывается из каталога, а не переиспользуется.