🛡️ StarkGate SDK

Official Python SDK for StarkGate — The Universal Firewall for AI Agents.

Installation

pip install starkgate-sdk

Quick Start

from starkgate import StarkGate

guard = StarkGate(api_key="sk_live_your_key")

result = guard.evaluate(
    agent_id="my-bot",
    policy_id="pol_safe",
    action_type="sql_query",
    payload={"query": "DROP TABLE users;"}
)

if result.is_denied:
    print(f"🛑 Blocked: {result.reason}")

Decorator Protection

from starkgate import StarkGate

guard = StarkGate(api_key="sk_live_your_key")

@guard.protect(agent_id="devops", policy_id="pol_prod", action_type="terminal")
def run_command(cmd: str):
    import os
    os.system(cmd)

run_command("ls -la")  # ✅ Allowed
run_command("rm -rf /")  # ❌ Blocked

Async Support

import asyncio
from starkgate import StarkGate

async def main():
    guard = StarkGate(api_key="sk_live_your_key")
    result = await guard.async_evaluate(
        agent_id="trading-bot",
        policy_id="pol_trading",
        action_type="execute_trade",
        payload={"amount": 50000, "ticker": "AAPL"}
    )
    print(result.decision)

asyncio.run(main())

LangChain

pip install "starkgate-sdk[langchain]"

from starkgate.langchain_guard import make_starkgate_tool

# hors-ligne : politique inline, aucun serveur
tools = [make_starkgate_tool(policy=my_policy)]
# cloud      : politique gérée côté serveur
# tools = [make_starkgate_tool(api_key="sk_live_...", policy_id="pol_x")]

OpenAI (function calling)

pip install "starkgate-sdk[langchain]"   # ou sans LangChain

from starkgate.openai_guard import make_starkgate_function, run_starkgate_call

tools = [make_starkgate_function(policy=my_policy)]          # mode local
# … app de chat avec tools=tools ; le modèle renvoie tool_calls …

verdict = run_starkgate_call(policy=my_policy, action_type="transfer",
                            payload={"op": "payday"})
if verdict["decision"] == "ALLOW":
    exécuter_l_action()
else:
    # disjoncteur : bloqué, preuve dans verdict["auditHash"]
    refuser(verdict)

Engine local (hors-ligne)

Le moteur d'évaluation peut tourner sans aucun serveur — bit-à-bit identique au moteur serveur (mêmes verdicts, mêmes auditHash). Idéal pour l'edge, l'air-gap, le drone, la voiture ou le satellite.

from starkgate import engine

policy = {
  "id": "pol-1", "name": "demo", "mode": "enforce", "defaultDecision": "ALLOW",
  "rules": [{
    "id": "r1", "name": "block payday", "enabled": True,
    "condition": {"field": "op", "operator": "eq", "value": "payday"},
    "decision": "DENY", "message": "Bloqué.", "riskLevel": "high",
  }],
}

verdict = engine.evaluate(
  {"agentId": "bot", "policyId": "pol-1",
   "actionType": "transfer", "payload": {"op": "payday"}},
  policy,
)
print(verdict["decision"], verdict["auditHash"])  # DENY sha256:…

Transform post-ALLOW

Une règle ALLOW gagnante peut porter un transform qui mute la payload avant signature. Ops : set, floor, ceiling, replace ; chemin pointé concret (clés + index numériques). Le verdict expose transformApplied et transformedPayload ; auditHash couvre la payload finale. Fail-closed : un transform invalide → DENY (transform invalid (…)). Parité bit-à-bit avec TS/Rust (design figé : docs/TRANSFORM.md).

policy = {
  "id": "pol-2", "name": "annotate", "mode": "enforce",
  "defaultDecision": "DENY",
  "rules": [{
    "id": "r1", "name": "annotate transfer", "enabled": True,
    "condition": {"field": "op", "operator": "eq", "value": "transfer"},
    "decision": "ALLOW", "message": "annotation appliquée", "riskLevel": "medium",
    "transform": {"type": "set", "path": "meta.annotated", "value": True},
  }],
}

verdict = engine.evaluate(
  {"agentId": "bot", "policyId": "pol-2",
   "actionType": "transfer", "payload": {"op": "transfer", "amount": 100}},
  policy,
)
assert verdict["decision"] == "ALLOW"
assert verdict["transformApplied"] is True
assert verdict["transformedPayload"]["meta"]["annotated"] is True

Serveur MCP

Expose StarkGate à n'importe quel agent (Claude Desktop, Cursor, claude-code…) via le Model Context Protocol.

pip install "starkgate-sdk[mcp]"
python -m starkgate.mcp_server            # stdio

Outils : evaluate (cloud ou local), evaluate_local (100 % hors-ligne) et verify (re-vérifie une preuve sans le serveur).

Exemple de config claude_desktop_config.json :

{
  "mcpServers": {
    "starkgate": {
      "command": "python",
      "args": ["-m", "starkgate.mcp_server"]
    }
  }
}

Démo de bout en bout

pip install "starkgate-sdk[mcp]"
python examples/demo.py

Enregistre un compte, crée une policy, évalue ALLOW + DENY en production, puis re-vérifie la preuve cryptographique hors-ligne — « Trust the Math, not the Platform. »

License

MIT