bluethroat 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.
- bluethroat/__init__.py +3 -0
- bluethroat/api.py +254 -0
- bluethroat/cli.py +202 -0
- bluethroat/config.py +63 -0
- bluethroat/credentials.py +151 -0
- bluethroat/errors.py +41 -0
- bluethroat/github_auth.py +220 -0
- bluethroat/report.py +195 -0
- bluethroat-0.1.0.dist-info/METADATA +36 -0
- bluethroat-0.1.0.dist-info/RECORD +12 -0
- bluethroat-0.1.0.dist-info/WHEEL +4 -0
- bluethroat-0.1.0.dist-info/entry_points.txt +3 -0
bluethroat/__init__.py
ADDED
bluethroat/api.py
ADDED
|
@@ -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
|
bluethroat/cli.py
ADDED
|
@@ -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())
|
bluethroat/config.py
ADDED
|
@@ -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)
|
bluethroat/errors.py
ADDED
|
@@ -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
|
bluethroat/report.py
ADDED
|
@@ -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
|
|
@@ -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,12 @@
|
|
|
1
|
+
bluethroat/__init__.py,sha256=Mfn-hXycfe_rR5Mrpe2IHjssYJKESvmLDOvjPBhVics,65
|
|
2
|
+
bluethroat/api.py,sha256=Gzk_Jcsz-PfDLo7RWJ1y35GQI5JEI1CFNRSpdsOY1FI,9214
|
|
3
|
+
bluethroat/cli.py,sha256=16WbYg0bdfZvRF3bBXO3JQA8CC7WOiRFlT6CuPZ5nxc,6697
|
|
4
|
+
bluethroat/config.py,sha256=UzzeKsKkqu2l0-NRyGZsEOdlKuKWE-krOBpFRx745Mg,1971
|
|
5
|
+
bluethroat/credentials.py,sha256=z4yQiV-2fszrqyQtn1vhDvxCeR-dIz94eDyxfStVJi8,3675
|
|
6
|
+
bluethroat/errors.py,sha256=Swgd-7wnveMUGmbKQeXly8jOpCyAUeNWx40kZO6Rrmc,980
|
|
7
|
+
bluethroat/github_auth.py,sha256=Eld2Uykm2DoAvBMWgfumOxFvWl18V6jOv6uwhsKR8bo,8811
|
|
8
|
+
bluethroat/report.py,sha256=EOqCP-XYqgAk7k0TvBO5wkXI6qkVGmHdzTPIMe8F92w,6842
|
|
9
|
+
bluethroat-0.1.0.dist-info/WHEEL,sha256=-i9oRNYVXXZJUIYl5zclLIg6onEb0NLibTX34uln84w,81
|
|
10
|
+
bluethroat-0.1.0.dist-info/entry_points.txt,sha256=EbSa_ToN1d2dJFe0u-KqLyRGKzJiOATnL_rLk9xP5fE,52
|
|
11
|
+
bluethroat-0.1.0.dist-info/METADATA,sha256=7k4-GMwIrZqOacIvveGdT4Za2KZ9D-nkNdFXJR5Ni8k,1837
|
|
12
|
+
bluethroat-0.1.0.dist-info/RECORD,,
|