URL Reputation (Rust)

Static URL policy checks for ContextForge and MCP Gateway resource fetches.

Features

  • Blocks resource fetches before execution with the resource_pre_fetch hook
  • Allows trusted domains or URL regex patterns to bypass later checks
  • Blocks configured domains, subdomains, or URL regex patterns
  • Blocks non-HTTPS URLs by default
  • Optional domain heuristics for high entropy, static IANA TLD validity, and Unicode security
  • Case-insensitive domain normalization for allowlist and blocklist entries
  • Pure static policy checks; no external reputation provider or threat-intel feed calls

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 runs on resource_pre_fetch before a resource URI is fetched.

Typical uses:

  • block known bad domains and subdomains
  • allow trusted internal URL patterns before enforcing HTTPS
  • reject insecure http:// resource fetches
  • enable lightweight domain heuristics for suspicious generated or Unicode domains

Configuration

config:
  whitelist_domains:
    - "example.com"
  allowed_patterns:
    - "^https://trusted\\.internal/.*"
  blocked_domains:
    - "malicious.example.com"
  blocked_patterns:
    - "casino"
    - "crypto"
  use_heuristic_check: false
  entropy_threshold: 3.65
  block_non_secure_http: true
Field Type Default Description
whitelist_domains set [] Domains and subdomains that bypass remaining checks
allowed_patterns list [] Regexes matched against the full trimmed URL; a match bypasses remaining checks
blocked_domains set [] Domains and subdomains that are always blocked unless allowlisted first
blocked_patterns list [] Regexes matched against the full trimmed URL; a match blocks the request
use_heuristic_check bool false Enable entropy, TLD, and Unicode domain checks for non-IP hosts
entropy_threshold float 3.65 Maximum allowed Shannon entropy for the domain
block_non_secure_http bool true Block URLs whose scheme is not https

Logic Workflow

  1. Trim and parse the URL.
  2. Extract the host/domain.
  3. Detect IPv4 or IPv6 hosts so domain heuristics can be skipped.
  4. Allow exact or parent-domain matches in whitelist_domains.
  5. Allow matches in allowed_patterns; this also bypasses HTTPS enforcement.
  6. Block non-HTTPS schemes when block_non_secure_http=true.
  7. Block exact or parent-domain matches in blocked_domains.
  8. Block matches in blocked_patterns.
  9. If heuristics are enabled for a non-IP host, block high-entropy domains, illegal static TLDs, or unsafe Unicode domains.

Returned Metadata

Allowed URLs return continue_processing=true.

Blocked URLs return continue_processing=false with a PluginViolation using code URL_REPUTATION_BLOCK. Violation details include the URL or domain involved in the decision.

resource_pre_fetch accepts 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["url_reputation"] with the following schema:

result.metadata["url_reputation"] = {
    "total_checked": 1,                    # int — always 1; one URL is checked per call
    "total_blocked": 0,                     # int — 0 or 1; this call's outcome, not a running total
    "reputation_categories": [],            # list[str] — category slugs; empty when allowed
}

resource_pre_fetch evaluates exactly one URL per call with no running counter, so — mirroring rate_limiter's per-call allowed/throttled semantics — total_checked and total_blocked describe only the current call's outcome; the gateway aggregates counts across spans/time. When the URL is blocked, reputation_categories contains exactly one slug describing why (e.g. blocked_domain, insecure_scheme, high_entropy_domain, illegal_tld, unicode_spoofing, blocked_pattern, malformed_url, malformed_domain, internal_error).

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.

Security Note (S1): The plugin never includes the raw URL or domain in result.metadata. Only counts and category slugs (derived from the plugin's static, hardcoded violation reasons) are reported; the actual URL/domain stays confined to PluginViolation.details on the blocking path, a separate channel unaffected by this metrics addition.

Limitations

  • Reputation data is static configuration only; there are no external provider lookups.
  • The IANA TLD list is compiled into the plugin and can lag newly delegated TLDs.
  • allowed_patterns intentionally runs before HTTPS enforcement, so trusted patterns can allow http:// URLs.
  • IP addresses skip domain heuristics.

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_url_reputation-0.3.6.tar.gz (45.1 kB view details)

Uploaded Source

Built Distributions

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

cpex_url_reputation-0.3.6-cp311-abi3-win_amd64.whl (854.8 kB view details)

Uploaded CPython 3.11+Windows x86-64

cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_x86_64.whl (935.7 kB view details)

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

cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_s390x.whl (992.6 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ s390x

cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_ppc64le.whl (970.2 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ppc64le

cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_aarch64.whl (887.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.34+ ARM64

cpex_url_reputation-0.3.6-cp311-abi3-macosx_11_0_arm64.whl (838.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

File details

Details for the file cpex_url_reputation-0.3.6.tar.gz.

File metadata

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

File hashes

Hashes for cpex_url_reputation-0.3.6.tar.gz
Algorithm Hash digest
SHA256 ad7af607b350b83e1d1d69405ac9f933c42a9fedff1b9443a3b4680d0a72629c
MD5 b887b04e89a359a1d46b27ff7717c500
BLAKE2b-256 904a13338cd370feb169f34db58655107674df8abe1b9b00e73ced921b4f0f31

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6.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_url_reputation-0.3.6-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 59eec91f0d0cb3c187d5bc25462fd4ce4278461e97a4887ca33d6957e4be5706
MD5 f28c20531aa9a4c7b996ffbadd5fe0a1
BLAKE2b-256 df1c0f5946333a9fc574a004f4d783265f13daf1738a35c987663f2d98959a19

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 7e451ac3e383c47fd20e2efee1f1a07198df0efbc62bba0ed5728dd9b3a0f9a8
MD5 4239755fbb7d00dbb65ac7fe10399e2d
BLAKE2b-256 16021f8016085dd7d8bdea183e455ecbb01de6a40825ec382a2b8ee5f4c604db

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_s390x.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_s390x.whl
Algorithm Hash digest
SHA256 05637362352619c2e2ac1c51fdccce2e4fd6339ea87f96a9d83f46886e89ec41
MD5 8a23a09b63af0d525fa5d62154d1bfeb
BLAKE2b-256 3322d81b1be0d026a2423e425d0146d77282e11bbe4a9f390c2a926bdcaed449

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_ppc64le.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_ppc64le.whl
Algorithm Hash digest
SHA256 5828f60868c3e288d7b63678991395608faba3fd4d501e5ccf095ac60c3db5bf
MD5 ef184825ac6f693fdb75f93e5b736a0c
BLAKE2b-256 98c3b345585e5d229ed601d3355b328450316e1fe8cb41dc2390c32a0769542a

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 6e019eee63e4766d22837d261af4b6c557e701916a9793166016aa60f0684673
MD5 b2b16786a98e7852c90836a3d327966c
BLAKE2b-256 a1d84a8a320378489b53d001e613a65289eb5c07203df62ce86d9778e2f9e21e

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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_url_reputation-0.3.6-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for cpex_url_reputation-0.3.6-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 33951fe703bad54073ed8341c7ec1268580d129689e2a077968c923dc92df297
MD5 a95839b92e55773e62ea099eae2e9a00
BLAKE2b-256 60de1d7aa95bf4215d08ec87268733b486374f66d5ada114e9b02403e6bc94d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for cpex_url_reputation-0.3.6-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.6 This release

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

0.1.1

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