> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lasso Security

> Lasso API v3 on TrueFoundry AI Gateway via a deployable FastAPI wrapper.

Deploy the [`integrations/lasso-security`](https://github.com/truefoundry/integrations-custom-guardrails/tree/main/integrations/lasso-security) **FastAPI wrapper** on any **public HTTPS** host. The gateway calls it at `llm_input` / `llm_output` via the [Custom Guardrail](/docs/ai-gateway/custom-guardrails) contract; the wrapper forwards traffic to [Lasso API v3](https://server.lasso.security) and returns `verdict` JSON on HTTP 200.

## What is Lasso Security?

[Lasso Security](https://www.lasso.security/) is a SaaS platform for classifying and remediating LLM traffic. You define **deputies** and policies in the Lasso platform; the wrapper does not embed policy logic.

API v3 exposes two operations used by this integration:

| Lasso API         | Purpose                                                             | Gateway operation |
| ----------------- | ------------------------------------------------------------------- | ----------------- |
| `POST /classify`  | Score prompt or completion; return `BLOCK` / `WARN` findings        | **Validate**      |
| `POST /classifix` | Apply masks or rewritten text when Lasso provides remediation spans | **Mutate**        |

The wrapper sets `messageType=PROMPT` for input hooks and `messageType=COMPLETION` for output hooks. Optional `sessionId` / `userId` from gateway `context` are forwarded when present for conversation-aware policy.

## How it works

1. The gateway POSTs an OpenAI-shaped `requestBody` (input) or `requestBody` + `responseBody` (output) to your wrapper URL.
2. The wrapper extracts user/assistant text and calls Lasso API v3 with your `LASSO_API_KEY`.
3. The wrapper returns **HTTP 200** with a policy outcome in the body (see below). Infrastructure failures return **HTTP 5xx**.

On **validate** rails, only findings with `action: BLOCK` produce `{"verdict": false}`; `WARN`-only findings are logged and allowed. On **mutate** rails, when Lasso returns mask metadata or rewritten content, the wrapper returns `{"verdict": true, "transformed": true, "result": {...}}` so the gateway can replace the request or response. Hard blocks without mask data still return `verdict: false`.

## Response contract

| HTTP  | Body                                                      | Meaning                  |
| ----- | --------------------------------------------------------- | ------------------------ |
| `200` | `{"verdict": true}`                                       | Allow                    |
| `200` | `{"verdict": false, "message": "..."}`                    | Block (policy)           |
| `200` | `{"verdict": true, "transformed": bool, "result": {...}}` | Mutate                   |
| `5xx` | error JSON                                                | Wrapper or Lasso failure |

Policy blocks must use **2xx + `verdict: false`**, not HTTP 4xx. See [Custom guardrail response contract](/docs/ai-gateway/custom-guardrails#custom-guardrail-response-contract).

## Wrapper endpoints

| Path                      | Operation | Target            |
| ------------------------- | --------- | ----------------- |
| `/lasso-classify`         | Validate  | Request (input)   |
| `/lasso-classify-output`  | Validate  | Response (output) |
| `/lasso-classifix`        | Mutate    | Request           |
| `/lasso-classifix-output` | Mutate    | Response          |

`GET /health` — health check. `GET /debug/runtime-config` — bearer-gated deploy verification.

All POST routes expect `Authorization: Bearer <WRAPPER_API_KEY>` when the key is configured on the wrapper.

## Prerequisites

* **Lasso API key** from the [Lasso Security platform](https://www.lasso.security/), plus deputies configured for your policies.
* **Public HTTPS URL** for the deployed wrapper.
* **`WRAPPER_API_KEY`** — shared secret; the gateway sends it as `Authorization: Bearer …` when calling the wrapper.

## Setup

<Steps>
  <Step title="Clone and configure">
    ```bash theme={"dark"}
    git clone https://github.com/truefoundry/integrations-custom-guardrails
    cd integrations-custom-guardrails/integrations/lasso-security
    cp .env.example .env
    ```

    ```bash .env theme={"dark"}
    LASSO_API_KEY=<from https://www.lasso.security/>
    WRAPPER_API_KEY=<generate: python -c "import secrets; print(secrets.token_urlsafe(32))">
    ```

    Get `LASSO_API_KEY` in the [Lasso Security platform](https://www.lasso.security/). Default API base: `https://server.lasso.security/gateway/v3` (override with `LASSO_API_BASE` if needed).
  </Step>

  <Step title="Deploy the wrapper">
    **Docker:**

    ```bash theme={"dark"}
    docker build -t lasso-guardrails-tfy .
    docker run --rm -p 8000:8000 --env-file .env lasso-guardrails-tfy
    ```

    **Local:**

    ```bash theme={"dark"}
    pip install -r requirements.txt
    uvicorn main:app --host 0.0.0.0 --port 8000
    ```

    Put TLS in front of the service (load balancer, ingress, or your platform’s HTTPS URL). The gateway must reach paths such as `https://<host>/lasso-classify`.

    <Accordion title="Deploy on TrueFoundry (optional)">
      Set `TFY_WORKSPACE_FQN`, `TFY_PUBLIC_HOST`, `TFY_PUBLIC_PATH`, and secret FQNs in `.env`. Create secrets `lasso-api-key` and `wrapper-api-key` under group `lasso-guardrails-tfy` in **Platform → Secrets**, then:

      ```bash theme={"dark"}
      pip install -U truefoundry
      tfy login
      python deploy.py --wait
      ```
    </Accordion>
  </Step>

  <Step title="Register Custom Guardrail configs">
    **AI Gateway → Guardrails → + Add New Guardrails Group** → type **Custom**.

    * **Group name**: `lasso-security`
    * Add one config per wrapper path (four total), or start with input validate only.

    **Input validate** example:

    | Field                  | Value                                        |
    | ---------------------- | -------------------------------------------- |
    | **Name**               | `lasso-validate-guardrail`                   |
    | **Operation**          | Validate                                     |
    | **Target**             | Request                                      |
    | **Enforcing Strategy** | Enforce                                      |
    | **URL**                | `https://<host>/lasso-classify`              |
    | **Headers**            | `Authorization` → `Bearer <WRAPPER_API_KEY>` |
    | **Config**             | `{}`                                         |

    <Frame caption="Custom Guardrail configuration (input validate)">
      <img src="https://mintcdn.com/truefoundry/TquyDgXk-RrfB4w0/images/lasso-security.png?fit=max&auto=format&n=TquyDgXk-RrfB4w0&q=85&s=fcc06666b71507298c75a63cb50acab2" alt="TrueFoundry custom guardrail form: Validate, Request target, /lasso-classify URL, Authorization Bearer header" width="1024" height="798" data-path="images/lasso-security.png" />
    </Frame>

    Register the remaining configs:

    | Name (example)           | Operation | Target   | Path                      |
    | ------------------------ | --------- | -------- | ------------------------- |
    | `lasso-classify-output`  | Validate  | Response | `/lasso-classify-output`  |
    | `lasso-classifix-input`  | Mutate    | Request  | `/lasso-classifix`        |
    | `lasso-classifix-output` | Mutate    | Response | `/lasso-classifix-output` |

    **Auth Data → Custom Bearer Auth** works the same as **Headers** if you prefer not to set headers manually.
  </Step>

  <Step title="Attach to traffic">
    **Model pin**: **AI Gateway → Models → \<model> → Guardrails** → attach group `lasso-security`.

    **Per request** — `X-TFY-GUARDRAILS` header, selector format `<group>/<config-name>`:

    ```json theme={"dark"}
    {
      "llm_input_guardrails": ["lasso-security/lasso-validate-guardrail"],
      "llm_output_guardrails": ["lasso-security/lasso-classify-output"]
    }
    ```

    For PII masking, use the `lasso-classifix-*` config names instead of classify.
  </Step>

  <Step title="Verify">
    Call the wrapper directly:

    ```bash theme={"dark"}
    curl -sS https://<host>/lasso-classify \
      -H "Authorization: Bearer $WRAPPER_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "requestBody": {"messages": [{"role": "user", "content": "My email is jane@example.com"}]},
        "context": {"user": {"subjectSlug": "test-user"}}
      }'
    ```

    Expect `{"verdict": false, ...}` when a deputy BLOCKs, or `{"verdict": true}` when allowed (depends on your Lasso policy).

    ```bash theme={"dark"}
    curl -sS https://<host>/debug/runtime-config -H "Authorization: Bearer $WRAPPER_API_KEY"
    ```

    Confirm `lasso_api_key_configured: true` and the `routes` map.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                       | Likely cause                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `401` from wrapper                            | `WRAPPER_API_KEY` on the service does not match the dashboard Bearer token     |
| Lasso console shows violation, gateway allows | Finding is `WARN` only; raise to `BLOCK` in Lasso, or use validate rails       |
| Mutate blocks instead of masking              | Lasso returned BLOCK without mask spans; use classify for hard stops           |
| Gateway allows despite `verdict: false`       | Tenant gateway not honoring verdict-on-200; set **Enforce** or upgrade gateway |

## Reference

| Item           | Value                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source repo    | [`truefoundry/integrations-custom-guardrails/integrations/lasso-security`](https://github.com/truefoundry/integrations-custom-guardrails/tree/main/integrations/lasso-security) |
| Lasso platform | [lasso.security](https://www.lasso.security/) (API key)                                                                                                                         |
| Lasso API base | `https://server.lasso.security/gateway/v3`                                                                                                                                      |
| Selector       | `lasso-security/<config-name>`                                                                                                                                                  |