Skip to main content

Observed traffic

Status: Beta Companion docs: Network DLP · ICAP API · Verdicts and modes Source of truth: ICAP API. This SDK guide covers the Python setup, govern shim, and event query.

Choose this when​

Choose observed integration when employees or agents use an AI app that your Python code does not call. A secure web gateway can send request and response traffic to Trinitite over ICAP. The Python SDK provisions the connector and reads its governance events.

Python flow​

Create the connector once and store the returned secret at once. Later list calls do not return it.

from trinitite import Trinitite

tr = Trinitite(env="prod")

connector = tr.swg.create_connector(
    display_name="corp-ai-egress",
    governance_mode="bidirectional",
    hitl_trigger="on_block",
    store_content=False,
)

connector_id = connector.tool_id
ingest_secret = connector.body["ingest_secret"]

Configure your gateway with connector_id and ingest_secret. The gateway sends request-side REQMOD and response-side RESPMOD transactions.

For a controlled integration check, the SDK exposes the same HTTP govern shim used by the bundled proxy. It encodes body_text as base64 and authenticates with connector headers:

check = tr.swg.govern(
    method="REQMOD",
    host="api.openai.com",
    path="/v1/chat/completions",
    http_method="POST",
    content_type="application/json",
    body_text='{"messages":[{"role":"user","content":"Summarize this account."}]}',
    connector_id=connector_id,
    icap_secret=ingest_secret,
)

if not check.ok:
    raise RuntimeError(check.body)

Read the audit events with the bearer-authenticated SDK client:

events = connector.events(
    method="REQMOD",
    verdict="block",
    limit=100,
)

for event in events.body.get("events", events.body.get("_list", [])):
    print(event["event_id"], event["verdict"], event["content_sha256"])

Request lifecycle​

Result and failure behavior​

The govern shim returns a standard SDK Response. Check response.ok, response.status, and response.body. Its ICAP verdict vocabulary is pass, correct, or block.

The event query returns newest-first audit rows. Useful filters include connector_id, vendor, verdict, method, nhi_id, principal_user_id, device_id, since, and limit.

  • A missing or invalid connector secret rejects the govern request.
  • Rotating a connector secret invalidates the old secret immediately.
  • A missing ICAP entitlement returns HTTP 402 on governed routes.
  • HTTP 4xx responses are returned without retries. Transport failures can raise ControlPlaneError after retries.

Identity, masking, and audit evidence​

Observed events can carry nhi_id, principal_user_id, hris_employee_id, device_id, and nhi_resolution_source when the gateway provides identity context and resolution succeeds. These fields can be null, so do not use them as required keys.

With store_content=False, the event keeps content_sha256, byte count, findings, severity, and routing metadata instead of the clear request or response body. Use event_id as the audit-row identifier and content_sha256 to match the payload your gateway saw.

The ICAP event surface uses pass, correct, and block. The broader SDK result vocabulary is used by inline and split-govern flows.

Next steps​

Last updated on