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,169 @@
1
+ """
2
+ TimeCodeSecurity - Vector C Import & Distribution Directional Resolvers.
3
+ Provides explicit forward and reverse resolution between distribution package names
4
+ and AST import root namespaces.
5
+ """
6
+
7
+ from typing import Optional, Set, Tuple
8
+ from sca_reachability.contracts import (
9
+ ImportDistributionResult,
10
+ ImportNamespaceResult,
11
+ )
12
+ from sca_reachability.dist_import_map import (
13
+ get_curated_imports_for_dist,
14
+ get_curated_dists_for_import,
15
+ )
16
+
17
+
18
+ def resolve_import_to_distributions(
19
+ import_root: str,
20
+ target_env: Optional[str] = None,
21
+ declared_distributions: Optional[Set[str]] = None,
22
+ ) -> ImportDistributionResult:
23
+ """
24
+ Reverse Attribution: Maps an AST import root (e.g. 'PIL', 'dateutil', 'vulnlib')
25
+ to its providing distribution package name(s) (e.g. 'pillow', 'python-dateutil', 'vulnlib').
26
+
27
+ Evidence Hierarchy:
28
+ 1. VERIFIED_STATIC_CURATED_MAPPING (STATIC_METADATA) - definitive
29
+ 2. TARGET_ENVIRONMENT_METADATA (exact match against declared distributions or target environment) - definitive
30
+ 3. NORMALIZED_HEURISTIC (NONE) - non-definitive
31
+ 4. UNRESOLVED
32
+ """
33
+ clean_root = import_root.strip()
34
+ norm_root = clean_root.lower().replace("_", "-")
35
+
36
+ # Step 1: Curated bidirectional tables (pillow -> PIL, python-dateutil -> dateutil, etc.)
37
+ curated = get_curated_dists_for_import(clean_root) or get_curated_dists_for_import(norm_root)
38
+ if curated:
39
+ # Step 4: 1-to-many guard on curated mapping
40
+ if len(curated) > 1:
41
+ return ImportDistributionResult(
42
+ import_root=clean_root,
43
+ distribution_names=curated,
44
+ evidence_source="VERIFIED_STATIC_CURATED_MAPPING",
45
+ environment_scope="STATIC_METADATA",
46
+ is_definitive=False,
47
+ limitations=(f"Ambiguous import root '{clean_root}' maps to multiple distributions: {', '.join(curated)}",)
48
+ )
49
+ return ImportDistributionResult(
50
+ import_root=clean_root,
51
+ distribution_names=curated,
52
+ evidence_source="VERIFIED_STATIC_CURATED_MAPPING",
53
+ environment_scope="STATIC_METADATA",
54
+ is_definitive=True,
55
+ limitations=()
56
+ )
57
+
58
+ # Step 2: Exact string match with declared distributions
59
+ if declared_distributions:
60
+ decl_exact = {d for d in declared_distributions if d == clean_root}
61
+ if decl_exact:
62
+ d_name = next(iter(decl_exact))
63
+ return ImportDistributionResult(
64
+ import_root=clean_root,
65
+ distribution_names=(d_name,),
66
+ evidence_source="TARGET_ENVIRONMENT_METADATA",
67
+ environment_scope="TARGET_ENVIRONMENT",
68
+ is_definitive=True,
69
+ limitations=()
70
+ )
71
+
72
+ # Check PEP 503 normalized declared distributions
73
+ decl_norm = {d for d in declared_distributions if d.lower().replace("_", "-") == norm_root}
74
+ if len(decl_norm) == 1:
75
+ d_name = next(iter(decl_norm))
76
+ # If the only difference was hyphen vs underscore (e.g. my-weird-pkg vs my_weird_pkg)
77
+ if d_name != clean_root and ("_" in clean_root or "-" in d_name):
78
+ # Step 3: Heuristic fallback
79
+ return ImportDistributionResult(
80
+ import_root=clean_root,
81
+ distribution_names=(d_name,),
82
+ evidence_source="NORMALIZED_HEURISTIC",
83
+ environment_scope="NONE",
84
+ is_definitive=False,
85
+ limitations=("Import namespace mapping uses non-definitive heuristic normalization; PROVEN_STATIC attribution not possible",)
86
+ )
87
+ return ImportDistributionResult(
88
+ import_root=clean_root,
89
+ distribution_names=(d_name,),
90
+ evidence_source="TARGET_ENVIRONMENT_METADATA",
91
+ environment_scope="TARGET_ENVIRONMENT",
92
+ is_definitive=True,
93
+ limitations=()
94
+ )
95
+ elif len(decl_norm) > 1:
96
+ # Step 4: 1-to-many ambiguity guard
97
+ return ImportDistributionResult(
98
+ import_root=clean_root,
99
+ distribution_names=tuple(sorted(decl_norm)),
100
+ evidence_source="TARGET_ENVIRONMENT_METADATA",
101
+ environment_scope="TARGET_ENVIRONMENT",
102
+ is_definitive=False,
103
+ limitations=(f"Ambiguous import root '{clean_root}' maps to multiple declared distributions: {', '.join(sorted(decl_norm))}",)
104
+ )
105
+
106
+ # Default fallback: If import_root looks like a standard package without declared context
107
+ if "_" in clean_root:
108
+ hyphenated = clean_root.replace("_", "-")
109
+ return ImportDistributionResult(
110
+ import_root=clean_root,
111
+ distribution_names=(hyphenated,),
112
+ evidence_source="NORMALIZED_HEURISTIC",
113
+ environment_scope="NONE",
114
+ is_definitive=False,
115
+ limitations=("Import namespace mapping uses non-definitive heuristic normalization; PROVEN_STATIC attribution not possible",)
116
+ )
117
+
118
+ # Clean unhyphenated name default: without declared context, return honest heuristic
119
+ return ImportDistributionResult(
120
+ import_root=clean_root,
121
+ distribution_names=(clean_root,),
122
+ evidence_source="NORMALIZED_HEURISTIC",
123
+ environment_scope="NONE",
124
+ is_definitive=False,
125
+ limitations=("Import namespace mapping uses non-definitive heuristic normalization; PROVEN_STATIC attribution not possible",)
126
+ )
127
+
128
+
129
+ def resolve_distribution_to_imports(
130
+ dist: str,
131
+ target_env: Optional[str] = None,
132
+ ) -> ImportNamespaceResult:
133
+ """
134
+ Forward Resolution: Maps a distribution package name (e.g. 'pillow', 'vulnlib')
135
+ to its import namespace root(s) (e.g. ('PIL',), ('vulnlib',)).
136
+ """
137
+ clean_dist = dist.strip()
138
+ curated = get_curated_imports_for_dist(clean_dist)
139
+ if curated:
140
+ return ImportNamespaceResult(
141
+ distribution_name=clean_dist,
142
+ import_roots=curated,
143
+ evidence_source="VERIFIED_STATIC_CURATED_MAPPING",
144
+ environment_scope="STATIC_METADATA",
145
+ is_definitive=True,
146
+ limitations=()
147
+ )
148
+
149
+ # Standard normalization: replace hyphens with underscores
150
+ import_root = clean_dist.lower().replace("-", "_")
151
+ if target_env:
152
+ return ImportNamespaceResult(
153
+ distribution_name=clean_dist,
154
+ import_roots=(import_root,),
155
+ evidence_source="TARGET_ENVIRONMENT_METADATA",
156
+ environment_scope="TARGET_ENVIRONMENT",
157
+ is_definitive=True,
158
+ limitations=()
159
+ )
160
+
161
+ return ImportNamespaceResult(
162
+ distribution_name=clean_dist,
163
+ import_roots=(import_root,),
164
+ evidence_source="NORMALIZED_HEURISTIC",
165
+ environment_scope="NONE",
166
+ is_definitive=False,
167
+ limitations=("Import namespace mapping uses non-definitive heuristic normalization; PROVEN_STATIC attribution not possible",)
168
+ )
169
+
scanners/__init__.py ADDED
@@ -0,0 +1,70 @@
1
+ """Modular auxiliary security scanners: containers, CI/IaC and dependency composition.
2
+
3
+ These run beside the Python AST engine, never inside it. ``ast_scanner.py`` is not imported for
4
+ detection here and is not modified by this package; the only shared surface is the finding dict
5
+ shape that ``cli._merge_findings`` already consumes.
6
+
7
+ ``iac_auditor`` keeps owning the legacy Dockerfile CWE-250/CWE-269 rows and every CWE-1357
8
+ unpinned-action row. The scanners in this package add the Snyk-container and Snyk-IaC rule families
9
+ on top, and ``audit_security_files`` suppresses a second CWE-250 on a file the legacy auditor
10
+ already booked so one defect is never reported twice.
11
+
12
+ ``sca_scanner`` is the Snyk-Open-Source family: manifests and lockfiles matched against the offline
13
+ advisory index in ``cve_index``, then labelled by an import-reachability proof the caller supplies.
14
+ It is deliberately separate from ``audit_security_files`` because reachability needs the Python
15
+ engine's parsed trees, which only the caller has.
16
+
17
+ ``secret_scanner`` is the Snyk-Code config family: ``.env``, INI, TOML, JSON, YAML and shell
18
+ documents carrying a vendor-prefixed or cryptographic credential. ``sbom`` renders the same
19
+ manifest parse as a CycloneDX 1.5 document, so the bill of materials and the report cannot drift.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ from typing import Any, Dict, Iterable, List
25
+
26
+ from .container_scanner import (
27
+ audit_container_files,
28
+ is_compose_path,
29
+ is_container_path,
30
+ is_dockerfile_name,
31
+ )
32
+ from .iac_scanner import (
33
+ audit_iac_security_files,
34
+ is_iac_security_path,
35
+ is_kubernetes_manifest,
36
+ is_terraform_path,
37
+ is_workflow_yaml_path,
38
+ )
39
+ from .sca_scanner import (
40
+ audit_sca_files,
41
+ collect_components,
42
+ is_manifest_path,
43
+ tag_reachability,
44
+ )
45
+ from .sbom import build_sbom
46
+ from .secret_scanner import audit_secret_files, is_secret_path
47
+
48
+ __all__ = [
49
+ "audit_container_files", "audit_iac_security_files", "audit_security_files",
50
+ "is_container_path", "is_compose_path", "is_dockerfile_name",
51
+ "is_iac_security_path", "is_workflow_yaml_path", "is_terraform_path",
52
+ "is_kubernetes_manifest", "is_aux_security_path",
53
+ "audit_sca_files", "is_manifest_path", "tag_reachability",
54
+ "collect_components", "build_sbom",
55
+ "audit_secret_files", "is_secret_path",
56
+ ]
57
+
58
+
59
+ def is_aux_security_path(path: str) -> bool:
60
+ """Path-decidable auxiliary security families. Kubernetes needs a content sniff as well."""
61
+ return is_container_path(path) or is_iac_security_path(path)
62
+
63
+
64
+ def audit_security_files(files: Dict[str, str],
65
+ legacy_findings: Iterable[Dict[str, Any]] = ()) -> List[Dict[str, Any]]:
66
+ """Run both scanners over ``{path: source}`` and return their findings, deterministically."""
67
+ already_root = {item["file"] for item in legacy_findings if item.get("cwe") == "CWE-250"}
68
+ findings = audit_container_files(files, already_root_reported=already_root)
69
+ findings.extend(audit_iac_security_files(files))
70
+ return sorted(findings, key=lambda item: (item["file"], item["line"], item["cwe"]))
@@ -0,0 +1,323 @@
1
+ """Container security scanner -- Dockerfiles and docker-compose, stdlib only.
2
+
3
+ Three rules, each decided from parsed instructions or parsed YAML nodes rather than a whole-file
4
+ pattern sweep:
5
+
6
+ * CWE-250 ``CONTAINER_ROOT_USER`` -- the image's FINAL stage runs as UID 0. Intermediate builder
7
+ stages are not the shipped image, and ``FROM scratch`` has no user at all, so neither is reported.
8
+ * CWE-798 ``CONTAINER_HARDCODED_SECRET`` -- an ``ENV``/``ARG`` (or a compose ``environment:`` entry)
9
+ writes a literal into a credential-named key. An empty value, a ``$VAR`` reference and an obvious
10
+ placeholder are not secrets: they are the absence of one.
11
+ * CWE-829 ``CONTAINER_UNTRUSTED_OR_UNPINNED_IMAGE`` -- ``ADD`` fetches a remote URL with no checksum,
12
+ or ``FROM`` names an image by ``:latest`` or by no reference at all. ``COPY`` moves a local file and
13
+ a digest-pinned or local stage reference is immutable, so neither is reported.
14
+
15
+ The legacy ``iac_auditor.audit_dockerfile`` keeps its own CWE-250/CWE-269 rows untouched. This module
16
+ takes ``already_root_reported`` so one defect is not booked twice on one file.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import re
22
+ from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
23
+
24
+ from . import yaml_lite
25
+
26
+ __all__ = ["is_container_path", "is_dockerfile_name", "is_compose_path", "audit_container_files"]
27
+
28
+ COMPOSE_SUFFIXES = (".yml", ".yaml")
29
+ ROOT_USER_VALUES = frozenset({"root", "0", "root:root", "0:0", "root:0", "0:root"})
30
+ SECRET_KEY_WORDS = frozenset({
31
+ "PASSWORD", "PASSWD", "SECRET", "API_KEY", "PRIVATE_KEY",
32
+ "AWS_SECRET_ACCESS_KEY", "AUTH_TOKEN", "ACCESS_TOKEN",
33
+ })
34
+ PLACEHOLDER_VALUES = frozenset({"changeme", "example", "dummy", "placeholder", "none", "null", ""})
35
+ CONTINUATION = "\\"
36
+
37
+ _DIGEST_RE = re.compile(r"@sha256:[0-9a-fA-F]{64}\s*$")
38
+ _REMOTE_ADD_RE = re.compile(r"^https?://", re.IGNORECASE)
39
+ _KEY_SPLIT_RE = re.compile(r"[^0-9A-Za-z]+")
40
+
41
+
42
+ def is_dockerfile_name(path: str) -> bool:
43
+ name = str(path).replace("\\", "/").rsplit("/", 1)[-1].lower()
44
+ return name.startswith("dockerfile") or name.endswith(".dockerfile")
45
+
46
+
47
+ def is_compose_path(path: str) -> bool:
48
+ normalized = str(path).replace("\\", "/").lower()
49
+ name = normalized.rsplit("/", 1)[-1]
50
+ return name.startswith("docker-compose") and name.endswith(COMPOSE_SUFFIXES)
51
+
52
+
53
+ def is_container_path(path: str) -> bool:
54
+ return is_dockerfile_name(path) or is_compose_path(path)
55
+
56
+
57
+ # ── Dockerfile instructions ───────────────────────────────────────────────
58
+ def _instructions(source: str) -> List[Tuple[int, str, str]]:
59
+ """[(start_line, KEYWORD, arguments)] honouring backslash continuations."""
60
+ out: List[Tuple[int, str, str]] = []
61
+ logical: List[str] = []
62
+ start = 0
63
+ for lineno, raw in enumerate(source.splitlines(), start=1):
64
+ line = raw.strip()
65
+ if not logical:
66
+ if not line or line.startswith("#"):
67
+ continue
68
+ start = lineno
69
+ elif not line or line.startswith("#"):
70
+ out.append(_split(start, logical))
71
+ logical = []
72
+ continue
73
+ if line.endswith(CONTINUATION) and not line.endswith("\\\\"):
74
+ logical.append(line[:-1].strip())
75
+ continue
76
+ logical.append(line)
77
+ out.append(_split(start, logical))
78
+ logical = []
79
+ if logical:
80
+ out.append(_split(start, logical))
81
+ return [(line, kw, args) for line, kw, args in out if kw]
82
+
83
+
84
+ def _split(start: int, logical: Sequence[str]) -> Tuple[int, str, str]:
85
+ text = " ".join(logical)
86
+ keyword, _, arguments = text.partition(" ")
87
+ return start, keyword.strip().upper(), arguments.strip()
88
+
89
+
90
+ def _from_target(arguments: str) -> Tuple[str, Optional[str]]:
91
+ """(image_reference, stage_alias) for a FROM instruction, skipping ``--flag=`` options."""
92
+ alias = None
93
+ tokens = arguments.split()
94
+ kept: List[str] = []
95
+ index = 0
96
+ while index < len(tokens):
97
+ token = tokens[index]
98
+ if token.lower() == "as" and index + 1 < len(tokens):
99
+ alias = tokens[index + 1].lower()
100
+ break
101
+ if token.startswith("--"):
102
+ index += 1
103
+ continue
104
+ kept.append(token)
105
+ index += 1
106
+ return (kept[0] if kept else ""), alias
107
+
108
+
109
+ def _image_is_pinned(reference: str) -> bool:
110
+ if _DIGEST_RE.search(reference):
111
+ return True
112
+ name, separator, tag = reference.rpartition(":")
113
+ if not separator or not name:
114
+ return False
115
+ return bool(tag) and tag.lower() != "latest"
116
+
117
+
118
+ def _stages(instructions: Sequence[Tuple[int, str, str]]) -> List[List[Tuple[int, str, str]]]:
119
+ stages: List[List[Tuple[int, str, str]]] = []
120
+ for entry in instructions:
121
+ if entry[1] == "FROM":
122
+ stages.append([entry])
123
+ elif stages:
124
+ stages[-1].append(entry)
125
+ return stages
126
+
127
+
128
+ # ── shared value proofs ───────────────────────────────────────────────────
129
+ def _key_is_sensitive(key: str) -> bool:
130
+ normalized = "_".join(part for part in _KEY_SPLIT_RE.split(str(key).upper()) if part)
131
+ if normalized in SECRET_KEY_WORDS:
132
+ return True
133
+ return any(normalized.endswith("_" + word) for word in SECRET_KEY_WORDS)
134
+
135
+
136
+ def _value_is_a_hardcoded_secret(value: str) -> bool:
137
+ """A non-empty literal that is neither a variable reference nor an obvious placeholder."""
138
+ text = str(value).strip()
139
+ if len(text) >= 2 and text[0] == text[-1] and text[0] in "'\"":
140
+ text = text[1:-1].strip()
141
+ if not text or "$" in text:
142
+ return False
143
+ lowered = text.lower()
144
+ if lowered in PLACEHOLDER_VALUES:
145
+ return False
146
+ if lowered.startswith(("your_", "your-", "<", "{{")):
147
+ return False
148
+ return True
149
+
150
+
151
+ def _finding(file_path: str, line: int, cwe: str, category: str, severity: str, message: str) -> Dict[str, Any]:
152
+ return {
153
+ "file": file_path,
154
+ "line": max(1, int(line)),
155
+ "cwe": cwe,
156
+ "severity": severity,
157
+ "category": category,
158
+ "message": f"{cwe}: {message}",
159
+ }
160
+
161
+
162
+ # ── Dockerfile rules ──────────────────────────────────────────────────────
163
+ def _dockerfile_root_user(file_path: str, instructions: Sequence[Tuple[int, str, str]]) -> List[Dict[str, Any]]:
164
+ stages = _stages(instructions)
165
+ if not stages:
166
+ return []
167
+ final = stages[-1]
168
+ from_line, _kw, from_args = final[0]
169
+ reference, _alias = _from_target(from_args)
170
+ if reference.lower() == "scratch":
171
+ return []
172
+ users = [entry for entry in final if entry[1] == "USER"]
173
+ if users:
174
+ user_line, _kw, user_args = users[-1]
175
+ value = user_args.split()[0].lower() if user_args.split() else ""
176
+ if value not in ROOT_USER_VALUES:
177
+ return []
178
+ return [_finding(
179
+ file_path, user_line, "CWE-250", "CONTAINER_ROOT_USER", "HIGH",
180
+ f"Final stage sets USER {value}: the container process runs as UID 0, so a container"
181
+ " escape inherits root on the host. Set USER to a non-root account or a numeric UID"
182
+ " above 0")]
183
+ return [_finding(
184
+ file_path, from_line, "CWE-250", "CONTAINER_ROOT_USER", "HIGH",
185
+ f"Final stage FROM {reference} declares no USER instruction, so the image runs as root."
186
+ " Add USER <non-root> after the final FROM so a container escape does not inherit UID 0")]
187
+
188
+
189
+ def _dockerfile_secrets(file_path: str, instructions: Sequence[Tuple[int, str, str]]) -> List[Dict[str, Any]]:
190
+ findings: List[Dict[str, Any]] = []
191
+ for line, keyword, arguments in instructions:
192
+ if keyword not in ("ENV", "ARG"):
193
+ continue
194
+ for key, value in _env_pairs(keyword, arguments):
195
+ if _key_is_sensitive(key) and _value_is_a_hardcoded_secret(value):
196
+ findings.append(_finding(
197
+ file_path, line, "CWE-798", "CONTAINER_HARDCODED_SECRET", "HIGH",
198
+ f"{keyword} {key} embeds a literal credential in the image layer history."
199
+ " Read it from a build secret or the runtime environment instead of baking it"
200
+ " into the image"))
201
+ return findings
202
+
203
+
204
+ def _env_pairs(keyword: str, arguments: str) -> List[Tuple[str, str]]:
205
+ """ENV/ARG assignments: ``K=V K2=V2`` and the legacy ``ENV K V`` single-pair form."""
206
+ text = arguments.strip()
207
+ if not text:
208
+ return []
209
+ if "=" not in text.split()[0]:
210
+ if keyword == "ENV":
211
+ key, _, value = text.partition(" ")
212
+ return [(key.strip(), value.strip())] if key.strip() else []
213
+ return [(text.split()[0], "")]
214
+ pairs: List[Tuple[str, str]] = []
215
+ for match in re.finditer(r"([A-Za-z_][A-Za-z0-9_]*)=(\"[^\"]*\"|'[^']*'|[^\s]*)", text):
216
+ pairs.append((match.group(1), match.group(2)))
217
+ return pairs
218
+
219
+
220
+ def _dockerfile_images(file_path: str, instructions: Sequence[Tuple[int, str, str]]) -> List[Dict[str, Any]]:
221
+ findings: List[Dict[str, Any]] = []
222
+ aliases: Set[str] = set()
223
+ for line, keyword, arguments in instructions:
224
+ if keyword == "ADD":
225
+ for token in arguments.split():
226
+ if _REMOTE_ADD_RE.match(token.strip("\"'")):
227
+ findings.append(_finding(
228
+ file_path, line, "CWE-829", "CONTAINER_UNTRUSTED_OR_UNPINNED_IMAGE", "HIGH",
229
+ f"ADD fetches {token} over the network with no checksum verification, so a"
230
+ " compromised or spoofed endpoint changes the image silently. Download with"
231
+ " a verified digest, or COPY a file already in the build context"))
232
+ break
233
+ elif keyword == "FROM":
234
+ reference, alias = _from_target(arguments)
235
+ if alias:
236
+ aliases.add(alias)
237
+ bare = reference.split("@", 1)[0].rpartition(":")[0] or reference
238
+ if not reference or reference.lower() == "scratch":
239
+ continue
240
+ if bare.lower() in aliases and "@" not in reference and ":" not in reference:
241
+ continue
242
+ if _image_is_pinned(reference):
243
+ continue
244
+ findings.append(_finding(
245
+ file_path, line, "CWE-829", "CONTAINER_UNTRUSTED_OR_UNPINNED_IMAGE", "HIGH",
246
+ f"FROM {reference} is not pinned to an immutable digest, so the base image can"
247
+ " change under the build without any edit here. Reference it by @sha256:<digest>"))
248
+ return findings
249
+
250
+
251
+ # ── docker-compose rules ──────────────────────────────────────────────────
252
+ def _compose_services(root: Any) -> Iterable[Tuple[str, int, Any]]:
253
+ services = yaml_lite.get(root, "services")
254
+ if isinstance(services, yaml_lite.Mapping):
255
+ for name, lineno, value in services.items:
256
+ yield name, lineno, value
257
+ return
258
+ if isinstance(root, yaml_lite.Mapping):
259
+ for name, lineno, value in root.items:
260
+ if isinstance(value, yaml_lite.Mapping) and (
261
+ yaml_lite.get(value, "image") is not None
262
+ or yaml_lite.get(value, "build") is not None):
263
+ yield name, lineno, value
264
+
265
+
266
+ def _environment_entries(node: Any) -> Iterable[Tuple[str, int, str]]:
267
+ if isinstance(node, yaml_lite.Mapping):
268
+ for key, lineno, value in node.items:
269
+ yield key, lineno, yaml_lite.scalar_text(value)
270
+ elif isinstance(node, yaml_lite.Sequence):
271
+ for lineno, value in node.items:
272
+ text = yaml_lite.scalar_text(value)
273
+ key, separator, val = text.partition("=")
274
+ if separator:
275
+ yield key.strip(), lineno, val.strip()
276
+
277
+
278
+ def _compose_rules(file_path: str, root: Any) -> List[Dict[str, Any]]:
279
+ findings: List[Dict[str, Any]] = []
280
+ for name, _lineno, service in _compose_services(root):
281
+ if not isinstance(service, yaml_lite.Mapping):
282
+ continue
283
+ privileged = yaml_lite.get(service, "privileged")
284
+ if isinstance(privileged, yaml_lite.Scalar) and privileged.text.strip().lower() == "true":
285
+ findings.append(_finding(
286
+ file_path, privileged.lineno, "CWE-250", "CONTAINER_ROOT_USER", "HIGH",
287
+ f"Service {name} sets privileged: true, which grants every capability and device"
288
+ " on the host. Drop privileged and add only the capabilities the service needs"))
289
+ user = yaml_lite.get(service, "user")
290
+ if isinstance(user, yaml_lite.Scalar):
291
+ value = user.text.strip().strip("'\"").lower()
292
+ if value in ROOT_USER_VALUES:
293
+ findings.append(_finding(
294
+ file_path, user.lineno, "CWE-250", "CONTAINER_ROOT_USER", "HIGH",
295
+ f"Service {name} runs as user {value}: the container process holds UID 0."
296
+ " Set user to a non-root account or a numeric UID above 0"))
297
+ for key, lineno, value in _environment_entries(yaml_lite.get(service, "environment")):
298
+ if _key_is_sensitive(key) and _value_is_a_hardcoded_secret(value):
299
+ findings.append(_finding(
300
+ file_path, lineno, "CWE-798", "CONTAINER_HARDCODED_SECRET", "HIGH",
301
+ f"Service {name} sets {key} to a literal credential in a file that is normally"
302
+ " committed. Reference an environment variable or a secrets file instead"))
303
+ return findings
304
+
305
+
306
+ def audit_container_files(files: Dict[str, str],
307
+ already_root_reported: Optional[Iterable[str]] = None) -> List[Dict[str, Any]]:
308
+ """Audit Dockerfiles and compose documents. ``already_root_reported`` names files whose CWE-250
309
+ the legacy Dockerfile auditor already booked, so one defect is not reported twice."""
310
+ skip_root: Set[str] = set(already_root_reported or ())
311
+ findings: List[Dict[str, Any]] = []
312
+ for file_path in sorted(files):
313
+ if is_dockerfile_name(file_path):
314
+ instructions = _instructions(files[file_path])
315
+ if not instructions:
316
+ continue
317
+ if file_path not in skip_root:
318
+ findings.extend(_dockerfile_root_user(file_path, instructions))
319
+ findings.extend(_dockerfile_secrets(file_path, instructions))
320
+ findings.extend(_dockerfile_images(file_path, instructions))
321
+ elif is_compose_path(file_path):
322
+ findings.extend(_compose_rules(file_path, yaml_lite.parse(files[file_path])))
323
+ return sorted(findings, key=lambda item: (item["file"], item["line"], item["cwe"]))