Principle:OpenHands OpenHands Permission Check
| Knowledge Sources | |
|---|---|
| Domains | Platform_Integration, Webhook_Processing |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Permission checking is the access control pattern that validates whether the user who triggered a webhook event is authorized to initiate automated processing on the target resource.
Description
When a webhook event arrives, the system must determine not only what happened but also who initiated it and whether that user has sufficient privileges to trigger downstream automation. This is critical because webhook events are externally sourced: any user who can interact with a repository (including those with read-only access) can generate events. Without permission checking, the system would process events from unauthorized users, potentially consuming expensive compute resources, exposing proprietary code to untrusted parties, or executing code modifications on behalf of unprivileged users.
The permission check pattern operates at the intersection of three concerns:
- Role-Based Access Control (RBAC) -- Verifying the user's role (read, triage, write, maintain, admin) against a minimum threshold required for the operation.
- Escalation Prevention -- Ensuring that the automation does not grant the triggering user capabilities beyond their existing permissions (e.g., a read-only user should not be able to trigger a bot that pushes commits).
- Event Filtering -- Distinguishing between events that warrant automated action (e.g., a comment mentioning the bot) and events that should be ignored (e.g., a label change or an event from a bot account).
Usage
Apply permission checking whenever:
- An external event triggers resource-intensive automation (agent execution, CI pipelines)
- The automation will perform write operations on behalf of the triggering user
- The system must enforce organizational access policies
- The webhook endpoint is exposed to events from users with varying privilege levels
Theoretical Basis
Permission checking in webhook processing draws from established access control theory.
1. Reference Monitor Concept
The permission check acts as a reference monitor -- a trusted component that mediates all access to protected resources. The reference monitor must satisfy three properties:
- Complete mediation: Every access request is checked.
- Tamper-proof: The check cannot be bypassed.
- Verifiable: The logic is simple enough to be audited.
2. Lattice-Based Access Control
Repository permissions form a lattice where each level subsumes the capabilities of the level below:
admin > maintain > write > triage > read
For a minimum required permission level P_min and a user's actual permission level P_user:
authorized = P_user >= P_min
3. Event Qualification Logic
Not all events from authorized users should trigger processing. The qualification function combines permission checking with event-type filtering:
should_process(event, user):
if user.is_bot:
return False
if event.type not in SUPPORTED_EVENT_TYPES:
return False
if user.permission_level < MINIMUM_REQUIRED_LEVEL:
return False
return True
4. Fail-Closed Design
The permission check follows a fail-closed principle: if the permission status cannot be determined (e.g., the GitHub API is unreachable), the event is rejected rather than allowed. This prevents privilege escalation through transient failures.
check_permission(user, resource):
try:
level = fetch_permission(user, resource)
return level >= MINIMUM_LEVEL
except Error:
return False # fail closed