diff --git a/README.md b/README.md index fe6c648..0e21949 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,21 @@ uv run python -m otter.cli revoke-token push `tools/push.sh` sends `$OTTER_TOKEN` when it is set. Other commands: `set-password` (closes the user's sessions), `list-users`, `delete-user`. +**Roles**: an account is `admin` (the default) or `viewer`, which sees everything and changes +nothing (it may still watch a device's live logs). The server refuses a viewer's changes and the +dashboard hides their controls. API tokens act with their account's role, so a monitoring token +can belong to a viewer. + +```sh +uv run python -m otter.cli create-user alice --role viewer +uv run python -m otter.cli set-role alice admin +``` + +**Activity**: every change made in the dashboard or through the API (deployments, uploads, +commands, configuration, tags, access…) is logged with who made it, when, and whether it went +through; **Activity** in the dashboard's header shows it. Command arguments and configuration +values stay out of it, as they may be secret. Kept 90 days. + Passwords are hashed with argon2; sessions and tokens are stored as SHA-256 hashes only. Logins are limited to 10 failures per address every 5 minutes. **Serve Otter over HTTPS as soon as it leaves your desk**: over plain HTTP, passwords and cookies can be sniffed on the network (see [HTTPS](#https)). diff --git a/server/otter/api_auth.py b/server/otter/api_auth.py index 445ab8f..1e04c44 100644 --- a/server/otter/api_auth.py +++ b/server/otter/api_auth.py @@ -22,7 +22,7 @@ def status(request: Request): user, _ = auth.current_user(request) with SessionLocal() as session: has_users = session.scalar(select(func.count(User.id))) > 0 - return {"user": user.username if user else None, "has_users": has_users} + return {"user": user.username if user else None, "role": user.role if user else None, "has_users": has_users} @router.post("/login") diff --git a/server/otter/api_rollouts.py b/server/otter/api_rollouts.py index 6b65571..f1ec8d4 100644 --- a/server/otter/api_rollouts.py +++ b/server/otter/api_rollouts.py @@ -3,12 +3,13 @@ import json from datetime import timedelta -from fastapi import APIRouter, Depends, HTTPException +from fastapi import APIRouter, Depends, HTTPException, Request from sqlalchemy import select from sqlalchemy.orm import Session, selectinload from . import channels, rollouts from .api_device import publish_device +from .audit import describe from .auth import require_user from .db import SessionLocal, get_session from .events import broadcaster, wakeups @@ -77,10 +78,12 @@ def list_rollouts(limit: int = 20, session: Session = Depends(get_session)): @router.post("/rollouts", response_model=RolloutOut, status_code=201) -def create_rollout(body: RolloutIn, session: Session = Depends(get_session)): +def create_rollout(body: RolloutIn, request: Request, session: Session = Depends(get_session)): fw = session.get(Firmware, body.firmware_id) if fw is None: raise HTTPException(404, "unknown firmware") + target = (f"channel {body.channel}" if body.channel else " ".join(f"#{t}" for t in body.tags) or "every device") + describe(request, f"started a staged rollout of {fw.app} {fw.version} to {target} ({', '.join(f'{s} %' for s in body.stages)})") try: rollout, changes = rollouts.create( session, fw, sorted(set(body.tags)), body.stages, body.soak_s, body.max_failure_rate, body.channel @@ -103,12 +106,14 @@ def create_rollout(body: RolloutIn, session: Session = Depends(get_session)): @router.post("/rollouts/{rollout_id}/{action}", response_model=RolloutOut) -def rollout_action(rollout_id: int, action: str, session: Session = Depends(get_session)): +def rollout_action(rollout_id: int, action: str, request: Request, session: Session = Depends(get_session)): if action not in ACTIONS: raise HTTPException(404, f"unknown action {action}") rollout = session.get(Rollout, rollout_id) if rollout is None: raise HTTPException(404, "unknown rollout") + done = {"pause": "paused", "resume": "resumed", "advance": "moved to the next stage", "abort": "aborted"}[action] + describe(request, f"{done}: the rollout of {rollout.firmware.app} {rollout.firmware.version}") try: changes = ACTIONS[action](rollout) except rollouts.RolloutError as exc: diff --git a/server/otter/api_ui.py b/server/otter/api_ui.py index 6a89c24..3cd0806 100644 --- a/server/otter/api_ui.py +++ b/server/otter/api_ui.py @@ -10,7 +10,8 @@ from sqlalchemy.exc import IntegrityError from sqlalchemy.orm import Session, selectinload -from . import commands, config, crashes, devconfig, history, signing +from . import audit, commands, config, crashes, devconfig, history, signing +from .audit import describe from .api_device import publish_device from .api_rollouts import reconcile_channels from .auth import require_user @@ -106,9 +107,10 @@ def get_device_config(device_id: int, session: Session = Depends(get_session)): @router.put("/devices/{device_id}/config", response_model=ConfigOut) -def put_device_config(device_id: int, body: ConfigIn, session: Session = Depends(get_session)): +def put_device_config(device_id: int, body: ConfigIn, request: Request, session: Session = Depends(get_session)): """Replaces the device's own values (its tags' values still apply underneath).""" device = session.get(Device, device_id) or _404("device") + describe(request, f"set the configuration of {who(device)}: {keys(body.values)}") devconfig.replace(session, body.values, device=device) session.commit() push_config([device]) @@ -121,21 +123,49 @@ def get_tag_config(name: TagName, session: Session = Depends(get_session)): @router.put("/tags/{name}/config", response_model=ConfigOut) -def put_tag_config(name: TagName, body: ConfigIn, session: Session = Depends(get_session)): +def put_tag_config(name: TagName, body: ConfigIn, request: Request, session: Session = Depends(get_session)): """Replaces the tag's values: every device with the tag gets them, unless it overrides them.""" + describe(request, f"set the configuration of #{name}: {keys(body.values)}") devconfig.replace(session, body.values, tag=name) session.commit() push_config(devconfig.devices_of_tag(session, name)) return ConfigOut(values=devconfig.scope_values(session, tag=name)) +# --- Activity log (#100, see audit.py) ----------------------------------------- + + +def who(device: Device) -> str: + return device.name or device.mac + + +def device_names(devices, most: int = 3) -> str: + shown = ", ".join(who(d) for d in list(devices)[:most]) + return shown + (f" and {len(devices) - most} more" if len(devices) > most else "") if devices else "no device" + + +def keys(values: dict) -> str: + """The keys only: values may be secret.""" + return ", ".join(sorted(values)) or "(empty)" + + +@router.get("/audit") +def audit_log(limit: int = Query(200, ge=1, le=1000)): + return [ + {"at": e.at.replace(tzinfo=UTC).isoformat(), "user": e.username, "via_token": e.via_token, "text": e.text, + "status": e.status, "method": e.method, "path": e.path} + for e in audit.recent(limit) + ] + + # --- Device credentials (#15, see device_auth.py) --------------------------- @router.post("/devices/{device_id}/revoke", response_model=DeviceOut) -def revoke_device(device_id: int, session: Session = Depends(get_session)): +def revoke_device(device_id: int, request: Request, session: Session = Depends(get_session)): """Blocks the device, with its token or the fleet key, until it is re-enrolled.""" device = session.get(Device, device_id) or _404("device") + describe(request, f"revoked {who(device)}") device.revoked_at = utcnow() device.token_hash = None session.commit() @@ -145,9 +175,10 @@ def revoke_device(device_id: int, session: Session = Depends(get_session)): @router.post("/devices/{device_id}/reenroll", response_model=DeviceOut) -def reenroll_device(device_id: int, session: Session = Depends(get_session)): +def reenroll_device(device_id: int, request: Request, session: Session = Depends(get_session)): """Forgets the device's token: its next check-in with the fleet key gets a new one.""" device = session.get(Device, device_id) or _404("device") + describe(request, f"re-enrolled {who(device)}") device.revoked_at = device.token_used_at = device.token_hash = device.token_lost_at = None device.approved = True session.commit() @@ -156,8 +187,9 @@ def reenroll_device(device_id: int, session: Session = Depends(get_session)): @router.post("/devices/{device_id}/approve", response_model=DeviceOut) -def approve_device(device_id: int, session: Session = Depends(get_session)): +def approve_device(device_id: int, request: Request, session: Session = Depends(get_session)): device = session.get(Device, device_id) or _404("device") + describe(request, f"approved {who(device)}") device.approved = True session.commit() publish_device(device) @@ -173,9 +205,10 @@ def device_commands(device_id: int, limit: int = 20, session: Session = Depends( @router.post("/commands", response_model=list[CommandOut], status_code=201) -def send_commands(body: CommandIn, session: Session = Depends(get_session)): +def send_commands(body: CommandIn, request: Request, session: Session = Depends(get_session)): """Queues a command for each device; long-polling devices get it within a second or two.""" devices = session.scalars(select(Device).where(Device.id.in_(body.device_ids))).all() + describe(request, f"sent {body.name} to {device_names(devices)}") # not its arguments: they may be secret if len(devices) != len(set(body.device_ids)): raise HTTPException(404, "unknown device") queued = [commands.queue(device, body.name, body.args) for device in devices] @@ -187,8 +220,16 @@ def send_commands(body: CommandIn, session: Session = Depends(get_session)): @router.patch("/devices/{device_id}", response_model=DeviceOut) -def patch_device(device_id: int, body: DevicePatch, session: Session = Depends(get_session)): +def patch_device(device_id: int, body: DevicePatch, request: Request, session: Session = Depends(get_session)): device = session.get(Device, device_id) or _404("device") + changes = [] + if "name" in body.model_fields_set: + changes.append(f"renamed it {body.name or '(no name)'}") + if "tags" in body.model_fields_set: + changes.append("tags " + (" ".join(f"#{t}" for t in body.tags or []) or "none")) + if "channel" in body.model_fields_set: + changes.append(f"channel {body.channel or 'none'}") + describe(request, f"changed {who(device)}: {', '.join(changes)}") if "name" in body.model_fields_set: device.name = (body.name or "").strip() or None if "tags" in body.model_fields_set: @@ -231,8 +272,9 @@ def list_tags(session: Session = Depends(get_session)): @router.delete("/devices/{device_id}", status_code=204) -def delete_device(device_id: int, session: Session = Depends(get_session)): +def delete_device(device_id: int, request: Request, session: Session = Depends(get_session)): device = session.get(Device, device_id) or _404("device") + describe(request, f"forgot {who(device)}") session.delete(device) session.flush() delete_unused_tags(session) @@ -300,11 +342,13 @@ def upload_firmware( signature: str | None = Form(default=None, max_length=2048), elf: UploadFile | None = None, factory: UploadFile | None = None, + request: Request = None, session: Session = Depends(get_session), ): """The .bin image, optionally with its signature, the ELF file it was built from (to decode crash reports, see crashes.py) and its factory image (to install it from the browser).""" + describe(request, f"uploaded {app.strip()} {version.strip()} ({hw.strip()})") try: sha, size = store_firmware(file.file) except ValueError as exc: @@ -442,9 +486,11 @@ def device_crashes(device_id: int, limit: int = 20, session: Session = Depends(g @router.patch("/firmwares/{firmware_id}", response_model=FirmwareOut) -def patch_firmware(firmware_id: int, body: FirmwarePatch, session: Session = Depends(get_session)): +def patch_firmware(firmware_id: int, body: FirmwarePatch, request: Request, session: Session = Depends(get_session)): """Publishes the firmware on a release channel: its followers are updated right away.""" fw = session.get(Firmware, firmware_id) or _404("firmware") + describe(request, f"published {fw.app} {fw.version} ({fw.hw}) on {body.channel}" if body.channel + else f"unpublished {fw.app} {fw.version} ({fw.hw})") fw.channel = body.channel session.commit() broadcaster.publish("firmwares") @@ -453,8 +499,9 @@ def patch_firmware(firmware_id: int, body: FirmwarePatch, session: Session = Dep @router.delete("/firmwares/{firmware_id}", status_code=204) -def delete_firmware(firmware_id: int, session: Session = Depends(get_session)): +def delete_firmware(firmware_id: int, request: Request, session: Session = Depends(get_session)): fw = session.get(Firmware, firmware_id) or _404("firmware") + describe(request, f"deleted {fw.app} {fw.version} ({fw.hw})") in_use = session.scalar( select(Deployment.id).where(Deployment.firmware_id == fw.id, Deployment.status.in_(OPEN_STATES)) ) @@ -487,8 +534,10 @@ def _cleanup_orphan(session: Session, sha: str) -> None: @router.post("/deployments", response_model=list[DeviceOut], status_code=201) -def create_deployments(body: DeployIn, session: Session = Depends(get_session)): +def create_deployments(body: DeployIn, request: Request, session: Session = Depends(get_session)): fw = session.get(Firmware, body.firmware_id) or _404("firmware") + target = " ".join(f"#{t}" for t in body.tags) if body.tags else f"{len(set(body.device_ids))} device(s)" + describe(request, f"deployed {fw.app} {fw.version} to {target}") devices = list(session.scalars(select(Device).where(Device.id.in_(body.device_ids))).all()) if len(devices) != len(set(body.device_ids)): raise HTTPException(404, "unknown device") @@ -516,6 +565,7 @@ def create_deployments(body: DeployIn, session: Session = Depends(get_session)): if not outdated and not devices: raise HTTPException(422, f"{fw.app} {fw.version} is too big for every device tagged {tag_list}") devices += [d for d in outdated if d not in devices] + describe(request, f"deployed {fw.app} {fw.version} to {device_names(devices)}") for device in devices: # Also drops a queued rollout deployment, which would otherwise override this one later. @@ -529,8 +579,9 @@ def create_deployments(body: DeployIn, session: Session = Depends(get_session)): @router.post("/deployments/{deployment_id}/cancel", response_model=DeviceOut) -def cancel_deployment(deployment_id: int, session: Session = Depends(get_session)): +def cancel_deployment(deployment_id: int, request: Request, session: Session = Depends(get_session)): deployment = session.get(Deployment, deployment_id) or _404("deployment") + describe(request, f"cancelled {deployment.firmware.app} {deployment.firmware.version} on {who(deployment.device)}") if deployment.status not in OPEN_STATES: raise HTTPException(409, f"deployment is already {deployment.status}") deployment.status = "cancelled" diff --git a/server/otter/audit.py b/server/otter/audit.py new file mode 100644 index 0000000..c128010 --- /dev/null +++ b/server/otter/audit.py @@ -0,0 +1,87 @@ +"""Activity log (#100): every change made through the UI API, by whom, and how it went. + +The HTTP middleware in main.py records each write once it's answered. Endpoints say what +they did in readable words with describe(); otherwise the endpoint's name and ids stand in. +Kept KEEP days. +""" + +from datetime import timedelta + +from fastapi import Request +from fastapi.concurrency import run_in_threadpool +from sqlalchemy import delete, select + +from .db import SessionLocal, utcnow +from .models import AuditEvent + +KEEP = timedelta(days=90) +_pruned_at = None + + +def describe(request: Request, text: str) -> None: + request.state.audit = text + + +def default_text(request: Request) -> str: + route = request.scope.get("route") + if route is None: + return f"{request.method} {request.url.path}" + ids = " ".join(f"#{v}" for v in request.scope.get("path_params", {}).values()) + return f"{route.name.replace('_', ' ')} {ids}".strip() + + +class AuditMiddleware: + """Records the UI API's writes once answered. Plain ASGI, so streams (the UI's events, + devices' long polls) pass through untouched.""" + + def __init__(self, app) -> None: + self.app = app + + async def __call__(self, scope, receive, send) -> None: + path = scope.get("path", "") + if ( + scope["type"] != "http" + or scope["method"] in ("GET", "HEAD", "OPTIONS") + or not path.startswith("/api/") + or path.startswith(("/api/v1/", "/api/auth/")) + ): + return await self.app(scope, receive, send) + status = 500 + + async def send_and_note(message) -> None: + nonlocal status + if message["type"] == "http.response.start": + status = message["status"] + await send(message) + + try: + await self.app(scope, receive, send_and_note) + finally: + await run_in_threadpool(record, Request(scope), status) + + +def record(request: Request, status: int) -> None: + global _pruned_at + user = getattr(request.state, "user", None) + if user is None: + return + with SessionLocal() as session: + session.add( + AuditEvent( + username=user.username, + via_token=getattr(request.state, "via_token", False), + method=request.method, + path=request.url.path, + text=getattr(request.state, "audit", None) or default_text(request), + status=status, + ) + ) + if _pruned_at is None or utcnow() - _pruned_at > timedelta(hours=1): + session.execute(delete(AuditEvent).where(AuditEvent.at < utcnow() - KEEP)) + _pruned_at = utcnow() + session.commit() + + +def recent(limit: int = 200) -> list[AuditEvent]: + with SessionLocal() as session: + return list(session.scalars(select(AuditEvent).order_by(AuditEvent.id.desc()).limit(limit))) diff --git a/server/otter/auth.py b/server/otter/auth.py index 672dbc6..93a1091 100644 --- a/server/otter/auth.py +++ b/server/otter/auth.py @@ -7,6 +7,7 @@ """ import hashlib +import re import secrets import threading import time @@ -96,14 +97,22 @@ def current_user(request: Request) -> tuple[User | None, bool]: return None, False +# What a viewer may still do besides reading: watching a device's live logs. +VIEWER_WRITES = re.compile(r"^/api/devices/\d+/logs/(watch|stop)$") + + def require_user(request: Request) -> User: """FastAPI dependency protecting the UI API.""" user, via_token = current_user(request) if user is None: raise HTTPException(401, "authentication required") - if request.method not in SAFE_METHODS and not via_token: - check_same_origin(request) + if request.method not in SAFE_METHODS: + if not via_token: + check_same_origin(request) + if user.role != "admin" and not VIEWER_WRITES.match(request.url.path): + raise HTTPException(403, "read-only account: ask an admin") request.state.user = user + request.state.via_token = via_token return user diff --git a/server/otter/cli.py b/server/otter/cli.py index c4772c7..d3c1a50 100644 --- a/server/otter/cli.py +++ b/server/otter/cli.py @@ -1,6 +1,8 @@ """Account and API token management. python -m otter.cli create-user admin + python -m otter.cli create-user alice --role viewer # sees everything, changes nothing + python -m otter.cli set-role alice admin python -m otter.cli create-token ci --user admin python -m otter.cli list-tokens python -m otter.cli revoke-token ci @@ -39,13 +41,23 @@ def get_user(session, username: str) -> User: return user +ROLES = ("admin", "viewer") + + def create_user(args) -> None: with SessionLocal() as session: if session.scalar(select(User).where(User.username == args.username)): sys.exit(f"User {args.username!r} already exists.") - session.add(User(username=args.username, password_hash=auth.hash_password(read_password(args)))) + session.add(User(username=args.username, password_hash=auth.hash_password(read_password(args)), role=args.role)) + session.commit() + print(f"User {args.username!r} created ({args.role}).") + + +def set_role(args) -> None: + with SessionLocal() as session: + get_user(session, args.username).role = args.role session.commit() - print(f"User {args.username!r} created.") + print(f"{args.username!r} is now {args.role}.") def set_password(args) -> None: @@ -60,7 +72,7 @@ def set_password(args) -> None: def list_users(args) -> None: with SessionLocal() as session: for user in session.scalars(select(User).order_by(User.username)): - print(f"{user.username}\tcreated {user.created_at:%Y-%m-%d}") + print(f"{user.username}\t{user.role}\tcreated {user.created_at:%Y-%m-%d}") def delete_user(args) -> None: @@ -108,8 +120,15 @@ def main(argv: list[str] | None = None) -> None: cmd = commands.add_parser(name, help=help_) cmd.add_argument("username") cmd.add_argument("--password-stdin", action="store_true", help="read the password from stdin") + if func is create_user: + cmd.add_argument("--role", choices=ROLES, default="admin", help="viewer: sees everything, changes nothing") cmd.set_defaults(func=func) + cmd = commands.add_parser("set-role", help="make an account admin or viewer") + cmd.add_argument("username") + cmd.add_argument("role", choices=ROLES) + cmd.set_defaults(func=set_role) + cmd = commands.add_parser("list-users", help="list accounts") cmd.set_defaults(func=list_users) cmd = commands.add_parser("delete-user", help="delete an account, its sessions and tokens") diff --git a/server/otter/main.py b/server/otter/main.py index ed3506e..bb4e6cb 100644 --- a/server/otter/main.py +++ b/server/otter/main.py @@ -10,6 +10,7 @@ from sqlalchemy import text from . import api_auth, api_device, api_rollouts, api_ui, config +from .audit import AuditMiddleware from .auth import require_user from .db import engine from .events import broadcaster, wakeups @@ -65,6 +66,7 @@ async def lifespan(_: FastAPI): app = FastAPI(title="Otter", lifespan=lifespan) +app.add_middleware(AuditMiddleware) @app.get("/healthz", include_in_schema=False) diff --git a/server/otter/migrations/versions/0022_roles_and_audit.py b/server/otter/migrations/versions/0022_roles_and_audit.py new file mode 100644 index 0000000..3543180 --- /dev/null +++ b/server/otter/migrations/versions/0022_roles_and_audit.py @@ -0,0 +1,42 @@ +"""user roles and audit log + +Revision ID: 0022 +Revises: 0021 +Create Date: 2026-10-01 23:00:00.000000 +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + + +revision: str = '0022' +down_revision: str | None = '0021' +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + with op.batch_alter_table('users', schema=None) as batch_op: + batch_op.add_column(sa.Column('role', sa.String(length=16), server_default='admin', nullable=False)) + op.create_table( + 'audit_events', + sa.Column('id', sa.Integer(), nullable=False), + sa.Column('at', sa.DateTime(), nullable=False), + sa.Column('username', sa.String(), nullable=False), + sa.Column('via_token', sa.Boolean(), nullable=False), + sa.Column('method', sa.String(length=8), nullable=False), + sa.Column('path', sa.String(), nullable=False), + sa.Column('text', sa.String(), nullable=False), + sa.Column('status', sa.Integer(), nullable=False), + sa.PrimaryKeyConstraint('id'), + ) + op.create_index('ix_audit_events_at', 'audit_events', ['at']) + + +def downgrade() -> None: + op.drop_index('ix_audit_events_at', table_name='audit_events') + op.drop_table('audit_events') + with op.batch_alter_table('users', schema=None) as batch_op: + batch_op.drop_column('role') diff --git a/server/otter/models.py b/server/otter/models.py index 59dad75..3f4d185 100644 --- a/server/otter/models.py +++ b/server/otter/models.py @@ -191,6 +191,8 @@ class User(Base): username: Mapped[str] = mapped_column(String(64), unique=True) password_hash: Mapped[str] # argon2 created_at: Mapped[datetime] = mapped_column(default=utcnow) + # admin: everything; viewer: sees everything, changes nothing (#100). API tokens act with it. + role: Mapped[str] = mapped_column(String(16), default="admin", server_default="admin") class AuthSession(Base): @@ -253,6 +255,22 @@ class ConfigValue(Base): value: Mapped[str] # JSON: a string, number or boolean +class AuditEvent(Base): + """A change made through the UI API (#100, see audit.py). The username is copied: the + entry outlives the account.""" + + __tablename__ = "audit_events" + + id: Mapped[int] = mapped_column(primary_key=True) + at: Mapped[datetime] = mapped_column(default=utcnow, index=True) + username: Mapped[str] + via_token: Mapped[bool] = mapped_column(default=False) + method: Mapped[str] = mapped_column(String(8)) + path: Mapped[str] + text: Mapped[str] # what happened, readable + status: Mapped[int] # the HTTP status of the answer + + class DeviceSample(Base): """A device's signal and free memory at one check-in (#98): one every few minutes, kept a week (see history.py). restart is the reset reason when the device had just restarted.""" diff --git a/server/otter/static/app.js b/server/otter/static/app.js index 7c98c9a..f5b77a7 100644 --- a/server/otter/static/app.js +++ b/server/otter/static/app.js @@ -1292,6 +1292,8 @@ async function start() { const status = await (await fetch("/api/auth/status")).json(); if (!status.user) return goToLogin(); $("#user").textContent = status.user; + // A viewer sees everything and changes nothing (the server refuses anyway, #100). + document.body.classList.toggle("read-only", status.role === "viewer"); loadFilterFromUrl(); connect(); } @@ -1553,3 +1555,29 @@ window.addEventListener("resize", () => { clearTimeout(historyResize); historyResize = setTimeout(() => panel.open && renderHistory(), 150); }); + +// --- Activity log (#100) -------------------------------------------------------- + +const activityDialog = $("#activity-dialog"); + +async function openActivity() { + activityDialog.showModal(); + const list = $(".activity-list", activityDialog); + list.innerHTML = `