Skip to main content

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).
  • Access to the RevSec console for that organization, with a role that can create policies.

1. Install (1 minute)

pip install revsec-sdk

2. Point the SDK at RevSec (1 minute)

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:

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)

python quickstart.py
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)

python quickstart.py
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.
  • 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).

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:

@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:

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.

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:

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.

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

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.

Metadata

Release files for revsec-sdk 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for revsec-sdk 0.3.0
File Size Uploaded Provenance Actions
revsec_sdk-0.3.0.tar.gz 30.4 kB Without provenance Details for revsec_sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for revsec-sdk 0.3.0
File Interpreter ABI Platform Actions
revsec_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for revsec_sdk-0.3.0-py3-none-any.whl

Total release size: 46.8 kB

Release files / revsec_sdk-0.3.0.tar.gz

Download URL revsec_sdk-0.3.0.tar.gz
Size 30.4 kB
Tags Source
SHA-256 checksum
How to use checksums
50cc9a3a65ac3c2276557582ab8a8635bceec35769c30f8e723f4e1792d33785
BLAKE2b-256 checksum
How to use checksums
5518102e20236a28bf4d21e4d08c49908113097b5723e0e5cfbf8fb106061694
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Release files / revsec_sdk-0.3.0-py3-none-any.whl

Download URL revsec_sdk-0.3.0-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d6b51a7292425551318f280ed56d85a3acee1a572303e6ce42798b3812a5aaa9
BLAKE2b-256 checksum
How to use checksums
11de5c4c7249a51b12bd5b0b5c972bbd90c9dba0f1a100de467f3505d4096beb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Security for revsec-sdk 0.3.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page