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,232 @@
1
+ """ABOM-001: invisible Unicode that can hide instructions from a human reviewer."""
2
+
3
+ import re
4
+ import unicodedata
5
+ from collections.abc import Callable, Iterator, Sequence
6
+ from dataclasses import dataclass, field
7
+ from typing import Literal
8
+
9
+ from pydantic import JsonValue
10
+
11
+ from agentbom.models import Artifact, Finding, Location, RuleId, Rules, Skill
12
+ from agentbom.rules._surfaces import Surface, line_of, surfaces
13
+
14
+ Category = Literal["tag", "zero-width", "bidirectional control"]
15
+
16
+ _CANDIDATES = re.compile(
17
+ "[\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff\U000e0000-\U000e007f]"
18
+ )
19
+ _ALWAYS_HIDDEN: dict[str, Category] = {
20
+ **dict.fromkeys(("\u200b", "\u2060", "\u2061", "\u2062", "\u2063", "\u2064"), "zero-width"),
21
+ **dict.fromkeys(("\u180e", "\ufeff"), "zero-width"),
22
+ **dict.fromkeys(map(chr, range(0x202A, 0x202F)), "bidirectional control"),
23
+ **dict.fromkeys(map(chr, range(0x2066, 0x206A)), "bidirectional control"),
24
+ }
25
+ _TAG_FIRST, _TAG_LAST = 0xE0000, 0xE007F
26
+ _FLAG_BASE = "\U0001f3f4"
27
+ # CLDR subdivision ids, the only tag specs RGI flags use: a region and 1 to 4 alphanumerics.
28
+ _SUBDIVISION = re.compile(
29
+ "[\U000e0061-\U000e007a]{2}[\U000e0030-\U000e0039\U000e0061-\U000e007a]{1,4}"
30
+ )
31
+
32
+ _EMOJI_RANGES = (
33
+ (0x00A9, 0x00A9),
34
+ (0x00AE, 0x00AE),
35
+ (0x203C, 0x203C),
36
+ (0x2049, 0x2049),
37
+ (0x2122, 0x2122),
38
+ (0x2139, 0x2139),
39
+ (0x2190, 0x21FF),
40
+ (0x2300, 0x23FF),
41
+ (0x24C2, 0x24C2),
42
+ (0x25A0, 0x27BF),
43
+ (0x2934, 0x2935),
44
+ (0x2B00, 0x2BFF),
45
+ (0x3030, 0x3030),
46
+ (0x303D, 0x303D),
47
+ (0x3297, 0x3297),
48
+ (0x3299, 0x3299),
49
+ (0xFE0F, 0xFE0F),
50
+ (0x1F000, 0x1FFFD),
51
+ )
52
+ # Scripts whose orthography uses ZWJ/ZWNJ: Arabic (and Persian), the Indic scripts,
53
+ # Sinhala, Myanmar and Khmer.
54
+ _JOINING_SCRIPT_RANGES = (
55
+ (0x0600, 0x06FF),
56
+ (0x0750, 0x077F),
57
+ (0x08A0, 0x08FF),
58
+ (0x0900, 0x0DFF),
59
+ (0x1000, 0x109F),
60
+ (0x1780, 0x17FF),
61
+ (0xFB50, 0xFDFF),
62
+ (0xFE70, 0xFEFC),
63
+ )
64
+
65
+
66
+ def _in(ranges: tuple[tuple[int, int], ...], char: str) -> bool:
67
+ code = ord(char)
68
+ return any(low <= code <= high for low, high in ranges)
69
+
70
+
71
+ def _before(text: str, i: int) -> str:
72
+ return text[i - 1] if i > 0 else ""
73
+
74
+
75
+ def _after(text: str, i: int) -> str:
76
+ return text[i + 1] if i + 1 < len(text) else ""
77
+
78
+
79
+ def _joining_letter(char: str) -> bool:
80
+ # Indic conjuncts put the joiner after a virama, a combining mark, not a letter.
81
+ return (
82
+ bool(char) and _in(_JOINING_SCRIPT_RANGES, char) and unicodedata.category(char)[0] in "LM"
83
+ )
84
+
85
+
86
+ def _zwj_allowed(text: str, i: int) -> bool:
87
+ before, after = _before(text, i), _after(text, i)
88
+ emoji = bool(before and after) and _in(_EMOJI_RANGES, before) and _in(_EMOJI_RANGES, after)
89
+ return emoji or _joining_letter(before)
90
+
91
+
92
+ def _zwnj_allowed(text: str, i: int) -> bool:
93
+ return _joining_letter(_before(text, i))
94
+
95
+
96
+ def _mark_allowed(text: str, i: int) -> bool:
97
+ start = text.rfind("\n", 0, i) + 1
98
+ end = text.find("\n", i)
99
+ line = text[start : end if end != -1 else len(text)]
100
+ return any(
101
+ unicodedata.bidirectional(char) in ("R", "AL") and unicodedata.category(char)[0] == "L"
102
+ for char in line
103
+ )
104
+
105
+
106
+ # Characters that are legitimate in some neighborhoods: category, and when they are allowed.
107
+ _CONDITIONAL: dict[str, tuple[Category, Callable[[str, int], bool]]] = {
108
+ "\u200d": ("zero-width", _zwj_allowed),
109
+ "\u200c": ("zero-width", _zwnj_allowed),
110
+ "\u200e": ("bidirectional control", _mark_allowed),
111
+ "\u200f": ("bidirectional control", _mark_allowed),
112
+ "\u061c": ("bidirectional control", _mark_allowed),
113
+ }
114
+
115
+
116
+ def _is_tag(char: str) -> bool:
117
+ return _TAG_FIRST <= ord(char) <= _TAG_LAST
118
+
119
+
120
+ def _is_flag_sequence(text: str, start: int, end: int) -> bool:
121
+ """Whether tags text[start:end] are the spec and terminator of a subdivision flag."""
122
+ return (
123
+ _before(text, start) == _FLAG_BASE
124
+ and text[end - 1] == chr(_TAG_LAST)
125
+ and _SUBDIVISION.fullmatch(text, start, end - 1) is not None
126
+ )
127
+
128
+
129
+ @dataclass
130
+ class _Tally:
131
+ first: int
132
+ count: int = 0
133
+ decoded: int = 0
134
+ code_points: set[int] = field(default_factory=set)
135
+
136
+ def add(self, char: str) -> None:
137
+ self.count += 1
138
+ self.code_points.add(ord(char))
139
+ if 0xE0020 <= ord(char) <= 0xE007E:
140
+ self.decoded += 1
141
+
142
+
143
+ def _tally(text: str) -> dict[Category, _Tally]:
144
+ tallies: dict[Category, _Tally] = {}
145
+
146
+ def add(category: Category, offset: int) -> None:
147
+ tallies.setdefault(category, _Tally(first=offset)).add(text[offset])
148
+
149
+ resume = 0
150
+ for match in _CANDIDATES.finditer(text):
151
+ i = match.start()
152
+ if i < resume:
153
+ continue
154
+ char = text[i]
155
+ if _is_tag(char):
156
+ end = i
157
+ while end < len(text) and _is_tag(text[end]):
158
+ end += 1
159
+ resume = end
160
+ if not _is_flag_sequence(text, i, end):
161
+ for offset in range(i, end):
162
+ add("tag", offset)
163
+ elif char in _ALWAYS_HIDDEN:
164
+ add(_ALWAYS_HIDDEN[char], i)
165
+ else:
166
+ category, allowed = _CONDITIONAL[char]
167
+ if not allowed(text, i):
168
+ add(category, i)
169
+ return tallies
170
+
171
+
172
+ def _message(category: Category, tally: _Tally, where: str) -> str:
173
+ codes = sorted(tally.code_points)
174
+ if tally.count == 1:
175
+ message = f"hidden {category} character U+{codes[0]:04X} in {where}"
176
+ else:
177
+ message = f"{tally.count} hidden {category} characters in {where}"
178
+ if category != "tag":
179
+ message += " (" + ", ".join(f"U+{code:04X}" for code in codes) + ")"
180
+ if category == "tag":
181
+ noun = "character" if tally.decoded == 1 else "characters"
182
+ message += f" (decodes to {tally.decoded} ASCII {noun})"
183
+ return message
184
+
185
+
186
+ def _visible(label: str) -> str:
187
+ return _CANDIDATES.sub("?", label)
188
+
189
+
190
+ def _frontmatter_strings(value: JsonValue, where: str) -> Iterator[tuple[str, str]]:
191
+ if isinstance(value, str):
192
+ yield where, value
193
+ elif isinstance(value, dict):
194
+ for key, item in value.items():
195
+ yield from _frontmatter_strings(item, f"{where}.{key}")
196
+ elif isinstance(value, list):
197
+ for index, item in enumerate(value):
198
+ yield from _frontmatter_strings(item, f"{where}[{index}]")
199
+
200
+
201
+ def _texts(artifact: Artifact) -> Iterator[tuple[str, str, Surface | None]]:
202
+ """Every (field, text, surface) to check; surface is None for text with no file line."""
203
+ seen: set[str] = set()
204
+ for surface in surfaces(artifact):
205
+ seen.add(surface.text)
206
+ yield surface.field, surface.text, surface
207
+ yield "name", artifact.name, None
208
+ seen.add(artifact.name)
209
+ if isinstance(artifact, Skill | Rules):
210
+ for where, text in _frontmatter_strings(artifact.frontmatter, "frontmatter"):
211
+ # The skill name and description are already checked as their own fields.
212
+ if text not in seen:
213
+ yield where, text, None
214
+
215
+
216
+ class HiddenUnicode:
217
+ rule_id: RuleId = "ABOM-001"
218
+
219
+ def run(self, artifacts: Sequence[Artifact]) -> Iterator[Finding]:
220
+ for artifact in artifacts:
221
+ for where, text, surface in _texts(artifact):
222
+ for category, tally in _tally(text).items():
223
+ line = line_of(surface, tally.first) if surface is not None else None
224
+ yield Finding(
225
+ rule_id=self.rule_id,
226
+ severity="high",
227
+ confidence="high",
228
+ message=_message(category, tally, _visible(where)),
229
+ location=Location(path=artifact.source.path, line=line),
230
+ artifact_id=artifact.id,
231
+ fix="remove the invisible characters; if intentional, document why",
232
+ )
@@ -0,0 +1,148 @@
1
+ """ABOM-002: commands that download a script and run it, or run a base64-decoded one."""
2
+
3
+ import re
4
+ from collections.abc import Iterator, Sequence
5
+ from dataclasses import dataclass
6
+
7
+ from agentbom.models import Artifact, Finding, Location, RuleId
8
+ from agentbom.rules._prose import regions
9
+ from agentbom.rules._surfaces import SeverityTable, Surface, field_label, line_of, surfaces
10
+
11
+ _SEVERITY: SeverityTable = {"executable": "high", "skill_prose": "medium", "rules_prose": "medium"}
12
+
13
+ _DOWNLOADER = r"\b(?:curl|wget|fetch|iwr|irm|Invoke-WebRequest|Invoke-RestMethod)\b"
14
+ _SUDO_ENV = r"(?:sudo[ \t]+(?:-\S+[ \t]+)*)?(?:env[ \t]+)?(?:\w+=\S*[ \t]+)*"
15
+ _SHELL = r"(?:ba|z|da|k|fi)?sh\b"
16
+ # An interpreter runs piped input only with no script argument, or with `-`;
17
+ # `python -m json.tool` or `node -e '...'` just reads it as data.
18
+ _INTERPRETER = r"(?:python[0-9.]*|node|perl|ruby)(?=[ \t]*(?:$|\n|[;&|)'\"`]|-(?:\s|$)))"
19
+ _POWERSHELL = r"(?:iex|Invoke-Expression|pwsh|powershell)\b"
20
+ _FETCHED = r"[ \t]*(?:curl|wget)\b"
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class _Family:
25
+ label: str
26
+ action: str
27
+ instruction: str
28
+ patterns: tuple[re.Pattern[str], ...]
29
+ executable_only: bool = False
30
+
31
+
32
+ def _compile(*patterns: str) -> tuple[re.Pattern[str], ...]:
33
+ return tuple(re.compile(p, re.IGNORECASE | re.MULTILINE) for p in patterns)
34
+
35
+
36
+ _DOWNLOAD_AND_RUN = ("downloads and runs remote code", "download and run remote code")
37
+ _DECODE_AND_RUN = ("runs an obfuscated command", "run an obfuscated command")
38
+
39
+ _FAMILIES: tuple[_Family, ...] = (
40
+ _Family(
41
+ "pipe to shell",
42
+ *_DOWNLOAD_AND_RUN,
43
+ _compile(
44
+ rf"{_DOWNLOADER}[^\n|;&]*\|[ \t]*{_SUDO_ENV}(?:{_SHELL}|{_INTERPRETER}|{_POWERSHELL})"
45
+ ),
46
+ ),
47
+ _Family(
48
+ "process substitution",
49
+ *_DOWNLOAD_AND_RUN,
50
+ _compile(
51
+ rf"\b(?:(?:ba|z)?sh|source)[ \t]+<\({_FETCHED}",
52
+ rf"(?:^|[\s;&|])\.[ \t]+<\({_FETCHED}",
53
+ ),
54
+ ),
55
+ _Family(
56
+ "eval of fetched content",
57
+ *_DOWNLOAD_AND_RUN,
58
+ _compile(
59
+ rf"\beval[ \t]+[\"']?(?:\$\(|`){_FETCHED}",
60
+ rf"\b(?:ba|z)?sh[ \t]+-c[ \t]+[\"']?(?:\$\(|`){_FETCHED}",
61
+ rf"\bpython[0-9.]*[ \t]+-c[ \t]+[\"']?(?:\$\(|`){_FETCHED}",
62
+ ),
63
+ ),
64
+ _Family(
65
+ "PowerShell download and invoke",
66
+ *_DOWNLOAD_AND_RUN,
67
+ _compile(
68
+ r"\b(?:iex|Invoke-Expression)\b[^\n]*\b(?:DownloadString|DownloadFile|Invoke-WebRequest"
69
+ r"|iwr|irm|Invoke-RestMethod|Net\.WebClient)\b",
70
+ r"\b(?:DownloadString|irm|iwr|Invoke-RestMethod|Invoke-WebRequest)\b[^\n]*\|[ \t]*"
71
+ r"(?:iex|Invoke-Expression)\b",
72
+ ),
73
+ ),
74
+ _Family(
75
+ "encoded PowerShell command",
76
+ *_DECODE_AND_RUN,
77
+ _compile(
78
+ r"\b(?:powershell|pwsh)(?:\.exe)?(?:[ \t]+\S+)*?[ \t]+-(?:e|ec|enc|encodedcommand)"
79
+ r"[ \t]+[A-Za-z0-9+/=]{20,}"
80
+ ),
81
+ ),
82
+ _Family(
83
+ "base64-decoded command",
84
+ *_DECODE_AND_RUN,
85
+ _compile(
86
+ r"\bbase64[ \t]+(?:-d|--decode)\b[^\n|]*\|[ \t]*(?:sudo[ \t]+)?(?:ba|z)?sh\b",
87
+ r"\bexec\([ \t]*(?:base64\.)?b64decode\(",
88
+ r"\beval\([ \t]*(?:atob|Buffer\.from)\(",
89
+ ),
90
+ ),
91
+ _Family(
92
+ "fetched script",
93
+ *_DOWNLOAD_AND_RUN,
94
+ _compile(
95
+ r"\beval\(\s*await\s+\(?\s*await\s+fetch\(",
96
+ r"\bnew\s+Function\([^)]*\bfetch\(",
97
+ r"\bexec\(\s*(?:requests\.get|urllib\.request\.urlopen)\(",
98
+ ),
99
+ executable_only=True,
100
+ ),
101
+ )
102
+
103
+
104
+ def _first_match(family: _Family, surface: Surface) -> tuple[int, int] | None:
105
+ for region in regions(surface):
106
+ found = [m for p in family.patterns if (m := p.search(region.text))]
107
+ if found:
108
+ first = min(found, key=lambda m: m.start())
109
+ return region.start + first.start(), region.start + first.end()
110
+ return None
111
+
112
+
113
+ def _findings(surface: Surface) -> Iterator[Finding]:
114
+ severity = _SEVERITY.get(surface.context)
115
+ if severity is None:
116
+ return
117
+ reported: list[tuple[int, int]] = []
118
+ for family in _FAMILIES:
119
+ if family.executable_only and surface.context != "executable":
120
+ continue
121
+ span = _first_match(family, surface)
122
+ # One command often matches two families (`irm x | iex`); report it once.
123
+ if span is None or any(span[0] < end and start < span[1] for start, end in reported):
124
+ continue
125
+ reported.append(span)
126
+ action = (
127
+ family.action
128
+ if surface.context == "executable"
129
+ else f"tells the agent to {family.instruction}"
130
+ )
131
+ yield Finding(
132
+ rule_id="ABOM-002",
133
+ severity=severity,
134
+ confidence="medium",
135
+ message=f"{field_label(surface)} {action} ({family.label})",
136
+ location=Location(path=surface.artifact.source.path, line=line_of(surface, span[0])),
137
+ artifact_id=surface.artifact.id,
138
+ fix="download to a file, verify a pinned checksum or signature, then run it",
139
+ )
140
+
141
+
142
+ class RemoteScriptExecution:
143
+ rule_id: RuleId = "ABOM-002"
144
+
145
+ def run(self, artifacts: Sequence[Artifact]) -> Iterator[Finding]:
146
+ for artifact in artifacts:
147
+ for surface in surfaces(artifact):
148
+ yield from _findings(surface)
@@ -0,0 +1,200 @@
1
+ """ABOM-003: hooks, scripts or instructions that read SSH keys, credential files,
2
+ OS credential stores, browser profiles or .env files."""
3
+
4
+ import re
5
+ from collections.abc import Iterator, Sequence
6
+ from dataclasses import dataclass
7
+
8
+ from agentbom.models import Artifact, Finding, Location, RuleId
9
+ from agentbom.rules._prose import regions
10
+ from agentbom.rules._surfaces import SeverityTable, Surface, field_label, line_of, surfaces
11
+
12
+ _SEVERITY: SeverityTable = {"executable": "high", "skill_prose": "medium", "rules_prose": "medium"}
13
+
14
+ _HOME = (
15
+ r"(?:~|\$HOME|\$\{HOME\}|%USERPROFILE%|%HOME%|\$env:USERPROFILE|\$env:HOME"
16
+ r"|/root|/home/[\w.-]+|/Users/[\w.-]+|[A-Za-z]:[/\\]{1,2}Users[/\\]{1,2}[\w.-]+)"
17
+ )
18
+ _SEP = r"[/\\]{1,2}"
19
+ _DOTENV = r"(?<![\w.$-])\.env(?!\.(?:example|sample|template|dist)\b)(?:\.[\w-]+)?(?![\w-])"
20
+ # Copying a template into place, and ignore files, are setup rather than reads.
21
+ _DOTENV_SETUP = re.compile(r"\.env\.(?:example|sample|template|dist)\b|\wignore\b", re.IGNORECASE)
22
+ _VERBS = (
23
+ "read|cat|open|print|show|display|copy|send|upload|include|paste|output|dump"
24
+ "|exfiltrate|collect|grab|extract|load"
25
+ )
26
+ # "Open .env in your editor" and "load .env with direnv" are setup steps, not reads.
27
+ _DOTENV_VERBS = "|".join(v for v in _VERBS.split("|") if v not in ("open", "load"))
28
+ _PERMISSION_RULE = re.compile(
29
+ r"\b(?:Read|Edit|MultiEdit|Write|Glob|Grep|Bash|WebFetch|NotebookEdit)\([^)\n]*$"
30
+ )
31
+ _EXCLUDE_OPTION = re.compile(r"(?:--exclude(?:-from)?|--ignore|\s-x)[= \t]+['\"]?[^\s'\"]*$")
32
+ # ssh authenticating with a key, or ssh-add and ssh-keygen managing one, uses the
33
+ # key without reading it out; `scp key host:` still counts.
34
+ _KEY_IN_USE = re.compile(
35
+ r"(?:\b(?:ssh|scp|sftp)\b[^\n|;&]*\s-i[ \t]*['\"]?|\bssh-(?:add|keygen)\b[^\n|;&]*\s"
36
+ r"|\bIdentityFile[ \t=]+['\"]?)\S*$"
37
+ )
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class _Path:
42
+ label: str
43
+ pattern: re.Pattern[str]
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class _Family:
48
+ description: str
49
+ executable: tuple[_Path, ...]
50
+ prose: tuple[_Path, ...]
51
+ # Prose must also say to read; None when the match is itself a command.
52
+ verbs: re.Pattern[str] | None
53
+ # A line or sentence matching this is not a read.
54
+ unless: re.Pattern[str] | None = None
55
+
56
+
57
+ def _paths(label: str, *patterns: str) -> tuple[_Path, ...]:
58
+ return tuple(_Path(label, re.compile(p, re.IGNORECASE | re.MULTILINE)) for p in patterns)
59
+
60
+
61
+ def _verbs(words: str) -> re.Pattern[str]:
62
+ return re.compile(rf"\b(?:{words})\b", re.IGNORECASE)
63
+
64
+
65
+ _SSH = (
66
+ *_paths("private key", rf"\.ssh{_SEP}id_[\w-]+(?![\w-]|\.pub)"),
67
+ *_paths(
68
+ "~/.ssh directory",
69
+ rf"{_HOME}{_SEP}\.ssh{_SEP}\*(?!\.pub)",
70
+ rf"\b(?:tar|zip|rsync|scp|cp[ \t]+-\w*[rRa]\w*)\b[^\n|;&]*{_HOME}{_SEP}\.ssh(?:{_SEP})?"
71
+ r"(?=$|[\s'\"])",
72
+ ),
73
+ )
74
+ _CLOUD = (
75
+ *_paths("AWS credentials", rf"\.aws{_SEP}credentials\b"),
76
+ *_paths(
77
+ "gcloud credentials",
78
+ rf"{_HOME}{_SEP}\.config{_SEP}gcloud{_SEP}(?:application_default_)?credentials\.json",
79
+ ),
80
+ *_paths("Azure CLI profile", rf"{_HOME}{_SEP}\.azure\b"),
81
+ *_paths("kubeconfig", rf"{_HOME}{_SEP}\.kube{_SEP}config\b"),
82
+ *_paths("Docker credentials", rf"{_HOME}{_SEP}\.docker{_SEP}config\.json"),
83
+ *_paths(".netrc", rf"{_HOME}{_SEP}[._]netrc\b"),
84
+ *_paths(".npmrc", rf"{_HOME}{_SEP}\.npmrc\b"),
85
+ *_paths(".pypirc", rf"{_HOME}{_SEP}\.pypirc\b"),
86
+ *_paths("git credentials", rf"{_HOME}{_SEP}\.git-credentials\b"),
87
+ *_paths("GitHub CLI token", rf"{_HOME}{_SEP}\.config{_SEP}gh{_SEP}hosts\.yml"),
88
+ )
89
+ _KEYCHAIN = (
90
+ *_paths(
91
+ "macOS keychain",
92
+ r"\bsecurity[ \t]+(?:find-generic-password|find-internet-password|dump-keychain)\b",
93
+ ),
94
+ *_paths("libsecret", r"\bsecret-tool[ \t]+lookup\b"),
95
+ *_paths(
96
+ "Windows Credential Manager",
97
+ r"\bcmdkey(?:\.exe)?[ \t]+/list\b",
98
+ r"\bGet-StoredCredential\b",
99
+ r"\bCredRead\w*\b",
100
+ ),
101
+ )
102
+ _BROWSER = (
103
+ *_paths(
104
+ "browser profile",
105
+ rf"Library{_SEP}Application Support{_SEP}(?:Google{_SEP}Chrome|BraveSoftware"
106
+ rf"|Microsoft Edge|Firefox)",
107
+ rf"\.mozilla{_SEP}firefox\b",
108
+ rf"\.config{_SEP}(?:google-chrome|chromium|BraveSoftware)\b",
109
+ rf"AppData{_SEP}(?:Local|Roaming){_SEP}(?:Google{_SEP}Chrome|Microsoft{_SEP}Edge"
110
+ rf"|Mozilla{_SEP}Firefox|BraveSoftware)",
111
+ ),
112
+ *_paths("Firefox password store", r"(?<![\w.-])(?:key4\.db|logins\.json)\b"),
113
+ )
114
+ _DOTENV_READS = _paths(
115
+ ".env file",
116
+ # The read command must sit where a command starts, so prose in a comment
117
+ # ("read more about .env") is not a `more .env`.
118
+ r"(?:^|[;&|(`\"'\[,])[ \t]*(?:(?:sudo|xargs|exec|command|then|do|else)[ \t]+)*"
119
+ r"(?:cat|less|more|head|tail|type|bat|xxd|base64|strings|cp|scp|rsync|tar|zip"
120
+ rf"|Get-Content|gc)(?=[ \t])[^\n|;&>]*?(?P<path>{_DOTENV})",
121
+ rf"\bopen\([ \t]*['\"][^'\"\n]*(?P<path>{_DOTENV})['\"]"
122
+ r"(?![ \t]*,[ \t]*(?:mode[ \t]*=[ \t]*)?['\"][wax])",
123
+ rf"\breadFile(?:Sync)?\([ \t]*['\"][^'\"\n]*(?P<path>{_DOTENV})['\"]",
124
+ )
125
+
126
+ _ANY_VERB = _verbs(_VERBS)
127
+ _FAMILIES: tuple[_Family, ...] = (
128
+ _Family("SSH keys", _SSH, _SSH, _ANY_VERB),
129
+ _Family("credential files", _CLOUD, _CLOUD, _ANY_VERB),
130
+ _Family("the OS credential store", _KEYCHAIN, _KEYCHAIN, None),
131
+ _Family("browser data", _BROWSER, _BROWSER, _ANY_VERB),
132
+ _Family(
133
+ "environment secrets",
134
+ _DOTENV_READS,
135
+ _paths(".env file", _DOTENV),
136
+ _verbs(_DOTENV_VERBS),
137
+ _DOTENV_SETUP,
138
+ ),
139
+ )
140
+
141
+
142
+ def _ignored(text: str, match: re.Match[str], scope: str, family: _Family) -> bool:
143
+ path_start = match.start("path") if "path" in match.re.groupindex else match.start()
144
+ before = text[text.rfind("\n", 0, path_start) + 1 : path_start]
145
+ if any(p.search(before) for p in (_PERMISSION_RULE, _EXCLUDE_OPTION, _KEY_IN_USE)):
146
+ return True
147
+ return family.unless is not None and family.unless.search(scope) is not None
148
+
149
+
150
+ def _line(text: str, match: re.Match[str]) -> str:
151
+ end = text.find("\n", match.end())
152
+ return text[text.rfind("\n", 0, match.start()) + 1 : len(text) if end < 0 else end]
153
+
154
+
155
+ def _first_match(family: _Family, surface: Surface) -> tuple[int, str] | None:
156
+ prose = surface.context != "executable"
157
+ for region in regions(surface):
158
+ if prose and family.verbs is not None and family.verbs.search(region.text) is None:
159
+ continue
160
+ hits = [
161
+ (region.start + match.start(), path.label)
162
+ for path in (family.prose if prose else family.executable)
163
+ for match in path.pattern.finditer(region.text)
164
+ if not _ignored(
165
+ region.text, match, region.text if prose else _line(region.text, match), family
166
+ )
167
+ ]
168
+ if hits:
169
+ return min(hits)
170
+ return None
171
+
172
+
173
+ def _findings(surface: Surface) -> Iterator[Finding]:
174
+ severity = _SEVERITY.get(surface.context)
175
+ if severity is None:
176
+ return
177
+ for family in _FAMILIES:
178
+ found = _first_match(family, surface)
179
+ if found is None:
180
+ continue
181
+ offset, label = found
182
+ verb = "reads" if surface.context == "executable" else "tells the agent to read"
183
+ yield Finding(
184
+ rule_id="ABOM-003",
185
+ severity=severity,
186
+ confidence="medium",
187
+ message=f"{field_label(surface)} {verb} {family.description} ({label})",
188
+ location=Location(path=surface.artifact.source.path, line=line_of(surface, offset)),
189
+ artifact_id=surface.artifact.id,
190
+ fix="do not let agent hooks, scripts or instructions access credential files",
191
+ )
192
+
193
+
194
+ class CredentialPathAccess:
195
+ rule_id: RuleId = "ABOM-003"
196
+
197
+ def run(self, artifacts: Sequence[Artifact]) -> Iterator[Finding]:
198
+ for artifact in artifacts:
199
+ for surface in surfaces(artifact):
200
+ yield from _findings(surface)