Slack review pilot
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.
What it is
Section titled “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
Section titled “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_urlin a Slack request is ignored, redirects are refused, and before posting the adapter checksauth.testagainst 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
Section titled “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
Section titled “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
Section titled “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.
node clients/slack-app/demo.mjs --out output/slack-review-demoUse 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
Section titled “Prepare an installation”node clients/slack-app/setup.mjs --out output/slack-setup --origin https://review.example.comSetup 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
Section titled “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
Section titled “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.
- Gate pull requests instead: GitHub App or CI.
- Every surface at a glance: apps and integrations.