Metadata-Version: 2.5
Name: cpex-lasso
Version: 0.1.0
Summary: Lasso Security guardrail plugin for ContextForge
Project-URL: Homepage, https://lasso.security
Project-URL: Documentation, https://lasso-security.gitbook.io/lasso-security/
Author-email: Lasso Security <support@lasso.security>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: agents,ai,contextforge,guardrails,llm,mcp,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: cpex<0.2,>=0.1.4
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Provides-Extra: conformance
Requires-Dist: mcp-contextforge-gateway==1.1.1; extra == 'conformance'
Requires-Dist: pyyaml>=6; extra == 'conformance'
Provides-Extra: lint
Requires-Dist: mypy>=1.13; extra == 'lint'
Requires-Dist: ruff>=0.8; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# cpex-lasso

Lasso Security guardrail plugin for [ContextForge](https://github.com/IBM/mcp-context-forge), 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:

```text
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.

```bash
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

<!-- x-release-please-start-version -->
```yaml
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
```
<!-- x-release-please-end -->

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:

```text
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

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

The conformance run against a real ContextForge is described in [conformance/README.md](https://github.com/lasso-security/cpex-lasso/blob/main/conformance/README.md). Releases are described in [RELEASING.md](https://github.com/lasso-security/cpex-lasso/blob/main/RELEASING.md).
