timecs 2.0.0__py3-none-any.whl

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 (94) hide show
  1. app.py +3014 -0
  2. ast_scanner.py +36187 -0
  3. banner.py +146 -0
  4. ci_reporter.py +570 -0
  5. cli.py +2347 -0
  6. config_loader.py +307 -0
  7. cross_file_engine.py +1781 -0
  8. delivery_models.py +145 -0
  9. delivery_repository.py +78 -0
  10. diff_scan.py +127 -0
  11. durable_delivery_sink.py +103 -0
  12. event_bus.py +155 -0
  13. event_publisher.py +345 -0
  14. event_taxonomy.py +313 -0
  15. function_summarizer.py +354 -0
  16. html_auditor.py +274 -0
  17. iac_auditor.py +400 -0
  18. in_app_adapter.py +115 -0
  19. js_scanner.py +895 -0
  20. manifest_parser.py +960 -0
  21. master_rules_bank.py +389 -0
  22. notification_models.py +346 -0
  23. notification_policy.py +309 -0
  24. notification_repository.py +118 -0
  25. notification_routes.py +394 -0
  26. notification_service.py +199 -0
  27. osv_client.py +437 -0
  28. remediation/__init__.py +39 -0
  29. remediation/base.py +102 -0
  30. remediation/contracts.py +196 -0
  31. remediation/cwe1188_binding.py +78 -0
  32. remediation/cwe1336_jinja.py +91 -0
  33. remediation/cwe22_path_traversal.py +348 -0
  34. remediation/cwe295_ssl.py +87 -0
  35. remediation/cwe327_weak_hash.py +78 -0
  36. remediation/cwe377_tempfile.py +77 -0
  37. remediation/cwe489_debug.py +80 -0
  38. remediation/cwe502_yaml.py +89 -0
  39. remediation/cwe614_cookie.py +91 -0
  40. remediation/cwe78_cmdi.py +415 -0
  41. remediation/cwe798_credentials.py +153 -0
  42. remediation/cwe89_sqli.py +425 -0
  43. remediation/cwe916_password_hash.py +131 -0
  44. remediation/cwe95_eval.py +77 -0
  45. remediation/dispatcher.py +114 -0
  46. remediation/orchestrator.py +541 -0
  47. remediation/patch_engine.py +213 -0
  48. remediation/verification.py +253 -0
  49. rule_engine.py +1535 -0
  50. sarif_adapter.py +719 -0
  51. sarif_exporter.py +88 -0
  52. sca_reachability/__init__.py +28 -0
  53. sca_reachability/ast_analyzer.py +366 -0
  54. sca_reachability/call_graph.py +203 -0
  55. sca_reachability/contracts.py +365 -0
  56. sca_reachability/dist_import_map.py +46 -0
  57. sca_reachability/engine.py +603 -0
  58. sca_reachability/resolver.py +169 -0
  59. scanners/__init__.py +70 -0
  60. scanners/container_scanner.py +323 -0
  61. scanners/cve_index.py +521 -0
  62. scanners/iac_scanner.py +328 -0
  63. scanners/sbom.py +183 -0
  64. scanners/sca_scanner.py +667 -0
  65. scanners/secret_scanner.py +345 -0
  66. scanners/yaml_lite.py +217 -0
  67. secret_filters.py +435 -0
  68. secret_scanner.py +943 -0
  69. sqlite_delivery_repository.py +277 -0
  70. sqlite_notification_repository.py +441 -0
  71. ssrf_guard.py +276 -0
  72. staged_scanner.py +492 -0
  73. suppression_resolver.py +282 -0
  74. symbol_indexer.py +424 -0
  75. tcs/__init__.py +1 -0
  76. tcs/analysis/__init__.py +1 -0
  77. tcs/analysis/def_use.py +408 -0
  78. tcs/analysis/function_contracts.py +290 -0
  79. tcs/parallel_analyzer.py +276 -0
  80. tcs/parallel_scanner.py +630 -0
  81. tcs/treesitter_packer.py +1446 -0
  82. tcs_cli.py +2086 -0
  83. tcs_config.py +218 -0
  84. tcs_gui.py +2123 -0
  85. timecs-2.0.0.dist-info/METADATA +142 -0
  86. timecs-2.0.0.dist-info/RECORD +94 -0
  87. timecs-2.0.0.dist-info/WHEEL +5 -0
  88. timecs-2.0.0.dist-info/entry_points.txt +4 -0
  89. timecs-2.0.0.dist-info/licenses/LICENSE +201 -0
  90. timecs-2.0.0.dist-info/top_level.txt +49 -0
  91. version_matcher.py +934 -0
  92. webhook_adapter.py +495 -0
  93. webhook_client.py +483 -0
  94. webhook_formatters.py +245 -0
@@ -0,0 +1,328 @@
1
+ """CI/CD and Infrastructure-as-Code security scanner -- stdlib only.
2
+
3
+ Four rules over three artefact families. The existing CWE-1357 unpinned-action check lives in
4
+ ``iac_auditor.audit_workflow`` and is deliberately NOT reimplemented or touched here: this module
5
+ adds the injection, permission, privilege and exposure rules beside it.
6
+
7
+ * CWE-78 ``GHA_SCRIPT_INJECTION`` -- a ``run:`` shell script interpolates an untrusted pull-request,
8
+ issue, comment or review expression. Routing that expression through a step ``env:`` variable and
9
+ quoting ``"$VAR"`` in the script is the safe spelling, and it is safe precisely because the
10
+ expression no longer appears in the script text at all.
11
+ * CWE-269 ``GHA_EXCESSIVE_PERMISSIONS_OR_PWN_REQUEST`` -- ``permissions: write-all``, or a
12
+ ``pull_request_target`` workflow that checks out the untrusted PR head.
13
+ * CWE-250 ``K8S_PRIVILEGED_CONTAINER`` -- a workload manifest asks for ``privileged``,
14
+ ``allowPrivilegeEscalation``, ``hostNetwork``, ``hostPID`` or ``runAsUser: 0``.
15
+ * CWE-732 ``IAC_PUBLIC_EXPOSURE`` -- a Terraform S3 bucket is public-read, or a security group opens
16
+ SSH/RDP to ``0.0.0.0/0``.
17
+
18
+ Every decision reads a parsed node or a parsed HCL block, never a whole-file pattern sweep, and an
19
+ unresolvable value is left alone rather than guessed at.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import re
25
+ from typing import Any, Dict, Iterator, List, Optional, Sequence, Set, Tuple
26
+
27
+ from . import yaml_lite
28
+
29
+ __all__ = ["is_iac_security_path", "is_workflow_yaml_path", "is_terraform_path",
30
+ "is_kubernetes_manifest", "audit_iac_security_files"]
31
+
32
+ WORKFLOW_SUFFIXES = (".yml", ".yaml")
33
+ KIND_WORKLOADS = frozenset({"Pod", "Deployment", "DaemonSet", "StatefulSet", "Job", "CronJob"})
34
+
35
+ # Expressions an outside contributor controls. `github.sha` and `github.ref` on a push are the
36
+ # repository's own code and are deliberately absent.
37
+ UNTRUSTED_EXPRESSIONS = (
38
+ "github.event.issue.title",
39
+ "github.event.issue.body",
40
+ "github.event.pull_request.title",
41
+ "github.event.pull_request.body",
42
+ "github.event.comment.body",
43
+ "github.event.review.body",
44
+ "github.head_ref",
45
+ )
46
+ PR_HEAD_EXPRESSIONS = (
47
+ "github.event.pull_request.head.sha",
48
+ "github.event.pull_request.head.ref",
49
+ )
50
+ _EXPRESSION_RE = re.compile(r"\$\{\{(.+?)\}\}", re.DOTALL)
51
+
52
+ K8S_TRUE_FLAGS = frozenset({"privileged", "allowPrivilegeEscalation", "hostNetwork", "hostPID"})
53
+ PUBLIC_ACLS = frozenset({"public-read", "public-read-write"})
54
+ WORLD_CIDRS = frozenset({"0.0.0.0/0", "::/0"})
55
+ ADMIN_PORTS = frozenset({22, 3389})
56
+
57
+ _TF_RESOURCE_RE = re.compile(r'^resource\s+"([^"]+)"\s+"([^"]+)"\s*\{')
58
+ _TF_ATTR_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$")
59
+ _TF_STRING_RE = re.compile(r'"([^"]*)"')
60
+
61
+
62
+ def is_workflow_yaml_path(path: str) -> bool:
63
+ normalized = str(path).replace("\\", "/").lower()
64
+ if not normalized.endswith(WORKFLOW_SUFFIXES):
65
+ return False
66
+ parts = normalized.split("/")
67
+ for index, part in enumerate(parts[:-1]):
68
+ if part == ".github" and index + 1 < len(parts) - 1 and parts[index + 1] == "workflows":
69
+ return True
70
+ return False
71
+
72
+
73
+ def is_terraform_path(path: str) -> bool:
74
+ return str(path).replace("\\", "/").lower().endswith(".tf")
75
+
76
+
77
+ def is_iac_security_path(path: str) -> bool:
78
+ """The path-decidable half of this family: GitHub Actions workflows and Terraform.
79
+
80
+ Kubernetes is deliberately not here -- a workload manifest can sit at any path, so it is
81
+ claimed by ``is_kubernetes_manifest`` on content instead of on a directory name.
82
+ """
83
+ return is_workflow_yaml_path(path) or is_terraform_path(path)
84
+
85
+
86
+ def is_kubernetes_manifest(source: str) -> bool:
87
+ # Cheap literal pre-guard: discovery offers every YAML document in a tree to this sniff, and
88
+ # parsing an unrelated config file to learn it is not a manifest is wasted work.
89
+ if "apiVersion" not in source or "kind" not in source:
90
+ return False
91
+ root = yaml_lite.parse(source)
92
+ if not isinstance(root, yaml_lite.Mapping):
93
+ return False
94
+ kind = yaml_lite.get(root, "kind")
95
+ version = yaml_lite.get(root, "apiVersion")
96
+ return (isinstance(kind, yaml_lite.Scalar) and isinstance(version, yaml_lite.Scalar)
97
+ and kind.text.strip() in KIND_WORKLOADS and bool(version.text.strip()))
98
+
99
+
100
+ def _finding(file_path: str, line: int, cwe: str, category: str, severity: str, message: str) -> Dict[str, Any]:
101
+ return {
102
+ "file": file_path,
103
+ "line": max(1, int(line)),
104
+ "cwe": cwe,
105
+ "severity": severity,
106
+ "category": category,
107
+ "message": f"{cwe}: {message}",
108
+ }
109
+
110
+
111
+ def _matching_lines(raw_lines: Sequence[str], node: Any, needle: str) -> Iterator[int]:
112
+ """Exact source lines inside a node's span that contain ``needle``.
113
+
114
+ A block scalar's text is joined, so its line offsets are not arithmetic; the span is read back
115
+ against the source instead, which keeps every reported line inside the node it belongs to.
116
+ """
117
+ start = getattr(node, "lineno", 1)
118
+ end = getattr(node, "end_lineno", start)
119
+ for lineno in range(start, min(end, len(raw_lines)) + 1):
120
+ if needle in raw_lines[lineno - 1]:
121
+ yield lineno
122
+
123
+
124
+ # ── GitHub Actions ────────────────────────────────────────────────────────
125
+ def _triggers(root: Any) -> Set[str]:
126
+ # `on` is a YAML 1.1 boolean, so PyYAML hands back True; yaml_lite keeps the literal spelling.
127
+ node = yaml_lite.get(root, "on")
128
+ if node is None:
129
+ node = yaml_lite.get(root, "True")
130
+ names: Set[str] = set()
131
+ if isinstance(node, yaml_lite.Scalar):
132
+ names.update(part.strip() for part in node.text.split(",") if part.strip())
133
+ elif isinstance(node, yaml_lite.Sequence):
134
+ for _lineno, item in node.items:
135
+ names.add(yaml_lite.scalar_text(item).strip())
136
+ elif isinstance(node, yaml_lite.Mapping):
137
+ names.update(key for key, _lineno, _value in node.items)
138
+ return names
139
+
140
+
141
+ def _run_nodes(root: Any) -> Iterator[Any]:
142
+ for path, _lineno, node in yaml_lite.walk(root):
143
+ if path and path[-1] == "run" and isinstance(node, yaml_lite.Scalar):
144
+ yield node
145
+
146
+
147
+ def _gha_script_injection(file_path: str, root: Any, raw_lines: Sequence[str]) -> List[Dict[str, Any]]:
148
+ findings: List[Dict[str, Any]] = []
149
+ for node in _run_nodes(root):
150
+ reported: Set[int] = set()
151
+ for expression in UNTRUSTED_EXPRESSIONS:
152
+ for lineno in _matching_lines(raw_lines, node, expression):
153
+ if lineno in reported:
154
+ continue
155
+ line_text = raw_lines[lineno - 1]
156
+ if not _EXPRESSION_RE.search(line_text):
157
+ continue
158
+ reported.add(lineno)
159
+ findings.append(_finding(
160
+ file_path, lineno, "CWE-78", "GHA_SCRIPT_INJECTION", "HIGH",
161
+ f"run: interpolates ${{{{ {expression} }}}} straight into a shell script, so a"
162
+ " pull-request or issue title can close the quote and execute arbitrary commands"
163
+ " on the runner. Assign the expression to a step env: variable and reference it"
164
+ ' as "$VAR" so the shell never parses attacker text'))
165
+ return findings
166
+
167
+
168
+ def _gha_permissions(file_path: str, root: Any, raw_lines: Sequence[str]) -> List[Dict[str, Any]]:
169
+ findings: List[Dict[str, Any]] = []
170
+ for path, _lineno, node in yaml_lite.walk(root):
171
+ if not path or path[-1] != "permissions" or not isinstance(node, yaml_lite.Scalar):
172
+ continue
173
+ if node.text.strip().lower() != "write-all":
174
+ continue
175
+ scope = "workflow" if len(path) == 1 else f"job {path[1]}"
176
+ findings.append(_finding(
177
+ file_path, node.lineno, "CWE-269", "GHA_EXCESSIVE_PERMISSIONS_OR_PWN_REQUEST", "HIGH",
178
+ f"{scope} grants permissions: write-all, giving the GITHUB_TOKEN write access to every"
179
+ " scope including contents and packages. Grant only the scopes the job actually uses"))
180
+ if "pull_request_target" not in _triggers(root):
181
+ return findings
182
+ for _path, _lineno, node in yaml_lite.walk(root):
183
+ if not isinstance(node, yaml_lite.Scalar):
184
+ continue
185
+ for expression in PR_HEAD_EXPRESSIONS:
186
+ for lineno in _matching_lines(raw_lines, node, expression):
187
+ findings.append(_finding(
188
+ file_path, lineno, "CWE-269", "GHA_EXCESSIVE_PERMISSIONS_OR_PWN_REQUEST", "CRITICAL",
189
+ f"pull_request_target runs with the base repository's token and secrets, and this"
190
+ f" line checks out {expression} -- the contributor's untrusted code. That"
191
+ " combination executes attacker code with write permissions. Use"
192
+ " pull_request, or drop the checkout of the PR head"))
193
+ return findings
194
+
195
+
196
+ # ── Kubernetes ────────────────────────────────────────────────────────────
197
+ def _kubernetes_privileges(file_path: str, root: Any) -> List[Dict[str, Any]]:
198
+ findings: List[Dict[str, Any]] = []
199
+ kind = yaml_lite.scalar_text(yaml_lite.get(root, "kind")).strip()
200
+ for path, _lineno, node in yaml_lite.walk(root):
201
+ if not path or not isinstance(node, yaml_lite.Scalar):
202
+ continue
203
+ key = path[-1]
204
+ value = node.text.strip().strip("'\"").lower()
205
+ if key in K8S_TRUE_FLAGS and value == "true":
206
+ findings.append(_finding(
207
+ file_path, node.lineno, "CWE-250", "K8S_PRIVILEGED_CONTAINER", "HIGH",
208
+ f"{kind} sets {key}: true, which removes the container's isolation from the host."
209
+ f" Set {key}: false and grant only the specific capability the workload needs"))
210
+ elif key == "runAsUser" and value == "0":
211
+ findings.append(_finding(
212
+ file_path, node.lineno, "CWE-250", "K8S_PRIVILEGED_CONTAINER", "HIGH",
213
+ f"{kind} sets runAsUser: 0, so the workload runs as root inside the container."
214
+ " Set runAsNonRoot: true and a non-zero runAsUser"))
215
+ return findings
216
+
217
+
218
+ # ── Terraform (HCL) ───────────────────────────────────────────────────────
219
+ def _hcl_blocks(source: str) -> List[Tuple[str, int, int, int]]:
220
+ """[(header, header_lineno, body_first_line, body_last_line)] for every brace block.
221
+
222
+ Comments are dropped before brace counting so a ``}`` inside a comment cannot close a block.
223
+ A header is the text preceding ``{`` on its own line: carrying it across lines would glue an
224
+ attribute (`name = "open"`) onto the next block's header and hide every nested `ingress`.
225
+ """
226
+ blocks: List[Tuple[str, int, int, int]] = []
227
+ stack: List[Tuple[str, int, int]] = []
228
+ for lineno, raw in enumerate(source.splitlines(), start=1):
229
+ line = re.sub(r"#.*$|//.*$", "", raw)
230
+ pending: List[str] = []
231
+ for part in re.split(r"([{}])", line):
232
+ if part == "{":
233
+ stack.append(("".join(pending).strip(), lineno, lineno))
234
+ pending = []
235
+ elif part == "}":
236
+ if stack:
237
+ header, start_line, body_start = stack.pop()
238
+ blocks.append((header, start_line, body_start, lineno))
239
+ pending = []
240
+ elif part.strip():
241
+ pending.append(part)
242
+ return blocks
243
+
244
+
245
+ def _body_lines(source_lines: Sequence[str], body_start: int, body_end: int) -> List[Tuple[int, str]]:
246
+ return [(lineno, source_lines[lineno - 1])
247
+ for lineno in range(body_start, min(body_end, len(source_lines)) + 1)]
248
+
249
+
250
+ def _terraform_exposure(file_path: str, source: str) -> List[Dict[str, Any]]:
251
+ findings: List[Dict[str, Any]] = []
252
+ lines = source.splitlines()
253
+ blocks = _hcl_blocks(source)
254
+ resources: List[Tuple[str, str, int, int, int]] = []
255
+ for header, header_line, body_start, body_end in blocks:
256
+ match = _TF_RESOURCE_RE.match(header + " {")
257
+ if match:
258
+ resources.append((match.group(1), match.group(2), header_line, body_start, body_end))
259
+ for kind, name, _header_line, body_start, body_end in resources:
260
+ body = _body_lines(lines, body_start, body_end)
261
+ if kind in ("aws_s3_bucket", "aws_s3_bucket_acl"):
262
+ for lineno, text in body:
263
+ attr = _TF_ATTR_RE.match(text)
264
+ if not attr or attr.group(1) != "acl":
265
+ continue
266
+ strings = _TF_STRING_RE.findall(attr.group(2))
267
+ if any(value.strip().lower() in PUBLIC_ACLS for value in strings):
268
+ findings.append(_finding(
269
+ file_path, lineno, "CWE-732", "IAC_PUBLIC_EXPOSURE", "HIGH",
270
+ f'{kind}.{name} sets acl = "{strings[0]}", exposing the bucket to anonymous'
271
+ ' readers. Set acl = "private" and grant access through a bucket policy'))
272
+ elif kind == "aws_security_group":
273
+ for header, ingress_line, ingress_start, ingress_end in blocks:
274
+ if header.split()[0:1] != ["ingress"]:
275
+ continue
276
+ if not (body_start <= ingress_line and ingress_end <= body_end):
277
+ continue
278
+ ingress_body = _body_lines(lines, ingress_start, ingress_end)
279
+ ports: List[int] = []
280
+ world: List[int] = []
281
+ for lineno, text in ingress_body:
282
+ attr = _TF_ATTR_RE.match(text)
283
+ if not attr:
284
+ continue
285
+ key, value = attr.group(1), attr.group(2)
286
+ if key in ("from_port", "to_port"):
287
+ try:
288
+ ports.append(int(value.strip().strip('"')))
289
+ except ValueError:
290
+ continue
291
+ elif key in ("cidr_blocks", "ipv6_cidr_blocks"):
292
+ if any(cidr in WORLD_CIDRS for cidr in _TF_STRING_RE.findall(value)):
293
+ world.append(lineno)
294
+ if not world or len(ports) < 2:
295
+ continue
296
+ low, high = min(ports), max(ports)
297
+ if not any(low <= port <= high for port in ADMIN_PORTS):
298
+ continue
299
+ for lineno in world:
300
+ findings.append(_finding(
301
+ file_path, lineno, "CWE-732", "IAC_PUBLIC_EXPOSURE", "CRITICAL",
302
+ f"aws_security_group.{name} opens ports {low}-{high} to 0.0.0.0/0, which"
303
+ " exposes SSH/RDP to the whole internet. Restrict cidr_blocks to an internal"
304
+ " range such as 10.0.0.0/8 or a bastion address"))
305
+ return findings
306
+
307
+
308
+ def audit_iac_security_files(files: Dict[str, str]) -> List[Dict[str, Any]]:
309
+ """Audit workflows, Kubernetes manifests and Terraform. CWE-1357 is not emitted here."""
310
+ findings: List[Dict[str, Any]] = []
311
+ for file_path in sorted(files):
312
+ source = files[file_path]
313
+ if is_terraform_path(file_path):
314
+ findings.extend(_terraform_exposure(file_path, source))
315
+ continue
316
+ if not str(file_path).lower().endswith(WORKFLOW_SUFFIXES):
317
+ continue
318
+ # Discovery offers every YAML document in a tree, so parse only the two shapes a rule can
319
+ # read: a workflow by path, a workload manifest by content. An unrelated config is skipped
320
+ # without building a node per line.
321
+ if is_workflow_yaml_path(file_path):
322
+ root = yaml_lite.parse(source)
323
+ raw_lines = source.splitlines()
324
+ findings.extend(_gha_script_injection(file_path, root, raw_lines))
325
+ findings.extend(_gha_permissions(file_path, root, raw_lines))
326
+ elif is_kubernetes_manifest(source):
327
+ findings.extend(_kubernetes_privileges(file_path, yaml_lite.parse(source)))
328
+ return sorted(findings, key=lambda item: (item["file"], item["line"], item["cwe"]))
scanners/sbom.py ADDED
@@ -0,0 +1,183 @@
1
+ """CycloneDX 1.5 JSON SBOM export -- stdlib only, built from the same parse the audit used.
2
+
3
+ The inventory and the findings come from one pass over the manifests, so the bill of materials
4
+ cannot disagree with the report: every `affects.ref` resolves to a component that is actually
5
+ listed, and every component carries the manifest line it was declared on.
6
+
7
+ Two honesty rules shape the document:
8
+
9
+ * A component carries a `version` only when the manifest proves exactly one. `^4.17.20` allows a
10
+ range, so it is inventoried as a version-less purl rather than as a guess at whichever release
11
+ a resolver happened to pick. A version-less purl is legal CycloneDX; a fabricated version is not.
12
+ * A vulnerability's CWE, severity and fix are read per CVE from the advisory index, not copied
13
+ from the finding's primary label. One pin can carry several advisories with different root
14
+ weaknesses and different fixes, and `requests==2.30.0` must not report CVE-2024-35195's fix as
15
+ the remedy for CVE-2023-32681.
16
+
17
+ Reachability travels as a property, so a consumer can filter dormant lockfile entries the same
18
+ way the table does.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import re
24
+ import uuid
25
+ from datetime import datetime, timezone
26
+ from typing import Any, Dict, List, Optional, Tuple
27
+
28
+ from .cve_index import advisories_for, compare_versions, parse_version
29
+ from .sca_scanner import CATEGORY as SCA_CATEGORY
30
+
31
+ __all__ = ["build_sbom", "component_purl", "SPEC_VERSION"]
32
+
33
+ SPEC_VERSION = "1.5"
34
+ TOOL_VENDOR = "TCS"
35
+ TOOL_NAME = "time-code-security"
36
+ TOOL_VERSION = "1.0.0"
37
+
38
+ _SEVERITY_TEXT = {"CRITICAL": "critical", "HIGH": "high", "MEDIUM": "medium", "LOW": "low"}
39
+ _SEVERITY_RANK = {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1}
40
+ _CWE_NUMBER = re.compile(r"CWE-(\d+)")
41
+ NVD_URL = "https://nvd.nist.gov/vuln/detail/"
42
+
43
+
44
+ def component_purl(ecosystem: str, name: str, version: Optional[str] = None) -> str:
45
+ """A package URL. An npm scope's leading '@' is percent-encoded so it stays one path segment."""
46
+ spelled = name.replace("@", "%40", 1) if name.startswith("@") else name
47
+ return "pkg:%s/%s" % (ecosystem, spelled) + ("@" + version if version else "")
48
+
49
+
50
+ def _advisory_facts(ecosystem: str, package: str, cve: str,
51
+ version: Optional[str]) -> Tuple[List[int], str, str, str]:
52
+ """(CWE numbers, severity, summary, upgrade target) for one CVE on one component."""
53
+ records = [item for item in advisories_for(ecosystem, package) if item[0] == cve]
54
+ cwes = {1395}
55
+ severity = "LOW"
56
+ summary = ""
57
+ current = parse_version(version) if version else None
58
+ target: Optional[str] = None
59
+ target_key = None
60
+ for item in records:
61
+ hit = _CWE_NUMBER.match(item[1])
62
+ if hit:
63
+ cwes.add(int(hit.group(1)))
64
+ if _SEVERITY_RANK.get(item[2], 0) > _SEVERITY_RANK.get(severity, 0):
65
+ severity = item[2]
66
+ if not summary:
67
+ summary = item[5]
68
+ fixed = parse_version(item[3])
69
+ if fixed is None:
70
+ continue
71
+ # With a known version the remedy is the nearest fix above it on its own branch, not the
72
+ # newest fix across every branch: ws 7.5.9 is remedied by 7.5.10, not by 8.17.1.
73
+ if current is not None and compare_versions(fixed, current) <= 0:
74
+ continue
75
+ if target_key is None or compare_versions(fixed, target_key) < 0:
76
+ target, target_key = item[3], fixed
77
+ if target is None and records:
78
+ target = max((item[3] for item in records), key=lambda text: parse_version(text) or ())
79
+ return sorted(cwes), _SEVERITY_TEXT.get(severity, "unknown"), summary, target or ""
80
+
81
+
82
+ def build_sbom(components: List[Dict[str, Any]], findings: List[Dict[str, Any]], *,
83
+ root_name: str = "target", timestamp: Optional[str] = None,
84
+ serial_number: Optional[str] = None) -> Dict[str, Any]:
85
+ """A CycloneDX 1.5 document. `findings` is the complete emission set, not the display rows."""
86
+ meta: Dict[str, Dict[str, Any]] = {}
87
+ locations: Dict[str, List[str]] = {}
88
+
89
+ def declare(entry: Dict[str, Any]) -> str:
90
+ purl = component_purl(entry["ecosystem"], entry["name"], entry.get("version"))
91
+ if purl not in meta:
92
+ meta[purl] = entry
93
+ locations[purl] = []
94
+ where = "%s:%s" % (entry["file"], entry["line"])
95
+ if where not in locations[purl]:
96
+ locations[purl].append(where)
97
+ return purl
98
+
99
+ for entry in components:
100
+ declare(entry)
101
+
102
+ index = {(entry["file"], entry["line"], entry["name"]): entry for entry in components}
103
+ records: Dict[Tuple[str, str], Dict[str, Any]] = {}
104
+ for finding in findings:
105
+ if finding.get("category") != SCA_CATEGORY:
106
+ continue
107
+ entry = index.get((finding["file"], finding["line"], finding["package"]))
108
+ if entry is None:
109
+ entry = {"ecosystem": finding["ecosystem"], "name": finding["package"],
110
+ "version": None, "spec": finding.get("spec", ""),
111
+ "file": finding["file"], "line": finding["line"]}
112
+ purl = declare(entry)
113
+ for cve in finding.get("cves") or [finding.get("cve")]:
114
+ if not cve:
115
+ continue
116
+ key = (cve, purl)
117
+ record = records.get(key)
118
+ if record is None:
119
+ cwes, severity, summary, fixed = _advisory_facts(
120
+ entry["ecosystem"], entry["name"], cve, entry.get("version"))
121
+ record = {"cve": cve, "purl": purl, "cwes": cwes, "severity": severity,
122
+ "summary": summary, "fixed": fixed, "locations": [],
123
+ "reachability": "UNREACHABLE_MANIFEST_ONLY", "confidence": "LOW"}
124
+ records[key] = record
125
+ # Reachability is a proof about the code, and one proof anywhere is enough: the
126
+ # upgrade never runs backwards when a second manifest declares the same coordinate.
127
+ if finding.get("reachability") == "REACHABLE":
128
+ record["reachability"] = "REACHABLE"
129
+ record["confidence"] = finding.get("confidence", "HIGH")
130
+ where = "%s:%s" % (finding["file"], finding["line"])
131
+ if where not in record["locations"]:
132
+ record["locations"].append(where)
133
+
134
+ root_ref = "root:%s" % (root_name or "target")
135
+ component_nodes = []
136
+ for purl, entry in meta.items():
137
+ node: Dict[str, Any] = {"type": "library", "bom-ref": purl, "name": entry["name"],
138
+ "purl": purl}
139
+ if entry.get("version"):
140
+ node["version"] = entry["version"]
141
+ properties = [{"name": "tcs:ecosystem", "value": entry["ecosystem"]},
142
+ {"name": "tcs:spec", "value": str(entry.get("spec") or "")}]
143
+ properties.extend({"name": "tcs:manifest", "value": where} for where in locations[purl])
144
+ node["properties"] = properties
145
+ component_nodes.append(node)
146
+
147
+ vulnerability_nodes = []
148
+ for (cve, purl), record in sorted(records.items()):
149
+ properties = [{"name": "tcs:reachability", "value": record["reachability"]},
150
+ {"name": "tcs:confidence", "value": record["confidence"]}]
151
+ if record["fixed"]:
152
+ properties.append({"name": "tcs:fixed_version", "value": record["fixed"]})
153
+ properties.extend({"name": "tcs:manifest", "value": where} for where in record["locations"])
154
+ node: Dict[str, Any] = {
155
+ "bom-ref": "vuln:%s:%s" % (cve, purl),
156
+ "id": cve,
157
+ "source": {"name": "NVD", "url": NVD_URL + cve},
158
+ "cwes": record["cwes"],
159
+ "ratings": [{"severity": record["severity"], "method": "other"}],
160
+ "description": record["summary"],
161
+ "affects": [{"ref": purl}],
162
+ "properties": properties,
163
+ }
164
+ if record["fixed"]:
165
+ node["recommendation"] = "Upgrade to version %s or later." % record["fixed"]
166
+ vulnerability_nodes.append(node)
167
+
168
+ return {
169
+ "bomFormat": "CycloneDX",
170
+ "specVersion": SPEC_VERSION,
171
+ "serialNumber": serial_number or "urn:uuid:%s" % uuid.uuid4(),
172
+ "version": 1,
173
+ "metadata": {
174
+ "timestamp": timestamp or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
175
+ "tools": [{"vendor": TOOL_VENDOR, "name": TOOL_NAME, "version": TOOL_VERSION}],
176
+ "component": {"type": "application", "bom-ref": root_ref,
177
+ "name": root_name or "target"},
178
+ },
179
+ "components": component_nodes,
180
+ "vulnerabilities": vulnerability_nodes,
181
+ "dependencies": [{"ref": root_ref, "dependsOn": sorted(meta)}]
182
+ + [{"ref": purl, "dependsOn": []} for purl in sorted(meta)],
183
+ }