Metadata-Version: 2.4
Name: revsec-sdk
Version: 0.3.0
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: 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.

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

You need:

- Python 3.9 or newer.
- Your RevSec **SDK key**: an organization API key for your RevSec
  organization (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://revsec.revt2d.com/fcc"
```

`REVSEC_BASE_URL` is the RevSec address followed by `/fcc`, with nothing
after it.

### 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)).

## Which key

The SDK sends your key in the `X-API-Key` header. RevSec accepts an
**organization API key** there: the same kind of key the RevSec model gateway
takes. Workspace keys that start with `rsk_` are not accepted. With one,
every call is 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 the key in `X-API-Key`:

| Request | When |
|---|---|
| `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.

## 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.
