sentrykit 0.1.0rc1__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.
- sentrykit/__init__.py +200 -0
- sentrykit/audit.py +967 -0
- sentrykit/cedar.py +750 -0
- sentrykit/cli.py +1405 -0
- sentrykit/config.py +300 -0
- sentrykit/constraints.py +928 -0
- sentrykit/context.py +393 -0
- sentrykit/decorator.py +252 -0
- sentrykit/engine.py +1509 -0
- sentrykit/envelope.py +513 -0
- sentrykit/errors.py +252 -0
- sentrykit/integrations/__init__.py +1 -0
- sentrykit/integrations/base.py +767 -0
- sentrykit/integrations/fastapi.py +361 -0
- sentrykit/integrations/flask.py +342 -0
- sentrykit/integrations/mcp.py +929 -0
- sentrykit/integrations/pydantic_ai.py +728 -0
- sentrykit/integrations/tools.py +479 -0
- sentrykit/masking.py +459 -0
- sentrykit/policy/__init__.py +40 -0
- sentrykit/policy/loader.py +764 -0
- sentrykit/policy/pack/10-rbac.cedar +9 -0
- sentrykit/policy/pack/20-groups.cedar +9 -0
- sentrykit/policy/pack/30-ownership.cedar +8 -0
- sentrykit/policy/pack/40-delegation.cedar +40 -0
- sentrykit/policy/pack/50-expiry.cedar +24 -0
- sentrykit/policy/pack/60-break-glass.cedar +34 -0
- sentrykit/policy/pack/70-separation-of-duties.cedar +22 -0
- sentrykit/policy/pack/80-jit-elevation.cedar +32 -0
- sentrykit/policy/pack/entities.json +3 -0
- sentrykit/policy/pack/pack.cedarschema +45 -0
- sentrykit/policy/pack/templates/time-boxed-grant.cedartemplate +5 -0
- sentrykit/py.typed +0 -0
- sentrykit/registry.py +666 -0
- sentrykit/stores/__init__.py +116 -0
- sentrykit/stores/base.py +870 -0
- sentrykit/stores/composite.py +635 -0
- sentrykit/stores/filesystem.py +400 -0
- sentrykit/stores/jsonfile.py +701 -0
- sentrykit/stores/jsonl.py +357 -0
- sentrykit/stores/memory.py +500 -0
- sentrykit-0.1.0rc1.dist-info/METADATA +541 -0
- sentrykit-0.1.0rc1.dist-info/RECORD +46 -0
- sentrykit-0.1.0rc1.dist-info/WHEEL +4 -0
- sentrykit-0.1.0rc1.dist-info/entry_points.txt +20 -0
- sentrykit-0.1.0rc1.dist-info/licenses/LICENSE +201 -0
sentrykit/errors.py
ADDED
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
"""Exception hierarchy for sentrykit.
|
|
2
|
+
|
|
3
|
+
Every error carries structured, machine-readable detail so context providers can render a
|
|
4
|
+
useful response (and so the audit record is precise). Never raise a bare ``Exception``.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class SentrykitError(Exception):
|
|
13
|
+
"""Base class for all sentrykit errors.
|
|
14
|
+
|
|
15
|
+
When :attr:`audit_failure` is set, both halves of it matter. The refusal is *correct*: it
|
|
16
|
+
is the one the decision produced, it stands, and it is not softened because nobody could
|
|
17
|
+
write it down — deciding and recording are separate guarantees, and losing the second does
|
|
18
|
+
not forfeit the first. And the refusal is *unrecorded*: there is no audit record that this
|
|
19
|
+
boundary was tested, so nothing in the trail will later show a caller probing which
|
|
20
|
+
actions exist and which argument values are accepted.
|
|
21
|
+
|
|
22
|
+
It lives on the base class because any refusal can arrive this way, and it travels with
|
|
23
|
+
the exception so that whoever renders the refusal — a provider's response, a host's own
|
|
24
|
+
error handler, a report — can say so at the point a reader is looking. The alternative is
|
|
25
|
+
to leave the fact in an operational log, and the operational channel is deliberately not
|
|
26
|
+
the audit trail: a fact that only ever lands there is a fact nobody can prove afterwards.
|
|
27
|
+
|
|
28
|
+
Attributes:
|
|
29
|
+
audit_failure: The audit sink failure that stopped this refusal from being recorded,
|
|
30
|
+
or ``None`` — which is what it is on every refusal a reachable sink accepted, so
|
|
31
|
+
on all but a vanishing fraction of them.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
audit_failure: AuditUnavailable | None = None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class ConfigurationError(SentrykitError):
|
|
38
|
+
"""Raised when sentrykit is misconfigured (bad settings, missing backend, etc.)."""
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class NoContext(SentrykitError):
|
|
42
|
+
"""Raised when a protected callable is invoked with no resolvable principal.
|
|
43
|
+
|
|
44
|
+
This is a fail-closed condition: no ambient context and no explicit override means the
|
|
45
|
+
call is denied.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
def __init__(self, action: str) -> None:
|
|
49
|
+
self.action = action
|
|
50
|
+
super().__init__(f"no principal in context for action {action!r}; denying (fail-closed)")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class AuthzDenied(SentrykitError):
|
|
54
|
+
"""Raised when the coarse Cedar gate denies the invocation.
|
|
55
|
+
|
|
56
|
+
``engine_errors`` separates the two ways a call can fail to be authorized. A plain
|
|
57
|
+
denial has none: a policy said no, or no policy said yes. A denial carrying engine
|
|
58
|
+
errors means Cedar could not evaluate cleanly -- an unparseable policy, a missing
|
|
59
|
+
attribute -- and ``fail_mode="closed"`` turned that failure into a refusal. Operators
|
|
60
|
+
need to tell those apart, because the second is a bug in the policy set, not a correctly
|
|
61
|
+
enforced boundary.
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
def __init__(
|
|
65
|
+
self,
|
|
66
|
+
action: str,
|
|
67
|
+
resource: str | None,
|
|
68
|
+
determining_policies: list[str],
|
|
69
|
+
engine_errors: list[str] | None = None,
|
|
70
|
+
) -> None:
|
|
71
|
+
"""Record a refusal.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
action: The full Cedar uid of the refused action, e.g. ``Action::"tool.search"``
|
|
75
|
+
-- always the uid spelling, never the bare id, so an error message is
|
|
76
|
+
unambiguous about which entity type was involved.
|
|
77
|
+
resource: The full Cedar uid of the resource, in the same spelling.
|
|
78
|
+
determining_policies: Ids of the policies that decided it, named by their ``@id``
|
|
79
|
+
annotation where they declare one. Empty on a default deny, which means no
|
|
80
|
+
policy matched at all.
|
|
81
|
+
engine_errors: Cedar's own errors when this refusal came from an engine failure,
|
|
82
|
+
and empty when it is an ordinary policy denial.
|
|
83
|
+
"""
|
|
84
|
+
self.action = action
|
|
85
|
+
self.resource = resource
|
|
86
|
+
self.determining_policies = determining_policies
|
|
87
|
+
self.engine_errors = engine_errors or []
|
|
88
|
+
detail = (
|
|
89
|
+
f"denied: action={action!r} resource={resource!r} "
|
|
90
|
+
f"determining_policies={determining_policies}"
|
|
91
|
+
)
|
|
92
|
+
if self.engine_errors:
|
|
93
|
+
detail += f" engine_errors={self.engine_errors}"
|
|
94
|
+
super().__init__(detail)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class ReservedKey(SentrykitError):
|
|
98
|
+
"""Raised when caller-supplied data spells one of Cedar's reserved ``__`` keys.
|
|
99
|
+
|
|
100
|
+
Cedar's request JSON reserves record keys beginning with ``__`` for its own escape
|
|
101
|
+
forms: ``__entity`` promotes a plain record into a typed entity reference, and
|
|
102
|
+
``__extn`` into an extension value. A caller who can put either key inside an argument
|
|
103
|
+
can therefore hand the evaluator an entity reference of their own choosing, and an
|
|
104
|
+
argument-aware ``forbid`` will read it as a genuine one -- so
|
|
105
|
+
``forbid ... when { !(context.args.region in Group::"approved") }`` is satisfied by
|
|
106
|
+
passing the approved group itself as the region, because Cedar's ``in`` is reflexive.
|
|
107
|
+
|
|
108
|
+
sentrykit refuses the request instead of deciding it, and the refusal is deliberately
|
|
109
|
+
*not* arbitrated by ``fail_mode``: a forged request is not a broken policy set, and
|
|
110
|
+
``fail_mode="open"`` exists to tolerate operator error, never caller input.
|
|
111
|
+
|
|
112
|
+
This closes the *spelling*, not the general question of who chooses an entity's type. A
|
|
113
|
+
parameter a callable annotates as :class:`~sentrykit.cedar.EntityRef` is a caller-chosen
|
|
114
|
+
entity by construction, and the same reflexive ``in`` applies to it -- see
|
|
115
|
+
:func:`~sentrykit.cedar.coerce_value` for how a policy pins that down.
|
|
116
|
+
|
|
117
|
+
Attributes:
|
|
118
|
+
key: The reserved key that was supplied.
|
|
119
|
+
path: Where it appeared inside the request context, e.g. ``args.region`` or
|
|
120
|
+
``args.regions[2].id``. Empty when the value was coerced on its own.
|
|
121
|
+
"""
|
|
122
|
+
|
|
123
|
+
def __init__(self, key: str, path: str = "") -> None:
|
|
124
|
+
self.key = key
|
|
125
|
+
self.path = path
|
|
126
|
+
located = f" at {path!r}" if path else ""
|
|
127
|
+
super().__init__(
|
|
128
|
+
f"reserved key {key!r}{located} is not permitted in supplied data: keys "
|
|
129
|
+
"beginning with '__' are Cedar's own escape forms and may not be spelled by "
|
|
130
|
+
"a caller"
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
class ArgumentRejected(SentrykitError):
|
|
135
|
+
"""Raised (in strict mode) when a supplied argument violates its policy constraint."""
|
|
136
|
+
|
|
137
|
+
def __init__(self, name: str, reason: str, policy: str | None = None) -> None:
|
|
138
|
+
self.name = name
|
|
139
|
+
self.reason = reason
|
|
140
|
+
self.policy = policy
|
|
141
|
+
super().__init__(f"argument {name!r} rejected: {reason}")
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class SignatureDefaultRejected(SentrykitError):
|
|
145
|
+
"""Raised when the only value left for a governed argument is one the policy refuses.
|
|
146
|
+
|
|
147
|
+
The argument has a constraint, nothing the caller supplied survived it, no policy default
|
|
148
|
+
applies — and the callable's own signature default does not satisfy the constraint either.
|
|
149
|
+
Python would otherwise fill the slot from that default, which is how a bound could be
|
|
150
|
+
exceeded by a value no rule ever saw.
|
|
151
|
+
|
|
152
|
+
This is the same rule a *policy* default has always been held to: a default is checked
|
|
153
|
+
against the constraint that governs it, so omitting an argument is not a way around that
|
|
154
|
+
rule. A signature default is a default from a different source, and it answers to the
|
|
155
|
+
same check.
|
|
156
|
+
|
|
157
|
+
``declared`` says whose mistake it is. When it is true the refusing rule came from an
|
|
158
|
+
argument ceiling — reviewed, version-controlled policy text — so the operator's policy file
|
|
159
|
+
and their application code disagree about the same parameter, and every caller of the
|
|
160
|
+
action is affected equally. When it is false the rule came from this principal's own grant
|
|
161
|
+
data, so the refusal is specific to them and is ordinary authorization rather than a
|
|
162
|
+
misconfiguration.
|
|
163
|
+
|
|
164
|
+
Not a :class:`ConfigurationError` even in the ``declared`` case, for two reasons: it
|
|
165
|
+
refuses one call rather than failing the wiring, and there is no moment at which it could
|
|
166
|
+
fail the wiring instead, since nothing enumerates protected callables for a policy load to
|
|
167
|
+
check against. Classifying it with configuration faults would also make it unqueryable in
|
|
168
|
+
the audit trail, where it has its own outcome.
|
|
169
|
+
"""
|
|
170
|
+
|
|
171
|
+
def __init__(
|
|
172
|
+
self, name: str, reason: str, policy: str | None = None, *, declared: bool = False
|
|
173
|
+
) -> None:
|
|
174
|
+
"""Record the refusal.
|
|
175
|
+
|
|
176
|
+
Args:
|
|
177
|
+
name: The governed parameter with no usable value.
|
|
178
|
+
reason: Why the signature default was refused, from the rejection that produced
|
|
179
|
+
it — the rule's own sentence, so the caller reads the same explanation they
|
|
180
|
+
would have got had they proposed the value themselves.
|
|
181
|
+
policy: Id of the grant or the reviewed policy that carried the constraint.
|
|
182
|
+
declared: Whether that constraint came from an argument ceiling rather than from
|
|
183
|
+
grant data.
|
|
184
|
+
"""
|
|
185
|
+
self.name = name
|
|
186
|
+
self.reason = reason
|
|
187
|
+
self.policy = policy
|
|
188
|
+
self.declared = declared
|
|
189
|
+
source = "a reviewed argument ceiling" if declared else "this principal's grant"
|
|
190
|
+
super().__init__(
|
|
191
|
+
f"argument {name!r} has no value that may be used: nothing the caller supplied "
|
|
192
|
+
f"survived, no policy default applies, and the callable's own default is refused "
|
|
193
|
+
f"by {source} ({reason})"
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
class NoValidArguments(SentrykitError):
|
|
198
|
+
"""Raised when the caller supplied arguments and the policy rejected every one of them.
|
|
199
|
+
|
|
200
|
+
Deliberately raised even when defaults could complete the call. Filling in defaults after
|
|
201
|
+
discarding everything the caller asked for would answer a question they did not ask --
|
|
202
|
+
the caller wanted orders for one customer and would silently get their own. Partial
|
|
203
|
+
rejection is different: some of the request stood, so narrowing the rest to what the
|
|
204
|
+
principal is entitled to is a refinement rather than a substitution.
|
|
205
|
+
|
|
206
|
+
``allowed`` describes what the principal *may* pass, so the caller can retry correctly.
|
|
207
|
+
"""
|
|
208
|
+
|
|
209
|
+
def __init__(self, allowed: dict[str, Any], rejected: list[dict[str, Any]]) -> None:
|
|
210
|
+
self.allowed = allowed
|
|
211
|
+
self.rejected = rejected
|
|
212
|
+
super().__init__("no valid arguments remain after policy filtering")
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
class DefaultUnavailable(SentrykitError):
|
|
216
|
+
"""Raised when a required argument is missing and no policy default is configured."""
|
|
217
|
+
|
|
218
|
+
def __init__(self, name: str) -> None:
|
|
219
|
+
self.name = name
|
|
220
|
+
super().__init__(f"argument {name!r} is required but no policy default is configured")
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
class ValidationFailed(SentrykitError):
|
|
224
|
+
"""Raised when the filtered/defaulted arguments fail the callable's pydantic model.
|
|
225
|
+
|
|
226
|
+
``errors`` mirrors pydantic's structured ``ValidationError.errors()`` output.
|
|
227
|
+
"""
|
|
228
|
+
|
|
229
|
+
def __init__(self, errors: list[dict[str, Any]]) -> None:
|
|
230
|
+
self.errors = errors
|
|
231
|
+
super().__init__(f"argument validation failed with {len(errors)} error(s)")
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
class AuditUnavailable(SentrykitError):
|
|
235
|
+
"""Raised when an audit record could not be written to its sink.
|
|
236
|
+
|
|
237
|
+
An operational failure, not an authorization one — but under ``fail_mode="closed"`` it
|
|
238
|
+
still refuses the governed call, because an action nobody can prove happened is an action
|
|
239
|
+
that should not have happened ("can't prove it, don't do it", per the logging standards).
|
|
240
|
+
|
|
241
|
+
``sink`` names the backend that failed; ``failures`` carries one entry per sink when a
|
|
242
|
+
fan-out composite raised, so an operator can see whether one replica or all of them are
|
|
243
|
+
down.
|
|
244
|
+
"""
|
|
245
|
+
|
|
246
|
+
def __init__(
|
|
247
|
+
self, sink: str, reason: str, failures: list[dict[str, Any]] | None = None
|
|
248
|
+
) -> None:
|
|
249
|
+
self.sink = sink
|
|
250
|
+
self.reason = reason
|
|
251
|
+
self.failures = failures or []
|
|
252
|
+
super().__init__(f"audit sink {sink!r} could not accept the record: {reason}")
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Framework context providers, each behind its own optional extra."""
|