"""The audit trail: every change, durable, in order.
`announce` says a change happened on a channel, and a channel reaches whatever
backends an operator configured. That is the right way to tell somebody, and
the wrong way to keep a record: if no file backend is configured there is no
trail at all, and an audit trail that depends on how the log was set up is not
an audit trail.
So a change is both announced and stored. The store is the record; the channel
is the notification.
`seq` is explicit and taken from `MAX(seq) + 1` under the store lock, for the
reason `grants.history` does the same: auto-increment is spelled differently
by the two backends and SQLite cannot add one with ALTER TABLE, while `rowid`
does not exist on PostgreSQL at all. Order matters here more than it does for
grants - "who changed it last" is the question an audit trail is for - so it
is a column and not an accident of storage.
`DURABILITY = 'commit'`: a change must be on disk before the call returns. The
window class would let a batch sit in memory, and the one record you cannot
afford to lose to a crash is the one that says what somebody just did.
"""
from __future__ import annotations
import json
from typing import Any, Optional, Sequence, TypedDict
from ..compartment.schema import Column, Index, Table
from ..storage import SqliteStore
from .change import Change
[docs]class ChangeRow(TypedDict):
"""One stored change, as an operator reads it back.
A named record for the reason check-dicts.py enforces it: an audit row is
read by field name, and this is the row.
"""
seq: int
at: int
resource: str
was: Any
now: Any
source: str
operator: str
session: str
tool: str
assurance: str
verified: bool
conflicts: list[str]
proofs: list[Any]
[docs]class TrailState(TypedDict):
"""How much trail there is, and how much of it nobody owns."""
changes: int
last_seq: int
unattributed: int
unverified: int
conflicted: int
[docs]class ChangeStore(SqliteStore):
"""Config changes, newest last by `seq`."""
DURABILITY = 'commit'
SCHEMA = (
Table('changes', (
Column('seq', 'INTEGER', primary_key=True),
Column('at', 'INTEGER', not_null=True),
Column('resource', 'TEXT', not_null=True),
Column('was', 'TEXT'),
Column('now', 'TEXT'),
Column('source', 'TEXT', not_null=True),
Column('operator', 'TEXT', not_null=True),
Column('session', 'TEXT', not_null=True),
Column('tool', 'TEXT', not_null=True),
Column('assurance', 'TEXT', not_null=True),
Column('verified', 'INTEGER', not_null=True),
Column('conflicts', 'TEXT', not_null=True),
Column('proofs', 'TEXT', not_null=True),
), indices=(
# The three questions an operator asks of an audit trail: what changed
# on this setting, what did this person change, and what did that one
# run do.
Index('changes_resource', ('resource', 'seq')),
Index('changes_operator', ('operator', 'seq')),
Index('changes_session', ('session', 'seq')),
)),
)
def _next_seq(self) -> int:
"""The next record number. Every caller holds the store lock, so the
read-then-write cannot race."""
row = self._one('SELECT COALESCE(MAX(seq), 0) + 1 FROM changes')
return int(row[0]) if row and row[0] is not None else 1
[docs] def put(self, change: Change) -> int:
"""Store one change and return its seq.
The values go through `Change.describe()`, so a secret is already
redacted by the time it reaches a row: an audit trail that records the
wallet URI it just rotated has published it to everyone who can read
the database.
"""
rec = change.describe()
act = change.actor
with self.transaction() as cur:
seq = self._next_seq()
cur.execute(
'INSERT INTO changes (seq, at, resource, was, now, source, operator, session, '
'tool, assurance, verified, conflicts, proofs) '
'VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)',
(seq, int(act.at), rec['resource'],
json.dumps(rec['was']), json.dumps(rec['now']), rec['source'],
act.operator, act.session, act.tool,
act.assurance or '', 1 if act.verified else 0,
json.dumps(act.conflicts()),
json.dumps([p.describe() for p in act.proofs])))
return seq
def _rows(self, where: str, args: Sequence[Any], limit: int) -> list[ChangeRow]:
rows = self._all(
'SELECT seq, at, resource, was, now, source, operator, session, tool, '
'assurance, verified, conflicts, proofs FROM changes '
+ where + ' ORDER BY seq DESC LIMIT ?', tuple(args) + (int(limit),))
out: list[ChangeRow] = []
for r in rows:
row: ChangeRow = {
'seq': int(r[0]), 'at': int(r[1]), 'resource': r[2],
'was': json.loads(r[3]) if r[3] is not None else None,
'now': json.loads(r[4]) if r[4] is not None else None,
'source': r[5], 'operator': r[6] or '(unknown)', 'session': r[7],
'tool': r[8], 'assurance': r[9] or '(none)', 'verified': bool(r[10]),
'conflicts': json.loads(r[11] or '[]'),
'proofs': json.loads(r[12] or '[]'),
}
out.append(row)
return out
[docs] def recent(self, limit: int = 50) -> list[ChangeRow]:
"""Newest first, which is the order the question is usually asked in."""
return self._rows('', (), limit)
[docs] def of_resource(self, resource: str, limit: int = 50) -> list[ChangeRow]:
"""What changed on one setting. 'who last touched this' lives here."""
return self._rows('WHERE resource = ?', (resource,), limit)
[docs] def of_operator(self, operator: str, limit: int = 50) -> list[ChangeRow]:
return self._rows('WHERE operator = ?', (operator,), limit)
[docs] def of_session(self, session: str, limit: int = 200) -> list[ChangeRow]:
"""One run of one tool. A dozen changes from one `meshctl apply` are
one act, and this is what makes them readable as one."""
return self._rows('WHERE session = ?', (session,), limit)
[docs] def unattributed(self, limit: int = 50) -> list[ChangeRow]:
"""Changes with nobody named. The thing to watch on a node several
people manage."""
return self._rows("WHERE operator = ''", (), limit)
[docs] def unverified(self, limit: int = 50) -> list[ChangeRow]:
"""Changes whose author was claimed but never proved. Separate from
unattributed, because 'said they were X' and 'said nothing' are
different and only one of them is a policy violation worth chasing."""
return self._rows('WHERE verified = 0', (), limit)
[docs] def conflicted(self, limit: int = 50) -> list[ChangeRow]:
"""Changes where two rungs named different subjects."""
return self._rows("WHERE conflicts <> '[]'", (), limit)
[docs] def state(self) -> TrailState:
"""For the health block: how much trail there is and how much of it
nobody owns."""
row = self._one('SELECT COUNT(*), COALESCE(MAX(seq), 0) FROM changes')
total, last = (int(row[0]), int(row[1])) if row else (0, 0)
un = self._one("SELECT COUNT(*) FROM changes WHERE operator = ''")
nv = self._one('SELECT COUNT(*) FROM changes WHERE verified = 0')
cf = self._one("SELECT COUNT(*) FROM changes WHERE conflicts <> '[]'")
out: TrailState = {'changes': total, 'last_seq': last,
'unattributed': int(un[0]) if un else 0,
'unverified': int(nv[0]) if nv else 0,
'conflicted': int(cf[0]) if cf else 0}
return out
[docs]def record(store: Optional[ChangeStore], log: Any, change: Change) -> Optional[int]:
"""Store the change, then announce it.
Stored first on purpose. The announcement is a notification and may go
nowhere an operator kept; the row is the record, and a crash between the
two should lose the telling rather than the evidence.
"""
from . import change as change_mod # noqa: PLC0415 (avoids a cycle)
seq = store.put(change) if store is not None else None
change_mod.announce(log, change)
return seq
__all__ = ['ChangeStore', 'ChangeRow', 'TrailState', 'record']