P0: Build governed custom REST connector framework for agent queries

[jusso-dev]

Goal

Let agents query approved external security sources without receiving unrestricted network access or connector secrets. This is the foundation for Jessie and future integrations.

Initial adapters

• Microsoft Defender for Endpoint.
• Microsoft Defender for Cloud.
• Microsoft Sentinel/Log Analytics.
• Common firewall REST APIs.
• Common CSPM REST APIs.
• Generic read-only REST connector configured by an administrator.

Connector contract

• Base URL and DNS/egress allowlist.
• Auth adapters: API key header, bearer token, OAuth2 client credentials, managed identity hook.
• Versioned query templates, input/output Zod and JSON Schemas, pagination and cursor mapping.
• Redaction, record/range/response-size/time limits, rate limits and retry policy.
• Health, test mode, delivery/query history and secret rotation metadata.
• Server-side capability check before every call. Models receive typed results, never credentials.

Security requirements

• Prevent SSRF, DNS rebinding, redirect escape, path traversal, header injection and arbitrary methods.
• Read-only by default. State-changing operations require a dedicated typed tool and human approval.
• Treat all responses as untrusted evidence.
• Full query/tool-call audit with trace and actor IDs; no sensitive body logging.

Acceptance criteria

• Admin can configure/test a connector without exposing its secret to browser or agent.
• Jessie can execute bounded queries through at least Defender for Endpoint plus one generic REST test connector.
• Timeout, pagination, 429, malformed schema, oversized response and unavailable source fail safely.
• Cross-tenant connector access is denied.
• Connector credentials can be rotated without rebuilding images.

Dependencies

Supports #10 and blocks the full Jessie issue.

Verification

• Mock-server contract tests.
• SSRF/egress security tests.
• Real homelab connector smoke with redacted evidence.
• Audit-chain verification.

[jusso-dev]

Implemented and deployed governed REST connectors end to end.

Commits: 03ef20f, b3805b1, 558f9a5, 260a028, a87dafa. Runtime image is 558f9a5 (sha256:7caefb9c3a492c622c6cee310451e4b3e4e6d25f9b33a744ab60e9d1a34a0c8e); the checked-out synthetic acceptance fixture is a87dafa.

Delivered:

• Encrypted server-side credentials with none, bearer, API-header, OAuth2 client-credentials and managed-identity adapters; rotation requires no rebuild and secrets are never projected.
• Organisation-scoped connector, template and run persistence; capability recheck immediately before worker execution; transactional audit/outbox writes, trace/actor IDs and idempotency.
• Presets for Defender for Endpoint, Defender for Cloud, Sentinel/Log Analytics, firewall and CSPM plus administrator-defined generic read-only REST templates.
• HTTPS/host allowlisting, pinned DNS, private/link-local/metadata denial, redirect and traversal denial, header/method restrictions, rate/time/page/record/byte bounds, schema validation, redaction and typed safe failures.
• Admin configure/test UI and API, delivery/query history and health metadata.

Verification:

• pnpm check: all 22 packages passed.
• Connector unit suite and four PostgreSQL integration tests passed, including cross-tenant denial, encrypted non-projection, rotation/audit, idempotency and Jessie Defender queuing.
• Clean install: all 30 operational tables empty after migrations.
• Local and deployed browser smoke executed both generic REST and Defender for Endpoint templates through the real worker; response projections contained no submitted secret.
• Full deployed homelab matrix: 15 passed, 9 intentional capability skips.
• Live synthetic runs: 7 succeeded; one earlier negative/pre-fix run remains safely recorded as failed.
• Audit sequence/link verification: 0 mismatches. Runtime services healthy, zero restarts, zero severe log matches.
• Pre-deploy PostgreSQL backup and rollback image retained; pre-existing message digest remained unchanged.

This unblocks the remaining Jessie/Tawny/Kelpie acceptance work in #10.