From 867984408b32192325a7de5b49841220aa4bf4cf Mon Sep 17 00:00:00 2001 From: Maxime Date: Tue, 26 May 2026 09:58:49 -0700 Subject: [PATCH 1/3] docs: add MSSP guide for deploying Viberails via EDR Payloads Explains how MSSPs can use existing LimaCharlie endpoint coverage (Payloads + D&R rules + Payload Manager / Git-Sync) to roll Viberails out across developer workstations at scale, including per-OS rule templates and the user-context caveat. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../tutorials/viberails-mssp-deployment.md | 258 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 259 insertions(+) create mode 100644 docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md diff --git a/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md new file mode 100644 index 000000000..6bc4f09c0 --- /dev/null +++ b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md @@ -0,0 +1,258 @@ +# Deploying Viberails at Scale via Payloads (MSSP Guide) + +[Viberails](https://viberails.io) is a control plane for AI coding assistants (Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, Codex, OpenCode, OpenClaw). It installs lightweight hooks into each tool so every prompt and tool call is audited and authorized through LimaCharlie. + +For MSSPs, MSPs, and MDR providers who already manage developer endpoints in LimaCharlie, the existing endpoint agent and its [Payloads](../endpoint-agent/payloads.md) feature can be used to deliver and configure Viberails across every customer's developer workstations without touching their endpoints by hand. + +This tutorial walks through that workflow end to end. + +## Why this works well for MSSPs + +- **Reuses your existing fleet.** Anywhere the LimaCharlie agent is already deployed, you can ship and execute a payload — no new MDM, no new VPN, no installer to email developers. +- **Fits IaC.** Payloads, installation rules, and D&R rules can all be templated and pushed to many customer organizations through the [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) extension or [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md). +- **Targeted, not fleet-wide.** Sensor tags let you scope the rollout to developer machines only, and the [sensor selector](../../1-getting-started/use-cases/investigation-guide.md) syntax keeps that targeting consistent across customers. +- **Auditable.** Every payload `run` produces a `RECEIPT` event in the sensor timeline, so you can prove that Viberails was installed on a given host at a given time. + +## How it works + +```mermaid +flowchart LR + subgraph MSSP[MSSP Org] + BIN[Viberails binaries
linux/macos/windows] + TPL[D&R rule template] + end + subgraph PM[Payload Manager] + SYNC[Sync every 24h] + end + subgraph CUST[Customer Orgs] + P1[Payloads] + R1[D&R Rules] + S1[Tagged sensors
developer workstations] + end + BIN --> PM + TPL --> PM + PM --> P1 + PM --> R1 + P1 --> S1 + R1 --> S1 + S1 -.RECEIPT.-> Audit[LimaCharlie
audit timeline] +``` + +1. The MSSP uploads the Viberails binaries (one per OS/architecture) as Payloads in each customer organization, normally via the Payload Manager so they stay in sync. +2. Each customer organization holds a D&R rule that fires on `CONNECTED` for sensors tagged as developer workstations (`viberails-deploy`). +3. The rule `put`s the right binary onto disk, then `run`s it with `join-team` and `install --providers all`, scoped to the active console user so hooks land in that user's home directory. +4. Once installed, Viberails reports every AI tool prompt and tool call back to that same LimaCharlie organization (or any Viberails team the MSSP designates). + +## Prerequisites + +- A Viberails team already created. See [Quick Start](https://github.com/refractionPOINT/viberails#quick-start). Note the **team URL** produced by `viberails init-team` — you will reuse it for every customer endpoint that should report to the same team. MSSPs typically create one Viberails team per customer (so audit data stays in the customer's tenant) or one shared team (so the MSSP SOC sees everything). +- The LimaCharlie endpoint agent installed on the developer workstations you want to cover. +- API permissions to manage payloads and D&R rules in each customer org: + - `payload.ctrl`, `payload.use` + - `dr.list`, `dr.set`, `dr.del` +- The [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) extension installed in each target org if you want centralized syncing of payloads. + +## Step 1 — Tag developer workstations + +Pick a tag that identifies machines where AI coding assistants are used. We will use `viberails-deploy` throughout this guide. + +You can tag manually from the Sensors view, with the CLI, or automatically based on installed software. A common pattern is to add the tag at install time via the [installation key](../installation-keys.md), so any new developer workstation enrolling under that key inherits the tag. + +```bash +# Example: tag an existing sensor +limacharlie sensors tag --sid --tag viberails-deploy --oid +``` + +See [Sensor Tags](../sensor-tags.md) for the full mechanics. + +## Step 2 — Upload the Viberails binaries as payloads + +Viberails publishes signed binaries for every supported OS/architecture at `get.viberails.io`. Download them once on a trusted host and verify checksums against [release.json](https://get.viberails.io/release.json), then upload each one as a [payload](../endpoint-agent/payloads.md). + +```bash +# Download +curl -fsSL -o viberails-linux-x64 https://get.viberails.io/viberails-linux-x64 +curl -fsSL -o viberails-linux-arm64 https://get.viberails.io/viberails-linux-arm64 +curl -fsSL -o viberails-macos-x64 https://get.viberails.io/viberails-macos-x64 +curl -fsSL -o viberails-macos-arm64 https://get.viberails.io/viberails-macos-arm64 +curl -fsSL -o viberails-windows-x64.exe https://get.viberails.io/viberails-windows-x64.exe + +# Upload to a single org via the CLI +for f in viberails-linux-x64 viberails-linux-arm64 \ + viberails-macos-x64 viberails-macos-arm64 \ + viberails-windows-x64.exe; do + limacharlie payload create --name "$f" --file "./$f" --oid +done +``` + +!!! tip "Naming" + The payload **name** is also the on-disk file name when it lands on the endpoint, and it determines the file extension that the OS uses to decide how to execute it. Keep the `.exe` suffix for Windows so it runs as a native executable. + +### Distributing payloads across many customer orgs + +For more than a handful of organizations, do not upload payloads one by one. Instead, drive the upload through the [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md): + +- Store the binaries in an object store (GCS, S3, an internal artifact registry) keyed by version. +- Configure Payload Manager in each customer org to pull the same set of named payloads from that source. +- Payload Manager re-syncs payloads every 24 hours, so refreshing a Viberails release across the fleet is a single upload at the source. + +When you ship a new Viberails release, replace the artifacts at the source URL and the change propagates everywhere. + +## Step 3 — Create the deployment D&R rule + +The rule below fires when a tagged sensor connects, drops the right binary onto disk, runs Viberails as the **active console user** (so hooks install in that user's home directory rather than `root`/`SYSTEM`), then removes the tag so the rule only fires once per workstation. + +Replace `` with the URL produced by `viberails init-team`. If you maintain one Viberails team per customer, parameterize this per-org when you sync the rule. + +### Windows + +```yaml +detect: + event: CONNECTED + op: and + rules: + - op: is platform + name: windows + - op: is tagged + tag: viberails-deploy +respond: + - action: task + command: put --payload-name viberails-windows-x64.exe --payload-path "C:\Windows\Temp\viberails.exe" + - action: wait + duration: 10s + # Run as the interactively logged-on user. PsExec/RunAs-equivalent behavior + # is needed because hooks must land in the developer's profile, not SYSTEM's. + # The scheduled task approach below uses the Interactive group token of + # whoever is currently signed in. + - action: task + command: > + run --shell-command + "schtasks /Create /F /SC ONCE /ST 00:00 /TN VRInstall + /TR \"cmd /c C:\\Windows\\Temp\\viberails.exe join-team + && C:\\Windows\\Temp\\viberails.exe install --providers all\" + /RU INTERACTIVE && schtasks /Run /TN VRInstall" + - action: wait + duration: 60s + - action: task + command: run --shell-command "schtasks /Delete /F /TN VRInstall" + - action: task + command: file_del "C:\Windows\Temp\viberails.exe" + - action: remove tag + tag: viberails-deploy + - action: add tag + tag: viberails-installed +``` + +### macOS + +```yaml +detect: + event: CONNECTED + op: and + rules: + - op: is platform + name: macos + - op: is tagged + tag: viberails-deploy +respond: + - action: task + command: put --payload-name viberails-macos-arm64 --payload-path "/var/tmp/viberails" + - action: wait + duration: 10s + - action: task + command: run --shell-command "chmod +x /var/tmp/viberails" + - action: task + command: > + run --shell-command + "USER=$(stat -f%Su /dev/console); + UID=$(id -u $USER); + launchctl asuser $UID sudo -u $USER -H /var/tmp/viberails join-team ; + launchctl asuser $UID sudo -u $USER -H /var/tmp/viberails install --providers all" + - action: wait + duration: 30s + - action: task + command: file_del "/var/tmp/viberails" + - action: remove tag + tag: viberails-deploy + - action: add tag + tag: viberails-installed +``` + +For Intel hardware, swap `viberails-macos-arm64` for `viberails-macos-x64`. If you have a mixed fleet, split the rule by architecture using `op: is arch`. + +### Linux + +```yaml +detect: + event: CONNECTED + op: and + rules: + - op: is platform + name: linux + - op: is tagged + tag: viberails-deploy +respond: + - action: task + command: put --payload-name viberails-linux-x64 --payload-path "/tmp/viberails" + - action: wait + duration: 10s + - action: task + command: run --shell-command "chmod +x /tmp/viberails" + - action: task + command: > + run --shell-command + "USER=$(who | awk 'NR==1{print $1}'); + sudo -u $USER -H /tmp/viberails join-team ; + sudo -u $USER -H /tmp/viberails install --providers all" + - action: wait + duration: 30s + - action: task + command: file_del "/tmp/viberails" + - action: remove tag + tag: viberails-deploy + - action: add tag + tag: viberails-installed +``` + +!!! warning "User-context matters" + Viberails stores its configuration under the **developer's** home directory (`~/.config/viberails/`) and installs hooks into per-tool config files there (`~/.claude/`, `~/.cursor/`, etc.). The endpoint agent runs payloads as `root`/`SYSTEM`, so the rules above explicitly drop privileges to the interactively signed-in user. Running Viberails as `root`/`SYSTEM` would install hooks for that account and leave the developer untouched. + + If no user is signed in when the rule fires, the install will fail. The simplest workaround is to fire on a different trigger that implies a user is present, or to leave the `viberails-deploy` tag in place until the rule sees a logged-in user and successfully completes. + +## Step 4 — Distribute the rule to every customer org + +Manage the rule the same way you manage every other MSSP-wide D&R rule. The two common patterns: + +- **Git-Sync.** Commit the rule (and the payload manifest) to your shared infrastructure repo and let [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md) push it to each customer org. Parameterize `` per-org through the templating mechanism your repo uses. +- **Organization Groups + IaC CLI.** Define the rule once and apply it to every organization in your "developer-coverage" Organization Group via `limacharlie configs push`. + +See [Designing Access for MSSPs](../../7-administration/access/designing-access.md) for the recommended Organization Group layout. + +## Step 5 — Verify + +For each newly tagged endpoint, confirm the install succeeded: + +1. **Receipt in the sensor timeline.** Look for `RECEIPT` events corresponding to each `run` task. The exit code should be 0 and STDOUT should contain `Joined team successfully!` followed by `Hooks installed`. +2. **Tag rotation.** The sensor should now carry `viberails-installed` and no longer carry `viberails-deploy`. +3. **Viberails events flowing.** In the Viberails team's LimaCharlie organization, watch for the first audit events from that machine the next time a developer uses one of the supported AI coding tools. + +If verification fails, enable Viberails debug logging on the affected machine and inspect `~/.local/share/viberails/debug/` (Linux/macOS) or `%LOCALAPPDATA%\viberails\debug\` (Windows). See [Viberails Troubleshooting](https://github.com/refractionPOINT/viberails#troubleshooting). + +## Updating Viberails on the fleet + +Viberails auto-upgrades itself by default whenever any hooked tool runs, so a one-shot install is normally enough. If you have disabled `auto_upgrade` per the [Viberails configuration](https://github.com/refractionPOINT/viberails#configuration), or you want to force-roll a version across all customer endpoints, add a second tag (e.g. `viberails-upgrade`) and a companion D&R rule that runs `viberails upgrade` instead of `install`. + +## Removing Viberails + +Use the same pattern in reverse: tag the targets `viberails-uninstall`, drop the binary as a payload, and run `viberails uninstall-all --yes` in the user's context. The `--yes` flag suppresses the interactive confirmation, which is essential under a non-interactive payload `run`. + +--- + +## See Also + +- [Payloads](../endpoint-agent/payloads.md) +- [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) +- [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md) +- [Sensor Tags](../sensor-tags.md) +- [Security Service Providers (MSSP, MSP, MDR)](../../1-getting-started/use-cases/mssp-msp-mdr.md) +- [Designing Access for MSSPs](../../7-administration/access/designing-access.md) diff --git a/mkdocs.yml b/mkdocs.yml index eeb58031a..04e094067 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -324,6 +324,7 @@ nav: - macOS Unified Logs: 2-sensors-deployment/tutorials/macos-unified-logs.md - Test Sensor Version: 2-sensors-deployment/tutorials/test-sensor-version.md - Update Sensors: 2-sensors-deployment/tutorials/update-sensors.md + - Viberails Deployment (MSSP): 2-sensors-deployment/tutorials/viberails-mssp-deployment.md - Detection & Response: - Overview: 3-detection-response/index.md From b4987054ca3fdd9f99b8cbb65641d71df40a3ab4 Mon Sep 17 00:00:00 2001 From: Maxime Date: Tue, 26 May 2026 10:50:41 -0700 Subject: [PATCH 2/3] docs(viberails-mssp): fix CLI/D&R inaccuracies from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - limacharlie payload create -> payload upload (the actual subcommand) - limacharlie sensors tag -> tag add/mass-add (top-level `tag` group) - --oid is a global flag, hoist it before the subcommand - Clarify per-OS config and debug dirs (macOS is ~/Library/Application Support/viberails, not ~/.config/viberails — README is wrong about macOS) - Remove the bogus `op: is arch` suggestion (no such operator); use per-arch deploy tags or selectors at tag-time instead - Rewrite the Windows rule to delegate to a viberails-install.ps1 helper payload — drops the brittle nested-quote schtasks one-liner and detects the interactive user via Win32_Process owner - Fix USER/UID collision with bash readonly vars in the macOS and Linux rules (use TARGET_USER/TARGET_UID instead) - Correct the verification step about event types: `put` returns RECEIPT, `run --shell-command` returns EXEC_OOB (macOS/Linux); explain that the Viberails team URL embeds the LimaCharlie OID where audit events land Co-Authored-By: Claude Opus 4.7 (1M context) --- .../tutorials/viberails-mssp-deployment.md | 90 +++++++++++++------ 1 file changed, 63 insertions(+), 27 deletions(-) diff --git a/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md index 6bc4f09c0..5c8dac73f 100644 --- a/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md +++ b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md @@ -59,8 +59,11 @@ Pick a tag that identifies machines where AI coding assistants are used. We will You can tag manually from the Sensors view, with the CLI, or automatically based on installed software. A common pattern is to add the tag at install time via the [installation key](../installation-keys.md), so any new developer workstation enrolling under that key inherits the tag. ```bash -# Example: tag an existing sensor -limacharlie sensors tag --sid --tag viberails-deploy --oid +# Tag a single sensor +limacharlie --oid tag add --sid --tag viberails-deploy + +# Or tag every sensor matching a selector — see `limacharlie tag mass-add --help` +limacharlie --oid tag mass-add --selector 'plat == windows and "developer" in tags' --tag viberails-deploy ``` See [Sensor Tags](../sensor-tags.md) for the full mechanics. @@ -81,8 +84,11 @@ curl -fsSL -o viberails-windows-x64.exe https://get.viberails.io/viberails-windo for f in viberails-linux-x64 viberails-linux-arm64 \ viberails-macos-x64 viberails-macos-arm64 \ viberails-windows-x64.exe; do - limacharlie payload create --name "$f" --file "./$f" --oid + limacharlie --oid payload upload --name "$f" --file "./$f" done + +# Also upload the Windows PowerShell helper (defined in Step 3). +limacharlie --oid payload upload --name viberails-install.ps1 --file ./viberails-install.ps1 ``` !!! tip "Naming" @@ -116,33 +122,59 @@ detect: - op: is tagged tag: viberails-deploy respond: + # 1. Drop the viberails binary. - action: task command: put --payload-name viberails-windows-x64.exe --payload-path "C:\Windows\Temp\viberails.exe" - action: wait duration: 10s - # Run as the interactively logged-on user. PsExec/RunAs-equivalent behavior - # is needed because hooks must land in the developer's profile, not SYSTEM's. - # The scheduled task approach below uses the Interactive group token of - # whoever is currently signed in. + # 2. Drop a small PowerShell helper that does the user-context dance. + # Upload this once as a payload named `viberails-install.ps1` (see below). - action: task - command: > - run --shell-command - "schtasks /Create /F /SC ONCE /ST 00:00 /TN VRInstall - /TR \"cmd /c C:\\Windows\\Temp\\viberails.exe join-team - && C:\\Windows\\Temp\\viberails.exe install --providers all\" - /RU INTERACTIVE && schtasks /Run /TN VRInstall" + command: put --payload-name viberails-install.ps1 --payload-path "C:\Windows\Temp\viberails-install.ps1" - action: wait - duration: 60s + duration: 5s + # 3. Run the helper as SYSTEM; the helper itself launches viberails in the + # interactive user's session. - action: task - command: run --shell-command "schtasks /Delete /F /TN VRInstall" + command: run --shell-command "powershell -ExecutionPolicy Bypass -File C:\Windows\Temp\viberails-install.ps1 -TeamUrl " + - action: wait + duration: 60s - action: task command: file_del "C:\Windows\Temp\viberails.exe" + - action: task + command: file_del "C:\Windows\Temp\viberails-install.ps1" - action: remove tag tag: viberails-deploy - action: add tag tag: viberails-installed ``` +The PowerShell helper (`viberails-install.ps1`) — upload once as a payload alongside the binaries: + +```powershell +param([Parameter(Mandatory = $true)][string]$TeamUrl) + +# Find the active console user by querying the explorer.exe owner. +$explorer = Get-CimInstance Win32_Process -Filter "Name='explorer.exe'" | + Select-Object -First 1 +if (-not $explorer) { + Write-Error "No interactive user signed in; aborting viberails install." + exit 1 +} +$owner = Invoke-CimMethod -InputObject $explorer -MethodName GetOwner +$runAs = "$($owner.Domain)\$($owner.User)" + +# Create a one-shot task that runs viberails as the interactive user and +# self-deletes after the run. /Z deletes the task after completion. +$cmd = "C:\Windows\Temp\viberails.exe join-team `"$TeamUrl`" && " + + "C:\Windows\Temp\viberails.exe install --providers all" +schtasks /Create /F /TN VRInstall /SC ONCE /ST 00:00 /Z ` + /RU "$runAs" /IT /TR "cmd /c $cmd" +schtasks /Run /TN VRInstall +``` + +`/IT` makes the task run only when the named user is signed in, and `/Z` deletes the task definition once it completes. Sign and review this script before deploying it across customer orgs. + ### macOS ```yaml @@ -161,13 +193,14 @@ respond: duration: 10s - action: task command: run --shell-command "chmod +x /var/tmp/viberails" + # USER/UID are read-only in bash, so use TARGET_USER/TARGET_UID. - action: task command: > run --shell-command - "USER=$(stat -f%Su /dev/console); - UID=$(id -u $USER); - launchctl asuser $UID sudo -u $USER -H /var/tmp/viberails join-team ; - launchctl asuser $UID sudo -u $USER -H /var/tmp/viberails install --providers all" + "TARGET_USER=$(stat -f%Su /dev/console); + TARGET_UID=$(id -u $TARGET_USER); + launchctl asuser $TARGET_UID sudo -u $TARGET_USER -H /var/tmp/viberails join-team ; + launchctl asuser $TARGET_UID sudo -u $TARGET_USER -H /var/tmp/viberails install --providers all" - action: wait duration: 30s - action: task @@ -178,7 +211,7 @@ respond: tag: viberails-installed ``` -For Intel hardware, swap `viberails-macos-arm64` for `viberails-macos-x64`. If you have a mixed fleet, split the rule by architecture using `op: is arch`. +For Intel hardware, swap `viberails-macos-arm64` for `viberails-macos-x64`. If you have a mixed fleet, use two tags (`viberails-deploy-arm`, `viberails-deploy-x64`) applied per host so each rule picks the right payload — there is no `is arch` operator in D&R rules, so architecture must be encoded in the tag (or in the selector at tag-time via `limacharlie tag mass-add --selector 'arch == arm64 and ...'`). ### Linux @@ -198,12 +231,15 @@ respond: duration: 10s - action: task command: run --shell-command "chmod +x /tmp/viberails" + # USER is read-only in bash, so use TARGET_USER. `who` returns one row per + # active login session; this picks the first, which is fine for typical + # single-developer workstations but should be revisited for multi-user hosts. - action: task command: > run --shell-command - "USER=$(who | awk 'NR==1{print $1}'); - sudo -u $USER -H /tmp/viberails join-team ; - sudo -u $USER -H /tmp/viberails install --providers all" + "TARGET_USER=$(who | awk 'NR==1{print $1}'); + sudo -u $TARGET_USER -H /tmp/viberails join-team ; + sudo -u $TARGET_USER -H /tmp/viberails install --providers all" - action: wait duration: 30s - action: task @@ -215,7 +251,7 @@ respond: ``` !!! warning "User-context matters" - Viberails stores its configuration under the **developer's** home directory (`~/.config/viberails/`) and installs hooks into per-tool config files there (`~/.claude/`, `~/.cursor/`, etc.). The endpoint agent runs payloads as `root`/`SYSTEM`, so the rules above explicitly drop privileges to the interactively signed-in user. Running Viberails as `root`/`SYSTEM` would install hooks for that account and leave the developer untouched. + Viberails stores its configuration in the **developer's** home directory — `~/.config/viberails/` on Linux, `~/Library/Application Support/viberails/` on macOS, `%APPDATA%\viberails\` on Windows — and installs hooks into per-tool config files there (`~/.claude/`, `~/.cursor/`, etc.). The binary lands at `~/.local/bin/viberails` on every platform. The endpoint agent runs payloads as `root`/`SYSTEM`, so the rules above explicitly drop privileges to the interactively signed-in user. Running Viberails as `root`/`SYSTEM` would install hooks for that account and leave the developer untouched. If no user is signed in when the rule fires, the install will fail. The simplest workaround is to fire on a different trigger that implies a user is present, or to leave the `viberails-deploy` tag in place until the rule sees a logged-in user and successfully completes. @@ -232,11 +268,11 @@ See [Designing Access for MSSPs](../../7-administration/access/designing-access. For each newly tagged endpoint, confirm the install succeeded: -1. **Receipt in the sensor timeline.** Look for `RECEIPT` events corresponding to each `run` task. The exit code should be 0 and STDOUT should contain `Joined team successfully!` followed by `Hooks installed`. +1. **Task results in the sensor timeline.** Each `put` task produces a [`RECEIPT`](../../8-reference/edr-events.md#receipt) event; each `run --shell-command` produces an `EXEC_OOB` event (macOS/Linux) and an audit entry on Windows. Confirm there are no errors. Viberails itself prints `Joined team successfully!` and `Hooks installed successfully!` to STDOUT when invoked correctly. 2. **Tag rotation.** The sensor should now carry `viberails-installed` and no longer carry `viberails-deploy`. -3. **Viberails events flowing.** In the Viberails team's LimaCharlie organization, watch for the first audit events from that machine the next time a developer uses one of the supported AI coding tools. +3. **Viberails events flowing.** The Viberails team URL is itself a LimaCharlie hook URL (`https://.hook.limacharlie.io///`), so audit events land in the LimaCharlie organization identified by the `` segment of that URL. Watch its timeline for the first events the next time a developer uses one of the supported AI coding tools. -If verification fails, enable Viberails debug logging on the affected machine and inspect `~/.local/share/viberails/debug/` (Linux/macOS) or `%LOCALAPPDATA%\viberails\debug\` (Windows). See [Viberails Troubleshooting](https://github.com/refractionPOINT/viberails#troubleshooting). +If verification fails, enable Viberails debug logging on the affected machine and inspect the debug directory: `~/.local/share/viberails/debug/` on Linux, `~/Library/Application Support/viberails/debug/` on macOS, `%LOCALAPPDATA%\viberails\debug\` on Windows. See [Viberails Troubleshooting](https://github.com/refractionPOINT/viberails#troubleshooting). ## Updating Viberails on the fleet From 3ecdb8018b8ef33e83d0024448b44e5679c82d07 Mon Sep 17 00:00:00 2001 From: Maxime Date: Tue, 26 May 2026 11:06:08 -0700 Subject: [PATCH 3/3] docs(viberails-mssp): assume customer LC orgs already exist Rewrite the guide for the common MSSP case: the customer already runs LimaCharlie and the goal is to add Viberails coverage onto the existing org, not to create a separate Viberails team. - Drop "create a Viberails team" prerequisite; assume customer LC orgs with the endpoint agent already deployed - Add a new Step 1 that provisions a per-customer `viberails` webhook adapter via `viberails init-team --existing-org `, with a scripted alternative using `installation-key create` and `cloud-adapter set` for fully non-interactive setups - Renumber the rest of the steps and rename the placeholder from to so it's clear the value is per-customer - Replace the architecture diagram to show audit events landing in the same customer LC org, no separate MSSP/team org - Replace the prerequisite permissions with the actual ones needed for the new flow: org.get, cloudsensor.get/set, ikey.list/set, payload.ctrl/use, dr.list/set/del, sensor.tag - Add a note that init-team also seeds Viberails primer detection rules in the customer's dr-general hive Co-Authored-By: Claude Opus 4.7 (1M context) --- .../tutorials/viberails-mssp-deployment.md | 122 +++++++++++------- 1 file changed, 76 insertions(+), 46 deletions(-) diff --git a/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md index 5c8dac73f..5625fb624 100644 --- a/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md +++ b/docs/2-sensors-deployment/tutorials/viberails-mssp-deployment.md @@ -2,57 +2,87 @@ [Viberails](https://viberails.io) is a control plane for AI coding assistants (Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, Codex, OpenCode, OpenClaw). It installs lightweight hooks into each tool so every prompt and tool call is audited and authorized through LimaCharlie. -For MSSPs, MSPs, and MDR providers who already manage developer endpoints in LimaCharlie, the existing endpoint agent and its [Payloads](../endpoint-agent/payloads.md) feature can be used to deliver and configure Viberails across every customer's developer workstations without touching their endpoints by hand. +This guide is for MSSPs, MSPs, and MDR providers who **already run LimaCharlie for their customers**: each customer has their own LC organization with the endpoint agent deployed. The goal here is to add Viberails coverage onto those existing organizations so each customer's AI coding assistant activity lands in their own LC org, alongside the rest of their telemetry. -This tutorial walks through that workflow end to end. +The whole rollout is done through the LimaCharlie tooling you are already using: the [Payloads](../endpoint-agent/payloads.md) feature delivers the Viberails binary, a [D&R rule](../../3-detection-response/index.md) installs it under the developer's user account, and the [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) extension and/or [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md) fan everything out across your customer fleet. ## Why this works well for MSSPs -- **Reuses your existing fleet.** Anywhere the LimaCharlie agent is already deployed, you can ship and execute a payload — no new MDM, no new VPN, no installer to email developers. +- **No new infrastructure.** Anywhere the LimaCharlie agent is already deployed, you can ship and execute a payload — no new MDM, no new VPN, no installer to email developers, no new SaaS console. +- **Customer data stays with the customer.** Viberails events flow into the customer's own LC org via a per-org webhook adapter. The MSSP retains the same access it already had — through Organization Groups and RBAC — and nothing about data ownership changes. - **Fits IaC.** Payloads, installation rules, and D&R rules can all be templated and pushed to many customer organizations through the [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) extension or [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md). - **Targeted, not fleet-wide.** Sensor tags let you scope the rollout to developer machines only, and the [sensor selector](../../1-getting-started/use-cases/investigation-guide.md) syntax keeps that targeting consistent across customers. -- **Auditable.** Every payload `run` produces a `RECEIPT` event in the sensor timeline, so you can prove that Viberails was installed on a given host at a given time. ## How it works ```mermaid flowchart LR - subgraph MSSP[MSSP Org] + subgraph MSSP[MSSP control plane] BIN[Viberails binaries
linux/macos/windows] - TPL[D&R rule template] + TPL[D&R rule template
+ ps1 helper] end - subgraph PM[Payload Manager] - SYNC[Sync every 24h] + subgraph CUST[Customer LC Org] + ADP[viberails webhook
adapter] + P[Payloads] + R[D&R rules] + S[Tagged sensors
developer workstations] + T[Audit timeline] end - subgraph CUST[Customer Orgs] - P1[Payloads] - R1[D&R Rules] - S1[Tagged sensors
developer workstations] - end - BIN --> PM - TPL --> PM - PM --> P1 - PM --> R1 - P1 --> S1 - R1 --> S1 - S1 -.RECEIPT.-> Audit[LimaCharlie
audit timeline] + BIN --> P + TPL --> R + R -.installs Viberails.-> S + S -.AI tool events.-> ADP + ADP --> T ``` -1. The MSSP uploads the Viberails binaries (one per OS/architecture) as Payloads in each customer organization, normally via the Payload Manager so they stay in sync. -2. Each customer organization holds a D&R rule that fires on `CONNECTED` for sensors tagged as developer workstations (`viberails-deploy`). -3. The rule `put`s the right binary onto disk, then `run`s it with `join-team` and `install --providers all`, scoped to the active console user so hooks land in that user's home directory. -4. Once installed, Viberails reports every AI tool prompt and tool call back to that same LimaCharlie organization (or any Viberails team the MSSP designates). +For each customer LC org: + +1. The MSSP provisions a `viberails` webhook adapter once via `viberails init-team --existing-org `. This creates the per-org team URL that Viberails on the endpoint will report to, and also seeds a set of Viberails-specific D&R rules in the customer's `dr-general` hive. +2. The MSSP uploads the Viberails binaries (one per OS/architecture) and a small PowerShell helper as Payloads in the customer org — normally via the Payload Manager so they stay in sync as Viberails releases new versions. +3. A D&R rule in the customer org fires on `CONNECTED` for sensors tagged `viberails-deploy`, `put`s the right binary, and runs `join-team` + `install --providers all` as the interactively signed-in user. +4. Viberails reports every AI tool prompt and tool call back to the same customer LC org through the webhook adapter. There is no separate "Viberails team" or shared MSSP team in the picture. ## Prerequisites -- A Viberails team already created. See [Quick Start](https://github.com/refractionPOINT/viberails#quick-start). Note the **team URL** produced by `viberails init-team` — you will reuse it for every customer endpoint that should report to the same team. MSSPs typically create one Viberails team per customer (so audit data stays in the customer's tenant) or one shared team (so the MSSP SOC sees everything). -- The LimaCharlie endpoint agent installed on the developer workstations you want to cover. -- API permissions to manage payloads and D&R rules in each customer org: - - `payload.ctrl`, `payload.use` - - `dr.list`, `dr.set`, `dr.del` +- One LimaCharlie organization **per customer**, with the endpoint agent already deployed on the developer workstations you want to cover. +- API permissions in each customer org to: + - read org metadata: `org.get` + - create the webhook adapter: `cloudsensor.get`, `cloudsensor.set` (the adapter lives in the `cloud_sensor` hive) + - create its installation key: `ikey.list`, `ikey.set` + - manage payloads: `payload.ctrl`, `payload.use` + - manage rules: `dr.list`, `dr.set`, `dr.del` + - manage tags: `sensor.tag` - The [Payload Manager](../../5-integrations/extensions/limacharlie/payload-manager.md) extension installed in each target org if you want centralized syncing of payloads. +- A LimaCharlie account that can OAuth into each customer org (interactively) for the one-shot `init-team --existing-org` step. The rest of the rollout is fully scriptable through the LimaCharlie CLI / API. + +## Step 1 — Provision Viberails reception in each customer org + +Viberails reports its events to a per-org **team URL** of the form `https://.hook.limacharlie.io//viberails/`. The `` segment is the customer's LimaCharlie OID — so a customer's Viberails events land in that customer's org and nowhere else. + +The simplest way to provision this is to install Viberails locally on an MSSP workstation and run `init-team` against each customer's existing org. `--existing-org` skips the "create new team" path: + +```bash +# Once per customer org. This will: +# - create a webhook adapter named `viberails` in the customer's `cloud_sensor` hive +# - seed a set of Viberails-specific D&R rules in the customer's `dr-general` hive +# - print the per-customer team URL — record this; you will need it in Step 4 +viberails init-team --existing-org +``` + +The command is interactive (OAuth) but only needs to run once per org. The webhook URL is stable; record it next to the OID in your customer inventory. + +If you prefer a fully scripted setup (no interactive OAuth), you can recreate the same artifacts using a non-interactive LimaCharlie credential against each customer org: + +1. `limacharlie --oid installation-key create --description "viberails webhook adapter" --get` to create the installation key. +2. `limacharlie --oid cloud-adapter set --key viberails --input-file viberails-adapter.json` to create the webhook adapter entry. The adapter JSON references the installation key from step 1, sets `secret` to a freshly generated UUID, and sets the type to `webhook` with `enabled: true`. +3. Fetch the org's hook domain (it varies per datacenter — query the `org urls` endpoint) and assemble the team URL as `https:////viberails/`. + +Recording the team URL in your customer inventory is still the only output you actually need for the rest of this guide. + +!!! note "Where Viberails D&R rules come from" + `init-team` seeds a set of detection rules covering SSH key access, hook-config tampering, binary-tamper, cloud-cred access, suspicious TLDs, and similar primer detections. These are independent of the deployment rule built in Step 4 — they detect things Viberails-instrumented tools do at runtime. If you maintain Viberails rules centrally in Git-Sync, you can disable or override these per-customer. -## Step 1 — Tag developer workstations +## Step 2 — Tag developer workstations Pick a tag that identifies machines where AI coding assistants are used. We will use `viberails-deploy` throughout this guide. @@ -60,15 +90,15 @@ You can tag manually from the Sensors view, with the CLI, or automatically based ```bash # Tag a single sensor -limacharlie --oid tag add --sid --tag viberails-deploy +limacharlie --oid tag add --sid --tag viberails-deploy # Or tag every sensor matching a selector — see `limacharlie tag mass-add --help` -limacharlie --oid tag mass-add --selector 'plat == windows and "developer" in tags' --tag viberails-deploy +limacharlie --oid tag mass-add --selector 'plat == windows and "developer" in tags' --tag viberails-deploy ``` See [Sensor Tags](../sensor-tags.md) for the full mechanics. -## Step 2 — Upload the Viberails binaries as payloads +## Step 3 — Upload the Viberails binaries as payloads Viberails publishes signed binaries for every supported OS/architecture at `get.viberails.io`. Download them once on a trusted host and verify checksums against [release.json](https://get.viberails.io/release.json), then upload each one as a [payload](../endpoint-agent/payloads.md). @@ -80,15 +110,15 @@ curl -fsSL -o viberails-macos-x64 https://get.viberails.io/viberails-macos curl -fsSL -o viberails-macos-arm64 https://get.viberails.io/viberails-macos-arm64 curl -fsSL -o viberails-windows-x64.exe https://get.viberails.io/viberails-windows-x64.exe -# Upload to a single org via the CLI +# Upload to one customer org via the CLI for f in viberails-linux-x64 viberails-linux-arm64 \ viberails-macos-x64 viberails-macos-arm64 \ viberails-windows-x64.exe; do - limacharlie --oid payload upload --name "$f" --file "./$f" + limacharlie --oid payload upload --name "$f" --file "./$f" done -# Also upload the Windows PowerShell helper (defined in Step 3). -limacharlie --oid payload upload --name viberails-install.ps1 --file ./viberails-install.ps1 +# Also upload the Windows PowerShell helper (defined in Step 4). +limacharlie --oid payload upload --name viberails-install.ps1 --file ./viberails-install.ps1 ``` !!! tip "Naming" @@ -104,11 +134,11 @@ For more than a handful of organizations, do not upload payloads one by one. Ins When you ship a new Viberails release, replace the artifacts at the source URL and the change propagates everywhere. -## Step 3 — Create the deployment D&R rule +## Step 4 — Create the deployment D&R rule The rule below fires when a tagged sensor connects, drops the right binary onto disk, runs Viberails as the **active console user** (so hooks install in that user's home directory rather than `root`/`SYSTEM`), then removes the tag so the rule only fires once per workstation. -Replace `` with the URL produced by `viberails init-team`. If you maintain one Viberails team per customer, parameterize this per-org when you sync the rule. +Replace `` with the URL recorded for **this** customer in Step 1. Each customer gets a different value — when you sync the rule across customers via Git-Sync or templates, parameterize on this URL per org. ### Windows @@ -136,7 +166,7 @@ respond: # 3. Run the helper as SYSTEM; the helper itself launches viberails in the # interactive user's session. - action: task - command: run --shell-command "powershell -ExecutionPolicy Bypass -File C:\Windows\Temp\viberails-install.ps1 -TeamUrl " + command: run --shell-command "powershell -ExecutionPolicy Bypass -File C:\Windows\Temp\viberails-install.ps1 -TeamUrl " - action: wait duration: 60s - action: task @@ -199,7 +229,7 @@ respond: run --shell-command "TARGET_USER=$(stat -f%Su /dev/console); TARGET_UID=$(id -u $TARGET_USER); - launchctl asuser $TARGET_UID sudo -u $TARGET_USER -H /var/tmp/viberails join-team ; + launchctl asuser $TARGET_UID sudo -u $TARGET_USER -H /var/tmp/viberails join-team ; launchctl asuser $TARGET_UID sudo -u $TARGET_USER -H /var/tmp/viberails install --providers all" - action: wait duration: 30s @@ -238,7 +268,7 @@ respond: command: > run --shell-command "TARGET_USER=$(who | awk 'NR==1{print $1}'); - sudo -u $TARGET_USER -H /tmp/viberails join-team ; + sudo -u $TARGET_USER -H /tmp/viberails join-team ; sudo -u $TARGET_USER -H /tmp/viberails install --providers all" - action: wait duration: 30s @@ -255,22 +285,22 @@ respond: If no user is signed in when the rule fires, the install will fail. The simplest workaround is to fire on a different trigger that implies a user is present, or to leave the `viberails-deploy` tag in place until the rule sees a logged-in user and successfully completes. -## Step 4 — Distribute the rule to every customer org +## Step 5 — Distribute the rule to every customer org Manage the rule the same way you manage every other MSSP-wide D&R rule. The two common patterns: -- **Git-Sync.** Commit the rule (and the payload manifest) to your shared infrastructure repo and let [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md) push it to each customer org. Parameterize `` per-org through the templating mechanism your repo uses. +- **Git-Sync.** Commit the rule (and the payload manifest) to your shared infrastructure repo and let [Git-Sync](../../5-integrations/extensions/limacharlie/git-sync.md) push it to each customer org. Parameterize `` per-org through the templating mechanism your repo uses. - **Organization Groups + IaC CLI.** Define the rule once and apply it to every organization in your "developer-coverage" Organization Group via `limacharlie configs push`. See [Designing Access for MSSPs](../../7-administration/access/designing-access.md) for the recommended Organization Group layout. -## Step 5 — Verify +## Step 6 — Verify For each newly tagged endpoint, confirm the install succeeded: 1. **Task results in the sensor timeline.** Each `put` task produces a [`RECEIPT`](../../8-reference/edr-events.md#receipt) event; each `run --shell-command` produces an `EXEC_OOB` event (macOS/Linux) and an audit entry on Windows. Confirm there are no errors. Viberails itself prints `Joined team successfully!` and `Hooks installed successfully!` to STDOUT when invoked correctly. 2. **Tag rotation.** The sensor should now carry `viberails-installed` and no longer carry `viberails-deploy`. -3. **Viberails events flowing.** The Viberails team URL is itself a LimaCharlie hook URL (`https://.hook.limacharlie.io///`), so audit events land in the LimaCharlie organization identified by the `` segment of that URL. Watch its timeline for the first events the next time a developer uses one of the supported AI coding tools. +3. **Viberails events flowing.** Watch the same customer org's timeline (or the dedicated Viberails view in the app) for the first AI tool events the next time a developer uses one of the hooked tools — they arrive via the `viberails` webhook adapter you created in Step 1. If verification fails, enable Viberails debug logging on the affected machine and inspect the debug directory: `~/.local/share/viberails/debug/` on Linux, `~/Library/Application Support/viberails/debug/` on macOS, `%LOCALAPPDATA%\viberails\debug\` on Windows. See [Viberails Troubleshooting](https://github.com/refractionPOINT/viberails#troubleshooting).