Metadata-Version: 2.4
Name: revsec-sdk
Version: 0.4.2
Summary: RevSec governance SDK — check your agent's tool calls before they run and record what happened.
Author-email: "RevSec / RevUp AI, Inc." <hello@revupai.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://revsec.revt2d.com
Keywords: mcp,model-context-protocol,ai-agents,ai-security,governance,tool-calls
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# revsec-sdk

Check each tool call your Python agent makes against your organization's
RevSec policies **before the tool runs**, and record what happened. A blocked
call raises `RevsecBlocked` and the tool body never executes.

Works with any Python function: a tool in your own agent loop, a tool you
register with an agent framework, or a handler in your own MCP server. It can
also check every call your agent makes to an MCP server, and register the
agent itself, so it is listed under **Agents** and its calls follow its
approval (see [Register your agent](#register-your-agent)).

## Quick start: a blocked tool call in 15 minutes

You need:

- Python 3.9 or newer.
- Your RevSec **SDK key**, from **Settings → SDK** in the RevSec console
  (see [Which key](#which-key)).
- Access to the RevSec console for that organization, with a role that can
  create policies.

### 1. Install (1 minute)

```bash
pip install revsec-sdk
```

### 2. Point the SDK at RevSec (1 minute)

```bash
export REVSEC_API_KEY="<your SDK key>"
export REVSEC_BASE_URL="https://<your RevSec address>/fcc"
```

`REVSEC_BASE_URL` is your RevSec console's address followed by `/fcc`, with
nothing after it. Settings → SDK in the console shows both values. The SDK
has no built-in address: `configure()` uses `base_url` if you pass it, else
`REVSEC_BASE_URL`, and raises `ValueError` if neither is set.

### 3. Guard two tools (3 minutes)

Save this as `quickstart.py`:

```python
import os
import uuid

from revsec import mcp
from revsec.mcp import RevsecBlocked

mcp.configure(
    api_key=os.environ["REVSEC_API_KEY"],
    base_url=os.environ["REVSEC_BASE_URL"],
)
mcp.set_session(str(uuid.uuid4()))  # groups this run's calls in RevSec


@mcp.guard(server="quickstart-agent", tool="lookup_order")
def lookup_order(order_id: str) -> dict:
    return {"order_id": order_id, "status": "delivered"}


@mcp.guard(server="quickstart-agent", tool="refund_order")
def refund_order(order_id: str, amount: float) -> dict:
    return {"order_id": order_id, "refunded": amount}


for name, call in [
    ("lookup_order", lambda: lookup_order("A-1001")),
    ("refund_order", lambda: refund_order("A-1001", 25.0)),
]:
    try:
        print(f"{name:13} allowed  {call()}")
    except RevsecBlocked as blocked:
        print(f"{name:13} BLOCKED  by '{blocked.decision.policy_name}'; the tool did not run")
```

`server` names the group the tools belong to (here, your agent). `tool` is
the name policies match on.

### 4. Run it: both calls are allowed and recorded (1 minute)

```bash
python quickstart.py
```

```text
lookup_order  allowed  {'order_id': 'A-1001', 'status': 'delivered'}
refund_order  allowed  {'order_id': 'A-1001', 'refunded': 25.0}
```

In the RevSec console, open **MCP → Inventory**. `quickstart-agent` is listed
as **Shadow** (nobody has approved it yet). Open it; its **Activity** tab shows
both calls.

### 5. Block the refund tool (5 minutes)

In the RevSec console:

1. Open **MCP → Policies** and click **Create Policy**.
2. **Name**: `Block refunds (quick start)`.
3. **Enforcement**: choose **Enforce**. **Action on match**: **block**.
4. Under **Target scope**, add a **Tool name regex pattern**: `^refund_order$`.
5. Click **Create policy**.

### 6. Run it again: the refund is blocked (1 minute)

```bash
python quickstart.py
```

```text
lookup_order  allowed  {'order_id': 'A-1001', 'status': 'delivered'}
refund_order  BLOCKED  by 'Block refunds (quick start)'; the tool did not run
```

The blocked call is listed under **MCP → Violations**. To undo, switch the
policy off on **MCP → Policies**.

### If `refund_order` is still allowed

- **The SDK printed `RevSec refused the API key`.** The key is wrong for this
  address, so nothing is being checked and every call is allowed. See
  [Which key](#which-key).
- **The policy is in Monitor.** Monitor records a violation but lets the call
  through. Edit the policy and choose **Enforce**.
- **`REVSEC_BASE_URL` is wrong.** It must end in `/fcc`, without `/api/v1`.
  When RevSec can't be reached, the SDK allows the call (see
  [When RevSec can't be reached](#when-revsec-cant-be-reached)).

### If both calls are blocked in step 4

- **By `Org posture · unapproved MCP server`.** Your organization lets only
  approved MCP servers run. Open **MCP → Inventory**, approve
  `quickstart-agent`, and run it again.

## Register your agent

Register the agent once when it starts. RevSec lists it under **Agents**, in
the same registry as every agent it finds, with what you declare: the models
it uses, its tools and the data it can reach. Then pass its `agent_id` to
every check, so its tool calls are tied to it and follow its approval.

```python
import os

from revsec import agent, mcp

mcp.configure(api_key=os.environ["REVSEC_API_KEY"], base_url=os.environ["REVSEC_BASE_URL"])

me = agent.register(
    name="orders-agent",
    framework="langgraph",
    agent_type="tool_using_agent",
    autonomy="human_on_the_loop",
    models=["claude-sonnet-5-5"],
    tools=["lookup_order", "refund_order"],
    data_access=["orders"],
    owner_email="owner@yourcompany.com",
)
print(me.agent_id, me.status)   # e.g. "6f1c1f9e-…", "shadow"


@mcp.guard(server="orders-tools", tool="lookup_order", agent_id=me.agent_id)
def lookup_order(order_id: str) -> dict:
    ...
```

- **A new agent starts as Shadow**, and an approval request is raised for it
  on the **Agents** page. Until someone approves it, its tool calls and
  content scans follow **Agents → Enforcement posture**: under **Enforce**
  they are blocked (`Agent posture · agent not approved`); under **Monitor**
  they run and are recorded. A quarantined or decommissioned agent is blocked
  under every posture.
- **Each tool call is checked against** the agent's approval, the agent's
  tool-call policies (Agents → Policies, "Tool the agent calls") and your MCP
  policies; a stop from any of them blocks the call. A tool-call policy set to
  quarantine also quarantines the agent.
- **Registering again** with the same `name` and `framework` updates the same
  agent and returns its current status: its tools, models, data access and
  environment, and its type, autonomy and description when you pass them. The
  owner is set only if the agent has none (an owner set on the Agents page is
  kept). When what the agent policies look at changes, they are checked
  again. A different `framework` makes a second agent.
- **`agent_type`** is one of `single_agent` (a new agent's default), `sub_agent`,
  `multi_agent_orchestrator`, `tool_using_agent`, `coding_assistant`,
  `productivity_assistant`. **`autonomy`** is one of `human_in_the_loop` (a new
  agent's default), `human_on_the_loop`, `supervised`, `semi_autonomous`,
  `fully_autonomous`, `advisory_only`. Agent policies match on these, so any
  other value is refused for a new agent, and kept as it was (with a warning)
  for a known one.
- **`owner_email`** must be a person in your RevSec organization. Otherwise
  the agent is registered with no owner, and `me.warnings` says so (it is
  logged too).
- **`agent_id` must be the id `register()` returned.** Anything else (the
  agent's name, a typo) is treated as an agent RevSec has no record of:
  blocked under Enforce (`Agent posture · agent not registered`), and the SDK
  logs a warning.
- `register()` raises `RegistrationFailed` when RevSec refuses the key or the
  values, or can't be reached, so a mistake shows up at start-up rather than as
  unchecked tool calls. `await agent.aregister(...)` is the async form.

## Which key

Use an **SDK key** (it starts with `rssdk_`). An Org Admin or CISO issues it
in the RevSec console, under **Settings → SDK**; it is shown once. Give each agent
or environment its own, and revoke one there at any time.

The SDK sends the key in the `X-API-Key` header (and, to register an agent,
as `Authorization: Bearer`). An organization API key also works. A key made
for the RevSec browser extension, or a workspace key starting with `rsk_`, is
refused: every call is then allowed and the SDK logs
`RevSec refused the API key`.

Keep the key in a secret store or an environment variable, never in code.

To check a different organization in the same process, pass `api_key=` to
`guard()`, `aguard()`, `evaluate()` or `scan_content()`. The key decides the
organization.

## What the SDK calls

All calls go to `REVSEC_BASE_URL` with your key:

| Request | When |
|---|---|
| `POST /api/v1/agent-security/sdk/register` | `agent.register()`, once at start-up. The key is sent as `Authorization: Bearer`. Timeout 10 s. |
| `POST /api/v1/mcp-governance/evaluate` | Before each guarded call. Timeout 1.5 s. |
| `PATCH /api/v1/mcp-governance/events/{id}/outcome` | After the tool returns, fails or is blocked. Timeout 1 s. |
| `POST /api/v1/ai-data-flows/ingest` | Only when the content scan is on (`dlp=True`) or you call `scan_content()`. |

## Async tools

Use `@mcp.aguard` for `async def` tools:

```python
@mcp.aguard(server="internal-rag", tool="search_docs")
async def search_docs(query: str) -> dict:
    return {"results": [...]}
```

Positional and keyword arguments both reach RevSec by parameter name, so
policies on arguments work however the tool is called. The wrapper keeps the
tool's name, signature and docstring, which agent frameworks read to describe
the tool to the model.

## MCP servers your agent connects to

Wrap the MCP client your agent already uses, and every tool call it makes to
that server is checked first. The server is reported the way RevSec
recognises it, read from the connection: its address, the package it runs, and
the name it gives itself. So it joins the server already on record (from a
laptop, the gateway or another agent) instead of being listed twice. Only the
package name is read from a launch command, never its arguments.

```bash
pip install "revsec-sdk[mcp]"
```

```python
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
from revsec import mcp_client

params = StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-github"])
async with stdio_client(params) as (read, write):
    async with mcp_client.guard(ClientSession(read, write), launch=params, agent_id=me.agent_id) as session:
        await session.initialize()
        await session.call_tool("create_issue", {"title": "Flaky test"})   # checked first
```

For a remote server pass `url="https://…"` instead of `launch`. `agent_id` is
the id `agent.register()` returned: it links the server to your agent. A
blocked call raises `RevsecBlocked` and never reaches the server; pass
`on_block="result"` to get an error result that tells the model why instead.

## When RevSec can't be reached

By default a call is allowed when RevSec can't be reached (fail open), so an
outage never stops your agent. Change it for every call:

```python
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], failure_mode="fail_closed")
```

Without a setting, the SDK blocks only tools whose names start with a
destructive verb (`delete_`, `drop_`, `truncate_`, `exec_`, `rm_`, `destroy_`,
`kill_`) on servers outside a short list of well-known services, and allows
everything else.

## Scan what a tool sends out

Policies decide *whether* a tool may run. Set `dlp=True` to also scan the
tool's **input** (the message, ticket or document it is about to send) for
secrets and personal data, with the same data policies as the rest of RevSec.
It is off by default: it adds one request per call and can newly block a
write.

```python
mcp.configure(api_key=os.environ["REVSEC_API_KEY"], dlp=True)


@mcp.aguard(server="slack", tool="post_message")
async def post_message(*, channel_id: str, text: str) -> dict:
    ...
# If `text` carries a secret a policy blocks, RevsecBlocked is raised
# before post_message runs: the payload never leaves your process.
```

A redact verdict on a write is treated as a block: RevSec returns the redacted
text as one string, which can't be put back into the tool's structured
arguments, so the write is withheld rather than sent with the secret in it.
If the scan can't reach RevSec, the call goes ahead.

Scan any text yourself, for example a tool's response:

```python
verdict = await mcp.scan_content(
    content=response_text, direction="inbound",
    server="slack", tool="get_channel_history",
)
if verdict.blocked:
    ...
```

## Group a run into turns

`set_session()` groups one run's calls. Inside a run, `set_turn()` opens a
**turn**: one thing the agent set out to do. Each guarded call is a step in
the current turn.

```python
mcp.set_session(str(uuid.uuid4()))

mcp.set_turn("Reconcile the overnight claims batch")
await fetch_ledger(...)        # step 1
await match_payments(...)      # step 2

mcp.set_turn("Post the reconciliation summary to Slack")
await post_message(...)        # step 1 of turn 2
```

The session id must be a UUID; another value is not kept. Write the turn as a
short goal, not the prompt: it is stored as written, so keep secrets, customer
data and prompt text out of it. It travels with the first call of the turn, so
it costs no extra request. `clear_turn()` stops tagging steps.

## Check without a decorator

```python
decision = await mcp.evaluate(
    server="internal-rag",
    tool="delete_doc",
    args={"doc_id": "..."},
)
if not decision.allowed:
    raise PermissionError(decision.reason)

# After running the tool:
await mcp.record_outcome(
    event_id=decision.event_id,
    outcome="success",
    response_latency_ms=42,
)
```

## What RevSec records

For every guarded call: the server and tool, the decision and the policy (and
its version) that made it, the tool's arguments with long values shortened and
secret-named fields (`password`, `token`, `secret`, `api_key`, `key`,
`authorization`, `auth`, `credential`) masked, the outcome (success, error,
timeout or blocked), how long the tool took and the size of its result.

## Turn the SDK off

`mcp.configure(api_key=..., enabled=False)` allows every call without
contacting RevSec.

## License

Proprietary. RevUp AI, Inc.
