Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Slack review pilot

    View as Markdown

    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.

    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.

    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.

    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.

    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.

    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.

    Terminal window
    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.

    Terminal window
    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.

    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.

    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.