bluethroat 0.1.0__tar.gz

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,36 @@
1
+ Metadata-Version: 2.3
2
+ Name: bluethroat
3
+ Version: 0.1.0
4
+ Summary: Command-line client for BlueSkills
5
+ Author: iamwehi
6
+ Author-email: iamwehi <iamwehi@proton.me>
7
+ Requires-Dist: httpx>=0.28
8
+ Requires-Dist: keyring>=25
9
+ Requires-Python: >=3.11
10
+ Description-Content-Type: text/markdown
11
+
12
+ # bluethroat
13
+
14
+ Command-line client for BlueSkills. Log in once with the Bluethroat GitHub App, then `scan` waits for the report and prints it.
15
+
16
+ ```bash
17
+ uv tool install .
18
+ bluethroat auth login
19
+ bluethroat blueskills scan https://github.com/owner/repository --ref <commit>
20
+ ```
21
+
22
+ Add `--json` for the scan document returned by the API. Without it, the command prints text.
23
+
24
+ ## Configuration
25
+
26
+ | Variable | Purpose |
27
+ | --- | --- |
28
+ | `BLUETHROAT_GITHUB_CLIENT_ID` | GitHub App client ID. Defaults to the Bluethroat app (`Iv23liH0YU6oTHHz0i8O`). |
29
+ | `BLUETHROAT_GITHUB_CLIENT_SECRET` | Optional, for development only. Revokes directly at GitHub instead of through BlueSkills. Do not put this in the distributed client. |
30
+ | `BLUETHROAT_API_URL` | BlueSkills API origin. Defaults to `https://blueskills.bluethroatlabs.com`. |
31
+
32
+ The same keys can live in `~/.config/bluethroat/config.json` as `github_client_id`, `github_client_secret`, and `api_url`. Environment variables win.
33
+
34
+ The GitHub session is stored in the operating-system credential store, or in a mode `0600` file at `~/.config/bluethroat/credentials.json` when that store is unavailable.
35
+
36
+ `scan` sends `Authorization: Bearer` with the GitHub user access token. BlueSkills checks it against the Bluethroat CLI GitHub App and applies limits to the GitHub user id. The access token lasts 8 hours; the CLI refreshes it with GitHub on its own, which needs no client secret for a device-flow login. `auth logout` asks BlueSkills (`POST /auth/github/revoke`) to revoke the token, since only the server holds the secret.
@@ -0,0 +1,25 @@
1
+ # bluethroat
2
+
3
+ Command-line client for BlueSkills. Log in once with the Bluethroat GitHub App, then `scan` waits for the report and prints it.
4
+
5
+ ```bash
6
+ uv tool install .
7
+ bluethroat auth login
8
+ bluethroat blueskills scan https://github.com/owner/repository --ref <commit>
9
+ ```
10
+
11
+ Add `--json` for the scan document returned by the API. Without it, the command prints text.
12
+
13
+ ## Configuration
14
+
15
+ | Variable | Purpose |
16
+ | --- | --- |
17
+ | `BLUETHROAT_GITHUB_CLIENT_ID` | GitHub App client ID. Defaults to the Bluethroat app (`Iv23liH0YU6oTHHz0i8O`). |
18
+ | `BLUETHROAT_GITHUB_CLIENT_SECRET` | Optional, for development only. Revokes directly at GitHub instead of through BlueSkills. Do not put this in the distributed client. |
19
+ | `BLUETHROAT_API_URL` | BlueSkills API origin. Defaults to `https://blueskills.bluethroatlabs.com`. |
20
+
21
+ The same keys can live in `~/.config/bluethroat/config.json` as `github_client_id`, `github_client_secret`, and `api_url`. Environment variables win.
22
+
23
+ The GitHub session is stored in the operating-system credential store, or in a mode `0600` file at `~/.config/bluethroat/credentials.json` when that store is unavailable.
24
+
25
+ `scan` sends `Authorization: Bearer` with the GitHub user access token. BlueSkills checks it against the Bluethroat CLI GitHub App and applies limits to the GitHub user id. The access token lasts 8 hours; the CLI refreshes it with GitHub on its own, which needs no client secret for a device-flow login. `auth logout` asks BlueSkills (`POST /auth/github/revoke`) to revoke the token, since only the server holds the secret.
@@ -0,0 +1,28 @@
1
+ [project]
2
+ name = "bluethroat"
3
+ version = "0.1.0"
4
+ description = "Command-line client for BlueSkills"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ dependencies = [
8
+ "httpx>=0.28",
9
+ "keyring>=25",
10
+ ]
11
+
12
+ [[project.authors]]
13
+ name = "iamwehi"
14
+ email = "iamwehi@proton.me"
15
+
16
+ [project.scripts]
17
+ bluethroat = "bluethroat.cli:main"
18
+
19
+ [dependency-groups]
20
+ dev = ["pytest>=8"]
21
+
22
+ [tool.pytest.ini_options]
23
+ testpaths = ["tests"]
24
+ addopts = "-q"
25
+
26
+ [build-system]
27
+ requires = ["uv_build>=0.12.13,<0.13.0"]
28
+ build-backend = "uv_build"
@@ -0,0 +1,27 @@
1
+ [project]
2
+ name = "bluethroat"
3
+ version = "0.1.0"
4
+ description = "Command-line client for BlueSkills"
5
+ readme = "README.md"
6
+ authors = [
7
+ { name = "iamwehi", email = "iamwehi@proton.me" }
8
+ ]
9
+ requires-python = ">=3.11"
10
+ dependencies = [
11
+ "httpx>=0.28",
12
+ "keyring>=25",
13
+ ]
14
+
15
+ [dependency-groups]
16
+ dev = ["pytest>=8"]
17
+
18
+ [tool.pytest.ini_options]
19
+ testpaths = ["tests"]
20
+ addopts = "-q"
21
+
22
+ [project.scripts]
23
+ bluethroat = "bluethroat.cli:main"
24
+
25
+ [build-system]
26
+ requires = ["uv_build>=0.12.13,<0.13.0"]
27
+ build-backend = "uv_build"
@@ -0,0 +1,3 @@
1
+ """Command-line client for BlueSkills."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,254 @@
1
+ """BlueSkills HTTP API.
2
+
3
+ ``POST /scan.json`` starts a scan. A hosted scan answers ``202`` with a
4
+ ``scan_id`` while deeper analysis is still running. ``GET /scans/{scan_id}``
5
+ is the status of that scan and is not a command the user runs: ``scan`` polls
6
+ it until the report is finished.
7
+
8
+ Every request sends the GitHub App user access token as
9
+ ``Authorization: Bearer``. BlueSkills checks it with the app's credentials and
10
+ keys its limits on the numeric GitHub user id. ``POST /auth/github/revoke``
11
+ revokes that token at GitHub for ``auth logout``.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import time
17
+ import zipfile
18
+ from collections.abc import Callable
19
+ from pathlib import Path
20
+ from urllib.parse import urlsplit, urlunsplit
21
+
22
+ import httpx
23
+
24
+ from bluethroat.credentials import Session
25
+ from bluethroat.errors import INVALID, RATE_LIMITED, SERVICE, CliError
26
+
27
+ _TERMINAL = {"done", "failed"}
28
+ _RUNNING = {"queued", "static", "queued_deep", "deep", "dynamic", "judging"}
29
+ _MAX_ZIP = 25 * 1024 * 1024
30
+ _MAX_TEXT = 1 * 1024 * 1024
31
+ _WAIT = 15 * 60
32
+
33
+
34
+ class BlueSkillsClient:
35
+ def __init__(
36
+ self,
37
+ client: httpx.Client,
38
+ api_url: str,
39
+ session: Session,
40
+ *,
41
+ sleep: Callable[[float], None] | None = None,
42
+ clock: Callable[[], float] | None = None,
43
+ ) -> None:
44
+ self._http = client
45
+ self._api = api_url.rstrip("/")
46
+ self._session = session
47
+ self._sleep = sleep or time.sleep
48
+ self._clock = clock or time.monotonic
49
+
50
+ def scan(self, source: str, *, ref: str | None) -> dict:
51
+ kind, payload, filename = _prepare(source, ref)
52
+ print("Scanning…", file=_err(), flush=True)
53
+ if kind == "url":
54
+ code, doc = self._request("POST", "/scan.json", data={"repo_url": payload})
55
+ elif kind == "text":
56
+ code, doc = self._request("POST", "/scan.json", data={"skill_md": payload})
57
+ else:
58
+ code, doc = self._request(
59
+ "POST",
60
+ "/scan.json",
61
+ files={"file": (filename, payload, "application/zip")},
62
+ )
63
+ _raise_for_status(code, doc)
64
+ if _finished(code, doc):
65
+ return _public(doc)
66
+ scan_id = str(doc.get("scan_id") or "")
67
+ if not scan_id:
68
+ raise CliError("The scan did not return an id to wait on.", SERVICE)
69
+ return self._wait(scan_id)
70
+
71
+ def revoke(self) -> None:
72
+ """Ask BlueSkills to revoke the session's access token at GitHub."""
73
+ code, _doc = self._request("POST", "/auth/github/revoke")
74
+ if code != 204:
75
+ raise CliError(
76
+ "The local session was removed, but GitHub did not revoke the token. "
77
+ "Revoke Bluethroat under GitHub Settings → Applications.",
78
+ SERVICE,
79
+ )
80
+
81
+ def _wait(self, scan_id: str) -> dict:
82
+ print("Waiting for the report…", file=_err(), flush=True)
83
+ deadline = self._clock() + _WAIT
84
+ fast_until = self._clock() + 30
85
+ interval = 2.0
86
+ while self._clock() < deadline:
87
+ self._sleep(interval)
88
+ if self._clock() >= fast_until:
89
+ interval = 10.0
90
+ code, doc = self._request("GET", f"/scans/{scan_id}")
91
+ if code == 404:
92
+ continue
93
+ _raise_for_status(code, doc)
94
+ if _finished(code, doc):
95
+ return _public(doc)
96
+ raise CliError(
97
+ "The report was not ready after 15 minutes. Run the same scan again.",
98
+ SERVICE,
99
+ )
100
+
101
+ def _request(self, method: str, path: str, **kwargs: object) -> tuple[int, dict]:
102
+ headers = {
103
+ "Authorization": f"Bearer {self._session.access_token}",
104
+ "User-Agent": "bluethroat",
105
+ "Accept": "application/json",
106
+ }
107
+ try:
108
+ response = self._http.request(method, f"{self._api}{path}", headers=headers, **kwargs)
109
+ except httpx.HTTPError as exc:
110
+ raise CliError(f"Could not reach BlueSkills ({exc.__class__.__name__}).", SERVICE) from exc
111
+ try:
112
+ body = response.json()
113
+ except ValueError:
114
+ body = {}
115
+ if not isinstance(body, dict):
116
+ body = {}
117
+ return response.status_code, body | {"_retry_after": response.headers.get("retry-after")}
118
+
119
+
120
+ def _public(doc: dict) -> dict:
121
+ return {key: value for key, value in doc.items() if not str(key).startswith("_")}
122
+
123
+
124
+ def _finished(code: int, doc: dict) -> bool:
125
+ status = str(doc.get("status") or "")
126
+ if status in _TERMINAL:
127
+ return True
128
+ if status in _RUNNING:
129
+ return False
130
+ return code == 200 and ("worst_verdict" in doc or "verdict" in doc)
131
+
132
+
133
+ def _raise_for_status(code: int, doc: dict) -> None:
134
+ if code == 429:
135
+ retry = doc.get("retry_after")
136
+ if retry is None:
137
+ retry = doc.get("_retry_after") or "1"
138
+ raise CliError(
139
+ f"rate limited, retry after {retry}s",
140
+ RATE_LIMITED,
141
+ body={"error": str(doc.get("error") or "Not right now"), "retry_after": _int(retry)},
142
+ )
143
+ if code in {400, 413, 422}:
144
+ raise CliError(str(doc.get("error") or "The scan was rejected."), INVALID)
145
+ if code >= 400:
146
+ raise CliError(str(doc.get("error") or f"BlueSkills returned HTTP {code}."), SERVICE)
147
+
148
+
149
+ def _int(value: object) -> int:
150
+ try:
151
+ return max(1, int(float(str(value))))
152
+ except (TypeError, ValueError):
153
+ return 1
154
+
155
+
156
+ def _prepare(source: str, ref: str | None) -> tuple[str, str | bytes, str]:
157
+ text = source.strip()
158
+ if _is_repo_url(text):
159
+ return "url", _with_ref(text, ref), ""
160
+ if ref:
161
+ raise CliError("--ref is only valid for a GitHub or GitLab URL.", INVALID)
162
+ path = Path(text).expanduser()
163
+ if not path.exists():
164
+ raise CliError(f"No such file: {path}", INVALID)
165
+ if path.is_symlink():
166
+ raise CliError(f"{path} is a symlink and cannot be scanned.", INVALID)
167
+ if path.is_dir():
168
+ return "zip", _zip_dir(path), f"{path.name}.zip"
169
+ if path.suffix.lower() == ".zip":
170
+ data = path.read_bytes()
171
+ if len(data) > _MAX_ZIP:
172
+ raise CliError("That archive is larger than the 25 MiB limit.", INVALID)
173
+ return "zip", data, path.name
174
+ if path.name.lower() == "skill.md":
175
+ data = path.read_text(encoding="utf-8")
176
+ if len(data.encode("utf-8")) > _MAX_TEXT:
177
+ raise CliError("That SKILL.md is larger than the 1 MiB limit.", INVALID)
178
+ return "text", data, ""
179
+ raise CliError(
180
+ "Scan a public GitHub or GitLab URL, a skill directory, a .zip, or a SKILL.md file.",
181
+ INVALID,
182
+ )
183
+
184
+
185
+ def _is_repo_url(value: str) -> bool:
186
+ if "://" not in value and not value.startswith(("github.com/", "gitlab.com/")):
187
+ return False
188
+ raw = value if "://" in value else "https://" + value
189
+ try:
190
+ host = (urlsplit(raw).hostname or "").lower()
191
+ except ValueError:
192
+ return False
193
+ return host in {"github.com", "www.github.com", "gitlab.com", "www.gitlab.com"}
194
+
195
+
196
+ def _with_ref(url: str, ref: str | None) -> str:
197
+ raw = url if "://" in url else "https://" + url
198
+ parts = urlsplit(raw)
199
+ if parts.scheme != "https":
200
+ raise CliError("Only https:// repository URLs are accepted.", INVALID)
201
+ host = (parts.hostname or "").lower()
202
+ segs = [segment for segment in parts.path.split("/") if segment]
203
+ if len(segs) < 2:
204
+ raise CliError("That URL does not look like a repository.", INVALID)
205
+ gitlab = host.endswith("gitlab.com")
206
+ existing = _existing_ref(segs, gitlab=gitlab)
207
+ if ref and existing and existing != ref:
208
+ raise CliError("The URL already names a different revision than --ref.", INVALID)
209
+ chosen = ref or existing
210
+ if not chosen or existing:
211
+ path = "/" + "/".join(_strip_git(segs))
212
+ return urlunsplit((parts.scheme, parts.netloc, path, "", ""))
213
+ owner, repo, *rest = _strip_git(segs)
214
+ middle = ["-", "tree", chosen] if gitlab else ["tree", chosen]
215
+ path = "/" + "/".join([owner, repo, *middle, *rest])
216
+ return urlunsplit((parts.scheme, parts.netloc, path, "", ""))
217
+
218
+
219
+ def _strip_git(segs: list[str]) -> list[str]:
220
+ if len(segs) >= 2 and segs[1].endswith(".git"):
221
+ return [segs[0], segs[1][:-4], *segs[2:]]
222
+ return segs
223
+
224
+
225
+ def _existing_ref(segs: list[str], *, gitlab: bool) -> str | None:
226
+ tail = segs[2:]
227
+ if gitlab and tail and tail[0] == "-":
228
+ tail = tail[1:]
229
+ if len(tail) >= 2 and tail[0] in {"tree", "blob"}:
230
+ return tail[1]
231
+ return None
232
+
233
+
234
+ def _zip_dir(root: Path) -> bytes:
235
+ import io
236
+
237
+ buf = io.BytesIO()
238
+ with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as archive:
239
+ for path in sorted(root.rglob("*")):
240
+ if path.is_symlink():
241
+ raise CliError(f"{path} is a symlink and cannot be scanned.", INVALID)
242
+ if not path.is_file():
243
+ continue
244
+ archive.write(path, path.relative_to(root).as_posix())
245
+ data = buf.getvalue()
246
+ if len(data) > _MAX_ZIP:
247
+ raise CliError("That directory zips to more than the 25 MiB limit.", INVALID)
248
+ return data
249
+
250
+
251
+ def _err():
252
+ import sys
253
+
254
+ return sys.stderr
@@ -0,0 +1,202 @@
1
+ """``bluethroat`` command line.
2
+
3
+ ``scan`` submits a source, waits for the hosted report, and prints it.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import argparse
9
+ import json
10
+ import sys
11
+ from collections.abc import Callable
12
+
13
+ import httpx
14
+
15
+ from bluethroat import __version__
16
+ from bluethroat.api import BlueSkillsClient
17
+ from bluethroat.config import Config
18
+ from bluethroat.credentials import CredentialStore, SessionStore
19
+ from bluethroat.errors import AUTH, INVALID, SERVICE, CliError, code_for
20
+ from bluethroat.github_auth import GitHubAuth
21
+ from bluethroat.report import _commit, outcome, render
22
+
23
+
24
+ def main(
25
+ argv: list[str] | None = None,
26
+ *,
27
+ store: SessionStore | None = None,
28
+ client: httpx.Client | None = None,
29
+ opener: Callable[[str], object] | None = None,
30
+ sleep: Callable[[float], None] | None = None,
31
+ now: Callable[[], float] | None = None,
32
+ clock: Callable[[], float] | None = None,
33
+ ) -> int:
34
+ parser = _parser()
35
+ args = parser.parse_args(argv)
36
+ handler = getattr(args, "handler", None)
37
+ if handler is None:
38
+ parser.print_help()
39
+ return INVALID
40
+ owns_client = client is None
41
+ http = client or httpx.Client(timeout=httpx.Timeout(10.0, read=120.0))
42
+ try:
43
+ return handler(
44
+ args,
45
+ store=store or CredentialStore(),
46
+ http=http,
47
+ opener=opener,
48
+ sleep=sleep,
49
+ now=now,
50
+ clock=clock,
51
+ )
52
+ except CliError as exc:
53
+ print(str(exc), file=sys.stderr)
54
+ if getattr(args, "json", False) and exc.body is not None:
55
+ json.dump(exc.body, sys.stdout)
56
+ sys.stdout.write("\n")
57
+ return exc.code
58
+ finally:
59
+ if owns_client:
60
+ http.close()
61
+
62
+
63
+ def _parser() -> argparse.ArgumentParser:
64
+ parser = argparse.ArgumentParser(
65
+ prog="bluethroat",
66
+ description="Scan an agent skill with BlueSkills before installing it.",
67
+ )
68
+ parser.add_argument("--version", action="version", version=f"bluethroat {__version__}")
69
+ commands = parser.add_subparsers(dest="command")
70
+
71
+ auth = commands.add_parser("auth", help="Log in with the Bluethroat GitHub App.")
72
+ auth_commands = auth.add_subparsers(dest="auth_command")
73
+ login = auth_commands.add_parser("login", help="Authorize this client once via GitHub device flow.")
74
+ login.set_defaults(handler=_login)
75
+ status = auth_commands.add_parser("status", help="Show the logged-in GitHub account.")
76
+ status.set_defaults(handler=_status)
77
+ logout = auth_commands.add_parser("logout", help="Remove the local credential and revoke it.")
78
+ logout.set_defaults(handler=_logout)
79
+ auth.set_defaults(handler=_auth_help)
80
+
81
+ blueskills = commands.add_parser("blueskills", help="BlueSkills scans.")
82
+ blueskills_commands = blueskills.add_subparsers(dest="blueskills_command")
83
+ scan = blueskills_commands.add_parser(
84
+ "scan",
85
+ help="Scan a public repository, directory, zip, or SKILL.md and print the report.",
86
+ )
87
+ scan.add_argument(
88
+ "source",
89
+ help="Public GitHub or GitLab URL, a skill directory, a .zip, or a SKILL.md file.",
90
+ )
91
+ scan.add_argument("--ref", help="Branch, tag, or commit. Only valid for a repository URL.")
92
+ scan.add_argument(
93
+ "--json",
94
+ action="store_true",
95
+ help="Print the hosted scan document as JSON. The default is a text report.",
96
+ )
97
+ scan.set_defaults(handler=_scan)
98
+ blueskills.set_defaults(handler=_blueskills_help)
99
+ return parser
100
+
101
+
102
+ def _auth_help(_args: argparse.Namespace, **_kwargs: object) -> int:
103
+ print("usage: bluethroat auth {login,status,logout}", file=sys.stderr)
104
+ return INVALID
105
+
106
+
107
+ def _blueskills_help(_args: argparse.Namespace, **_kwargs: object) -> int:
108
+ print("usage: bluethroat blueskills scan <source> [--ref REF] [--json]", file=sys.stderr)
109
+ return INVALID
110
+
111
+
112
+ def _github(http: httpx.Client, **kwargs: object) -> GitHubAuth:
113
+ config = Config.load()
114
+ return GitHubAuth(
115
+ http,
116
+ config.github_client_id,
117
+ client_secret=config.github_client_secret,
118
+ opener=kwargs.get("opener"), # type: ignore[arg-type]
119
+ sleep=kwargs.get("sleep"), # type: ignore[arg-type]
120
+ now=kwargs.get("now"), # type: ignore[arg-type]
121
+ )
122
+
123
+
124
+ def _login(_args: argparse.Namespace, *, store: SessionStore, http: httpx.Client, **kwargs: object) -> int:
125
+ session = _github(http, **kwargs).login()
126
+ store.save(session)
127
+ print(f"logged in as {session.login}")
128
+ return 0
129
+
130
+
131
+ def _status(_args: argparse.Namespace, *, store: SessionStore, http: httpx.Client, **kwargs: object) -> int:
132
+ session = store.load()
133
+ if session is None:
134
+ raise CliError("not logged in", AUTH)
135
+ session = _github(http, **kwargs).ensure(session)
136
+ store.save(session)
137
+ print(f"logged in as {session.login} (id {session.user_id})")
138
+ return 0
139
+
140
+
141
+ def _logout(_args: argparse.Namespace, *, store: SessionStore, http: httpx.Client, **kwargs: object) -> int:
142
+ session = store.load()
143
+ store.clear()
144
+ if session is None:
145
+ print("logged out")
146
+ return 0
147
+ config = Config.load()
148
+ if config.github_client_secret:
149
+ _github(http, **kwargs).revoke(session)
150
+ else:
151
+ BlueSkillsClient(http, config.api_url, session).revoke()
152
+ print("logged out")
153
+ return 0
154
+
155
+
156
+ def _scan(
157
+ args: argparse.Namespace,
158
+ *,
159
+ store: SessionStore,
160
+ http: httpx.Client,
161
+ **kwargs: object,
162
+ ) -> int:
163
+ session = store.load()
164
+ if session is None:
165
+ raise CliError("not logged in. Run bluethroat auth login.", AUTH)
166
+ auth = _github(http, **kwargs)
167
+ session = auth.ensure(session)
168
+ store.save(session)
169
+ doc = BlueSkillsClient(
170
+ http,
171
+ Config.load().api_url,
172
+ session,
173
+ sleep=kwargs.get("sleep"), # type: ignore[arg-type]
174
+ clock=kwargs.get("clock"), # type: ignore[arg-type]
175
+ ).scan(args.source, ref=args.ref)
176
+ _check_ref(args.ref, _commit(doc))
177
+ verdict, complete = outcome(doc)
178
+ if args.json:
179
+ json.dump(doc, sys.stdout, indent=2)
180
+ sys.stdout.write("\n")
181
+ else:
182
+ print(render(doc))
183
+ if doc.get("status") == "failed":
184
+ return SERVICE
185
+ return code_for(verdict, complete=complete)
186
+
187
+
188
+ def _check_ref(ref: str | None, served: str) -> None:
189
+ if not ref or len(ref) != 40 or any(char not in "0123456789abcdefABCDEF" for char in ref):
190
+ return
191
+ wanted = ref.lower()
192
+ got = served.lower()
193
+ if got and (wanted.startswith(got) or got.startswith(wanted)):
194
+ return
195
+ raise CliError(
196
+ "The host served a different commit than --ref. No verdict.",
197
+ INVALID,
198
+ )
199
+
200
+
201
+ if __name__ == "__main__":
202
+ raise SystemExit(main())
@@ -0,0 +1,63 @@
1
+ """Process configuration. Environment variables override the config file."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+
10
+ DEFAULT_API_URL = "https://blueskills.bluethroatlabs.com"
11
+ # Public GitHub App client ID. The client secret stays out of the distributed CLI.
12
+ DEFAULT_GITHUB_CLIENT_ID = "Iv23liH0YU6oTHHz0i8O"
13
+
14
+
15
+ def config_dir() -> Path:
16
+ override = (os.environ.get("BLUETHROAT_CONFIG_DIR") or "").strip()
17
+ if override:
18
+ return Path(override).expanduser()
19
+ xdg = (os.environ.get("XDG_CONFIG_HOME") or "").strip()
20
+ base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
21
+ return base / "bluethroat"
22
+
23
+
24
+ def _file_values() -> dict[str, str]:
25
+ path = config_dir() / "config.json"
26
+ try:
27
+ raw = json.loads(path.read_text(encoding="utf-8"))
28
+ except (OSError, json.JSONDecodeError, UnicodeError):
29
+ return {}
30
+ if not isinstance(raw, dict):
31
+ return {}
32
+ out: dict[str, str] = {}
33
+ for key in ("github_client_id", "github_client_secret", "api_url"):
34
+ value = raw.get(key)
35
+ if isinstance(value, str) and value.strip():
36
+ out[key] = value.strip()
37
+ return out
38
+
39
+
40
+ def _pick(env: str, file_key: str, default: str = "") -> str:
41
+ direct = (os.environ.get(env) or "").strip()
42
+ if direct:
43
+ return direct
44
+ return _file_values().get(file_key, default)
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class Config:
49
+ github_client_id: str
50
+ github_client_secret: str
51
+ api_url: str
52
+
53
+ @classmethod
54
+ def load(cls) -> Config:
55
+ return cls(
56
+ github_client_id=_pick(
57
+ "BLUETHROAT_GITHUB_CLIENT_ID",
58
+ "github_client_id",
59
+ DEFAULT_GITHUB_CLIENT_ID,
60
+ ),
61
+ github_client_secret=_pick("BLUETHROAT_GITHUB_CLIENT_SECRET", "github_client_secret"),
62
+ api_url=_pick("BLUETHROAT_API_URL", "api_url", DEFAULT_API_URL).rstrip("/"),
63
+ )
@@ -0,0 +1,151 @@
1
+ """Local GitHub session.
2
+
3
+ The operating-system credential store holds the session when it is available.
4
+ Otherwise the session is a mode ``0600`` file under the config directory.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import os
11
+ from dataclasses import asdict, dataclass
12
+ from typing import Protocol
13
+
14
+ from bluethroat.config import config_dir
15
+
16
+ _SERVICE = "bluethroat"
17
+ _ACCOUNT = "default"
18
+
19
+
20
+ @dataclass
21
+ class Session:
22
+ access_token: str
23
+ refresh_token: str
24
+ expires_at: float
25
+ refresh_expires_at: float
26
+ login: str
27
+ user_id: int
28
+
29
+ def to_json(self) -> str:
30
+ return json.dumps(asdict(self), separators=(",", ":"))
31
+
32
+ @classmethod
33
+ def from_json(cls, raw: str) -> Session | None:
34
+ try:
35
+ data = json.loads(raw)
36
+ except json.JSONDecodeError:
37
+ return None
38
+ if not isinstance(data, dict):
39
+ return None
40
+ try:
41
+ return cls(
42
+ access_token=str(data["access_token"]),
43
+ refresh_token=str(data.get("refresh_token") or ""),
44
+ expires_at=float(data.get("expires_at") or 0),
45
+ refresh_expires_at=float(data.get("refresh_expires_at") or 0),
46
+ login=str(data.get("login") or ""),
47
+ user_id=int(data.get("user_id") or 0),
48
+ )
49
+ except (KeyError, TypeError, ValueError):
50
+ return None
51
+
52
+
53
+ class SessionStore(Protocol):
54
+ def load(self) -> Session | None: ...
55
+
56
+ def save(self, session: Session) -> None: ...
57
+
58
+ def clear(self) -> None: ...
59
+
60
+
61
+ class MemoryStore:
62
+ """In-process store for tests."""
63
+
64
+ def __init__(self) -> None:
65
+ self.session: Session | None = None
66
+
67
+ def load(self) -> Session | None:
68
+ return self.session
69
+
70
+ def save(self, session: Session) -> None:
71
+ self.session = session
72
+
73
+ def clear(self) -> None:
74
+ self.session = None
75
+
76
+
77
+ class CredentialStore:
78
+ def load(self) -> Session | None:
79
+ raw = _keyring_get()
80
+ if raw:
81
+ session = Session.from_json(raw)
82
+ if session is not None:
83
+ return session
84
+ return _file_load()
85
+
86
+ def save(self, session: Session) -> None:
87
+ encoded = session.to_json()
88
+ if _keyring_set(encoded):
89
+ _file_path().unlink(missing_ok=True)
90
+ return
91
+ _file_save(encoded)
92
+
93
+ def clear(self) -> None:
94
+ _keyring_delete()
95
+ _file_path().unlink(missing_ok=True)
96
+
97
+
98
+ def _keyring_get() -> str | None:
99
+ try:
100
+ import keyring
101
+ except ImportError:
102
+ return None
103
+ try:
104
+ return keyring.get_password(_SERVICE, _ACCOUNT)
105
+ except Exception:
106
+ return None
107
+
108
+
109
+ def _keyring_set(encoded: str) -> bool:
110
+ try:
111
+ import keyring
112
+ except ImportError:
113
+ return False
114
+ try:
115
+ keyring.set_password(_SERVICE, _ACCOUNT, encoded)
116
+ except Exception:
117
+ return False
118
+ return True
119
+
120
+
121
+ def _keyring_delete() -> None:
122
+ try:
123
+ import keyring
124
+ keyring.delete_password(_SERVICE, _ACCOUNT)
125
+ except Exception:
126
+ return
127
+
128
+
129
+ def _file_path():
130
+ return config_dir() / "credentials.json"
131
+
132
+
133
+ def _file_load() -> Session | None:
134
+ try:
135
+ raw = _file_path().read_text(encoding="utf-8")
136
+ except (OSError, UnicodeError):
137
+ return None
138
+ return Session.from_json(raw)
139
+
140
+
141
+ def _file_save(encoded: str) -> None:
142
+ path = _file_path()
143
+ path.parent.mkdir(parents=True, exist_ok=True)
144
+ os.chmod(path.parent, 0o700)
145
+ flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
146
+ fd = os.open(path, flags, 0o600)
147
+ try:
148
+ os.write(fd, encoded.encode("utf-8"))
149
+ finally:
150
+ os.close(fd)
151
+ os.chmod(path, 0o600)
@@ -0,0 +1,41 @@
1
+ """Process exit codes for ``bluethroat``."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ CLEAN = 0
7
+ SUSPICIOUS = 1
8
+ MALICIOUS = 2
9
+ INCOMPLETE = 3
10
+ INVALID = 4
11
+ RATE_LIMITED = 5
12
+ AUTH = 6
13
+ SERVICE = 7
14
+
15
+
16
+ class CliError(Exception):
17
+ """A failure the command should print and exit with ``code``."""
18
+
19
+ def __init__(self, message: str, code: int, *, body: dict | None = None) -> None:
20
+ super().__init__(message)
21
+ self.code = code
22
+ self.body = body
23
+
24
+
25
+ def code_for(verdict: str, *, complete: bool) -> int:
26
+ """Map a finished report to an exit code.
27
+
28
+ An unfinished or partial report is never a successful clean scan.
29
+ """
30
+ label = (verdict or "").strip().lower()
31
+ if label == "invalid":
32
+ return INVALID
33
+ if label == "error":
34
+ return SERVICE
35
+ if not complete or label == "partial":
36
+ return INCOMPLETE
37
+ return {
38
+ "clean": CLEAN,
39
+ "suspicious": SUSPICIOUS,
40
+ "malicious": MALICIOUS,
41
+ }.get(label, INCOMPLETE)
@@ -0,0 +1,220 @@
1
+ """GitHub App device flow.
2
+
3
+ The device grant and the refresh grant send only the public client ID. A
4
+ distributed CLI cannot keep the client secret, so revocation goes through
5
+ BlueSkills (``POST /auth/github/revoke``), which holds it. A secret set locally
6
+ still revokes directly at GitHub.
7
+
8
+ See GitHub's "Generating a user access token for a GitHub App".
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import time
15
+ import webbrowser
16
+ from collections.abc import Callable
17
+ from typing import Any
18
+
19
+ import httpx
20
+
21
+ from bluethroat.credentials import Session
22
+ from bluethroat.errors import AUTH, SERVICE, CliError
23
+
24
+ GITHUB = "https://github.com"
25
+ API = "https://api.github.com"
26
+ _API_VERSION = "2026-03-10"
27
+ _DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
28
+
29
+
30
+ class GitHubAuth:
31
+ def __init__(
32
+ self,
33
+ client: httpx.Client,
34
+ client_id: str,
35
+ *,
36
+ client_secret: str = "",
37
+ opener: Callable[[str], object] | None = None,
38
+ sleep: Callable[[float], None] | None = None,
39
+ now: Callable[[], float] | None = None,
40
+ ) -> None:
41
+ if not client_id:
42
+ raise CliError(
43
+ "Set BLUETHROAT_GITHUB_CLIENT_ID to the GitHub App client ID.",
44
+ AUTH,
45
+ )
46
+ self._http = client
47
+ self._client_id = client_id
48
+ self._client_secret = client_secret
49
+ self._open = opener or webbrowser.open
50
+ self._sleep = sleep or time.sleep
51
+ self._now = now or time.time
52
+
53
+ def login(self) -> Session:
54
+ """Run the device flow and return the session for the authorizing user."""
55
+ pending = self._post_form(
56
+ f"{GITHUB}/login/device/code",
57
+ {"client_id": self._client_id},
58
+ )
59
+ if pending.get("error"):
60
+ raise CliError(f"GitHub login failed ({pending['error']}).", AUTH)
61
+ device_code = str(pending.get("device_code") or "")
62
+ user_code = str(pending.get("user_code") or "")
63
+ if not device_code or not user_code:
64
+ raise CliError("GitHub did not return a device code.", SERVICE)
65
+ uri = str(pending.get("verification_uri") or f"{GITHUB}/login/device")
66
+ complete = pending.get("verification_uri_complete")
67
+ print(f"Open {uri}", file=_err(), flush=True)
68
+ print(f"Enter code {user_code}", file=_err(), flush=True)
69
+ self._open(str(complete or uri))
70
+
71
+ interval = max(1, int(pending.get("interval") or 5))
72
+ deadline = self._now() + int(pending.get("expires_in") or 900)
73
+ token = self._poll(device_code, interval, deadline)
74
+ identity = self.identity(str(token["access_token"]))
75
+ now = self._now()
76
+ return Session(
77
+ access_token=str(token["access_token"]),
78
+ refresh_token=str(token.get("refresh_token") or ""),
79
+ expires_at=now + int(token.get("expires_in") or 0),
80
+ refresh_expires_at=now + int(token.get("refresh_token_expires_in") or 0),
81
+ login=str(identity.get("login") or ""),
82
+ user_id=int(identity.get("id") or 0),
83
+ )
84
+
85
+ def identity(self, access_token: str) -> dict[str, Any]:
86
+ response = self._http.get(
87
+ f"{API}/user",
88
+ headers=self._headers(access_token),
89
+ )
90
+ if response.status_code != 200:
91
+ raise CliError("GitHub rejected the new token.", AUTH)
92
+ body = response.json()
93
+ if not isinstance(body, dict) or "id" not in body:
94
+ raise CliError("GitHub did not identify the authorizing user.", AUTH)
95
+ return body
96
+
97
+ def refresh(self, session: Session) -> Session:
98
+ """Exchange a refresh token.
99
+
100
+ GitHub does not require the client secret for a token that came from
101
+ the device flow, so the distributed client refreshes on its own.
102
+ """
103
+ if not session.refresh_token:
104
+ raise CliError("The GitHub session expired. Run bluethroat auth login.", AUTH)
105
+ if session.refresh_expires_at and self._now() >= session.refresh_expires_at:
106
+ raise CliError("The GitHub session expired. Run bluethroat auth login.", AUTH)
107
+ fields = {
108
+ "client_id": self._client_id,
109
+ "grant_type": "refresh_token",
110
+ "refresh_token": session.refresh_token,
111
+ }
112
+ if self._client_secret:
113
+ fields["client_secret"] = self._client_secret
114
+ token = self._post_form(f"{GITHUB}/login/oauth/access_token", fields)
115
+ if token.get("error"):
116
+ raise CliError("The GitHub session expired. Run bluethroat auth login.", AUTH)
117
+ identity = self.identity(str(token["access_token"]))
118
+ now = self._now()
119
+ return Session(
120
+ access_token=str(token["access_token"]),
121
+ refresh_token=str(token.get("refresh_token") or session.refresh_token),
122
+ expires_at=now + int(token.get("expires_in") or 0),
123
+ refresh_expires_at=now + int(token.get("refresh_token_expires_in") or 0),
124
+ login=str(identity.get("login") or session.login),
125
+ user_id=int(identity.get("id") or session.user_id),
126
+ )
127
+
128
+ def revoke(self, session: Session) -> None:
129
+ """Revoke the user token when a client secret is configured.
130
+
131
+ GitHub's revocation endpoint authenticates with the app's client id and
132
+ secret. Without the secret the local session is still discarded.
133
+ """
134
+ if not self._client_secret:
135
+ return
136
+ for token in (session.access_token, session.refresh_token):
137
+ if not token:
138
+ continue
139
+ response = self._http.request(
140
+ "DELETE",
141
+ f"{API}/applications/{self._client_id}/token",
142
+ auth=(self._client_id, self._client_secret),
143
+ headers={
144
+ "Accept": "application/vnd.github+json",
145
+ "X-GitHub-Api-Version": _API_VERSION,
146
+ },
147
+ json={"access_token": token},
148
+ )
149
+ if response.status_code not in (204, 404):
150
+ raise CliError(
151
+ "The local session was removed, but GitHub did not revoke the token. "
152
+ "Revoke Bluethroat under GitHub Settings → Applications.",
153
+ SERVICE,
154
+ )
155
+
156
+ def ensure(self, session: Session) -> Session:
157
+ """Return a session whose access token is still valid."""
158
+ if self._now() + 30 < session.expires_at:
159
+ return session
160
+ return self.refresh(session)
161
+
162
+ def _poll(self, device_code: str, interval: int, deadline: float) -> dict[str, Any]:
163
+ while self._now() < deadline:
164
+ self._sleep(interval)
165
+ body = self._post_form(
166
+ f"{GITHUB}/login/oauth/access_token",
167
+ {
168
+ "client_id": self._client_id,
169
+ "device_code": device_code,
170
+ "grant_type": _DEVICE_GRANT,
171
+ },
172
+ )
173
+ error = str(body.get("error") or "")
174
+ if not error and body.get("access_token"):
175
+ return body
176
+ if error == "authorization_pending":
177
+ continue
178
+ if error == "slow_down":
179
+ interval += 5
180
+ continue
181
+ if error == "access_denied":
182
+ raise CliError("GitHub authorization was cancelled.", AUTH)
183
+ if error in {"expired_token", "token_expired"}:
184
+ break
185
+ raise CliError(f"GitHub login failed ({error or 'unknown error'}).", AUTH)
186
+ raise CliError("The GitHub code expired. Run bluethroat auth login again.", AUTH)
187
+
188
+ def _post_form(self, url: str, fields: dict[str, str]) -> dict[str, Any]:
189
+ try:
190
+ response = self._http.post(
191
+ url,
192
+ data=fields,
193
+ headers={"Accept": "application/json", "User-Agent": "bluethroat"},
194
+ )
195
+ except httpx.HTTPError as exc:
196
+ raise CliError(f"Could not reach GitHub ({exc.__class__.__name__}).", SERVICE) from exc
197
+ try:
198
+ body = response.json()
199
+ except json.JSONDecodeError:
200
+ body = None
201
+ if not isinstance(body, dict):
202
+ raise CliError(f"GitHub returned HTTP {response.status_code}.", SERVICE)
203
+ if response.status_code >= 400 and not body.get("error"):
204
+ raise CliError(f"GitHub returned HTTP {response.status_code}.", SERVICE)
205
+ return body
206
+
207
+ @staticmethod
208
+ def _headers(access_token: str) -> dict[str, str]:
209
+ return {
210
+ "Accept": "application/vnd.github+json",
211
+ "Authorization": f"Bearer {access_token}",
212
+ "X-GitHub-Api-Version": _API_VERSION,
213
+ "User-Agent": "bluethroat",
214
+ }
215
+
216
+
217
+ def _err():
218
+ import sys
219
+
220
+ return sys.stderr
@@ -0,0 +1,195 @@
1
+ """Text rendering of a BlueSkills scan document.
2
+
3
+ The JSON from ``POST /scan.json`` and the JSON from ``GET /scans/{id}`` use
4
+ different envelopes. Both become the same text report.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ _ICONS = {
10
+ "clean": "✓",
11
+ "suspicious": "⚠",
12
+ "malicious": "✗",
13
+ "partial": "◐",
14
+ "invalid": "⊘",
15
+ "error": "✗",
16
+ }
17
+ _SEVERITY = {
18
+ "critical": "CRIT",
19
+ "high": "HIGH",
20
+ "medium": "MED",
21
+ "low": "LOW",
22
+ "info": "INFO",
23
+ }
24
+
25
+
26
+ def outcome(doc: dict) -> tuple[str, bool]:
27
+ """Headline verdict and whether the scan is a complete result."""
28
+ units = _units(doc)
29
+ verdict = _headline(doc, units)
30
+ if str(doc.get("status") or "") == "failed" or verdict == "error":
31
+ return verdict or "error", False
32
+ complete = True
33
+ if doc.get("complete") is False or doc.get("truncated") or doc.get("deadline_skipped"):
34
+ complete = False
35
+ if verdict in {"partial", "invalid"}:
36
+ complete = False
37
+ for unit in units:
38
+ stats = unit.get("stats")
39
+ if isinstance(stats, dict) and stats.get("incomplete"):
40
+ complete = False
41
+ return verdict, complete
42
+
43
+
44
+ def render(doc: dict) -> str:
45
+ units = _units(doc)
46
+ verdict = _headline(doc, units)
47
+ lines: list[str] = []
48
+ score = _headline_score(doc, units, verdict)
49
+ lines.append(_headline_line(doc, verdict, score, several=len(units) > 1))
50
+ commit = _commit(doc)
51
+ if commit:
52
+ lines.append(f" commit: {_plain(commit)}")
53
+ source = _source(doc)
54
+ if source:
55
+ lines.append(f" source: {_plain(source)}")
56
+ if doc.get("truncated"):
57
+ lines.append(" ⚠ the package has more skills than this scan covered")
58
+ if len(units) > 1:
59
+ lines.append(f" {len(units)} skills scanned. Review every block below.")
60
+ if len(units) == 1:
61
+ lines.extend(_unit_body(units[0], header=False))
62
+ else:
63
+ ordered = sorted(
64
+ units,
65
+ key=lambda unit: (
66
+ -_rank(str(unit.get("verdict") or "")),
67
+ str(unit.get("skill_name") or ""),
68
+ ),
69
+ )
70
+ for unit in ordered:
71
+ lines.append("")
72
+ lines.extend(_unit_body(unit, header=True))
73
+ return "\n".join(lines)
74
+
75
+
76
+ def _units(doc: dict) -> list[dict]:
77
+ reports = doc.get("reports")
78
+ if isinstance(reports, list) and reports:
79
+ return [item for item in reports if isinstance(item, dict)]
80
+ if "verdict" in doc:
81
+ return [doc]
82
+ return []
83
+
84
+
85
+ def _headline(doc: dict, units: list[dict]) -> str:
86
+ for key in ("worst_verdict", "verdict"):
87
+ value = doc.get(key)
88
+ if isinstance(value, str) and value:
89
+ return value.lower()
90
+ if not units:
91
+ return "error"
92
+ return max((str(unit.get("verdict") or "clean") for unit in units), key=_rank).lower()
93
+
94
+
95
+ def _headline_score(doc: dict, units: list[dict], verdict: str) -> int | None:
96
+ if verdict in {"invalid", "error"}:
97
+ return None
98
+ if "score" in doc and "worst_verdict" not in doc:
99
+ score = doc.get("score")
100
+ return int(score) if isinstance(score, int) else None
101
+ scores = [
102
+ int(unit["risk_score"])
103
+ for unit in units
104
+ if str(unit.get("verdict") or "").lower() == verdict and isinstance(unit.get("risk_score"), int)
105
+ ]
106
+ if scores:
107
+ return max(scores)
108
+ for unit in units:
109
+ if isinstance(unit.get("risk_score"), int):
110
+ return int(unit["risk_score"])
111
+ return None
112
+
113
+
114
+ def _headline_line(doc: dict, verdict: str, score: int | None, *, several: bool) -> str:
115
+ icon = _ICONS.get(verdict, "?")
116
+ name = _plain(str(_source(doc) or doc.get("slug") or "scan"))
117
+ label = verdict.upper()
118
+ if several:
119
+ label = f"headline {label}"
120
+ if verdict == "partial" and score is not None:
121
+ return f"{icon} {name} — PARTIAL (observed risk {score}/100; CLEAN unreachable)"
122
+ if score is None:
123
+ reason = _plain(str(doc.get("error") or verdict))
124
+ return f"{icon} {name} — {label} — not scored ({reason})"
125
+ return f"{icon} {name} — {label} (risk {score}/100)"
126
+
127
+
128
+ def _unit_body(unit: dict, *, header: bool) -> list[str]:
129
+ lines: list[str] = []
130
+ verdict = str(unit.get("verdict") or "").lower()
131
+ if header:
132
+ score = unit.get("risk_score")
133
+ shown = f"{score}/100" if isinstance(score, int) else "not scored"
134
+ name = _plain(str(unit.get("skill") or unit.get("skill_name") or "skill"))
135
+ lines.append(f"{_ICONS.get(verdict, '?')} {name} — {verdict.upper()} (risk {shown})")
136
+ stats = unit.get("stats") if isinstance(unit.get("stats"), dict) else {}
137
+ if stats.get("incomplete") or unit.get("complete") is False:
138
+ missing = stats.get("missing_layers")
139
+ detail = ", ".join(missing) if isinstance(missing, list) and missing else "a detection layer"
140
+ lines.append(f" ⚠ INCOMPLETE SCAN — {_plain(detail)} did not run")
141
+ layers = unit.get("layers_run")
142
+ if isinstance(layers, list) and layers:
143
+ lines.append(f" layers: {_plain(', '.join(str(item) for item in layers))}")
144
+ findings = [item for item in unit.get("findings") or [] if isinstance(item, dict)]
145
+ lines.append(f" findings: {len(findings)}")
146
+ for finding in findings:
147
+ severity = _SEVERITY.get(str(finding.get("severity") or "").lower(), "INFO")
148
+ title = _plain(str(finding.get("title") or finding.get("message") or "Finding"))
149
+ layer = _plain(str(finding.get("layer") or ""))
150
+ where = _plain(str(finding.get("file") or "(skill)"))
151
+ if finding.get("line"):
152
+ where += f":{finding['line']}"
153
+ detail = _plain(str(finding.get("detail") or ""))
154
+ lines.append(f" [{severity}] {title} ({layer})")
155
+ lines.append(f" {where} — {detail}")
156
+ if finding.get("evidence"):
157
+ lines.append(f" evidence: {_plain(str(finding['evidence']))}")
158
+ return lines
159
+
160
+
161
+ def _source(doc: dict) -> str:
162
+ raw = doc.get("source")
163
+ if isinstance(raw, str) and raw:
164
+ return raw
165
+ entered = doc.get("input")
166
+ if isinstance(entered, dict) and isinstance(entered.get("source"), str):
167
+ return str(entered["source"])
168
+ return ""
169
+
170
+
171
+ def _commit(doc: dict) -> str:
172
+ if isinstance(doc.get("commit"), str):
173
+ return str(doc["commit"])
174
+ entered = doc.get("input")
175
+ if isinstance(entered, dict) and isinstance(entered.get("commit"), str):
176
+ return str(entered["commit"])
177
+ return ""
178
+
179
+
180
+ def _rank(verdict: str) -> int:
181
+ return {
182
+ "clean": 0,
183
+ "suspicious": 1,
184
+ "partial": 2,
185
+ "malicious": 3,
186
+ "invalid": 4,
187
+ "error": 5,
188
+ }.get(verdict.lower(), 0)
189
+
190
+
191
+ def _plain(text: str) -> str:
192
+ flattened = " ".join(text.split())
193
+ if len(flattened) > 400:
194
+ return flattened[:399] + "…"
195
+ return flattened