Encoded Exfiltration Detection (Rust)

High-performance encoded exfiltration detection for ContextForge and MCP Gateway.

Features

  • Detects suspicious encoded payloads in prompt args, tool outputs, and resource content
  • Scans common exfil encodings:
    • base64
    • base64url
    • hex
    • percent-encoding
    • escaped hex
  • Scores candidates using decoded length, entropy, printable ratio, sensitive keywords, and egress hints
  • Optional redaction instead of hard blocking
  • Recursive scanning of nested dicts, lists, and JSON-like string payloads
  • Allowlist regex support for known-safe encoded strings
  • Decode-depth and recursion-depth guardrails

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
  • tool_post_invoke
  • resource_post_fetch

Typical uses:

  • block suspicious encoded payloads before they leave the gateway
  • redact encoded secrets or staged exfil fragments from tool results
  • surface findings metadata for review and tuning

Detection Model

Each candidate encoded segment is decoded and scored. The detector looks for combinations of:

  • sufficient decoded length
  • suspicious entropy
  • printable decoded content
  • sensitive markers such as password, secret, token, authorization, or private key
  • egress hints such as curl, wget, webhook, upload, socket, or pastebin

The plugin can also inspect JSON strings recursively so encoded content nested inside serialized blobs is still visible to the detector.

Configuration

Important settings include:

  • enabled: per-encoding enable flags
  • min_encoded_length
  • min_decoded_length
  • min_entropy
  • min_printable_ratio
  • min_suspicion_score
  • max_scan_string_length
  • max_findings_per_value
  • redact
  • redaction_text
  • block_on_detection
  • min_findings_to_block
  • allowlist_patterns
  • extra_sensitive_keywords
  • extra_egress_hints
  • max_decode_depth
  • max_recursion_depth
  • parse_json_strings

Returned Metadata

prompt_pre_fetch, 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) and at least one detection occurred, the plugin emits operational metrics on result.metadata["encoded_exfil_detection"] with the following schema:

result.metadata["encoded_exfil_detection"] = {
    "total_detections": 2,                      # int — total number of findings in this call
    "encoding_types": ["base64", "hex"],         # list[str] — distinct encoding names, sorted, deduped
    "redacted": True,                            # bool — present only when the redact branch fired
}

redacted is only included when redact=true is configured and the payload was actually rewritten in this call; it is omitted otherwise (its absence means "not redacted this call", not "false").

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

Security Note (S1): The plugin never includes raw finding content, matched/decoded payload text, or per-finding path/score detail in result.metadata. Only the total count and the distinct encoding names are reported.

Blocking responses use the ENCODED_EXFIL_DETECTED violation code.

Migration Note

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

  • The old flat result.metadata keys — encoded_exfil_count, encoded_exfil_findings, encoded_exfil_redacted, and implementation — have been removed entirely. There is no compatibility shim; code reading those keys will silently stop receiving data. (These keys were already dropped at the gateway before this change, since the gateway's metadata sanitizer treats each top-level result.metadata key as a plugin namespace expecting a dict value, and encoded_exfil_count/implementation are scalars — so this migration removes a write that was already dead-on-arrival downstream.)
  • Detection metrics are now emitted on result.metadata["encoded_exfil_detection"] instead, with keys total_detections, encoding_types, and (conditionally) redacted — see Returned Metadata above for the full schema.
  • prompt_pre_fetch, tool_post_invoke, and resource_post_fetch now accept a new optional extensions parameter carrying OpenTelemetry trace context. Emission to result.metadata["encoded_exfil_detection"] is gated on extensions.request.trace_id being present and valid, and requires at least one detection — if no trace context is supplied, or the payload is clean, no metrics are written at all, regardless of any config flag.
  • Consumers that previously read result.metadata["encoded_exfil_count"] / result.metadata["encoded_exfil_findings"] / result.metadata["encoded_exfil_redacted"] unconditionally must migrate to reading result.metadata["encoded_exfil_detection"] and must pass a trace_id via extensions to receive metrics.
  • The include_detection_details config flag no longer has any influence over result.metadata (it never leaks per-finding detail into metrics regardless of its value); it continues to affect only the examples field of PluginViolation.details on the blocking path, which is unaffected by this migration.

Security Notes

  • Guardrails reject Rust-incompatible allowlist regexes at engine initialization time (during plugin construction). Features such as lookaround and backreferences are not supported.
  • Scan and recursion caps exist to keep detection bounded on large payloads.
  • Detailed findings can be reduced or sanitized before metadata emission depending on configuration.

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_encoded_exfil_detection-0.3.7.tar.gz (42.5 kB view details)

Uploaded Source

Built Distributions

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

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-win_amd64.whl (756.5 kB view details)

Uploaded CPython 3.11+Windows x86-64

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_x86_64.whl (829.6 kB view details)

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

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_s390x.whl (868.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ s390x

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_ppc64le.whl (857.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ppc64le

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_aarch64.whl (780.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ARM64

cpex_encoded_exfil_detection-0.3.7-cp311-abi3-macosx_11_0_arm64.whl (732.9 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file cpex_encoded_exfil_detection-0.3.7.tar.gz.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7.tar.gz
Algorithm Hash digest
SHA256 b867520114088a2d3ce8d77bdf758d980857b1481ff26fc7e0da2c2b69eb42b6
MD5 05718d8a22049cce54789a055f768fc8
BLAKE2b-256 a263bcaf1e4c10c8a845cea0416c0ab532be907039ad7a8b3ac6646755887464

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7.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_encoded_exfil_detection-0.3.7-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 63af3e201906031ca4a8cb11672f84c623eade0071fdb7e8bf4a7ffccb0e9f16
MD5 17430fe01eeace24a411757252f91d40
BLAKE2b-256 b02b0f8442194eed1104c56815dccd517d89898097701d7143ac79cbe5546c45

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 3de6ffe1f910c43cd0b3e545e0463e18f2941d23ba77ed0d0bb00486e3b097e5
MD5 d501253a4d0182f9c405b54fc4a183cb
BLAKE2b-256 2dfebb95598f3297850f3560056ae470c0afea20fcaf6e4a57ac0ed377db04fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_s390x.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_s390x.whl
Algorithm Hash digest
SHA256 6ec9f9b59d2932f9496d99b90bc1c618ef165c31cf1357a9f8737bc4ee87107b
MD5 06e2e78ef0893680636077c27180c0aa
BLAKE2b-256 cefd712a76974d8460b0cf624c6bb0a5aa8a448b5efd20adcfece348947caf29

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_ppc64le.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_ppc64le.whl
Algorithm Hash digest
SHA256 38095f05a35e8373719abbf6ded02eedf1c62455a0c6f1ef20c023a3dfd6613c
MD5 b8385f0e1851e0b894194c918fca388f
BLAKE2b-256 cbe4bba3d22b86ca447a58ee3bc37d02a2b35a43f6949a656231be3603936efa

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 0c60f35bbcdb8b347608e7a03f0fb5ca8ac871b34dfc842c7159e3e5a8b69545
MD5 fa0898ffad84daccf7b2020ec8cc170a
BLAKE2b-256 2b205f66d7e75be1749a7e723bfbda4eb8f085274261ff271b31a354fed16230

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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_encoded_exfil_detection-0.3.7-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for cpex_encoded_exfil_detection-0.3.7-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 20bb63044d64793626c960ee3c9741f1952ba17bb98f6ae91a660b63b5bc06b9
MD5 a38d285ead072d5202a7b8589841e9f7
BLAKE2b-256 2065dcd9ce750f64bfa09efd4f0320befa8c8978ec5c2a206956153e71662aed

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_encoded_exfil_detection-0.3.7-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.7 This release

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.1

7 files

0.2.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