Proxy Mode

The proxy mode exposes a FastAPI application that sits between the agent runtime and tool implementations. It provides real-time interception, auditing, policy enforcement, and operational tooling for interactive investigations.

Getting started

export PROXY_TOKEN="change-me"
uvicorn AISentinel_auditor.proxy.app:proxy_app --host 0.0.0.0 --port 8080

All requests must present the shared secret via X-Proxy-Token. Without a token the server responds with 401.

Endpoints

Method	Path	Description
`POST`	`/proxy/v1/tools/{tool}`	Execute a tool through the proxy. Supports optional `session_id` and `call_id` for correlation.
`GET`	`/proxy/v1/metrics`	Returns aggregate proxy metrics (throughput, block/error counts, latency).
`GET`	`/proxy/v1/rules`	List the active policy rules.
`PUT`	`/proxy/v1/rules`	Replace the active ruleset with a new list.
`GET`	`/proxy/v1/sessions`	List active sessions and recent call history.
`GET`	`/proxy/v1/sessions/{session}`	Fetch a single session including call timeline.
`POST`	`/proxy/v1/reset`	Reset metrics, sessions, and rules (useful for tests).

Rule schema

Rules are declared in priority order (lowest first). Each rule supports simple matching criteria and an action:

{
  "name": "block python",
  "action": "block",
  "match_tool": "python_exec",
  "match_args": {"user": "external"},
  "match_metadata": {"tenant": "beta"},
  "match_pattern": "(?i)suspicious",
  "block_reason": "high risk",
  "param_overrides": {"expression": "0"},
  "response_override": {"status": "masked"},
  "priority": 50
}

Supported action values:

allow: allow the call through untouched.
block: abort the call and return 403 with the configured reason.
modify: apply overrides to tool arguments and/or replace the downstream response.

Metrics

The metrics endpoint emits totals for calls, blocked calls, modified calls, error count, and latency (aggregate and average). This data can be scraped by existing monitoring pipelines or forwarded to dashboards.

Session tracking

Each proxied call is associated with a session_id. A new ID is generated when the client omits it. Session summaries include a bounded history of recent tool invocations with timestamps, tool names, status (ok, blocked, error), latency, and the rule that matched.

Extensibility

The proxy state exposes an in-memory rule engine and token bucket rate limiter. The ProxyState object can be swapped or extended for persistent storage, distributed rate limiting, or richer policy evaluation if needed.