contextlock 0.1.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.
@@ -0,0 +1,219 @@
1
+ """ABOM-004: commands or instructions that send environment variables, files or secrets
2
+ to an external URL, and webhook or capture URLs in commands and config."""
3
+
4
+ import re
5
+ from collections.abc import Iterator, Sequence
6
+ from dataclasses import dataclass
7
+ from typing import Literal
8
+
9
+ from agentbom.models import Artifact, Finding, Location, McpServer, RuleId
10
+ from agentbom.rules._prose import regions
11
+ from agentbom.rules._surfaces import (
12
+ Context,
13
+ SeverityTable,
14
+ Surface,
15
+ field_label,
16
+ line_of,
17
+ surfaces,
18
+ )
19
+
20
+ _SEVERITY: SeverityTable = {
21
+ "executable": "high",
22
+ "config": "high",
23
+ "skill_prose": "high",
24
+ "rules_prose": "high",
25
+ }
26
+ _COMMANDS: frozenset[Context] = frozenset({"executable", "skill_prose", "rules_prose"})
27
+ _PROSE: frozenset[Context] = frozenset({"skill_prose", "rules_prose"})
28
+ _FIX = "remove the outbound transfer or move it behind a reviewed, allowlisted integration"
29
+
30
+ _LOCAL_HOST = r"(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?![\w.-])"
31
+ _LOCAL = re.compile(_LOCAL_HOST, re.IGNORECASE)
32
+ _EXTERNAL_URL = re.compile(rf"\bhttps?://(?!{_LOCAL_HOST})[\w\[]", re.IGNORECASE)
33
+ _DATA_FLAG = r"\s(?:-d|--data(?:-binary|-urlencode|-ascii)?)(?:[ \t]+|=)"
34
+ _FORM_FLAG = r"\s(?:-F|--form)(?:[ \t]+|=)"
35
+ _SECRET_VAR = (
36
+ r"\$\{?(?-i:[A-Z_][A-Z0-9_]*?(?:TOKEN|SECRET|KEY|PASSWORD|PASSWD|CREDENTIAL|AUTH)[A-Z0-9_]*)"
37
+ )
38
+ _WHOLE_ENV = r"\bprocess\.env\b(?!\s*\??\.|\s*\[)"
39
+ _HOST_START = r"(?:\b(?:https?|wss?)://|(?<![\w./@-]))"
40
+ _SEND_VERB = r"\b(?:send|post|upload|transmit|exfiltrate|forward|beacon)\b"
41
+ # Model tokens ("prompt tokens", "token usage") are not credentials.
42
+ _TOKEN = (
43
+ r"(?<!prompt )(?<!input )(?<!output )(?<!completion )"
44
+ r"tokens?\b(?!\s+(?:counts?|usage|limits?|budgets?|costs?|windows?)\b)"
45
+ )
46
+ _SECRET_OBJECT = (
47
+ rf"(?:environment\s+variables|env\s+vars|(?<![\w.$-])\.env\b|secrets?|{_TOKEN}|credentials?"
48
+ r"|api[\s_-]?keys?|ssh\s+keys?|the\s+(?:file|repository|repo|codebase)\s+contents)\b"
49
+ )
50
+ # "Send requests with your API key in the Authorization header" is how an API is
51
+ # called, not a transfer of the key.
52
+ _AUTH_CONTEXT = re.compile(r"\b(?:headers?|authorization|bearer|authenticat\w*)\b", re.I)
53
+
54
+
55
+ @dataclass(frozen=True)
56
+ class _Pattern:
57
+ label: str
58
+ regex: re.Pattern[str]
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class _Family:
63
+ contexts: frozenset[Context]
64
+ action: str
65
+ instruction: str
66
+ patterns: tuple[_Pattern, ...]
67
+ # line: skip a command whose line targets only localhost. sentence: the
68
+ # sentence must name an external URL and not be about authentication.
69
+ target: Literal["line", "sentence", "any"]
70
+
71
+
72
+ def _patterns(*sources: str, label: str = "") -> tuple[_Pattern, ...]:
73
+ return tuple(_Pattern(label, re.compile(s, re.IGNORECASE | re.MULTILINE)) for s in sources)
74
+
75
+
76
+ def _hosts(*pairs: tuple[str, str]) -> tuple[_Pattern, ...]:
77
+ return tuple(p for label, host in pairs for p in _patterns(_HOST_START + host, label=label))
78
+
79
+
80
+ _ENV_TO_NETWORK = _Family(
81
+ _COMMANDS,
82
+ "sends environment variables to an external URL",
83
+ "send environment variables to an external URL",
84
+ _patterns(
85
+ r"\b(?:env|printenv|set)\b[ \t]*\|[^\n]*\b(?:curl|wget|nc|ncat|netcat|socat)\b",
86
+ rf"\bcurl\b[^\n]*?(?:{_DATA_FLAG}|{_FORM_FLAG}|\s(?:-T|--upload-file)(?:[ \t]+|=))"
87
+ r"[^\n]*\$\([ \t]*(?:env|printenv)[ \t]*\)",
88
+ # Single quotes stop the shell expanding the variable, so only double
89
+ # quotes or a bare word carry its value.
90
+ rf"\bcurl\b[^\n]*?(?:{_DATA_FLAG}|{_FORM_FLAG})(?:\"[^\"\n]*?|[^\s'\"]*?){_SECRET_VAR}",
91
+ rf"\bfetch\([^)]*?\bbody\s*:[^,}}]*?{_WHOLE_ENV}",
92
+ rf"\b(?:axios|got|request|superagent|needle)\.post\([^)]*?{_WHOLE_ENV}",
93
+ r"\b(?:requests|httpx)\.(?:post|put|patch)\([^)]*?\bos\.environ\b(?!\s*\[|\s*\.get\b)",
94
+ r"\bjson\s*=\s*dict\(\s*os\.environ\s*\)",
95
+ r"\bInvoke-(?:RestMethod|WebRequest)\b[^\n]*-Method[ \t]+Post\b[^\n]*-Body\b[^\n]*\$env:",
96
+ r"\b(?:Get-ChildItem|gci|ls|dir)[ \t]+env:[^\n]*\|[^\n]*"
97
+ r"\bInvoke-(?:RestMethod|WebRequest)\b",
98
+ ),
99
+ "line",
100
+ )
101
+ _FILE_TO_NETWORK = _Family(
102
+ _COMMANDS,
103
+ "sends file contents to an external URL",
104
+ "send file contents to an external URL",
105
+ _patterns(
106
+ # `@-` is stdin, which the env-to-network patterns cover when it is the environment.
107
+ rf"\bcurl\b[^\n]*?{_DATA_FLAG}[\"']?@(?!-)",
108
+ rf"\bcurl\b[^\n]*?{_FORM_FLAG}[\"']?[^\s=\"']*=[@<](?!-)",
109
+ r"\bcurl\b[^\n]*?\s(?:-T|--upload-file)(?:[ \t]+|=)[\"']?(?!-[\s\"'])\S",
110
+ r"\bwget\b[^\n]*--post-file\b",
111
+ r"\b(?:nc|ncat|netcat)\b[ \t]+\S+[ \t]+\d+[ \t]*<[ \t]*\S+",
112
+ ),
113
+ "line",
114
+ )
115
+ _WEBHOOK_URL = _Family(
116
+ frozenset({"executable", "config"}),
117
+ "contains a webhook or capture URL",
118
+ "",
119
+ _hosts(
120
+ ("Slack webhook", r"hooks\.slack\.com/services/"),
121
+ ("Discord webhook", r"(?:[\w-]+\.)?discord(?:app)?\.com/api/webhooks/"),
122
+ ("webhook.site", r"webhook\.site\b"),
123
+ ("RequestBin", r"(?:[\w-]+\.)*requestbin\.[a-z]+\b"),
124
+ ("Pipedream", r"(?:[\w-]+\.)+pipedream\.net\b"),
125
+ ("ngrok tunnel", r"(?:[\w-]+\.)+ngrok(?:-free)?\.(?:io|app)\b"),
126
+ ("Interactsh", r"(?:[\w-]+\.)+interact\.sh\b"),
127
+ ("OAST", r"(?:[\w-]+\.)+oast\.(?:fun|me|online|pro|site|live)\b"),
128
+ ("Burp Collaborator", r"(?:[\w-]+\.)+(?:burpcollaborator\.net|oastify\.com)\b"),
129
+ ("Canarytokens", r"(?:[\w-]+\.)*canarytokens\.com\b"),
130
+ ),
131
+ "any",
132
+ )
133
+ _EXFIL_INSTRUCTION = _Family(
134
+ _PROSE,
135
+ "",
136
+ "send secrets to an external URL",
137
+ _patterns(rf"{_SEND_VERB}(?:\W+[\w-]+){{0,4}}?\W*{_SECRET_OBJECT}"),
138
+ "sentence",
139
+ )
140
+ _FAMILIES = (_ENV_TO_NETWORK, _FILE_TO_NETWORK, _WEBHOOK_URL, _EXFIL_INSTRUCTION)
141
+
142
+
143
+ def _line(text: str, match: re.Match[str]) -> str:
144
+ end = text.find("\n", match.end())
145
+ return text[text.rfind("\n", 0, match.start()) + 1 : len(text) if end < 0 else end]
146
+
147
+
148
+ def _only_local(line: str) -> bool:
149
+ return _LOCAL.search(line) is not None and _EXTERNAL_URL.search(line) is None
150
+
151
+
152
+ def _counts(family: _Family, region: str, hit: re.Match[str]) -> bool:
153
+ match family.target:
154
+ case "line":
155
+ return not _only_local(_line(region, hit))
156
+ case "sentence":
157
+ return _EXTERNAL_URL.search(region) is not None and _AUTH_CONTEXT.search(region) is None
158
+ case "any":
159
+ return True
160
+
161
+
162
+ def _first_match(family: _Family, surface: Surface) -> tuple[int, int, str] | None:
163
+ for region in regions(surface):
164
+ hits = [
165
+ (region.start + hit.start(), region.start + hit.end(), pattern.label)
166
+ for pattern in family.patterns
167
+ for hit in pattern.regex.finditer(region.text)
168
+ if _counts(family, region.text, hit)
169
+ ]
170
+ if hits:
171
+ return min(hits)
172
+ return None
173
+
174
+
175
+ def _applies(family: _Family, surface: Surface) -> bool:
176
+ if surface.context not in family.contexts:
177
+ return False
178
+ # Which remote MCP hosts are allowed is a policy decision, not this rule's.
179
+ return not (isinstance(surface.artifact, McpServer) and surface.field == "url")
180
+
181
+
182
+ def _findings(surface: Surface) -> Iterator[Finding]:
183
+ severity = _SEVERITY.get(surface.context)
184
+ if severity is None:
185
+ return
186
+ reported: list[tuple[int, int]] = []
187
+ for family in _FAMILIES:
188
+ if not _applies(family, surface):
189
+ continue
190
+ found = _first_match(family, surface)
191
+ if found is None:
192
+ continue
193
+ start, end, label = found
194
+ if any(start < done_end and done_start < end for done_start, done_end in reported):
195
+ continue
196
+ reported.append((start, end))
197
+ action = (
198
+ f"tells the agent to {family.instruction}"
199
+ if surface.context in _PROSE
200
+ else family.action
201
+ )
202
+ yield Finding(
203
+ rule_id="ABOM-004",
204
+ severity=severity,
205
+ confidence="medium",
206
+ message=f"{field_label(surface)} {action}" + (f" ({label})" if label else ""),
207
+ location=Location(path=surface.artifact.source.path, line=line_of(surface, start)),
208
+ artifact_id=surface.artifact.id,
209
+ fix=_FIX,
210
+ )
211
+
212
+
213
+ class OutboundDataTransfer:
214
+ rule_id: RuleId = "ABOM-004"
215
+
216
+ def run(self, artifacts: Sequence[Artifact]) -> Iterator[Finding]:
217
+ for artifact in artifacts:
218
+ for surface in surfaces(artifact):
219
+ yield from _findings(surface)
@@ -0,0 +1,399 @@
1
+ """ABOM-005: an MCP server launched from a package, image or git source with no exact version."""
2
+
3
+ import re
4
+ import shlex
5
+ from collections.abc import Callable, Iterator, Sequence
6
+ from dataclasses import dataclass
7
+ from pathlib import PureWindowsPath
8
+
9
+ from agentbom.models import Artifact, Finding, Location, McpServer, RuleId, StdioLaunch
10
+
11
+ _SEMVER = re.compile(
12
+ r"v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?"
13
+ )
14
+ _COMMIT = re.compile(r"[0-9a-fA-F]{40}")
15
+ _NPM_GIT_PREFIXES = ("git+", "git://", "github:", "gitlab:", "bitbucket:", "gist:")
16
+ _GITHUB_SHORTHAND = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(#.*)?")
17
+ _PY_NAME = r"[A-Za-z0-9][A-Za-z0-9._-]*(?:\[[^\]]*\])?"
18
+ _PEP440_EXACT = re.compile(rf"{_PY_NAME}\s*===?\s*[A-Za-z0-9.!+_-]+")
19
+ _UV_AT_VERSION = re.compile(rf"{_PY_NAME}@v?\d+(?:\.\d+)+[A-Za-z0-9.+_-]*")
20
+ _PY_GIT_COMMIT = re.compile(r"@[0-9a-fA-F]{40}(#|$)")
21
+ _GIT_REF = re.compile(r"@[^/@]*$")
22
+ _USERINFO = re.compile(r"(?<=://)[^/@\s]*@")
23
+ _WINDOWS_DRIVE = re.compile(r"[A-Za-z]:[\\/]")
24
+ _PATH_START = re.compile(r"([A-Za-z]:)?[\\/]|\.{1,2}[\\/]|~[\\/]")
25
+ _EXECUTABLE_SUFFIXES = (".exe", ".cmd", ".bat", ".ps1")
26
+
27
+
28
+ def _is_local_path(spec: str) -> bool:
29
+ return (
30
+ spec.startswith((".", "/", "~", "file:"))
31
+ or "\\" in spec
32
+ or _WINDOWS_DRIVE.match(spec) is not None
33
+ )
34
+
35
+
36
+ def _is_unresolved(spec: str) -> bool:
37
+ # A variable expands at launch time, so the scanner cannot see the real version.
38
+ return "$" in spec or "%" in spec or "{{" in spec
39
+
40
+
41
+ def _npm_fix(spec: str) -> str | None:
42
+ if _is_local_path(spec):
43
+ return None
44
+ if spec.startswith(_NPM_GIT_PREFIXES) or _GITHUB_SHORTHAND.fullmatch(spec):
45
+ source, _, ref = spec.partition("#")
46
+ return None if _COMMIT.fullmatch(ref) else f"pin a commit, e.g. {source}#<commit-sha>"
47
+ if "://" in spec:
48
+ return None
49
+ at = spec.rfind("@")
50
+ name, version = (spec[:at], spec[at + 1 :]) if at > 0 else (spec, "")
51
+ return None if _SEMVER.fullmatch(version) else f"pin an exact version, e.g. {name}@<x.y.z>"
52
+
53
+
54
+ def _python_fix(spec: str) -> str | None:
55
+ if "git+" in spec:
56
+ if _PY_GIT_COMMIT.search(spec):
57
+ return None
58
+ return f"pin a commit, e.g. {_GIT_REF.sub('', spec)}@<commit-sha>"
59
+ if _is_local_path(spec) or "://" in spec or "/" in spec:
60
+ return None
61
+ if _PEP440_EXACT.fullmatch(spec) or _UV_AT_VERSION.fullmatch(spec):
62
+ return None
63
+ name = re.match(r"[A-Za-z0-9._-]*", spec)
64
+ return f"pin an exact version, e.g. {name.group() if name else spec}==<x.y.z>"
65
+
66
+
67
+ def _image_fix(image: str) -> str | None:
68
+ if "@sha256:" in image:
69
+ return None
70
+ last = image.rsplit("/", 1)[-1]
71
+ repository, _, tag = last.partition(":")
72
+ if tag and tag != "latest":
73
+ return None
74
+ base = image[: len(image) - len(last)] + repository
75
+ return f"pin a version tag or digest, e.g. {base}@sha256:<digest>"
76
+
77
+
78
+ @dataclass(frozen=True)
79
+ class _Launcher:
80
+ tool: str
81
+ noun: str
82
+ fix: Callable[[str], str | None]
83
+ package_flags: frozenset[str] = frozenset()
84
+ value_flags: frozenset[str] = frozenset()
85
+
86
+
87
+ _NPX = _Launcher(
88
+ "npx",
89
+ "package",
90
+ _npm_fix,
91
+ frozenset({"-p", "--package"}),
92
+ frozenset(
93
+ {"-c", "--call", "--registry", "--cache", "--userconfig", "-w", "--workspace", "--prefix"}
94
+ ),
95
+ )
96
+ _UV_VALUE_FLAGS = frozenset(
97
+ {
98
+ "--with",
99
+ "--with-editable",
100
+ "--with-requirements",
101
+ "-p",
102
+ "--python",
103
+ "--python-preference",
104
+ "--index",
105
+ "--default-index",
106
+ "-i",
107
+ "--index-url",
108
+ "--extra-index-url",
109
+ "-f",
110
+ "--find-links",
111
+ "--index-strategy",
112
+ "--keyring-provider",
113
+ "-c",
114
+ "--constraints",
115
+ "--overrides",
116
+ "-b",
117
+ "--build-constraints",
118
+ "-C",
119
+ "--config-setting",
120
+ "--resolution",
121
+ "--prerelease",
122
+ "--exclude-newer",
123
+ "--link-mode",
124
+ "-P",
125
+ "--upgrade-package",
126
+ "--reinstall-package",
127
+ "--refresh-package",
128
+ "--no-build-package",
129
+ "--no-binary-package",
130
+ "--allow-insecure-host",
131
+ "--env-file",
132
+ "--directory",
133
+ "--project",
134
+ "--cache-dir",
135
+ "--config-file",
136
+ "--color",
137
+ }
138
+ )
139
+ _CONTAINER_VALUE_FLAGS = frozenset(
140
+ {
141
+ "-a",
142
+ "--attach",
143
+ "--add-host",
144
+ "--annotation",
145
+ "--arch",
146
+ "--authfile",
147
+ "--blkio-weight",
148
+ "--blkio-weight-device",
149
+ "--cap-add",
150
+ "--cap-drop",
151
+ "--cgroup-parent",
152
+ "--cgroupns",
153
+ "--cidfile",
154
+ "-c",
155
+ "--cpu-shares",
156
+ "--cpu-period",
157
+ "--cpu-quota",
158
+ "--cpu-rt-period",
159
+ "--cpu-rt-runtime",
160
+ "--cpus",
161
+ "--cpuset-cpus",
162
+ "--cpuset-mems",
163
+ "--creds",
164
+ "--detach-keys",
165
+ "--device",
166
+ "--device-cgroup-rule",
167
+ "--device-read-bps",
168
+ "--device-read-iops",
169
+ "--device-write-bps",
170
+ "--device-write-iops",
171
+ "--dns",
172
+ "--dns-option",
173
+ "--dns-search",
174
+ "--domainname",
175
+ "-e",
176
+ "--env",
177
+ "--entrypoint",
178
+ "--env-file",
179
+ "--expose",
180
+ "--gidmap",
181
+ "--gpus",
182
+ "--group-add",
183
+ "--health-cmd",
184
+ "--health-interval",
185
+ "--health-retries",
186
+ "--health-start-interval",
187
+ "--health-start-period",
188
+ "--health-timeout",
189
+ "-h",
190
+ "--hostname",
191
+ "--ip",
192
+ "--ip6",
193
+ "--ipc",
194
+ "--isolation",
195
+ "--kernel-memory",
196
+ "-l",
197
+ "--label",
198
+ "--label-file",
199
+ "--link",
200
+ "--link-local-ip",
201
+ "--log-driver",
202
+ "--log-opt",
203
+ "--mac-address",
204
+ "-m",
205
+ "--memory",
206
+ "--memory-reservation",
207
+ "--memory-swap",
208
+ "--memory-swappiness",
209
+ "--mount",
210
+ "--name",
211
+ "--net",
212
+ "--network",
213
+ "--network-alias",
214
+ "--oom-score-adj",
215
+ "--os",
216
+ "-p",
217
+ "--publish",
218
+ "--pid",
219
+ "--pids-limit",
220
+ "--platform",
221
+ "--pod",
222
+ "--pull",
223
+ "--restart",
224
+ "--runtime",
225
+ "--secret",
226
+ "--security-opt",
227
+ "--shm-size",
228
+ "--stop-signal",
229
+ "--stop-timeout",
230
+ "--storage-opt",
231
+ "--sysctl",
232
+ "--tmpfs",
233
+ "--tz",
234
+ "--uidmap",
235
+ "--ulimit",
236
+ "--umask",
237
+ "--unsetenv",
238
+ "-u",
239
+ "--user",
240
+ "--userns",
241
+ "--uts",
242
+ "--variant",
243
+ "-v",
244
+ "--volume",
245
+ "--volume-driver",
246
+ "--volumes-from",
247
+ "-w",
248
+ "--workdir",
249
+ }
250
+ )
251
+ _UV = _Launcher("uvx", "package", _python_fix, frozenset({"--from"}), _UV_VALUE_FLAGS)
252
+ _DOCKER = _Launcher("docker", "image", _image_fix, value_flags=_CONTAINER_VALUE_FLAGS)
253
+ _PODMAN = _Launcher("podman", "image", _image_fix, value_flags=_CONTAINER_VALUE_FLAGS)
254
+
255
+ # Keyed by the leading argv words (program name lowercased, without .exe/.cmd).
256
+ _LAUNCHERS: dict[tuple[str, ...], _Launcher] = {
257
+ ("npx",): _NPX,
258
+ ("npm", "exec"): _Launcher(
259
+ "npm exec", "package", _npm_fix, _NPX.package_flags, _NPX.value_flags
260
+ ),
261
+ ("npm", "x"): _Launcher("npm exec", "package", _npm_fix, _NPX.package_flags, _NPX.value_flags),
262
+ ("bunx",): _Launcher(
263
+ "bunx", "package", _npm_fix, frozenset({"-p", "--package"}), frozenset({"--cwd"})
264
+ ),
265
+ ("pnpm", "dlx"): _Launcher(
266
+ "pnpm dlx",
267
+ "package",
268
+ _npm_fix,
269
+ frozenset({"--package"}),
270
+ frozenset({"--allow-build", "--registry", "--reporter", "-C", "--dir"}),
271
+ ),
272
+ ("yarn", "dlx"): _Launcher("yarn dlx", "package", _npm_fix, frozenset({"-p", "--package"})),
273
+ ("uvx",): _UV,
274
+ ("uv", "tool", "run"): _Launcher(
275
+ "uv tool run", "package", _python_fix, _UV.package_flags, _UV.value_flags
276
+ ),
277
+ ("pipx", "run"): _Launcher(
278
+ "pipx run",
279
+ "package",
280
+ _python_fix,
281
+ frozenset({"--spec"}),
282
+ frozenset({"--python", "--pip-args", "-i", "--index-url", "--backend"}),
283
+ ),
284
+ ("docker", "run"): _DOCKER,
285
+ ("docker", "container", "run"): _DOCKER,
286
+ ("podman", "run"): _PODMAN,
287
+ ("podman", "container", "run"): _PODMAN,
288
+ }
289
+ _LONGEST_PREFIX = max(len(prefix) for prefix in _LAUNCHERS)
290
+ _PROGRAMS = frozenset({prefix[0] for prefix in _LAUNCHERS} | {"cmd"})
291
+
292
+
293
+ def _split_line(line: str) -> list[str]:
294
+ try:
295
+ return shlex.split(line, posix=True)
296
+ except ValueError:
297
+ return line.split()
298
+
299
+
300
+ def _command_words(command: str) -> list[str]:
301
+ if not any(char.isspace() for char in command):
302
+ return [command]
303
+ # A path with spaces to a launcher is one word; anything else is a whole command line.
304
+ if _PATH_START.match(command) and _program(command) in _PROGRAMS:
305
+ return [command]
306
+ return _split_line(command)
307
+
308
+
309
+ def _argv(launch: StdioLaunch) -> list[str]:
310
+ argv = [*_command_words(launch.command.strip()), *launch.args]
311
+ if len(argv) > 2 and _program(argv[0]) == "cmd" and argv[1].lower() in ("/c", "/k"):
312
+ argv = argv[2:]
313
+ if len(argv) == 1:
314
+ argv = _split_line(argv[0])
315
+ return argv
316
+
317
+
318
+ def _program(word: str) -> str:
319
+ name = PureWindowsPath(word).name.lower()
320
+ for suffix in _EXECUTABLE_SUFFIXES:
321
+ name = name.removesuffix(suffix)
322
+ return name
323
+
324
+
325
+ def _launcher(argv: list[str]) -> tuple[_Launcher, list[str]] | None:
326
+ if not argv:
327
+ return None
328
+ words = [_program(argv[0]), *(word.lower() for word in argv[1:_LONGEST_PREFIX])]
329
+ for length in range(_LONGEST_PREFIX, 0, -1):
330
+ launcher = _LAUNCHERS.get(tuple(words[:length]))
331
+ if launcher is not None:
332
+ return launcher, argv[length:]
333
+ return None
334
+
335
+
336
+ def _specs(launcher: _Launcher, args: list[str]) -> list[str]:
337
+ """The package specs a launcher installs: its package flags, else its first positional."""
338
+ explicit: list[str] = []
339
+ positional: str | None = None
340
+ i = 0
341
+ while i < len(args):
342
+ arg = args[i]
343
+ if arg == "--":
344
+ positional = args[i + 1] if i + 1 < len(args) else None
345
+ break
346
+ if not arg.startswith("-") or arg == "-":
347
+ positional = arg
348
+ break
349
+ name, has_value, value = arg.partition("=")
350
+ if name in launcher.package_flags:
351
+ if has_value:
352
+ explicit.append(value)
353
+ elif i + 1 < len(args):
354
+ explicit.append(args[i + 1])
355
+ i += 1
356
+ elif name in launcher.value_flags and not has_value:
357
+ i += 1
358
+ i += 1
359
+ if explicit:
360
+ return explicit
361
+ return [] if positional is None else [positional]
362
+
363
+
364
+ def _finding(server: McpServer, launch: StdioLaunch) -> Finding | None:
365
+ found = _launcher(_argv(launch))
366
+ if found is None:
367
+ return None
368
+ launcher, args = found
369
+ for spec in _specs(launcher, args):
370
+ if not spec or _is_unresolved(spec):
371
+ continue
372
+ fix = launcher.fix(spec)
373
+ if fix is None:
374
+ continue
375
+ shown = _USERINFO.sub("", spec)
376
+ return Finding(
377
+ rule_id="ABOM-005",
378
+ severity="medium",
379
+ confidence="high",
380
+ message=(
381
+ f'server "{server.name}" runs {launcher.tool} {launcher.noun} "{shown}" '
382
+ "without an exact version"
383
+ ),
384
+ location=Location(path=server.source.path),
385
+ artifact_id=server.id,
386
+ fix=_USERINFO.sub("", fix),
387
+ )
388
+ return None
389
+
390
+
391
+ class UnpinnedServer:
392
+ rule_id: RuleId = "ABOM-005"
393
+
394
+ def run(self, artifacts: Sequence[Artifact]) -> Iterator[Finding]:
395
+ for artifact in artifacts:
396
+ if isinstance(artifact, McpServer) and isinstance(artifact.launch, StdioLaunch):
397
+ finding = _finding(artifact, artifact.launch)
398
+ if finding is not None:
399
+ yield finding
@@ -0,0 +1,52 @@
1
+ """ABOM-006: an artifact whose definition differs from agentbom.lock.
2
+
3
+ Unlike the rules in RULES, drift needs the lockfile, so it reads the drift that
4
+ `diff_lock` computed instead of the artifacts.
5
+ """
6
+
7
+ from collections.abc import Iterator, Sequence
8
+
9
+ from agentbom.lockfile import LOCKFILE_NAME
10
+ from agentbom.models import Drift, DriftKind, Finding, RuleId
11
+
12
+ RULE_ID: RuleId = "ABOM-006"
13
+ _FIX = f"Review the change, then run `agentbom lock` to record it in {LOCKFILE_NAME}."
14
+ _NOUNS: dict[DriftKind, str] = {
15
+ "mcp_server": "MCP server",
16
+ "hook": "hook",
17
+ "skill": "skill",
18
+ "rules": "rules file",
19
+ "script": "script",
20
+ "settings": "settings file",
21
+ "file": "file",
22
+ }
23
+
24
+
25
+ def drift_findings(drift: Sequence[Drift]) -> Iterator[Finding]:
26
+ # A changed file is its own finding only when no artifact in it drifted; the diff
27
+ # still lists it, so a change the artifacts do not show stays visible.
28
+ reported = {item.location.path for item in drift if item.kind != "file"}
29
+ for item in drift:
30
+ if item.kind == "file" and item.location.path in reported:
31
+ continue
32
+ yield Finding(
33
+ rule_id=RULE_ID,
34
+ severity="high",
35
+ confidence="high",
36
+ message=_message(item),
37
+ location=item.location,
38
+ artifact_id=item.artifact_id,
39
+ fix=_FIX,
40
+ )
41
+
42
+
43
+ def _message(item: Drift) -> str:
44
+ subject = f'{_NOUNS[item.kind]} "{item.name}"'
45
+ match item.change:
46
+ case "added":
47
+ return f"{subject} is not in {LOCKFILE_NAME}"
48
+ case "removed":
49
+ return f"{subject} is in {LOCKFILE_NAME} but no longer in the repository"
50
+ case "changed":
51
+ fields = ", ".join(change.field for change in item.fields)
52
+ return f"{subject} differs from {LOCKFILE_NAME}" + (f": {fields}" if fields else "")