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.
- boundarycheck/__init__.py +3 -0
- boundarycheck/__main__.py +3 -0
- boundarycheck/cli.py +261 -0
- boundarycheck/comparator.py +297 -0
- boundarycheck/config.py +409 -0
- boundarycheck/engine.py +366 -0
- boundarycheck/evidence.py +125 -0
- boundarycheck/model.py +63 -0
- boundarycheck/netcheck.py +48 -0
- boundarycheck/oracle.py +100 -0
- boundarycheck/planner.py +66 -0
- boundarycheck/py.typed +0 -0
- boundarycheck/redact.py +97 -0
- boundarycheck/report.py +120 -0
- boundarycheck/statediff.py +43 -0
- boundarycheck/template.py +69 -0
- boundarycheck/transports/__init__.py +1 -0
- boundarycheck/transports/lab_fixture.py +213 -0
- boundarycheck/transports/live.py +213 -0
- boundarycheck/transports/sqlite_state.py +41 -0
- boundarycheck-0.1.0.dist-info/METADATA +207 -0
- boundarycheck-0.1.0.dist-info/RECORD +26 -0
- boundarycheck-0.1.0.dist-info/WHEEL +4 -0
- boundarycheck-0.1.0.dist-info/entry_points.txt +3 -0
- boundarycheck-0.1.0.dist-info/licenses/LICENSE +202 -0
- boundarycheck-0.1.0.dist-info/licenses/NOTICE +7 -0
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])
|