Skip to content

Configuration Reference

This page documents all configuration options for the Capiscio Python SDK.

Auto-Generated Reference

For the most accurate API documentation, see the SDK Reference which is auto-generated from source code.

SimpleGuard Configuration

SimpleGuard uses convention over configuration. It auto-discovers keys based on directory structure.

Constructor Parameters

from capiscio_sdk import SimpleGuard

guard = SimpleGuard(
    base_dir=None,     # Optional: Starting directory (defaults to cwd)
    dev_mode=False,    # Optional: Auto-generate keys if missing
)
Parameter Type Default Description
base_dir str \| Path \| None None Directory to search for config (defaults to current working directory)
dev_mode bool False If True, auto-generates keys and agent-card.json

Expected Directory Structure

SimpleGuard walks up from base_dir looking for agent-card.json:

your-project/              # ← SimpleGuard finds this via walk-up
├── agent-card.json        # Agent identity (required)
└── capiscio_keys/
    ├── private.pem        # Ed25519 private key (required for signing)
    ├── public.pem         # Ed25519 public key
    └── trusted/           # Trust store directory
        ├── partner-a.pem  # Trusted public key (filename = kid)
        └── partner-b.pem

Development vs Production

# Auto-generates all missing files
guard = SimpleGuard(dev_mode=True)
  • Creates agent-card.json with default values
  • Generates Ed25519 keypair
  • Adds self-trust for local testing
# Requires existing keys
guard = SimpleGuard()  # dev_mode=False by default

# Or specify config location
guard = SimpleGuard(base_dir="/etc/capiscio")
  • Raises ConfigurationError if keys missing
  • No auto-generation

SecurityConfig

Configuration for CapiscioSecurityExecutor. Controls security behavior for incoming and outgoing requests.

Fields

Field Type Default Description
downstream DownstreamConfig DownstreamConfig() Incoming request settings
upstream UpstreamConfig UpstreamConfig() Outgoing request settings
strict_mode bool False Enable strict validation
fail_mode "block" \| "monitor" \| "log" "block" How to handle failures
log_validation_failures bool True Log validation failures
timeout_ms int 5000 Request timeout in milliseconds

Presets

from capiscio_sdk import SecurityConfig

# Development - permissive, logs instead of blocking
config = SecurityConfig.development()

# Production - balanced security
config = SecurityConfig.production()

# Strict - maximum security
config = SecurityConfig.strict()

# From environment variables
config = SecurityConfig.from_env()

DownstreamConfig

Controls how incoming requests are validated.

Fields

Field Type Default Description
validate_schema bool True Validate A2A message schema
verify_signatures bool True Verify request signatures
require_signatures bool False Reject unsigned requests
check_protocol_compliance bool True Check A2A protocol compliance
enable_rate_limiting bool True Enable rate limiting
rate_limit_requests_per_minute int 60 Rate limit threshold

Example

from capiscio_sdk import DownstreamConfig

downstream = DownstreamConfig(
    validate_schema=True,
    verify_signatures=True,
    require_signatures=True,  # Strict: reject unsigned
    enable_rate_limiting=True,
    rate_limit_requests_per_minute=100,
)

UpstreamConfig

Controls how outgoing requests to other agents are handled.

Fields

Field Type Default Description
validate_agent_cards bool True Validate upstream agent cards
verify_signatures bool True Verify response signatures
require_signatures bool False Reject unsigned responses
test_endpoints bool False Test endpoint availability (slow)
cache_validation bool True Cache validation results
cache_timeout int 3600 Cache TTL in seconds

Example

from capiscio_sdk import UpstreamConfig

upstream = UpstreamConfig(
    validate_agent_cards=True,
    verify_signatures=True,
    require_signatures=False,
    cache_validation=True,
    cache_timeout=1800,  # 30 minutes
)

Environment Variables

SecurityConfig.from_env() reads these environment variables:

Variable Type Default Maps To
CAPISCIO_VALIDATE_SCHEMA bool true downstream.validate_schema
CAPISCIO_VERIFY_SIGNATURES bool true downstream.verify_signatures
CAPISCIO_REQUIRE_SIGNATURES bool false downstream.require_signatures
CAPISCIO_RATE_LIMITING bool true downstream.enable_rate_limiting
CAPISCIO_RATE_LIMIT_RPM int 60 downstream.rate_limit_requests_per_minute
CAPISCIO_VALIDATE_UPSTREAM bool true upstream.validate_agent_cards
CAPISCIO_VERIFY_UPSTREAM_SIGNATURES bool true upstream.verify_signatures
CAPISCIO_CACHE_VALIDATION bool true upstream.cache_validation
CAPISCIO_FAIL_MODE string block fail_mode
CAPISCIO_TIMEOUT_MS int 5000 timeout_ms

Example

# Production environment
export CAPISCIO_REQUIRE_SIGNATURES=true
export CAPISCIO_FAIL_MODE=block
export CAPISCIO_RATE_LIMIT_RPM=100

from capiscio_sdk import SecurityConfig

config = SecurityConfig.from_env()

Policy Enforcement (Server)

These environment variables configure the PDP integration on the CapiscIO server (RFC-005). They are read by the server, not the SDK.

Variable Type Default Description
CAPISCIO_PDP_ENDPOINT string (empty) PDP URL. Empty = badge-only mode
CAPISCIO_PDP_TIMEOUT_MS int 500 PDP query timeout in milliseconds
CAPISCIO_ENFORCEMENT_MODE string EM-OBSERVE EM-OBSERVE, EM-GUARD, EM-DELEGATE, or EM-STRICT
CAPISCIO_BREAKGLASS_PUBLIC_KEY string (empty) Path to break-glass Ed25519 public key
CAPISCIO_PEP_ID string (empty) PEP instance identifier
CAPISCIO_WORKSPACE string (empty) Workspace/tenant identifier

Example

# Enable policy enforcement in observe mode
export CAPISCIO_PDP_ENDPOINT=http://pdp.internal:9090/v1/evaluate
export CAPISCIO_ENFORCEMENT_MODE=EM-OBSERVE
export CAPISCIO_PDP_TIMEOUT_MS=500

See Policy Enforcement Setup for step-by-step configuration.

Complete Example

from capiscio_sdk import (
    SimpleGuard,
    CapiscioSecurityExecutor,
    SecurityConfig,
    DownstreamConfig,
    UpstreamConfig,
)

# SimpleGuard for signing/verification
guard = SimpleGuard(dev_mode=True)

# Custom security config
config = SecurityConfig(
    downstream=DownstreamConfig(
        validate_schema=True,
        require_signatures=True,
        rate_limit_requests_per_minute=100,
    ),
    upstream=UpstreamConfig(
        validate_agent_cards=True,
        cache_timeout=1800,
    ),
    fail_mode="block",
)

# Wrap your agent
executor = CapiscioSecurityExecutor(
    delegate=my_agent,
    config=config,
)

See Also