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, asname,category,actionandseverity. The category is the one the Lasso rule editor shows, for examplePERSONAL_IDENTIFIABLE_INFORMATION.intent_findings: violations of the application's intent, asviolations,actionandmonitor_only. A block caused by intent alone has an emptyfindingslist.
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_LEVELisERROR, 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.