Module Map
Two Python packages, two trees. opentremor_core is the analysis engine in OpenTremor-core;
opentremor_platform is the multi-tenant base in OpenTremor-platform, which core mounts on (see
Platform / product composition). Each line comes from the module’s
own docstring or a summary of it, so a module missing here is a module the docs have not caught up
with.
OpenTremor-core/src
Section titled “OpenTremor-core/src”server.py Uvicorn entrypoint — host, port, reload and log level from the environmenttools/└── refresh_atr_rules.py Refresh the vendored injection-detection corpusopentremor_core/├── cli.py `opentremor-admin` — operator commands that run against the database, not through the API.├── config.py Pydantic AppConfig — typed, validated at load time├── controllers/│ ├── app.py Application factory — create_platform_app() (multi-tenant base only) + create_app() (= platform + _install_product()), _init_storage, lifespan│ ├── dependencies.py FastAPI deps: get_storage, require_permission(name) (the role must hold the permission; fails closed on an org-less None role), require_authenticated (any principal, org optional — /auth/me, /auth/…│ ├── errors.py Product-specific exceptions.│ ├── packs/│ │ ├── base.py BasePack ABC (+ .manifest) + PackRegistry (skips is_ready=False)│ │ └── demo.py A pack's demo sample: an input and its analysis, written once and shipped with the pack.│ ├── routers/│ │ ├── analysis/│ │ │ ├── injection.py GET/PUT /v1/orgs/{org_id}/injection-settings — semantic scoring and the injection gate (admin to change)│ │ │ ├── jobs.py GET /v1/jobs, GET /v1/jobs/{job_id} (async-analysis status polling), POST /v1/jobs/{job_id}/retry (resume a failed api-triggered job under a new job_id)│ │ │ ├── metrics.py GET /v1/analysis/metrics/summary — the ingest/analysis rollup (org-admin only, org-scoped)│ │ │ ├── packs.py Pack discovery, rules, ingest, server-side analyze (org-scoped)│ │ │ └── resources.py Resource CRUD + changeset operations (org-scoped)│ │ ├── catalog/│ │ │ └── products.py Products — named groups of repositories, owned by teams (models/catalog.py).│ │ ├── demo/│ │ │ └── sample.py The demo analysis — sample findings an organization can explore before its first real run.│ │ ├── feedback/│ │ │ └── verdicts.py Review feedback, rule health, and the rule changes it suggests.│ │ ├── findings/│ │ │ └── triage.py GET /v1/findings, GET /v1/findings/summary, PATCH /v1/findings/{hash}/{rule_id} (status incl. needs_review; setting it notifies subscribed channels, and any status change re-posts the commit status of ever…│ │ ├── goals/│ │ ├── integrations/│ │ │ ├── github.py GitHub App connect/disconnect (admin), manifest-flow trigger/callback for custom per-org Apps, + public webhook receiver (verifies, normalises to a PullRequestRef, enqueues the review) — commit sta…│ │ │ └── gitlab.py GitLab (self-managed) integration — org-admin connect/disconnect + the webhook receiver.│ │ ├── llm/│ │ │ ├── catalog.py GET /v1/models (member), GET/POST /v1/admin/models + PATCH/DELETE /v1/admin/models/{llm_backend}/{model} (superadmin) — allowed-models catalog, platform-wide│ │ │ └── connections.py LLM connections — org-scoped endpoints analysis runs against.│ │ ├── product/│ │ │ ├── admin.py GET /v1/admin/custom-rules (read-only), GET /v1/admin/analysis/metrics/summary — the product-owned half of the /admin surface, same prefix, separate router (superadmin only)│ │ │ └── org.py Org-scoped routes owned by the analysis product, mounted under the platform's /orgs prefix.│ │ ├── reports/│ │ │ └── templates.py POST/GET /v1/orgs/{org_id}/report-templates, GET/PATCH/DELETE /v1/orgs/{org_id}/report-templates/{template_id}, POST .../seed-builtin, POST .../preview (custom report templates CRUD, org-scoped)│ │ ├── repositories/│ │ │ ├── inventory.py The repository inventory.│ │ │ ├── ownership.py Who owns which repository.│ │ │ └── settings.py What runs on one repository: rule exclusions, and a preview of the next review.│ │ └── rules/│ │ ├── categories.py POST/GET /v1/orgs/{org_id}/rule-categories, GET/PATCH/DELETE /v1/orgs/{org_id}/rule-categories/{category_id}, POST .../seed-defaults (org-owned rule categories, fully editable/deletable)│ │ ├── custom.py POST/GET /v1/orgs/{org_id}/rules, GET/PATCH/DELETE /v1/orgs/{org_id}/rules/{rule_id} (custom rules CRUD, org-scoped)│ │ └── detection.py GET /v1/detection-rules/{rule_id} — core's AGENT-* rules and the vendored Agent Threat Rules entries│ ├── seed/│ │ ├── categories.py seed_default_categories_for_org() — imports the 12 default rule categories, Performance and Reliability included (ids match the old fixed enum's values); must run before rules.py's sync│ │ ├── models.py seed_default_allowed_models() — platform-wide allowed-models catalog seeding at startup│ │ ├── rules.py sync_builtin_rules_for_org() — keeps an org's custom_rules in step with every pack's built-in rules: adds new ones, updates rows the org never edited, disables unedited rows whose rule left the file (OpenTremor-core#0034); sync_builtin_rules_for_all_orgs() runs it for every org at startup, once per version of the pack files│ │ └── templates.py seed_builtin_templates_for_org() — imports the 3 built-in report templates into report_templates at org setup, not default│ ├── services/│ │ ├── settings_sections.py composition: imports every domain's registrations in order, then verify_complete() asserts no AppConfig section lacks a disposition│ │ ├── analysis/│ │ │ ├── content_router.py Auto-routing: pick the right pack(s) for raw input without the caller having to name one — the mechanism `BasePack.file_globs` was always meant for (see its docstring), now actually wired up.│ │ │ ├── injection_scan.py Run agent-injection detection over a change and record what it finds.│ │ │ ├── injection_scoring.py Run tier 2 of agent-injection detection: one LLM call per tier 1 match, paid by the org.│ │ │ ├── injection_settings.py An organization's agent-injection settings — read, saved and resolved against the platform.│ │ │ ├── jobs.py The analysis engine's side of a background job: its document, and what it records at the end.│ │ │ ├── metering.py What the analysis engine counts, declared to the platform's meter registry.│ │ │ ├── metrics.py Prometheus metrics for the analysis engine.│ │ │ ├── queue.py Background analysis on the platform's job queue (`OpenTremor-platform#0014`).│ │ │ ├── recording.py record_analysis() — shared side-effects (metrics, span, findings upsert with review's computed initial_status, needs_review notification on auto-needs_review) for every analysis, client- or server-led│ │ │ ├── revisions.py Starting a revision of a changeset.│ │ │ └── runner.py run_analysis()/count_units() — server-side analysis orchestration; resume_analysis() is the second half of run_analysis (everything after ingest_units), split out so POST /v1/jobs/{job_id}/retry can r…│ │ ├── catalog/│ │ │ └── products.py Products: ids, validation, and what deleting one undoes (models/catalog.py).│ │ ├── demo/│ │ │ ├── lifecycle.py Loading, reading and removing an organization's demo analysis — the only writer of demo data.│ │ │ └── scenario.py The half of the demo every pack shares: a pull request that tries to talk its AI reviewer down.│ │ ├── feedback/│ │ │ ├── calibration.py Composing reviewer verdicts into the analysis prompt — bounded, fenced, and inspectable.│ │ │ ├── capture.py Recording what a human said about a finding — the capture half of the review-feedback loop.│ │ │ └── ingest.py Turning a pull-request comment into a reviewer verdict.│ │ ├── findings/│ │ │ ├── needs_review.py notify_needs_review() — sends finding.needs_review to every subscribed notification channel│ │ │ └── review.py compute_initial_status() — open vs needs_review for a brand-new finding: a matched rule marked requires_review, or LOW/UNKNOWN LLM confidence│ │ ├── goals/│ │ ├── integrations/│ │ │ ├── github_app.py github_client_for()/webhook_secret_for() — the org's own GitHub App; github_app_name()/check_app_name() — the App's name; GitHubScmRepository — GitHub's adapter behind the code-host port; github_c…│ │ │ ├── gitlab.py GitLab (self-managed) as a code host: reaching an org's instance, and the repository adapter.│ │ │ ├── pr_comment.py The pull-request comment — one comment per pull request, edited in place.│ │ │ ├── pr_gate.py compute_gate_state() — the single definition of how findings map to a PR check state, called by both the review job and a triage action; record_pr_gate()/refresh_pr_gates_for_resource() rem…│ │ │ ├── providers.py open_repository() — the one place that picks an adapter by provider│ │ │ ├── review.py enqueue_pull_request_review()/review_pull_request() — the host-independent pull-request review (scm.pull_request job)│ │ │ └── scm.py ScmRepository port + PullRequestRef — what the review needs from any code host│ │ ├── llm/│ │ │ ├── catalog.py is_model_allowed(storage, llm_backend, model) — allowed-models enforcement; empty catalog == unrestricted│ │ │ └── connections.py Resolve an org's LLM connection into a ready-to-call client.│ │ ├── product/│ │ │ ├── notify_events.py What this product notifies about — the event vocabulary and its payload builders.│ │ │ ├── offboarding.py the analysis engine's org-purge step — the eight collections it keys by org_id, registered into the cascade above│ │ │ ├── permissions.py The analysis engine's permissions, declared to the platform's permission registry.│ │ │ ├── retention.py the analysis engine's sweep steps — severity-tiered findings purge + raw resource-content redaction, registered into the sweep above│ │ │ └── settings.py the analysis engine's own settings sections (the product halves of retention/server)│ │ ├── reports/│ │ │ ├── data.py build_report_data() — changeset resources joined against findings-triage status; shared by the report endpoints and the GitHub webhook job│ │ │ └── templates.py resolve_and_render() — picks explicit template_id > org's default template for a format > the built-in file, for every report-rendering call site; render_custom() turns any Jinja2/Python rendering…│ │ ├── repositories/│ │ │ ├── inventory.py The repository inventory — which repositories an org's code-host integrations reach.│ │ │ ├── ownership.py Which teams own a repository, and so who reviews what it sends.│ │ │ └── suggestions.py Rule variant suggestions: what the analysed content says about a repository's packs.│ │ └── rules/│ │ ├── categories.py unique_category_id()/validate_category() — org-owned rule-category id generation + existence check│ │ ├── coverage.py rule_coverage() — where one rule runs: rule_decision() for every repository, and for an analysis that names none│ │ ├── health.py Rule precision, and the rule changes the evidence suggests.│ │ ├── ruleset.py get_effective_rules() — composes an org's enabled custom rules after a pack's base rules, grouped by category (resolved against the org's rule_categories list, alphabetical by name, "Uncategorized"…│ │ ├── reset.py reset_to_pack() — gives a built-in rule its pack file's wording again (POST .../rules/{rule_id}/reset)│ │ └── scope.py rule_decision() — whether a rule runs on a target, or the first check it fails; which custom rules apply where: an org-wide rule everywhere, a scoped rule only where its scope matches (models/rules.py, RuleScope).│ └── storage/│ ├── base.py StorageBackend = both halves; re-exports the error contract│ ├── mongo.py MongoBackend + ensure_mongo_indexes (org_id-scoped)│ └── product_base.py ProductStorageBackend ABC — resources/changesets, findings, jobs, custom rules, categories, templates, report links, LLM credentials, allowed models, integrations├── libs/│ ├── analysis_guard.py Guards on LLM-produced analysis, for the paths where the analysed content is attacker-controlled.│ ├── content_sniff.py Generic, pack-independent content-type labeling.│ ├── diff.py Unified-diff reading shared by core and by every pack that parses a diff.│ ├── github_client.py Thin httpx wrapper for the GitHub Apps API — no GitHub SDK dependency.│ ├── gitlab_client.py Thin httpx wrapper for the GitLab REST API (v4), plus inbound webhook verification.│ ├── hash.py Content hash (SHA-256 after normalisation)│ ├── injection_scan/│ │ ├── patterns.py Tier 1: the vendored Agent Threat Rules corpus, matched per channel.│ │ ├── segment.py Split a change into typed channels, so a detector can score *where* text sits and not just what it says.│ │ ├── semantic.py Tier 2: an LLM's second opinion on a tier 1 pattern match.│ │ └── structural.py Tier 0: the detections that need no patterns, no corpus and no model.│ └── llm/│ ├── anthropic_client.py Anthropic backend — structured output via a forced single tool call.│ ├── base.py Provider-agnostic structured-output LLM client interface.│ ├── mistral_client.py Mistral backend — Mistral's OpenAI-compatible Chat Completions endpoint.│ ├── openai_client.py OpenAI backend — structured output via response_format=json_schema.│ ├── openai_compatible_client.py Any endpoint speaking the OpenAI Chat Completions wire format.│ └── retry.py Retry-with-backoff around one structured LLM call.├── models/│ ├── analysis.py AnalyzeRequest/AnalyzeResponse/JobAccepted/LLMCredentialCreate; JobStatus — widens the platform's JobRecord with this product's fields (changeset, pack, llm_backend, detections, current_resource, ...)│ ├── catalog.py Products — named groups of repositories, owned by teams.│ ├── demo.py What GET/POST /v1/demo return — see controllers/services/demo/lifecycle.py.│ ├── feedback.py Human review feedback — the durable record of what a person said about a finding.│ ├── findings.py FindingStatus (incl. needs_review), FindingRecord, FindingStatusUpdate, FindingsSummary│ ├── github_webhooks.py The parts of GitHub's webhook payloads the webhook endpoint reads.│ ├── gitlab_webhooks.py The parts of GitLab's webhook payloads the webhook endpoint reads.│ ├── injection.py An organization's agent-injection settings: tier 2 scoring and the gate.│ ├── integrations.py GitHubIntegrationCreate/GitHubIntegrationInfo/GitHubAppInfo/GitHubAppManifestResponse│ ├── llm_connections.py LLM connections — one stored endpoint an org can run analysis against.│ ├── llm_models.py AllowedModel/AllowedModelCreate/AllowedModelUpdate — allowed-models catalog (platform-wide, no org_id)│ ├── repositories.py The repository inventory — every repository an org's code-host integrations reach.│ ├── reports.py ReportQuery, ChangesetReportQuery (the report endpoints' query string), ChangesetReport, ScopeReport (format=json)│ ├── resource.py AnalysisUnit, Finding, UnitAnalysis, UnitMetadata — pack-agnostic, no custom to_dict, use model_dump()│ ├── rules.py CustomRuleCreate, CustomRuleUpdate, CustomRule (category: str, a rule_categories.category_id reference; requires_review: bool routes a match straight to needs_review), RuleCategoryCreate, RuleCateg…│ └── templates.py ReportFormat, ReportTemplateCreate, ReportTemplateUpdate, ReportTemplate, ReportTemplatePreviewRequest/Response└── views/ ├── formatter.py OutputFormatter — Jinja2 SandboxedEnvironment; format_markdown/format_markdown_light/format_html render the 3 built-in files, format_custom() renders org-authored source (no template loader, autoes… └── templates/ ├── html_report.html.j2 ├── markdown_report.md.j2 └── markdown_report_light.md.j2OpenTremor-platform/src
Section titled “OpenTremor-platform/src”opentremor_platform/├── config.py Typed platform configuration via Pydantic.├── controllers/│ ├── app.py OpenTremor Platform — application factory.│ ├── dependencies.py FastAPI dependency functions and shared domain exceptions.│ ├── mcp_server.py FastMCP server over the routes a product declares, run as the caller.│ ├── routers/│ │ ├── auth/│ │ │ ├── api_keys.py API key management routes (org-admin only) — "service accounts" in dashboard terms.│ │ │ ├── permissions.py The permission catalogue — every permission this deployment's domains declare.│ │ │ ├── recovery.py Account recovery and email verification — the flows that go through a link in an email.│ │ │ ├── saml.py SAML 2.0 endpoints for an org's SSO connection (platform adr/0037).│ │ │ ├── session.py Human user registration and session (login/logout) routes.│ │ │ ├── social_login.py Social login — "Continue with Google / Microsoft", platform-wide.│ │ │ └── sso.py Per-organization SSO — org-admin connection management + the login flow.│ │ ├── billing/│ │ │ └── pricing.py Platform-wide, admin-configurable metered pricing.│ │ ├── notifications/│ │ │ ├── channels.py Org-scoped notification channels — where an org's events are delivered.│ │ │ └── slack.py The guided Slack install — an org's own app, Slack's own channel picker.│ │ ├── system/│ │ │ ├── admin.py Platform-admin routes — cross-tenant operator views.│ │ │ ├── capabilities.py GET /v1/capabilities — which domains are mounted on this deployment.│ │ │ ├── health.py Health probes. Both are public: an orchestrator calls them without credentials.│ │ │ └── metrics.py Org-admin-only metrics, telemetry, and audit endpoints (scoped to the caller's organization).│ │ └── tenancy/│ │ ├── orgs.py Organization management routes.│ │ ├── roles.py An organization's roles — the built-in four, and custom roles the org defines.│ │ ├── scim.py Per-organization SCIM 2.0 provisioning (RFC 7643/7644) — Entra ID (or any SCIM-compliant IdP)│ │ └── teams.py Teams — org-owned, freely-editable named groupings of existing members.│ ├── services/│ │ ├── audit.py Structured audit-event recording — actor-attributed privileged-action log.│ │ ├── capability_registry.py The capability registry — what is actually mounted on this deployment.│ │ ├── notification_events.py The notification-event registry — how a product declares what it can notify about.│ │ ├── org_purge_registry.py The org-purge step registry — how a domain gets its own rows deleted when an org is purged.│ │ ├── settings_composition.py Settings composition for the platform half.│ │ ├── settings_registry.py The settings-section registry — how a config section becomes admin-editable.│ │ ├── slug.py Shared slug generation — server-generated, immutable ids derived from a│ │ ├── sweep_registry.py The sweep-step registry — how a domain contributes work to a platform-owned sweep.│ │ ├── auth/│ │ │ ├── account_links.py The emails that carry a single-use link back to the dashboard: reset a password, verify an address.│ │ │ ├── permissions.py The permission registry — what an org-scoped endpoint asks of its caller.│ │ │ ├── roles.py What a stored role means, and who may hand it out.│ │ │ ├── sessions.py Session state that lives on the user document — revocation, and the remembered org.│ │ │ ├── social_login.py Social login providers — which ones this deployment offers, and each one's quirks.│ │ │ ├── terms.py Whether a new account must accept the operator's terms, and how that acceptance is recorded.│ │ │ └── user_tokens.py Single-use links sent to a person: password reset and email verification.│ │ ├── billing/│ │ │ ├── budget.py The monthly spend cap — what an org may still spend this month.│ │ │ ├── entitlements.py Plan-gating: whether an org may consume a meter right now, and how its usage is billed.│ │ │ ├── meters.py The meter registry — what a product counts, declared by the product.│ │ │ └── pricing.py Degressive (S3-style) per-unit pricing of the billed meter, and enterprise overage on top of it.│ │ ├── jobs/│ │ │ ├── control.py Reading a job's own record back, mid-run, to decide whether it should keep going.│ │ │ ├── kinds.py The kinds of queued job a product declares, and what runs each.│ │ │ ├── queue.py The job queue: putting a job on it, and the worker every replica runs to take jobs off it.│ │ │ ├── runner.py Running one background job — starting it, reporting progress, and writing how it ended.│ │ │ └── sweep.py Stuck-job sweep orchestration — applies PlatformConfig.jobs' policy once.│ │ ├── mail/│ │ │ ├── delivery.py Sending a templated email without making the caller wait for it.│ │ │ └── templates.py The mail-template registry — what each email the platform, or a product, sends says.│ │ ├── notifications/│ │ │ ├── fanout.py Notification fan-out — one event in, N deliveries out.│ │ │ ├── recipients.py Who an email channel mails — resolved from the member list on every read and every send.│ │ │ ├── slack_oauth.py Slack's OAuth v2 install flow, for an org's own Slack app.│ │ │ └── webhooks.py Outbound webhooks — HMAC-signed, best-effort delivery.│ │ ├── system/│ │ │ ├── retention.py Retention sweep orchestration — the platform half: run one sweep, time it, persist state.│ │ │ └── settings.py Admin-editable subset of PlatformConfig — hardcoded defaults overlaid with a database override,│ │ └── tenancy/│ │ ├── invites.py Invitation redemption — shared by the two ways an invite can be accepted.│ │ ├── members.py Member-management guardrails and actions shared by the org-admin routes│ │ ├── org_offboarding.py Org-offboarding purge — hard-deletes every organization whose deletion grace period has│ │ ├── orgs.py The one place a new organization document is built.│ │ ├── scim.py SCIM 2.0 provisioning sync logic (RFC 7643/7644) — kept out of controllers/routers/tenancy/scim.py so│ │ └── team.py Teams — id helpers + membership validation for the CRUD router, mirroring│ ├── shared/│ │ ├── exception_handlers.py How exceptions that escape a route become JSON responses.│ │ ├── org_bootstrap.py Per-org bootstrap hooks — "an organization was just created, seed whatever it needs".│ │ ├── public_urls.py Where this deployment is reachable from a browser — for building redirects out of a login flow.│ │ ├── startup.py Startup hooks — "the app is coming up, storage is ready, do your one-time seeding".│ │ └── observability/│ │ ├── background.py Best-effort writes that must never slow down or fail the request that triggered them.│ │ ├── http_metrics.py Prometheus: the HTTP request histogram, and the /metrics endpoint every collector shows up on.│ │ ├── request_context.py What the current request is: its correlation ID and the principal it authenticated as.│ │ └── spans.py Telemetry spans: one per HTTP request, plus whatever domain spans a product records.│ └── storage/│ ├── index_registry.py The index registry — how each domain declares the MongoDB indexes it needs.│ ├── lifecycle.py Storage lifecycle + the shared error contract.│ ├── mongo_admin.py Admin-triggered MongoDB preparation.│ ├── platform_base.py PlatformStorageBackend — the persistence contract for the multi-tenant platform half.│ └── platform_mongo.py MongoDB persistence for the platform half (PyMongo's async driver).├── libs/│ ├── auth.py API key / password hashing and session token utilities.│ ├── crypto.py Reversible encryption for stored secrets (SSO client secrets, notification channel URLs, …).│ ├── egress.py Outbound-request policy — which addresses this server is permitted to call.│ ├── mail.py Sending one email — the transport, and nothing about what the message says.│ ├── network.py IP source-filtering helpers for service-account API keys (ApiKeyDocument.ip_allowlist).│ ├── oidc_client.py Thin httpx + PyJWT wrapper for the OIDC authorization-code + PKCE flow used by│ ├── rate_limit.py Attempt budgets for credential verification — the app-layer half of brute-force protection.│ ├── saml_sp.py SAML 2.0 service provider for per-organization SSO connections.│ ├── totp.py TOTP (RFC 6238) secret/code handling for local-account 2FA.│ └── notify/│ ├── email.py Email renderer — a subject line and a plain-text body.│ ├── envelope.py The canonical notification payload — one struct, N renderers.│ ├── slack.py Slack Incoming Webhook renderer — Block Kit.│ └── webhook.py The raw-JSON renderer — the envelope, verbatim.└── models/ ├── admin.py Response models for the platform-admin surface (GET/POST /v1/admin/*). ├── audit.py Structured audit-event model: who did what to which target, and when. ├── auth.py Organization, user, membership and API key data models. ├── billing.py Platform-wide, admin-configurable pricing for the billed meter, and the per-org usage summary. ├── capabilities.py What GET /v1/capabilities returns — see controllers/services/capability_registry.py. ├── common.py Response shapes shared by every router — here and in any product composed on the platform. ├── jobs.py Background job tracking — the domain-neutral half. ├── metrics.py Span data models for telemetry. ├── notifications.py Request/response models for notification channels. ├── retention.py Retention sweep result — the outcome of one run of controllers.services.system.retention. ├── scim.py Request/response models for per-org SCIM 2.0 provisioning (RFC 7643/7644). ├── settings.py Platform settings — the admin-editable subset of PlatformConfig, plus MongoDB preparation. ├── social_login.py Response models for the platform's social login providers (routers/auth/social_login.py). ├── sso.py Request/response models for per-organization SSO connections, over OIDC or SAML 2.0. └── teams.py Teams — org-owned, freely-editable named groupings of existing members.