reachdiff 0.9.0__py3-none-any.whl

reachdiff/config.py

@@ -0,0 +1,135 @@
+"""Load and validate reachdiff TOML. Unknown keys are errors, so a typo cannot disable a rule."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from reachdiff.resolve import LEVELS
+
+BUILTIN_RULES = (
+    'broad_principal',
+    'broad_privilege',
+    'grant_resource_conflict',
+    'individual_owner',
+    'sensitive_access',
+    'unverified',
+)
+BUILTIN_DEFAULTS = {'grant_resource_conflict': 'BLOCK'}  # every other built-in rule defaults to WARN
+SEVERITIES = ('WARN', 'BLOCK')
+PRINCIPAL_KINDS = ('user', 'service_principal', 'group', 'unknown')
+DEFAULT_TAGS = ('pii*', 'sensitive*', 'class.*')
+RULE_KEYS = ('id', 'severity', 'message', 'when', 'levels', 'objects', 'principal_kinds', 'sensitive', 'unless_via')
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    severity: str
+    message: str
+    when: str = 'gain'
+    levels: frozenset[str] = frozenset()
+    objects: tuple[str, ...] = ()
+    principal_kinds: frozenset[str] = frozenset()
+    sensitive: bool | None = None
+    unless_via: frozenset[str] = frozenset()
+
+
+def builtin_defaults() -> dict[str, str]:
+    return {rule: BUILTIN_DEFAULTS.get(rule, 'WARN') for rule in BUILTIN_RULES}
+
+
+@dataclass(frozen=True)
+class Config:
+    fail_on: str = 'block'
+    sensitive_tags: tuple[str, ...] = DEFAULT_TAGS
+    builtin: dict[str, str] = field(default_factory=builtin_defaults)
+    limit_objects: int = 500
+    limit_members: int = 5000
+    limit_deep_children: int = 1000
+    rules: tuple[Rule, ...] = ()
+
+
+def _keys(table: object, allowed: tuple[str, ...], where: str) -> dict:
+    if not isinstance(table, dict):
+        raise ValueError(f'{where} must be a table')
+    unknown = sorted(set(table) - set(allowed))
+    if unknown:
+        raise ValueError(f'unknown config key in {where}: {", ".join(unknown)}')
+    return table
+
+
+def _strings(value: object, where: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value):
+        raise ValueError(f'{where} must be a list of nonempty strings')
+    return tuple(value)
+
+
+def _choice(value: object, choices: tuple[str, ...], where: str) -> str:
+    if value not in choices:
+        raise ValueError(f'{where} must be one of {", ".join(choices)}')
+    return value
+
+
+def _rule(raw: object, index: int) -> Rule:
+    where = f'rule[{index}]'
+    raw = _keys(raw, RULE_KEYS, where)
+    for key in ('id', 'message'):
+        if not isinstance(raw.get(key), str) or not raw[key]:
+            raise ValueError(f'{where}.{key} is required')
+    sensitive = raw.get('sensitive')
+    if sensitive is not None and type(sensitive) is not bool:
+        raise ValueError(f'{where}.sensitive must be true or false')
+    levels = _strings(raw.get('levels', []), f'{where}.levels')
+    kinds = _strings(raw.get('principal_kinds', []), f'{where}.principal_kinds')
+    for value in levels:
+        _choice(value, LEVELS, f'{where}.levels')
+    for value in kinds:
+        _choice(value, PRINCIPAL_KINDS, f'{where}.principal_kinds')
+    return Rule(
+        raw['id'],
+        _choice(raw.get('severity'), SEVERITIES, f'{where}.severity'),
+        raw['message'],
+        _choice(raw.get('when', 'gain'), ('gain', 'lose', 'any'), f'{where}.when'),
+        frozenset(levels),
+        _strings(raw.get('objects', []), f'{where}.objects'),
+        frozenset(kinds),
+        sensitive,
+        frozenset(_strings(raw.get('unless_via', []), f'{where}.unless_via')),
+    )
+
+
+def parse_config(data: dict) -> Config:
+    _keys(data, ('fail_on', 'sensitive', 'builtin', 'limits', 'rule'), 'config')
+    fail_on = _choice(data.get('fail_on', 'block'), ('block', 'warn', 'never'), 'fail_on')
+    sensitive = _keys(data.get('sensitive', {}), ('tags',), '[sensitive]')
+    tags = _strings(sensitive.get('tags', list(DEFAULT_TAGS)), 'sensitive.tags')
+    builtin = builtin_defaults()
+    for name, value in _keys(data.get('builtin', {}), BUILTIN_RULES, '[builtin]').items():
+        allowed = SEVERITIES if name == 'unverified' else SEVERITIES + ('off',)
+        builtin[name] = _choice(value, allowed, f'builtin.{name}')
+    limits = _keys(data.get('limits', {}), ('objects', 'members', 'deep_children'), '[limits]')
+    values = {}
+    for key, default in (('objects', 500), ('members', 5000), ('deep_children', 1000)):
+        value = limits.get(key, default)
+        if type(value) is not int or value < 1:
+            raise ValueError(f'limits.{key} must be a positive integer')
+        values[key] = value
+    raw_rules = data.get('rule', [])
+    if not isinstance(raw_rules, list):
+        raise ValueError('rule must be an array of tables ([[rule]])')
+    rules = tuple(_rule(raw, i) for i, raw in enumerate(raw_rules))
+    ids = [r.id for r in rules]
+    if len(set(ids)) != len(ids) or set(ids) & set(BUILTIN_RULES):
+        raise ValueError('rule ids must be unique and must not reuse built-in rule names')
+    return Config(fail_on, tags, builtin, values['objects'], values['members'], values['deep_children'], rules)
+
+
+def load_config(path: Path | None) -> Config:
+    if path is None:
+        return Config()
+    try:
+        return parse_config(tomllib.loads(path.read_text(encoding='utf-8')))
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f'invalid config TOML: {exc}') from None

reachdiff/diff.py

@@ -0,0 +1,234 @@
+"""Compare access before and after a plan, and shape the rows a reviewer sees."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+from reachdiff.resolve import Entry, Route, groups_of, resolve
+from reachdiff.scope import changed_objects, with_ancestors
+from reachdiff.state import BUILTIN_GROUPS, Gap, State, ancestors, kind_of
+from reachdiff.tfplan import Plan
+
+USAGE = frozenset({'USE_CATALOG', 'USE_SCHEMA', 'ALL_PRIVILEGES'})
+
+
+@dataclass(frozen=True)
+class MemberCount:
+    expanded: bool
+    total: int = 0
+    changed: int = 0  # members who newly gain (+) or lose (-) the entry
+    unchanged: int = 0  # members who already had it (+) or keep it another way (-)
+    names: tuple[str, ...] = ()
+    unread: bool = False  # membership could not be read
+
+
+@dataclass(frozen=True)
+class Change:
+    direction: str  # '+' gained, '-' lost
+    principal: str
+    kind: str
+    level: str
+    securable: str
+    routes: tuple[Route, ...]
+    members: MemberCount | None = None
+
+
+@dataclass(frozen=True)
+class AccessDiff:
+    rows: tuple[Change, ...]  # what a reviewer sees: child rows collapse into parent rows
+    all_rows: tuple[Change, ...]  # the same rows before collapsing; configured rules match these
+    gained: frozenset
+    lost: frozenset
+    route_changes: tuple
+    gaps: tuple[Gap, ...]
+
+
+Members = dict[str, frozenset[str]]  # group -> transitive members, computed once per state
+
+
+def _direct(state: State) -> dict[str, list[str]]:
+    children: dict[str, list[str]] = {}
+    for link in state.memberships:
+        children.setdefault(link.group, []).append(link.member)
+    return children
+
+
+def _walk(children: dict[str, list[str]], group: str) -> set[str]:
+    found: set[str] = set()
+    queue = deque([group])
+    while queue:
+        for member in children.get(queue.popleft(), ()):
+            if member not in found and member != group:
+                found.add(member)
+                queue.append(member)
+    return found
+
+
+def members_of(state: State, group: str) -> set[str]:
+    """Transitive members through explicit memberships (built-in groups have none listed)."""
+    return _walk(_direct(state), group)
+
+
+def _member_map(state: State) -> Members:
+    children = _direct(state)
+    return {group: frozenset(_walk(children, group)) for group in children}
+
+
+def _touched(before: State, after: State, plan: Plan) -> tuple[set[str], set[str]]:
+    ids = {p.scim_id: p.name for s in (before, after) for p in s.principals.values() if p.scim_id}
+    ids.update({scim_id: p.name for scim_id, p in plan.identities.items()})
+    touched: set[str] = set()
+    member_groups: set[str] = set()
+    for resource in plan.changed_grants():
+        touched |= set(resource.before or {}) | set(resource.after or {})
+    for resource in plan.changed_owners():
+        touched |= {x for x in (resource.before, resource.after) if x}
+    for edge in plan.changed_memberships():
+        for scim_id, bucket in ((edge.group_id, member_groups), (edge.member_id, touched)):
+            if scim_id in ids:
+                bucket.add(ids[scim_id])
+    return touched | member_groups, member_groups
+
+
+def _count(
+    state: State, members_map: Members, group: str, entry: Entry, entries: frozenset, expanded: set[str]
+) -> MemberCount:
+    if group in state.unread_groups:
+        return MemberCount(False, unread=True)
+    if group in BUILTIN_GROUPS or group not in expanded:
+        return MemberCount(False)
+    members = sorted(m for m in members_map.get(group, ()) if state.kind(m) != 'group')
+    changed = tuple(m for m in members if (m,) + entry[1:] in entries)
+    return MemberCount(True, len(members), len(changed), len(members) - len(changed), changed)
+
+
+def _explained(routes: tuple[Route, ...], group_rows: dict, level: str, securable: str) -> bool:
+    """Hidden only when every route passes through a group shown in its own row for the same level and object."""
+    shown = {
+        group for group, row_level, row_securable in group_rows if (row_level, row_securable) == (level, securable)
+    }
+    return all(shown & set(route.main.chain) for route in routes)
+
+
+def _rows(
+    direction: str, entries: frozenset, state: State, members_map: Members, routes: dict, expanded: set[str]
+) -> list[Change]:
+    group_rows = {}
+    for entry in sorted(entries):
+        principal, level, securable = entry
+        if state.kind(principal) == 'group':
+            group_rows[entry] = Change(
+                direction,
+                principal,
+                'group',
+                level,
+                securable,
+                routes[entry],
+                _count(state, members_map, principal, entry, entries, expanded),
+            )
+    rows = list(group_rows.values())
+    for entry in sorted(entries):
+        principal, level, securable = entry
+        if entry not in group_rows and not _explained(routes[entry], group_rows, level, securable):
+            rows.append(Change(direction, principal, state.kind(principal), level, securable, routes[entry]))
+    return rows
+
+
+def _sorted(rows: list[Change]) -> tuple[Change, ...]:
+    return tuple(sorted(rows, key=lambda r: (r.direction, r.principal, r.level, r.securable)))
+
+
+def _collapse(rows: list[Change]) -> tuple[Change, ...]:
+    keys = {(r.direction, r.principal, r.level, r.securable) for r in rows}
+    return _sorted(
+        [r for r in rows if not any((r.direction, r.principal, r.level, a) in keys for a in ancestors(r.securable)[1:])]
+    )
+
+
+def _usage(state: State, securable: str) -> dict[str, frozenset[str]]:
+    held: dict[str, frozenset[str]] = {}
+    for grant in state.grants:
+        if grant.securable == securable:
+            held[grant.principal] = held.get(grant.principal, frozenset()) | (grant.privileges & USAGE)
+    return held
+
+
+def _latent(before: State, after: State, plan: Plan) -> list[Gap]:
+    """Usage privileges gained or lost on a catalog or schema can change grants below it that were not read.
+
+    Compared on the states, like the rows: a resource's plan `before` misses grants it replaces, such as the live
+    grants on an object a `databricks_grants` create takes over.
+    """
+    gaps = []
+    for securable in sorted({r.securable for r in plan.changed_grants() if kind_of(r.securable) != 'table'}):
+        old, new = _usage(before, securable), _usage(after, securable)
+        for principal in sorted(set(old) | set(new)):
+            had, has = old.get(principal, frozenset()), new.get(principal, frozenset())
+            if gained := has - had:
+                gaps.append(
+                    Gap(
+                        'latent_grants',
+                        f'{principal} gains {", ".join(sorted(gained))} on '
+                        f'{securable}; this may activate existing table-level grants '
+                        'that were not enumerated (use --deep)',
+                    )
+                )
+            if lost := had - has:
+                gaps.append(
+                    Gap(
+                        'deactivated_grants',
+                        f'{principal} loses {", ".join(sorted(lost))} on '
+                        f'{securable}; grants below it that relied on this may stop working '
+                        'and were not enumerated (use --deep)',
+                    )
+                )
+    return gaps
+
+
+def compute_diff(before: State, after: State, plan: Plan, *, members_limit: int, deep: bool) -> AccessDiff:
+    gaps: list[Gap] = []
+    touched, member_groups = _touched(before, after, plan)
+    holders = {h for g in member_groups for s in (before, after) for h in groups_of(s, g)}
+    objects = set(changed_objects(plan))
+    for s in (before, after):
+        objects |= {g.securable for g in s.grants if g.principal in holders}
+        objects |= {x.name for x in s.securables.values() if x.owner in holders}
+        if deep:
+            objects |= set(s.securables)
+    objects = with_ancestors(objects)
+    if deep:
+        # A usage change can activate or deactivate anyone's grants below it, so evaluate every holder in scope.
+        for s in (before, after):
+            touched |= {g.principal for g in s.grants if g.securable in objects}
+            touched |= {x.owner for x in s.securables.values() if x.owner and x.name in objects}
+    groups = {p for p in touched if 'group' in (before.kind(p), after.kind(p))}
+    members_before, members_after = _member_map(before), _member_map(after)
+
+    def members(group: str) -> frozenset[str]:
+        return members_before.get(group, frozenset()) | members_after.get(group, frozenset())
+
+    subjects = set(touched)
+    # Decided once: member counts are shown only for groups whose members were all evaluated.
+    expanded: set[str] = set()
+    skipped: list[str] = []
+    for group in sorted(groups - set(BUILTIN_GROUPS)):
+        if len(subjects | members(group)) > members_limit:
+            skipped.append(group)
+            continue
+        subjects |= members(group)
+        expanded.add(group)
+    # A group nested in an expanded group comes along when every one of its members was evaluated.
+    nested = {m for g in expanded for m in members(g) if 'group' in (before.kind(m), after.kind(m))} - set(skipped)
+    expanded |= {g for g in nested if members(g) <= subjects}
+    if skipped:
+        gaps.append(Gap('limit_reached', f'members of {", ".join(skipped)} were not expanded beyond {members_limit}'))
+    old, new = resolve(before, subjects, objects), resolve(after, subjects, objects)
+    gained, lost = frozenset(new.keys() - old.keys()), frozenset(old.keys() - new.keys())
+    route_changes = tuple((k, old[k], new[k]) for k in sorted(old.keys() & new.keys()) if old[k] != new[k])
+    rows = _rows('+', gained, after, members_after, new, expanded) + _rows(
+        '-', lost, before, members_before, old, expanded
+    )
+    if not deep:
+        gaps += _latent(before, after, plan)
+    return AccessDiff(_collapse(rows), _sorted(rows), gained, lost, route_changes, tuple(sorted(set(gaps))))

reachdiff/report.py

@@ -0,0 +1,215 @@
+"""Report dict and renderers. Reports name principals and objects: treat them as sensitive metadata."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from reachdiff.diff import AccessDiff, Change
+from reachdiff.resolve import Route
+from reachdiff.scope import has_access_changes
+from reachdiff.state import BUILTIN_GROUPS, State, kind_of
+from reachdiff.tfplan import Plan
+
+STANDING_LIMITATIONS = (
+    'metastore and workspace admin powers',
+    'ABAC policies, row filters and column masks',
+    'workspace-level ACLs',
+    'account and identity-provider membership completeness',
+    'runtime behavior',
+)
+
+
+def route_text(route: Route) -> str:
+    main = f'{route.main.privilege} on {route.main.securable}'
+    if route.main.chain:
+        main += f' (via {" → ".join(route.main.chain)})'
+    parts, shown = [main], {(route.main.privilege, route.main.securable)}
+    for hop in route.prerequisites:  # ownership can meet several requirements; show each hop once
+        if (hop.privilege, hop.securable) not in shown:
+            shown.add((hop.privilege, hop.securable))
+            parts.append(f'{hop.privilege} on {hop.securable}')
+    return ' + '.join(parts)
+
+
+def _row(change: Change) -> dict:
+    members = None
+    if change.members is not None:
+        members = {**asdict(change.members), 'names': list(change.members.names)}
+    return {
+        'direction': change.direction,
+        'principal': change.principal,
+        'kind': change.kind,
+        'level': change.level,
+        'securable': change.securable,
+        'via': [route_text(r) for r in change.routes],
+        'members': members,
+    }
+
+
+def build_report(plan: Plan, before: State, after: State, diff: AccessDiff, findings: tuple, status: str) -> dict:
+    gaps = sorted(set(plan.gaps) | set(before.gaps) | set(after.gaps) | set(diff.gaps))
+    return {
+        'schema_version': 1,
+        'tool': 'reachdiff',
+        'status': status,
+        'mode': before.source,
+        'synthetic': plan.synthetic,
+        'access_changes': has_access_changes(plan) or bool(plan.not_evaluated),
+        'summary': {
+            'gained': sum(r.direction == '+' for r in diff.rows),
+            'lost': sum(r.direction == '-' for r in diff.rows),
+            'findings': len(findings),
+        },
+        'changes': [_row(r) for r in diff.rows],
+        'findings': [asdict(f) for f in findings],
+        'not_evaluated': list(plan.not_evaluated),
+        'gaps': [asdict(g) for g in gaps],
+        'route_changes': [
+            {
+                'principal': k[0],
+                'level': k[1],
+                'securable': k[2],
+                'before': [route_text(r) for r in old],
+                'after': [route_text(r) for r in new],
+            }
+            for k, old, new in diff.route_changes
+        ],
+        'notes': sorted(set(before.notes) | set(after.notes)),
+        'standing_limitations': list(STANDING_LIMITATIONS),
+    }
+
+
+def _who(row: dict) -> str:
+    name, members = row['principal'], row['members']
+    if name in BUILTIN_GROUPS:
+        return f'{name} ({BUILTIN_GROUPS[name]})'
+    if members is None:
+        return name
+    if members.get('unread'):
+        return f'{name} (members not read)'
+    if not members['expanded']:
+        return f'{name} (members not expanded)'
+    total = f'{members["total"]} member' + ('' if members['total'] == 1 else 's')
+    if row['direction'] == '+':
+        return f'{name} ({total}, {members["changed"]} new, {members["unchanged"]} already had it)'
+    return f'{name} ({total}, {members["changed"]} lose it, {members["unchanged"]} keep it another way)'
+
+
+def _where(securable: str) -> str:
+    return securable + {'catalog': ' (all schemas)', 'schema': ' (all tables)', 'table': ''}[kind_of(securable)]
+
+
+INLINE = (('\\', '\\\\'), ('\r', ' '), ('\n', ' '), ('<', '&lt;'), ('>', '&gt;'), ('[', '\\['), (']', '\\]'))
+
+
+def _escape(text: str, pairs) -> str:
+    for old, new in pairs:
+        text = text.replace(old, new)
+    return text
+
+
+def _inline(text: str) -> str:
+    """Untrusted text on one Markdown line: no line breaks, HTML tags, code spans or links."""
+    return _escape(text, INLINE + (('`', "'"),))
+
+
+def _cell(text: str) -> str:
+    return _escape(text, INLINE + (('|', '\\|'),))
+
+
+def _no_changes(report: dict) -> str:
+    return 'No evaluated access changes; see findings.' if report['access_changes'] else 'No access changes.'
+
+
+def _details(report: dict) -> list[str]:
+    lines = [
+        '- ' + _inline(f'{r["principal"]} {r["level"]} {r["securable"]}: {", ".join(r["members"]["names"])}')
+        for r in report['changes']
+        if r['members'] and r['members']['names']
+    ]
+    lines += [
+        '- route changed: ' + _inline(f'{c["principal"]} {c["level"]} {c["securable"]}')
+        for c in report['route_changes']
+    ]
+    lines += [f'- gap `{_inline(g["category"])}`: {_inline(g["detail"])}' for g in report['gaps']]
+    lines += [f'- note: {_inline(n)}' for n in report['notes']]
+    return lines or ['- nothing further']
+
+
+def render_markdown(report: dict) -> str:
+    label = 'SYNTHETIC FIXTURE · ' if report['synthetic'] else ''
+    summary = report['summary']
+    lines = [
+        f'## reachdiff: {report["status"]}',
+        '',
+        f'_{label}{report["mode"]} mode_',
+        '',
+        f'**{summary["gained"]} gained · {summary["lost"]} lost · {summary["findings"]} findings**',
+        '',
+    ]
+    if report['changes']:
+        lines += ['| | Principal | Access | On | Via |', '|---|---|---|---|---|']
+        lines += [
+            f'| {r["direction"]} | {_cell(_who(r))} | {r["level"]} | {_cell(_where(r["securable"]))} | '
+            f'{_cell("; ".join(r["via"]))} |'
+            for r in report['changes']
+        ]
+    else:
+        lines.append(_no_changes(report))
+    if report['findings']:
+        lines += ['', '### Findings', '']
+        lines += [
+            f'- **{f["severity"]}** `{_inline(f["rule"])}` {_inline(f["subject"])}: {_inline(f["message"])}'
+            for f in report['findings']
+        ]
+    if report['not_evaluated']:
+        lines += ['', f'### Not evaluated ({len(report["not_evaluated"])})', '']
+        lines += [f'- {_inline(item)}' for item in report['not_evaluated']]
+    lines += ['', '<details><summary>Details</summary>', ''] + _details(report)
+    lines += [
+        '',
+        '</details>',
+        '',
+        f'<sub>Not evaluated in any run: {"; ".join(report["standing_limitations"])}.</sub>',
+    ]
+    return '\n'.join(lines) + '\n'
+
+
+def render_text(report: dict) -> str:
+    label = ', SYNTHETIC FIXTURE' if report['synthetic'] else ''
+    summary = report['summary']
+    lines = [
+        f'reachdiff: {report["status"]} ({report["mode"]} mode{label})',
+        f'{summary["gained"]} gained, {summary["lost"]} lost, {summary["findings"]} findings',
+        '',
+    ]
+    for r in report['changes']:
+        lines.append(f'{r["direction"]} {_who(r)}  {r["level"]}  {_where(r["securable"])}')
+        lines += [f'    via {v}' for v in r['via']]
+    if not report['changes']:
+        lines.append(_no_changes(report))
+    if report['findings']:
+        lines += ['', 'Findings:'] + [
+            f'  {f["severity"]} {f["rule"]} {f["subject"]}: {f["message"]}' for f in report['findings']
+        ]
+    if report['not_evaluated']:
+        lines += ['', 'Not evaluated:'] + [f'  {item}' for item in report['not_evaluated']]
+    if report['gaps']:
+        lines += ['', 'Gaps:'] + [f'  {g["category"]}: {g["detail"]}' for g in report['gaps']]
+    if report['route_changes']:
+        lines += ['', 'Route changes:'] + [
+            f'  {c["principal"]} {c["level"]} {c["securable"]}' for c in report['route_changes']
+        ]
+    if report['notes']:
+        lines += ['', 'Notes:'] + [f'  {n}' for n in report['notes']]
+    lines += ['', 'Not evaluated in any run: ' + '; '.join(report['standing_limitations']) + '.']
+    # Every entry is one line: a line break inside a name must not forge report lines.
+    return '\n'.join(line.replace('\r', ' ').replace('\n', ' ') for line in lines) + '\n'
+
+
+def render_json(report: dict) -> str:
+    return json.dumps(report, indent=2, sort_keys=True, ensure_ascii=False) + '\n'
+
+
+RENDERERS = {'text': render_text, 'json': render_json, 'md': render_markdown}

reachdiff/resolve.py

@@ -0,0 +1,104 @@
+"""Effective access per principal and object, with evidence routes."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from reachdiff.state import Grant, State, ancestors
+
+LEVELS = ('READ', 'WRITE', 'MANAGE')
+Entry = tuple[str, str, str]  # (principal, level, securable)
+
+
+@dataclass(frozen=True, order=True)
+class Hop:
+    chain: tuple[str, ...]  # groups from the subject to the holder; () when the subject holds it
+    privilege: str
+    securable: str
+    evidence: str = field(compare=False)
+
+
+@dataclass(frozen=True, order=True)
+class Route:
+    main: Hop
+    prerequisites: tuple[Hop, ...] = ()
+
+
+def groups_of(state: State, subject: str) -> dict[str, tuple[str, ...]]:
+    """The subject, every group it belongs to (shortest chain), and implicit `account users`."""
+    chains: dict[str, tuple[str, ...]] = {subject: ()}
+    if subject != 'account users':
+        chains['account users'] = ('account users',)
+    links = sorted(state.memberships, key=lambda m: (m.member, m.group))
+    queue = deque([subject])
+    while queue:
+        current = queue.popleft()
+        for link in links:
+            if link.member == current and link.group not in chains:
+                chains[link.group] = chains[current] + (link.group,)
+                queue.append(link.group)
+    return chains
+
+
+def _by_securable(state: State) -> dict[str, list[Grant]]:
+    index: dict[str, list[Grant]] = {}
+    for grant in state.grants:
+        index.setdefault(grant.securable, []).append(grant)
+    return index
+
+
+def _hops(grants: dict[str, list[Grant]], chains: dict, scope: tuple[str, ...], privileges: set[str]) -> list[Hop]:
+    found = []
+    for securable in scope:
+        for grant in grants.get(securable, ()):
+            if grant.principal in chains:
+                for privilege in sorted(grant.privileges & privileges):
+                    found.append(Hop(chains[grant.principal], privilege, grant.securable, grant.evidence))
+    return sorted(found)
+
+
+def _ownership(state: State, chains: dict, scope: tuple[str, ...]) -> list[Hop]:
+    found = []
+    for name in scope:
+        securable = state.securables.get(name)
+        if securable and securable.owner in chains:
+            found.append(Hop(chains[securable.owner], 'OWNER', name, f'owner of {name}'))
+    return sorted(found)
+
+
+def _levels(state: State, grants: dict[str, list[Grant]], chains: dict, obj: str) -> dict[str, list[Route]]:
+    chain = ancestors(obj)
+    catalog = chain[-1]
+    schema_scope = chain[-2:]  # (schema, catalog) for tables and schemas; (catalog,) for catalogs
+    # Owners hold all privileges on the owned object and its children (Databricks docs), and MANAGE.
+    owned = _ownership(state, chains, chain)
+
+    def held(scope: tuple[str, ...], privileges: set[str]) -> list[Hop]:
+        return sorted(_hops(grants, chains, scope, privileges) + [h for h in owned if h.securable in scope])
+
+    use_catalog = held((catalog,), {'USE_CATALOG', 'ALL_PRIVILEGES'})
+    use_schema = held(schema_scope, {'USE_SCHEMA', 'ALL_PRIVILEGES'})
+    select = held(chain, {'SELECT', 'ALL_PRIVILEGES'})
+    modify = held(chain, {'MODIFY', 'ALL_PRIVILEGES'})
+    manage = held(chain, {'MANAGE'})
+    levels = {'READ': [], 'WRITE': [], 'MANAGE': [Route(h) for h in manage]}
+    if use_catalog and use_schema:
+        usage = (use_catalog[0], use_schema[0])
+        levels['READ'] = [Route(h, usage) for h in select]
+        if select:
+            levels['WRITE'] = [Route(h, usage + (select[0],)) for h in modify]
+    return levels
+
+
+def resolve(state: State, subjects: Iterable[str], objects: Iterable[str]) -> dict[Entry, tuple[Route, ...]]:
+    result: dict[Entry, tuple[Route, ...]] = {}
+    grants = _by_securable(state)
+    for subject in sorted(set(subjects)):
+        chains = groups_of(state, subject)
+        for obj in sorted(set(objects)):
+            for level, routes in _levels(state, grants, chains, obj).items():
+                if routes:
+                    result[(subject, level, obj)] = tuple(sorted(set(routes)))
+    return result