GHSA-rv2q-f2h5-6xmg: Node Role Device Identity Bypass in OpenClaw

OpenClaw acts as a central infrastructure for AI agents, managing communication between gateways, processing nodes, and client devices via WebSockets. A critical security flaw was identified in the ws-connection/message-handler.ts component, specifically within the handshake logic responsible for validating device identities. The vulnerability stems from an overly permissive authorization check that allowed clients to bypass device pairing if they presented a valid shared gateway token.

In a secure configuration, OpenClaw requires distinct authentication proofs for different roles. While operators might legitimately use a shared token for administrative access, processing nodes are expected to be paired devices with specific identities. The vulnerability conflated these requirements, treating the possession of a shared token as a universal pass to skip device identity verification. This failure in the authorization model effectively broke the binding between hardware nodes and the central gateway.

The impact of this bypass is significant because the node role possesses privileged capabilities within the system. Nodes are responsible for processing voice streams and triggering agent behaviors. By spoofing this role, an attacker can inject malicious node.event messages, leading to unauthorized command execution within the agent framework or manipulation of the voice processing pipeline.

The root cause of this vulnerability lies in a logic error within the boolean evaluation of connection privileges. The application defines a canSkipDevice flag, which determines whether an incoming WebSocket connection requires a valid device object to proceed. In the vulnerable implementation, this flag was derived solely from the variable sharedAuthOk, which indicated whether the connection was established using a valid shared gateway token.

The code failed to check the context in which the shared token was being used. Specifically, it did not validate the requested role before granting the bypass. The logic can be summarized as: "If the token is valid, device identity is optional." This assumption is valid for operator connections (which may be ephemeral UI sessions) but dangerous for node connections (which represent trusted hardware infrastructure).

Consequently, any client capable of authenticating with the shared token automatically inherited the canSkipDevice privilege. When such a client requested the role: 'node', the system proceeded to establish the session without enforcing the mandatory device pairing protocol. This represents a classic CWE-863 (Incorrect Authorization) flaw, where the system validates credentials (the token) but fails to verify that those credentials grant the specific privilege requested (skipping device identity for a Node).

The vulnerability existed in src/gateway/server/ws-connection/message-handler.ts. The following comparison highlights the defective logic and the subsequent remediation.

Vulnerable Implementation: In the original code, the decision to skip device validation was purely based on sharedAuthOk. This boolean was true whenever a valid shared token was presented during the handshake.

// VULNERABLE CODE
// If the shared token is valid, we allow skipping the device check
// regardless of the role requested by the client.
const canSkipDevice = sharedAuthOk;
 
if (!device && !canSkipDevice) {
  // Error handling for missing device
}

Patched Implementation: The fix, introduced in commit ddcb2d79, refines the condition. It now explicitly requires that the client is requesting the operator role in addition to having a valid shared token to bypass the device check. For all other roles, including node, canSkipDevice evaluates to false, enforcing the presence of a valid device object.

// PATCHED CODE
// The bypass is now scoped strictly to the 'operator' role.
// A 'node' requesting a connection with a shared token must still provide a device.
const canSkipDevice = role === "operator" && sharedAuthOk;
 
if (!device && !canSkipDevice) {
  // Correctly rejects 'node' roles missing device info
  return socket.close(4003, "Device required for this role");
}

This change ensures that the security model for nodes—requiring strict device identity—cannot be circumvented simply by possessing a shared token intended for operators.

To exploit this vulnerability, an attacker requires network access to the OpenClaw WebSocket gateway and possession of the shared gateway token. This token is often distributed for internal integrations or operator access, making it a lower-privilege credential compared to a paired hardware identity.

The attack follows a standard WebSocket handshake manipulation:

1. Connection Initiation: The attacker opens a WebSocket connection to the gateway endpoint.
2. Handshake Payload: The attacker constructs a connection payload containing the valid shared token, sets the role to node, and explicitly sets the device field to null.
3. Bypass Trigger: The server verifies the token, sets sharedAuthOk to true, and consequently sets canSkipDevice to true. The check for the device field is skipped.
4. Session Establishment: The server registers the connection as a valid Node.

Once the session is active, the attacker can send frames reserved for processing nodes. The primary vector is the node.event message type. By injecting these events, the attacker can simulate voice commands or hardware triggers, forcing the AI agents to execute actions defined in their logic. This effectively allows remote control over the agent infrastructure without compromising a physical device.

The vulnerability was officially patched in February 2026. The remediation involves updating the OpenClaw gateway code to ensure strict role-based checking during the connection phase. The fix explicitly couples the device-skip privilege to the operator role.

Immediate Actions:

• Update Software: Administrators should immediately update to the version containing commit ddcb2d79b17bf2a42c5037d8aeff1537a12b931e. Verify that src/gateway/server/ws-connection/message-handler.ts contains the updated logic const canSkipDevice = role === "operator" && sharedAuthOk.
• Rotate Shared Tokens: Since the exploitation relies on the shared gateway token, it is prudent to rotate this secret. If an attacker has previously harvested this token, they may attempt to use it again, although the patch will prevent the specific node-impersonation attack.
• Audit Logs: Review WebSocket connection logs for historic connections where role: 'node' was successfully established without a corresponding device ID. This may indicate past exploitation attempts.

For environments where immediate code deployment is not possible, network-level restrictions on the WebSocket endpoint could limit the attack surface, though this does not fix the underlying logic flaw.