Connector Overview¶

ARX connectors are the enforcement boundary between AI agents and the security tools they operate. Every action an agent takes against an external system — querying a SIEM, isolating an endpoint, rotating a credential — passes through a connector. Connectors do not simply proxy API calls. They intercept each operation, evaluate it against organizational policy, log it to an immutable audit trail, and only then execute it against the target system with scoped credentials.

ARX ships with 101+ connectors across 10 categories, covering EDR/XDR, SIEM, cloud security, identity and access management, application security, network and email security, threat intelligence, ITSM and communications, GRC and compliance, and secrets management.

The BaseConnector Intercept Pattern (INV-002)¶

Every connector extends BaseConnector, which implements the INV-002 intercept pattern. When an agent calls execute(operation, params), the following sequence runs before any external API call is made:

1. Credential loading — The connector resolves credentials from plaintext or encrypted storage (see Credential Management below).
2. Policy evaluation — The PolicyEngine evaluates the operation against the organization's policy set, returning a verdict (ALLOW, DENY, or ESCALATE), a numeric risk score, and the matched policy ID.
3. Audit logging — An intercept record is written to the audit log, capturing the agent ID, organization ID, connector name, operation, verdict, risk score, and policy ID. This happens before execution, ensuring that denied operations are still recorded.
4. Verdict routing — If the verdict is DENY, the connector raises PermissionDeniedError and the call terminates. If ESCALATE, the connector creates a human-in-the-loop approval request and blocks until a reviewer acts. Only on ALLOW (or approved escalation) does execution proceed.
5. Execution — The connector's _execute_impl method runs the operation against the target system using the loaded credentials.
6. Result audit — The response from the target system is appended to the audit record, completing the chain of custody.

This pattern is non-optional. There is no code path that bypasses policy evaluation or audit logging. Subclasses implement _execute_impl and declare a connector_name property; the intercept logic is inherited and cannot be overridden.

Credential Management (INV-005)¶

Connectors never store credentials in application memory beyond the scope of a single execute call. Credentials are loaded on demand through _load_credentials(), which supports two modes:

• Plaintext credentials — Passed directly during connector initialization, typically sourced from an in-memory vault client. Used in development and testing.
• Encrypted credentials — Stored as encrypted bytes and decrypted at call time via decrypt_credentials(). Used in production, where credentials are sealed by the organization's encryption key and stored in the ARX vault.

Credential rotation, access scoping, and key management are handled at the vault layer. Connectors are stateless with respect to secrets; they request credentials, use them for a single operation, and discard them.

The OPERATION_MAP Structure¶

Each connector defines an OPERATION_MAP — a dictionary that maps operation names to their metadata, including the HTTP method, API endpoint template, required parameters, optional parameters, and risk classification. For example:

OPERATION_MAP = {
    "list_alerts": {
        "method": "GET",
        "endpoint": "/alerts",
        "risk": "LOW",
        "description": "List security alerts with optional filters",
        "required_params": [],
        "optional_params": ["severity", "status", "limit"],
    },
    "isolate_host": {
        "method": "POST",
        "endpoint": "/hosts/{host_id}/isolate",
        "risk": "HIGH",
        "description": "Network-isolate a host from the environment",
        "required_params": ["host_id"],
        "optional_params": ["comment"],
    },
}

The OPERATION_MAP serves three purposes. First, it provides a declarative schema that the policy engine uses to classify operations before execution. Second, it generates the agent's available action set — agents can only invoke operations that exist in the map. Third, it drives documentation and UI rendering, ensuring that every operation is discoverable and consistently described.

Risk Classification¶

Every operation in every connector carries a risk level. ARX uses four tiers:

Risk levels drive policy evaluation. An organization might configure a policy that allows LOW and MEDIUM operations automatically, escalates HIGH operations to a human reviewer, and denies CRITICAL operations outright unless invoked by a named principal. Risk levels are assigned per-operation in the OPERATION_MAP and can be overridden by organizational policy.

Policy Evaluation¶

The PolicyEngine.evaluate() method runs on every execute call. It takes the agent ID, organization ID, connector name, operation name, and session context as inputs and returns a verdict. Policy evaluation considers:

• Operation risk level — The static risk classification from the OPERATION_MAP.
• Agent permissions — The set of connectors and operations the agent is authorized to use, as defined in the agent's configuration.
• Organization policy — Rules defined at the organization level, such as "all HIGH operations on CrowdStrike require approval" or "deny all CRITICAL operations between 02:00 and 06:00 UTC."
• Session context — Runtime context including the agent's current investigation, the number of operations executed in the session, and any escalation state from prior calls.

Verdicts are deterministic for a given policy set. The same operation under the same conditions always produces the same verdict, which is essential for auditability and compliance.

Audit Logging¶

Every connector call generates two audit records:

1. Intercept record — Written before execution. Contains the connector, operation, verdict, risk score, policy ID, agent ID, and organization ID. This record exists even if the operation is denied.
2. Result record — Written after execution (or after denial/escalation). Contains the operation outcome, including response data from the target system or the denial reason.

Audit records are immutable. They support INV-001 data collection requirements and provide the forensic trail needed for compliance frameworks (SOC 2, ISO 27001, FedRAMP). The audit log is queryable through the ARX API and exportable to external SIEM systems.

Human-in-the-Loop Escalation¶

When the policy engine returns an ESCALATE verdict, the connector creates an approval request in the approval_requests table and dispatches notifications to configured channels (Slack, Microsoft Teams, or webhooks). The approval request includes the operation details, risk score, agent name, and policy context. A human reviewer can approve or deny the request through the ARX dashboard or directly from the notification.

Until the reviewer acts, the agent's operation is blocked. If denied, ApprovalDeniedError is raised. If approved, execution proceeds and the approval ID is linked to the audit record.

Connector Categories¶

ARX organizes its 101+ connectors into 10 categories:

Each category index page lists the available connectors, their operation counts, risk levels, and links to individual connector documentation.