Vulnify Python SDK

Ask Vulnify before your AI agent acts. Get ALLOW, REVIEW, or BLOCK, with a risk score and the reasons.

Docs · Dashboard · MCP · Changelog

Vulnify is runtime authorization for AI agents. Before an agent reads, writes, deletes, exports, or emails data, your code sends Vulnify the action metadata (agent, action, resource, destination, record count). Vulnify answers with a decision, a 0 to 100 risk score, and the reasons, and writes the decision to your audit log. Vulnify sees the metadata, not the records.

• Zero dependencies. The core package uses only the standard library. Python 3.9+.
• Fail-closed by default. If Vulnify cannot be reached, the action is blocked unless you opt into fail_mode="open".
• Human review built in. REVIEW holds the action until a person approves or denies it.
• Framework adapters for LangChain, LangGraph, CrewAI, OpenAI Agents, and MCP, plus webhook verification and a policies-as-code CLI.

Quickstart

1. Install

pip install vulnify

2. Create an API key in the dashboard (a TEST key is fine to start) and export it:

export VULNIFY_API_KEY="..."

3. Ask before the action runs

import os
from vulnify import Vulnify

vulnify = Vulnify(api_key=os.environ["VULNIFY_API_KEY"])

decision = vulnify.check(
    agent="SalesBot",
    action="EXPORT_DATA",
    resource="Customer Database",
    destination="EXTERNAL_EMAIL",
    records_affected=12000,
)

outcome = decision.final_decision or decision.decision  # "ALLOW", "REVIEW", or "BLOCK"
if outcome == "ALLOW":
    export_customer_records()
else:
    print(outcome, decision.risk_score, decision.reasons)

Or let guard() do the branching. The function runs only on ALLOW. Anything else raises VulnifyBlockedError:

from vulnify import VulnifyBlockedError

try:
    vulnify.guard(
        export_customer_records,
        agent="SalesBot",
        action="EXPORT_DATA",
        resource="Customer Database",
        destination="EXTERNAL_EMAIL",
        records_affected=12000,
    )
except VulnifyBlockedError as err:
    print(err.result.decision, err.result.reasons)

@vulnify.protect(agent=..., action=..., resource=...) is the same check as a decorator.

How it works

1. Your agent is about to act. Your code calls check() (or guard(), or an adapter) with the action metadata.
2. Vulnify evaluates your policies and the risk engine and returns a decision:
   • ALLOW: run the action.
   • REVIEW: do not run it yet. A person approves or denies it. Poll with wait_for_review(event_id), or pass wait={"timeout": 300} to guard().
   • BLOCK: do not run it.
3. Every decision lands in the audit log with its score and reasons.

Each decision has a detail view in the dashboard that explains it:

Which field is authoritative

Monitor mode

Roll out without blocking anything: in monitor mode the action is allowed and recorded, and the dashboard shows what enforcement would have done.

Audit log

Every decision, including human reviews, is appended to a per-organization SHA-256 hash chain that you can verify from the dashboard. Evidence and audit exports are a JSON or CSV download that includes a SHA-256 checksum. Settings has "SIEM export: JSON or CEF lines". See Audit log.

Configuration

Vulnify(
    api_key="...",          # required
    base_url=None,          # defaults to VULNIFY_BASE_URL, then https://api.vulnify.io
    timeout=3.0,            # seconds per HTTP request
    fail_mode="closed",     # "closed" blocks when Vulnify is unreachable; "open" allows
    retries=2,              # retries after the first attempt, for transient failures only
)

Any other HTTP 4xx (bad key, unknown agent or resource, invalid or oversized payload) raises VulnifyError immediately. It is not retried, and fail_mode="open" never turns it into an ALLOW.

check() arguments

Other methods: get_event(event_id) reads one decision, and wait_for_review(event_id, timeout=300.0, poll=2.0) returns ALLOW, BLOCK, or TIMEOUT (or APPROVED, DENIED, EXPIRED for older decisions without final_decision).

Framework integrations

vulnify.adapters wraps your tools so they run only on ALLOW. Adapters are duck-typed and import a framework only when they need one of its types, so the core install stays dependency-free. Each adapter takes a describe callback that turns the tool's arguments into check() keywords:

def describe_export(args):
    return {
        "agent": "SalesBot",
        "action": "EXPORT_DATA",
        "resource": "Customer Database",
        "records_affected": args.get("rows"),
    }

The framework extras require Python 3.10+. A blocked tool answers the agent with Vulnify's reasons instead of running; pass on_blocked="raise" to the tool wrappers (LangChain, OpenAI Agents, CrewAI) to raise VulnifyBlockedError instead. MCP adapters return an MCP error result. All adapters accept wait={"timeout": 300} to wait for a human review. Runnable samples are in examples/.

LangChain

from langchain_core.tools import tool
from vulnify.adapters import guard_langchain_tool

@tool
def export_customers(rows: int) -> str:
    """Export customer records."""
    return f"exported {rows}"

export_customers = guard_langchain_tool(vulnify, export_customers, describe_export)
export_customers.invoke({"rows": 3})

LangGraph

from langgraph.prebuilt import ToolNode
from vulnify.adapters import langgraph_tool_guard

node = ToolNode(tools, wrap_tool_call=langgraph_tool_guard(vulnify, {"export_customers": describe_export}))

A call that is not allowed returns an error ToolMessage with the reasons, so the model sees why. Tools not in the map run unchanged.

OpenAI Agents

from agents import function_tool
from vulnify.adapters import guard_openai_agents_tool

@function_tool
def export_customers(rows: int) -> str:
    """Export customer records."""
    return f"exported {rows}"

export_customers = guard_openai_agents_tool(vulnify, export_customers, describe_export)

MCP

from vulnify.adapters import guard_mcp_client, guard_mcp_handler

# Inside your MCP server: register the wrapped function.
async def export_customers(rows: int) -> str:
    """Export customer records."""
    return f"exported {rows}"

server.tool()(guard_mcp_handler(vulnify, describe_export, export_customers))

# In an MCP client: check listed tools before the request is sent.
session = guard_mcp_client(vulnify, session, {"export_customers": describe_export})

Webhooks

Vulnify can POST decision, anomaly, and test deliveries to an endpoint you register. Each delivery is signed with HMAC-SHA256 in the X-Vulnify-Signature header (t=<unix seconds>,v1=<hex>), keyed with your whsec_ endpoint secret. Verify and parse it with one call, passing the raw request body:

from flask import Flask, request
from vulnify import WebhookVerificationError, construct_webhook_from_request

app = Flask(__name__)

@app.post("/webhooks/vulnify")
def vulnify_webhook():
    try:
        event = construct_webhook_from_request(SECRET, request.headers, request.get_data())
    except WebhookVerificationError:
        return "", 400
    # event.id is the delivery id (dedupe retries on it); event.event_id is the event.
    if event.type == "BLOCK":
        print("blocked", event.event_id, event.data.final_decision)
    return "", 204

Read the raw body with request.get_data() (Flask), await request.body() (FastAPI), or request.body (Django). Do not re-serialize parsed JSON. Samples: Flask, FastAPI, Django. Delivery format: Webhook deliveries.

CLI

Policies as code and one-off decisions from the terminal. Same commands as the npm CLI.

pip install "vulnify[cli]"

vulnify init                      # writes vulnify/policies/example.yaml and a test file
vulnify login --api-key "$VULNIFY_API_KEY"
vulnify check --agent SalesBot --action EXPORT_DATA --resource "Customer Database" --records 12000
vulnify policies validate         # offline schema check with file:line errors
vulnify policies pull --out vulnify/policies
vulnify policies apply --dry-run
vulnify test --local

Every command accepts --json. There is no telemetry. Credentials are stored in ~/.config/vulnify/credentials.json (mode 0600); VULNIFY_API_KEY and VULNIFY_BASE_URL take precedence.

Policy file format: Policy files. CLI reference: CLI.

Vulnify MCP server

The Vulnify MCP server gives AI assistants and IDEs tools to check an action, read a decision, and test policies. Cursor, Claude, Grok, or your own code connect to it. It does not run your agent's tools, and it does not sit between the agent and another MCP server.

The recommended path is Sign in with Vulnify (OAuth 2.1). The hosted server is https://mcp.vulnify.io/mcp. Add that URL in the client and leave the API-key and OAuth client fields empty. It speaks Streamable HTTP and keeps no session. After you allow access, the server offers five tools: decide_action, get_decision, list_policies, check_action, and test_policies. It has no approve tool and no deny tool. A person resolves a REVIEW in Vulnify.

Use an API key when you need plan_policy_changes or check_mcp_tool_call, when the client cannot open a browser, or when the key has an IP allowlist. The local process is @vulnify/mcp 0.1.2. It needs Node.js 20 or newer, reads VULNIFY_API_KEY, and does not open the OAuth consent page:

npx -y @vulnify/mcp

On the hosted server, send the same key on every request as Authorization: Bearer <api key> or X-Vulnify-Key: <api key>. An API-key session lists all seven tools.

This is different from two other MCP features:

• The MCP gateway (POST /v1/gateway/mcp on the API) decides an agent's MCP tool call and, when the decision allows it, forwards the call to a registered upstream MCP server. See MCP gateway.
• The MCP adapters in this SDK (guard_mcp_handler, guard_mcp_client) guard tools inside your own MCP server or client. See MCP above.

Plans and pricing

The SDK is MIT-licensed. Usage limits, retention, and features depend on your Vulnify plan. See vulnify.io/pricing.

Support

• Docs: docs.vulnify.io
• Bugs and feature requests: GitHub issues
• Product support and billing: hello@vulnify.io (Support)

Security

Report vulnerabilities to security@vulnify.io. See the disclosure policy.

Development

pip install -e ".[dev,cli]"
pytest

License

MIT. Copyright 2026 Vulnify.