Dashboard
The dashboard is a Next.js app in the OpenTremor-dashboard repository. Engineers and platform administrators use it to manage organizations, members, packs, rules, findings, integrations, and analysis.
It uses the API’s session system. Email and password sign-in uses
POST /v1/auth/session; SSO sign-in completes through GET /auth/sso/callback. Both use the
httpOnly mcp_session cookie. The dashboard does not have a separate login system.
Navigation
Section titled “Navigation”The sidebar groups pages by task. A ▸ marks a collapsible category.
| Heading | Entries |
|---|---|
| (none) | Overview |
| Analysis | Findings · Products · Repositories · Changesets · Jobs |
| Rules | Rules (tabs: Rules, To review, Categories) · Packs · Rule Health |
| Organization | ▸ Access (Members, Teams, Invitations, Roles, Service Accounts, SSO) · ▸ Connections (GitHub, GitLab, Jira, Notifications, LLM) · ▸ Features (Agent Injection, Code Suggestions, Support Assistant, Report Templates) · ▸ Usage & Audit (Audit Log, Usage, Quota) |
| Platform Admin | Organizations · Users · ▸ Billing (Pricing, Usage) · ▸ Catalog (Rules, Models) · ▸ Analysis (Engine, Agent Injection, Review Feedback, Support Assistant) · ▸ Security (Firewall, Rate Limits, Sign-in Providers, Sign-up & Sessions, Agents, Audit Log) · ▸ Connections (GitHub Webhooks, GitLab, Jira, LLM Endpoints, Audit Streaming) · ▸ System (General, Data Lifecycle, Jobs, Database, Backups, Migrations) |
- New analysis, in the header, opens the Analyze page. It appears only when the analysis
product is mounted and you hold
analysis:run. - API docs, in the user menu at the bottom of the sidebar, opens the API’s Swagger UI.
- An entry you lack permission to access is hidden. A category with one remaining entry shows that entry directly.
- A number next to Findings counts the findings that need a human review. A number next to Rules counts the rules drawn from repository files that wait in the To review tab. Both refresh on every page change. They show only when the count is above zero and you may read it.
- With the sidebar collapsed to icons, a category’s icon opens a menu of its pages.
- The Platform Admin heading folds its section. It starts closed and opens by itself on an admin page.
- With a platform-only API, the Analysis and Rules headings, the Organization → Connections and Features categories and Platform Admin → Catalog and Analysis disappear.
The breadcrumb in the header follows the menu: the headings above the page, then the page. A detail page adds the name of what it shows, such as the product or the team.
The menu is declared as data. The platform’s half is in platform-ui/src/lib/nav/platform-nav.ts,
and the product’s half is in src/lib/nav/product-nav.ts. composeNav merges sections and
categories that share an id, then sorts entries by order. src/lib/nav/nav.test.ts fails
when a category or heading has fewer than two entries, or when a label repeats its category.
Search
Section titled “Search”The Search bar in the header finds pages and records in the current organization. Click it, or press ⌘K / Ctrl+K from any page. Type two characters or more, then pick a result with ↑↓ and Enter.
A search shows only what you could already open:
- Pages come from your sidebar, so a page hidden from you never appears. Each page shows where it sits in the menu, so two pages with the same name can be told apart.
- Records come from
GET /v1/search, which searches your current organization only. Each kind needs the permission of its own list page. A kind you lack is left out, not reported as an error.
| Kind | Matches on | Needs | Opens |
|---|---|---|---|
| Team | name | teams:read | the team’s page |
| Member | name, email | members:read | Members |
| Changeset | name | analysis:read | the changeset’s page |
| Finding | title, rule id, resource address | findings:read | Findings, filtered to that finding |
| Product | name | products:read | Products |
| Repository | full name | repositories:read | the repository’s page |
| Rule | rule id, title (custom and built-in rules synced to the org) | rules:read | Rules |
Matching ignores case and returns at most five records per kind. Closed findings are left out, as on the Findings page by default.
| Page | Backing endpoint(s) |
|---|---|
| Sign in / Register | POST /v1/auth/session, POST /v1/auth/register — both accept ?invite=<token> to join an org directly instead of creating/picking one. Register also reads GET /v1/auth/registration-options and drops the “create an organization” choice (and its org-name field) when registration.allow_public_org_creation is off. When the operator requires terms (registration.terms_*), Register also shows a required checkbox linking to them, which gates both the form and the “Continue with …” buttons. Sign in also offers “Continue with SSO” (POST /v1/auth/sso/discover → GET /v1/auth/sso/{org_id}/start) |
Accept invite (/invite/[token]) | GET /v1/invite/{token} (public preview), POST /v1/invite/{token}/accept, then POST /v1/auth/session/switch onto the org just joined — accepting alone only creates the membership, it leaves the session cookie pointing wherever it already pointed |
| Onboarding (no org yet) | POST /v1/orgs, POST /v1/auth/session/switch — shown instead of the normal dashboard shell when GET /v1/auth/me reports org_id: null. Also reads GET /v1/auth/registration-options: with public org creation off, the create-an-org form is replaced by a “use an invite link, or ask an administrator” note, leaving the invite route as the only way out. Also lists any invitations addressed to this account (GET /v1/auth/me/invitations) — the one route out that needs nothing from the user |
| Overview | GET /v1/orgs/{org_id}, GET /v1/orgs/{org_id}/usage, GET /v1/findings/summary, GET /v1/jobs. Also the Getting started checklist, each item checked against the endpoint of the page it leads to |
| Account (tabs: Profile, Sign-in, Agent access, Organizations) | GET /v1/auth/me, PATCH /v1/auth/me (own name), POST /v1/auth/me/password (own password, requires current password) — reachable regardless of org membership. Agent access lists, creates and revokes the account’s access tokens (GET/POST /v1/auth/me/access-tokens, DELETE /v1/auth/me/access-tokens/{token_id}); a new token is shown once. Also lists every organization this account belongs to (GET /v1/auth/me/organizations) with a self-service Leave action per row (POST /v1/orgs/{org_id}/leave), and any invitations waiting for this email (GET /v1/auth/me/invitations, POST /v1/auth/me/invitations/{invite_id}/accept) |
| Members | GET/POST /v1/orgs/{org_id}/members — each row also shows the member’s team names and, when set, a “scim”/“sso”/“invite” provenance badge (provisioned_via — informational only); admin/owner additionally get inline role change, org-scoped active/inactive toggle, one-time password reset, and remove (PATCH/DELETE /v1/orgs/{org_id}/members/{user_id}, POST .../reset-password) |
Teams (/teams, /teams/[team_id]) | GET/POST /v1/orgs/{org_id}/teams, GET/PATCH/DELETE /v1/orgs/{org_id}/teams/{team_id}, GET/POST /v1/orgs/{org_id}/teams/{team_id}/members, DELETE .../members/{user_id} — teams grant no access; they own repositories (see Repositories) and can scope notification channels |
| Invitations | GET/POST /v1/orgs/{org_id}/invites, DELETE /v1/orgs/{org_id}/invites/{invite_id} — an invitation can be left open (a link anyone holding it can redeem) or addressed to one email, in which case only that account can accept it and it appears on their Account page without the link having to be delivered |
| Roles | GET/POST /v1/orgs/{org_id}/roles, PATCH/DELETE /v1/orgs/{org_id}/roles/{role_id}, GET /v1/permissions — built-in roles read-only; custom roles created and edited from a permission checklist. Every role picker (members, invitations, service accounts, SCIM mappings) offers the org’s custom roles too |
| Service Accounts (tabs: API keys, Agent access) | GET/POST /v1/auth/keys, DELETE /v1/auth/keys/{key_id} — name, role, optional IP source filter (ip_allowlist) and optional permission scopes per key. Agent access, for holders of agent_access:manage: whether members’ access tokens act in the org (GET/PUT /v1/orgs/{org_id}/agent-access) |
| SSO (two tabs: Single sign-on and SCIM provisioning) | GET/POST/PATCH/DELETE /v1/orgs/{org_id}/sso |
| SSO page’s SCIM provisioning tab | GET/POST/PATCH/DELETE /v1/orgs/{org_id}/scim, POST .../rotate-token — tenant URL, bearer-token reveal-once, default role, ordered group-name-regex-to-role mappings |
| Packs | GET/POST/DELETE /v1/orgs/{org_id}/packs/{name} |
Pack ruleset preview (/packs/[pack]/rules) | GET /v1/{pack}/rules?repository=&rule_type=, GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/effective (read-only; For picks a repository or an analysis that names none; links out to Rules for editing) |
| Rules (paginated, 15/page) | GET/POST /v1/orgs/{org_id}/rules, GET/PATCH/DELETE /v1/orgs/{org_id}/rules/{rule_id}, GET .../coverage (the rule sheet’s Where it runs), POST .../reset (Use the pack version) |
| Rules page’s Categories tab | GET/POST /v1/orgs/{org_id}/rule-categories, GET/PATCH/DELETE /v1/orgs/{org_id}/rule-categories/{category_id}, POST .../seed-defaults |
| Agent Injection | GET/PUT /v1/orgs/{org_id}/injection-settings, GET /v1/orgs/{org_id}/llm-connections, GET /v1/models — turns on semantic injection scoring on the organization’s own LLM budget when the platform allows it, picks its model, and sets the injection gate. Viewers see the settings; admins change them |
| Report Templates | GET/POST /v1/orgs/{org_id}/report-templates, GET/PATCH/DELETE /v1/orgs/{org_id}/report-templates/{template_id}, POST .../seed-builtin, POST .../preview |
| LLM Connections | GET/POST /v1/orgs/{org_id}/llm-connections, PATCH/DELETE /v1/orgs/{org_id}/llm-connections/{connection_id}, POST .../test |
| Quota | PATCH /v1/orgs/{org_id}/quota, GET /v1/orgs/{org_id}/usage |
| Usage | GET /v1/orgs/{org_id}/usage, GET /v1/metrics/summary, GET /v1/analysis/metrics/summary, GET /v1/metrics/usage |
| Audit Log | GET /v1/metrics/audit, GET /v1/metrics/audit/export — filterable by action/actor/target/date range, CSV/JSON export |
| GitHub Integration | GET /v1/models (model picker), GET/PUT/DELETE /v1/orgs/{org_id}/integrations/github, GET /v1/orgs/{org_id}/integrations/github/app-name, POST /v1/orgs/{org_id}/integrations/github/manifest |
| GitLab Integration | GET /v1/orgs/{org_id}/integrations/gitlab/availability, GET/POST/DELETE /v1/orgs/{org_id}/integrations/gitlab, GET /v1/orgs/{org_id}/llm-connections, GET /v1/models — connect a self-managed GitLab group; shows the webhook URL and secret once. See GitLab Integration |
Repository (/repositories/[provider]/[external_id], tabs: Activity, Report, Settings, Packs, Rules, Knowledge, Scan) | GET .../repositories/{provider}/{external_id}/activity, GET /v1/changesets?repository=, GET .../report?format=html, and the repository settings endpoints |
| Repositories | GET /v1/orgs/{org_id}/repositories, POST .../repositories/sync, PATCH .../repositories/{provider}/{external_id}, POST .../repositories/bulk, GET/PUT .../repositories/ownership, POST .../repositories/ownership/apply, GET /v1/orgs/{org_id}/teams — every repository reachable from connected code hosts, the teams that own each one, and the rules that assign new ones. See Review routing |
| Notifications | GET/POST/PATCH/DELETE /v1/orgs/{org_id}/notifications/channels + POST .../test — N channels per org, one tab per kind (Slack, Microsoft Teams, email, webhook), per-channel event subscriptions built from GET /v1/notifications/events, per-channel test send and last-delivery status. Destination URLs are write-only and shown only as a redacted hint |
| Rule Health | GET /v1/rule-health, GET /v1/feedback, GET /v1/rule-proposals, POST /v1/rule-proposals/{proposal_id}/apply or /dismiss — per-rule reviewer precision and the rule changes supported by feedback. See Review Feedback Loop |
| Findings | GET /v1/findings, GET /v1/findings/summary, PATCH /v1/findings/{hash}/{rule_id} — status now includes needs_review, both auto-set (low LLM confidence, or a rule marked requires_review) and settable manually from this page’s status dropdown |
| Changesets / Report | GET /v1/changesets?product_id=&repository= (the list, with each changeset’s repository, product, pull request and open findings), GET /v1/changesets/{changeset} (the product › repository › pull request line), GET /v1/changesets/{changeset}/revisions (revision picker), GET /v1/changesets/{changeset}/report?format=html (Report tab), GET /v1/changesets/{changeset}/dump (Resources tab) |
Product (/products/[product_id], tabs: Repositories, Changesets, Report) | GET /v1/orgs/{org_id}/products/{product_id}, GET .../overview, GET /v1/changesets?product_id=, GET .../report?format=html. See Review routing |
| Analyze (the header’s New analysis button) | GET /v1/models (model picker, falls back to free text if the catalog is empty), POST /v1/{pack}/{changeset}/analyze (a “Variant” picker, sourced from the selected pack’s rule_types/default_rule_type, is shown when it has more than one and folds the choice into the request’s rule_type), GET /v1/jobs/{job_id}. The Pack picker defaults to Auto-detect, which posts to POST /v1/{changeset}/analyze/auto instead (no Variant picker — auto mode always uses each matched pack’s default) and renders the response’s detections as a small file → pack/skipped-reason table above the report |
| Jobs (paginated, 15/page) | GET /v1/jobs — every job for the org, from the Analyze page and the GitHub webhook. A job whose pack is auto (any /analyze/auto run, or a GitHub webhook run) shows an “Auto” badge with the resolved packs_used. GET /v1/jobs/{job_id} additionally fetches a ?job_id= link target as a pinned card; any row (pinned or not) expands in place into full status, live progress, and links to that job’s Findings/Report — see Linking the workflow together |
| Platform Admin → Organizations | GET /v1/admin/organizations (incl. an SSO enabled/not-configured badge per org), GET /v1/admin/organizations/{org_id} (adds the full SSO connection when one exists). Its detail page’s Members card is the superadmin drill-down — same role/active/reset-password/remove actions as the org-scoped Members page (GET/PATCH/DELETE /v1/admin/organizations/{org_id}/members[/{user_id}], POST .../reset-password), reachable without being a member of that org, plus a per-row “Edit account”/“Reset password” pair for the whole-account fields (PATCH /v1/admin/users/{user_id}, POST /v1/admin/users/{user_id}/reset-password) — kept in a visually separate column since it affects every org that user belongs to, not just this one |
| Platform Admin → Users | GET /v1/admin/users — every account, its organizations and role in each, 50 per page, filtered on the server by name, email or organization (?q=, ?page= in the URL); POST /v1/admin/users/{id}/superadmin from each row. Account actions are not repeated here: each organization badge links to that org’s Members tab |
| Platform Admin → Catalog → Models (16 defaults seeded at startup) | GET/POST /v1/admin/models, PATCH/DELETE /v1/admin/models/{llm_backend}/{model} |
| Platform Admin → Catalog → Rules | GET /v1/admin/custom-rules, GET /v1/admin/organizations — every organization’s rules in one read-only table, for support (OpenTremor-core#0042) |
| Platform Admin → Billing → Pricing | GET/PATCH /v1/admin/pricing — the instance’s degressive price list; see Pricing |
| Platform Admin settings pages: Analysis (Engine, Agent Injection, Review Feedback), Security (Rate Limits, Sign-in Providers, Sign-up & Sessions, Agents), Connections (GitHub Webhooks, Audit Streaming), System (General, Data Lifecycle, Jobs, Database) | GET/PATCH /v1/admin/settings (hardcoded-default fields the config file cannot control), GET /v1/admin/storage, POST /v1/admin/storage/prepare-mongodb — one page per group of sections |
| Platform Admin → Connections → GitLab | GET/PATCH /v1/admin/settings (gitlab_egress): whether orgs may connect a self-managed GitLab, and which hosts it may reach |
| Platform Admin → Connections → LLM Endpoints | GET/PATCH /v1/admin/settings (llm_egress): whether orgs may point an LLM connection at their own address, and which hosts it may reach |
| Platform Admin → Billing → Usage | GET /v1/admin/usage |
| Platform Admin → Security → Audit Log | GET /v1/admin/metrics/summary (cross-org rollup), GET /v1/admin/audit/GET /v1/admin/organizations/{org_id}/audit (org picker, default “All organizations”), GET /v1/admin/audit/export. The org detail page also shows an org’s 5 most recent audit events inline, linking through to this page pre-filtered |
The Platform Admin section appears in the sidebar only when GET /v1/auth/me reports
is_superadmin: true — a permission axis independent of any org’s role. See
Platform Admin for what it grants and how to bootstrap the first one.
Almost all of the above already existed in the REST API before the dashboard did. Building the dashboard added no new business logic beyond three small session-introspection routes needed to bootstrap identity on page load and support switching between organizations:
| Route | Purpose |
|---|---|
GET /v1/auth/me | Resolve the current session cookie into {user, org_id, role, is_superadmin} |
GET /v1/auth/me/organizations | List every org the signed-in user belongs to (org switcher) |
POST /v1/auth/session/switch | Re-scope the session cookie to a different org the user is a member of |
POST /v1/orgs | Create an additional organization (switcher → Create organization), then switch into it. Hidden when registration.allow_public_org_creation is off, unless the user is a superadmin — GET /v1/auth/registration-options |
The later exception is the GitHub Integration page, which drove new backend endpoints (the
manifest flow) rather than just wrapping existing ones. An org admin
registers the org’s own GitHub App entirely from the dashboard. A “Create GitHub App”
button submits a real top-level browser form to github.com, not a fetch call, because GitHub needs
to perform its own redirect back. The App’s private key/webhook secret never pass through the
browser.
Switching between many organizations
Section titled “Switching between many organizations”The sidebar switcher lists up to eight memberships inline, which covers almost everyone. Past that, it truncates the list. The current organization always appears first, so truncation cannot hide it. The switcher offers Search all N organizations, a filterable picker with ↑↓/Enter navigation. The same picker opens from anywhere with ⌘⇧O / Ctrl+Shift+O.
The picker is a dialog rather than a search field inside the dropdown on purpose: Base UI menus own keyboard focus and run their own typeahead over item labels, so a text input inside one fights the menu for every keystroke.
Where a switch lands you
Section titled “Where a switch lands you”Switching keeps you on the current page when that page means the same thing in the
new organization — Members, Findings, Rules, and every other entry in the sidebar. Anything else
falls back to /overview, because a route carrying an id (/changesets/{changeset},
/teams/{team_id}, /packs/{pack}/rules) names something that belongs to the
organization you just left. Query strings are dropped for the same reason: ?changeset=,
?job_id=, and other values are org-scoped ids, even on a page whose path is not.
The set of preservable routes comes from the composed sidebar nav rather than a hand-maintained list. A page added to the sidebar therefore becomes switch-preserving automatically.
Organization is per session, not per tab
Section titled “Organization is per session, not per tab”The org a request resolves to comes from the mcp_session cookie, and a cookie belongs to the
browser rather than to one tab. Switching organizations therefore re-scopes every open tab, not
just the one where you clicked the switcher. A second tab left on another org keeps displaying what
it already rendered, while every action you take in it now applies somewhere else.
To surface this, (dashboard)/layout.tsx wraps the whole shell in an
OrgContextGuard. The switching tab announces the new org on a BroadcastChannel, and every
other tab re-checks GET /v1/auth/me whenever it regains focus. This also catches a switch made
from another browser or device, and works in browsers without BroadcastChannel. When the orgs
do not match, the stale tab shows a dialog offering either “switch back” (POST /v1/auth/session/switch onto the org that tab was showing) or “continue” (land on /overview under the session’s current org).
The announcement carries the sending tab’s id, and each tab ignores its own id. A BroadcastChannel message reaches every other channel object with that name, including objects in the sending tab. Without the id, the switching tab would warn itself about its own switch. The dialog also compares the session org with the org this tab last rendered on every render, rather than latching a flag when it first detects a mismatch. The tab’s org changes under it as router.refresh() lands, so the dialog must close when it does.
Two tabs cannot stay on different organizations at once. Supporting that would require carrying the org per request and changing the auth path and every route.
The other later exception is org-less accounts and invitation links (see
Invitations): POST /v1/auth/register no longer requires
org_name, so a signed-in user can have org_id: null. (dashboard)/layout.tsx redirects
that state to /onboarding (outside the authenticated shell, alongside /login//register)
before rendering the sidebar. Every other page under (dashboard)/ fetches identity
via getMeWithOrg() rather than getMe() directly. That performs the same redirect, so no
individual page has to guard against a null org_id.
Cookies and consent
Section titled “Cookies and consent”On a visitor’s first visit, every page shows a cookie banner in the bottom corner, whether the
visitor is signed in or not. It has Refuse all and Accept all, which carry equal weight,
and Customize, which opens a per-category dialog. The choice is stored in a cookie_consent
cookie for six months, a refusal included, and then the banner asks again. The same dialog can be
reopened at any time from Cookie settings in the sidebar’s user menu, from the site footer, or
from /cookies.
/cookies is a public page that lists everything OpenTremor stores in the browser, with each
item’s purpose and lifetime:
| Name | Purpose | Lifetime |
|---|---|---|
mcp_session | Sign-in session and active organization | Until sign-out, or session.access_ttl_minutes (8 h default) |
oauth_state / sso_state | Request-forgery protection during a social or SSO login | 10 minutes |
cookie_consent | The visitor’s consent choice | 6 months |
sidebar_state | Sidebar open or collapsed | 7 days |
getting_started_hidden | Organizations where you hid the Getting started checklist | 1 year |
theme (localStorage) | Light or dark theme | Until cleared |
All of these are strictly necessary and exempt from consent under the EU ePrivacy rules. The only
optional category, Analytics, gates nothing by default. It exists so a fork can add an optional
tracker without a separate consent mechanism. If you add one to a fork, render it
inside <ConsentGate category="analytics"> from @opentremor/platform-ui/components/cookie-consent,
and list any new cookie in COOKIE_INVENTORY (@opentremor/platform-ui/lib/cookie-inventory) so
it appears on /cookies. Anything added in front of the dashboard, such as a load balancer’s
sticky-session cookie or an analytics tag injected at the ingress, bypasses the banner. You are
responsible for consent to it.
Running locally
Section titled “Running locally”From the workspace root — npm runs inside the containers, nothing is installed on your machine:
make up-dev # the dashboard at http://localhost:8080/dashboard, live-reloadingThe dev stack also publishes the dashboard and the API on their own ports. Local dev does not
need a reverse proxy, even though the dashboard and API run on different ports. By default, the
API’s CORS configuration reflects the request Origin when allow_credentials=True, following
Starlette behavior rather than using a "*" literal. The httpOnly session cookie therefore
round-trips correctly across ports.
Report viewing
Section titled “Report viewing”The changeset report page (/changesets/{changeset}) fetches rendered HTML server-side via the authenticated
GET /v1/changesets/{changeset}/report?format=html endpoint and embeds it with <iframe srcDoc>. It does not
reimplement report rendering, so styling and content stay in one place
(views/formatter.py / services/reports/). No public link needs to be minted to view a report
for your organization while you are signed in. A template picker
next to the page title lets you switch between the built-in HTML template and any
of your organization’s custom HTML templates (GET /v1/orgs/{org_id}/report-templates?format=html).
Selecting one appends &template_id= to the same server-side fetch, keeping this a
query-param-driven addition rather than a client-side re-fetch of report data.
The page has two tabs, kept in ?tab=. Report shows the embedded report. Resources
lists the resources of the selected revision from GET /v1/changesets/{changeset}/dump, with each resource’s
finding count and worst severity. A resource with findings links its name to
/findings?resource_hash={hash}, the Findings page narrowed to that resource.
When a changeset has more than one revision, a History card above the tabs lists them,
newest first: what each push closed, opened and left open (GET /v1/changesets/{changeset}/revisions).
Findings on a row expands the findings behind those counts
(GET /v1/changesets/{changeset}/revisions/{revision}/changes). Report opens that revision’s report.
On the Findings page, a changeset filter shows how many of its findings later pushes closed, with
links to them and to this history.
The built-in report names the model and LLM connection used to analyse its units, under the title. A client-led analysis appears as “your own agent”.
The built-in report has filters. Severity and status toggles sit above the findings table, and a toggle hides resources without findings. A finding’s title links to its details. The filters use no script, so they also work offline, on a shared link and in print.
The built-in report follows the dashboard’s light or dark theme, including when you switch
themes while the report is open. A custom HTML template follows the theme only if it reads the
theme class (see Report templates).
The Usage page’s “Requests” stat and the “Requests by API key” chart below it reflect only
API-key-authenticated traffic. See Endpoints — Metrics
for details. A session-cookie request, such as loading this page, does not count, so reloading
the page never inflates its own numbers. “Resources analyzed” reflects ingest spans from
either ingestion path (POST .../ingest or the Analyze page’s POST .../analyze). Both share
one implementation.
Each row on the Findings page has a chevron toggle (components/finding-detail-panel.tsx)
that expands on demand to show the resource block, the LLM’s evidence, risk, and next step for
that finding, and the matching rule. None of this data is in FindingRecord itself, which is
deliberately a flattened triage summary. The panel fetches GET /v1/resource/{hash} and GET /v1/orgs/{org_id}/rules/{rule_id} the first time a row is
expanded, then keeps the result for the rest of the page’s lifetime. When the org has no rule
with that id, the panel shows the pack’s built-in rule from
GET /v1/{pack_name}/rules/{rule_id} instead.
An agent-manipulation finding, such as AGENT-PATTERN-MATCH, has neither. Its rule comes from
GET /v1/detection-rules/{rule_id}, without a severity badge; the finding carries its own.
A tag that names a rule opens that rule’s title, severity and description on hover or click
(components/finding-tag.tsx). Two kinds of tag name a rule. An Agent Threat Rules entry, such
as atr:ATR-2026-00001, comes from GET /v1/detection-rules/{rule_id} and adds its references.
A built-in rule id of the finding’s pack, such as TFSEC-040, comes from
GET /v1/{pack_name}/rules/{rule_id}. Each rule is fetched the first time its tag opens. The expanded panel
also shows a “View report” link for each changeset in FindingRecord.changesets. A finding
can appear in more than one changeset. Each link goes directly to that changeset’s report
page.
The Rules page (custom-rules-manager.tsx) and the read-only superadmin cross-org table on
/admin/rules (platform-rules-manager.tsx) share one filter bar (rule-filter-bar.tsx) and
one table (rules-table.tsx). Each rule is a single cell: its title with a source badge (Built-in,
Built-in · edited, Written, From ADR, From agent instructions) and the Pack update, Scope empty and
“Needs review” badges, and a muted line with its category, variant, packs and where it applies.
Severity, the enabled switch and icon actions take the other columns, so a long title wraps instead
of widening the table. The admin table adds an Organization column and has no actions.
Built-in rules follow their pack. When a pack release adds a rule, rewords one, or removes one,
core updates every organization at its next start (OpenTremor-core#0034): it adds the new rule,
rewrites built-in rows nobody edited, and disables unedited rows whose rule left the pack. A row
you edited, enabled or disabled stays as you left it. Sync built-in rules
(POST /v1/orgs/{org_id}/rules/seed-builtin) runs the same sync for your organization on demand.
Built-in rules are filed under the default categories, including Performance and
Reliability. Rules in those two categories are LOW or MEDIUM and never fail the merge check
on their own.
Both tables paginate client-side, 15 rows at a time, after search/source/category/severity/
pack/enabled filtering. GET /v1/orgs/{org_id}/rules returns the full unpaginated list, so this
dashboard-side slice requires no new query params. Changing any filter resets the table to
page 1.
On the Rules page, New rule and each row’s edit button open the rule form in a side panel.
The Products and Report Templates pages and each Notifications tab work the same way. All of them
use EditorSheet from @opentremor/platform-ui.
Only that form exposes the “Always needs human review” toggle that sets requires_review. The
platform-admin view only lets users toggle enabled or delete a rule.
The Report Templates page itself (report-templates-manager.tsx) has a table of an org’s
templates (name, built-in/custom origin, a
Switch for is_default) plus a create/edit form in a wide side panel, with a plain Textarea for the
Jinja2 source (no code-editor dependency in this project, same choice already made
for custom rules’ Markdown description). A live preview sits next to the editor
(report-template-preview.tsx). It calls POST /v1/orgs/{org_id}/report-templates/preview
600 ms after typing stops and renders the current in-progress form state (not yet saved).
By default it renders against sample data: the demo analysis built in memory on the server. A
changeset typed into its “Preview against” field replaces the sample with that changeset’s real
analysed data. An HTML result renders in the same themed frame as the report page; a markdown
result renders in a <pre> block. A render error, such as a template syntax error, shows in the
pane.
Rows are grouped under a header row for each format rather than listed flat with a format
badge, because is_default is scoped to (org, format). Up to three switches can be on
at once, one per format. Grouping same-format rows makes this clear. Toggling one on
optimistically clears its same-format sibling, matching what clear_other_defaults does
server-side. Users can toggle the last one off; the built-in template for that format then
becomes the default.
A “Get shareable link” button on that page mints a public link on demand: a
high-entropy /reports/{token} URL on the dashboard, time-limited by the org’s
report_link_ttl_hours (default 24h, see Endpoints — Report links).
Use this when you want to share the report with someone outside the dashboard.
The iframe’s content is not a shareable URL.
The shared page needs no sign-in. It blocks scripts in the report, so a custom HTML template cannot run code on the dashboard’s address.
Analysis workflow visualization
Section titled “Analysis workflow visualization”Both the Analyze page’s job poller and the Jobs page render a four-stage stepper (Queued →
Ingest & parse → Analyze resources → Report ready/Failed). It derives the stages from a job’s
status and two counters, processed_count and total_count. run_analysis() updates these
counters through an optional progress_cb after each unit is analyzed. This callback is wired
only for the async job path. The sync path responds within one request and does not use it. A
failed job maps to the stage indicated by its counters, since the job model does not record
which stage actually failed. lib/analysis-steps.ts derives the step list once;
analysis-stepper.tsx renders it full-size on the Analyze page or as a compact icon row
with a text summary in the Jobs table.
The Jobs page (/jobs, jobs-table.tsx) lists every job for the org, from the Analyze
page and the GitHub webhook, through a new GET /v1/jobs endpoint with a status filter and
15-item pagination. It polls every 3s while any visible row is queued or running.
This is the only place to see webhook-triggered jobs. The Analyze page’s poller only
tracks the job it just launched.
Linking the workflow together
Section titled “Linking the workflow together”The Analyze page’s job poller (job-status-poller.tsx) links to /jobs?job_id=<id>
as soon as a job is created, not just when it is done. The Jobs page reads that
job_id query param server-side and fetches the job directly via GET /v1/jobs/{job_id},
independently of the current status filter or page. It renders the job as a pinned,
pre-expanded “Linked job” card above the filtered table, so the link always resolves to
visible content.
Every row in the Jobs table (pinned or not) can be expanded in place, mirroring the
Findings table’s chevron-toggle pattern, via a shared job-detail-panel.tsx component.
It needs no extra fetch — everything it renders already lives on the polled JobStatus
object — and shows the full-size stepper, a processed/total progress bar,
current_resource (the resource most recently picked up by the analysis loop; since
resources are processed strictly one at a time, this doubles as “what’s running right
now” while the job is running), the auto-detection breakdown, and two links: “View
findings” (/findings?changeset=<job.changeset>, which the Findings page’s changeset
filter already reads as its default) always, and “View report” once the job is done.
The panel also shows two lifecycle actions. Cancel appears for a queued or running
job with a background run to stop. It does not appear for a mode: "sync" job, which runs
entirely inside the request that started it. Retry/Resume appears for any job that stopped
with work left: failed (labelled “Retry”), cancelled, or done with quota_exceeded.
The last two are labelled “Resume” because the work is being continued, not retried after an
error. A budget-capped job also gets an explanation, so a done job with a Resume button
says why. Both buttons follow their endpoint’s preconditions, so the API accepts every
action the UI offers.
Every run appears here, including inline runs. A run small enough to finish within its
request (server.sync_analysis_max_units, default 5) is recorded as a mode: "sync" job,
and the Analyze page links to it. On success, it links from the report; on failure, from a
callout. This covers the failure case that previously needed a link. Before this change, a
small failed analysis left only a toast.
Below the auto-detection breakdown, the panel also renders any
agent-injection signals found by the job
(injection-detections-panel.tsx). Each signal is severity-coloured and shows its file and
line, or its channel if it appears in a pull request title, description, or commit message.
These signals do not belong to a file. Evidence is shown pre-formatted and never collapsed.
For these signals, exact whitespace and invisible characters rendered as <U+200B> escapes
can matter, and normalizing them away would hide what the report flags. The same signals appear
on the Findings page like any other finding. This panel lets reviewers see why a job held a
pull request without leaving the job.
See Deployment for how the dashboard is built and served alongside the API in Docker Compose.