From 86544e423be7bec9d750b50ab5af214828431a60 Mon Sep 17 00:00:00 2001 From: Nathan Aronson Date: Mon, 2 Mar 2026 19:49:55 -0500 Subject: [PATCH] docs: expand Concepts section and add Local Auth page - Rewrite concepts/resource-roles.mdx with accurate type/subtype tables, credential format, agent binding, access modes, and feature-plugin mapping - Add concepts/sessions.mdx covering lifecycle states, recorded data, and visibility rules by role - Add concepts/plugins.mdx with default plugin set, full plugin reference, and managed-by-connection behavior for review and dlp - Add setup/configuration/idp/local-auth.mdx covering first-user-admin flow, invite model, AUTH_METHOD env var, and transitioning to OIDC/SAML - Update IDP get-started.mdx to add Local Auth card to CardGroup - Update docs.json to add sessions, plugins, and local-auth to navigation Co-Authored-By: Claude Sonnet 4.6 --- concepts/plugins.mdx | 57 +++++ concepts/resource-roles.mdx | 272 ++++++++---------------- concepts/sessions.mdx | 58 +++++ docs.json | 5 +- setup/configuration/idp/get-started.mdx | 1 + setup/configuration/idp/local-auth.mdx | 55 +++++ 6 files changed, 268 insertions(+), 180 deletions(-) create mode 100644 concepts/plugins.mdx create mode 100644 concepts/sessions.mdx create mode 100644 setup/configuration/idp/local-auth.mdx diff --git a/concepts/plugins.mdx b/concepts/plugins.mdx new file mode 100644 index 0000000..76cc89f --- /dev/null +++ b/concepts/plugins.mdx @@ -0,0 +1,57 @@ +--- +title: "Plugins" +description: "Gateway extensions that intercept session lifecycle events and enforce policies on connections" +--- + +Plugins are the mechanism by which Hoop features are applied to connections. They intercept events during a session's lifecycle — when it opens, when data flows through, and when it closes — and enforce policies or forward information to external systems. + +## How Plugins Work + +Plugins are enabled **per-connection**. When you create a connection, a default set of plugins is automatically attached to it. You can configure additional plugins on a connection-by-connection basis. + +Plugins are not global switches. Enabling a plugin for your organization doesn't activate it on every connection — it activates it only on connections to which the plugin is explicitly attached. + +## Default Plugins + +The following plugins are automatically attached to every new connection: + +| Plugin | What it does | +|--------|-------------| +| `audit` | Records all session activity. Always active. | +| `dlp` | Data Loss Prevention. Scans session output and redacts configured data types. Inactive until redact types are configured on the connection. | +| `review` | Access Request workflow. Holds execution until a designated reviewer group approves. Inactive until reviewers are configured on the connection. | +| `slack` | Sends Slack notifications for access request events and session activity. | + +## Full Plugin Reference + +| Plugin | Feature | Description | +|--------|---------|-------------| +| `audit` | Session Recording | Captures all session input and output. Always active; cannot be removed. | +| `dlp` | Live Data Masking | Redacts sensitive data patterns in session output. Configurable types include `EMAIL_ADDRESS`, `CREDIT_CARD_NUMBER`, `PHONE_NUMBER`, and more. See [Live Data Masking](/setup/configuration/live-data-masking/fields). | +| `review` | Access Requests | Implements the approval workflow. A session is held in `open` state until the required reviewers approve or reject it. See [Access Requests](/learn/features/access-requests/action). | +| `slack` | Slack Notifications | Sends messages to configured Slack channels for access request events. See [Slack Integration](/integrations/slack). | +| `runbooks` | Runbooks | Enables runbook script execution on the connection. Must be explicitly added. See [Runbooks](/learn/features/runbooks). | +| `access_control` | Access Control | Restricts which user groups can see and interact with the connection. Must be explicitly added. See [Access Control](/learn/features/access-control). | +| `webhooks` | Webhooks / SIEM | Forwards session lifecycle events to external webhook endpoints. Must be explicitly added. See [Webhooks & SIEM](/setup/apis/webhooks-siem). | +| `indexer` | Session Search | Indexes session content for full-text search within the platform. | + +## Plugins Managed by Connection + +Two plugins — `review` and `dlp` — are configured directly on the connection resource rather than through the plugin API. Their behavior is tied to connection-level fields: + +- **`dlp`** is configured via the `redact_types` field on the connection. Setting one or more redact types activates the plugin on that connection; removing all types deactivates it. +- **`review`** is configured via the `reviewers` field on the connection. Setting one or more reviewer groups activates the approval workflow; removing all reviewers deactivates it. + +These two plugins are created automatically when a connection is created and cannot be deleted independently. + +## Feature → Plugin Mapping + +| Feature | Plugin | +|---------|--------| +| Session Recording | `audit` | +| Live Data Masking | `dlp` | +| Access Requests | `review` | +| Slack Notifications | `slack` | +| Runbooks | `runbooks` | +| Access Control | `access_control` | +| Webhooks / SIEM | `webhooks` | diff --git a/concepts/resource-roles.mdx b/concepts/resource-roles.mdx index ef1f36e..2e7377b 100644 --- a/concepts/resource-roles.mdx +++ b/concepts/resource-roles.mdx @@ -1,203 +1,117 @@ --- title: "Resource Roles" -description: "The bridge between users and resources" +description: "Connections that expose internal services to authorized users through the Hoop gateway" --- -Connections +In the **Web App**, these are called **Resource Roles**. In the **API**, the same objects are called **connections**. They refer to the same thing: a named, typed configuration that exposes an internal service through a Hoop agent. -Connections +## Connection Types -# Resource Roles +Every connection has a `type` and an optional `subtype`. -Resource Roles are a central concept in Hoop.dev that serve as secure bridges between users and your organization's resources. They enable controlled access to internal services, databases, and other resources while maintaining security and compliance. Resource Roles are defined by the administrator and can be assigned to users and groups. +### Database (`type: "database"`) -## What is a Resource Role? +Connections that implement native database wire protocols. Hoop intercepts queries and can enforce masking, guardrails, and access policies on the traffic. -A Resource Role is a configurable connection that exposes internal services from your infrastructure to authorized users in a secure and controlled manner. It acts as an intermediary layer that: +| Subtype | Protocol | +|---------|----------| +| `postgres` | PostgreSQL wire protocol | +| `mysql` | MySQL protocol | +| `mongodb` | MongoDB Wire Protocol | +| `mssql` | Microsoft SQL Server | +| `oracledb` | Oracle Database | -- Provides secure access to internal resources -- Enforces access control policies -- Enables monitoring and auditing of resource usage -- Supports various types of services and protocols +### Application (`type: "application"`) -## Types of Resources +Connections to networked services and processes. -Hoop.dev supports several types of connections: +| Subtype | Description | +|---------|-------------| +| `httpproxy` | Forwards HTTP/HTTPS traffic to an upstream service | +| `tcp` | Raw TCP forwarding | +| `ssh` | SSH tunneling | -**Databases** +### Custom (`type: "custom"`) -- PostgreSQL, MySQL and many other database systems +Arbitrary shell command execution. Use this type when your resource doesn't fit a standard protocol. The `command` field defines what runs when a session opens. -**Applications** +## Agent Binding -- TCP forwarding, custom CLI tools, and web services +Each connection is bound to an agent via the `agent_id` field. The connection's status reflects the agent's reachability: -**Custom Resources** +- **`online`** — the agent is connected and the resource is accessible +- **`offline`** — the agent is not connected or the resource is unreachable -- Ability to connect to specialized resources -- Support for complex configurations -- Integration with custom tools and services +If no `agent_id` is set on the connection, it inherits the agent from the associated resource. -## Key Features +## Credentials -### Access Control +Connection secrets (database passwords, API tokens, hostnames) are stored as environment variables attached to the connection. In the API, they are submitted under a `secret` object with `"envvar:KEY"` keys, base64-encoded: -- Granular permission management -- Group-based access policies -- Access request approval processes for sensitive resources +```json +{ + "secret": { + "envvar:HOST": "bXlkYi5leGFtcGxlLmNvbQ==", + "envvar:PORT": "NTQzMg==", + "envvar:USER": "YWRtaW4=", + "envvar:PASS": "c3VwZXJzZWNyZXQ=" + } +} +``` -### Security +The agent resolves these environment variables at runtime when opening a session. -- Encrypted communication -- Credential management -- Audit logging -- Security policy enforcement +## Access Modes -### Monitoring and Compliance - -- Activity tracking -- Usage analytics -- Compliance reporting -- Integration with SIEM systems - -## Resource Components - -Resources and Resource Roles in Hoop.dev consist of several components: - - - -
    -
  • - Name and type -
    • - - -
  • - Resource specifications -
    • - - -
  • - Security settings -
    • - - -
  • - Access control rules -
    • - -
- - -
    -
  • - Connects to internal resources -
    • - - -
  • - Manages communication -
    • - - -
  • - Handles authentication -
    • - - -
  • - Enforces security policies -
    • - -
- - -
    -
  • - Integration with external tools -
    • - - -
  • - Custom functionality -
    • - - -
  • - Automation capabilities -
    • - - -
  • - Compliance features -
    • - -
- - - -## Best Practices - - - - - Use strong authentication - - Implement least privilege access - - Enable access request approval for sensitive resources - - Regularly audit access patterns - - - - Use clear naming conventions - - Group related resource roles - - Document resource role purposes - - Maintain access control lists - - - - Enable logging and auditing - - Monitor usage patterns - - Set up alerts for suspicious activity - - Regular security reviews - - - - Keep software and dependencies up to date - - Apply security patches promptly - - Review and update configurations regularly - - Stay informed about new features and improvements - - - -## Managing Resources - -Resources and Resource Roles can be managed through: - -1. **Web Interface** - - User-friendly management console - - Real-time monitoring - - Configuration tools - - Access control management -2. **API** - - Programmatic access - - Automation capabilities - - Integration support - - Custom implementations -3. **CLI** - - Command-line management - - Scripting support - - Automation tools - - Quick access - -## Next Steps - -To get started with your Resources and Resource Roles: - -1. [Set up your first resource](/clients/webapp/creating-resource-roles) -2. [Learn about access management](/clients/webapp/managing-access) -3. [Explore integration options](/integrations) -4. [Understand the architecture](/setup/architecture) +Each connection exposes up to three interaction modes, each independently enabled or disabled: + +| Mode | Description | +|------|-------------| +| `exec` | Run a command and receive output (non-interactive) | +| `connect` | Open an interactive session (e.g., a database shell) | +| `runbooks` | Execute pre-defined runbook scripts against the connection | + +## Features Per Connection + +Hoop features are attached to individual connections via the plugin system. When a connection is created, a default set of plugins is automatically enabled. Additional features can be configured on a per-connection basis: + +| Feature | Plugin | What it does | +|---------|--------|--------------| +| Session Recording | `audit` | Always active; records all session activity | +| Live Data Masking | `dlp` | Redacts sensitive patterns (emails, credit cards, etc.) in output | +| Access Requests | `review` | Holds execution pending approval from a designated reviewer group | +| Guardrails | — | Enforces input/output rules attached to the connection | +| Access Control | `access_control` | Restricts which user groups can see and use the connection | +| Runbooks | `runbooks` | Enables runbook execution on the connection | +| Webhooks / SIEM | `webhooks` | Forwards session lifecycle events to external endpoints | +| Slack Notifications | `slack` | Sends Slack messages for access request events | + +See [Plugins](/concepts/plugins) for a full reference. + +## Creating Connections + + + + Navigate to **Resource Roles** in the sidebar, then click **New Resource Role**. Select the type and fill in the required fields. + + + ```bash + curl -X POST https:///api/connections \ + -H "Api-Key: " \ + -H "Content-Type: application/json" \ + -d '{ + "name": "prod-postgres", + "type": "database", + "subtype": "postgres", + "agent_id": "", + "secret": { + "envvar:HOST": "", + "envvar:PORT": "", + "envvar:USER": "", + "envvar:PASS": "", + "envvar:DB": "" + } + }' + ``` + + diff --git a/concepts/sessions.mdx b/concepts/sessions.mdx new file mode 100644 index 0000000..dc8655d --- /dev/null +++ b/concepts/sessions.mdx @@ -0,0 +1,58 @@ +--- +title: "Sessions" +description: "A recorded interaction between a user and a connection" +--- + +A session is created every time a user interacts with a connection — running a query, executing a command, or opening an interactive shell. Sessions are the unit of audit in Hoop. + +## Lifecycle + +Sessions move through three states: + +| Status | Meaning | +|--------|---------| +| `open` | The session has started and the user is connected | +| `ready` | All required approvals have been granted; execution is about to begin | +| `done` | The session has ended (disconnected or timed out) | + +When a connection has the **Access Requests** feature enabled, sessions that trigger a review pause in `open` state until approved. Once all required approvers have approved, the session transitions to `ready` and execution proceeds. If the request is rejected or times out, the session moves to `done` without executing. + +## What Is Recorded + +Each session captures: + +- **User identity** — the user's ID, name, and email at the time of the session +- **Connection metadata** — the connection name, type, and subtype +- **Input** — the command or query submitted (stored as a blob) +- **Output stream** — the full response from the resource (stored as a blob) +- **Timestamps** — when the session started (`created_at`) and ended (`ended_at`) +- **Exit code** — the exit status of the process or command +- **Review** — if an access request was triggered, its status and reviewer decisions are linked to the session + +## Visibility + +Who can see which sessions depends on the user's role: + +| Role | Visibility | +|------|-----------| +| Admin | All sessions in the organization | +| Auditor | All sessions in the organization (read-only) | +| Regular user | Their own sessions, plus any sessions where they are a designated reviewer | + +## Viewing Sessions + +Sessions are visible in the **Sessions** tab of the Web App. You can filter by: + +- User +- Connection name +- Connection type +- Date range +- Access request review status + +Each session entry links to the full recording, including input and output replay. + +## Related + +- [Session Recording](/learn/features/session-recording) +- [Access Requests](/learn/features/access-requests/action) +- [Webhooks & SIEM](/setup/apis/webhooks-siem) diff --git a/docs.json b/docs.json index 90dbaed..698607a 100644 --- a/docs.json +++ b/docs.json @@ -166,6 +166,7 @@ "group": "Identity Providers", "pages": [ "setup/configuration/idp/get-started", + "setup/configuration/idp/local-auth", "setup/configuration/idp/auth0", "setup/configuration/idp/okta", "setup/configuration/idp/google", @@ -191,7 +192,9 @@ "group": "Concepts", "pages": [ "concepts/agents", - "concepts/resource-roles" + "concepts/resource-roles", + "concepts/sessions", + "concepts/plugins" ] }, { diff --git a/setup/configuration/idp/get-started.mdx b/setup/configuration/idp/get-started.mdx index 530b38c..e0edfdf 100644 --- a/setup/configuration/idp/get-started.mdx +++ b/setup/configuration/idp/get-started.mdx @@ -6,6 +6,7 @@ description: "Integrate with your own Identity Provider" We support a variety of Identity Providers to authenticate users in hoop.dev. In this guide you will find the IDPs we had success integrating with but as due to how we integrate with them using OIDC standards, you can try to integrate with any OIDC compliant IDP. + diff --git a/setup/configuration/idp/local-auth.mdx b/setup/configuration/idp/local-auth.mdx new file mode 100644 index 0000000..6b4e03f --- /dev/null +++ b/setup/configuration/idp/local-auth.mdx @@ -0,0 +1,55 @@ +--- +title: "Local Authentication" +description: "Built-in username and password authentication — no external identity provider required" +--- + +Local authentication is the default mode for new self-hosted Hoop installations. It uses a built-in username and password system and requires no external identity provider. + +## When to Use Local Auth + +- **New installs** — local auth is active by default when no IdP is configured +- **Development and test environments** — useful for evaluating Hoop without IdP setup overhead +- **Small teams** — when an external IdP is not available or not needed + +## First User Registration + +The first user to register via the web app's signup screen is automatically granted the **admin** role and has full access to the platform. + +After the first user is registered, the public registration endpoint is closed. Subsequent users can only join by invitation from an existing admin. + + + If you attempt to register a second account via the signup screen without an invitation, you will receive a "unable to register new users, please contact your administrator" error. + + +## Inviting Additional Users + +Admins can invite additional users through the user management screen in the Web App. Go to **Settings > Users** and send an invitation to the new user's email address. + +## Configuration + +Local auth is enabled by default when no external IdP is configured. You can also set it explicitly via an environment variable: + +```env +AUTH_METHOD=local +``` + +No other configuration is required. + +## Transitioning to OIDC or SAML + +To migrate from local auth to an external identity provider: + +1. Go to **Integrations > Authentication** in the Web App +2. Configure your OIDC or SAML provider +3. Save the configuration — the gateway reloads automatically with the new auth method + + + After saving a new auth configuration via the Web App, the `AUTH_METHOD` environment variable is no longer consulted — the database configuration takes precedence. + + +Existing users are matched by email when they sign in with the new provider. If the `sub` claim from the new provider doesn't match the stored subject, the user will be treated as a new account. Make sure the email addresses in your IdP match the ones already registered in Hoop. + +## Related + +- [Identity Provider Overview](/setup/configuration/idp/get-started) +- [Env Vars Reference](/setup/configuration/env-vars)