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.
- agentbom/__init__.py +0 -0
- agentbom/__main__.py +3 -0
- agentbom/cli.py +221 -0
- agentbom/discover.py +337 -0
- agentbom/gitindex.py +119 -0
- agentbom/lockfile.py +261 -0
- agentbom/models.py +180 -0
- agentbom/parsers/__init__.py +53 -0
- agentbom/parsers/_shape.py +96 -0
- agentbom/parsers/hooks.py +146 -0
- agentbom/parsers/jsonc.py +35 -0
- agentbom/parsers/markdown.py +111 -0
- agentbom/parsers/mcp.py +94 -0
- agentbom/parsers/script.py +15 -0
- agentbom/parsers/settings.py +47 -0
- agentbom/policy.py +178 -0
- agentbom/py.typed +0 -0
- agentbom/registry.py +120 -0
- agentbom/report.py +237 -0
- agentbom/rules/__init__.py +51 -0
- agentbom/rules/_prose.py +109 -0
- agentbom/rules/_surfaces.py +92 -0
- agentbom/rules/abom_001_hidden_unicode.py +232 -0
- agentbom/rules/abom_002_remote_exec.py +148 -0
- agentbom/rules/abom_003_credential_paths.py +200 -0
- agentbom/rules/abom_004_outbound_transfer.py +219 -0
- agentbom/rules/abom_005_unpinned.py +399 -0
- agentbom/rules/abom_006_drift.py +52 -0
- agentbom/rules/abom_007_permissions.py +192 -0
- agentbom/rules/abom_008_auto_run_hooks.py +160 -0
- agentbom/rules/abom_009_instruction_override.py +166 -0
- agentbom/rules/abom_010_secrets.py +203 -0
- agentbom/sarif.py +142 -0
- agentbom/scan.py +35 -0
- contextlock-0.1.0.dist-info/METADATA +238 -0
- contextlock-0.1.0.dist-info/RECORD +39 -0
- contextlock-0.1.0.dist-info/WHEEL +4 -0
- contextlock-0.1.0.dist-info/entry_points.txt +3 -0
- contextlock-0.1.0.dist-info/licenses/LICENSE +201 -0
agentbom/registry.py
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import re
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from typing import Literal
|
|
4
|
+
|
|
5
|
+
from pathspec.patterns.gitignore.basic import GitIgnoreBasicPattern
|
|
6
|
+
|
|
7
|
+
from agentbom.models import Agent, ScriptLanguage
|
|
8
|
+
|
|
9
|
+
Format = Literal[
|
|
10
|
+
"mcp_json",
|
|
11
|
+
"vscode_mcp_json",
|
|
12
|
+
"claude_settings_json",
|
|
13
|
+
"nested_hooks_json",
|
|
14
|
+
"cursor_hooks_json",
|
|
15
|
+
"copilot_hooks_json",
|
|
16
|
+
"skill_md",
|
|
17
|
+
"rules_md",
|
|
18
|
+
"script",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(frozen=True)
|
|
23
|
+
class SourcePattern:
|
|
24
|
+
pattern: str
|
|
25
|
+
format: Format
|
|
26
|
+
agents: tuple[Agent, ...]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
_CLAUDE_HOOK_AGENTS: tuple[Agent, ...] = ("claude_code", "cursor", "copilot")
|
|
30
|
+
_CLAUDE_SKILL_AGENTS: tuple[Agent, ...] = ("claude_code", "cursor", "vscode")
|
|
31
|
+
_AGENTS_SKILL_AGENTS: tuple[Agent, ...] = ("codex", "cursor")
|
|
32
|
+
|
|
33
|
+
SCRIPT_LANGUAGES: dict[str, ScriptLanguage] = {
|
|
34
|
+
".sh": "shell",
|
|
35
|
+
".bash": "shell",
|
|
36
|
+
".zsh": "shell",
|
|
37
|
+
".ps1": "powershell",
|
|
38
|
+
".psm1": "powershell",
|
|
39
|
+
".py": "python",
|
|
40
|
+
".js": "javascript",
|
|
41
|
+
".mjs": "javascript",
|
|
42
|
+
".cjs": "javascript",
|
|
43
|
+
".ts": "typescript",
|
|
44
|
+
".mts": "typescript",
|
|
45
|
+
".cts": "typescript",
|
|
46
|
+
".rb": "ruby",
|
|
47
|
+
".pl": "perl",
|
|
48
|
+
".bat": "batch",
|
|
49
|
+
".cmd": "batch",
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
# Directories whose scripts an agent runs, with the agents of the config row that runs them.
|
|
53
|
+
_SCRIPT_DIRECTORIES: tuple[tuple[str, tuple[Agent, ...]], ...] = (
|
|
54
|
+
(".claude/hooks/**/", _CLAUDE_HOOK_AGENTS),
|
|
55
|
+
(".cursor/hooks/**/", ("cursor",)),
|
|
56
|
+
(".codex/hooks/**/", ("codex",)),
|
|
57
|
+
(".github/hooks/**/", ("copilot",)),
|
|
58
|
+
("**/.claude/skills/*/**/", _CLAUDE_SKILL_AGENTS),
|
|
59
|
+
(".agents/skills/*/**/", _AGENTS_SKILL_AGENTS),
|
|
60
|
+
(".cursor/skills/*/**/", ("cursor",)),
|
|
61
|
+
(".github/skills/*/**/", ("copilot",)),
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def _script_rows() -> tuple[SourcePattern, ...]:
|
|
66
|
+
# gitwildmatch has no brace expansion, so each directory and extension is its own row.
|
|
67
|
+
return tuple(
|
|
68
|
+
SourcePattern(f"{directory}*{extension}", "script", agents)
|
|
69
|
+
for directory, agents in _SCRIPT_DIRECTORIES
|
|
70
|
+
for extension in SCRIPT_LANGUAGES
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
REGISTRY: tuple[SourcePattern, ...] = (
|
|
75
|
+
SourcePattern(".mcp.json", "mcp_json", ("claude_code", "vscode")),
|
|
76
|
+
SourcePattern(".cursor/mcp.json", "mcp_json", ("cursor",)),
|
|
77
|
+
SourcePattern(".vscode/mcp.json", "vscode_mcp_json", ("vscode",)),
|
|
78
|
+
SourcePattern(".claude/settings.json", "claude_settings_json", _CLAUDE_HOOK_AGENTS),
|
|
79
|
+
SourcePattern(".claude/settings.local.json", "claude_settings_json", _CLAUDE_HOOK_AGENTS),
|
|
80
|
+
SourcePattern(".codex/hooks.json", "nested_hooks_json", ("codex",)),
|
|
81
|
+
SourcePattern(".cursor/hooks.json", "cursor_hooks_json", ("cursor",)),
|
|
82
|
+
SourcePattern(".github/hooks/*.json", "copilot_hooks_json", ("copilot",)),
|
|
83
|
+
SourcePattern("**/.claude/skills/*/SKILL.md", "skill_md", _CLAUDE_SKILL_AGENTS),
|
|
84
|
+
SourcePattern(".agents/skills/*/SKILL.md", "skill_md", _AGENTS_SKILL_AGENTS),
|
|
85
|
+
SourcePattern(".cursor/skills/*/SKILL.md", "skill_md", ("cursor",)),
|
|
86
|
+
SourcePattern(".github/skills/*/SKILL.md", "skill_md", ("copilot",)),
|
|
87
|
+
SourcePattern("**/.claude/rules/**/*.md", "rules_md", ("claude_code", "vscode")),
|
|
88
|
+
SourcePattern(".claude/commands/**/*.md", "rules_md", ("claude_code",)),
|
|
89
|
+
SourcePattern(".claude/agents/**/*.md", "rules_md", ("claude_code",)),
|
|
90
|
+
SourcePattern("**/AGENTS.md", "rules_md", ("agents_md",)),
|
|
91
|
+
SourcePattern("**/CLAUDE.md", "rules_md", ("claude_code",)),
|
|
92
|
+
SourcePattern("**/CLAUDE.local.md", "rules_md", ("claude_code",)),
|
|
93
|
+
SourcePattern(".cursorrules", "rules_md", ("cursor",)),
|
|
94
|
+
SourcePattern("**/.cursor/rules/**/*.mdc", "rules_md", ("cursor",)),
|
|
95
|
+
SourcePattern(".github/copilot-instructions.md", "rules_md", ("copilot",)),
|
|
96
|
+
SourcePattern(".github/instructions/**/*.instructions.md", "rules_md", ("copilot",)),
|
|
97
|
+
SourcePattern(".github/prompts/**/*.prompt.md", "rules_md", ("vscode",)),
|
|
98
|
+
SourcePattern(".github/agents/**/*.md", "rules_md", ("copilot",)),
|
|
99
|
+
*_script_rows(),
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _compile(pattern: str) -> re.Pattern[str]:
|
|
104
|
+
anchored = pattern if pattern.startswith("**/") else f"/{pattern}"
|
|
105
|
+
regex = GitIgnoreBasicPattern(anchored).regex
|
|
106
|
+
if regex is None:
|
|
107
|
+
raise ValueError(f"registry pattern {pattern!r} matches nothing")
|
|
108
|
+
return regex
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
_COMPILED = tuple((row, _compile(row.pattern)) for row in REGISTRY)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def match_source(path: str) -> SourcePattern | None:
|
|
115
|
+
# fullmatch, because a gitignore pattern also matches every path under a
|
|
116
|
+
# directory of the same name, and only the file itself is a source.
|
|
117
|
+
for row, regex in _COMPILED:
|
|
118
|
+
if regex.fullmatch(path):
|
|
119
|
+
return row
|
|
120
|
+
return None
|
agentbom/report.py
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import re
|
|
3
|
+
import unicodedata
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
from pydantic import JsonValue
|
|
7
|
+
from rich.console import Console
|
|
8
|
+
from rich.table import Table
|
|
9
|
+
from rich.text import Text
|
|
10
|
+
|
|
11
|
+
from agentbom.lockfile import LOCKFILE_NAME
|
|
12
|
+
from agentbom.models import (
|
|
13
|
+
Artifact,
|
|
14
|
+
Drift,
|
|
15
|
+
FieldChange,
|
|
16
|
+
Finding,
|
|
17
|
+
Hook,
|
|
18
|
+
McpServer,
|
|
19
|
+
RemoteLaunch,
|
|
20
|
+
ScanResult,
|
|
21
|
+
Script,
|
|
22
|
+
Settings,
|
|
23
|
+
Severity,
|
|
24
|
+
StdioLaunch,
|
|
25
|
+
)
|
|
26
|
+
from agentbom.policy import POLICY_FILENAME
|
|
27
|
+
|
|
28
|
+
SCHEMA_VERSION = 4
|
|
29
|
+
_SEVERITY_LABELS: dict[Severity, str] = {"high": "HIGH", "medium": "MED", "low": "LOW"}
|
|
30
|
+
_INVISIBLE_CATEGORIES = frozenset({"Cc", "Cf", "Co", "Cs", "Zl", "Zp"})
|
|
31
|
+
_BACKTICK_RUNS = re.compile("`+")
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def render_json(result: ScanResult) -> str:
|
|
35
|
+
document = {
|
|
36
|
+
"schema_version": SCHEMA_VERSION,
|
|
37
|
+
"artifacts": [_artifact_document(artifact) for artifact in result.artifacts],
|
|
38
|
+
"drift": [item.model_dump(mode="json") for item in result.drift],
|
|
39
|
+
"policy_notes": list(result.policy_notes),
|
|
40
|
+
"suppressed": [item.model_dump(mode="json") for item in result.suppressed],
|
|
41
|
+
"errors": [error.model_dump(mode="json") for error in result.errors],
|
|
42
|
+
"findings": [finding.model_dump(mode="json") for finding in result.findings],
|
|
43
|
+
}
|
|
44
|
+
return json.dumps(document, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _artifact_document(artifact: Artifact) -> dict[str, Any]:
|
|
48
|
+
# Secrets live in env and header values, so only their keys leave the scanner.
|
|
49
|
+
match artifact:
|
|
50
|
+
case McpServer(launch=StdioLaunch() as launch):
|
|
51
|
+
document = artifact.model_dump(mode="json", exclude={"launch": {"env"}})
|
|
52
|
+
document["launch"]["env_keys"] = sorted(launch.env)
|
|
53
|
+
case McpServer(launch=RemoteLaunch() as launch):
|
|
54
|
+
document = artifact.model_dump(mode="json", exclude={"launch": {"headers"}})
|
|
55
|
+
document["launch"]["header_keys"] = sorted(launch.headers)
|
|
56
|
+
case Settings(env=env):
|
|
57
|
+
document = artifact.model_dump(mode="json", exclude={"env"})
|
|
58
|
+
document["env_keys"] = sorted(env)
|
|
59
|
+
case Hook():
|
|
60
|
+
document = artifact.model_dump(mode="json")
|
|
61
|
+
case _:
|
|
62
|
+
document = artifact.model_dump(mode="json", exclude={"body"})
|
|
63
|
+
document["id"] = artifact.id
|
|
64
|
+
document["content_hash"] = artifact.content_hash
|
|
65
|
+
return document
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def summary_line(result: ScanResult) -> str:
|
|
69
|
+
counts = dict.fromkeys(("mcp_server", "skill", "hook", "rules", "script", "settings"), 0)
|
|
70
|
+
for artifact in result.artifacts:
|
|
71
|
+
counts[artifact.kind] += 1
|
|
72
|
+
return "Found: " + ", ".join(
|
|
73
|
+
[
|
|
74
|
+
_count(counts["mcp_server"], "MCP server"),
|
|
75
|
+
_count(counts["skill"], "skill"),
|
|
76
|
+
_count(counts["hook"], "hook"),
|
|
77
|
+
_count(counts["rules"], "rules file"),
|
|
78
|
+
_count(counts["script"], "script"),
|
|
79
|
+
_count(counts["settings"], "settings file"),
|
|
80
|
+
]
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def print_terminal(result: ScanResult, out: Console, err: Console, *, drift: bool) -> None:
|
|
85
|
+
out.print(Text(summary_line(result)), soft_wrap=True)
|
|
86
|
+
if result.artifacts:
|
|
87
|
+
table = Table()
|
|
88
|
+
for header in ("Kind", "Name", "Path", "Agents", "Detail"):
|
|
89
|
+
table.add_column(header, overflow="fold")
|
|
90
|
+
for artifact in result.artifacts:
|
|
91
|
+
table.add_row(
|
|
92
|
+
*(
|
|
93
|
+
Text(_visible(cell))
|
|
94
|
+
for cell in (
|
|
95
|
+
artifact.kind,
|
|
96
|
+
artifact.name,
|
|
97
|
+
artifact.source.path,
|
|
98
|
+
", ".join(artifact.agents),
|
|
99
|
+
_detail(artifact),
|
|
100
|
+
)
|
|
101
|
+
)
|
|
102
|
+
)
|
|
103
|
+
out.print(table)
|
|
104
|
+
for line in body_lines(result, drift=drift):
|
|
105
|
+
out.print(Text(_visible(line)), soft_wrap=True)
|
|
106
|
+
print_errors(result, err)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def body_lines(result: ScanResult, *, drift: bool) -> list[str]:
|
|
110
|
+
"""What the terminal and Markdown reports say after the inventory."""
|
|
111
|
+
lines = [finding_line(finding) for finding in result.findings]
|
|
112
|
+
lines.append(findings_total(result))
|
|
113
|
+
if result.suppressed:
|
|
114
|
+
count = len(result.suppressed)
|
|
115
|
+
noun = "finding" if count == 1 else "findings"
|
|
116
|
+
lines.append(f"{count} {noun} suppressed by {POLICY_FILENAME}.")
|
|
117
|
+
lines.extend(f"policy: {note}" for note in result.policy_notes)
|
|
118
|
+
if drift:
|
|
119
|
+
lines.extend(drift_lines(result.drift))
|
|
120
|
+
return lines
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def render_markdown(result: ScanResult, *, command: str, drift: bool) -> str:
|
|
124
|
+
"""A heading and one code block, so nothing from the repository renders as Markdown."""
|
|
125
|
+
lines = [summary_line(result), *body_lines(result, drift=drift)]
|
|
126
|
+
lines += [f"error: {error.path}: {error.message}" for error in result.errors]
|
|
127
|
+
text = "\n".join(_visible(line) for line in lines)
|
|
128
|
+
longest = max((len(run) for run in _BACKTICK_RUNS.findall(text)), default=0)
|
|
129
|
+
fence = "`" * max(3, longest + 1)
|
|
130
|
+
return f"### agentbom {command}: {_status(result)}\n\n{fence}text\n{text}\n{fence}\n"
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _status(result: ScanResult) -> str:
|
|
134
|
+
if result.errors:
|
|
135
|
+
return f"{len(result.errors)} error(s), so the result cannot be trusted"
|
|
136
|
+
return findings_total(result).removesuffix(".")
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def print_errors(result: ScanResult, err: Console) -> None:
|
|
140
|
+
if result.errors:
|
|
141
|
+
err.print(Text(f"{len(result.errors)} error(s):"))
|
|
142
|
+
for error in result.errors:
|
|
143
|
+
err.print(Text(_visible(f"{error.path}: {error.message}")))
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def drift_lines(drift: tuple[Drift, ...]) -> list[str]:
|
|
147
|
+
"""The readable diff between the lockfile and the repository, ending in a total."""
|
|
148
|
+
lines: list[str] = []
|
|
149
|
+
for item in drift:
|
|
150
|
+
lines.append(f"{item.change.upper():<8} {item.artifact_id}")
|
|
151
|
+
for change in item.fields:
|
|
152
|
+
lines.extend(_field_lines(change))
|
|
153
|
+
if not drift:
|
|
154
|
+
return [*lines, f"No drift from {LOCKFILE_NAME}."]
|
|
155
|
+
noun = "difference" if len(drift) == 1 else "differences"
|
|
156
|
+
return [*lines, f"{len(drift)} {noun} from {LOCKFILE_NAME}."]
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def _field_lines(change: FieldChange) -> list[str]:
|
|
160
|
+
if change.hidden:
|
|
161
|
+
note = "only a digest is locked; review the file's diff"
|
|
162
|
+
return [f" {change.field}: {change.change} ({note})"]
|
|
163
|
+
lines = [f" {change.field}:"]
|
|
164
|
+
if change.change != "added":
|
|
165
|
+
lines.extend(_value_lines("-", change.before))
|
|
166
|
+
if change.change != "removed":
|
|
167
|
+
lines.extend(_value_lines("+", change.after))
|
|
168
|
+
return lines
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _value_lines(mark: str, value: JsonValue) -> list[str]:
|
|
172
|
+
# A string prints raw unless it reads as JSON, so "false" and false never look alike.
|
|
173
|
+
if isinstance(value, str) and not _reads_as_json(value):
|
|
174
|
+
text = value
|
|
175
|
+
else:
|
|
176
|
+
text = json.dumps(value, ensure_ascii=False)
|
|
177
|
+
return [f" {mark} {line}" for line in text.split("\n")]
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _reads_as_json(text: str) -> bool:
|
|
181
|
+
try:
|
|
182
|
+
json.loads(text)
|
|
183
|
+
except (ValueError, RecursionError):
|
|
184
|
+
return False
|
|
185
|
+
return True
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def finding_line(finding: Finding) -> str:
|
|
189
|
+
where = finding.location.path
|
|
190
|
+
if finding.location.line is not None:
|
|
191
|
+
where = f"{where}:{finding.location.line}"
|
|
192
|
+
return f"{_SEVERITY_LABELS[finding.severity]:<4} {finding.rule_id} {where} {finding.message}"
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
def findings_total(result: ScanResult) -> str:
|
|
196
|
+
if not result.findings:
|
|
197
|
+
return "No findings."
|
|
198
|
+
counts = dict.fromkeys(_SEVERITY_LABELS, 0)
|
|
199
|
+
for finding in result.findings:
|
|
200
|
+
counts[finding.severity] += 1
|
|
201
|
+
noun = "finding" if len(result.findings) == 1 else "findings"
|
|
202
|
+
return (
|
|
203
|
+
f"{len(result.findings)} {noun} "
|
|
204
|
+
f"({counts['high']} high, {counts['medium']} medium, {counts['low']} low)."
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def _detail(artifact: Artifact) -> str:
|
|
209
|
+
match artifact:
|
|
210
|
+
case McpServer(launch=StdioLaunch(command=command)):
|
|
211
|
+
return command
|
|
212
|
+
case McpServer(launch=RemoteLaunch(url=url)):
|
|
213
|
+
return url
|
|
214
|
+
case Hook(commands=commands, url=url, handler_type=handler_type):
|
|
215
|
+
return next(iter(commands.values()), url or handler_type)
|
|
216
|
+
case Script(language=language):
|
|
217
|
+
return language
|
|
218
|
+
case _:
|
|
219
|
+
return ""
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def _count(n: int, noun: str) -> str:
|
|
223
|
+
return f"{n} {noun}" if n == 1 else f"{n} {noun}s"
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _visible(text: str) -> str:
|
|
227
|
+
# Repo files are untrusted: escape control and format characters (ANSI
|
|
228
|
+
# escapes, bidi overrides, zero-width text) instead of sending them to a terminal.
|
|
229
|
+
return "".join(
|
|
230
|
+
_escape(char) if unicodedata.category(char) in _INVISIBLE_CATEGORIES else char
|
|
231
|
+
for char in text
|
|
232
|
+
)
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def _escape(char: str) -> str:
|
|
236
|
+
code = ord(char)
|
|
237
|
+
return f"\\u{code:04x}" if code <= 0xFFFF else f"\\U{code:08x}"
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
from collections.abc import Iterable, Sequence
|
|
2
|
+
from typing import Protocol
|
|
3
|
+
|
|
4
|
+
from agentbom.models import SEVERITY_RANK, Artifact, Drift, Finding, RuleId
|
|
5
|
+
from agentbom.rules.abom_001_hidden_unicode import HiddenUnicode
|
|
6
|
+
from agentbom.rules.abom_002_remote_exec import RemoteScriptExecution
|
|
7
|
+
from agentbom.rules.abom_003_credential_paths import CredentialPathAccess
|
|
8
|
+
from agentbom.rules.abom_004_outbound_transfer import OutboundDataTransfer
|
|
9
|
+
from agentbom.rules.abom_005_unpinned import UnpinnedServer
|
|
10
|
+
from agentbom.rules.abom_006_drift import drift_findings
|
|
11
|
+
from agentbom.rules.abom_007_permissions import OverBroadPermissions
|
|
12
|
+
from agentbom.rules.abom_008_auto_run_hooks import AutoRunHooks
|
|
13
|
+
from agentbom.rules.abom_009_instruction_override import InstructionOverride
|
|
14
|
+
from agentbom.rules.abom_010_secrets import EmbeddedSecrets
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class Rule(Protocol):
|
|
18
|
+
@property
|
|
19
|
+
def rule_id(self) -> RuleId: ...
|
|
20
|
+
|
|
21
|
+
def run(self, artifacts: Sequence[Artifact]) -> Iterable[Finding]: ...
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
RULES: tuple[Rule, ...] = (
|
|
25
|
+
HiddenUnicode(),
|
|
26
|
+
RemoteScriptExecution(),
|
|
27
|
+
CredentialPathAccess(),
|
|
28
|
+
OutboundDataTransfer(),
|
|
29
|
+
UnpinnedServer(),
|
|
30
|
+
OverBroadPermissions(),
|
|
31
|
+
AutoRunHooks(),
|
|
32
|
+
InstructionOverride(),
|
|
33
|
+
EmbeddedSecrets(),
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def run_rules(artifacts: Sequence[Artifact], drift: Sequence[Drift] = ()) -> tuple[Finding, ...]:
|
|
38
|
+
findings = [finding for rule in RULES for finding in rule.run(artifacts)]
|
|
39
|
+
findings.extend(drift_findings(drift))
|
|
40
|
+
return tuple(sorted(findings, key=_finding_key))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _finding_key(finding: Finding) -> tuple[int, str, str, int, str, str]:
|
|
44
|
+
return (
|
|
45
|
+
-SEVERITY_RANK[finding.severity],
|
|
46
|
+
finding.rule_id,
|
|
47
|
+
finding.location.path,
|
|
48
|
+
finding.location.line or 0,
|
|
49
|
+
finding.message,
|
|
50
|
+
finding.artifact_id,
|
|
51
|
+
)
|
agentbom/rules/_prose.py
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"""Sentences and negation, for rules that judge instructions written in prose."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
from collections.abc import Iterator
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from agentbom.rules._surfaces import Surface
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass(frozen=True)
|
|
11
|
+
class Sentence:
|
|
12
|
+
start: int
|
|
13
|
+
text: str
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
_FENCE = re.compile(r"[ \t]*(?:```|~~~)")
|
|
17
|
+
# A Markdown list item, heading or quote starts a new block; any other line
|
|
18
|
+
# continues the paragraph above it, so a soft-wrapped sentence stays whole.
|
|
19
|
+
_BLOCK_START = re.compile(r"[ \t]*(?:[-*+][ \t]|\d+[.)][ \t]|#|>)")
|
|
20
|
+
_NUMBERED_ITEM = re.compile(r"[ \t]*\d+[.)][ \t]")
|
|
21
|
+
_HEADING = re.compile(r"[ \t]*#")
|
|
22
|
+
_TABLE_ROW = re.compile(r"[ \t]*\|")
|
|
23
|
+
_CELL_BORDER = re.compile(r"(?<!\\)\|")
|
|
24
|
+
_SENTENCE_END = re.compile(r"(?<=[.!?])(?<!\be\.g\.)(?<!\bi\.e\.)(?<!\betc\.)\s+")
|
|
25
|
+
_NEGATION = re.compile(
|
|
26
|
+
r"\b(?:"
|
|
27
|
+
r"(?:never|do\s+not|don['\u2019]t)(?!\s+(?:forget|hesitate|fail)\b)"
|
|
28
|
+
r"|must\s+not|mustn['\u2019]t|should\s+not|shouldn['\u2019]t"
|
|
29
|
+
r"|avoid(?:s|ing)?|refus(?:e|es|ing)|den(?:y|ies|ied)"
|
|
30
|
+
r"|not\s+allowed|prohibited|forbidden"
|
|
31
|
+
r"|without(?!\s+(?:asking|telling|notifying|informing|alerting|mentioning|showing"
|
|
32
|
+
r"|confirming|prompting|letting)\b)"
|
|
33
|
+
r")\b",
|
|
34
|
+
re.IGNORECASE,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def sentences(text: str) -> Iterator[Sentence]:
|
|
39
|
+
"""Sentences of Markdown prose, each with its offset in `text`.
|
|
40
|
+
|
|
41
|
+
Paragraphs split on `.`, `!` or `?` before whitespace; list items, headings,
|
|
42
|
+
table cells and lines of a code block are sentences of their own.
|
|
43
|
+
"""
|
|
44
|
+
for start, end in _blocks(text):
|
|
45
|
+
block = text[start:end]
|
|
46
|
+
cursor = 0
|
|
47
|
+
marker = _NUMBERED_ITEM.match(block)
|
|
48
|
+
for boundary in _SENTENCE_END.finditer(block, marker.end() if marker else 0):
|
|
49
|
+
yield from _trimmed(text, start + cursor, start + boundary.start())
|
|
50
|
+
cursor = boundary.end()
|
|
51
|
+
yield from _trimmed(text, start + cursor, end)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def negated(sentence: str) -> bool:
|
|
55
|
+
return _NEGATION.search(sentence) is not None
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def regions(surface: Surface) -> Iterator[Sentence]:
|
|
59
|
+
"""The parts of a surface a rule searches: all of a command or value, or each
|
|
60
|
+
prose sentence that does not negate what it says."""
|
|
61
|
+
if surface.context in ("skill_prose", "rules_prose"):
|
|
62
|
+
yield from (s for s in sentences(surface.text) if not negated(s.text))
|
|
63
|
+
else:
|
|
64
|
+
yield Sentence(0, surface.text)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _blocks(text: str) -> Iterator[tuple[int, int]]:
|
|
68
|
+
open_start: int | None = None
|
|
69
|
+
open_end = 0
|
|
70
|
+
in_fence = False
|
|
71
|
+
offset = 0
|
|
72
|
+
for line in text.splitlines(keepends=True):
|
|
73
|
+
start, offset = offset, offset + len(line)
|
|
74
|
+
end = start + len(line.rstrip("\r\n"))
|
|
75
|
+
fence = _FENCE.match(line) is not None
|
|
76
|
+
standalone = fence or in_fence or not line.strip() or _TABLE_ROW.match(line)
|
|
77
|
+
if open_start is not None and (standalone or _BLOCK_START.match(line)):
|
|
78
|
+
yield open_start, open_end
|
|
79
|
+
open_start = None
|
|
80
|
+
if fence:
|
|
81
|
+
in_fence = not in_fence
|
|
82
|
+
elif in_fence:
|
|
83
|
+
yield start, end
|
|
84
|
+
elif _TABLE_ROW.match(line):
|
|
85
|
+
yield from _cells(line, start, end)
|
|
86
|
+
elif line.strip():
|
|
87
|
+
if open_start is None:
|
|
88
|
+
open_start = start
|
|
89
|
+
open_end = end
|
|
90
|
+
if _HEADING.match(line):
|
|
91
|
+
yield open_start, open_end
|
|
92
|
+
open_start = None
|
|
93
|
+
if open_start is not None:
|
|
94
|
+
yield open_start, open_end
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _cells(line: str, start: int, end: int) -> Iterator[tuple[int, int]]:
|
|
98
|
+
cursor = start
|
|
99
|
+
for border in _CELL_BORDER.finditer(line, 0, end - start):
|
|
100
|
+
yield cursor, start + border.start()
|
|
101
|
+
cursor = start + border.end()
|
|
102
|
+
yield cursor, end
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def _trimmed(text: str, start: int, end: int) -> Iterator[Sentence]:
|
|
106
|
+
chunk = text[start:end]
|
|
107
|
+
stripped = chunk.strip()
|
|
108
|
+
if stripped:
|
|
109
|
+
yield Sentence(start + len(chunk) - len(chunk.lstrip()), stripped)
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""The text each artifact exposes to text rules, and the context that text runs in."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Iterator, Mapping
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from typing import Literal, assert_never
|
|
6
|
+
|
|
7
|
+
from agentbom.models import (
|
|
8
|
+
Artifact,
|
|
9
|
+
Hook,
|
|
10
|
+
McpServer,
|
|
11
|
+
RemoteLaunch,
|
|
12
|
+
Rules,
|
|
13
|
+
Script,
|
|
14
|
+
Settings,
|
|
15
|
+
Severity,
|
|
16
|
+
Skill,
|
|
17
|
+
StdioLaunch,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
# executable: runs as a command or program. config: a value an agent passes to a
|
|
21
|
+
# server or process. skill_prose / rules_prose: instructions an agent reads.
|
|
22
|
+
Context = Literal["executable", "config", "skill_prose", "rules_prose"]
|
|
23
|
+
|
|
24
|
+
# A rule rates each context it applies to; a context missing from its table is skipped.
|
|
25
|
+
SeverityTable = Mapping[Context, Severity]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class Surface:
|
|
30
|
+
artifact: Artifact
|
|
31
|
+
context: Context
|
|
32
|
+
field: str
|
|
33
|
+
text: str
|
|
34
|
+
line: int | None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def surfaces(artifact: Artifact) -> Iterator[Surface]:
|
|
38
|
+
match artifact:
|
|
39
|
+
case McpServer():
|
|
40
|
+
yield from _server_surfaces(artifact)
|
|
41
|
+
case Hook():
|
|
42
|
+
for shell, command in artifact.commands.items():
|
|
43
|
+
yield Surface(artifact, "executable", f"commands.{shell}", command, None)
|
|
44
|
+
if artifact.url is not None:
|
|
45
|
+
yield Surface(artifact, "config", "url", artifact.url, None)
|
|
46
|
+
case Script():
|
|
47
|
+
yield Surface(artifact, "executable", "body", artifact.body, 1)
|
|
48
|
+
case Skill():
|
|
49
|
+
if artifact.description is not None:
|
|
50
|
+
yield Surface(artifact, "skill_prose", "description", artifact.description, None)
|
|
51
|
+
yield Surface(artifact, "skill_prose", "body", artifact.body, artifact.body_line)
|
|
52
|
+
case Rules():
|
|
53
|
+
yield Surface(artifact, "rules_prose", "body", artifact.body, artifact.body_line)
|
|
54
|
+
case Settings():
|
|
55
|
+
for key, value in artifact.env.items():
|
|
56
|
+
yield Surface(artifact, "config", f"env.{key}", value, None)
|
|
57
|
+
case _:
|
|
58
|
+
assert_never(artifact)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _server_surfaces(server: McpServer) -> Iterator[Surface]:
|
|
62
|
+
launch = server.launch
|
|
63
|
+
match launch:
|
|
64
|
+
case StdioLaunch():
|
|
65
|
+
command = " ".join((launch.command, *launch.args))
|
|
66
|
+
yield Surface(server, "executable", "command", command, None)
|
|
67
|
+
for key, value in launch.env.items():
|
|
68
|
+
yield Surface(server, "config", f"env.{key}", value, None)
|
|
69
|
+
case RemoteLaunch():
|
|
70
|
+
yield Surface(server, "config", "url", launch.url, None)
|
|
71
|
+
for key, value in launch.headers.items():
|
|
72
|
+
yield Surface(server, "config", f"headers.{key}", value, None)
|
|
73
|
+
case _:
|
|
74
|
+
assert_never(launch)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def field_label(surface: Surface) -> str:
|
|
78
|
+
"""The surface's field, prefixed with its artifact's name when one file holds several."""
|
|
79
|
+
match surface.artifact:
|
|
80
|
+
case McpServer():
|
|
81
|
+
return f'server "{surface.artifact.name}" {surface.field}'
|
|
82
|
+
case Hook():
|
|
83
|
+
return f"hook {surface.artifact.name} {surface.field}"
|
|
84
|
+
case _:
|
|
85
|
+
return surface.field
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def line_of(surface: Surface, offset: int) -> int | None:
|
|
89
|
+
"""The file line of the character at `offset` in `surface.text`, when the surface has one."""
|
|
90
|
+
if surface.line is None:
|
|
91
|
+
return None
|
|
92
|
+
return surface.line + surface.text.count("\n", 0, offset)
|