Setting the file. One moment.
Skill 23 · Secret Serialization
Subchapter 23.2
references/python.mdMarkdown10 KBView on GitHub
Use this when reviewing Python code. These notes refine the core skill; they do not add reporting scope. “Generated paths” and “raw attribute access” have the meanings defined in SKILL.md under Explicit Exclusion.
| Type | Generated paths that include every field by default | What blocks them |
|---|---|---|
@dataclasses.dataclass | __repr__ (so str(), f-strings, %s, %r), dataclasses.asdict, dataclasses.astuple | field(repr=False) blocks repr only. Nothing blocks asdict; wrap the value or keep it off the instance. |
attrs @define / @attr.s | __repr__, attrs.asdict, attrs.astuple | field(repr=False) blocks repr only. asdict still includes the field unless the call passes filter=. |
pydantic.BaseModel | __repr__, __str__, model_dump, model_dump_json, .dict(), .json(), FastAPI response serialization | SecretStr / SecretBytes redact all of these (**********). Field(repr=False) blocks __repr__ and __str__. Field(exclude=True) blocks dump, JSON, and response serialization. A plain field is fully excluded only with both flags. |
pydantic_settings.BaseSettings | Same as BaseModel; often logged wholesale at startup | SecretStr for every credential setting. Plain fields follow the BaseModel flag rules. |
typing.NamedTuple | __repr__, _asdict, iteration and unpacking | None. Do not hold credentials on a NamedTuple. |
TypedDict / dict | repr, json.dumps, iteration | None. Redact at the sink. |
msgspec.Struct | __repr__, msgspec.to_builtins, encoders | field(repr=False) on newer versions blocks repr only. |
| Plain class | None. The default repr is <Class object at 0x...>. | Nothing to block. A hand-written __repr__ that prints fields creates a generated path. |
Every stored attribute on these types, including one with repr=False, exclude=True, or both, is still visible through raw attribute access. SecretStr hides the value from repr-based rendering of vars(obj), but pickle and a recursive default=vars walk still reach the raw string stored inside the wrapper.
dataclass(init=False) with a hand-written __init__ still generates __repr__ and still registers annotated fields with asdict. A custom constructor blocks nothing.
functools.cached_property stores its result in instance.__dict__ after first access. It does not appear in the generated __repr__ or in asdict, so it matters only when a raw attribute sink receives the instance.
The Sentry SDK serializer, used for span data, set_context, set_extra, and exception frame locals, renders unknown objects with repr(). It does not walk __dict__. A fully excluded field does not reach Sentry through that serializer.
| Sink | Why it leaks | Safe form |
|---|---|---|
safe_kwargs[key] = str(value) over **kwargs | Stringifies client and config objects passed as tool or task arguments | Allowlist scalar keys; record type(value).__name__ for objects; redact keys matching credential names |
span.set_data(key, obj), set_context(name, obj), set_extra | The Sentry serializer renders objects with repr() | Pass explicit scalar fields only |
span.set_attribute(key, str(obj)) in OpenTelemetry | OpenTelemetry drops non-primitive values, so callers stringify with str() or json.dumps first | Pass explicit scalar fields only |
logger.info("... %s", obj), {obj} in f-strings, logger.exception(...) | Interpolates __repr__; Sentry include_local_variables=True (the default) captures frame locals by repr on exceptions | Log identifiers, not objects; exclude credential fields from repr |
json.dumps(obj, default=str), default=repr | Falls back to repr for unknown objects | An explicit to_dict() with an allowlist |
json.dumps(obj, default=vars), vars(obj), obj.__dict__ into a log, span, or payload | Raw attribute access, including fully excluded fields, cached properties, and the value inside a SecretStr when the walk recurses | An explicit to_dict() with an allowlist |
dataclasses.asdict(obj) / model.model_dump() into a response, cache, or queue | Includes every field regardless of repr=False | exclude={...} or a separate public DTO |
pickle.dumps(obj) into Redis or a task queue | Raw attribute access: serializes __dict__, including fully excluded fields and cached properties | Rebuild clients from config at the consumer |
pprint, print(obj) in shipped code | repr | Remove, or log identifiers |
rich.inspect(obj) in shipped code | Raw attribute access: lists attribute values | Remove |
Report (high): credential field added to a dataclass that existing instrumentation stringifies
@dataclasses.dataclass(init=False)
class RpcClient:
referrer: str
_base_url: str | None
_shared_secret: str | None # new field, no repr=False
def __init__(self, referrer, *, base_url=None, shared_secret=None):
self.referrer = referrer
self._base_url = base_url
self._shared_secret = shared_secret# tracing.py, already on the default branch, not in this diff
for key, value in kwargs.items():
safe_kwargs[key] = str(value) # rpc_client=RpcClient(...) lands here
span.set_data("gen_ai.tool.call.arguments", safe_kwargs)Evidence: str(rpc_client) renders RpcClient(referrer=..., _base_url=..., _shared_secret='...'). The tool-tracing decorator passes every kwarg through str() into a span attribute, and tools receive rpc_client as a kwarg. Fix: _shared_secret: str | None = dataclasses.field(repr=False), and have the sink record type(value).__name__ for non-scalar values.
Report (medium): unexcluded field, instances travel, no sink found
@dataclass
class WebhookConfig:
url: str
signing_secret: str
def register(config: WebhookConfig) -> None:
dispatcher.enqueue("register_webhook", config=config)Evidence: WebhookConfig.__repr__ includes signing_secret, and instances are enqueued as task kwargs. A repository search found no task instrumentation that serializes kwargs. Fix: signing_secret: str = field(repr=False), or pass config.url and read the secret inside the task.
Report (high): partial exclusion with a sink on the unblocked path
@dataclass
class Settings:
api_key: str = field(repr=False)
cache.set("settings", json.dumps(asdict(settings)))Evidence: repr=False does not affect asdict, and the cache write serializes the key. Fix: build an explicit dict of non-secret fields for the cache.
Report (medium): new wholesale sink with no filter
def trace_call(func):
def wrapper(*args, **kwargs):
with start_span() as span:
span.set_data("call.kwargs", {k: str(v) for k, v in kwargs.items()})
return func(*args, **kwargs)
return wrapperEvidence: every kwarg is stringified into span data with no allowlist or type filter, and no credential-bearing caller was traced yet. Fix: record int, float, bool, and short str values; record type(v).__name__ for everything else; redact keys matching credential names.
Do not report: credential never stored on the instance
@dataclass
class RpcClient:
referrer: str
@property
def shared_secret(self) -> str:
return os.environ["RPC_SHARED_SECRET"]A plain property is not a dataclass field and does not write to __dict__. Switching it to cached_property would make vars(obj) leak after first access.
Report (high): Field(exclude=True) with a str() sink
class Settings(BaseModel):
service: str
api_key: str = Field(exclude=True)
span.set_data("settings", str(settings))Evidence: exclude=True omits api_key from model_dump and response serialization. str(settings) and repr(settings) still contain the raw key, and the span records str(settings). Fix: api_key: str = Field(repr=False, exclude=True), or use SecretStr. repr=False alone still leaks through model_dump.
Report (high): fully excluded field with a raw attribute sink
class Settings(BaseModel):
service: str
api_key: str = Field(repr=False, exclude=True)
redis.set("settings", pickle.dumps(settings))Evidence: both flags block every generated path, but pickle serializes __dict__, which holds the raw key, into a cache entry. SecretStr would not help, because it pickles its raw value. Fix: cache settings.model_dump() and read the key from the secret source at the consumer.
Do not report: fully excluded field with only generated-path sinks
class Settings(BaseModel):
service: str
api_key: str = Field(repr=False, exclude=True)
logger.info("loaded %s", settings)
return settings.model_dump()repr, str, and model_dump all omit api_key, and no sink reads __dict__.
Do not report: pydantic SecretStr
class Settings(BaseSettings):
database_password: SecretStrrepr, str, and model_dump render **********. Report only if a changed call site passes get_secret_value() to a sink, or a raw attribute sink such as pickle receives the instance.
Do not report: sink already filters
SCALARS = (str, int, float, bool, type(None))
safe_kwargs = {
k: (v if isinstance(v, SCALARS) and not is_credential_key(k) else type(v).__name__)
for k, v in kwargs.items()
}from sentry_sdk.serializer import serialize
def test_client_serialization_excludes_secret():
client = RpcClient(referrer="test", shared_secret="shared-secret-value")
assert "shared-secret-value" not in json.dumps(serialize({"client": client}))
assert "shared-secret-value" not in repr(client)Use the serializer the real sink uses. A repr check alone misses the asdict and __dict__ paths.