Feat: Request explorer

[mclueppers]

No description provided.

[Copilot]

Pull request overview

This PR introduces a “Request Explorer” capability by recording bounded enforcement decisions (including a per-mechanism trace) into Redis, exposing them via new admin API endpoints, and adding an Admin UI page to search and inspect individual decisions. It also improves request-id consistency/correlation and updates OpenAPI + contract checking to account for non-fetchable parametric routes.

Changes:

• Add a shared decision buffering primitive and a new enforcement decision recorder flushed from redis_sync.
• Add new admin API endpoints (/decisions, /decisions/{request_id}) with RBAC permissions and OpenAPI documentation.
• Add an Admin UI “Request Explorer” page and navigation wiring.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/check-api-contract.py	Skip (and report) parametric/explicitly skipped OpenAPI paths during contract checks.
openresty/spec/decision_recorder_spec.lua	Adds unit tests for the new decision recorder behavior (buffering, flush, trace compaction).
openresty/lua/webhooks.lua	Uses cached request id from ngx.ctx to avoid per-read $request_id instability.
openresty/lua/waf_handler.lua	Adds stable per-request id caching, trace flattening, decision stashing, log-phase recording, and response header.
openresty/lua/shadow_recorder.lua	Refactors shadow recorder to use shared decision_buffer.
openresty/lua/redis_sync.lua	Flushes enforcement decision recorder during sync (reusing existing Redis connection).
openresty/lua/rbac.lua	Adds decisions permissions and routing coverage for decisions endpoints.
openresty/lua/defense_profile_multi_executor.lua	Propagates/merges trace data in multi-profile execution results.
openresty/lua/defense_profile_executor.lua	Builds per-node execution trace while accumulating score/flags.
openresty/lua/decision_recorder.lua	New module: bounded, configurable decision logging with trace compaction.
openresty/lua/decision_buffer.lua	New shared buffer implementation for request-path recording + timer-based Redis flush.
openresty/lua/api_handlers/decisions.lua	New API handler: search decisions + fetch one decision by request id + clear log.
openresty/lua/admin_api.lua	Registers decisions handlers and adds parametric routing for /decisions/{request_id}.
openresty/conf/nginx.conf	Adds env vars + shared dict for decision buffering; records decision in log_by_lua.
helm/forms-waf/templates/openresty-configmap.yaml	Mirrors nginx config additions for Helm deployments.
docs/openapi.yaml	Documents decision schemas and /decisions endpoints (including skip metadata for param route).
docs/API_HANDLERS.md	Documents the new decisions handler and RBAC resource.
admin-ui/src/pages/analytics/RequestExplorer.tsx	New UI page to search and inspect recorded decisions + trace breakdown.
admin-ui/src/components/layout/Sidebar.tsx	Adds navigation link to Request Explorer.
admin-ui/src/App.tsx	Adds route for the Request Explorer page.
admin-ui/src/api/generated.ts	Extends generated OpenAPI client types with decisions endpoints/schemas.
admin-ui/src/api/client.ts	Adds runtime API client helpers/types for decisions endpoints.

Suppressed comments (1)

openresty/lua/decision_recorder.lua:133

• compact_trace() can return an empty Lua table when nothing is considered significant, which cjson will encode as {} and the API will decode back into an object rather than an array. Returning nil when there are no significant entries avoids emitting an incorrectly-typed trace field in stored records and API responses.

local function compact_trace(trace)
    if type(trace) ~= "table" then return nil end

    local significant = {}
    for _, entry in ipairs(trace) do
        if type(entry) == "table" then
            local contributed = (entry.score or 0) ~= 0 or entry.blocked
                or (entry.flags and #entry.flags > 0)
                or entry.suppressed
            if contributed then
                significant[#significant + 1] = {
                    node       = entry.node,
                    defense    = entry.defense,
                    score      = entry.score or 0,
                    blocked    = entry.blocked or nil,
                    flags      = clip_list(entry.flags, 8, MAX_FLAG_LENGTH),
                    suppressed = clip_list(entry.suppressed, 8, MAX_FLAG_LENGTH),
                }
                if #significant >= MAX_TRACE then break end
            end
        end
    end
    return significant
end

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.