# Slack review pilot

> A source-distributed Slack adapter, a pilot, that turns recorded Keryn security evidence into scoped review cards and lets a reviewer request a bounded rerun on a runner you own. Read what it posts to Slack before you enable it.

Source: https://keryn.dev/docs/guides/slack/

## Goal

Let the people who own a fix review recorded security evidence in Slack: see the card, take ownership, acknowledge the evidence, and ask for a bounded rerun on your own runner, without giving Slack the evidence itself.

> **Note: In the next release**
> The Slack review adapter is in the Keryn source on the main branch after release 0.5.2 and is in no release yet. It is a pilot: it has not been registered, installed in a live Slack workspace or tested against one. Its tests use signed requests to an owned loopback listener and an injected Slack transport, and the offline demo sends no real Slack message. It is source only, needs a Node version with native TypeScript stripping (validated with Node 25.9.0), and has no registry entry, so it is not on the [download page](https://keryn.dev/download/). The app's manifest calls it **Keryn Review**.

## What it is

A small HTTP adapter you host, plus a worker you run next to the application under test. The adapter holds the original evidence (the test suites and execution receipts from Keryn's security tests), recomputes the review from that evidence every time, and answers Slack commands. A caller's summary or a manual acknowledgement can never establish a verified fix: only a fresh receipt from the worker can.

It adds no account, login or OAuth platform. Who may do what comes from an explicit allowlist that maps Slack team, user and channel IDs to an actor, an organization, a project, applications and the operations `read`, `assign`, `verify` and `share`. A production setup should resolve those grants through your own identity platform instead.

## What leaves your machine

| From | To | What | When |
|---|---|---|---|
| Slack | your adapter | a signed slash command or button press (`/keryn`), up to 128 KiB | when someone uses it |
| your adapter | Slack, fixed API destinations only | a review card, which omits raw evidence snippets and target URLs | only when both `enableSlackWrites` and the channel mapping's `allowChannelPosts` are on, the person has the `share` operation, and they press **Share in this channel** |
| your worker | your adapter | a signed completion receipt for one rerun | when a reviewer requested a verification and you ran the worker with `--execute` |
| your worker | your application under test | the requests of the reviewed suite | only when you run the worker; Slack cannot supply a URL, path, command or secret name |

Never done by the adapter:

- Original evidence, suites and receipts are kept in the adapter's private state file and are not sent to Slack. Because they can contain private synthetic or business data, protect the state directory and its backups.
- Direct slash command replies are ephemeral. Nothing is posted to a channel by default.
- The `response_url` in a Slack request is ignored, redirects are refused, and before posting the adapter checks `auth.test` against the configured workspace.
- Secrets are named environment variables. Secret values never appear in the config, a suite, a command or a review record. The Slack bot token is read only when writes are enabled.

Neither the adapter nor the worker contacts Keryn.

## Slack permissions

The generated manifest asks for two bot scopes only: `commands` and `chat:write`. It configures one slash command, `/keryn`, and sends commands and interactivity to the adapter's `/slack` path over your HTTPS origin. Socket mode, org-wide deployment and token rotation are off.

## Commands

| Command | Result |
|---|---|
| `/keryn review <id>` | the evidence card, ownership, acknowledgement, freshness and available actions |
| `/keryn explain <id>` | the recorded verification reasons and the evidence's limitations |
| `/keryn status <app>` | the reviews of an application you are authorised for |
| `/keryn verify <id>` | one authorised, digest-bound rerun request |

Ownership goes to the person who takes it, and only that owner can release it or acknowledge the review. An acknowledgement records that a human looked; it does not change the verification result. Each card binds the exact evidence digest, the record generation and an expiry, so a stale or replayed button cannot apply to a newer review.

## Try it offline

This runs entirely on your machine: a signed HTTP exchange with an owned loopback listener, the security runner against an in-process reference application, and an injected Slack transport.

```sh
node clients/slack-app/demo.mjs --out output/slack-review-demo
```

Use a new output directory each time. The demo first keeps failing evidence, then, after a fresh authorised worker receipt on the corrected behaviour, shows the review as `verified-for-recorded-trials`. That wording is deliberate: it covers the recorded trials, not every possible request.

## Prepare an installation

```sh
node clients/slack-app/setup.mjs --out output/slack-setup --origin https://review.example.com
```

Setup writes `manifest.json`, `config.json` and `worker.json` into a new directory. It registers nothing, installs nothing and sends no Slack message. Replace every template identifier, host the adapter behind an HTTPS reverse proxy that preserves the raw request body, and do not expose a development listener directly. The adapter binds `127.0.0.1`.

Import original evidence with `clients/slack-app/app.mjs import`, serve with `clients/slack-app/app.mjs serve`, and run `clients/slack-app/worker.mjs` on your own schedule with `--execute`. The worker claims at most one request, checks the suite's digest, bounds the request count, and passes only the environment secrets the suite names. The OpenAPI document `clients/slack-app/openapi.yaml` in the source describes the four HTTP routes.

## Google Drive knowledge access

The same adapter can review the outcome of a Knowledge Access range, which tests whether an assistant respects document permissions. A rerun there tests the original reviewed source snapshot: it does not look at Drive again, refresh document versions or recompute permissions. If permissions changed, do a fresh probe, compile and import. The Drive connector in this pilot is limited to one synthetic document checked through two reviewed identities, using metadata calls only; it does not list a Drive, download contents or change sharing.

## What you just proved

The reviewer sees counts, ownership and a verdict-bearing card in Slack while the evidence stays in a state file you control, and a green outcome exists only because a worker you run produced a fresh receipt, not because someone clicked acknowledge. What is not proved is a live Slack installation: workspace approval, registration and how the cards render in Slack are still to be accepted by you.

## Next

- Gate pull requests instead: [GitHub App](https://keryn.dev/docs/guides/github-app/) or [CI](https://keryn.dev/docs/guides/ci/).
- Every surface at a glance: [apps and integrations](https://keryn.dev/docs/guides/apps/).
