Command Approval Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Command Approval Workflows in Hoop provide a security layer that sits between users and infrastructure, requiring human intervention before sensitive or risky operations are executed. This system allows organizations to route production writes, schema changes, or configuration mutations for approval via integrated communication platforms like Slack or Microsoft Teams.
The workflow ensures that every session and command is recorded and indexed, providing full visibility into "who" did "what" and "why". By utilizing "Just-in-Time" (JIT) reviews and "Review by Command," the project enforces time-bound access and granular control over terminal and native access flows.
Sources: README.md:12-32, webapp_v2/src/pages/Roles/Configure/components/ReviewSection.jsx:13-20
Review Types and Mechanisms
The system supports multiple review strategies depending on the access mode and the level of granularity required.
Review by Command
This mechanism requires approval for specific commands executed through the Web Terminal or the Hoop CLI. It is primarily used for "One-Off" executions where a specific script or statement needs to be validated by a peer before reaching the infrastructure.
Sources: webapp_v2/src/pages/Roles/Configure/components/ReviewSection.jsx:15-18, webapp_v2/src/pages/Roles/Configure/TerminalAccessTab.jsx:38-51
Just-in-Time (JIT) Review
JIT reviews provide a time-bound window for access. Once approved, the user is granted permission to interact with the resource role for a predefined duration (e.g., 15 minutes to 8 hours).
Sources: webapp_v2/src/pages/Roles/Configure/components/ReviewSection.jsx:21-30
Access Request Rules
Advanced workflows utilize AccessRequestRule objects to define complex logic, such as requiring approvals from all listed groups or a specific minimum number of approvals.
Sources: gateway/api/review/review_test.go:30-45
Workflow State Machine
The lifecycle of an approval request transitions through several statuses, managed by the gateway's review logic.
This diagram illustrates the state transitions for a command review request.
Sources: gateway/api/review/review_test.go:78-360, client/cmd/sessions.go:275-285
Configuration and Management
Approvals are configured at the Resource Role level. Administrators define which user groups are eligible to approve requests and set constraints on the approval process.
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
reviewers | Array (Groups) | List of user groups authorized to approve the request. |
min_review_approvals | Integer | The minimum number of approvals required from the authorized groups. |
force_approve_groups | Array (Groups) | Groups that can bypass standard minimums to immediately approve a request. |
access_max_duration | Integer | Max duration (in seconds) for JIT access windows. |
Sources: webapp_v2/src/pages/Roles/Configure/components/ReviewSection.jsx:56-115, gateway/api/review/review_test.go:30-45
User Roles and Eligibility
The system distinguishes between several types of participants:
- Owner: The user who initiated the session/command. Owners cannot self-approve their requests but can reject (revoke) them.
- Reviewer: A member of an "Approval User Group."
- Admin: Has the privilege to deny reviews even if not an explicitly listed reviewer for that specific group.
Sources: gateway/api/review/review_test.go:343-375, gateway/api/review/review_test.go:445-455
Integration and Monitoring
The workflow is integrated with external communication tools to facilitate real-time notifications and decision-making.
Webhook Integration (Microsoft Teams)
When a review is created, the system triggers a webhook, sending an Adaptive Card to Microsoft Teams. This card contains:
- Session ID: A unique link to the session.
- Context: "Created By" information and the specific "Connection" name.
- Command Content: A
CodeBlockshowing the SQL or script waiting for execution.
Sources: gateway/transport/plugins/webhooks/microsoftteams.review.create.json:13-75
Session Inspection (CLI)
Users can monitor the status of reviews using the CLI via the sessions command.
# List sessions pending approval
hoop sessions list --review-status pending
# Inspect detailed review status for a specific session
hoop sessions get <session-id>
Sources: client/cmd/sessions.go:68-85
Session Data Model (Review Segment)
The review data returned by the API includes the status of individual approval groups.
"review": {
"status": "PENDING",
"type": "onetime",
"min_approvals": "1",
"review_groups_data": [
{
"group": "sre-team",
"status": "APPROVED",
"reviewed_by": {"email": "admin@hoop.dev"},
"review_date": "2024-05-20T10:00:00Z"
}
]
}
Sources: client/cmd/sessions.go:424-460, client/cmd/admin/get.go:485-515
Summary
Command Approval Workflows serve as a gatekeeper for infrastructure access in Hoop. By combining granular role-based configuration, peer-review requirements, and real-time integration with team communication tools, the system mitigates the risk of destructive operations. The architecture supports both transactional command-level reviews and temporal access windows, ensuring that sensitive data and critical systems are protected by human-verified governance.
Sources: README.md:120-135, webapp_v2/src/pages/Roles/Configure/components/ReviewSection.jsx:13-35