Skip to content
DashboardWebsite

Adding a New Pack

A minimal pack package looks like this:

my_pack_package/
├── pyproject.toml
└── my_pack/
├── __init__.py exports MyPack
├── pack.py MyPack(BasePack)
├── parser.py parsing logic
├── manifest.py VERSION, FILE_GLOBS
└── rules/
├── generic-rules.md
└── django-rules.md

BasePack lives in OpenTremor Core (opentremor_core.controllers.packs.base). Your package depends on opentremor-core, not the other way around.

my_pack/manifest.py
VERSION = "1.0.0"
# Glob patterns of file paths this pack claims — used by auto-routing
# (POST /v1/{changeset}/ingest|analyze/auto and the GitHub webhook) to decide
# which pack handles which changed file in a diff. Leave empty if the
# input isn't a single file (like the text output of a CLI tool) —
# implement sniff() below instead for that case.
FILE_GLOBS: list[str] = ["*.py"]
my_pack/pack.py
from __future__ import annotations
from pathlib import Path
from opentremor_core.controllers.packs.base import BasePack
from .manifest import FILE_GLOBS, VERSION
from .parser import parse_my_format
class MyPack(BasePack):
name = "my-pack" # URL slug — must be URL-safe
description = "Analyzes XYZ for security issues."
version = VERSION
repository_url = "https://github.com/<org>/OpenTremor-pack-my-pack" # shown on the dashboard's Packs page
file_globs = FILE_GLOBS
# Rule files: BasePack's get_rules() and list_rule_types() read them from here.
# rules/generic-rules.md is the default ruleset; rules/django-rules.md is variant "django".
rules_dir = Path(__file__).parent / "rules"
default_rules_file = "generic-rules.md"
# Optional: scores content that FILE_GLOBS cannot route — a single blob
# pasted into the dashboard's Analyze form, or the added lines of a diff
# file no pack's glob claims. Default is 0.0: opt out, and auto-routing
# never asks this pack. Override only if your format is recognisable from
# content alone, and match your own schema, not the language: when two
# packs score within 0.2 of each other, a diff file goes to `generic`.
# The highest score at or above 0.5 wins.
def sniff(self, raw_input: str) -> float:
return 1.0 if "some distinctive marker text" in raw_input else 0.0
# The parser: a plain function from the input text to AnalysisUnit models.
# BasePack.ingest() calls it and hands storage the dicts.
parse = staticmethod(parse_my_format)

get_rules() and list_rule_types() need no code when the rules are Markdown files — three class attributes drive BasePack’s defaults:

AttributeDefaultMeaning
rules_dirNoneWhere the rule files live. None means no rules: get_rules() raises NotImplementedError
rules_file_suffix"rules.md"The name every rule file ends with. Variant django is django-<suffix>
default_rules_filethe suffixThe default ruleset’s file, when it isn’t just the suffix (generic-rules.md above)

An unknown variant raises FileNotFoundError, which the API answers with 404. Override get_rules() only for rules that don’t live in files.

my_pack/__init__.py
from .pack import MyPack
__all__ = ["MyPack"]

Your parser returns AnalysisUnit models — pack-agnostic, the “thing a pack produces and an LLM analyzes one of”: a changed Python function, a Terraform resource block, an Ansible task, …:

my_pack/parser.py
from datetime import UTC, datetime
from opentremor_core.libs.hash import generate_resource_hash
from opentremor_core.models.resource import AnalysisUnit, UnitMetadata
def parse_my_format(raw_input: str) -> list[AnalysisUnit]:
return [
AnalysisUnit(
hash=generate_resource_hash(item.body),
type=item.type, name=item.name, action=item.action, body=item.body,
metadata=UnitMetadata(generated_at_utc=datetime.now(UTC), source_path=item.path),
)
for item in _split(raw_input)
]

If your input is a unified diff, don’t parse the diff yourself: opentremor_core.libs.diff provides iter_hunks(text, path_suffix=".py") — each Hunk includes its file path, Git’s section heading, and its +/-/space lines — and change_kind(lines) (add / delete / modify). Your parser only has to find its own blocks inside a hunk.

If your input is YAML — workflows, manifests, compose files, playbooks — opentremor_core.libs.yaml_diff also finds the blocks. iter_yaml_blocks(hunk) yields one YamlBlock per changed key or list item:

  • path — the key path from the document root, such as ("jobs", "build", "permissions"). A list item is "- " plus its first line: "- name: app".
  • kind — add, delete or modify.
  • lines — the block’s slice of hunk.lines, markers kept. It starts and ends with a changed line.
from opentremor_core.libs.diff import iter_hunks
from opentremor_core.libs.yaml_diff import iter_yaml_blocks
for hunk in iter_hunks(diff_text, path_suffix=".yml"):
for block in iter_yaml_blocks(hunk):
job = block.path[:2] # ("jobs", "build"): group blocks into one unit per job

Keys and items below a changed line are blocks of their own, at every depth. A new job, play or document therefore arrives as several blocks, its parent line (jobs:, ---) included. Group them on a path prefix, as the example does.

It reads indentation, not YAML, because a hunk is a fragment that a YAML parser rejects. Added lines are read against the new file and removed lines against the old one. Lines of a block scalar (run: |) take the path of their key. --- restarts the path. Every + and - line lands in exactly one block. When a hunk starts below keys it does not show, and Git’s section heading does not name them, the path holds ABOVE_HUNK ("…") in their place.


Declare the entry point in your package’s own pyproject.toml; do not change code in OpenTremor Core:

[project]
dependencies = ["opentremor-core>=1.0,<2"] # or a path/git source during development
[project.entry-points."opentremor_core.packs"]
my-pack = "my_pack:MyPack"

At startup, core discovers every installed package that declares this entry-point group and registers it automatically (controllers/app.py::_discover_packs()). Installing your package completes the integration.

In the dashboard: Rules → Packs. A registered pack starts off for every organization. An organization admin enables it for the whole organization with POST /v1/orgs/{org_id}/packs/{name} and {"enabled": true}, or on a product or repository. Declare accurate file_globs: they also decide which repositories get your pack suggested.


Terminal window
pip install -e ./my_pack_package # or uv add, if depending on it from core's own pyproject
curl http://localhost:8000/v1/packs
# → {"packs": [..., {"name": "my-pack", "description": "...", "version": "1.0.0", "repository_url": "...", "file_globs": [...], "detects_content": false, "license": "Apache-2.0", ...}]}
curl http://localhost:8000/v1/my-pack/rules
# → Markdown ruleset (with any enabled org custom rules for this pack, grouped by category, appended)
curl -X POST http://localhost:8000/v1/my-pack/my-changeset/ingest \
-H "Content-Type: text/plain" \
--data-binary @my_input.txt
# → [{"hash": "…", "type": "…", …}]

All of the above require an authenticated principal (API key or session), unless auth is disabled. See API overview for the authentication model.

Once FILE_GLOBS or sniff() is set, clients can also call your pack without naming it. POST /v1/{changeset}/ingest/auto and POST /v1/{changeset}/analyze/auto use the input to resolve the applicable pack or packs. See API endpoints. The GitHub webhook uses the same mechanism for PR diffs:

Terminal window
curl -X POST http://localhost:8000/v1/my-changeset/ingest/auto \
-H "Content-Type: text/plain" \
--data-binary @my_input.txt
# → {"units": [...], "packs_used": ["my-pack"], "detections": [...]}

Optionally, let an organization with no prior analyses load a demo analysis built from your pack’s sample without an LLM call. Put two files in the package and set demo_dir to their directory:

my_pack/pack.py
class MyPack(BasePack):
...
demo_dir = Path(__file__).parent / "demo"
FileContent
demo/input.txtRaw input, exactly what a user would paste. It goes through your own ingest()
demo/analyses.json{"<unit hash>": <UnitAnalysis>} for every unit ingest() produces; a unit with nothing to report gets {"verdict": "...", "findings": []}

Write the analyses by hand or capture them from a real run, then review them. This sample gives users their first impression of your pack. Use obviously fictional names and values (example-…, the documented AWS account 111122223333), and cite only rule ids from your own rule files.

Assert that the sample stays consistent. This makes parser or rule changes fail your build instead of breaking someone’s demo:

tests/test_demo_sample.py
from opentremor_core.controllers.packs import demo_sample_problems
from my_pack import MyPack
def test_the_demo_sample_is_consistent_with_the_pack():
assert demo_sample_problems(MyPack()) == []

demo_sample_problems() loads the sample and checks that ingest() produces exactly the hashes covered by analyses.json. It also checks that every finding’s rule_id appears in one of your rule files. GET /v1/packs reports has_demo: true for a pack that sets demo_dir. When several enabled packs ship one, the deployment’s analysis.demo_preferred_packs decides which loads.


  • name is URL-safe (lowercase, hyphens only)
  • package is self-contained — no files shared with other pack packages
  • parse is set and always returns a list of AnalysisUnit (an empty list is valid)
  • each unit’s hash is computed with generate_resource_hash() over its body
  • rule files are in the package’s own rules/, named <variant>-<rules_file_suffix>, with rules_dir set
  • manifest.py sets VERSION and FILE_GLOBS
  • FILE_GLOBS set or sniff() overridden so auto-routing can find this pack — at least one, unless the pack is only ever invoked by name. sniff() covers a pasted blob and a diff file no glob claims
  • the opentremor_core.packs entry point is declared in pyproject.toml
  • optional: a demo sample in demo/, with demo_dir set and demo_sample_problems() asserted empty in a test
  • unit tests added
  • a LICENSE file is present and the license field in pyproject.toml matches it. The dashboard’s Packs page shows that value

OpenTremor is split across two licences. The server — OpenTremor-core, OpenTremor-platform, OpenTremor-dashboard and OpenTremor-task-scheduler — is AGPL-3.0-or-later. Every integration surface, including all first-party packs, is Apache-2.0.

Packs can use permissive licences even though they depend on an AGPL core because core carries the OpenTremor Pack Plugin Exception (LICENSE-EXCEPTION in the core repo), an additional permission granted under section 7 of the AGPL. It says that a work which uses core only through the pack plugin API may be combined with core and distributed under any terms you choose.

The exception names that API surface explicitly. It is the surface described on this page:

CoveredWhere
BasePack, PackRegistryopentremor_core.controllers.packs.base
AnalysisUnit, UnitMetadataopentremor_core.models.resource
generate_resource_hashopentremor_core.libs.hash
Hunk, iter_hunks, change_kindopentremor_core.libs.diff — covered as documented pack surface (clause (e))
YamlBlock, iter_yaml_blocks, ABOVE_HUNKopentremor_core.libs.yaml_diff — covered as documented pack surface (clause (e))
the opentremor_core.packs entry-point groupyour pyproject.toml

If you contribute a pack back for inclusion alongside the first-party ones, match their licence: license = "Apache-2.0" in pyproject.toml, with a matching LICENSE and NOTICE copied from any existing pack.

A pack built for one company does not have to be open source. Still declare its licence in pyproject.toml, for example license = "LicenseRef-Proprietary". Core reads the field from the installed package metadata, and the dashboard’s Packs page shows it as is. A pack that declares no licence shows none.


Why build one at all? (the generic fallback)

Section titled “Why build one at all? (the generic fallback)”