Metadata-Version: 2.5
Name: ory-argus
Version: 1.4.7
Summary: Ory Agent Security core for Python — authentication, per-tool authorization, activity logging, and identity propagation for Agent SDK integrations. Python sibling of the TypeScript @ory/argus.
Author: Ory
License-Expression: Apache-2.0
Keywords: agent,ai,audit,authentication,authorization,ory,permissions
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: ory-client<2,>=1.22
Requires-Dist: tree-sitter-bash<0.26,>=0.25
Requires-Dist: tree-sitter>=0.23
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ory-argus (Python)

Ory Agent Security core for Python — the sibling of the TypeScript
[`@ory/argus`](https://www.npmjs.com/package/@ory/argus) package.

It provides the shared primitives that the Ory **Agent SDK integrations**
 (LangChain, OpenAI Agents, Pydantic AI, Microsoft Agent Framework, CrewAI,
 LlamaIndex, Google ADK, AWS Strands, Google Antigravity, Hermes Agent) build on:

1. **Authenticate** the session on startup (user PKCE login + injected or Talos runtime identity).
2. **Authorize** every tool call against Ory Permissions (Zanzibar-style relation checks).
3. **Record** every tool invocation as a privacy-safe structured activity event in the unified NDJSON log.
4. **Propagate identity** through the user → agent → sub-agent delegation chain.

## Interop with the TypeScript core

`ory-argus` reads and writes the **same** shared config file as every TS harness
plugin — `~/.config/ory-agent-plugins/config.json` (XDG / `%APPDATA%` aware). A
user who logs in via a TS coding-agent harness has those credentials transparently
reused by a Python SDK integration, and vice-versa. This package never invents a
second config location; use `get_data_dir()` / `get_config_path()`.

Install: `pip install ory-argus` · Console script: `ory-argus`

## SPIFFE runtime authentication

Call `create_spiffe_file_request_authenticator(generation_path=...,
generation_file=..., expected_server_spiffe_id=...)` for generated SPIFFE deployments.
The expected ID must exactly match a URI SAN on the peer leaf; CA-chain verification
remains enabled, while DNS SANs and other same-bundle workloads do not satisfy it.
The authenticator uses TLS 1.3 mutual TLS and does not consume forwarded identity
headers. The generation directory defaults to `svid.pem`, `svid-key.pem`, and
`bundle.pem`; atomically switch its symlink to rotate a coherent set. If provided,
`generation_file` is checked before and after each snapshot. Hosted Web-PKI servers
must explicitly set `verify_hostname=True` instead of `expected_server_spiffe_id`;
that mode reads the bundle as part of the material snapshot but uses system trust
roots and ordinary HTTPS hostname verification. Server-SPIFFE mode trusts the
workload bundle and requires the exact sole URI SAN. Exactly one identity mode is
required. The legacy three-path form remains available but cannot guarantee a
coherent snapshot. One request setup is retried if rotation races with
certificate/key validation.

Administrator-preprovisioned headless Agents normally provide only
`ORY_AGENT_API_KEY` (or an injected runtime authenticator such as SPIFFE) plus the
project and Agent Security URLs. Before PKCE, Argus resolves the subject and opaque root
from Agent Security and keeps them only in memory. `ORY_AGENT_SUBJECT_ID` and
`ORY_AGENT_ROOT_DELEGATION` remain compatibility overrides; a complete legacy package
skips the context request.
