Adding a New Pack
1. Create the package
Section titled “1. Create the package”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.mdBasePack lives in OpenTremor Core (opentremor_core.controllers.packs.base). Your package depends on opentremor-core, not the other way around.
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"]from __future__ import annotationsfrom pathlib import Path
from opentremor_core.controllers.packs.base import BasePackfrom .manifest import FILE_GLOBS, VERSIONfrom .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:
| Attribute | Default | Meaning |
|---|---|---|
rules_dir | None | Where 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_file | the suffix | The 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.
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, …:
from datetime import UTC, datetime
from opentremor_core.libs.hash import generate_resource_hashfrom 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.
YAML diffs
Section titled “YAML diffs”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,deleteormodify.lines— the block’s slice ofhunk.lines, markers kept. It starts and ends with a changed line.
from opentremor_core.libs.diff import iter_hunksfrom 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 jobKeys 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.
2. Register the pack via entry points
Section titled “2. Register the pack via entry points”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.
3. Verify
Section titled “3. Verify”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:
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": [...]}Ship a demo sample
Section titled “Ship a demo sample”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:
class MyPack(BasePack): ... demo_dir = Path(__file__).parent / "demo"| File | Content |
|---|---|
demo/input.txt | Raw 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:
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.
Checklist
Section titled “Checklist”-
nameis URL-safe (lowercase, hyphens only) - package is self-contained — no files shared with other pack packages
-
parseis set and always returns a list ofAnalysisUnit(an empty list is valid) - each unit’s
hashis computed withgenerate_resource_hash()over itsbody - rule files are in the package’s own
rules/, named<variant>-<rules_file_suffix>, withrules_dirset -
manifest.pysetsVERSIONandFILE_GLOBS -
FILE_GLOBSset orsniff()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.packsentry point is declared inpyproject.toml - optional: a demo sample in
demo/, withdemo_dirset anddemo_sample_problems()asserted empty in a test - unit tests added
- a
LICENSEfile is present and thelicensefield inpyproject.tomlmatches it. The dashboard’s Packs page shows that value
Licensing your pack
Section titled “Licensing your pack”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:
| Covered | Where |
|---|---|
BasePack, PackRegistry | opentremor_core.controllers.packs.base |
AnalysisUnit, UnitMetadata | opentremor_core.models.resource |
generate_resource_hash | opentremor_core.libs.hash |
Hunk, iter_hunks, change_kind | opentremor_core.libs.diff — covered as documented pack surface (clause (e)) |
YamlBlock, iter_yaml_blocks, ABOVE_HUNK | opentremor_core.libs.yaml_diff — covered as documented pack surface (clause (e)) |
the opentremor_core.packs entry-point group | your 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.