Repository navigation
Expand file tree
/
Copy pathdata_collection.py
More file actions
334 lines (284 loc) · 11 KB
/
Copy pathdata_collection.py
File metadata and controls
334 lines (284 loc) · 11 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
"""
Data Collection configuration.
Implements the ``data_collection`` client option described in the Sentry SDK
"Data Collection" spec
(https://develop.sentry.dev/sdk/foundations/client/data-collection/).
``data_collection`` supersedes the single ``send_default_pii`` boolean with a
structured configuration that lets users enable or restrict automatically
collected data by category (user identity, cookies, HTTP headers, URL query params,
HTTP bodies, generative AI inputs/outputs, stack frame variables, source
context).
Resolution precedence (see :func:`_resolve_data_collection`):
* ``data_collection`` set, ``send_default_pii`` unset -> honour ``data_collection``
using the spec defaults for any omitted field.
* ``send_default_pii`` set, ``data_collection`` unset -> derive a
resolved ``DataCollection`` that mirrors what ``send_default_pii`` collects today.
* neither set -> treated as ``send_default_pii=False``.
* both set -> ``data_collection`` wins (it is the single source of truth); a
``DeprecationWarning`` is emitted for ``send_default_pii``.
"""
import warnings
from typing import TYPE_CHECKING, List, Mapping, Optional, Union, cast
from urllib.parse import parse_qs, urlencode
from sentry_sdk._types import SENSITIVE_DATA_SUBSTITUTE
if TYPE_CHECKING:
from typing import Any, Dict
from sentry_sdk._types import (
DataCollection,
GenAICollectionBehaviour,
GraphQLCollectionBehaviour,
HttpHeadersCollectionBehaviour,
KeyValueCollectionBehaviour,
)
# ``http_bodies`` defaults to this (collect everything the
# platform supports); an empty list is the explicit opt-out.
# response bodyies are not included here because we don't
# currently capture them (as of Jul 7 2026)
_ALL_HTTP_BODY_TYPES = [
"incoming_request",
"outgoing_request",
]
# Default number of source lines captured above and below a stack frame.
_DEFAULT_FRAME_CONTEXT_LINES = 5
# Collection modes for key-value data (cookies, headers, URL query params).
# snake_case (Python-only deviation from the spec's camelCase); never
# serialized to Sentry.
_VALID_KEY_VALUE_COLLECTION_BEHAVIOUR_MODES = ("off", "denylist", "allowlist")
# Values of keys that contain any of
# these terms (partial, case-insensitive) are always replaced with
# ``"[Filtered]"`` regardless of the configured collection mode.
_SENSITIVE_DENYLIST = [
"auth",
"token",
"secret",
"password",
"passwd",
"pwd",
"key",
"jwt",
"bearer",
"sso",
"saml",
"csrf",
"xsrf",
"credentials",
"session",
"sid",
"identity",
]
def _is_sensitive_key(key: str, extra_terms: "Optional[List[str]]" = None) -> bool:
"""
Return whether ``key`` matches the sensitive denylist using a partial,
case-insensitive substring match.
:param extra_terms: additional deny terms (e.g. user-provided) to consider
alongside the built-in `_SENSITIVE_DENYLIST`.
"""
lowered = key.lower()
for term in _SENSITIVE_DENYLIST:
if term in lowered:
return True
if extra_terms:
for term in extra_terms:
if term and term.lower() in lowered:
return True
return False
def _apply_data_collection_filtering_to_query_string(
query_string: str,
behaviour: "KeyValueCollectionBehaviour",
) -> "Union[str, None]":
parsed_qs = parse_qs(query_string, keep_blank_values=True)
filtered_qs = _apply_key_value_collection_filtering(
items=parsed_qs, behaviour=behaviour
)
if filtered_qs:
return urlencode(filtered_qs, doseq=True)
return None
def _apply_key_value_collection_filtering(
items: "Mapping[str, Any]",
behaviour: "KeyValueCollectionBehaviour",
substitute: "Any" = SENSITIVE_DATA_SUBSTITUTE,
) -> "Dict[str, Any]":
if behaviour["mode"] == "off":
return {}
result: "Dict[str, Any]" = {}
if behaviour["mode"] == "allowlist":
for key, value in items.items():
is_allowed = False
if isinstance(key, str):
lowered = key.lower()
is_allowed = any(
term and term.lower() in lowered
for term in behaviour.get("terms", [])
)
if is_allowed and not _is_sensitive_key(key):
result[key] = value
else:
result[key] = substitute
return result
# denylist behaviour
for key, value in items.items():
if isinstance(key, str) and _is_sensitive_key(
key=key, extra_terms=behaviour.get("terms", [])
):
result[key] = substitute
else:
result[key] = value
return result
def _map_from_send_default_pii(
*,
send_default_pii: bool,
include_local_variables: bool,
include_source_context: bool,
) -> "DataCollection":
"""
Build a fully-resolved ``DataCollection`` dict that mirrors the data
``send_default_pii`` collects today. Used when ``data_collection`` is not
provided explicitly.
"""
terms = [] if send_default_pii else ["forwarded", "-ip", "remote-", "via", "-user"]
return {
"provided_by_user": False,
"user_info": send_default_pii,
"cookies": {"mode": "denylist", "terms": terms},
# Headers are collected in both PII modes today (sensitive ones filtered
# when PII is off), so this never maps to "off".
"http_headers": {
"request": {"mode": "denylist", "terms": terms},
},
# Bodies are collected regardless of PII today, bounded by
# ``max_request_body_size``.
"http_bodies": list(_ALL_HTTP_BODY_TYPES),
"url_query_params": {"mode": "denylist", "terms": terms},
"graphql": {"document": send_default_pii, "variables": send_default_pii},
"gen_ai": {"inputs": send_default_pii, "outputs": send_default_pii},
"database_query_data": send_default_pii,
"queues": send_default_pii,
"stack_frame_variables": include_local_variables,
"frame_context_lines": (
_DEFAULT_FRAME_CONTEXT_LINES if include_source_context else 0
),
}
def _resolve_explicit(
d: "dict[str, Any]",
include_local_variables: bool,
include_source_context: bool,
) -> "DataCollection":
"""
Build a fully-resolved ``DataCollection`` from a user-supplied
``data_collection`` dict, filling in spec defaults for any omitted or
partially-specified field. Frame fields fall back to the legacy
``include_local_variables`` / ``include_source_context`` options when unset.
"""
# frame_context_lines accepts an integer or a boolean fallback (spec: True
# -> platform default of 5, False -> 0). bool is a subclass of int, so
# coerce explicitly before treating it as a line count.
frame_context_lines = d.get("frame_context_lines")
if frame_context_lines is None:
frame_context_lines = (
_DEFAULT_FRAME_CONTEXT_LINES if include_source_context else 0
)
elif isinstance(frame_context_lines, bool):
frame_context_lines = _DEFAULT_FRAME_CONTEXT_LINES if frame_context_lines else 0
stack_frame_variables = d.get("stack_frame_variables")
if stack_frame_variables is None:
stack_frame_variables = include_local_variables
# http_bodies: omitted means "all valid types"; [] is the explicit opt-out.
http_bodies = d.get("http_bodies")
http_bodies = (
list(http_bodies) if http_bodies is not None else list(_ALL_HTTP_BODY_TYPES)
)
return {
"provided_by_user": True,
"user_info": d.get("user_info", True),
"cookies": _kvcb_from_value(d.get("cookies") or {}),
"http_headers": _http_headers_from_value(d.get("http_headers") or {}),
"http_bodies": http_bodies,
"url_query_params": _kvcb_from_value(d.get("url_query_params") or {}),
"graphql": _graphql_from_value(d.get("graphql") or {}),
"gen_ai": _gen_ai_from_value(d.get("gen_ai") or {}),
"database_query_data": d.get("database_query_data", True),
"queues": d.get("queues", True),
"stack_frame_variables": stack_frame_variables,
"frame_context_lines": frame_context_lines,
}
def _kvcb_from_value(
val: "dict[str, Any]",
) -> "KeyValueCollectionBehaviour":
mode = val.get("mode", "denylist")
terms = val.get("terms", None)
if mode not in _VALID_KEY_VALUE_COLLECTION_BEHAVIOUR_MODES:
raise ValueError(
"Invalid collection mode {!r}. Must be one of {}.".format(
mode, _VALID_KEY_VALUE_COLLECTION_BEHAVIOUR_MODES
)
)
behaviour: "dict[str, Any]" = {"mode": mode}
if terms is not None:
behaviour["terms"] = list(terms)
return cast("KeyValueCollectionBehaviour", behaviour)
def _http_headers_from_value(
val: "dict[str, Any]",
) -> "HttpHeadersCollectionBehaviour":
return {
"request": (
_kvcb_from_value(val["request"])
if "request" in val
else _kvcb_from_value({"mode": "denylist"})
),
}
def _gen_ai_from_value(val: "dict[str, Any]") -> "GenAICollectionBehaviour":
return {
"inputs": val.get("inputs", True),
"outputs": val.get("outputs", True),
}
def _graphql_from_value(
val: "dict[str, Any]",
) -> "GraphQLCollectionBehaviour":
return {
"document": val.get("document", True),
"variables": val.get("variables", True),
}
def _resolve_data_collection(options: "Dict[str, Any]") -> "DataCollection":
"""
Resolve the effective ``DataCollection`` dict from client ``options``.
Reads ``data_collection``, ``send_default_pii``, ``include_local_variables``
and ``include_source_context`` and returns a fully-resolved dict with
concrete values for every field.
``data_collection`` must be a plain ``dict``.
"""
user_dc = options.get("_experiments", {}).get("data_collection")
send_default_pii = options.get("send_default_pii")
include_local_variables = (
bool(options.get("include_local_variables"))
if options.get("include_local_variables") is not None
else True
)
include_source_context = (
bool(options.get("include_source_context"))
if options.get("include_source_context") is not None
else True
)
if user_dc is not None:
if not isinstance(user_dc, dict):
raise TypeError(
"`data_collection` must be a dict, got {!r}.".format(
type(user_dc).__name__
)
)
if send_default_pii is not None:
warnings.warn(
"`send_default_pii` is deprecated and ignored when "
"`data_collection` is set.",
DeprecationWarning,
stacklevel=2,
)
return _resolve_explicit(
user_dc,
include_local_variables,
include_source_context,
)
return _map_from_send_default_pii(
send_default_pii=bool(send_default_pii),
include_local_variables=include_local_variables,
include_source_context=include_source_context,
)