Secrets Detection (Rust)

Rust-backed secrets detection and redaction for ContextForge and MCP Gateway.

Features

  • Detects likely credentials in prompt arguments, tool inputs, tool outputs, and resource content
  • Built-in detectors for AWS keys, Google API keys, GitHub tokens, Stripe keys, Slack tokens, and private key blocks
  • Optional broad detectors for generic API key assignments, JWT-like strings, long hex strings, and base64-like secrets
  • Blocking, redaction, or metadata-only reporting modes
  • Recursive scanning for nested dicts, lists, tuples, Pydantic-style objects, __dict__, and __slots__
  • Optional dotted field allowlist and denylist controls for structured payload scanning
  • Sanitized outward metadata that reports finding types and counts, not original secret values

Build

make install

Runtime Requirements

This plugin depends on cpex>=0.1.0,<0.2 and imports hook models from cpex.framework. The compiled Rust extension is mandatory; there is no Python fallback implementation.

Usage

The plugin scans these hooks:

  • prompt_pre_fetch: scans payload.args
  • tool_pre_invoke: scans tool invocation payloads before execution
  • tool_post_invoke: scans payload.result
  • resource_post_fetch: scans payload.content.text

Typical uses:

  • block requests that contain likely credentials before they reach tools or prompts
  • redact secrets from returned tool or resource payloads
  • surface sanitized findings metadata for observability and tuning

Detection Coverage

Enabled by default:

  • aws_access_key_id
  • aws_secret_access_key
  • google_api_key
  • github_token
  • stripe_secret_key
  • slack_token
  • private_key_block

Disabled by default because they are broader and more false-positive-prone:

  • generic_api_key_assignment
  • jwt_like
  • hex_secret_32
  • base64_24

The detectors are regex-based. They do not verify whether a credential is real, active, or revoked.

Configuration

config:
  enabled:
    aws_access_key_id: true
    aws_secret_access_key: true
    google_api_key: true
    github_token: true
    stripe_secret_key: true
    slack_token: true
    private_key_block: true
    generic_api_key_assignment: false
    jwt_like: false
    hex_secret_32: false
    base64_24: false
  redact: false
  redaction_text: "***REDACTED***"
  block_on_detection: true
  min_findings_to_block: 1
  field_allowlist: []
  field_denylist: []
Field Type Default Description
enabled dict built-in defaults Per-detector enable flags; unspecified detectors inherit defaults
redact bool false Replace matched secret values in returned payloads
redaction_text string "***REDACTED***" Replacement text used when redact=true
block_on_detection bool true Return a violation when enough findings are present
min_findings_to_block integer 1 Minimum finding count required before blocking
field_allowlist list[string] [] Dotted field paths eligible for scanning; empty means all structured fields are eligible
field_denylist list[string] [] Dotted field paths excluded from scanning; denylist entries take precedence over allowlist entries

Field Filtering

field_allowlist and field_denylist apply to structured scan targets:

  • prompt_pre_fetch: paths are relative to payload.args
  • tool_pre_invoke: paths are relative to payload.args
  • tool_post_invoke: paths are relative to payload.result

For example, accounts.credentials.token matches payload.args.accounts.credentials.token in pre-hooks and payload.result.accounts.credentials.token in tool_post_invoke.

Rules:

  • An empty field_allowlist scans all structured fields.
  • A non-empty field_allowlist scans only the listed paths and their descendants.
  • A field_denylist entry excludes that path and all descendants.
  • When both lists match, field_denylist wins.
  • Parent containers are still traversed to reach nested allowlisted paths.
  • Matching is segment-aware: layer1 does not match layer10.
  • Lists and tuples are transparent to field matching; numeric indices are not used.
  • Mapping keys themselves are not scanned.
  • Direct scalar scan targets, including payload.content.text in resource_post_fetch, retain current behavior and are not filtered by field paths.

Valid field paths use non-empty dot-separated segments. Empty paths, whitespace-only paths, leading or trailing dots, and empty segments such as layer1..token are rejected during plugin initialization.

Example:

config:
  field_allowlist:
    - "layer1"
    - "accounts.credentials"
  field_denylist:
    - "layer1.layer2.layer3"
    - "accounts.credentials.test_token"

Behavior Notes

  • Redaction preserves payload shape where possible instead of flattening everything to plain dicts.
  • aws_secret_access_key recognizes = and : assignments with optional single or double quotes around the value.
  • aws_secret_access_key, generic_api_key_assignment, and base64_24 use capture-group redaction so only the detected secret span is replaced; assignment labels, separators, quotes, and leading non-base64 boundary characters are preserved.
  • Broad detectors remain opt-in to reduce noisy matches on ordinary identifiers.
  • Binary resource bodies are not scanned; resource_post_fetch only scans text content exposed as payload.content.text.
  • The plugin does not decode archives, compressed data, or arbitrary encoded blobs before scanning.

Returned Metadata

prompt_pre_fetch, tool_pre_invoke, tool_post_invoke, and resource_post_fetch accept an optional extensions parameter carrying OpenTelemetry trace context. When a trace context is present (via extensions.request.trace_id), the plugin emits operational metrics on result.metadata["secrets_detection"] with the following schema:

result.metadata["secrets_detection"] = {
    "total_detections": 2,   # int — total number of findings in this call
    "total_masked": 2,       # int — number redacted (masking action taken)
    "total_blocked": 0,      # int — number that caused a block (blocking action taken)
    "secret_types": ["aws_access_key_id", "slack_token"],  # list[str] — distinct type names, sorted, deduped
}

total_masked and total_blocked are mutually exclusive per call: exactly one of them carries the finding count (the other is 0), depending on whether the redaction branch or the blocking branch executed. If neither redaction nor blocking is configured, both are 0 and only total_detections/secret_types are non-zero (findings-only reporting mode).

Gating: Metrics are only emitted when a valid trace_id is present in the trace context (extensions.request.trace_id). No trace context means no result.metadata write at all, regardless of any config flag — this keeps the untraced path byte-for-byte identical to before metrics existed.

Security Note (S1): The plugin never includes raw secret values in result.metadata, logs, or any other output. Only counts and type-category names (e.g. "aws_access_key_id") are reported.

tool_pre_invoke is in scope for this metrics contract on the same terms as the other 3 hooks: it accepts extensions and emits result.metadata["secrets_detection"] under the identical gating/schema once a valid trace_id is present.

Blocking responses use the SECRETS_DETECTED violation code.

Migration Note

Version 0.3.8 adds optional field filtering:

  • field_allowlist and field_denylist default to empty lists, so existing configurations keep scanning the same fields as before.
  • When configured, field filters affect detection counts, metadata, redaction, min_findings_to_block, and blocking decisions.
  • field_denylist entries take precedence over field_allowlist entries.

Version 0.3.7 is a breaking change for any existing consumer reading detection metadata:

  • The old flat result.metadata keys — secrets_redacted, count (redaction path) and secrets_findings, count (findings-only path) — have been removed entirely. There is no compatibility shim; code reading those keys will silently stop receiving data.
  • Detection/redaction/blocking metrics are now emitted on result.metadata["secrets_detection"] instead, with keys total_detections, total_masked, total_blocked, and secret_types (see Returned Metadata above for the full schema).
  • All 4 hooks — prompt_pre_fetch, tool_pre_invoke, tool_post_invoke, and resource_post_fetch — now accept a new optional extensions parameter carrying OpenTelemetry trace context. Emission to result.metadata["secrets_detection"] is gated solely on extensions.request.trace_id being present and valid — if no trace context is supplied, no metrics are written at all, regardless of any config flag.
  • Consumers that previously read result.metadata["secrets_redacted"] / result.metadata["secrets_findings"] unconditionally must migrate to reading result.metadata["secrets_detection"] and must pass a trace_id via extensions to receive metrics.
  • tool_pre_invoke previously never received extensions and could never emit metrics (a regression introduced earlier on this branch, since fixed) — it now follows the exact same contract as the other 3 hooks.

Security Notes

  • Outward-facing findings metadata and violation examples do not include original matched secret values.
  • Enable broad detectors only after testing against representative payloads.
  • The detector is best-effort pattern matching and should complement, not replace, upstream secret management controls.

Testing

make ci

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for jonpspri from gravatar.com jonpspri Avatar for lucarlig from gravatar.com lucarlig

Credits

Author: ContextForge Contributors

License

Apache-2.0

Requires

Python >=3.11

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cpex_secrets_detection-0.3.11.tar.gz (58.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cpex_secrets_detection-0.3.11-cp311-abi3-win_amd64.whl (784.4 kB view details)

Uploaded CPython 3.11+Windows x86-64

cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_x86_64.whl (853.2 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ x86-64

cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_s390x.whl (891.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ s390x

cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_ppc64le.whl (885.1 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ppc64le

cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_aarch64.whl (799.1 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ARM64

cpex_secrets_detection-0.3.11-cp311-abi3-macosx_11_0_arm64.whl (753.1 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file cpex_secrets_detection-0.3.11.tar.gz.

File metadata

  • Download URL: cpex_secrets_detection-0.3.11.tar.gz
  • Upload date:
  • Size: 58.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for cpex_secrets_detection-0.3.11.tar.gz
Algorithm Hash digest
SHA256 9a5e557ad3abd4e2451c1b7e5a79764f570b872c69f0d9554c6e86d75713cfb7
MD5 23ba63c0ebf626292e24531fb19daec3
BLAKE2b-256 c7df8bdaa341c521db601b4642f563b2a6b979c686794f06348509e6a186eed2

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11.tar.gz:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e8a3dec4a65f9b519e8f852deee22dea3ef49ab5984c731911576f3e9b4750fa
MD5 a51b8796c58a63cc332eee195135dcbf
BLAKE2b-256 9556f5778c75560fb73db5436fc2deb0bdfe5d34e3871e59199b5e45744dc2e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-win_amd64.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 fde88de31bb09aeb5cc9f4b0f10767e59a746989e4d9266c5da19a2f9538f92f
MD5 d60d20bd30325a7897b85ff4471e1460
BLAKE2b-256 b65a29cfe0831d29c59a19f8b5f030b6bc3d6a2705aa56165e559d96d5773e5d

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_x86_64.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_s390x.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_s390x.whl
Algorithm Hash digest
SHA256 c77e171b48322bd1026b8e61203bed577d14d47d884611d5a615376c1d23adff
MD5 290b0dd76b7a3860b1c620d20ba0dc25
BLAKE2b-256 e0340f4dfa7808e6e7c124d94824ddcbc1540713ee46fe04c4aa2f410524f062

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_s390x.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_ppc64le.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_ppc64le.whl
Algorithm Hash digest
SHA256 e2267b10ea2f6023e93517be48c3e4902d6e7d7eb47011b7f0b34defa2974185
MD5 66d844af06735fa0f003642ff26699ac
BLAKE2b-256 e8987e67d6ccc5a00b3cd77329ab3f8daa6947231d09a36a85ae10d2b746358d

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_ppc64le.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 9aadd9065d84a44234f3343dc9a715d3e2bda1307e6b949e00791846ab9c8ec4
MD5 8d6834d55c47501246e93c6ec1657cf4
BLAKE2b-256 583942a7feefea3e330b30faaeeda63778ac92e3df06faec2f72d574efd3e29d

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-manylinux_2_34_aarch64.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cpex_secrets_detection-0.3.11-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for cpex_secrets_detection-0.3.11-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3a065652e9576cb281eb928729fb33136f650cb8ad0ebf29a14c11de8a5662e1
MD5 fb263cc8a4471fc3199cb03806cf13a8
BLAKE2b-256 2feea80c24659988de844795c3888853746c3e61d34a0f5088f440e4710083f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_secrets_detection-0.3.11-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release-rust-python-package.yaml on IBM/cpex-plugins

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.11 This release

7 files

0.3.10

7 files

0.3.9

7 files

0.3.8

7 files

0.3.7

7 files

0.3.6

7 files

0.3.5

7 files

0.3.4

7 files

0.3.3

7 files

0.3.2

7 files

0.3.1

7 files

0.3.0

7 files

0.2.2

7 files

0.2.1

7 files

0.2.0

7 files

0.1.0

7 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page