boundarycheck 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.
@@ -0,0 +1,3 @@
1
+ """boundarycheck: check that an API enforces the authorization boundaries you declare."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from boundarycheck.cli import app
2
+
3
+ app()
boundarycheck/cli.py ADDED
@@ -0,0 +1,261 @@
1
+ """The command line: a thin layer over the library. Exit codes: 0 clean, 1 findings, 2 anything else."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import json
7
+ import os
8
+ import sys
9
+ import traceback
10
+ from collections import Counter
11
+ from pathlib import Path
12
+ from typing import Annotated, Any, NoReturn
13
+
14
+ import typer
15
+
16
+ from boundarycheck import __version__
17
+ from boundarycheck.config import ConfigError, load_config
18
+ from boundarycheck.engine import RunResult, run
19
+ from boundarycheck.evidence import RunStore, StoreError, parse_age
20
+ from boundarycheck.model import EgressViolation, Status, TransportUnavailable
21
+ from boundarycheck.planner import plan
22
+ from boundarycheck.redact import SecretLeakError
23
+ from boundarycheck.report import to_json, to_markdown
24
+ from boundarycheck.template import STARTER_CONFIG
25
+
26
+ DEFAULT_RUNS = Path(".boundarycheck/runs")
27
+ app = typer.Typer(
28
+ add_completion=False, no_args_is_help=True, pretty_exceptions_enable=False,
29
+ help="Check that an API enforces the authorization boundaries you declare. Read-only, loopback-only in v0.1.",
30
+ ) # fmt: skip
31
+ Config_ = Annotated[Path, typer.Option("--config", "-c", help="Path to the YAML config.")]
32
+ Runs_ = Annotated[Path, typer.Option("--runs-dir", help="Where runs are stored.")]
33
+
34
+
35
+ def _fail(message: str) -> NoReturn:
36
+ typer.echo(f"error: {message}", err=True)
37
+ raise typer.Exit(2)
38
+
39
+
40
+ def _version(value: bool) -> None:
41
+ if value:
42
+ typer.echo(f"boundarycheck {__version__}")
43
+ raise typer.Exit(0)
44
+
45
+
46
+ @app.callback()
47
+ def main(
48
+ version: Annotated[
49
+ bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")
50
+ ] = False,
51
+ ) -> None:
52
+ """boundarycheck"""
53
+
54
+
55
+ def _load(path: Path) -> Any:
56
+ try:
57
+ return load_config(path)
58
+ except ConfigError as exc:
59
+ _fail(f"config: {exc}")
60
+
61
+
62
+ @app.command()
63
+ def init(
64
+ output: Annotated[Path, typer.Option("--output", "-o", help="Where to write the starter config.")] = Path(
65
+ "boundarycheck.yaml"
66
+ ),
67
+ force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
68
+ ) -> None:
69
+ """Write an annotated, safe-by-default starter config."""
70
+ try:
71
+ with output.open("w" if force else "x", encoding="utf-8") as handle:
72
+ handle.write(STARTER_CONFIG)
73
+ except FileExistsError:
74
+ _fail(f"{output} already exists (use --force to overwrite it)")
75
+ except OSError:
76
+ _fail(f"could not write {output}")
77
+ typer.echo(f"wrote {output}. Next: edit it, then 'boundarycheck validate --config {output}'.")
78
+
79
+
80
+ @app.command()
81
+ def validate(config: Config_) -> None:
82
+ """Check the config (schema, references, policy completeness). No network."""
83
+ cfg = _load(config)
84
+ cases = plan(cfg)
85
+ typer.echo(
86
+ f"ok: scope '{cfg.scope.id}', {len(cfg.tenants)} tenants, {len(cfg.principals)} principals, "
87
+ f"{len(cfg.resources)} resources, {len(cfg.actions)} actions; {len(cases)} cases planned "
88
+ "(plus concealment checks derived from them)"
89
+ )
90
+
91
+
92
+ @app.command(name="plan")
93
+ def plan_cmd(config: Config_) -> None:
94
+ """Print every request that would be sent. Nothing is sent and no credential is read."""
95
+ cfg = _load(config)
96
+ cases = plan(cfg)
97
+ for c in cases:
98
+ body = ""
99
+ if c.action.body is not None: # the presence and size of a body, never its content
100
+ body = f" [JSON body, {len(json.dumps(c.action.body, separators=(',', ':')))} bytes]"
101
+ typer.echo(
102
+ f"{c.id} {c.action.method} {c.path}{body} as {c.principal or 'anonymous'} "
103
+ f"-> expect {c.expected.outcome.value} ({c.expected.reason})"
104
+ )
105
+ writes = sum(1 for c in cases if c.action.is_write)
106
+ note = f" ({writes} are writes: fixture transport only)" if writes else ""
107
+ typer.echo(f"{len(cases)} requests planned{note}; none sent.")
108
+
109
+
110
+ def _summarize(result: RunResult, saved: Path | None) -> None:
111
+ counts = Counter(c.status.value for c in result.cases)
112
+ typer.echo(f"boundarycheck {result.tool_version} | scope {result.scope_id} | transport {result.transport}")
113
+ typer.echo(
114
+ "cases: " + ", ".join(f"{s.value}: {counts.get(s.value, 0)}" for s in Status) + f" (total {len(result.cases)})"
115
+ )
116
+ findings = [c for c in result.cases if c.status is Status.FINDING_CANDIDATE]
117
+ for c in findings[:50]:
118
+ typer.echo(f" FINDING {c.id} {c.rule_id} [{c.severity}] {c.key}: {c.detail}")
119
+ if len(findings) > 50:
120
+ typer.echo(f" ... and {len(findings) - 50} more in the report")
121
+ problems = [c for c in result.cases if c.status not in (Status.FINDING_CANDIDATE, Status.NO_ISSUE_OBSERVED)]
122
+ for status, group in sorted(
123
+ {s: [c for c in problems if c.status is s] for s in {c.status for c in problems}}.items(),
124
+ key=lambda kv: kv[0].value,
125
+ ):
126
+ typer.echo(f" {status.value}: {len(group)} (first: {group[0].key}: {group[0].detail})")
127
+ for note in result.limitations:
128
+ if "--reads-only" in note or "not exercised" in note:
129
+ typer.echo(f" note: {note}")
130
+ if saved is not None:
131
+ typer.echo(f"run {result.run_id} saved to {saved}")
132
+ typer.echo(f"exit code {result.exit_code}. Note: no_issue_observed does not mean the target is secure.")
133
+
134
+
135
+ async def _run_fixture(cfg: Any, variant: str | None, flaws: list[str] | None, reads_only: bool) -> RunResult:
136
+ from boundarycheck.transports.lab_fixture import LabFixtureTransport # noqa: PLC0415
137
+
138
+ async with LabFixtureTransport.open(cfg, variant=variant, flaws=flaws) as transport:
139
+ return await run(cfg, transport, reads_only=reads_only)
140
+
141
+
142
+ async def _run_live(cfg: Any, reads_only: bool) -> RunResult:
143
+ from boundarycheck.transports.live import LiveTransport # noqa: PLC0415
144
+
145
+ transport = LiveTransport.from_config(cfg, os.environ)
146
+ try:
147
+ return await run(cfg, transport, reads_only=reads_only)
148
+ finally:
149
+ await transport.aclose()
150
+
151
+
152
+ @app.command(name="test")
153
+ def check_cmd(
154
+ config: Config_,
155
+ transport: Annotated[
156
+ str,
157
+ typer.Option("--transport", "-t", help="fixture (in-process lab) or live (loopback only)."),
158
+ ] = "fixture",
159
+ runs_dir: Runs_ = DEFAULT_RUNS,
160
+ no_save: Annotated[bool, typer.Option("--no-save", help="Print the summary but store nothing.")] = False,
161
+ fixture_variant: Annotated[
162
+ str | None,
163
+ typer.Option("--fixture-variant", help="Lab adapter only: patched or vulnerable."),
164
+ ] = None,
165
+ fixture_flaws: Annotated[
166
+ str | None,
167
+ typer.Option(
168
+ "--fixture-flaws",
169
+ help="Lab adapter only: comma-separated flaw names (vulnerable variant).",
170
+ ),
171
+ ] = None,
172
+ reads_only: Annotated[
173
+ bool,
174
+ typer.Option(
175
+ "--reads-only",
176
+ help="Leave the declared write checks out (they need the fixture's state diff). The report says so.",
177
+ ),
178
+ ] = False,
179
+ ) -> None:
180
+ """Run the checks and judge every result against the declared policy."""
181
+ if transport not in ("fixture", "live"):
182
+ _fail("--transport must be 'fixture' or 'live'")
183
+ cfg = _load(config)
184
+ flaws = [f.strip() for f in fixture_flaws.split(",") if f.strip()] if fixture_flaws is not None else None
185
+ try:
186
+ result = asyncio.run(
187
+ _run_fixture(cfg, fixture_variant, flaws, reads_only)
188
+ if transport == "fixture"
189
+ else _run_live(cfg, reads_only)
190
+ )
191
+ except (TransportUnavailable, EgressViolation) as exc:
192
+ _fail(str(exc))
193
+ except Exception as exc:
194
+ if os.environ.get("BOUNDARYCHECK_DEBUG"):
195
+ traceback.print_exc()
196
+ _fail(f"internal error ({type(exc).__name__}); set BOUNDARYCHECK_DEBUG=1 for a traceback")
197
+ saved: Path | None = None
198
+ if not no_save:
199
+ try:
200
+ saved = RunStore(runs_dir).save(result, to_json(result), to_markdown(result), _secrets_of(result, cfg))
201
+ except (StoreError, SecretLeakError) as exc:
202
+ _fail(str(exc))
203
+ _summarize(result, saved)
204
+ raise typer.Exit(result.exit_code)
205
+
206
+
207
+ def _secrets_of(result: RunResult, cfg: Any) -> list[str]:
208
+ """Every credential value used in this run (re-read from the environment for the live transport;
209
+ the fixture transport's tokens are scanned for inside the engine, which sees them first)."""
210
+ return [
211
+ os.environ[p.credential.env]
212
+ for p in cfg.principals.values()
213
+ if p.credential and p.credential.env and p.credential.env in os.environ
214
+ ]
215
+
216
+
217
+ @app.command()
218
+ def report(
219
+ run_id: Annotated[str, typer.Option("--run", help="Run id (see list-runs).")],
220
+ fmt: Annotated[str, typer.Option("--format", "-f", help="json or md.")] = "md",
221
+ runs_dir: Runs_ = DEFAULT_RUNS,
222
+ ) -> None:
223
+ """Print a stored report."""
224
+ try:
225
+ typer.echo(RunStore(runs_dir).read_report(run_id, fmt), nl=False)
226
+ except StoreError as exc:
227
+ _fail(str(exc))
228
+
229
+
230
+ @app.command(name="list-runs")
231
+ def list_runs(runs_dir: Runs_ = DEFAULT_RUNS) -> None:
232
+ """List stored runs, newest first."""
233
+ try:
234
+ rows = RunStore(runs_dir).list_runs()
235
+ except StoreError as exc:
236
+ _fail(str(exc))
237
+ if not rows:
238
+ typer.echo("no runs")
239
+ for r in rows:
240
+ typer.echo(
241
+ f"{r['run_id']} scope {r['scope_id']} cases {r['total']} exit {r['exit_code']} "
242
+ f"started {r['started_at']}"
243
+ )
244
+
245
+
246
+ @app.command()
247
+ def purge(
248
+ older_than: Annotated[str, typer.Option("--older-than", help="Age such as 30d, 12h or 45m.")],
249
+ runs_dir: Runs_ = DEFAULT_RUNS,
250
+ ) -> None:
251
+ """Delete stored runs older than the given age. Only directories that look like runs are touched."""
252
+ try:
253
+ removed = RunStore(runs_dir).purge(parse_age(older_than))
254
+ except StoreError as exc:
255
+ _fail(str(exc))
256
+ typer.echo(f"removed {len(removed)} run(s)" + "".join(f"\n {r}" for r in removed))
257
+
258
+
259
+ if __name__ == "__main__": # pragma: no cover
260
+ app()
261
+ sys.exit(0)
@@ -0,0 +1,297 @@
1
+ """The comparator: what was OBSERVED against what was EXPECTED (docs/contract.md s4).
2
+
3
+ Like the oracle it imports nothing that talks to a target. A status code is never trusted alone:
4
+ a matching `allow` is also checked against the declared field projection and, for lists, against
5
+ the declared set of objects the principal may see.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import re
13
+ from collections.abc import Iterator, Mapping, Sequence
14
+ from dataclasses import dataclass, replace
15
+ from typing import Any
16
+
17
+ from boundarycheck.config import Action, Config
18
+ from boundarycheck.model import Observation, Outcome, Status
19
+ from boundarycheck.statediff import StateChange
20
+
21
+ MUTATION_RULE = "BC-MUTATION-01"
22
+
23
+ ENVELOPE = ("items", "next_cursor", "total")
24
+ _SAFE = re.compile(r"[^A-Za-z0-9_.\[\]-]")
25
+ SIGNATURE_HEADERS = ("content-type", "cache-control", "www-authenticate")
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class Verdict:
30
+ status: Status
31
+ observed: str | None
32
+ detail: str
33
+ rule_id: str
34
+ severity: str | None = None
35
+ confidence: str | None = None
36
+
37
+
38
+ def classify(observation: Observation) -> Outcome | None:
39
+ """Map an HTTP status to a decision. Anything else is unmapped (None): never guessed."""
40
+ status = observation.status
41
+ if status is None:
42
+ return None
43
+ if 200 <= status < 300:
44
+ return Outcome.ALLOW
45
+ return {
46
+ 401: Outcome.DENY_UNAUTHENTICATED,
47
+ 403: Outcome.DENY_FORBIDDEN,
48
+ 404: Outcome.DENY_NOT_FOUND,
49
+ }.get(status)
50
+
51
+
52
+ def _clean(text: object, limit: int = 60) -> str:
53
+ """Names that came from the target are shown only in a restricted alphabet."""
54
+ return _SAFE.sub("?", str(text))[:limit]
55
+
56
+
57
+ def paths(value: Any, prefix: str = "") -> Iterator[str]:
58
+ """Every field path in a JSON value: `a`, `a.b`, `items[].id` (lists are transparent)."""
59
+ if isinstance(value, dict):
60
+ for key, inner in value.items():
61
+ path = f"{prefix}.{key}" if prefix else str(key)
62
+ yield path
63
+ yield from paths(inner, path)
64
+ elif isinstance(value, list):
65
+ for element in value:
66
+ yield from paths(element, f"{prefix}[]")
67
+
68
+
69
+ def _exposed(found: set[str], allowed: frozenset[str], prefix: str = "") -> list[str]:
70
+ return sorted(prefix + p for p in found if p not in allowed)
71
+
72
+
73
+ def _names(items: list[str]) -> str:
74
+ shown = ", ".join(_clean(i) for i in items[:5])
75
+ return shown + (f" (and {len(items) - 5} more)" if len(items) > 5 else "")
76
+
77
+
78
+ def _finding(case: Any, observed: Outcome, obs: Observation) -> Verdict:
79
+ exp = case.expected
80
+ base = f"expected {exp.outcome.value} ({exp.reason}), observed {observed.value} (HTTP {obs.status})"
81
+ if observed is Outcome.ALLOW:
82
+ severity = "medium" if exp.reason == "tenant_inactive" else "high"
83
+ return Verdict(
84
+ Status.FINDING_CANDIDATE,
85
+ observed.value,
86
+ base + ": access was granted where the policy denies it",
87
+ case.rule_id,
88
+ severity,
89
+ "medium",
90
+ )
91
+ if exp.outcome is Outcome.ALLOW:
92
+ return Verdict(
93
+ Status.FINDING_CANDIDATE,
94
+ observed.value,
95
+ base + ": denied where the policy allows it (fails closed; check the policy first)",
96
+ case.rule_id,
97
+ "low",
98
+ "medium",
99
+ )
100
+ if exp.outcome is Outcome.DENY_NOT_FOUND and observed is Outcome.DENY_FORBIDDEN:
101
+ return Verdict(
102
+ Status.FINDING_CANDIDATE,
103
+ observed.value,
104
+ base + ": the response reveals that the object exists (existence oracle)",
105
+ case.rule_id,
106
+ "medium",
107
+ "medium",
108
+ )
109
+ return Verdict(
110
+ Status.FINDING_CANDIDATE,
111
+ observed.value,
112
+ base + ": a different denial than declared",
113
+ case.rule_id,
114
+ "low",
115
+ "medium",
116
+ )
117
+
118
+
119
+ def compare(config: Config, case: Any, observation: Observation) -> Verdict:
120
+ if observation.error == "redirect":
121
+ return Verdict(
122
+ Status.POLICY_DENIED,
123
+ None,
124
+ "a redirect was returned and is never followed",
125
+ case.rule_id,
126
+ )
127
+ if observation.error is not None:
128
+ return Verdict(
129
+ Status.INCOMPLETE,
130
+ None,
131
+ f"the request did not complete ({_clean(observation.error, 30)})",
132
+ case.rule_id,
133
+ )
134
+ observed = classify(observation)
135
+ if observed is None:
136
+ return Verdict(
137
+ Status.INCONCLUSIVE,
138
+ None,
139
+ f"HTTP {observation.status} does not map to a decision",
140
+ case.rule_id,
141
+ )
142
+ if observed is not case.expected.outcome:
143
+ return _finding(case, observed, observation)
144
+ ok = Verdict(
145
+ Status.NO_ISSUE_OBSERVED,
146
+ observed.value,
147
+ f"observed {observed.value} as declared",
148
+ case.rule_id,
149
+ )
150
+ if observed is not Outcome.ALLOW or case.action.method == "HEAD" or observation.status == 204:
151
+ return ok
152
+ return _check_allowed(config, case, observation, ok)
153
+
154
+
155
+ def _where(changes: Sequence[StateChange]) -> str:
156
+ """Names only (table, key, kind), restricted to a safe alphabet: a value never gets here."""
157
+ shown = ", ".join(f"{_clean(c.table)}:{_clean(c.key)} ({c.kind})" for c in changes[:3])
158
+ return shown + (f" and {len(changes) - 3} more" if len(changes) > 3 else "")
159
+
160
+
161
+ def compare_write(config: Config, case: Any, observation: Observation, changes: Sequence[StateChange]) -> Verdict:
162
+ """A write the policy says must be refused (docs/contract.md s9.4). What the target ANSWERED is
163
+ compared as for a read; what it DID to its own state is judged by an independent diff."""
164
+ verdict = compare(config, case, observation)
165
+ if not changes:
166
+ return verdict
167
+ status = observation.status
168
+ if status is not None and 200 <= status < 300:
169
+ # access was granted: the access rule stands, and the write is stated as a fact
170
+ return replace(verdict, detail=f"{verdict.detail}; state changed: {_where(changes)}")
171
+ observed = classify(observation)
172
+ shown = f"HTTP {status}" if status is not None else _clean(observation.error or "no response", 30)
173
+ return Verdict(
174
+ Status.FINDING_CANDIDATE,
175
+ observed.value if observed is not None else None,
176
+ f"the request was not accepted ({shown}) but state changed: {_where(changes)}",
177
+ MUTATION_RULE,
178
+ "high",
179
+ "high",
180
+ )
181
+
182
+
183
+ def _check_allowed(config: Config, case: Any, obs: Observation, ok: Verdict) -> Verdict: # noqa: PLR0911
184
+ try:
185
+ doc = json.loads(obs.body.decode("utf-8"))
186
+ except (ValueError, UnicodeDecodeError):
187
+ return Verdict(
188
+ Status.INCONCLUSIVE,
189
+ "allow",
190
+ "the response body is not JSON, so its fields cannot be checked",
191
+ case.rule_id,
192
+ )
193
+ if not isinstance(doc, dict):
194
+ return Verdict(Status.INCONCLUSIVE, "allow", "the response body is not a JSON object", case.rule_id)
195
+ action: Action = case.action
196
+ visible: frozenset[str] = case.expected.visible_fields or frozenset()
197
+ if action.paged:
198
+ spec = action.list_spec
199
+ envelope = set(ENVELOPE) | ({spec.total_field} if spec is not None and spec.total_field else set())
200
+ extra = sorted(set(doc) - envelope)
201
+ if extra:
202
+ return _exposure(case, f"unexpected top-level field(s): {_names(extra)}")
203
+ items = doc.get("items")
204
+ if not isinstance(items, list) or not all(isinstance(i, dict) for i in items):
205
+ return Verdict(Status.INCONCLUSIVE, "allow", "'items' is not a list of objects", case.rule_id)
206
+ leaked = _exposed({p for i in items for p in paths(i)}, visible, "items[].")
207
+ if leaked:
208
+ return _exposure(case, f"undeclared field(s) in items: {_names(leaked)}")
209
+ else:
210
+ leaked = _exposed(set(paths(doc)), visible)
211
+ if leaked:
212
+ return _exposure(case, f"undeclared field(s) exposed: {_names(leaked)}")
213
+ if action.list_spec is not None:
214
+ return _check_list(config, case, doc, ok)
215
+ return ok
216
+
217
+
218
+ def _exposure(case: Any, detail: str) -> Verdict:
219
+ role = case.expected.role or "?"
220
+ return Verdict(
221
+ Status.FINDING_CANDIDATE,
222
+ "allow",
223
+ f"{detail} (role {_clean(role)}; names only, values are never reported)",
224
+ "BC-FIELDS-01",
225
+ "medium",
226
+ "medium",
227
+ )
228
+
229
+
230
+ def _check_list(config: Config, case: Any, doc: dict[str, Any], ok: Verdict) -> Verdict:
231
+ spec = case.action.list_spec
232
+ visible: frozenset[str] = case.expected.visible_ids or frozenset()
233
+ known = {r.ids[spec.id_key]: r.key for r in config.resources if r.kind == spec.kind and spec.id_key in r.ids}
234
+ ids = [i.get(spec.item_id_field) for i in doc["items"]]
235
+ leaked = [f"{known[i]} ({i})" for i in ids if isinstance(i, str) and i in known and i not in visible]
236
+ if leaked:
237
+ return Verdict(
238
+ Status.FINDING_CANDIDATE,
239
+ "allow",
240
+ f"the list names object(s) this principal may not see: {', '.join(leaked)}",
241
+ "BC-LIST-01",
242
+ "high",
243
+ "medium",
244
+ )
245
+ total = doc.get(spec.total_field) if spec.total_field is not None else None
246
+ if spec.total_field is not None and total != len(visible):
247
+ return Verdict(
248
+ Status.FINDING_CANDIDATE,
249
+ "allow",
250
+ f"list total is {_clean(total, 20)} but the principal may see {len(visible)} object(s)",
251
+ "BC-LIST-01",
252
+ "high",
253
+ "medium",
254
+ )
255
+ unknown = [i for i in ids if not isinstance(i, str) or i not in known]
256
+ if unknown:
257
+ return Verdict(
258
+ Status.INCONCLUSIVE,
259
+ "allow",
260
+ f"the list names {len(unknown)} object(s) that the config does not declare",
261
+ case.rule_id,
262
+ )
263
+ return ok
264
+
265
+
266
+ # ---------------------------------------------------------------------------- concealment ----
267
+ def _canonical(value: Any, ignore: frozenset[str]) -> Any:
268
+ if isinstance(value, dict):
269
+ return {k: _canonical(v, ignore) for k, v in value.items() if k not in ignore}
270
+ if isinstance(value, list):
271
+ return [_canonical(v, ignore) for v in value]
272
+ return value
273
+
274
+
275
+ def signature_parts(observation: Observation, ignore_fields: list[str]) -> dict[str, str]:
276
+ """The comparable shape of a response: status, selected headers, body (volatile fields removed)."""
277
+ headers: Mapping[str, str] = {k.lower(): v for k, v in observation.headers.items()}
278
+ try:
279
+ body = json.dumps(
280
+ _canonical(json.loads(observation.body.decode("utf-8")), frozenset(ignore_fields)),
281
+ sort_keys=True,
282
+ )
283
+ except (ValueError, UnicodeDecodeError):
284
+ body = "raw:" + hashlib.sha256(observation.body).hexdigest()
285
+ parts = {"status": str(observation.status), "body": body}
286
+ parts.update({f"header:{name}": headers.get(name, "") for name in SIGNATURE_HEADERS})
287
+ return parts
288
+
289
+
290
+ def signature(observation: Observation, ignore_fields: list[str]) -> str:
291
+ return hashlib.sha256(json.dumps(signature_parts(observation, ignore_fields), sort_keys=True).encode()).hexdigest()
292
+
293
+
294
+ def differences(a: Observation, b: Observation, ignore_fields: list[str]) -> list[str]:
295
+ """Which parts of two responses differ: 'status', 'body' or 'header:<name>' (never the content)."""
296
+ pa, pb = signature_parts(a, ignore_fields), signature_parts(b, ignore_fields)
297
+ return sorted(k for k in pa if pa[k] != pb[k])