Skip to main content

cpex-lasso

Lasso Security guardrail plugin for ContextForge, IBM's MCP gateway. It sends tool calls, tool results, prompts and resources to Lasso and blocks or masks them inline, before they reach the tool or the agent.

Tested with ContextForge 1.1.1 (plugin framework cpex 0.1.4).

How it works

ContextForge runs cpex-lasso inside its plugin pipeline. At each check the plugin sends the content to Lasso and acts on Lasso's answer before ContextForge goes on. A tool call is checked twice, once on the way in and once on the way out:

MCP client            ContextForge + cpex-lasso                Lasso        MCP server
    |                            |                               |               |
    |--- tools/call ------------>|                               |               |
    |                            |--- tool name + arguments ---->|               |
    |                            |<-- allow / block / mask ------|               |
    |                            |--- call the tool (if allowed) --------------->|
    |                            |<-- tool result -------------------------------|
    |                            |--- tool result -------------->|               |
    |                            |<-- allow / block / mask ------|               |
    |<-- result, or tool error --|                               |               |
  • Allow: the content goes on unchanged. Findings that do not block are logged.
  • Block: ContextForge refuses the call. A call blocked on the way in never reaches the tool; a result blocked on the way out never reaches the agent.
  • Mask (only with mask: true): Lasso returns the content with the sensitive parts replaced, the plugin writes it back in place, and the call goes on with the masked content.

Prompts and resources get one check each, after ContextForge renders the prompt or reads the resource. If Lasso cannot be reached, ContextForge's on_error setting decides whether the call passes or is refused (see "Fail-open or fail-closed" below).

What it checks

ContextForge hook What is sent to Lasso What Lasso can do
tool_pre_invoke the tool's name and arguments block the call, or mask the arguments before the tool runs
tool_post_invoke the tool's result block the result, or mask it before the agent sees it
prompt_post_fetch the rendered prompt text block or mask
resource_post_fetch the resource text block or mask

Not covered: agent-to-agent (A2A) traffic, tool descriptions at registration or listing, and ContextForge's LLM proxy.

Install

Install the package into the Python environment ContextForge runs in. For a container deployment that means building it into the gateway image.

pip install cpex-lasso

Requires Python 3.12 or newer.

Configure

1. Environment

Variable Value Why
PLUGINS_ENABLED true turns on ContextForge's plugin framework
PLUGINS_CONFIG_FILE path to your plugins YAML where the block below lives
PLUGINS_FAIL_ON_PLUGIN_ERROR true without it, ContextForge silently skips a plugin that fails to load and runs unprotected
LASSO_API_KEY your Lasso application API key the plugin refuses to load without it

2. Plugin block

plugins:
  - name: "LassoGuardrail"
    kind: "cpex_lasso.LassoPlugin"
    version: "0.1.0"
    hooks: ["tool_pre_invoke", "tool_post_invoke", "prompt_post_fetch", "resource_post_fetch"]
    mode: "sequential"
    on_error: "ignore"     # default: fail-open. "fail" = fail-closed
    priority: 10
    config:
      mask: false
      timeout_seconds: 5

ContextForge reads the plugin list at startup, so restart it after changing this file.

3. Settings

Everything under config is optional.

Setting Default Meaning
base_url https://server.lasso.security/gateway/v3 your Lasso gateway URL
api_key_env LASSO_API_KEY name of the environment variable that holds the API key
mask false when true, content Lasso marks for masking is rewritten instead of passed through
timeout_seconds 5 how long to wait for Lasso on each check

A misspelled setting stops the plugin from loading.

4. Fail-open or fail-closed

This is ContextForge's own on_error setting on the plugin block. It decides what happens when Lasso cannot be reached, times out, or answers with an error.

on_error When Lasso is unavailable
ignore (default) the call passes unscanned (fail-open)
fail the call is refused (fail-closed)

ignore is the default for cpex-lasso, as in the config block above. Keep the line in your config: without it, ContextForge falls back to fail.

Keep mode: "sequential". It is the only mode in which a plugin can both block and modify.

5. Turn on tool policies in Lasso

Lasso classifies tool traffic only when a policy or rule covers it. In the Lasso dashboard, enable the detections you want for Tool call and Tool output. Until you do, tool calls and results pass with no findings.

What the MCP client sees

MCP clients connect to a ContextForge virtual server over Streamable HTTP (/servers/<id>/mcp). There, a call the plugin refuses comes back as a failed tool call: HTTP 200, isError: true, and one text block with the hook and the code, for example:

tool_pre_invoke blocked by plugin LassoGuardrail: LASSO_BLOCK - Blocked by Lasso (Lasso policy blocked this content)
Situation Tool call result
Lasso blocks the content isError: true, code LASSO_BLOCK
Lasso masks the content and mask is true the call succeeds with the masked content
Lasso only alerts the call succeeds; the finding is logged
Lasso is unavailable, on_error: ignore the call succeeds unscanned; an error is logged
Lasso is unavailable, on_error: fail JSON-RPC error -32603
Lasso rejects the API key (HTTP 401) isError: true, code LASSO_AUTH_FAILED, whatever on_error says
Lasso asks to mask content that cannot be rewritten safely isError: true, code LASSO_MASKING_FAILED

A blocked prompt or resource comes back as a JSON-RPC error with the same text, for example prompt_post_fetch blocked by plugin LassoGuardrail: LASSO_BLOCK - ....

A rejected API key refuses every call on purpose. Under on_error: ignore it would otherwise switch scanning off without anyone noticing.

ContextForge's own JSON-RPC endpoint, /rpc, which the admin UI's tool test uses, returns a refusal as an HTTP error instead: HTTP 403 and JSON-RPC error -32602 for a block or a masking failure, HTTP 503 for a rejected key. The code and the block's details are under error.data.

A block's details in the /rpc response hold two lists:

  • findings: each detection once, as name, category, action and severity. The category is the one the Lasso rule editor shows, for example PERSONAL_IDENTIFIABLE_INFORMATION.
  • intent_findings: violations of the application's intent, as violations, action and monitor_only. A block caused by intent alone has an empty findings list.

What Lasso receives

  • The tool's name, description and input schema, its arguments and its result.
  • Prompt and resource text.
  • The ContextForge user's email, the MCP session id, the team id and the id of the upstream MCP server.

The credentials ContextForge stores for upstream MCP servers are never sent.

Things to know

  • Do not enable Code detection for tool calls. Lasso classifies a tool call's arguments as their JSON text, and code detection treats that JSON as code, so every tool call is blocked.
  • Auto mask does not stop prompt injection. An injection has nothing to mask, so under an Auto mask action it passes with a finding. Use Block for those detections.
  • Findings that do not block are logged at INFO. ContextForge's default LOG_LEVEL is ERROR, which hides them.
  • The first check is slower. Each team or tool context creates its own plugin instance on first use.

Development

pip install -e ".[test]"
pytest -q

The conformance run against a real ContextForge is described in conformance/README.md. Releases are described in RELEASING.md.

Metadata

Release files for cpex-lasso 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cpex-lasso 0.1.0
File Size Uploaded Provenance Actions
cpex_lasso-0.1.0.tar.gz 11.8 kB Without provenance Details for cpex_lasso-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cpex-lasso 0.1.0
File Interpreter ABI Platform Actions
cpex_lasso-0.1.0-py3-none-any.whl Python 3 none any Details for cpex_lasso-0.1.0-py3-none-any.whl

Total release size: 25.7 kB

Release files / cpex_lasso-0.1.0.tar.gz

Download URL cpex_lasso-0.1.0.tar.gz
Size 11.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f2e0cbe1ca6b3a58d744a1fc151716138cde35ada6b9cac3ab2d3ef2e8b338d9
BLAKE2b-256 checksum
How to use checksums
f1da648fc697bb86243467b98db9fb27daa94010a1d95e4f2bbb4a8c41a2bd85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / cpex_lasso-0.1.0-py3-none-any.whl

Download URL cpex_lasso-0.1.0-py3-none-any.whl
Size 13.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
27542a9027e8fb1e74469007c2de5aa35312e78d35ca0e32834a1e38093fd0fc
BLAKE2b-256 checksum
How to use checksums
f4d6fed294a3d4c9203d7c3568c2fa204380b7da6c3a92feca30bc38244fda52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for cpex-lasso 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

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