Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/deployment_checks.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
deployment_checks.py · 14.2 KB · 402 lines
1"""Deployment checks for the conservative single-VM layout."""
2from __future__ import annotations
3
4import argparse
5import grp
6import json
7import os
8import pwd
9import stat
10from dataclasses import asdict, dataclass
11from datetime import datetime, timedelta, timezone
12from pathlib import Path
13from typing import Literal
14
15import object_record_changes
16
17DEFAULT_CODE_DIR = Path("/opt/dbbasic-object-server")
18DEFAULT_OBJECTS_DIR = Path("/var/lib/dbbasic-object-server/objects")
19DEFAULT_DATA_DIR = Path("/var/lib/dbbasic-object-server/data")
20DEFAULT_ENV_FILE = Path("/etc/dbbasic-object-server.env")
21DEFAULT_SERVICE_FILE = Path("/etc/systemd/system/dbbasic-object-server.service")
22DEFAULT_JOURNALD_DROPIN = Path("/etc/systemd/journald.conf.d/99-dbbasic.conf")
23DEFAULT_SERVICE_USER = "dbbasic"
24DEFAULT_SERVICE_GROUP = "dbbasic"
25UNATTRIBUTED_ACTOR = "unattributed"
26DEFAULT_UNATTRIBUTED_WINDOW_HOURS = 24
27
28Status = Literal["ok", "warning", "error"]
29
30
31@dataclass(frozen=True)
32class CheckResult:
33 name: str
34 path: str
35 status: Status
36 message: str
37
38
39def check_single_vm_layout(
40 *,
41 code_dir: Path | str = DEFAULT_CODE_DIR,
42 objects_dir: Path | str | None = None,
43 data_dir: Path | str | None = None,
44 env_file: Path | str = DEFAULT_ENV_FILE,
45 service_file: Path | str = DEFAULT_SERVICE_FILE,
46 journald_dropin: Path | str = DEFAULT_JOURNALD_DROPIN,
47 service_user: str = DEFAULT_SERVICE_USER,
48 service_group: str = DEFAULT_SERVICE_GROUP,
49 env_owner: str = "root",
50 system_owner: str = "root",
51 system_group: str = "root",
52) -> list[CheckResult]:
53 """Return filesystem placement and permission checks for one VM."""
54 objects_path = Path(
55 objects_dir
56 if objects_dir is not None
57 else os.environ.get("DBBASIC_OBJECTS_DIR", DEFAULT_OBJECTS_DIR)
58 )
59 data_path = Path(
60 data_dir if data_dir is not None else os.environ.get("DBBASIC_DATA_DIR", DEFAULT_DATA_DIR)
61 )
62
63 results: list[CheckResult] = []
64 results.extend(
65 _check_service_directory(
66 "code directory",
67 Path(code_dir),
68 expected_user=service_user,
69 expected_group=service_group,
70 private_runtime=False,
71 )
72 )
73 results.extend(
74 _check_service_directory(
75 "object source directory",
76 objects_path,
77 expected_user=service_user,
78 expected_group=service_group,
79 private_runtime=True,
80 )
81 )
82 results.extend(
83 _check_service_directory(
84 "data directory",
85 data_path,
86 expected_user=service_user,
87 expected_group=service_group,
88 private_runtime=True,
89 )
90 )
91 results.extend(_check_env_file(Path(env_file), expected_owner=env_owner, expected_group=service_group))
92 results.extend(
93 _check_service_file(
94 Path(service_file),
95 expected_owner=system_owner,
96 expected_group=system_group,
97 )
98 )
99 results.extend(
100 _check_journald_dropin(
101 Path(journald_dropin),
102 expected_owner=system_owner,
103 expected_group=system_group,
104 )
105 )
106 return results
107
108
109def has_errors(results: list[CheckResult]) -> bool:
110 return any(result.status == "error" for result in results)
111
112
113def check_unattributed_record_changes(
114 *,
115 data_dir: Path | str | None = None,
116 window_hours: int = DEFAULT_UNATTRIBUTED_WINDOW_HOURS,
117) -> list[CheckResult]:
118 """Count recent record changes with no real actor, and warn (never fail).
119
120 Universal attribution defaults an un-actored write to "unattributed"
121 rather than skipping it (see object_records.create/update/delete_
122 collection_record), so writes never go missing -- but a growing count
123 here means some caller still isn't passing its own actor through.
124 This is visibility, not enforcement: it always reports "warning", so
125 it can be tightened to fail-closed later once callers are cleaned up.
126 """
127 name = "record change attribution"
128 data_path = Path(
129 data_dir if data_dir is not None else os.environ.get("DBBASIC_DATA_DIR", DEFAULT_DATA_DIR)
130 )
131 root = data_path / object_record_changes.RECORD_CHANGES_DIR
132 if not root.is_dir():
133 return [_result(name, root, "ok", "no record change log yet")]
134
135 cutoff = datetime.now(timezone.utc) - timedelta(hours=window_hours)
136 unattributed_by_collection: dict[str, int] = {}
137 total = 0
138
139 for changes_file in sorted(root.glob(f"*/{object_record_changes.CHANGES_FILE}")):
140 collection = changes_file.parent.name
141 for line in changes_file.read_text(encoding="utf-8", errors="replace").splitlines():
142 if not line.strip():
143 continue
144 try:
145 entry = json.loads(line)
146 except json.JSONDecodeError:
147 continue
148 if not isinstance(entry, dict) or entry.get("actor") != UNATTRIBUTED_ACTOR:
149 continue
150 if not _within_window(entry.get("timestamp"), cutoff):
151 continue
152 total += 1
153 unattributed_by_collection[collection] = unattributed_by_collection.get(collection, 0) + 1
154
155 if total == 0:
156 return [_result(name, root, "ok", f"no unattributed record changes in the last {window_hours}h")]
157
158 top = ", ".join(
159 f"{collection}={count}"
160 for collection, count in sorted(unattributed_by_collection.items(), key=lambda item: -item[1])[:5]
161 )
162 return [
163 _result(
164 name,
165 root,
166 "warning",
167 f"{total} unattributed record change(s) in the last {window_hours}h ({top})",
168 )
169 ]
170
171
172def _within_window(timestamp: object, cutoff: datetime) -> bool:
173 if not isinstance(timestamp, str):
174 return False
175 try:
176 parsed = datetime.fromisoformat(timestamp)
177 except ValueError:
178 return False
179 if parsed.tzinfo is None:
180 parsed = parsed.replace(tzinfo=timezone.utc)
181 return parsed >= cutoff
182
183
184def _check_service_directory(
185 name: str,
186 path: Path,
187 *,
188 expected_user: str,
189 expected_group: str,
190 private_runtime: bool,
191) -> list[CheckResult]:
192 if not path.exists():
193 return [_result(name, path, "error", "missing")]
194 if not path.is_dir():
195 return [_result(name, path, "error", "not a directory")]
196
197 results = _check_owner(path, name, expected_user, expected_group)
198 mode = stat.S_IMODE(path.stat().st_mode)
199
200 if not mode & stat.S_IRUSR or not mode & stat.S_IWUSR or not mode & stat.S_IXUSR:
201 results.append(_result(name, path, "error", f"owner needs rwx permissions, mode is {_mode(mode)}"))
202
203 if mode & stat.S_IWGRP or mode & stat.S_IWOTH:
204 results.append(_result(name, path, "error", f"group/world writable, mode is {_mode(mode)}"))
205
206 if private_runtime and mode & (stat.S_IROTH | stat.S_IXOTH):
207 results.append(
208 _result(
209 name,
210 path,
211 "warning",
212 f"runtime path is visible to other local users, mode is {_mode(mode)}",
213 )
214 )
215
216 if not results:
217 results.append(_result(name, path, "ok", f"directory mode {_mode(mode)}"))
218 return results
219
220
221def _check_env_file(path: Path, *, expected_owner: str, expected_group: str) -> list[CheckResult]:
222 name = "environment file"
223 if not path.exists():
224 return [_result(name, path, "error", "missing")]
225 if not path.is_file():
226 return [_result(name, path, "error", "not a file")]
227
228 results: list[CheckResult] = []
229 owner, group = _owner_group(path)
230 mode = stat.S_IMODE(path.stat().st_mode)
231
232 if owner != expected_owner:
233 results.append(_result(name, path, "error", f"expected owner {expected_owner}, found {owner}"))
234 if group not in {"root", expected_group}:
235 results.append(
236 _result(name, path, "warning", f"expected group root or {expected_group}, found {group}")
237 )
238 if mode & stat.S_IWGRP or mode & stat.S_IRWXO:
239 results.append(
240 _result(name, path, "error", f"too permissive for deployment secrets, mode is {_mode(mode)}")
241 )
242 if mode & (stat.S_IXUSR | stat.S_IXGRP):
243 results.append(_result(name, path, "warning", f"environment file is executable, mode is {_mode(mode)}"))
244
245 if not results:
246 results.append(_result(name, path, "ok", f"file mode {_mode(mode)}"))
247 return results
248
249
250def _check_service_file(path: Path, *, expected_owner: str, expected_group: str) -> list[CheckResult]:
251 name = "systemd service file"
252 if not path.exists():
253 return [_result(name, path, "error", "missing")]
254 if not path.is_file():
255 return [_result(name, path, "error", "not a file")]
256
257 results: list[CheckResult] = []
258 owner, group = _owner_group(path)
259 mode = stat.S_IMODE(path.stat().st_mode)
260
261 if owner != expected_owner:
262 results.append(_result(name, path, "error", f"expected owner {expected_owner}, found {owner}"))
263 if group != expected_group:
264 results.append(_result(name, path, "warning", f"expected group {expected_group}, found {group}"))
265 if mode & stat.S_IWGRP or mode & stat.S_IWOTH:
266 results.append(_result(name, path, "error", f"group/world writable, mode is {_mode(mode)}"))
267
268 content = path.read_text(errors="replace")
269 if "ExecStart=" in content and "uvicorn" in content and "--no-access-log" not in content:
270 results.append(
271 _result(
272 name,
273 path,
274 "warning",
275 "uvicorn access logs are enabled; add --no-access-log and rely on object logs plus metrics",
276 )
277 )
278
279 if not results:
280 results.append(_result(name, path, "ok", f"file mode {_mode(mode)}"))
281 return results
282
283
284def _check_journald_dropin(
285 path: Path,
286 *,
287 expected_owner: str,
288 expected_group: str,
289) -> list[CheckResult]:
290 name = "journald retention drop-in"
291 if not path.exists():
292 return [_result(name, path, "warning", "missing; journald may keep unbounded process logs")]
293 if not path.is_file():
294 return [_result(name, path, "error", "not a file")]
295
296 results: list[CheckResult] = []
297 owner, group = _owner_group(path)
298 mode = stat.S_IMODE(path.stat().st_mode)
299 content = path.read_text(errors="replace")
300
301 if owner != expected_owner:
302 results.append(_result(name, path, "error", f"expected owner {expected_owner}, found {owner}"))
303 if group != expected_group:
304 results.append(_result(name, path, "warning", f"expected group {expected_group}, found {group}"))
305 if mode & stat.S_IWGRP or mode & stat.S_IWOTH:
306 results.append(_result(name, path, "error", f"group/world writable, mode is {_mode(mode)}"))
307 if "[Journal]" not in content:
308 results.append(_result(name, path, "warning", "missing [Journal] section"))
309 if "SystemMaxUse=" not in content and "RuntimeMaxUse=" not in content:
310 results.append(_result(name, path, "warning", "missing journal size cap"))
311 if "MaxRetentionSec=" not in content:
312 results.append(_result(name, path, "warning", "missing journal age retention cap"))
313
314 if not results:
315 results.append(_result(name, path, "ok", f"file mode {_mode(mode)}"))
316 return results
317
318
319def _check_owner(path: Path, name: str, expected_user: str, expected_group: str) -> list[CheckResult]:
320 owner, group = _owner_group(path)
321 results: list[CheckResult] = []
322 if owner != expected_user:
323 results.append(_result(name, path, "error", f"expected owner {expected_user}, found {owner}"))
324 if group != expected_group:
325 results.append(_result(name, path, "error", f"expected group {expected_group}, found {group}"))
326 return results
327
328
329def _owner_group(path: Path) -> tuple[str, str]:
330 info = path.stat()
331 try:
332 owner = pwd.getpwuid(info.st_uid).pw_name
333 except KeyError:
334 owner = str(info.st_uid)
335 try:
336 group = grp.getgrgid(info.st_gid).gr_name
337 except KeyError:
338 group = str(info.st_gid)
339 return owner, group
340
341
342def _result(name: str, path: Path, status: Status, message: str) -> CheckResult:
343 return CheckResult(name=name, path=str(path), status=status, message=message)
344
345
346def _mode(mode: int) -> str:
347 return format(mode, "04o")
348
349
350def main(argv: list[str] | None = None) -> int:
351 parser = argparse.ArgumentParser(description="Check DBBASIC single-VM filesystem layout.")
352 parser.add_argument("--code-dir", type=Path, default=DEFAULT_CODE_DIR)
353 parser.add_argument("--objects-dir", type=Path)
354 parser.add_argument("--data-dir", type=Path)
355 parser.add_argument("--env-file", type=Path, default=DEFAULT_ENV_FILE)
356 parser.add_argument("--service-file", type=Path, default=DEFAULT_SERVICE_FILE)
357 parser.add_argument("--journald-dropin", type=Path, default=DEFAULT_JOURNALD_DROPIN)
358 parser.add_argument("--service-user", default=DEFAULT_SERVICE_USER)
359 parser.add_argument("--service-group", default=DEFAULT_SERVICE_GROUP)
360 parser.add_argument("--env-owner", default="root")
361 parser.add_argument("--system-owner", default="root")
362 parser.add_argument("--system-group", default="root")
363 parser.add_argument(
364 "--unattributed-window-hours",
365 type=int,
366 default=DEFAULT_UNATTRIBUTED_WINDOW_HOURS,
367 help="lookback window for the unattributed record-change count",
368 )
369 parser.add_argument("--json", action="store_true", help="print machine-readable JSON")
370 args = parser.parse_args(argv)
371
372 results = check_single_vm_layout(
373 code_dir=args.code_dir,
374 objects_dir=args.objects_dir,
375 data_dir=args.data_dir,
376 env_file=args.env_file,
377 service_file=args.service_file,
378 journald_dropin=args.journald_dropin,
379 service_user=args.service_user,
380 service_group=args.service_group,
381 env_owner=args.env_owner,
382 system_owner=args.system_owner,
383 system_group=args.system_group,
384 )
385 results.extend(
386 check_unattributed_record_changes(
387 data_dir=args.data_dir,
388 window_hours=args.unattributed_window_hours,
389 )
390 )
391
392 if args.json:
393 print(json.dumps([asdict(result) for result in results], indent=2))
394 else:
395 for result in results:
396 print(f"{result.status.upper():7} {result.name}: {result.path} - {result.message}")
397
398 return 1 if has_errors(results) else 0
399
400
401if __name__ == "__main__":
402 raise SystemExit(main())