local-triage 0.0.0-stage → 0.10.0-dev.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (223) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +90 -2
  3. package/THIRD-PARTY-NOTICES.md +48 -0
  4. package/app/__init__.py +3 -0
  5. package/app/affiliation.py +137 -0
  6. package/app/ask.py +300 -0
  7. package/app/build_info.py +98 -0
  8. package/app/capec.py +168 -0
  9. package/app/capec_view.py +27 -0
  10. package/app/codecmp.py +59 -0
  11. package/app/config.py +411 -0
  12. package/app/context.py +1451 -0
  13. package/app/cvss.py +357 -0
  14. package/app/db.py +6234 -0
  15. package/app/defect.py +670 -0
  16. package/app/defect_check.py +323 -0
  17. package/app/defect_drafts.py +612 -0
  18. package/app/defect_dto.py +149 -0
  19. package/app/defect_fields.py +248 -0
  20. package/app/defect_form.py +124 -0
  21. package/app/defect_links.py +107 -0
  22. package/app/defect_local_text.py +103 -0
  23. package/app/defect_references.py +164 -0
  24. package/app/defect_where.py +147 -0
  25. package/app/ecosystem.py +51 -0
  26. package/app/executors.py +660 -0
  27. package/app/feeds.py +1231 -0
  28. package/app/guard.py +164 -0
  29. package/app/hub_block_builder.py +200 -0
  30. package/app/hub_block_version.py +220 -0
  31. package/app/hub_defects.py +4469 -0
  32. package/app/hub_effects.py +421 -0
  33. package/app/hub_entity_versions.py +108 -0
  34. package/app/hub_import.py +2054 -0
  35. package/app/hub_onboarding.py +114 -0
  36. package/app/hub_ops.py +330 -0
  37. package/app/hub_pull.py +1195 -0
  38. package/app/hub_state.py +255 -0
  39. package/app/hub_status.py +237 -0
  40. package/app/hub_sync.py +619 -0
  41. package/app/hub_sync_api.py +241 -0
  42. package/app/hub_sync_compare.py +1054 -0
  43. package/app/hub_sync_contract.py +75 -0
  44. package/app/hub_template_model.py +74 -0
  45. package/app/hub_text_scale.py +159 -0
  46. package/app/journal.py +250 -0
  47. package/app/llm.py +850 -0
  48. package/app/llm_chat.py +596 -0
  49. package/app/llm_http.py +319 -0
  50. package/app/llm_messages.py +401 -0
  51. package/app/llm_net.py +764 -0
  52. package/app/llm_ollama.py +571 -0
  53. package/app/lockfile.py +505 -0
  54. package/app/logsafe.py +54 -0
  55. package/app/main.py +367 -0
  56. package/app/mask_display.py +132 -0
  57. package/app/masking.py +814 -0
  58. package/app/metrics.py +194 -0
  59. package/app/model_traffic.py +519 -0
  60. package/app/models.py +483 -0
  61. package/app/navigation.py +121 -0
  62. package/app/osv.py +279 -0
  63. package/app/package_identity.py +189 -0
  64. package/app/package_transition.py +824 -0
  65. package/app/profile_gate.py +71 -0
  66. package/app/prompts.py +1108 -0
  67. package/app/provider_keys.py +189 -0
  68. package/app/providers.py +511 -0
  69. package/app/routes/__init__.py +10 -0
  70. package/app/routes/api.py +153 -0
  71. package/app/routes/capec.py +186 -0
  72. package/app/routes/common.py +407 -0
  73. package/app/routes/components.py +1499 -0
  74. package/app/routes/cwe.py +168 -0
  75. package/app/routes/decision_selected.py +153 -0
  76. package/app/routes/defect_add.py +223 -0
  77. package/app/routes/defect_card_routes.py +363 -0
  78. package/app/routes/defect_selected.py +342 -0
  79. package/app/routes/feeds.py +155 -0
  80. package/app/routes/findings.py +2736 -0
  81. package/app/routes/hub.py +402 -0
  82. package/app/routes/hub_bulk.py +288 -0
  83. package/app/routes/hub_defect_routes.py +1945 -0
  84. package/app/routes/hub_status_routes.py +1132 -0
  85. package/app/routes/hub_sync_routes.py +463 -0
  86. package/app/routes/journal.py +132 -0
  87. package/app/routes/projects.py +1601 -0
  88. package/app/routes/providers.py +336 -0
  89. package/app/routes/references.py +26 -0
  90. package/app/routes/runs.py +219 -0
  91. package/app/routes/sca.py +2722 -0
  92. package/app/routes/settings.py +163 -0
  93. package/app/run_errors.py +151 -0
  94. package/app/sca.py +1662 -0
  95. package/app/sca_contract.py +1289 -0
  96. package/app/sca_research.py +1089 -0
  97. package/app/sca_research_net.py +1007 -0
  98. package/app/sca_text.py +965 -0
  99. package/app/serve.py +70 -0
  100. package/app/settings_store.py +262 -0
  101. package/app/static/app.css +2802 -0
  102. package/app/static/app.js +3772 -0
  103. package/app/static/capec-license.txt +9 -0
  104. package/app/static/favicon.svg +1 -0
  105. package/app/static/fonts/Golos-Text_DemiBold.woff2 +0 -0
  106. package/app/static/fonts/Golos-Text_Regular.woff2 +0 -0
  107. package/app/static/fonts/OFL.txt +90 -0
  108. package/app/static/navigation.js +234 -0
  109. package/app/static/observability.js +121 -0
  110. package/app/static/theme.js +49 -0
  111. package/app/storage/__init__.py +16 -0
  112. package/app/storage/local_state.py +246 -0
  113. package/app/storage/migrate.py +110 -0
  114. package/app/storage/migrations/postgresql/0001_baseline.sql +896 -0
  115. package/app/storage/migrations/postgresql/0002_feeds_and_secrets.sql +55 -0
  116. package/app/storage/migrations/postgresql/0003_project_mask_display.sql +5 -0
  117. package/app/storage/migrations/postgresql/0004_package_identity.sql +36 -0
  118. package/app/storage/postgresql.py +573 -0
  119. package/app/storage/schema.py +619 -0
  120. package/app/storage/sql.py +57 -0
  121. package/app/storage/tools.py +254 -0
  122. package/app/telemetry.py +307 -0
  123. package/app/templates/base.html +91 -0
  124. package/app/templates/capec/context.html +3 -0
  125. package/app/templates/capec/detail.html +27 -0
  126. package/app/templates/capec/index.html +128 -0
  127. package/app/templates/components/_archive.html +11 -0
  128. package/app/templates/components/archived.html +19 -0
  129. package/app/templates/components/batch.html +35 -0
  130. package/app/templates/components/detail.html +332 -0
  131. package/app/templates/components/index.html +338 -0
  132. package/app/templates/components/research_preview.html +80 -0
  133. package/app/templates/components/research_run.html +54 -0
  134. package/app/templates/cwe/bdu.html +56 -0
  135. package/app/templates/cwe/detail.html +233 -0
  136. package/app/templates/cwe/index.html +97 -0
  137. package/app/templates/error.html +8 -0
  138. package/app/templates/feeds/index.html +65 -0
  139. package/app/templates/findings/card.html +639 -0
  140. package/app/templates/findings/decision_selected.html +41 -0
  141. package/app/templates/findings/defect_add.html +46 -0
  142. package/app/templates/findings/defect_selected.html +47 -0
  143. package/app/templates/findings/list.html +153 -0
  144. package/app/templates/findings/send_selected.html +53 -0
  145. package/app/templates/findings/trace.html +72 -0
  146. package/app/templates/journal/detail.html +19 -0
  147. package/app/templates/journal/index.html +19 -0
  148. package/app/templates/macros.html +440 -0
  149. package/app/templates/navigation-fields.html +1 -0
  150. package/app/templates/navigation.html +11 -0
  151. package/app/templates/projects/_identity_summary.html +42 -0
  152. package/app/templates/projects/defect_card.html +153 -0
  153. package/app/templates/projects/defect_create_preview.html +17 -0
  154. package/app/templates/projects/defect_fields_diff.html +6 -0
  155. package/app/templates/projects/defect_fields_form.html +40 -0
  156. package/app/templates/projects/defect_references.html +17 -0
  157. package/app/templates/projects/defect_sync_preview.html +28 -0
  158. package/app/templates/projects/defect_update_actions.html +6 -0
  159. package/app/templates/projects/defect_update_preview.html +24 -0
  160. package/app/templates/projects/defects.html +126 -0
  161. package/app/templates/projects/delete.html +31 -0
  162. package/app/templates/projects/external.html +61 -0
  163. package/app/templates/projects/folders.html +64 -0
  164. package/app/templates/projects/hub_accepted.html +10 -0
  165. package/app/templates/projects/hub_assignment.html +50 -0
  166. package/app/templates/projects/hub_pending.html +20 -0
  167. package/app/templates/projects/hub_pending_list.html +17 -0
  168. package/app/templates/projects/hub_state_note.html +23 -0
  169. package/app/templates/projects/hub_step_note.html +5 -0
  170. package/app/templates/projects/hub_sync.html +105 -0
  171. package/app/templates/projects/hub_sync_confirm.html +32 -0
  172. package/app/templates/projects/hub_sync_worker.html +5 -0
  173. package/app/templates/projects/hub_text_rules.html +64 -0
  174. package/app/templates/projects/identity_report.html +74 -0
  175. package/app/templates/projects/list.html +90 -0
  176. package/app/templates/projects/project.html +433 -0
  177. package/app/templates/reference-missing.html +14 -0
  178. package/app/templates/runs/run.html +166 -0
  179. package/app/templates/sca/card.html +476 -0
  180. package/app/templates/sca/index.html +321 -0
  181. package/app/templates/settings/hub_url.html +31 -0
  182. package/app/templates/settings/index.html +216 -0
  183. package/app/templates/settings/provider.html +229 -0
  184. package/app/templates/settings/providers.html +37 -0
  185. package/app/templates/worklists.html +52 -0
  186. package/app/textsafe.py +117 -0
  187. package/app/timing.py +245 -0
  188. package/app/triage.py +1743 -0
  189. package/app/view.py +430 -0
  190. package/app/worklists.py +204 -0
  191. package/examples/demo/demo-hub-report-v2.xlsx +0 -0
  192. package/examples/demo/demo-hub-report.xlsx +0 -0
  193. package/examples/demo/repos/billing-core/pom.xml +30 -0
  194. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/Invoice.java +9 -0
  195. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/InvoiceRepository.java +51 -0
  196. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/InvoiceStatus.java +11 -0
  197. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/config/DatabaseSettings.java +18 -0
  198. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/payment/PaymentTokenService.java +35 -0
  199. package/examples/demo/repos/billing-core/src/main/java/org/example/billing/web/InvoiceExportController.java +57 -0
  200. package/examples/demo/repos/catalog-api/catalog_api/__init__.py +1 -0
  201. package/examples/demo/repos/catalog-api/catalog_api/products.py +24 -0
  202. package/examples/demo/repos/catalog-api/catalog_api/tasks.py +24 -0
  203. package/examples/demo/repos/catalog-api/catalog_api/views.py +17 -0
  204. package/examples/demo/repos/catalog-api/requirements.txt +3 -0
  205. package/npm/build.json +5 -0
  206. package/npm/cli.js +346 -0
  207. package/npm/files.manifest +224 -0
  208. package/npm/lib/binding.js +64 -0
  209. package/npm/lib/cluster.js +330 -0
  210. package/npm/lib/env.js +88 -0
  211. package/npm/lib/fsx.js +125 -0
  212. package/npm/lib/http.js +53 -0
  213. package/npm/lib/metrics.js +73 -0
  214. package/npm/lib/paths.js +150 -0
  215. package/npm/lib/pg.js +351 -0
  216. package/npm/lib/proc.js +101 -0
  217. package/npm/lib/python.js +133 -0
  218. package/npm/lib/stand.js +46 -0
  219. package/npm/lib/supervisor.js +1141 -0
  220. package/npm/lib/version.js +21 -0
  221. package/npm/requirements.txt +476 -0
  222. package/npm-shrinkwrap.json +111 -0
  223. package/package.json +37 -4
@@ -0,0 +1,1289 @@
1
+ """Контракт ответа агента по исследованию компонентов SCA, версия 2.
2
+
3
+ Один модуль обслуживает и приложение, и внешнего агента: из одного описания полей собираются и JSON Schema
4
+ для агента, и все проверки приложения, поэтому описание и проверки разойтись не могут. Только стандартная
5
+ библиотека Python 3.11: этот же файл без изменений копируется в комплект задания как validate.py и запускается
6
+ агентом отдельно от приложения, поэтому импортировать app.* здесь нельзя.
7
+
8
+ Что проверяется и с какой строгстью: значения и перечисления, лишние и пропущенные поля, полный набор строк
9
+ задания без пропусков и дублей, неизменность входных координат, несуществующие ссылки на доказательства,
10
+ будущие даты, внутренние номера AST, пределы объёма (отказ с кодом, без обрезки) и очевидные противоречия
11
+ между полями. Состояние пакета не принимается на веру: оно вычисляется по проверенным полям, и заявленный
12
+ агентом статус должен совпасть с вычисленным.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import json
19
+ import math
20
+ import re
21
+ import sys
22
+ from collections.abc import Iterable, Mapping
23
+ from dataclasses import dataclass, field as dc_field
24
+ from datetime import date, datetime, timedelta
25
+ from hashlib import sha256 as _sha256
26
+ from pathlib import Path
27
+ from typing import Any
28
+ from urllib.parse import urlsplit
29
+
30
+ # ------------------------------------------------------------------ контракт и пределы
31
+
32
+ ANSWER_CONTRACT = "local-triage/sca-answers/2"
33
+ TASK_CONTRACT = "local-triage/sca-task/2"
34
+ REPORT_CONTRACT = "local-triage/sca-report/2"
35
+ # 2.1.1 – явный диапазон «от начала без верхней границы» (introduced="0", без fixed и last_affected) затрагивает все
36
+ # версии, а не «порядок не проверен»; схема ответа та же, что у 2.1.0
37
+ VALIDATOR_VERSION = "sca-contract/2.1.1"
38
+ ACCEPTED_VALIDATORS = (VALIDATOR_VERSION, "sca-contract/2.1.0", "sca-contract/2.0.2", "sca-contract/2.0.1")
39
+ # версии схемы ответа, в которых допустимы расширения 2.1 (ADR-0094): проверка версий Hub и цели, статус
40
+ # исправления, оспоренность и позиции источников
41
+ EXTENSION_VALIDATORS = ("sca-contract/2.1.0", VALIDATOR_VERSION)
42
+ EXTENSION_FIELDS = ("version_checks", "fix_status", "disputed", "source_positions")
43
+
44
+ # Пределы объёма. Обновление ответов первой версии заканчивалось десятью ссылками на компонент, поэтому здесь
45
+ # запас на десятки публичных уязвимостей и доказательств. Пределы публикуются в manifest и в схеме ответа:
46
+ # агент узнаёт о них до работы, а отказ приходит с кодом и без обрезки.
47
+ LIMITS: dict[str, int] = {
48
+ "answer_bytes": 16 * 1024 * 1024,
49
+ "row_bytes": 512 * 1024,
50
+ "max_rows": 5000,
51
+ "findings_per_row": 500,
52
+ "evidence_per_row": 128,
53
+ "coverage_per_row": 64,
54
+ "gaps_per_row": 32,
55
+ "aliases_per_finding": 64,
56
+ "ranges_per_finding": 32,
57
+ "fixed_versions_per_finding": 32,
58
+ "source_refs": 128,
59
+ "candidates_per_row": 32,
60
+ "id_chars": 64,
61
+ "version_chars": 64,
62
+ "url_chars": 1000,
63
+ "text_chars": 4000,
64
+ "note_chars": 2000,
65
+ "quote_chars": 4000,
66
+ "source_chars": 120,
67
+ "version_checks_per_row": 8,
68
+ "positions_per_finding": 8,
69
+ "depth": 12,
70
+ # больше этого числа ошибок в отчёте не показываем, но обязательно говорим, что список неполный
71
+ "reported_errors": 200,
72
+ }
73
+
74
+ IDENTITY_STATES = ("resolved", "ambiguous", "unresolved", "unknown")
75
+ UPDATE_STATUSES = ("up_to_date", "update_available", "unknown")
76
+ SUPPORT_STATES = ("supported", "maintenance", "eol", "deprecated", "archived", "unknown")
77
+ SUPPORT_SCOPES = ("oss", "commercial", "unknown")
78
+ APPLIES_VALUES = ("yes", "no", "unknown")
79
+ COVERAGE_STATUSES = ("ok", "partial", "error")
80
+ EVIDENCE_SOURCES = ("registry", "advisory", "release_notes", "policy", "aggregator", "issue_tracker", "other")
81
+ EVIDENCE_LEVELS = ("primary", "corroborated", "single_source", "unconfirmed")
82
+ ADVICE_ACTIONS = ("update", "replace", "keep", "remove", "accept_risk", "needs_identity", "no_action",
83
+ "insufficient_data")
84
+ PACKAGE_STATUSES = ("vulnerable", "no_known_vulnerabilities", "incomplete", "identity_unresolved")
85
+ GAP_CODES = ("IDENTITY_AMBIGUOUS", "IDENTITY_UNRESOLVED", "VERSION_UNKNOWN", "RELEASE_UNKNOWN", "COVERAGE_INCOMPLETE",
86
+ "SOURCE_UNAVAILABLE", "SOURCE_BLOCKED", "NO_PUBLIC_FIX", "FIX_UNCONFIRMED", "APPLICABILITY_UNCLEAR",
87
+ "LICENSE_UNKNOWN", "SUPPORT_UNKNOWN", "NOT_RESEARCHED", "OTHER")
88
+
89
+ # Дата проверки источника не может быть в будущем: источника с таким ответом ещё не существует.
90
+ # Допуск в сутки – на разницу часовых поясов у агента и у этого компьютера.
91
+ FUTURE_TOLERANCE_DAYS = 1
92
+ # Источники, где ищут уязвимости, определяются не названием, а целью проверки: официальный бюллетень проекта
93
+ # годится, а проверка метаданных публикации в реестре – нет. Поэтому запись охвата объявляет, зачем её делали.
94
+ # Обе формы названия цели принимаются (релиз/release), важна не форма, а смысл.
95
+ COVERAGE_PURPOSES = ("vulnerabilities", "releases", "release", "support", "identity", "licenses", "license",
96
+ "other")
97
+ # Номера AST-соответствий внутренние: в публичном ответе по компоненту им не место (AGENTS.md).
98
+ _AST = re.compile(r"(?i)\bast[-\u2013]?[0-9]{4}[-\u2013]?[0-9]{3,}")
99
+ _REF_PREFIX = re.compile(r"^[a-z][a-z0-9]*$")
100
+ _SHA = re.compile(r"^[0-9a-f]{64}$")
101
+
102
+
103
+ # ------------------------------------------------------------------ вспомогательное
104
+
105
+ def canonical(obj: Any) -> bytes:
106
+ """Один канонический вид JSON: UTF-8, ключи по алфавиту, без пробелов. По нему считаются отпечатки,
107
+ поэтому и манифест, и ответ агента канонизируются одинаково."""
108
+ return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
109
+ allow_nan=False).encode("utf-8")
110
+
111
+
112
+ def sha256(data: bytes | str) -> str:
113
+ """Отпечаток SHA-256 в нижнем регистре: тот же для байтов и для текста в UTF-8."""
114
+ return _sha256(data.encode("utf-8") if isinstance(data, str) else data).hexdigest()
115
+
116
+
117
+ def input_ref(ecosystem: str, name: str, version: str) -> str:
118
+ """Устойчивый ключ входной строки: экосистема, исходное имя и исходная версия. Подтверждённая агентом
119
+ координата ключ не меняет (ecosystem:name@version)."""
120
+ digest = sha256(canonical([str(ecosystem or ""), str(name or ""), str(version or "")]))
121
+ prefix = str(ecosystem or "").casefold()
122
+ prefix = prefix if _REF_PREFIX.match(prefix) else "unk"
123
+ return f"{prefix}:{digest[:16]}"
124
+
125
+
126
+ def row_status(row: Mapping[str, Any]) -> str:
127
+ """Состояние пакета по проверенным полям, а не по заявлению агента: неподтверждённая идентичность, затем
128
+ применимые находки, затем полнота охвата. Пустой результат при ошибке источника чистым не считается."""
129
+ identity = _obj(row.get("identity_resolution"))
130
+ state = _text(identity.get("state"))
131
+ if state not in ("resolved", "unknown"):
132
+ return "identity_unresolved"
133
+ if state == "unknown" or not _text(identity.get("coordinates")):
134
+ return "incomplete" # идентичность ещё не определяли – это неполнота исследования, а не вывод о пакете
135
+ findings = [_obj(item) for item in _list(row.get("public_findings"))]
136
+ if any(item.get("applies") == "yes" for item in findings):
137
+ return "vulnerable"
138
+ if any(item.get("applies") == "unknown" for item in findings):
139
+ return "incomplete" # применимость не выяснена: чистым результат не может быть
140
+ coverage = [_obj(item) for item in _list(row.get("research_coverage"))]
141
+ checked = [item for item in coverage if _text(item.get("purpose")) == "vulnerabilities"]
142
+ if not checked:
143
+ return "incomplete" # проверяли публикацию пакета или поддержку, а уязвимости по нему не искали
144
+ if any(item.get("status") != "ok" or not item.get("complete") for item in checked):
145
+ return "incomplete"
146
+ # сорванный поиск релизов или политики поддержки не отменяет удавшийся поиск уязвимостей: это пробел,
147
+ # а не провал проверки, о которой спрашивает состояние
148
+ return "no_known_vulnerabilities"
149
+
150
+
151
+ def _obj(value: Any) -> dict:
152
+ return value if isinstance(value, dict) else {}
153
+
154
+
155
+ def _list(value: Any) -> list:
156
+ return value if isinstance(value, list) else []
157
+
158
+
159
+ def _text(value: Any) -> str:
160
+ return value.strip() if isinstance(value, str) else ""
161
+
162
+
163
+ # ------------------------------------------------------------------ описание полей
164
+
165
+ class Field:
166
+ """Одно поле контракта: тип, границы, перечисление, шаблон, необязательность. Из него и JSON Schema,
167
+ и проверка значения, поэтому лишнее поле или неверный тип нельзя пропустить незаметно."""
168
+
169
+ __slots__ = ("kind", "fields", "item", "enum", "min_chars", "max_chars", "pattern", "fmt", "minimum",
170
+ "maximum", "min_items", "max_items", "unique_key", "unique_code", "nullable", "required")
171
+
172
+ def __init__(self, kind: str, *, fields: Mapping[str, "Field"] | None = None, item: "Field | None" = None,
173
+ enum: Iterable[str] | None = None, min_chars: int | None = None, max_chars: int | None = None,
174
+ pattern: str | None = None, fmt: str | None = None, minimum: float | None = None,
175
+ maximum: float | None = None, min_items: int | None = None, max_items: int | None = None,
176
+ unique_key: str | tuple[str, ...] | None = None, unique_code: str = "SCA-M005", nullable: bool = False,
177
+ required: bool = True):
178
+ self.kind = kind
179
+ self.fields = dict(fields or {})
180
+ self.item = item
181
+ self.enum = tuple(enum) if enum else None
182
+ self.min_chars = min_chars
183
+ self.max_chars = max_chars
184
+ self.pattern = pattern
185
+ self.fmt = fmt
186
+ self.minimum = minimum
187
+ self.maximum = maximum
188
+ self.min_items = min_items
189
+ self.max_items = max_items
190
+ self.unique_key = unique_key
191
+ self.unique_code = unique_code
192
+ self.nullable = nullable
193
+ self.required = required
194
+
195
+ def schema(self) -> dict:
196
+ if self.kind == "object":
197
+ out: dict[str, Any] = {"type": "object", "additionalProperties": False,
198
+ "required": [name for name, item in self.fields.items() if item.required],
199
+ "properties": {name: item.schema() for name, item in self.fields.items()}}
200
+ elif self.kind == "array":
201
+ out = {"type": "array", "items": (self.item or Field("string")).schema()}
202
+ if self.min_items is not None:
203
+ out["minItems"] = self.min_items
204
+ if self.max_items is not None:
205
+ out["maxItems"] = self.max_items
206
+ elif self.kind == "string":
207
+ out = {"type": "string"}
208
+ if self.enum:
209
+ out["enum"] = list(self.enum)
210
+ if self.min_chars is not None:
211
+ out["minLength"] = self.min_chars
212
+ if self.max_chars is not None:
213
+ out["maxLength"] = self.max_chars
214
+ if self.pattern:
215
+ out["pattern"] = self.pattern
216
+ if self.fmt:
217
+ out["format"] = self.fmt
218
+ else:
219
+ out = {"type": self.kind}
220
+ if self.minimum is not None:
221
+ out["minimum"] = self.minimum
222
+ if self.maximum is not None:
223
+ out["maximum"] = self.maximum
224
+ if self.nullable:
225
+ out["type"] = [out["type"], "null"]
226
+ return out
227
+
228
+ def check(self, value: Any, path: str, ctx: "Context", errors: list[dict]) -> None:
229
+ if value is None and self.nullable:
230
+ return
231
+ if self.kind == "object":
232
+ self._check_object(value, path, ctx, errors)
233
+ elif self.kind == "array":
234
+ self._check_array(value, path, ctx, errors)
235
+ elif self.kind == "string":
236
+ self._check_string(value, path, ctx, errors)
237
+ else:
238
+ self._check_number(value, path, ctx, errors)
239
+
240
+ def _fail(self, code: str, path: str, message: str, errors: list[dict]) -> None:
241
+ errors.append({"code": code, "path": path or "ответ", "message": message})
242
+
243
+ def _check_object(self, value: Any, path: str, ctx: "Context", errors: list[dict]) -> None:
244
+ if not isinstance(value, dict):
245
+ self._fail("SCA-M005", path, "ожидался объект", errors)
246
+ return
247
+ for name in value:
248
+ if name not in self.fields:
249
+ self._fail("SCA-M003", f"{path}.{name}", "поля нет в контракте", errors)
250
+ for name, item in self.fields.items():
251
+ if name not in value:
252
+ if item.required:
253
+ self._fail("SCA-M004", f"{path}.{name}", "обязательное поле не заполнено", errors)
254
+ continue
255
+ item.check(value[name], f"{path}.{name}", ctx, errors)
256
+
257
+ def _check_array(self, value: Any, path: str, ctx: "Context", errors: list[dict]) -> None:
258
+ if not isinstance(value, list):
259
+ self._fail("SCA-M005", path, "ожидался список", errors)
260
+ return
261
+ limit = self.max_items if self.max_items is not None else ctx.limits["max_rows"]
262
+ if len(value) > limit:
263
+ self._fail("SCA-M002", path, f"элементов больше предела ({len(value)} при пределе {limit})", errors)
264
+ return
265
+ if self.min_items is not None and len(value) < self.min_items:
266
+ self._fail("SCA-M005", path, f"элементов меньше минимума ({len(value)})", errors)
267
+ if self.unique_key:
268
+ seen: set[Any] = set()
269
+ for index, item in enumerate(value):
270
+ names = self.unique_key if isinstance(self.unique_key, tuple) else (self.unique_key,)
271
+ parts = tuple(_obj(item).get(name) for name in names)
272
+ if any(not isinstance(part, str) for part in parts):
273
+ # Тип проверяется ниже описанием поля; списки и объекты нельзя хешировать.
274
+ continue
275
+ key = parts if len(names) > 1 else parts[0]
276
+ if key in seen:
277
+ self._fail(self.unique_code, f"{path}[{index}].{names[0]}",
278
+ f"повтор значения {key!r}", errors)
279
+ seen.add(key)
280
+ for index, item in enumerate(value):
281
+ (self.item or Field("string")).check(item, f"{path}[{index}]", ctx, errors)
282
+
283
+ def _check_string(self, value: Any, path: str, ctx: "Context", errors: list[dict]) -> None:
284
+ if not isinstance(value, str):
285
+ self._fail("SCA-M005", path, "ожидалась строка", errors)
286
+ return
287
+ if self.enum and value not in self.enum:
288
+ self._fail("SCA-M005", path, f"значение не из перечисления: {value!r}", errors)
289
+ return
290
+ if self.min_chars is not None and len(value.strip()) < self.min_chars:
291
+ self._fail("SCA-M005", path, f"строка короче {self.min_chars} символов", errors)
292
+ if self.max_chars is not None and len(value) > self.max_chars:
293
+ self._fail("SCA-M002", path, f"строка длиннее предела ({len(value)} при пределе {self.max_chars})",
294
+ errors)
295
+ if self.pattern and not re.match(self.pattern, value):
296
+ self._fail("SCA-M005", path, "значение не по шаблону контракта", errors)
297
+ if self.fmt and value.strip(): # пустое значение – факт ещё не установлен, а не ошибка даты
298
+ stamp = _timestamp(value)
299
+ if stamp is None:
300
+ self._fail("SCA-M005", path, f"не дата и не время ISO 8601: {value!r}", errors)
301
+ elif stamp > ctx.today + timedelta(days=FUTURE_TOLERANCE_DAYS):
302
+ self._fail("SCA-D001", path, f"дата в будущем: {value}", errors)
303
+
304
+ def _check_number(self, value: Any, path: str, ctx: "Context", errors: list[dict]) -> None:
305
+ if self.kind == 'integer' and type(value) is not int:
306
+ self._fail('SCA-M005', path, 'ожидалось целое число', errors)
307
+ return
308
+ if self.kind == "boolean":
309
+ if not isinstance(value, bool):
310
+ self._fail("SCA-M005", path, f"ожидалось true или false, получено {type(value).__name__}",
311
+ errors)
312
+ return
313
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
314
+ self._fail("SCA-M005", path, f"ожидалось число, получено {type(value).__name__}", errors)
315
+ return
316
+ if isinstance(value, float) and not math.isfinite(value):
317
+ self._fail("SCA-M001", path, "число вне диапазона (NaN или бесконечность)", errors)
318
+ return
319
+ if self.minimum is not None and value < self.minimum:
320
+ self._fail("SCA-M005", path, f"меньше минимума {self.minimum}", errors)
321
+ if self.maximum is not None and value > self.maximum:
322
+ self._fail("SCA-M005", path, f"больше максимума {self.maximum}", errors)
323
+
324
+
325
+ def compare_versions(ecosystem: str, left: str, right: str) -> int | None:
326
+ """SemVer, PEP 440, RubyGems и ограниченные числовые формы Maven/NuGet/Composer.
327
+
328
+ Maven: числовые сегменты и alpha/beta/milestone/rc/snapshot/final/ga/release/sp с номером.
329
+ Это не полная реализация ComparableVersion. Неизвестные суффиксы поставщика дают None:
330
+ приложение не делает вид, что знает их порядок. У npm метаданные сборки порядок не меняют.
331
+ """
332
+ def sign(a, b):
333
+ return (a > b) - (a < b)
334
+
335
+ def numeric(parts):
336
+ values = [int(x) for x in parts.split('.')]
337
+ while len(values) > 1 and values[-1] == 0:
338
+ values.pop()
339
+ return tuple(values)
340
+
341
+ def compare_core(a, b):
342
+ size = max(len(a), len(b))
343
+ return sign(a + (0,) * (size - len(a)), b + (0,) * (size - len(b)))
344
+
345
+ left, right = _text(left), _text(right)
346
+ if not left or not right:
347
+ return None
348
+ if left == right:
349
+ return 0
350
+ eco = ecosystem.casefold()
351
+ if eco == 'pypi':
352
+ a, b = _pep440_key(left), _pep440_key(right)
353
+ return sign(a, b) if a is not None and b is not None else None
354
+ if eco == 'gem':
355
+ def gem(value):
356
+ if not re.fullmatch(r'[0-9]+(?:\.[0-9A-Za-z]+)*(?:-[0-9A-Za-z.-]+)?', value):
357
+ return None
358
+ tokens = re.findall(r'[0-9]+|[A-Za-z]+', value.replace('-', '.pre.'))
359
+ result = [(1, int(x)) if x.isdigit() else (0, x) for x in tokens]
360
+ first_string = next((i for i,x in enumerate(result) if x[0] == 0),len(result))
361
+ numeric_part = result[:first_string]
362
+ while numeric_part and numeric_part[-1] == (1,0):
363
+ numeric_part.pop()
364
+ result = numeric_part + result[first_string:]
365
+ while result and result[-1] == (1, 0):
366
+ result.pop()
367
+ return result
368
+ a, b = gem(left), gem(right)
369
+ if a is None or b is None:
370
+ return None
371
+ size = max(len(a), len(b))
372
+ return sign(a + [(1, 0)] * (size-len(a)), b + [(1, 0)] * (size-len(b)))
373
+ if eco in ('nuget', 'composer'):
374
+ # NuGet: до четырёх числовых частей, регистр prerelease незначим.
375
+ # Composer: опубликованные числовые релизы с необязательным v, без branch alias/dev-веток.
376
+ def normalize(value):
377
+ if eco == 'composer':
378
+ value = value.removeprefix('v')
379
+ m = re.fullmatch(r'([0-9]+(?:\.[0-9]+){0,3})(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?', value)
380
+ if not m:
381
+ return None
382
+ nums = [int(x) for x in m[1].split('.')]
383
+ nums += [0] * (4-len(nums))
384
+ pre = m[2] or ''
385
+ return nums, pre.casefold() if eco == 'nuget' else pre
386
+ a, b = normalize(left), normalize(right)
387
+ if a is None or b is None:
388
+ return None
389
+ core = sign(a[0], b[0])
390
+ if core:
391
+ return core
392
+ left, right = '0.0.0' + ('-' + a[1] if a[1] else ''), '0.0.0' + ('-' + b[1] if b[1] else '')
393
+ eco = 'npm'
394
+ if ecosystem.casefold() == 'maven':
395
+ pattern = r'([0-9]+(?:\.[0-9]+)*)(?:[.-]?(alpha|beta|milestone|rc|cr|snapshot|final|ga|release|sp|a|b|m)(?:[.-]?([0-9]+))?)?'
396
+ a, b = re.fullmatch(pattern, left, re.I), re.fullmatch(pattern, right, re.I)
397
+ if not a or not b:
398
+ return None
399
+ core = compare_core(numeric(a[1]), numeric(b[1]))
400
+ if core:
401
+ return core
402
+ ranks = {'alpha': -5, 'a': -5, 'beta': -4, 'b': -4, 'milestone': -3, 'm': -3,
403
+ 'rc': -2, 'cr': -2, 'snapshot': -1, '': 0, 'final': 0, 'ga': 0, 'release': 0, 'sp': 1}
404
+ return sign((ranks[(a[2] or '').lower()], int(a[3] or 0)),
405
+ (ranks[(b[2] or '').lower()], int(b[3] or 0)))
406
+ if eco not in ('npm', 'cargo'):
407
+ return None
408
+ pattern = r'(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?'
409
+ a, b = re.fullmatch(pattern, left), re.fullmatch(pattern, right)
410
+ if not a or not b:
411
+ return None
412
+ pre_a, pre_b = (a[4] or '').split('.'), (b[4] or '').split('.')
413
+ if any(x.isdigit() and len(x) > 1 and x[0] == '0' for x in pre_a + pre_b):
414
+ return None
415
+ core = sign(tuple(int(a[i]) for i in (1, 2, 3)), tuple(int(b[i]) for i in (1, 2, 3)))
416
+ if core:
417
+ return core
418
+ if not a[4] or not b[4]:
419
+ return sign(not a[4], not b[4])
420
+ for x, y in zip(pre_a, pre_b, strict=False):
421
+ if x == y:
422
+ continue
423
+ if x.isdigit() and y.isdigit():
424
+ return sign(int(x), int(y))
425
+ if x.isdigit() != y.isdigit():
426
+ return -1 if x.isdigit() else 1
427
+ return sign(x, y)
428
+ return sign(len(pre_a), len(pre_b))
429
+
430
+
431
+ def _pep440_key(value: str) -> tuple | None:
432
+ """PEP 440: epoch, release, pre/post/dev и local; неизвестная форма остаётся неизвестной."""
433
+ pattern = (r'v?(?:(?P<epoch>[0-9]+)!)?(?P<release>[0-9]+(?:\.[0-9]+)*)'
434
+ r'(?:[-_.]?(?P<pre>a|b|c|rc|alpha|beta|pre|preview)[-_.]?(?P<prenum>[0-9]+)?)?'
435
+ r'(?:(?:-(?P<postnum1>[0-9]+))|(?:[-_.]?(?P<post>post|rev|r)[-_.]?(?P<postnum2>[0-9]+)?))?'
436
+ r'(?:[-_.]?(?P<dev>dev)[-_.]?(?P<devnum>[0-9]+)?)?'
437
+ r'(?:\+(?P<local>[a-z0-9]+(?:[-_.][a-z0-9]+)*))?')
438
+ match = re.fullmatch(pattern, value, re.I)
439
+ if not match:
440
+ return None
441
+ m = match.groupdict();release = [int(x) for x in m['release'].split('.')]
442
+ while release and release[-1] == 0:
443
+ release.pop()
444
+ post = m['post'] is not None or m['postnum1'] is not None
445
+ pre_names = {'a':0,'alpha':0,'b':1,'beta':1,'rc':2,'c':2,'pre':2,'preview':2}
446
+ pre = (pre_names[m['pre'].lower()],int(m['prenum'] or 0)) if m['pre'] else (
447
+ (-1,0) if m['dev'] and not post else (3,0))
448
+ local = tuple((1,int(x)) if x.isdigit() else (0,x.lower())
449
+ for x in re.split(r'[-_.]',m['local'] or '') if x)
450
+ return (int(m['epoch'] or 0),tuple(release),pre,
451
+ (1,int(m['postnum1'] or m['postnum2'] or 0)) if post else (0,0),
452
+ (0,int(m['devnum'] or 0)) if m['dev'] else (1,0),local)
453
+
454
+
455
+ def public_url_parts(text: str) -> tuple[str, str] | None:
456
+ """Общие правила ссылок источников, без DNS-запросов и неоднозначной записи WHATWG."""
457
+ if (not text or len(text) > LIMITS['url_chars'] or not text.isascii()
458
+ or re.search(r'[\x00-\x20\x7f\\]', text)):
459
+ return None
460
+ try:
461
+ parts = urlsplit(text); host = parts.hostname or ''
462
+ if parts.scheme.lower() not in ('http','https') or parts.username is not None or parts.password is not None or parts.port not in (None,80,443):
463
+ return None
464
+ except ValueError:
465
+ return None
466
+ labels = host.split('.')
467
+ if (len(labels)<2 or len(host)>253 or not all(re.fullmatch(r'[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?', x) for x in labels)
468
+ or re.fullmatch(r'[0-9]+|0x[0-9a-f]*', labels[-1],re.I)
469
+ or host.endswith(('.local','.internal','.lan','.corp','.localhost','.home','.intranet','.localdomain'))):
470
+ return None
471
+ for label in labels:
472
+ if label.startswith('xn--'):
473
+ try:
474
+ if label.encode('ascii').decode('idna').isascii():
475
+ return None
476
+ except UnicodeError:
477
+ return None
478
+ if re.search(r'["<>`{}]',parts.path) or any(re.fullmatch(r'(?:\.|%2e){1,2}',x,re.I) for x in parts.path.split('/')):
479
+ return None
480
+ return host, parts.path
481
+
482
+
483
+ def _timestamp(value: str) -> date | None:
484
+ """Дата или время ISO 8601 из строки; пустая строка и мусор – None."""
485
+ text = value.strip()
486
+ if not text:
487
+ return None
488
+ try:
489
+ return datetime.fromisoformat(text.replace("Z", "+00:00")).date()
490
+ except ValueError:
491
+ pass
492
+ try:
493
+ return date.fromisoformat(text)
494
+ except ValueError:
495
+ return None
496
+
497
+
498
+ def _date_field(max_chars: int = 40, required: bool = True) -> Field:
499
+ """Поле-дата: пустое значение допустимо (факт ещё не установлен), непустое должно быть датой ISO 8601."""
500
+ return Field("string", min_chars=0, max_chars=max_chars, fmt="date-time", required=required)
501
+
502
+
503
+ def _short(nullable: bool = False) -> Field:
504
+ return Field("string", max_chars=LIMITS["id_chars"], nullable=nullable)
505
+
506
+
507
+ def _text_field(max_chars: int = LIMITS["text_chars"], nullable: bool = False) -> Field:
508
+ return Field("string", max_chars=max_chars, nullable=nullable)
509
+
510
+
511
+ def _source_refs() -> Field:
512
+ """Список ссылок на доказательства строки: значения сверяются с массивом evidence этой же строки."""
513
+ return Field("array", item=_short(), max_items=LIMITS["source_refs"])
514
+
515
+ _CVSS = {
516
+ "score": Field("number", minimum=0, maximum=10),
517
+ "vector": _text_field(max_chars=200, nullable=True),
518
+ "version": Field("string", min_chars=0, max_chars=8, nullable=True),
519
+ }
520
+ _RANGE = {"introduced": Field("string", max_chars=LIMITS["version_chars"], nullable=True),
521
+ "fixed": Field("string", max_chars=LIMITS["version_chars"], nullable=True),
522
+ "last_affected": Field("string", max_chars=LIMITS["version_chars"], nullable=True, required=False)}
523
+
524
+ _EVIDENCE_ITEM = {
525
+ "evidence_ref": _short(),
526
+ "url": Field("string", min_chars=8, max_chars=LIMITS["url_chars"], pattern=r"^https?://\S+$"),
527
+ "checked_at": _date_field(),
528
+ "source_type": Field("string", enum=EVIDENCE_SOURCES),
529
+ "justification": Field("string", min_chars=3, max_chars=LIMITS["text_chars"]),
530
+ "quote": Field("string", min_chars=1, max_chars=LIMITS["quote_chars"], nullable=True),
531
+ "level": Field("string", enum=EVIDENCE_LEVELS),
532
+ }
533
+
534
+ FIX_STATUSES = ("fixed", "no_fix_published", "unknown")
535
+ FIX_SCOPES = ("package", "branch")
536
+ DISPUTED_BY = ("vendor", "other")
537
+ CHECK_ROLES = ("hub", "target")
538
+
539
+ _FIX_STATUS = Field("object", fields={
540
+ "status": Field("string", enum=FIX_STATUSES),
541
+ "scope": Field("string", enum=FIX_SCOPES),
542
+ # ветка утверждения при scope=branch: префикс версий («42.7»), к цели относится, только если цель в этой ветке
543
+ "branch": Field("string", max_chars=LIMITS["version_chars"], nullable=True, required=False),
544
+ "source_refs": _source_refs(),
545
+ }, nullable=True, required=False)
546
+
547
+ _DISPUTED = Field("object", fields={
548
+ "by": Field("string", enum=DISPUTED_BY),
549
+ "note": _text_field(max_chars=LIMITS["note_chars"]),
550
+ "source_refs": _source_refs(),
551
+ }, nullable=True, required=False)
552
+
553
+ _POSITION_ITEM = {
554
+ "source": Field("string", min_chars=1, max_chars=LIMITS["source_chars"]),
555
+ "affects": Field("string", enum=APPLIES_VALUES),
556
+ "ranges": Field("array", item=Field("object", fields=_RANGE), max_items=LIMITS["ranges_per_finding"]),
557
+ "source_refs": _source_refs(),
558
+ }
559
+
560
+ _FINDING_ITEM = {
561
+ "id": Field("string", min_chars=3, max_chars=LIMITS["id_chars"]),
562
+ "aliases": Field("array", item=_short(), max_items=LIMITS["aliases_per_finding"]),
563
+ "applies": Field("string", enum=APPLIES_VALUES),
564
+ "description": Field("string", min_chars=1, max_chars=LIMITS["text_chars"]),
565
+ "ranges": Field("array", item=Field("object", fields=_RANGE), max_items=LIMITS["ranges_per_finding"]),
566
+ "conditions": Field("string", max_chars=LIMITS["text_chars"], nullable=True),
567
+ "fixed_versions": Field("array", item=_short(), max_items=LIMITS["fixed_versions_per_finding"]),
568
+ "cvss": Field("object", fields=_CVSS, nullable=True),
569
+ "source_refs": _source_refs(),
570
+ "fix_status": _FIX_STATUS,
571
+ "disputed": _DISPUTED,
572
+ "source_positions": Field("array", item=Field("object", fields=_POSITION_ITEM),
573
+ max_items=LIMITS["positions_per_finding"], unique_key="source", required=False),
574
+ }
575
+
576
+ _COVERAGE_ITEM = {
577
+ "source": Field("string", min_chars=1, max_chars=LIMITS["source_chars"]),
578
+ "purpose": Field("string", enum=COVERAGE_PURPOSES),
579
+ "query": Field("object", fields={"ecosystem": Field("string", max_chars=LIMITS["source_chars"], nullable=True),
580
+ "coordinates": Field("string", max_chars=LIMITS["source_chars"],
581
+ nullable=True),
582
+ "version": Field("string", max_chars=LIMITS["version_chars"],
583
+ nullable=True)}, nullable=True),
584
+ "source_refs": Field("array", item=_short(), max_items=LIMITS["source_refs"]),
585
+ "checked_at": _date_field(),
586
+ "status": Field("string", enum=COVERAGE_STATUSES),
587
+ "complete": Field("boolean"),
588
+ "note": _text_field(max_chars=LIMITS["note_chars"], nullable=True),
589
+ }
590
+
591
+ _GAP_ITEM = {
592
+ "code": Field("string", enum=GAP_CODES),
593
+ "text": Field("string", min_chars=1, max_chars=LIMITS["note_chars"]),
594
+ }
595
+
596
+ _ADVICE = {
597
+ "action": Field("string", enum=ADVICE_ACTIONS),
598
+ "target_version": Field("string", max_chars=LIMITS["version_chars"], nullable=True),
599
+ "source_refs": Field("array", item=_short(), max_items=LIMITS["source_refs"], required=False),
600
+ "compatibility_notes": Field("string", max_chars=LIMITS["text_chars"], nullable=True),
601
+ "remaining_risks": Field("array", item=_text_field(max_chars=LIMITS["note_chars"]),
602
+ max_items=LIMITS["gaps_per_row"]),
603
+ }
604
+
605
+ _ROW = Field("object", fields={
606
+ "input_ref": Field("string", max_chars=LIMITS["id_chars"]),
607
+ "ecosystem": Field("string", min_chars=0, max_chars=LIMITS["source_chars"]),
608
+ "component": Field("string", min_chars=1, max_chars=LIMITS["source_chars"]),
609
+ "current_version": Field("string", min_chars=1, max_chars=LIMITS["version_chars"]),
610
+ "identity_resolution": Field("object", fields={
611
+ "state": Field("string", enum=IDENTITY_STATES),
612
+ "coordinates": Field("string", max_chars=LIMITS["source_chars"], nullable=True),
613
+ "candidates": Field("array", item=_short(), max_items=LIMITS["candidates_per_row"]),
614
+ "note": Field("string", max_chars=LIMITS["note_chars"], nullable=True),
615
+ "basis": Field("string", max_chars=LIMITS["note_chars"], nullable=True, required=False),
616
+ "source_refs": _source_refs(),
617
+ }),
618
+ "latest_stable_release": Field("object", fields={
619
+ "version": Field("string", max_chars=LIMITS["version_chars"], nullable=True),
620
+ "released_at": _date_field(),
621
+ "note": Field("string", max_chars=LIMITS["note_chars"], nullable=True),
622
+ "source_refs": _source_refs(),
623
+ }),
624
+ "update_status": Field("string", enum=UPDATE_STATUSES),
625
+ "support_status": Field("object", fields={
626
+ "state": Field("string", enum=SUPPORT_STATES),
627
+ "scope": Field("string", enum=SUPPORT_SCOPES),
628
+ "as_of": _date_field(),
629
+ "note": Field("string", max_chars=LIMITS["note_chars"], nullable=True),
630
+ "source_refs": _source_refs(),
631
+ }),
632
+ "public_findings": Field("array", item=Field("object", fields=_FINDING_ITEM),
633
+ max_items=LIMITS["findings_per_row"], unique_key="id",
634
+ unique_code="SCA-E001"),
635
+ "research_coverage": Field("array", item=Field("object", fields=_COVERAGE_ITEM),
636
+ max_items=LIMITS["coverage_per_row"], unique_key=("source", "purpose"),
637
+ unique_code="SCA-M005"),
638
+ "package_advice": Field("object", fields=_ADVICE),
639
+ "evidence": Field("array", item=Field("object", fields=_EVIDENCE_ITEM),
640
+ max_items=LIMITS["evidence_per_row"], unique_key="evidence_ref", unique_code="SCA-E001"),
641
+ "gaps": Field("array", item=Field("object", fields=_GAP_ITEM), max_items=LIMITS["gaps_per_row"]),
642
+ "package_status": Field("string", enum=PACKAGE_STATUSES),
643
+ # ADR-0094 Р2: проверка конкретных версий – исправления из Hub (role=hub) и цели (role=target); находки здесь
644
+ # описывают проверенную версию и уязвимостями текущей версии не становятся
645
+ "version_checks": Field("array", item=Field("object", fields={
646
+ "role": Field("string", enum=CHECK_ROLES),
647
+ "version": Field("string", min_chars=1, max_chars=LIMITS["version_chars"]),
648
+ "coverage": Field("array", item=Field("object", fields=_COVERAGE_ITEM),
649
+ max_items=LIMITS["coverage_per_row"], unique_key=("source", "purpose"),
650
+ unique_code="SCA-M005"),
651
+ "findings": Field("array", item=Field("object", fields={
652
+ "id": Field("string", min_chars=3, max_chars=LIMITS["id_chars"]),
653
+ "aliases": Field("array", item=_short(), max_items=LIMITS["aliases_per_finding"]),
654
+ "ranges": Field("array", item=Field("object", fields=_RANGE), max_items=LIMITS["ranges_per_finding"]),
655
+ "fixed_versions": Field("array", item=_short(), max_items=LIMITS["fixed_versions_per_finding"]),
656
+ "fix_status": _FIX_STATUS,
657
+ "cvss": Field("object", fields=_CVSS, nullable=True),
658
+ "source_refs": _source_refs(),
659
+ }), max_items=LIMITS["findings_per_row"], unique_key="id", unique_code="SCA-E001"),
660
+ }), max_items=LIMITS["version_checks_per_row"], unique_key=("role", "version"), unique_code="SCA-M005",
661
+ required=False),
662
+ })
663
+
664
+ ROW_SCHEMA = _ROW.schema()
665
+
666
+
667
+ def extensions_used(row: Mapping[str, Any]) -> list[str]:
668
+ """Поля расширения 2.1 (ADR-0094), которые есть в строке ответа."""
669
+ used = []
670
+ if "version_checks" in _obj(row):
671
+ used.append("version_checks")
672
+ for finding in _list(_obj(row).get("public_findings")):
673
+ for name in ("fix_status", "disputed", "source_positions"):
674
+ if name in _obj(finding) and name not in used:
675
+ used.append(name)
676
+ return used
677
+
678
+ _ANSWER_SPEC: dict[str, Field] = {
679
+ "contract": Field("string", enum=[ANSWER_CONTRACT]),
680
+ "task_id": Field("string", min_chars=1, max_chars=LIMITS["id_chars"]),
681
+ "manifest_sha256": Field("string", pattern=r"^[0-9a-f]{64}$"),
682
+ "validator_version": Field("string", enum=ACCEPTED_VALIDATORS),
683
+ # время ответа необязательно: приложение само помнит, когда ответ загружен, а часы агента доказательством
684
+ # поддержки не являются
685
+ "generated_at": _date_field(required=False),
686
+ "row_count": Field("integer", minimum=1, maximum=LIMITS["max_rows"]),
687
+ "rows": Field("array", item=_ROW, max_items=LIMITS["max_rows"]),
688
+ }
689
+
690
+
691
+ def schema() -> dict:
692
+ """Схема ответа для агента – из того же описания полей, которым проверяет приложение. Пределы и версия
693
+ валидатора объявлены здесь же: агент видит их до работы, а не после отказа."""
694
+ return {"$schema": "https://json-schema.org/draft/2020-12/schema",
695
+ "title": "Ответ по исследованию компонентов SCA", "x-contract": ANSWER_CONTRACT,
696
+ "x-validator": VALIDATOR_VERSION, "x-limits": dict(LIMITS), "additionalProperties": False,
697
+ "required": [name for name, item in _ANSWER_SPEC.items() if item.required],
698
+ "properties": {name: item.schema() for name, item in _ANSWER_SPEC.items()}}
699
+
700
+
701
+ def empty_row(source: Mapping[str, Any]) -> dict:
702
+ """Заготовка одной строки ответа: правильная по контракту и честно незаполненная. Входные поля в ней уже
703
+ стоят из задания – их не приходится переписывать, и подмена заметна проверке. Статус «неполно»
704
+ намеренный: пустая заготовка не должна выглядеть чистым результатом."""
705
+ return {
706
+ "input_ref": _text(source.get("input_ref")),
707
+ "ecosystem": _text(source.get("ecosystem")),
708
+ "component": _text(source.get("component") or source.get("name")),
709
+ "current_version": _text(source.get("version")),
710
+ "identity_resolution": {"state": "unknown", "coordinates": None, "candidates": [], "note": None,
711
+ "source_refs": []},
712
+ "latest_stable_release": {"version": None, "released_at": "", "note": None, "source_refs": []},
713
+ "update_status": "unknown",
714
+ "support_status": {"state": "unknown", "scope": "unknown", "as_of": "", "note": None, "source_refs": []},
715
+ "public_findings": [],
716
+ "research_coverage": [{
717
+ "source": "", "purpose": purpose,
718
+ "query": {"ecosystem": _text(source.get('ecosystem')), "coordinates": None,
719
+ "version": _text(source.get('version'))},
720
+ "source_refs": [], "checked_at": "", "status": "error", "complete": False,
721
+ "note": "Проверка ещё не выполнена"
722
+ } for purpose in ('identity', 'vulnerabilities', 'releases', 'support')],
723
+ "package_advice": {"action": "insufficient_data", "target_version": None,
724
+ "compatibility_notes": None, "remaining_risks": []},
725
+ "evidence": [],
726
+ "gaps": [{"code": "NOT_RESEARCHED", "text": "Компонент ещё не исследован"}],
727
+ "package_status": "incomplete",
728
+ }
729
+
730
+
731
+ def template(task: Mapping[str, Any], rows: Iterable[Mapping[str, Any]]) -> dict:
732
+ """Заготовка ответа на всё задание: те же строки в том же порядке, что в components.json."""
733
+ items = [empty_row(item) for item in rows]
734
+ return {"contract": ANSWER_CONTRACT, "task_id": _text(task.get("task_id")),
735
+ "manifest_sha256": _text(task.get("manifest_sha256")), "validator_version": VALIDATOR_VERSION,
736
+ "generated_at": "", "row_count": len(items), "rows": items}
737
+
738
+
739
+ # ------------------------------------------------------------------ проверка ответа
740
+
741
+ @dataclass
742
+ class Context:
743
+ """Состояние проверки: границы, сегодняшний день для дат и строки сохранённого задания."""
744
+ limits: dict = dc_field(default_factory=lambda: dict(LIMITS))
745
+ today: date = dc_field(default_factory=date.today)
746
+ rows: dict = dc_field(default_factory=dict)
747
+ manifest_sha256: str = ""
748
+
749
+
750
+ @dataclass
751
+ class Report:
752
+ """Итог проверки: годен ли ответ, все ли поля проверены и что именно не так, по каждой строке и полю."""
753
+ ok: bool
754
+ errors: list[dict]
755
+ answer: dict | None = None
756
+ answer_sha256: str = ""
757
+ answer_bytes: int = 0
758
+ summary: dict = dc_field(default_factory=dict)
759
+
760
+ def codes(self) -> list[str]:
761
+ return [error["code"] for error in self.errors]
762
+
763
+ def paths(self) -> list[str]:
764
+ return [error["path"] for error in self.errors]
765
+
766
+ def text(self) -> str:
767
+ """Отчёт для человека и агента: по одной строке на ошибку с путём до поля."""
768
+ if self.ok:
769
+ summary = ", ".join(f"{key}: {value}" for key, value in sorted(self.summary.items())) or "нет строк"
770
+ return f"Ответ принят: строк {len(_list((self.answer or {}).get('rows')))}, состояния – {summary}."
771
+ lines = [f"Ответ не принят: ошибок {len(self.errors)}."]
772
+ lines += [f" {item['code']} {item['path']}: {item['message']}" for item in self.errors]
773
+ return "\n".join(lines)
774
+
775
+ def as_dict(self) -> dict:
776
+ """Машинный отчёт: целиком, без сокращений, чтобы агент исправил все поля за один проход."""
777
+ return {"ok": self.ok, "contract": ANSWER_CONTRACT, "validator": VALIDATOR_VERSION,
778
+ "answer_sha256": self.answer_sha256, "answer_bytes": self.answer_bytes, "summary": self.summary,
779
+ "errors": self.errors}
780
+
781
+
782
+ def _fail(code: str, path: str, message: str, errors: list[dict]) -> None:
783
+ errors.append({"code": code, "path": path or "ответ", "message": message})
784
+
785
+
786
+ def _pairs_hook(dupes: list[str]):
787
+ """Разбор объекта с запоминанием повторов ключей: повтор в JSON молча берёт последнее значение."""
788
+ def hook(pairs):
789
+ seen: dict[str, Any] = {}
790
+ for key, value in pairs:
791
+ if key in seen:
792
+ dupes.append(key)
793
+ seen[key] = value
794
+ return seen
795
+ return hook
796
+
797
+
798
+ def _reject_constant(name: str):
799
+ raise ValueError(f"недопустимое число {name}")
800
+
801
+
802
+ def validate_answer(text: bytes | str, task: Mapping[str, Any], *, today: date | None = None,
803
+ limits: Mapping[str, int] | None = None) -> Report:
804
+ """Проверка ответа агента по сохранённому заданию. task – {task_id, manifest_sha256, row_count, rows}.
805
+ Неверный ответ отклоняется целиком: частичная запись строк невозможна, потому что проверка идёт до записи."""
806
+ ctx = Context(limits={**LIMITS, **dict(limits or {})}, today=today or date.today())
807
+ raw = text.encode("utf-8") if isinstance(text, str) else bytes(text)
808
+ errors: list[dict] = []
809
+ if len(raw) > ctx.limits["answer_bytes"]:
810
+ _fail("SCA-M002", "ответ", f"размер ответа {len(raw)} байт при пределе {ctx.limits['answer_bytes']}",
811
+ errors)
812
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
813
+ try:
814
+ body = raw.decode("utf-8-sig")
815
+ except UnicodeDecodeError as exc:
816
+ _fail("SCA-M001", "ответ", f"файл не в UTF-8: {exc.reason}", errors)
817
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
818
+ if not body.strip():
819
+ _fail("SCA-M001", "ответ", "файл ответа пуст", errors)
820
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
821
+ dupes: list[str] = []
822
+ try:
823
+ answer = json.loads(body, object_pairs_hook=_pairs_hook(dupes), parse_constant=_reject_constant)
824
+ except RecursionError:
825
+ _fail("SCA-M006", "ответ", "слишком глубокое вложение JSON", errors)
826
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
827
+ except ValueError as exc:
828
+ _fail("SCA-M001", "ответ", f"JSON не разобран: {exc}", errors)
829
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
830
+ for key in dict.fromkeys(dupes):
831
+ _fail("SCA-M001", "ответ", f"повтор ключа JSON: {key}", errors)
832
+ if not isinstance(answer, dict):
833
+ _fail("SCA-M001", "ответ", f"ожидался объект ответа, получено {type(answer).__name__}", errors)
834
+ return Report(ok=False, errors=errors, answer_bytes=len(raw))
835
+ stack = [(answer, 0)]
836
+ while stack:
837
+ node, depth = stack.pop()
838
+ if isinstance(node, (dict, list)):
839
+ if depth > ctx.limits['depth']:
840
+ _fail('SCA-M006', 'ответ', 'превышен предел глубины JSON', errors)
841
+ return Report(ok=False, errors=_limited(errors, ctx.limits['reported_errors']), answer_bytes=len(raw))
842
+ stack.extend((child,depth+1) for child in (node.values() if isinstance(node,dict) else node))
843
+ ctx.rows = {_text(item.get("input_ref")): item for item in _list(task.get("rows"))}
844
+ ctx.manifest_sha256 = _text(task.get("manifest_sha256"))
845
+ for name, item in _ANSWER_SPEC.items():
846
+ if name not in answer:
847
+ _fail("SCA-M004", name, "обязательное поле не заполнено", errors)
848
+ continue
849
+ item.check(answer[name], name, ctx, errors)
850
+ for name in answer:
851
+ if name not in _ANSWER_SPEC:
852
+ _fail("SCA-M003", name, "поля нет в контракте", errors)
853
+ if _text(answer.get("contract")) not in ("", ANSWER_CONTRACT):
854
+ _fail("SCA-T002", "contract", f"контракт {answer.get('contract')!r}, ожидался {ANSWER_CONTRACT}", errors)
855
+ if _text(answer.get("validator_version")) not in ("", *ACCEPTED_VALIDATORS):
856
+ _fail("SCA-T002", "validator_version", f"версия валидатора {answer.get('validator_version')!r}",
857
+ errors)
858
+ declared = _text(answer.get("validator_version"))
859
+ if declared in ACCEPTED_VALIDATORS and declared not in EXTENSION_VALIDATORS:
860
+ for index, row in enumerate(_list(answer.get("rows"))):
861
+ used = extensions_used(row) if isinstance(row, dict) else []
862
+ if used:
863
+ _fail("SCA-T002", f"rows[{index}]",
864
+ f"поля {', '.join(used)} есть только в схеме {EXTENSION_VALIDATORS[0]}, а объявлена {declared}",
865
+ errors)
866
+ if ctx.manifest_sha256 and _text(answer.get("manifest_sha256")) and not _SHA.match(
867
+ _text(answer.get("manifest_sha256"))):
868
+ _fail("SCA-M005", "manifest_sha256", "отпечаток манифеста не 64 знака sha256", errors)
869
+ if _text(task.get("task_id")) and _text(answer.get("task_id")) != _text(task.get("task_id")):
870
+ _fail("SCA-T002", "task_id", f"задание {answer.get('task_id')!r}, а сохранено {task.get('task_id')!r}",
871
+ errors)
872
+ if (ctx.manifest_sha256 and _text(answer.get("manifest_sha256"))
873
+ and _text(answer.get("manifest_sha256")) != ctx.manifest_sha256):
874
+ _fail("SCA-C004", "manifest_sha256", "отпечаток манифеста не совпадает с сохранённым на сервере", errors)
875
+ rows = _list(answer.get("rows"))
876
+ if isinstance(answer.get("row_count"), int) and not isinstance(answer.get("row_count"), bool) \
877
+ and answer["row_count"] != len(rows):
878
+ _fail("SCA-C003", "row_count", f"в ответе {answer['row_count']} строк, а в rows {len(rows)}", errors)
879
+ seen: set[str] = set()
880
+ for index, row in enumerate(rows):
881
+ path = f"rows[{index}]"
882
+ if not isinstance(row, dict):
883
+ continue
884
+ ref = _text(row.get("input_ref"))
885
+ source = ctx.rows.get(ref)
886
+ if source is None:
887
+ _fail("SCA-C001", f"{path}.input_ref", f"строки {ref!r} нет в сохранённом задании", errors)
888
+ elif ref in seen:
889
+ _fail("SCA-C003", f"{path}.input_ref", f"повтор строки {ref!r}", errors)
890
+ else:
891
+ seen.add(ref)
892
+ # сверяются те поля, которые есть в сохранённом задании: у сервера их полный набор,
893
+ # в манифесте комплекта – тоже, но проверка не должна ломаться на неполном описании строки
894
+ for name in ("ecosystem", "component", "version"):
895
+ if name not in source:
896
+ continue
897
+ given = _text(row.get("current_version")) if name == "version" else _text(row.get(name))
898
+ if given != _text(source.get(name)):
899
+ _fail("SCA-C002", f"{path}.{'current_version' if name == 'version' else name}",
900
+ f"{given!r} вместо {source.get(name)!r} из задания", errors)
901
+ confirmed = _text(_obj(row.get("identity_resolution")).get("coordinates"))
902
+ raw_name, eco = _text(source.get('component')), _text(source.get('ecosystem')).lower()
903
+ same = confirmed == raw_name
904
+ if eco == 'maven' and ':' not in raw_name:
905
+ group, separator, artifact = confirmed.partition(':')
906
+ same = bool(group and separator and artifact == raw_name and ':' not in artifact)
907
+ elif eco == 'npm' and not raw_name.startswith('@'):
908
+ same = same or bool(re.fullmatch(r'@[^/]+/' + re.escape(raw_name), confirmed))
909
+ if confirmed and not same:
910
+ _fail("SCA-C002", f"{path}.identity_resolution.coordinates",
911
+ f"{confirmed!r} не соответствует исходному пакету {raw_name!r}", errors)
912
+ _check_row(row, path, ctx, errors)
913
+ declared = _text(row.get("package_status"))
914
+ computed = row_status(row)
915
+ if declared and declared != computed:
916
+ _fail("SCA-T001", f"{path}.package_status",
917
+ f"заявлено {declared!r}, по проверенным полям {computed!r}", errors)
918
+ missing = [ref for ref in ctx.rows if ref not in seen]
919
+ if missing:
920
+ _fail("SCA-C003", "rows", f"нет строк задания: {', '.join(sorted(missing)[:5])}"
921
+ + (f" и ещё {len(missing) - 5}" if len(missing) > 5 else ""), errors)
922
+ if len(rows) != int(task.get("row_count") or len(rows)):
923
+ _fail("SCA-C003", "rows", f"в ответе {len(rows)} строк, в задании {task.get('row_count')}", errors)
924
+ summary: dict[str, int] = {}
925
+ for row in rows:
926
+ if isinstance(row, dict):
927
+ status = _text(row.get("package_status")) or "?"
928
+ summary[status] = summary.get(status, 0) + 1
929
+ try:
930
+ digest = sha256(canonical(answer))
931
+ except ValueError as exc: # 1e999 и подобное разбирается в число, которое нельзя ни записать, ни посчитать
932
+ _fail("SCA-M001", "ответ", f"ответ не пригоден для отпечатка: {exc}", errors)
933
+ digest = ""
934
+ return Report(ok=not errors, errors=_limited(errors, ctx.limits['reported_errors']), answer=answer, answer_sha256=digest,
935
+ answer_bytes=len(raw), summary=summary)
936
+
937
+
938
+ def _limited(errors: list[dict], limit: int) -> list[dict]:
939
+ """Список ошибок ограничен по числу, но о том, что он неполный, сообщаем явно."""
940
+ if len(errors) <= limit:
941
+ return errors
942
+ kept = errors[:limit]
943
+ kept.append({"code": "SCA-M007", "path": "ответ",
944
+ "message": f"показаны первые {limit} ошибок из {len(errors)}: исправьте их и проверьте снова"})
945
+ return kept
946
+
947
+
948
+ def _check_row(row: dict, path: str, ctx: Context, errors: list[dict]) -> None:
949
+ """Доказательства, объём строки, внутренние номера и очевидные противоречия одной строки."""
950
+ try:
951
+ body = canonical(row)
952
+ except ValueError as exc: # число вне диапазона JSON: строку нельзя ни посчитать, ни сравнить с пределом
953
+ _fail("SCA-M001", path, f"строка не пригодна для проверки: {exc}", errors)
954
+ body = b""
955
+ if len(body) > ctx.limits["row_bytes"]:
956
+ _fail("SCA-M002", path, f"строка ответа {len(body)} байт при пределе {ctx.limits['row_bytes']}", errors)
957
+ evidence = [_text(item.get("evidence_ref")) for item in _list(row.get("evidence")) if isinstance(item, dict)]
958
+ known = {ref for ref in evidence if ref}
959
+
960
+ def refs(owner: str, value: Any, path_to: str, code: str = "SCA-E001") -> None:
961
+ missing = sorted({ref for ref in _list(value) if isinstance(ref, str) and ref not in known})
962
+ if missing:
963
+ _fail(code, path_to, f"ссылки на доказательства без записи в evidence: {', '.join(missing[:5])}",
964
+ errors)
965
+
966
+ identity = _obj(row.get("identity_resolution"))
967
+ refs("identity", identity.get("source_refs"), f"{path}.identity_resolution.source_refs")
968
+ if identity.get("state") == "resolved" and not identity.get("source_refs"):
969
+ _fail("SCA-E001", f"{path}.identity_resolution.source_refs", "подтверждённая идентификация без источника",
970
+ errors)
971
+ needs_basis = ((_text(row.get('ecosystem')) == 'maven' and ':' not in _text(row.get('component')))
972
+ or (_text(row.get('ecosystem')) == 'npm' and not _text(row.get('component')).startswith('@')))
973
+ if identity.get('state') == 'resolved' and needs_basis:
974
+ if not _text(identity.get('basis')):
975
+ _fail('SCA-E001', f'{path}.identity_resolution.basis',
976
+ 'краткое имя требует основания выбора namespace, а не совпадения имени первого кандидата', errors)
977
+ identity_checks = [entry for entry in _list(row.get('research_coverage'))
978
+ if isinstance(entry, dict) and entry.get('purpose') == 'identity'
979
+ and entry.get('status') == 'ok' and entry.get('complete')]
980
+ if not identity_checks:
981
+ _fail('SCA-E001', f'{path}.research_coverage',
982
+ 'не подтверждена проверка идентичности краткого имени и текущей версии', errors)
983
+ latest = _obj(row.get("latest_stable_release"))
984
+ refs("latest", latest.get("source_refs"), f"{path}.latest_stable_release.source_refs")
985
+ if _text(latest.get("version")) and not latest.get("source_refs"):
986
+ _fail("SCA-E001", f"{path}.latest_stable_release.source_refs", "назван последний релиз без источника",
987
+ errors)
988
+ support = _obj(row.get("support_status"))
989
+ refs("support", support.get("source_refs"), f"{path}.support_status.source_refs")
990
+ if _text(support.get("state")) not in ("", "unknown") and not support.get("source_refs"):
991
+ _fail("SCA-E001", f"{path}.support_status.source_refs", "состояние поддержки без источника", errors)
992
+ for index, finding in enumerate(_list(row.get("public_findings"))):
993
+ if not isinstance(finding, dict):
994
+ continue
995
+ owner = f"{path}.public_findings[{index}]"
996
+ refs("finding", finding.get("source_refs"), f"{owner}.source_refs")
997
+ if not finding.get("source_refs"):
998
+ _fail("SCA-E001", f"{owner}.source_refs", "публичная находка без источника", errors)
999
+ evidence_by_ref = {entry.get('evidence_ref'): entry for entry in _list(row.get('evidence'))
1000
+ if isinstance(entry, dict) and isinstance(entry.get('evidence_ref'), str)}
1001
+ urls: set[str] = set()
1002
+ for index, entry in enumerate(_list(row.get('evidence'))):
1003
+ url = _text(_obj(entry).get('url'))
1004
+ if public_url_parts(url) is None:
1005
+ _fail('SCA-E001', f'{path}.evidence[{index}].url', 'нужна однозначная ссылка на публичный источник', errors)
1006
+ if url in urls:
1007
+ _fail('SCA-E001', f'{path}.evidence[{index}].url', 'повтор URL: используйте один evidence_ref в нескольких source_refs', errors)
1008
+ urls.add(url)
1009
+ advice = _obj(row.get('package_advice'))
1010
+ refs('advice', advice.get('source_refs'), f'{path}.package_advice.source_refs')
1011
+ if _text(advice.get('target_version')):
1012
+ publications = [evidence_by_ref.get(ref, {}) for ref in _list(advice.get('source_refs'))]
1013
+ if not any(ev.get('source_type') in ('registry', 'release_notes') for ev in publications):
1014
+ _fail('SCA-E001', f'{path}.package_advice.source_refs',
1015
+ 'целевая версия требует источника публикации: реестр или официальный релиз', errors)
1016
+ for index, entry in enumerate(_list(row.get("research_coverage"))):
1017
+ if not isinstance(entry, dict):
1018
+ continue
1019
+ # запись «искали уязвимости» должна называть, что именно проверяли, и ссылаться на источник:
1020
+ # иначе по названию источника нельзя понять, относится ли проверка к этому пакету
1021
+ owner = f"{path}.research_coverage[{index}]"
1022
+ query = _obj(entry.get("query"))
1023
+ if entry.get('status') == 'ok' and entry.get('complete') and (
1024
+ not _text(query.get('ecosystem')) or not _text(query.get("coordinates")) or not _text(query.get("version"))):
1025
+ _fail("SCA-E001", f"{owner}.query", "проверка уязвимостей без координат и версии: непонятно, что "
1026
+ "проверяли", errors)
1027
+ else: # запрос должен совпадать с тем, что человек смотрит: иначе это вывод о другом пакете
1028
+ resolved = _text(_obj(row.get("identity_resolution")).get("coordinates"))
1029
+ if resolved and _text(query.get("coordinates")) and _text(query.get("coordinates")) != resolved:
1030
+ _fail("SCA-E001", f"{owner}.query.coordinates",
1031
+ f"{_text(query.get('coordinates'))!r} вместо {resolved!r} – проверяли другой пакет", errors)
1032
+ if _text(query.get("version")) and _text(query.get("version")) != _text(row.get("current_version")):
1033
+ _fail("SCA-E001", f"{owner}.query.version",
1034
+ f"{_text(query.get('version'))!r} вместо {_text(row.get('current_version'))!r} из задания",
1035
+ errors)
1036
+ if _text(query.get('ecosystem')) and _text(query.get('ecosystem')) != _text(row.get('ecosystem')):
1037
+ _fail('SCA-E001', f'{owner}.query.ecosystem', 'запрос относится к другой экосистеме', errors)
1038
+ refs("coverage", entry.get("source_refs"), f"{owner}.source_refs")
1039
+ if entry.get('status') == 'ok' and entry.get('complete') and not _list(entry.get("source_refs")):
1040
+ _fail("SCA-E001", f"{owner}.source_refs", "проверка уязвимостей без источника", errors)
1041
+ def fix_status_ok(status: Any, owner: str) -> None:
1042
+ state = _obj(status)
1043
+ refs("fix", state.get("source_refs"), f"{owner}.source_refs")
1044
+ if state.get("status") in ("fixed", "no_fix_published") and not _list(state.get("source_refs")):
1045
+ _fail("SCA-E001", f"{owner}.source_refs", "утверждение об исправлении без источника", errors)
1046
+ if state.get("scope") == "branch" and not _text(state.get("branch")):
1047
+ _fail("SCA-E001", f"{owner}.branch", "scope=branch требует ветку (префикс версий)", errors)
1048
+ if state.get("status") == "no_fix_published":
1049
+ proofs = [evidence_by_ref.get(ref, {}) for ref in _list(state.get("source_refs"))]
1050
+ if not any(p.get("source_type") in ("advisory", "issue_tracker") and _text(p.get("quote"))
1051
+ and _text(p.get("checked_at")) for p in proofs):
1052
+ _fail("SCA-E001", f"{owner}.source_refs", "«исправления нет» требует бюллетеня или трекера с "
1053
+ "выдержкой и датой проверки", errors)
1054
+
1055
+ for index, finding in enumerate(_list(row.get("public_findings"))):
1056
+ owner = f"{path}.public_findings[{index}]"
1057
+ finding = _obj(finding)
1058
+ if "fix_status" in finding and finding.get("fix_status") is not None:
1059
+ fix_status_ok(finding.get("fix_status"), f"{owner}.fix_status")
1060
+ disputed = _obj(finding.get("disputed"))
1061
+ refs("disputed", disputed.get("source_refs"), f"{owner}.disputed.source_refs")
1062
+ if disputed and not _list(disputed.get("source_refs")):
1063
+ _fail("SCA-E001", f"{owner}.disputed.source_refs", "оспоренность без источника", errors)
1064
+ for k, position in enumerate(_list(finding.get("source_positions"))):
1065
+ refs("position", _obj(position).get("source_refs"), f"{owner}.source_positions[{k}].source_refs")
1066
+ if not _list(_obj(position).get("source_refs")):
1067
+ _fail("SCA-E001", f"{owner}.source_positions[{k}].source_refs", "позиция источника без ссылки",
1068
+ errors)
1069
+ for index, check in enumerate(_list(row.get("version_checks"))):
1070
+ check = _obj(check)
1071
+ owner = f"{path}.version_checks[{index}]"
1072
+ version = _text(check.get("version"))
1073
+ resolved = _text(_obj(row.get("identity_resolution")).get("coordinates"))
1074
+ for k, entry in enumerate(_list(check.get("coverage"))):
1075
+ entry = _obj(entry)
1076
+ query = _obj(entry.get("query"))
1077
+ where = f"{owner}.coverage[{k}]"
1078
+ # те же требования, что у охвата текущей версии: что проверяли, по какому пакету и источнику
1079
+ if entry.get("status") == "ok" and entry.get("complete") and (
1080
+ not _text(query.get("ecosystem")) or not _text(query.get("coordinates"))
1081
+ or not _text(query.get("version"))):
1082
+ _fail("SCA-E001", f"{where}.query", "проверка версии без координат и версии: непонятно, что "
1083
+ "проверяли", errors)
1084
+ if _text(query.get("version")) and _text(query.get("version")) != version:
1085
+ _fail("SCA-E001", f"{where}.query.version",
1086
+ f"{_text(query.get('version'))!r} вместо проверяемой версии {version!r}", errors)
1087
+ if resolved and _text(query.get("coordinates")) and _text(query.get("coordinates")) != resolved:
1088
+ _fail("SCA-E001", f"{where}.query.coordinates", "проверяли другой пакет", errors)
1089
+ if _text(query.get("ecosystem")) and _text(query.get("ecosystem")) != _text(row.get("ecosystem")):
1090
+ _fail("SCA-E001", f"{where}.query.ecosystem", "запрос относится к другой экосистеме", errors)
1091
+ refs("coverage", entry.get("source_refs"), f"{where}.source_refs")
1092
+ if entry.get("status") == "ok" and entry.get("complete") and not _list(entry.get("source_refs")):
1093
+ _fail("SCA-E001", f"{where}.source_refs", "проверка версии без источника", errors)
1094
+ for k, finding in enumerate(_list(check.get("findings"))):
1095
+ finding = _obj(finding)
1096
+ refs("finding", finding.get("source_refs"), f"{owner}.findings[{k}].source_refs")
1097
+ if not finding.get("source_refs"):
1098
+ _fail("SCA-E001", f"{owner}.findings[{k}].source_refs", "находка проверки версии без источника",
1099
+ errors)
1100
+ if finding.get("fix_status") is not None and "fix_status" in finding:
1101
+ fix_status_ok(finding.get("fix_status"), f"{owner}.findings[{k}].fix_status")
1102
+ # находка проверки версии описывает уязвимость, затрагивающую именно эту версию: интервалы корректны,
1103
+ # и проверяемая версия не исключена ни одним из них
1104
+ intervals = [_obj(r) for r in _list(finding.get("ranges"))]
1105
+ for interval in intervals:
1106
+ start = _text(interval.get("introduced"))
1107
+ if start and start != "0":
1108
+ for end, inclusive in (("fixed", False), ("last_affected", True)):
1109
+ order = compare_versions(_text(row.get("ecosystem")), start, _text(interval.get(end)))
1110
+ if order is not None and (order > 0 or (order == 0 and not inclusive)):
1111
+ _fail("SCA-A001", f"{owner}.findings[{k}].ranges", "пустой или обратный диапазон", errors)
1112
+ hits = [range_contains(_text(row.get("ecosystem")), version, r) for r in intervals]
1113
+ if intervals and hits and all(hit is False for hit in hits):
1114
+ _fail("SCA-A001", f"{owner}.findings[{k}].ranges",
1115
+ f"диапазоны находки исключают проверяемую версию {version}", errors)
1116
+ for match in _AST.finditer(body.decode("utf-8", "replace")):
1117
+ _fail("SCA-A001", path, f"внутренний номер соответствия {match.group(0)!r} в ответе по компоненту",
1118
+ errors)
1119
+ if not _list(row.get("research_coverage")):
1120
+ # нет ни проверенных источников, ни находок, ни доказательств – это незаполненная заготовка, а не
1121
+ # исследование: принять её можно было бы, только выдав пустой ответ за результат
1122
+ _fail("SCA-L001", path, "нет протокола попыток проверки источников: строка не исследована", errors)
1123
+ if row.get('package_status') in ('incomplete', 'identity_unresolved') and not _list(row.get('gaps')):
1124
+ _fail('SCA-L001', f'{path}.gaps', 'неполный результат требует конкретной причины', errors)
1125
+ if any(isinstance(gap, dict) and gap.get('code') == 'NOT_RESEARCHED' for gap in _list(row.get('gaps'))):
1126
+ _fail('SCA-L001', f'{path}.gaps', 'незаполненная заготовка не является выполненным исследованием', errors)
1127
+ _contradictions(row, path, errors)
1128
+
1129
+
1130
+ def _contradictions(row: dict, path: str, errors: list[dict]) -> None:
1131
+ """Очевидные противоречия между полями: их проверяет программа, а не доверие к тексту агента."""
1132
+ identity = _obj(row.get("identity_resolution"))
1133
+ state = _text(identity.get("state"))
1134
+ coordinates = _text(identity.get("coordinates"))
1135
+ if state == "resolved" and not coordinates:
1136
+ _fail("SCA-L001", f"{path}.identity_resolution.coordinates", "идентичность подтверждена, а координат нет",
1137
+ errors)
1138
+ if state in ("ambiguous", "unresolved") and coordinates:
1139
+ _fail("SCA-L001", f"{path}.identity_resolution.coordinates",
1140
+ f"идентичность {state}, а координаты указаны", errors)
1141
+ latest = _text(_obj(row.get("latest_stable_release")).get("version"))
1142
+ update = _text(row.get("update_status"))
1143
+ current = _text(row.get("current_version"))
1144
+ latest_order = compare_versions(_text(row.get('ecosystem')), latest, current)
1145
+ if update == 'up_to_date' and (not latest or not _obj(row.get('latest_stable_release')).get('source_refs')):
1146
+ _fail('SCA-E001', f'{path}.latest_stable_release.source_refs', 'актуальность версии требует последнего релиза и источника', errors)
1147
+ if update == "up_to_date" and latest and latest_order != 0:
1148
+ _fail("SCA-L001", f"{path}.update_status", f"up_to_date, а последний релиз {latest} отличается от {current}",
1149
+ errors)
1150
+ if update == "update_available" and not latest:
1151
+ _fail("SCA-L001", f"{path}.update_status", "доступно обновление, но версия не названа", errors)
1152
+ if update == "update_available" and latest and latest_order is not None and latest_order != 1:
1153
+ _fail("SCA-L001", f"{path}.update_status",
1154
+ f"не подтверждён порядок версий {current} → {latest}: используйте unknown и пояснение", errors)
1155
+ advice = _obj(row.get("package_advice"))
1156
+ action = _text(advice.get("action"))
1157
+ target = _text(advice.get("target_version"))
1158
+ if action == "update" and not target:
1159
+ _fail("SCA-L001", f"{path}.package_advice.target_version", "действие «обновить» без версии", errors)
1160
+ if target and target == current:
1161
+ _fail("SCA-L001", f"{path}.package_advice.target_version",
1162
+ f"советуемая версия совпадает с текущей {current}: обновлять нечего", errors)
1163
+ target_order = compare_versions(_text(row.get('ecosystem')), target, current)
1164
+ if action == 'update' and target and target_order is not None and target_order != 1:
1165
+ _fail("SCA-L001", f"{path}.package_advice.target_version",
1166
+ f"версия {target} не подтверждена как более новая, чем {current}; поясните кандидат без совета update", errors)
1167
+ if state != 'resolved' and (latest or update != 'unknown' or target
1168
+ or _obj(row.get('support_status')).get('state') != 'unknown'
1169
+ or _list(row.get('public_findings'))):
1170
+ _fail('SCA-L001', path, 'неразрешённой идентичности нельзя приписывать факты о пакете-кандидате', errors)
1171
+ if action == "replace" and not _text(advice.get("compatibility_notes")):
1172
+ _fail("SCA-L001", f"{path}.package_advice.compatibility_notes", "замена без указания заменяющего пакета",
1173
+ errors)
1174
+ if action == "needs_identity" and state == "resolved":
1175
+ _fail("SCA-L001", f"{path}.package_advice.action", "действие «нужна идентификация» при подтверждённой "
1176
+ "идентичности", errors)
1177
+ applicable = [item for item in _list(row.get("public_findings"))
1178
+ if isinstance(item, dict) and item.get("applies") == "yes"]
1179
+ for index, finding in enumerate(_list(row.get('public_findings'))):
1180
+ if not isinstance(finding, dict) or not finding.get('ranges'):
1181
+ continue
1182
+ matches = [range_contains(_text(row.get('ecosystem')), current, _obj(r)) for r in _list(finding.get('ranges'))]
1183
+ known = True if True in matches else (None if None in matches else False)
1184
+ applies = finding.get('applies')
1185
+ owner = f'{path}.public_findings[{index}].ranges'
1186
+ for interval in _list(finding.get('ranges')):
1187
+ interval = _obj(interval)
1188
+ start = _text(interval.get('introduced'))
1189
+ if start and start != '0':
1190
+ for end, inclusive in (('fixed',False), ('last_affected',True)):
1191
+ order = compare_versions(_text(row.get('ecosystem')), start, _text(interval.get(end)))
1192
+ if order is not None and (order > 0 or (order == 0 and not inclusive)):
1193
+ _fail('SCA-A001', owner, 'пустой или обратный диапазон не доказывает неприменимость', errors)
1194
+ if known is None:
1195
+ if applies != 'unknown' or not any(_obj(g).get('code')=='APPLICABILITY_UNCLEAR' for g in _list(row.get('gaps'))):
1196
+ _fail('SCA-A001', owner, 'порядок версий не проверен: нужны applies=unknown и gap APPLICABILITY_UNCLEAR', errors)
1197
+ elif applies in ('yes','no') and (applies == 'yes') != known:
1198
+ _fail('SCA-A001', owner, f'вывод applies={applies} противоречит диапазону для текущей версии {current}', errors)
1199
+ if applicable and action in ("keep", "no_action", "remove"):
1200
+ if not _text(advice.get("compatibility_notes")) and not _list(advice.get("remaining_risks")):
1201
+ _fail("SCA-L001", f"{path}.package_advice",
1202
+ f"при применимых уязвимостях ({len(applicable)}) действие {action!r} не объяснено", errors)
1203
+
1204
+
1205
+ def range_contains(ecosystem: str, current: str, interval: Mapping[str, Any]) -> bool | None:
1206
+ """Нижняя граница включена, fixed исключена, last_affected включена. None означает неизвестность. introduced="0" –
1207
+ от первой версии; без fixed и last_affected такой диапазон затрагивает все версии (как в OSV), а пустой интервал
1208
+ без границ остаётся неизвестностью."""
1209
+ bounds = []
1210
+ start = _text(interval.get('introduced'))
1211
+ if start == '0' and not _text(interval.get('fixed')) and not _text(interval.get('last_affected')):
1212
+ return True
1213
+ if start and start != '0':
1214
+ order = compare_versions(ecosystem,current,start)
1215
+ bounds.append(None if order is None else order >= 0)
1216
+ for name, inclusive in (('fixed',False),('last_affected',True)):
1217
+ end = _text(interval.get(name))
1218
+ if end:
1219
+ order = compare_versions(ecosystem,current,end)
1220
+ bounds.append(None if order is None else (order <= 0 if inclusive else order < 0))
1221
+ if False in bounds:
1222
+ return False
1223
+ return None if None in bounds or not bounds else True
1224
+
1225
+
1226
+ # ------------------------------------------------------------------ командная проверка из комплекта
1227
+
1228
+ EXIT_OK = 0
1229
+ EXIT_CONTRACT = 2
1230
+ EXIT_TECHNICAL = 3
1231
+
1232
+
1233
+ def _load(path: str) -> Any:
1234
+ try:
1235
+ raw = Path(path).read_bytes()
1236
+ except OSError as exc:
1237
+ raise ValueError(f"не удалось прочитать {path}: {exc.strerror or exc}") from exc
1238
+ return json.loads(raw.decode("utf-8-sig"))
1239
+
1240
+
1241
+ def main(argv: list[str] | None = None) -> int:
1242
+ """python validate.py --manifest manifest.json --answer answer.json [--report report.json]
1243
+
1244
+ 0 – ответ принят, 2 – нарушения контракта (полный отчёт в stdout и в файле отчёта), 3 – техническая
1245
+ ошибка проверки (нечитаемый манифест или файл ответа)."""
1246
+ for stream in (sys.stdout, sys.stderr): # консоль агента может быть не в UTF-8: отчёт читает человек
1247
+ try:
1248
+ stream.reconfigure(encoding="utf-8", errors="replace") # type: ignore[attr-defined]
1249
+ except (AttributeError, ValueError):
1250
+ pass
1251
+ parser = argparse.ArgumentParser(prog="validate.py", add_help=True,
1252
+ description="Проверка ответа по исследованию компонентов SCA.")
1253
+ parser.add_argument("--manifest", required=True, help="manifest.json из комплекта задания")
1254
+ parser.add_argument("--answer", required=True, help="answer.json с ответом агента")
1255
+ parser.add_argument("--report", default="", help="куда записать машинный отчёт об ошибках (JSON)")
1256
+ parser.add_argument("--base", default="", help="сегодняшняя дата для проверки дат (YYYY-MM-DD)")
1257
+ args = parser.parse_args(argv)
1258
+ try:
1259
+ manifest = _load(args.manifest)
1260
+ answer_bytes = Path(args.answer).read_bytes()
1261
+ except (OSError, ValueError) as exc:
1262
+ print(f"Техническая ошибка: {exc}", file=sys.stderr)
1263
+ return EXIT_TECHNICAL
1264
+ if not isinstance(manifest, dict) or not isinstance(manifest.get("rows"), list):
1265
+ print("Техническая ошибка: в манифесте нет списка rows", file=sys.stderr)
1266
+ return EXIT_TECHNICAL
1267
+ base = date.today()
1268
+ if args.base:
1269
+ try:
1270
+ base = date.fromisoformat(args.base)
1271
+ except ValueError:
1272
+ print(f"Техническая ошибка: неверная дата --base {args.base!r}", file=sys.stderr)
1273
+ return EXIT_TECHNICAL
1274
+ task = {"task_id": manifest.get("task_id", ""), "manifest_sha256": manifest.get("manifest_sha256", ""),
1275
+ "row_count": manifest.get("row_count", len(manifest["rows"])), "rows": manifest["rows"]}
1276
+ report = validate_answer(answer_bytes, task, today=base)
1277
+ print(report.text())
1278
+ if args.report:
1279
+ try:
1280
+ Path(args.report).write_text(json.dumps(report.as_dict(), ensure_ascii=False, indent=2) + "\n",
1281
+ encoding="utf-8")
1282
+ except OSError as exc:
1283
+ print(f"Техническая ошибка: отчёт не записан: {exc}", file=sys.stderr)
1284
+ return EXIT_TECHNICAL
1285
+ return EXIT_OK if report.ok else EXIT_CONTRACT
1286
+
1287
+
1288
+ if __name__ == "__main__": # комплект задания: python validate.py --manifest ... --answer ...
1289
+ sys.exit(main())