Secret Serialization

SentryOfficialPublished by Sentry

Skill
Review and audit
Security
Apache-2.0
No issues found

From the author

Finds secrets, tokens, passwords, and API keys that can leak through generated serialization: Python dataclass repr and asdict, attrs, pydantic model_dump, NamedTuple, JavaScript JSON.stringify and util.inspect, structured logs, tracing spans, and error reports. Use when asked to "check for secret serialization", "credential in repr", "repr=False audit", "secret in spans", "token in logs", or when a change adds a credential field to a dataclass, model, or config object, or adds code that stringifies whole objects or every kwarg into telemetry.

— the description by Sentry

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a systematic process for identifying and mitigating credential leaks that occur when sensitive data is stored in objects that are subsequently serialized by automated systems. Leaks often arise from the combination of a 'holder' (a class or data structure that stores a credential and provides a default serialization method) and a 'sink' (a logging, tracing, or reporting utility that serializes the entire object). Because these components are often developed independently, this skill emphasizes searching the entire repository for potential sinks rather than focusing solely on the changed code.

What it does

Identifies credential-bearing fields in data structures like dataclasses, Pydantic models, and JavaScript objects.
Maps generated serialization paths such as repr, asdict, model_dump, and JSON.stringify.
Detects wholesale serialization sinks that inadvertently capture sensitive object attributes.
Evaluates the effectiveness of field-level exclusion mechanisms against various serialization methods.
Provides guidance on remediating leaks through redaction, allowlisting, or structural changes.
Distinguishes between generated serialization paths and raw attribute access sinks.

When to use it

When reviewing changes that add credential fields to data models or configuration objects.
When auditing telemetry, logging, or error-reporting code that serializes entire objects or kwargs.
When responding to requests to check for secret serialization, credential exposure in repr, or token leaks in logs.
When a refactor moves a credential from a secure scope (like a closure) onto an object field.

Advantages

Prevents common, high-impact security vulnerabilities caused by indirect data exposure.
Provides a clear framework for evaluating the security of different serialization mechanisms.
Encourages a holistic view of the codebase by tracing the lifecycle of sensitive objects.
Offers actionable, concrete fix guidance for both holders and sinks.

Usage examples

“Check for secret serialization in the new UserConfig dataclass.”: The agent will inspect the dataclass for credential fields, verify if they are excluded from repr/asdict, and search the repository for any logging or tracing sinks that might serialize the UserConfig instance.
“Audit the new telemetry sink for credential leaks.”: The agent will analyze the sink's implementation to see if it performs wholesale serialization of objects and check if any credential-bearing objects are passed to it by callers.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/getsentry/secret-serialization/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip secret-serialization.zip -d .agents/skills

Documentation by Sentry

Secret Serialization Review

Find credentials that can leak because a type serializes itself and something upstream serializes whole objects.

A leak usually needs two changes that each look safe alone:

Holder: a credential is stored as a field on a type with generated repr, str, asdict, model_dump, toJSON, or property enumeration.
Sink: logging, tracing, error reporting, caching, or a response serializes whole objects or every kwarg (str(value), span.set_data(key, obj), logger.info("%s", obj), JSON.stringify(args)).

The two sides are often written months apart by different authors. Report either side on its own. Always search the existing tree for the other side, because it is frequently already on the default branch and absent from the diff.

Boundary

This skill covers indirect leaks through generated serialization and wholesale sinks.
Direct leaks, such as interpolating a token into a log message, belong to security-review. Report them here only when they come from a changed wholesale sink.
Hardcoded secret literals and committed .env files are out of scope.

References

Reference	Read When
`references/python.md`	Reviewing Python dataclasses, attrs, pydantic, NamedTuple, msgspec, logging, Sentry SDK, or OpenTelemetry code
`references/javascript-typescript.md`	Reviewing JavaScript or TypeScript classes, config objects, `JSON.stringify`, `util.inspect`, pino or winston, or Sentry and OpenTelemetry spans

Credential Fields

Treat a field as credential-bearing when its name, type, or source says so:

Names containing secret, token, password, passwd, pwd, api_key, apikey, access_key, private_key, signing_key, client_secret, bearer, credential, authorization, auth_header, cookie, session_key, dsn, connection_string, webhook_secret, hmac, or refresh_token.
Types such as SecretStr, SecretBytes, or wrappers around them.
Values assigned from environment variables, a secrets manager, or a constructor argument named like the above.

Explicit Exclusion

Separate two kinds of path:

Generated paths are produced by the type itself: __repr__ and __str__, asdict, model_dump, toJSON, and own-enumerable-property walks (JSON.stringify, util.inspect, spread). They are the holder's responsibility.
Raw attribute access reads the stored value directly: vars(obj), obj.__dict__, pickle, json.dumps(obj, default=vars). Every stored attribute is exposed this way, whatever flags the field has. Treat these only as sinks: report them when a sink in the repository applies one to a credential-bearing instance.

A field is fully excluded when every generated path its type has is blocked, whether by one mechanism or several together. A field is partially excluded when at least one generated path still includes it. No field-level mechanism defeats raw attribute access. Only not storing the value does, so fix raw attribute findings at the sink.

Mechanism	Blocks	Still includes the field
`dataclasses.field(repr=False)`, `attrs.field(repr=False)`	`__repr__`, `__str__`	`asdict`, `astuple`, raw access
Pydantic `Field(repr=False)`	`__repr__`, `__str__`	`model_dump`, `model_dump_json`, response serialization, raw access
Pydantic `Field(exclude=True)`	`model_dump`, `model_dump_json`, response serialization	`__repr__`, `__str__`, raw access
Pydantic `Field(repr=False, exclude=True)`	Every generated path	Raw access
JavaScript `#private` field	Every generated path	Nothing outside the class body
`Object.defineProperty(..., { enumerable: false })`	Every generated path	Explicit property reads, `Object.getOwnPropertyNames`
Hand-written `__repr__`, `__str__`, `toJSON`, or `[util.inspect.custom]` that omits the field	Only the path it overrides (a `__repr__` also serves `str()` when there is no `__str__`)	Every other generated path, raw access
Redacting wrapper: `SecretStr`, `SecretBytes`, a project `Redacted[T]`	Every generated path	`pickle` and recursive `__dict__` walks such as `default=vars`, which reach the value stored inside the wrapper
Not stored on the object: read inside the method, or held in a closure	Everything	Nothing

Do not treat underscore naming, TypeScript private, __slots__, type annotations, comments, dataclass(init=False), or a custom __init__ that still assigns the field as blocking any path.

Investigation Process

Read the changed hunk. Find new or modified credential fields on auto-serializing types, and new or modified code that serializes objects or kwargs into logs, spans, error context, caches, queues, or responses.
For each credential field, read the full class, decorators, base classes, and model config. List every generated path and check which ones the field's mechanisms block, using the table above.
Grep for where instances are constructed and passed. Instances handed to decorators, **kwargs, tool call arguments, task payloads, or middleware reach generic sinks.
Grep the whole repository for sinks that can see those instances, not only the diff. Useful patterns: str(value), repr(, asdict(, model_dump(, set_data(, set_attribute(, set_context(, set_extra(, JSON.stringify(, util.inspect(, loggers called with objects, and raw attribute access (vars(, __dict__, pickle.dumps(, default=vars).
For each changed sink, check for a key allowlist, redaction keyed on credential names, or a filter that replaces objects with their type name. Then grep for callers that pass credential-bearing objects into it.
Look at tests only to see whether one asserts the credential is absent from the serialized form. A missing test is fix guidance, not a finding.
Confirm the code ships. Skip fixtures, examples, generated code, and test-only helpers.

What To Report

Category	Report When
Unexcluded credential field	A credential field is added or moved onto a type with generated serialization, and no mechanism blocks any of its generated paths.
Partial exclusion	At least one generated path still includes the field, and a sink in the repository uses that path on instances of the type.
Raw attribute sink	A sink applies `vars`, `__dict__`, `pickle`, or `default=vars` to an instance that stores a credential, even if the field is fully excluded or wrapped.
Credential moved onto a holder	A refactor moves a credential from a lazy read or closure onto an object field.
Wholesale serialization sink	New or changed telemetry, logging, error-context, cache, or response code serializes every kwarg, every attribute, or whole objects without an allowlist or redaction.
Sink loses its filter	A change removes or weakens redaction, an allowlist, or object-to-type-name replacement in an existing sink.
Object passed to telemetry	A client, config, or settings object is passed to a span, log, or error-context call that stringifies it.

Severity

Level	Use For
high	The credential reaches a sink anywhere in the repository: log line, span attribute, error event, cache entry, persisted row, queue payload, or API response. The other side may predate the diff. Also a new wholesale sink whose existing callers pass credential-bearing objects.
medium	An unexcluded credential field whose instances leave the constructing module, after a repository search found no sink. Also a wholesale sink with no allowlist and no traced credential-bearing caller.
low	An unexcluded credential field whose instances never leave the constructing scope.

Do not downgrade because the sink or the holder is outside the diff. That is the normal shape of this bug.
Choose the lower severity when reachability depends on unproven preconditions.

What Not To Report

Fully excluded fields, unless a raw attribute sink receives the instance.
Partial exclusions when no sink in the repository uses the unblocked path.
Credentials read inside a method and never stored on the instance.
Placeholder or fake values in tests, fixtures, or examples.
Types with no generated serialization and no __dict__ or enumeration sink.
Sinks that already allowlist scalar keys, redact by credential name, or replace objects with a type name.
Pre-existing fields and sinks the diff does not touch, unless the diff connects them.
Style, naming, or missing-test-only observations.

Fix Guidance

Include one concrete fix per finding:

Holder: block every generated path, wrap the value in a redacting type, or stop storing it on the object.
Raw attribute sink: serialize an explicit allowlisted dict instead of the instance, or stop storing the credential on it. A field flag or wrapper does not fix it.
Sink: allowlist scalar keys, redact keys matching credential names, and record type(value).__name__ instead of str(value) for non-scalar values.
Regression test: serialize an instance with the same serializer the sink uses (for example sentry_sdk.serializer.serialize, json.dumps(asdict(obj)), JSON.stringify(obj), util.inspect(obj)) and assert the credential string is absent.

Finding Format

Title: name the field or sink and the leak path, for example "_shared_secret included in RpcClient dataclass repr".
Description: one or two sentences naming the generated path that exposes the credential, where instances travel, and the fix.
Evidence: 2 to 5 bullets naming the class, decorator, generated paths checked, the exclusion looked for, and every sink or caller traced, including those outside the diff.

Files

ATTRIBUTION.mdAdded by AutoGineer864 B
LICENSELicence file added by AutoGineer10.5 KiB
SKILL.md10.2 KiB
SOURCES.md6.8 KiB
SPEC.md5.1 KiB
references/javascript-typescript.md5.1 KiB
references/python.md9.9 KiB

references/python.md

Python Secret Serialization Notes

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.

Generated Serialization Paths

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.

High-Signal Sinks

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

Examples

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 wrapper

Evidence: 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: SecretStr

repr, 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()
}

Regression Test Shape

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.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs an API key, Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Sentry

Publisher

Sentry (Official)

Source

getsentry/skills · skills/secret-serialization · commit e94f222

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Sentry.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download secret-serialization.zip