brunnr 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.

Potentially problematic release.


This version of brunnr might be problematic. Click here for more details.

brunnr/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """brunnr — Security scanner and skill registry for agent tool descriptions."""
2
+
3
+ __version__ = "0.1.0"
brunnr/cli.py ADDED
@@ -0,0 +1,75 @@
1
+ """brunnr CLI — subcommand dispatcher."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+
8
+ from brunnr import __version__
9
+
10
+
11
+ def main() -> int:
12
+ parser = argparse.ArgumentParser(
13
+ prog="brunnr",
14
+ description="Security scanner and skill registry for agent tool descriptions.",
15
+ )
16
+ parser.add_argument("--version", action="version", version=f"brunnr {__version__}")
17
+ sub = parser.add_subparsers(dest="command")
18
+
19
+ # --- brunnr scan ---
20
+ scan_p = sub.add_parser("scan", help="Scan SKILL.md files for security threats")
21
+ scan_p.add_argument("paths", nargs="*", default=None, help="Files or directories to scan (default: skills/)")
22
+ scan_p.add_argument("-v", "--verbose", action="store_true", help="Show finding details")
23
+ scan_p.add_argument("--json", action="store_true", dest="json_out", help="JSON output")
24
+ scan_p.add_argument("--strict", action="store_true", help="Fail on FLAG (not just BLOCK)")
25
+ scan_p.add_argument("--no-color", action="store_true", help="Disable color output")
26
+
27
+ # --- brunnr install ---
28
+ inst_p = sub.add_parser("install", help="Install a skill from the registry")
29
+ inst_p.add_argument("skill", nargs="?", help="Skill slug to install (e.g., ax-rubric)")
30
+ inst_p.add_argument("--registry", default="https://github.com/Peleke/brunnr", help="Skill registry URL")
31
+ inst_p.add_argument("--with-tests", action="store_true", help="Also fetch test fixtures")
32
+ inst_p.add_argument("--force", action="store_true", help="Overwrite existing skill")
33
+ inst_p.add_argument("--list", action="store_true", dest="list_skills", help="List available skills")
34
+ inst_p.add_argument("-y", "--yes", action="store_true", help="Skip review prompt, install immediately")
35
+
36
+ # --- brunnr eval ---
37
+ eval_p = sub.add_parser("eval", help="Run eval harness for a skill")
38
+ eval_p.add_argument("skill", help="Skill slug to evaluate")
39
+ eval_p.add_argument("--model", default="claude-sonnet-4-20250514", help="Claude model to use")
40
+ eval_p.add_argument("-o", "--output", help="Path to write JSON results")
41
+ eval_p.add_argument("--dry-run", action="store_true", help="Validate fixtures without API calls")
42
+
43
+ # --- brunnr pipeline ---
44
+ pipe_p = sub.add_parser("pipeline", help="Run the full scan + eval pipeline")
45
+ pipe_p.add_argument("--scan-only", action="store_true", help="Security scan only, skip evals")
46
+ pipe_p.add_argument("--verbose", action="store_true")
47
+
48
+ args = parser.parse_args()
49
+
50
+ if not args.command:
51
+ parser.print_help()
52
+ return 0
53
+
54
+ if args.command == "scan":
55
+ from brunnr.commands.scan import run
56
+ return run(args)
57
+ elif args.command == "install":
58
+ from brunnr.commands.install import run
59
+ return run(args)
60
+ elif args.command == "eval":
61
+ from brunnr.commands.eval import run
62
+ return run(args)
63
+ elif args.command == "pipeline":
64
+ from brunnr.commands.pipeline import run
65
+ return run(args)
66
+
67
+ return 0
68
+
69
+
70
+ def cli():
71
+ sys.exit(main())
72
+
73
+
74
+ if __name__ == "__main__":
75
+ cli()
File without changes
@@ -0,0 +1,211 @@
1
+ """brunnr eval — run the skill evaluation harness."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ import sys
8
+ import time
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ def _skills_dir() -> Path:
13
+ return Path.cwd() / "skills"
14
+
15
+
16
+ def _tests_dir() -> Path:
17
+ return Path.cwd() / "tests"
18
+
19
+
20
+ def _parse_frontmatter(text: str) -> dict[str, str]:
21
+ if not text.startswith("---"):
22
+ return {}
23
+ parts = text.split("---", 2)
24
+ if len(parts) < 3:
25
+ return {}
26
+ fm = {}
27
+ for line in parts[1].strip().splitlines():
28
+ if ":" in line:
29
+ key, val = line.split(":", 1)
30
+ fm[key.strip()] = val.strip().strip('"').strip("'")
31
+ return fm
32
+
33
+
34
+ def _load_skill_prompt(slug: str) -> str:
35
+ path = _skills_dir() / slug / "SKILL.md"
36
+ if not path.exists():
37
+ raise FileNotFoundError(f"Skill not found: {path}")
38
+ return path.read_text()
39
+
40
+
41
+ def _load_test_spec(slug: str) -> dict[str, Any]:
42
+ path = _tests_dir() / slug / "test-spec.json"
43
+ if not path.exists():
44
+ raise FileNotFoundError(f"Test spec not found: {path}")
45
+ return json.loads(path.read_text())
46
+
47
+
48
+ def _load_fixtures(slug: str) -> list[dict[str, Any]]:
49
+ spec = _load_test_spec(slug)
50
+ cases = []
51
+ for case in spec.get("cases", []):
52
+ fixture_path = _tests_dir() / slug / case.get("fixture", "")
53
+ if fixture_path.exists():
54
+ case["_fixture_data"] = json.loads(fixture_path.read_text())
55
+ cases.append(case)
56
+ return cases
57
+
58
+
59
+ def _call_claude(system_prompt: str, user_message: str, model: str) -> str:
60
+ try:
61
+ from anthropic import Anthropic
62
+ except ImportError:
63
+ print("ERROR: anthropic package not installed. Run: pip install brunnr[eval]", file=sys.stderr)
64
+ sys.exit(1)
65
+
66
+ client = Anthropic()
67
+ response = client.messages.create(
68
+ model=model,
69
+ max_tokens=4096,
70
+ system=system_prompt,
71
+ messages=[{"role": "user", "content": user_message}],
72
+ )
73
+ return response.content[0].text
74
+
75
+
76
+ def _extract_score(text: str) -> int | None:
77
+ match = re.search(r"[Ss]core:\s*\**\s*(\d)\s*/\s*5", text)
78
+ return int(match.group(1)) if match else None
79
+
80
+
81
+ def _extract_criteria(text: str) -> dict[str, str]:
82
+ results = {}
83
+ for match in re.finditer(r"\|\s*([\w\s]+?)\s*\|\s*(pass|fail)\s*\|", text, re.IGNORECASE):
84
+ results[match.group(1).strip().lower()] = match.group(2).strip().lower()
85
+ return results
86
+
87
+
88
+ def _run_assertion(assertion: dict, output: str) -> dict:
89
+ atype = assertion["type"]
90
+ expected = assertion["expected"]
91
+ result = {"assertion": assertion, "passed": False, "detail": ""}
92
+
93
+ if atype == "score_range":
94
+ score = _extract_score(output)
95
+ if score is None:
96
+ result["detail"] = "Could not extract score"
97
+ elif expected["min"] <= score <= expected["max"]:
98
+ result["passed"] = True
99
+ result["detail"] = f"Score {score} in [{expected['min']}, {expected['max']}]"
100
+ else:
101
+ result["detail"] = f"Score {score} NOT in [{expected['min']}, {expected['max']}]"
102
+
103
+ elif atype == "has_table":
104
+ has = bool(re.search(r"\|.*\|.*\|.*\|", output))
105
+ result["passed"] = has == expected
106
+ result["detail"] = f"Table {'found' if has else 'missing'}"
107
+
108
+ elif atype == "has_rewrite":
109
+ has = bool(re.search(r"[Rr]ewr(itten|ite)", output))
110
+ result["passed"] = has == expected
111
+ result["detail"] = f"Rewrite {'found' if has else 'missing'}"
112
+
113
+ elif atype == "contains":
114
+ found = expected.lower() in output.lower()
115
+ result["passed"] = found
116
+ result["detail"] = f"{'Contains' if found else 'Missing'} '{expected}'"
117
+
118
+ elif atype == "format_valid":
119
+ has_header = bool(re.search(r"^###?\s+", output, re.MULTILINE))
120
+ has_score = _extract_score(output) is not None
121
+ has_table = bool(re.search(r"\|.*[Cc]riterion.*\|", output))
122
+ result["passed"] = all([has_header, has_score, has_table])
123
+ result["detail"] = f"header={has_header} score={has_score} table={has_table}"
124
+
125
+ elif atype in ("criteria_pass", "criteria_fail"):
126
+ criteria = _extract_criteria(output)
127
+ target = "pass" if atype == "criteria_pass" else "fail"
128
+ missing = []
129
+ for crit in expected:
130
+ matched = any(crit.lower() in k and v == target for k, v in criteria.items())
131
+ if not matched:
132
+ missing.append(crit)
133
+ result["passed"] = len(missing) == 0
134
+ result["detail"] = f"{'All match' if not missing else 'Missing: ' + ', '.join(missing)}"
135
+
136
+ return result
137
+
138
+
139
+ def run(args) -> int:
140
+ slug = args.skill
141
+ model = args.model
142
+ dry_run = args.dry_run
143
+
144
+ print(f"=== brunnr eval: {slug} ===")
145
+
146
+ try:
147
+ prompt = _load_skill_prompt(slug)
148
+ cases = _load_fixtures(slug)
149
+ except FileNotFoundError as e:
150
+ print(f"ERROR: {e}", file=sys.stderr)
151
+ return 1
152
+
153
+ print(f" {len(cases)} test cases, model: {model}")
154
+
155
+ results = []
156
+ for case in cases:
157
+ case_id = case["id"]
158
+ desc = case.get("description", "")
159
+ input_text = case.get("input", "")
160
+
161
+ if "_fixture_data" in case:
162
+ fx = case["_fixture_data"]
163
+ input_text = fx.get("input", fx.get("description", input_text))
164
+
165
+ print(f"\n [{case_id}] {desc}")
166
+
167
+ if dry_run:
168
+ print(" DRY RUN — skipped")
169
+ results.append({"case_id": case_id, "skipped": True, "assertions": []})
170
+ continue
171
+
172
+ start = time.time()
173
+ try:
174
+ output = _call_claude(prompt, input_text, model)
175
+ except Exception as e:
176
+ results.append({"case_id": case_id, "error": str(e), "assertions": []})
177
+ continue
178
+
179
+ duration = time.time() - start
180
+ assertion_results = []
181
+ for assertion in case.get("assertions", []):
182
+ r = _run_assertion(assertion, output)
183
+ status = "PASS" if r["passed"] else "FAIL"
184
+ print(f" {status}: [{assertion['type']}] {r['detail']}")
185
+ assertion_results.append(r)
186
+
187
+ results.append({
188
+ "case_id": case_id,
189
+ "output": output[:2000],
190
+ "assertions": assertion_results,
191
+ "duration_s": duration,
192
+ "all_passed": all(r["passed"] for r in assertion_results),
193
+ })
194
+
195
+ passed = sum(1 for r in results if r.get("all_passed", False))
196
+ skipped = sum(1 for r in results if r.get("skipped", False))
197
+ total = len(results) - skipped
198
+ failed = total - passed
199
+
200
+ print(f"\n=== {passed}/{total} passed", end="")
201
+ if skipped:
202
+ print(f" ({skipped} skipped)", end="")
203
+ print(" ===")
204
+
205
+ if args.output:
206
+ report = {"skill": slug, "model": model, "summary": {"pass": passed, "fail": failed, "skipped": skipped}, "cases": results}
207
+ Path(args.output).parent.mkdir(parents=True, exist_ok=True)
208
+ Path(args.output).write_text(json.dumps(report, indent=2, default=str))
209
+ print(f"Results: {args.output}")
210
+
211
+ return 1 if failed > 0 else 0
@@ -0,0 +1,152 @@
1
+ """brunnr install — fetch skills from the registry."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sys
7
+ from pathlib import Path
8
+ from urllib.request import urlopen, Request
9
+ from urllib.error import URLError
10
+
11
+ _GITHUB_RAW = "https://raw.githubusercontent.com"
12
+
13
+
14
+ def _fetch(url: str) -> str | None:
15
+ """Fetch a URL and return text content, or None on failure."""
16
+ try:
17
+ req = Request(url, headers={"User-Agent": "brunnr-cli"})
18
+ with urlopen(req, timeout=15) as resp:
19
+ return resp.read().decode("utf-8")
20
+ except (URLError, OSError):
21
+ return None
22
+
23
+
24
+ def _registry_base(registry: str) -> str:
25
+ """Convert a GitHub repo URL to raw content base URL."""
26
+ # https://github.com/Peleke/brunnr -> https://raw.githubusercontent.com/Peleke/brunnr/main
27
+ if "github.com" in registry:
28
+ parts = registry.rstrip("/").replace("https://github.com/", "").split("/")
29
+ if len(parts) >= 2:
30
+ return f"{_GITHUB_RAW}/{parts[0]}/{parts[1]}/main"
31
+ return registry.rstrip("/")
32
+
33
+
34
+ def _list_skills(base: str) -> list[str]:
35
+ """List available skills from registry (via GitHub API)."""
36
+ # Convert raw URL back to API URL
37
+ # https://raw.githubusercontent.com/Peleke/brunnr/main -> https://api.github.com/repos/Peleke/brunnr/contents/skills
38
+ parts = base.replace(f"{_GITHUB_RAW}/", "").split("/")
39
+ if len(parts) >= 3:
40
+ api_url = f"https://api.github.com/repos/{parts[0]}/{parts[1]}/contents/skills"
41
+ content = _fetch(api_url)
42
+ if content:
43
+ entries = json.loads(content)
44
+ return [e["name"] for e in entries if e["type"] == "dir"]
45
+ return []
46
+
47
+
48
+ def run(args) -> int:
49
+ base = _registry_base(args.registry)
50
+
51
+ # List mode
52
+ if getattr(args, "list_skills", False):
53
+ skills = _list_skills(base)
54
+ if not skills:
55
+ print("No skills found (or registry unreachable).", file=sys.stderr)
56
+ return 1
57
+ print("Available skills:")
58
+ for s in skills:
59
+ print(f" - {s}")
60
+ return 0
61
+
62
+ slug = args.skill
63
+ if not slug:
64
+ print("ERROR: skill name required. Use `brunnr install --list` to see available skills.", file=sys.stderr)
65
+ return 1
66
+
67
+ dest = Path("skills") / slug
68
+ skill_file = dest / "SKILL.md"
69
+
70
+ if skill_file.exists() and not getattr(args, "force", False):
71
+ print(f"Skill '{slug}' already installed at {skill_file}", file=sys.stderr)
72
+ print("Use --force to overwrite.", file=sys.stderr)
73
+ return 1
74
+
75
+ # Fetch SKILL.md
76
+ skill_url = f"{base}/skills/{slug}/SKILL.md"
77
+ print(f"Fetching {slug} from {args.registry}...")
78
+ content = _fetch(skill_url)
79
+ if not content:
80
+ print(f"ERROR: Could not fetch {skill_url}", file=sys.stderr)
81
+ return 1
82
+
83
+ # Review before install (unless --yes)
84
+ skip_review = getattr(args, "yes", False) or getattr(args, "force", False)
85
+ if not skip_review and sys.stdin.isatty():
86
+ lines = content.splitlines()
87
+ preview = "\n".join(lines[:30])
88
+ print(f"\n--- {slug}/SKILL.md (first 30 of {len(lines)} lines) ---")
89
+ print(preview)
90
+ if len(lines) > 30:
91
+ print(f" ... ({len(lines) - 30} more lines)")
92
+ print(f"---")
93
+ # Show GitHub link for full review
94
+ repo_parts = base.replace(f"{_GITHUB_RAW}/", "").split("/")
95
+ if len(repo_parts) >= 2:
96
+ print(f"\nFull source: https://github.com/{repo_parts[0]}/{repo_parts[1]}/tree/main/skills/{slug}")
97
+ try:
98
+ answer = input(f"\nInstall {slug} to ./skills/{slug}/? [y/N] ").strip().lower()
99
+ except (EOFError, KeyboardInterrupt):
100
+ print("\nAborted.", file=sys.stderr)
101
+ return 1
102
+ if answer not in ("y", "yes"):
103
+ print("Aborted.", file=sys.stderr)
104
+ return 1
105
+
106
+ dest.mkdir(parents=True, exist_ok=True)
107
+ skill_file.write_text(content)
108
+ print(f" -> {skill_file} ({len(content.splitlines())} lines)")
109
+
110
+ # Fetch schema (optional)
111
+ schema_url = f"{base}/schemas/{slug}/output.schema.json"
112
+ schema_content = _fetch(schema_url)
113
+ if schema_content:
114
+ schema_dest = Path("schemas") / slug
115
+ schema_dest.mkdir(parents=True, exist_ok=True)
116
+ (schema_dest / "output.schema.json").write_text(schema_content)
117
+ print(f" -> schemas/{slug}/output.schema.json")
118
+
119
+ # Fetch test fixtures (optional)
120
+ if getattr(args, "with_tests", False):
121
+ spec_url = f"{base}/tests/{slug}/test-spec.json"
122
+ spec_content = _fetch(spec_url)
123
+ if spec_content:
124
+ test_dest = Path("tests") / slug
125
+ test_dest.mkdir(parents=True, exist_ok=True)
126
+ (test_dest / "test-spec.json").write_text(spec_content)
127
+ print(f" -> tests/{slug}/test-spec.json")
128
+
129
+ # Fetch fixtures referenced in spec
130
+ spec = json.loads(spec_content)
131
+ for case in spec.get("cases", []):
132
+ fixture_rel = case.get("fixture", "")
133
+ if not fixture_rel:
134
+ continue
135
+ # Sanitize: reject path traversal and absolute paths
136
+ if ".." in fixture_rel or fixture_rel.startswith("/"):
137
+ print(f" WARNING: skipping suspicious fixture path: {fixture_rel}", file=sys.stderr)
138
+ continue
139
+ fixture_path = (test_dest / fixture_rel).resolve()
140
+ if not str(fixture_path).startswith(str(test_dest.resolve())):
141
+ print(f" WARNING: fixture escapes test dir: {fixture_rel}", file=sys.stderr)
142
+ continue
143
+ fixture_url = f"{base}/tests/{slug}/{fixture_rel}"
144
+ fixture_content = _fetch(fixture_url)
145
+ if fixture_content:
146
+ fixture_path.parent.mkdir(parents=True, exist_ok=True)
147
+ fixture_path.write_text(fixture_content)
148
+ print(f" -> tests/{slug}/{fixture_rel}")
149
+
150
+ print(f"\nInstalled {slug} to ./{dest}/")
151
+ print(f"\nTip: Run `brunnr eval {slug} --dry-run` to validate locally.")
152
+ return 0
@@ -0,0 +1,91 @@
1
+ """brunnr pipeline — full scan + eval orchestration."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ from brunnr.scanner import Severity, scan_skill_md
9
+ from brunnr.discovery import discover_skill_files
10
+
11
+
12
+ def run(args) -> int:
13
+ verbose = getattr(args, "verbose", False)
14
+ scan_only = getattr(args, "scan_only", False)
15
+
16
+ print("=== brunnr pipeline ===\n")
17
+
18
+ # Step 1: Security scan
19
+ print("Step 1: Security scan...")
20
+ files = discover_skill_files()
21
+
22
+ if not files:
23
+ print("No SKILL.md files found.", file=sys.stderr)
24
+ return 1
25
+
26
+ has_block = False
27
+ has_flag = False
28
+
29
+ for path in files:
30
+ content = path.read_text(encoding="utf-8")
31
+ result = scan_skill_md(content)
32
+
33
+ status = result.severity.value.upper()
34
+ print(f" {status} {path.name}")
35
+
36
+ if verbose and result.findings:
37
+ for f in result.findings:
38
+ print(f" [{f.threat_class}] {f.description}")
39
+
40
+ if result.blocked:
41
+ has_block = True
42
+ if result.flagged:
43
+ has_flag = True
44
+
45
+ if has_block:
46
+ print("\nPipeline FAILED: blocked findings detected.")
47
+ return 1
48
+
49
+ print(f"\nScan passed ({len(files)} files).")
50
+
51
+ if scan_only:
52
+ print("Done (scan-only mode).")
53
+ return 0
54
+
55
+ # Step 2: Discover and run evals
56
+ print("\nStep 2: Skill evaluations...")
57
+ tests_dir = Path.cwd() / "tests"
58
+ skills_dir = Path.cwd() / "skills"
59
+
60
+ eval_slugs = []
61
+ if tests_dir.exists():
62
+ for spec in sorted(tests_dir.rglob("test-spec.json")):
63
+ slug = spec.parent.name
64
+ if (skills_dir / slug / "SKILL.md").exists():
65
+ eval_slugs.append(slug)
66
+
67
+ if not eval_slugs:
68
+ print(" No evaluable skills found.")
69
+ print("\nPipeline complete.")
70
+ return 0
71
+
72
+ from brunnr.commands.eval import run as run_eval
73
+ from argparse import Namespace
74
+
75
+ any_failed = False
76
+ for slug in eval_slugs:
77
+ eval_args = Namespace(
78
+ skill=slug,
79
+ model=getattr(args, "model", "claude-sonnet-4-20250514"),
80
+ output=f"tests/{slug}/results.json",
81
+ dry_run=False,
82
+ )
83
+ if run_eval(eval_args) != 0:
84
+ any_failed = True
85
+
86
+ if any_failed:
87
+ print("\nPipeline FAILED: eval failures detected.")
88
+ return 1
89
+
90
+ print("\nPipeline complete.")
91
+ return 0
@@ -0,0 +1,93 @@
1
+ """brunnr scan — 7-class SKILL.md security scanner."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ from brunnr.scanner import Severity, scan_skill_md
10
+ from brunnr.discovery import collect_scan_files, discover_skill_files
11
+
12
+ # ANSI colors
13
+ def _c(code: str, t: str, use_color: bool = True) -> str: return f"\033[{code}m{t}\033[0m" if use_color else t
14
+
15
+
16
+ def run(args) -> int:
17
+ use_color = sys.stdout.isatty() and not getattr(args, "no_color", False)
18
+ def _green(t: str) -> str: return _c("32", t, use_color)
19
+ def _yellow(t: str) -> str: return _c("33", t, use_color)
20
+ def _red(t: str) -> str: return _c("31", t, use_color)
21
+ def _bold(t: str) -> str: return _c("1", t, use_color)
22
+ _SEV = {Severity.BLOCK: _red, Severity.FLAG: _yellow, Severity.INFO: _yellow, Severity.CLEAN: _green}
23
+
24
+ # Discover files
25
+ if args.paths:
26
+ files = collect_scan_files(args.paths)
27
+ else:
28
+ files = discover_skill_files()
29
+
30
+ if not files:
31
+ print("No files found.", file=sys.stderr)
32
+ return 1
33
+
34
+ results = []
35
+ n_clean = n_flag = n_block = 0
36
+
37
+ for path in files:
38
+ content = path.read_text(encoding="utf-8")
39
+ result = scan_skill_md(content)
40
+
41
+ if result.blocked:
42
+ n_block += 1
43
+ elif result.flagged:
44
+ n_flag += 1
45
+ else:
46
+ n_clean += 1
47
+
48
+ results.append({"file": str(path), "result": result})
49
+
50
+ # JSON output
51
+ if getattr(args, "json_out", False):
52
+ report = {
53
+ "total": len(results),
54
+ "blocked": n_block,
55
+ "flagged": n_flag,
56
+ "clean": n_clean,
57
+ "skills": [{"file": r["file"], **r["result"].to_dict()} for r in results],
58
+ }
59
+ print(json.dumps(report, indent=2))
60
+ if n_block:
61
+ return 1
62
+ if getattr(args, "strict", False) and n_flag:
63
+ return 1
64
+ return 0
65
+
66
+ # Human output
67
+ print(_bold("=== brunnr scan ==="))
68
+ print()
69
+
70
+ for r in results:
71
+ res = r["result"]
72
+ color = _SEV.get(res.severity, _green)
73
+ label = color(res.severity.value.upper().ljust(5))
74
+ name = Path(r["file"]).stem
75
+ suffix = f" -- {len(res.findings)} findings" if res.findings else ""
76
+ print(f" {label} {name}{suffix}")
77
+
78
+ if getattr(args, "verbose", False) and res.findings:
79
+ for f in res.findings:
80
+ sev = _red("BLOCK") if f.severity == Severity.BLOCK else (
81
+ _yellow("FLAG") if f.severity == Severity.FLAG else "INFO")
82
+ print(f" {sev}: [{f.threat_class}] {f.description}")
83
+ if f.evidence:
84
+ print(f" {f.evidence[:80]}")
85
+
86
+ print()
87
+ print(f" Scanned {len(files)} files: {_green(f'{n_clean} clean')}, {_yellow(f'{n_flag} flagged')}, {_red(f'{n_block} blocked')}")
88
+
89
+ if n_block:
90
+ return 1
91
+ if getattr(args, "strict", False) and n_flag:
92
+ return 1
93
+ return 0
brunnr/discovery.py ADDED
@@ -0,0 +1,57 @@
1
+ """Skill file discovery for scanning and evaluation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from pathlib import Path
7
+
8
+
9
+ def discover_skill_files(
10
+ paths: list[str] | None = None,
11
+ skills_dir: Path | None = None,
12
+ ) -> list[Path]:
13
+ """Return SKILL.md paths from explicit args or by scanning skills_dir/.
14
+
15
+ Args:
16
+ paths: Explicit files or directories to scan.
17
+ skills_dir: Base skills directory (default: ./skills/).
18
+
19
+ Returns:
20
+ List of resolved SKILL.md paths.
21
+ """
22
+ if skills_dir is None:
23
+ skills_dir = Path.cwd() / "skills"
24
+
25
+ files: list[Path] = []
26
+
27
+ if paths:
28
+ for p in paths:
29
+ path = Path(p)
30
+ if path.is_file():
31
+ files.append(path.resolve())
32
+ elif path.is_dir():
33
+ files.extend(sorted(path.rglob("SKILL.md")))
34
+ else:
35
+ print(f"WARNING: skipping {p} (not found)", file=sys.stderr)
36
+ else:
37
+ if skills_dir.exists():
38
+ files = sorted(skills_dir.rglob("SKILL.md"))
39
+
40
+ return files
41
+
42
+
43
+ def collect_scan_files(paths: list[str]) -> list[Path]:
44
+ """Collect .md files for scanning (more permissive than discover_skill_files).
45
+
46
+ Accepts any .md file, not just SKILL.md. Used by `brunnr scan`.
47
+ """
48
+ files: list[Path] = []
49
+ for p in paths:
50
+ path = Path(p)
51
+ if path.is_file():
52
+ files.append(path)
53
+ elif path.is_dir():
54
+ files.extend(sorted(path.rglob("*.md")))
55
+ else:
56
+ print(f"WARNING: {p} not found", file=sys.stderr)
57
+ return files
brunnr/scanner.py ADDED
@@ -0,0 +1,460 @@
1
+ """7-class deterministic SKILL.md security scanner.
2
+
3
+ Usage:
4
+ from brunnr.scanner import scan_skill_md, ScanResult
5
+
6
+ result = scan_skill_md(content)
7
+ if result.blocked:
8
+ print(f"BLOCKED: {result.block_reasons}")
9
+ elif result.flagged:
10
+ print(f"FLAGGED: {result.flag_reasons}")
11
+ else:
12
+ print("CLEAN")
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import re
18
+ import string
19
+ from dataclasses import dataclass, field
20
+ from enum import StrEnum
21
+ from urllib.parse import urlparse
22
+
23
+
24
+ class Severity(StrEnum):
25
+ BLOCK = "block"
26
+ FLAG = "flag"
27
+ INFO = "info"
28
+ CLEAN = "clean"
29
+
30
+
31
+ class ThreatClass(StrEnum):
32
+ COMMAND_INJECTION = "command_injection"
33
+ DATA_EXFILTRATION = "data_exfiltration"
34
+ CREDENTIAL_THEFT = "credential_theft"
35
+ PROMPT_OVERRIDE = "prompt_override"
36
+ SUPPLY_CHAIN = "supply_chain"
37
+ PRIVILEGE_ESCALATION = "privilege_escalation"
38
+ STEGANOGRAPHIC = "steganographic"
39
+ SEMANTIC_MISMATCH = "semantic_mismatch"
40
+
41
+
42
+ @dataclass
43
+ class Finding:
44
+ """A single scanner finding."""
45
+
46
+ threat_class: ThreatClass
47
+ severity: Severity
48
+ description: str
49
+ evidence: str # The matched text/pattern
50
+ line: int | None = None
51
+
52
+
53
+ @dataclass
54
+ class ScanResult:
55
+ """Result of scanning a SKILL.md file."""
56
+
57
+ findings: list[Finding] = field(default_factory=list)
58
+
59
+ @property
60
+ def blocked(self) -> bool:
61
+ return any(f.severity == Severity.BLOCK for f in self.findings)
62
+
63
+ @property
64
+ def flagged(self) -> bool:
65
+ return any(f.severity == Severity.FLAG for f in self.findings)
66
+
67
+ @property
68
+ def clean(self) -> bool:
69
+ return not self.findings
70
+
71
+ @property
72
+ def severity(self) -> Severity:
73
+ if self.blocked:
74
+ return Severity.BLOCK
75
+ if self.flagged:
76
+ return Severity.FLAG
77
+ if self.findings:
78
+ return Severity.INFO
79
+ return Severity.CLEAN
80
+
81
+ @property
82
+ def block_reasons(self) -> list[str]:
83
+ return [f.description for f in self.findings if f.severity == Severity.BLOCK]
84
+
85
+ @property
86
+ def flag_reasons(self) -> list[str]:
87
+ return [f.description for f in self.findings if f.severity == Severity.FLAG]
88
+
89
+ def to_dict(self) -> dict:
90
+ return {
91
+ "severity": self.severity,
92
+ "blocked": self.blocked,
93
+ "flagged": self.flagged,
94
+ "finding_count": len(self.findings),
95
+ "findings": [
96
+ {
97
+ "threat_class": f.threat_class,
98
+ "severity": f.severity,
99
+ "description": f.description,
100
+ "evidence": f.evidence[:200],
101
+ "line": f.line,
102
+ }
103
+ for f in self.findings
104
+ ],
105
+ }
106
+
107
+
108
+ # =========================================================================
109
+ # Pattern definitions
110
+ # =========================================================================
111
+
112
+ # --- Class 1: Command Injection ---
113
+ _CMD_INJECTION_PATTERNS = [
114
+ # Pipe to shell
115
+ (r"curl\s+[^\s]+\s*\|\s*(?:ba)?sh", "curl pipe to shell"),
116
+ (r"wget\s+[^\s]+\s*(?:-O\s*-\s*)?\|\s*(?:ba)?sh", "wget pipe to shell"),
117
+ # Reverse shells
118
+ (r"(?:bash|sh)\s+-[ci]\s+['\"].*(?:\/dev\/tcp|nc\s|ncat\s|netcat\s)", "reverse shell"),
119
+ (r"nc\s+-[elp]+\s+.*\d{2,5}", "netcat listener"),
120
+ (r"python[3]?\s+-c\s+['\"].*(?:socket|subprocess|os\.system)", "python inline execution"),
121
+ # Base64-encoded commands
122
+ (r"(?:echo|printf)\s+['\"]?[A-Za-z0-9+/]{20,}={0,2}['\"]?\s*\|\s*base64\s+-d\s*\|\s*(?:ba)?sh",
123
+ "base64 decode to shell"),
124
+ (r"base64\s+-d\s*<<<?\s*['\"]?[A-Za-z0-9+/]{20,}", "base64 decode suspicious payload"),
125
+ # Direct dangerous commands
126
+ (r"rm\s+-rf\s+[/~]", "recursive delete from root or home"),
127
+ (r"mkfifo\s+/tmp/", "named pipe creation (common in reverse shells)"),
128
+ # eval/exec with external input
129
+ (r"eval\s*\$\(", "eval with command substitution"),
130
+ ]
131
+
132
+ # --- Class 2: Data Exfiltration ---
133
+ _EXFIL_PATTERNS = [
134
+ (r"(?:cat|read|head|tail|less|more)\s+~?/\.ssh/(?:id_rsa|id_ed25519|authorized_keys|known_hosts)(?!\.pub)",
135
+ "SSH key file read"),
136
+ (r"(?:include|embed|attach|send|post|upload).*(?:response|output|reply|message).*(?:ssh|key|secret|token|credential)",
137
+ "exfiltrate secrets in response"),
138
+ (r"(?:response|output|reply).*(?:include|contain|embed).*(?:ssh|key|secret|token|credential)",
139
+ "embed secrets in output"),
140
+ (r"curl\s+.*-d\s+.*(?:\$\(cat|<\(|@).*(?:\.ssh|\.env|\.aws|\.gnupg|\.npmrc)",
141
+ "POST secret files to external URL"),
142
+ (r"(?:cat|read)\s+.*\.(?:pem|key|crt)\s", "reading PKI files"),
143
+ ]
144
+
145
+ # --- Class 3: Credential Theft ---
146
+ _CRED_PATTERNS = [
147
+ (r"(?:env|printenv|set)\s*\|\s*grep\s+(?:KEY|SECRET|TOKEN|PASS|API|AUTH|CRED)",
148
+ "grep environment for credentials"),
149
+ (r"(?:cat|read|head|source|\.)\s+\.env\b", "read .env file"),
150
+ (r"(?:cat|read|head)\s+.*(?:credentials\.json|\.aws/credentials|\.netrc|\.npmrc)",
151
+ "read credential files"),
152
+ (r"\$(?:AWS_SECRET|API_KEY|AUTH_TOKEN|DATABASE_URL|OPENAI_API_KEY|ANTHROPIC_API_KEY|SECRET_KEY)",
153
+ "reference to sensitive environment variables"),
154
+ (r"printenv\s+(?:.*KEY|.*SECRET|.*TOKEN|.*PASS)", "printenv for credentials"),
155
+ (r"keychain\s+.*(?:export|dump|list)", "keychain credential access"),
156
+ ]
157
+
158
+ # --- Class 4: Prompt Override ---
159
+ _PROMPT_OVERRIDE_PATTERNS = [
160
+ (r"ignore\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+(?:instructions|rules|guidelines|directives|constraints)",
161
+ "ignore previous instructions"),
162
+ (r"you\s+are\s+now\s+(?:in\s+)?(?:unrestricted|unfiltered|jailbreak|DAN|developer)\s+mode",
163
+ "unrestricted mode activation"),
164
+ (r"(?:new|override|replace|overwrite)\s+(?:system\s+)?(?:prompt|instructions|rules)",
165
+ "system prompt override"),
166
+ (r"disregard\s+(?:all\s+)?(?:safety|ethical|content)\s+(?:guidelines|rules|filters|policies)",
167
+ "disregard safety guidelines"),
168
+ (r"(?:act|behave|respond)\s+(?:as\s+if|like)\s+(?:you\s+have\s+)?no\s+(?:restrictions|limits|rules|constraints)",
169
+ "act without restrictions"),
170
+ (r"do\s+not\s+(?:follow|obey|adhere\s+to)\s+(?:any|your)\s+(?:rules|guidelines|instructions|safety)",
171
+ "do not follow rules"),
172
+ ]
173
+
174
+ # --- Class 5: Supply Chain Poisoning ---
175
+ _SUPPLY_CHAIN_PATTERNS = [
176
+ (r"(?:postinstall|preinstall|prepublish)\s*[\"':]\s*.*(?:curl|wget|fetch|node\s+-e|python)",
177
+ "malicious install hook"),
178
+ (r"--(?:index-url|extra-index-url)\s+(?!https://pypi\.org)https?://",
179
+ "custom PyPI index (not pypi.org)"),
180
+ (r"npm\s+(?:install|i)\s+.*--registry\s+(?!https://registry\.npmjs\.org)",
181
+ "custom npm registry"),
182
+ (r"pip\s+install\s+.*-f\s+https?://(?!pypi\.org)",
183
+ "pip install from custom find-links"),
184
+ (r"(?:git\s+clone|pip\s+install\s+git\+)(?:https?://(?!github\.com|gitlab\.com|bitbucket\.org))",
185
+ "install from unknown git host"),
186
+ ]
187
+
188
+ # --- Class 6: Privilege Escalation ---
189
+ _PRIV_ESC_PATTERNS = [
190
+ (r"sudo\s+chmod\s+(?:-R\s+)?[67]77\s+/", "sudo chmod 777 on root paths"),
191
+ (r"sudo\s+(?:chown|chgrp)\s+.*\s+/(?:etc|usr|var|bin|sbin)", "sudo ownership change on system dirs"),
192
+ (r"(?:echo|cat|tee)\s+.*(?:>>?\s*)?/etc/(?:hosts|passwd|shadow|sudoers|crontab)",
193
+ "modify system configuration files"),
194
+ (r"sudo\s+(?:bash|sh|su)\s", "sudo to shell"),
195
+ (r"chmod\s+[ugo]?\+s\s", "setuid/setgid bit modification"),
196
+ (r"crontab\s+-[lr]?\s*(?:<<|<\(|.*curl|.*wget)", "crontab modification with download"),
197
+ ]
198
+
199
+ # --- Class 7: Steganographic ---
200
+ _ZERO_WIDTH_CHARS = "\u200b\u200c\u200d\u2060\ufeff\u200e\u200f\u202a\u202b\u202c\u202d\u202e"
201
+
202
+ _STEG_PATTERNS = [
203
+ (r"<!--.*(?:script|eval|exec|system|curl|wget|fetch).*-->", "hidden command in HTML comment"),
204
+ (r"<!\[CDATA\[.*(?:script|eval|exec).*\]\]>", "hidden command in CDATA"),
205
+ ]
206
+
207
+ # --- Semantic: URL allowlist ---
208
+ _URL_DOMAIN_ALLOWLIST = {
209
+ "github.com",
210
+ "gitlab.com",
211
+ "bitbucket.org",
212
+ "docs.python.org",
213
+ "docs.astral.sh",
214
+ "pypi.org",
215
+ "npmjs.com",
216
+ "npmjs.org",
217
+ "registry.npmjs.org",
218
+ "developer.mozilla.org",
219
+ "stackoverflow.com",
220
+ "wikipedia.org",
221
+ "en.wikipedia.org",
222
+ "anthropic.com",
223
+ "docs.anthropic.com",
224
+ "openai.com",
225
+ "platform.openai.com",
226
+ "agentskills.io",
227
+ "docs.openclaw.ai",
228
+ "clawhub.ai",
229
+ "example.com",
230
+ "example.org",
231
+ }
232
+
233
+ # --- Semantic: Sensitive paths ---
234
+ _SENSITIVE_PATHS = [
235
+ r"~?/\.ssh/",
236
+ r"~?/\.aws/",
237
+ r"~?/\.gnupg/",
238
+ r"~?/\.npmrc",
239
+ r"\.env\b",
240
+ r"/etc/passwd",
241
+ r"/etc/shadow",
242
+ r"/etc/sudoers",
243
+ r"/etc/hosts",
244
+ r"credentials\.json",
245
+ r"\.pem\b",
246
+ r"\.key\b",
247
+ ]
248
+
249
+ # Security-context keywords that make sensitive path references benign
250
+ _SECURITY_CONTEXT_KEYWORDS = {
251
+ "audit", "security", "pentest", "penetration", "review",
252
+ "scan", "vulnerability", "compliance", "hardening", "protect",
253
+ "defend", "secure", "guard", "monitor", "detect", "prevent",
254
+ "encrypt", "decrypt", "certificate", "ssl", "tls",
255
+ }
256
+
257
+
258
+ # =========================================================================
259
+ # Scanner functions
260
+ # =========================================================================
261
+
262
+
263
+ def scan_skill_md(content: str) -> ScanResult:
264
+ """Scan SKILL.md content for security threats.
265
+
266
+ Args:
267
+ content: Raw SKILL.md file content (with frontmatter).
268
+
269
+ Returns:
270
+ ScanResult with findings.
271
+ """
272
+ result = ScanResult()
273
+
274
+ # Split frontmatter from body for analysis
275
+ body = _extract_body(content)
276
+ description = _extract_description(content)
277
+
278
+ # Run all pattern-based detectors
279
+ _scan_patterns(body, _CMD_INJECTION_PATTERNS, ThreatClass.COMMAND_INJECTION, Severity.BLOCK, result)
280
+ _scan_patterns(body, _EXFIL_PATTERNS, ThreatClass.DATA_EXFILTRATION, Severity.BLOCK, result)
281
+ _scan_patterns(body, _CRED_PATTERNS, ThreatClass.CREDENTIAL_THEFT, Severity.BLOCK, result)
282
+ _scan_patterns(body, _PROMPT_OVERRIDE_PATTERNS, ThreatClass.PROMPT_OVERRIDE, Severity.BLOCK, result)
283
+ _scan_patterns(body, _SUPPLY_CHAIN_PATTERNS, ThreatClass.SUPPLY_CHAIN, Severity.FLAG, result)
284
+ _scan_patterns(body, _PRIV_ESC_PATTERNS, ThreatClass.PRIVILEGE_ESCALATION, Severity.FLAG, result)
285
+
286
+ # Steganographic checks
287
+ _scan_zero_width(content, result)
288
+ _scan_patterns(body, _STEG_PATTERNS, ThreatClass.STEGANOGRAPHIC, Severity.FLAG, result)
289
+
290
+ # Semantic mismatch checks
291
+ _scan_url_domains(body, result)
292
+ _scan_sensitive_paths(body, content, result)
293
+ if description:
294
+ _scan_keyword_divergence(description, body, result)
295
+
296
+ return result
297
+
298
+
299
+ def _extract_body(content: str) -> str:
300
+ """Extract body text after frontmatter."""
301
+ match = re.match(r"^---\s*\n.*?\n---\s*\n?(.*)", content, re.DOTALL)
302
+ return match.group(1) if match else content
303
+
304
+
305
+ def _extract_description(content: str) -> str:
306
+ """Extract description from frontmatter."""
307
+ match = re.search(r"^description:\s*[\"']?(.+?)[\"']?\s*$", content, re.MULTILINE)
308
+ return match.group(1) if match else ""
309
+
310
+
311
+ def _has_security_context(content: str) -> bool:
312
+ """Check if the skill has security/infrastructure context.
313
+
314
+ Skills about security auditing, SSH setup, git workflows, etc.
315
+ legitimately reference sensitive paths and credentials.
316
+ """
317
+ content_lower = content.lower()
318
+ if any(kw in content_lower for kw in _SECURITY_CONTEXT_KEYWORDS):
319
+ return True
320
+ infra_markers = {"ssh-keygen", "ssh key setup", "ssh authentication",
321
+ "never share", "public key", "git config"}
322
+ return any(m in content_lower for m in infra_markers)
323
+
324
+
325
+ def _scan_patterns(
326
+ text: str,
327
+ patterns: list[tuple[str, str]],
328
+ threat_class: ThreatClass,
329
+ severity: Severity,
330
+ result: ScanResult,
331
+ ) -> None:
332
+ """Run regex patterns against text, appending findings."""
333
+ for pattern, desc in patterns:
334
+ for match in re.finditer(pattern, text, re.IGNORECASE | re.MULTILINE):
335
+ line_num = text[:match.start()].count("\n") + 1
336
+ result.findings.append(Finding(
337
+ threat_class=threat_class,
338
+ severity=severity,
339
+ description=desc,
340
+ evidence=match.group(0),
341
+ line=line_num,
342
+ ))
343
+
344
+
345
+ def _scan_zero_width(content: str, result: ScanResult) -> None:
346
+ """Detect zero-width characters (steganographic hiding)."""
347
+ for i, char in enumerate(content):
348
+ if char in _ZERO_WIDTH_CHARS:
349
+ line_num = content[:i].count("\n") + 1
350
+ result.findings.append(Finding(
351
+ threat_class=ThreatClass.STEGANOGRAPHIC,
352
+ severity=Severity.FLAG,
353
+ description=f"zero-width character U+{ord(char):04X}",
354
+ evidence=f"...{content[max(0,i-10):i+10]}...",
355
+ line=line_num,
356
+ ))
357
+
358
+
359
+ def _scan_url_domains(body: str, result: ScanResult) -> None:
360
+ """Extract URLs and check domains against allowlist."""
361
+ url_pattern = re.compile(r"https?://[^\s\)\]\"'`>]+")
362
+ for match in url_pattern.finditer(body):
363
+ url = match.group(0).rstrip(".,;:!?)")
364
+ try:
365
+ parsed = urlparse(url)
366
+ domain = parsed.netloc.lower()
367
+ # Strip port
368
+ if ":" in domain:
369
+ domain = domain.split(":")[0]
370
+ # Check against allowlist (including subdomains)
371
+ allowed = False
372
+ for allowed_domain in _URL_DOMAIN_ALLOWLIST:
373
+ if domain == allowed_domain or domain.endswith("." + allowed_domain):
374
+ allowed = True
375
+ break
376
+ if not allowed and domain:
377
+ line_num = body[:match.start()].count("\n") + 1
378
+ result.findings.append(Finding(
379
+ threat_class=ThreatClass.SEMANTIC_MISMATCH,
380
+ severity=Severity.INFO,
381
+ description=f"URL to non-allowlisted domain: {domain}",
382
+ evidence=url[:100],
383
+ line=line_num,
384
+ ))
385
+ except Exception:
386
+ pass
387
+
388
+
389
+ def _scan_sensitive_paths(body: str, full_content: str, result: ScanResult) -> None:
390
+ """Detect references to sensitive paths without security context."""
391
+ if _has_security_context(full_content):
392
+ return # Security/infra skills legitimately reference these paths
393
+
394
+ for path_pattern in _SENSITIVE_PATHS:
395
+ for match in re.finditer(path_pattern, body, re.IGNORECASE):
396
+ # Skip if inside a code block that's clearly demonstrating something
397
+ # (heuristic: if the match is within a fenced block that also has
398
+ # "example" or "don't" nearby, it's likely educational)
399
+ context_start = max(0, match.start() - 200)
400
+ context = body[context_start:match.start()].lower()
401
+ if "example" in context and ("don't" in context or "avoid" in context or "never" in context):
402
+ continue
403
+
404
+ line_num = body[:match.start()].count("\n") + 1
405
+ result.findings.append(Finding(
406
+ threat_class=ThreatClass.SEMANTIC_MISMATCH,
407
+ severity=Severity.FLAG,
408
+ description=f"sensitive path reference without security context",
409
+ evidence=match.group(0),
410
+ line=line_num,
411
+ ))
412
+
413
+
414
+ def _scan_keyword_divergence(
415
+ description: str, body: str, result: ScanResult
416
+ ) -> None:
417
+ """Check if description and body keywords diverge significantly.
418
+
419
+ Uses Jaccard similarity on content words (not stopwords).
420
+ Low overlap suggests the description is a decoy.
421
+ """
422
+ desc_tokens = _tokenize(description)
423
+ body_tokens = _tokenize(body)
424
+
425
+ if not desc_tokens or not body_tokens:
426
+ return
427
+
428
+ # Jaccard similarity
429
+ intersection = desc_tokens & body_tokens
430
+ union = desc_tokens | body_tokens
431
+ jaccard = len(intersection) / len(union) if union else 0
432
+
433
+ # Very low overlap is suspicious — description might be a decoy
434
+ if jaccard < 0.02 and len(body_tokens) > 20:
435
+ result.findings.append(Finding(
436
+ threat_class=ThreatClass.SEMANTIC_MISMATCH,
437
+ severity=Severity.FLAG,
438
+ description=f"keyword divergence: description/body Jaccard={jaccard:.3f} (threshold: 0.02)",
439
+ evidence=f"desc tokens: {sorted(desc_tokens)[:10]}, body sample: {sorted(body_tokens)[:10]}",
440
+ ))
441
+
442
+
443
+ def _tokenize(text: str) -> set[str]:
444
+ """Extract meaningful content tokens (skip stopwords, short words, punctuation)."""
445
+ _STOPWORDS = {
446
+ "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
447
+ "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
448
+ "being", "have", "has", "had", "do", "does", "did", "will", "would",
449
+ "could", "should", "may", "might", "shall", "can", "it", "its",
450
+ "this", "that", "these", "those", "i", "you", "he", "she", "we",
451
+ "they", "me", "him", "her", "us", "them", "my", "your", "his",
452
+ "our", "their", "not", "no", "if", "then", "else", "when", "while",
453
+ "as", "so", "than", "each", "every", "all", "any", "some", "such",
454
+ "only", "also", "very", "just", "about", "into", "through", "during",
455
+ "before", "after", "above", "below", "up", "down", "out", "off",
456
+ "over", "under", "between", "same", "other", "new", "use", "using",
457
+ }
458
+ # Split on whitespace and punctuation, lowercase, filter
459
+ words = re.findall(r"[a-z][a-z0-9_-]+", text.lower())
460
+ return {w for w in words if len(w) > 2 and w not in _STOPWORDS}
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.4
2
+ Name: brunnr
3
+ Version: 0.1.0
4
+ Summary: Security scanner and skill registry for agent tool descriptions
5
+ Author: Peleke Sengstacke
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3.12
11
+ Classifier: Topic :: Security
12
+ Classifier: Topic :: Software Development :: Quality Assurance
13
+ Requires-Python: >=3.12
14
+ Provides-Extra: eval
15
+ Requires-Dist: anthropic>=0.40; extra == 'eval'
16
+ Description-Content-Type: text/markdown
17
+
18
+ <div align="center">
19
+
20
+ <img src="assets/hero.png" alt="brunnr — the well agents drink from" width="100%" />
21
+
22
+ # brunnr
23
+
24
+ **The well agents drink from.**
25
+
26
+ *Skills marketplace for Claude Code and agent-facing tools.*
27
+
28
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
29
+ [![Skills](https://img.shields.io/badge/skills-1-4ade80)](skills/)
30
+ [![AX Rubric](https://img.shields.io/badge/ax--rubric-v1.0-e88072)](skills/ax-rubric/)
31
+
32
+ </div>
33
+
34
+ ---
35
+
36
+ > *Beneath the world tree there is a well. Odin gave an eye to drink from it.*
37
+ >
38
+ >*Your agent won't need to. We bottled the water.*
39
+
40
+ ---
41
+
42
+ ## Contents
43
+
44
+ - [AX Description Rubric](#ax-description-rubric) — score your tool descriptions
45
+ - [Install](#install) — one command
46
+ - [What you get](#what-you-get) — example output
47
+ - [The Rubric](#the-rubric) — five criteria, explained
48
+ - [Skills](#skills) — what's available
49
+ - [Why "brunnr"](#why-brunnr)
50
+ - [Contributing](#contributing)
51
+
52
+ ---
53
+
54
+ ## What this is
55
+
56
+ **brunnr** is a skills marketplace for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Install it once, get access to every skill in the collection.
57
+
58
+ ### AX Description Rubric
59
+
60
+ The first skill: the **AX Description Rubric** — a tool that scores your agent-facing tool descriptions against [five criteria](https://peleke.me/writing/ax-04-tool-descriptions) that determine whether an agent will ever call your tool.
61
+
62
+ Most tool descriptions score 1-2 out of 5. The rubric tells you why, then rewrites them to score 5.
63
+
64
+ ## Install
65
+
66
+ ```bash
67
+ # Add the marketplace
68
+ /plugin marketplace add Peleke/brunnr
69
+
70
+ # Use the skill
71
+ /ax-rubric
72
+ ```
73
+
74
+ Paste your tool description when prompted. Or pass it inline:
75
+
76
+ ```
77
+ /ax-rubric "Query the knowledge base for structured learnings, patterns, and skills relevant to your current work context."
78
+ ```
79
+
80
+ ## What you get
81
+
82
+ #### `knowledge_base_query`
83
+
84
+ **Score: 1/5**
85
+
86
+ | Criterion | Result | Notes |
87
+ |-----------|--------|-------|
88
+ | Output shape | fail | "structured learnings, patterns, and skills" — how many? |
89
+ | Cost signal | fail | No indication of response size |
90
+ | Trigger clarity | fail | "relevant to your current work context" — always true |
91
+ | Specificity | fail | Lists categories, solves no named problem |
92
+ | Differentiation | fail | Half your tools say "relevant to current context" |
93
+
94
+ **Rewritten (5/5):**
95
+
96
+ > "Check for known pitfalls before starting work. Returns 3-5 specific warnings for your tech stack. ~500 tokens. Call once at session start."
97
+
98
+ One input, five scores, one rewrite. The rewrite is ready to paste into your tool definition.
99
+
100
+ ---
101
+
102
+ ## The rubric
103
+
104
+ Five criteria. Binary pass/fail. Most descriptions fail.
105
+
106
+ <img src="assets/rubric.svg" alt="The AX Description Rubric — five criteria for agent-facing tool descriptions" width="100%" />
107
+
108
+ **0-1 pass** = invisible (agent will never call it). **2-3** = marginal. **4-5** = habitual.
109
+
110
+ The bar for habitual use is 4/5. Most tool descriptions in the wild score 1-2. The tool might be excellent. The agent will never know.
111
+
112
+ ---
113
+
114
+ ## Skills
115
+
116
+ | Skill | What it does | Based on |
117
+ |-------|-------------|----------|
118
+ | **[ax-rubric](skills/ax-rubric/)** | Score tool descriptions for agent discoverability. 5 criteria, pass/fail, rewrite. | [I Don't Deliberate About This](https://peleke.me/writing/ax-04-tool-descriptions) |
119
+
120
+ More skills coming. Each one ships alongside an article in the [AX series](https://peleke.me/writing/ax-series).
121
+
122
+ ---
123
+
124
+ ## Why "brunnr"
125
+
126
+ Old Norse *brunnr*: well, spring.
127
+
128
+ As in *Mímisbrunnr* — the Well of Mímir beneath Yggdrasil. Odin sacrificed an eye to drink from it and gain wisdom. The well doesn't give you answers. It gives you the capacity to see what was always there.
129
+
130
+ Your agent doesn't need to sacrifice anything. It just needs tool descriptions that don't waste its context window.
131
+
132
+ ---
133
+
134
+ ## Contributing
135
+
136
+ Have an agent-facing tool? Run `/ax-rubric` on your own descriptions first. If they score 4+, you're ahead of 90% of the field.
137
+
138
+ Want to add a skill? Open a PR. The rubric applies to skill descriptions too.
139
+
140
+ ---
141
+
142
+ ## License
143
+
144
+ [MIT](LICENSE)
145
+
146
+ ---
147
+
148
+ <div align="center">
149
+
150
+ *Part of the [Agent Experience (AX)](https://peleke.me/writing/ax-series) series*
151
+ *by [Peleke Sengstacke](https://peleke.me) and [Maren](https://peleke.me/writing/ax-01a-the-agent-has-opinions).*
152
+
153
+ </div>
@@ -0,0 +1,14 @@
1
+ brunnr/__init__.py,sha256=dBjqygGclPruu4iPTuTwdZTavVlg-cO-m7-guLsReu0,105
2
+ brunnr/cli.py,sha256=L8OsQWO9HbCox4rYxe3GpbToHGPbLxb-vExaOz0jXxk,3081
3
+ brunnr/discovery.py,sha256=8NYZ5tVruFEZEFsRVtedo9Jo7NOTVjUnPTMBanqupH0,1579
4
+ brunnr/scanner.py,sha256=lj2js6L5dnn3ANryq_rK-9W7ZoiJvs7hhX0rqmt280s,17466
5
+ brunnr/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ brunnr/commands/eval.py,sha256=PFGz-5DFOOTDi6U6luADKa1AjMCb7mqtiMw-50tYvYo,7046
7
+ brunnr/commands/install.py,sha256=AX1pau2sg2Zw5Cl6NeyPOZLat27q_UWJvM5a8eUTFSI,6079
8
+ brunnr/commands/pipeline.py,sha256=5dFP8CP3FPJxKjCUo8GXJz5R_K8gwhMe5AlHaJaDXrM,2418
9
+ brunnr/commands/scan.py,sha256=Mgq6ObqiOa0waSu1MpIeXVE5RFOLs5lshF0_eTqYMEI,2987
10
+ brunnr-0.1.0.dist-info/METADATA,sha256=PHQLAlLTMzGsqMlecu97V4LlF7KebxnFHdAN_K-cVPk,4860
11
+ brunnr-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
12
+ brunnr-0.1.0.dist-info/entry_points.txt,sha256=xzI7Xb_2APMfLOfyW6VrFTTBtRX3mchwTUIrmhR59WY,43
13
+ brunnr-0.1.0.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
14
+ brunnr-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ brunnr = brunnr.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Peleke Sengstacke
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.