Table of Contents

Every chapter in this report, in order — click any entry to jump straight to it.

Foreword — About CIRCL and the NGSOTI Project

Before explaining what Rulezet does, it helps to know who built it and why — this isn't a weekend side project, it's a tool built by a national CERT for the community it already serves every day.

Rulezet is developed at CIRCL — the Computer Incident Response Center Luxembourg, the country's governmental CERT. CIRCL's day job is responding to and coordinating the response to computer security incidents affecting Luxembourg, but it's also known well beyond its borders for building and operating open tools the wider security community relies on: MISP (the threat intelligence sharing platform), the MISP taxonomies and galaxy knowledge bases that standardize how threats are described, and Vulnerability Lookup, a fast CVE/vulnerability reference search engine.

Rulezet was built at CIRCL as part of NGSOTI, a project aimed at giving the next generation of SOC analysts and detection engineers better tooling and training. MISP solved the "how do we share threat indicators" problem for the community years ago. Rulezet exists to solve the equivalent problem for detection rules — the YARA signatures, Sigma queries, and Suricata/Zeek scripts that actually do the detecting, which never had an equivalent shared home.

Everything in this documentation — and everything on the live platform — is shared under a TLP:CLEAR posture: open, disclosable, meant to be spread. If you're not familiar with Traffic Light Protocol classification, chapter 5 (Core Terminology) explains it — you'll see it again as a default tag on every rule.

The Problem — Why Detection Rule Sharing Is Broken

Detection rules are the operational output of threat detection work — and today, they live everywhere except one trustworthy place.

Ask any detection engineer where "the rules" live and you'll get an uncomfortable answer: scattered across dozens of GitHub repositories, buried in blog post code blocks, pasted into private Slack channels, or sitting in a folder on someone's laptop who left the team eighteen months ago. Every one of those rules represents real analytical work — someone noticed a pattern, wrote logic to catch it, and then had nowhere durable to put it except "wherever was convenient at the time."

That scattering isn't just untidy, it actively costs security teams detection quality:

• No single place to check "has this already been solved?" — a team burns half a day writing a rule for a technique that a dozen other teams already detect, because there was no shared index to search first.
• No consistent way to judge if a rule is actually good. Syntactically valid isn't the same as effective, and a rule copied from a blog post with a silent typo in a field name will pass code review and fail in production, quietly, for months.
• Format fragmentation compounds everything. YARA, Sigma, Suricata, Zeek and others all describe detection logic differently — there was no tool that treated them as equally first-class, so teams standardized on whichever format they happened to start with and struggled to reuse anything written for a different one.
• Ownership evaporates. A rule written by an analyst who has since left the team becomes an orphan — still running, still generating alerts or silently failing to, with nobody left who remembers why it exists or whether it still should.

Rulezet's answer isn't "yet another paste bin with search." It's a platform that validates a rule's syntax the moment it arrives, flags likely duplicates automatically, tracks who owns what, and puts community review directly into the workflow — so that scattering stops being the default and becomes something you'd have to actively choose instead.

What Is Rulezet — Vision, Mission, Goals

An open-source, community-driven platform to create, import, validate, discuss, and curate cybersecurity detection rules across multiple formats.

Rulezet gives detection content the same treatment source code gets from a modern developer platform: version history, peer review, ownership, quality gates, and a search index that actually understands what it's looking at. The four goals that shaped every feature in this report:

Supported rule formats today

YARA, Sigma, Suricata, Zeek, Wazuh, NSE, CRS, Nova, Elastic, and a free-text "no format" fallback for anything else. This list is deliberately not fixed — chapter 29 explains how a new format gets added as a self-contained plug-in, without touching anything else in the platform.

Audience & How to Read This Documentation

This report is long on purpose — here's where to start depending on who you are, so you don't have to read all of it to get value from it.

Day to day, this documentation is meant to be browsed as a website with the navigation menu on the left. When you need an offline or formal copy — onboarding a new analyst, sharing with a partner organization evaluating Rulezet — use the Export button in the top-right at any time, either as a printable PDF or as a plain Markdown file.

Core Terminology & Concepts

A handful of words this report leans on constantly — defined once here, so every later chapter can use them without re-explaining.

A fuller alphabetical list, including every format acronym used in this report, is in Appendix A — Glossary.

Accounts, Roles & Permissions

Any collaborative platform needs to know who is doing what — accountability is what makes community-contributed detection content trustworthy at all.

Every visitor to Rulezet falls into exactly one of three tiers, and this three-tier model is the single most important concept to understand before anything else in this report — nearly every later chapter refers back to it instead of re-explaining permissions from scratch.

Within the "authenticated" tier, one more distinction matters everywhere: ownership. Whoever created a rule, bundle, or comment is its owner, and — together with any admin — is the only one who can edit or delete it. This single rule (owner-or-admin, nobody else) is applied identically across every feature in this report; once you've internalized it here, you won't need it re-explained per chapter.

What this feature covers

• Registration, email verification, login, password reset.
• Profile editing (name, avatar) and a public contributor profile (see chapter 18, Gamification).
• API key generation and rotation for programmatic access.
• Notification preferences (chapter 19).

Rule Management — Create, Import, Version

The rule is the atomic unit of the entire platform. Every other feature in this report exists to make rules easier to find, safer to trust, or better maintained.

There are two ways a rule comes into existence on Rulezet, and both end up going through the exact same validation gate (chapter 8 covers that gate in depth):

What you can do with a rule once it exists

• Edit content, metadata, and associated CVE/vulnerability identifiers (if you own it, or you're an admin).
• Favorite it and vote it up or down — community signal that factors into how it surfaces in search.
• View its full detail page: metadata, syntax-highlighted content, edit history, similarity matches, and the comment thread — each of those gets its own chapter later in this Part.
• Delete it — which, importantly, is a soft delete (see the callout below), never an instant, irreversible removal from a single click.

Rule Validation, Quality & Similarity Detection

This chapter is the safety net — the direct answer to "rules may contain syntax errors, and even valid ones offer no guarantee they're not a duplicate of something that already exists."

Two independent mechanisms work together here. Validation happens the instant a rule is created or imported — a format-specific parser (chapter 29 explains the mechanism behind this) checks that the content actually parses as valid syntax for its declared format. Similarity detection is a separate, on-demand analysis that compares a rule's content against everything else already in the library to flag likely duplicates or near-duplicates for human review.

When validation fails: the Bad Rules queue

A rule that fails validation is never silently discarded and never silently accepted broken — it's quarantined into a dedicated queue, visible to whoever submitted it (or an admin), with the specific errors that were found. This matters most during a bulk GitHub import: out of, say, forty imported files, three might fail — those three show up for the importer to fix or discard deliberately, instead of vanishing into a log nobody reads.

When two rules look alike: similarity detection

A similarity scan compares rule content across the library and ranks candidate pairs by how alike they are, surfacing them for a human to decide: genuinely the same rule imported twice, a deliberate variant worth keeping separately, or coincidentally similar and fine as-is. Every rule's detail page also carries its own "similar rules" panel so this isn't only something an admin runs platform-wide — anyone reviewing one rule can immediately see its closest relatives.

Collaborative Edit Proposals

The pull-request model, applied to detection content — anyone can suggest an improvement to a rule they don't own, without ever needing direct write access to make the suggestion.

Any authenticated user who spots something worth changing in a rule — a condition that's too broad, a false-positive-prone pattern, a stale reference — can open an edit proposal: write the change plus a short message explaining why, and submit it for review. From there, a proposal moves through exactly three possible states.

The review itself happens against a full side-by-side diff of the current content versus the proposed content, with its own dedicated comment thread underneath for back-and-forth discussion before a decision is made — the same review ergonomics engineers already expect from a code review, applied to a Sigma condition or a YARA string.

Ownership & Transfer Requests

Rules need a responsible owner at all times — this is the formal, auditable mechanism for that responsibility to change hands.

There are two distinct paths to a change of ownership, and Rulezet is careful to make both show up identically in the audit trail even though they start very differently.

Both regular users and admins share the exact same requests page — a deliberate choice: a regular user tracking their own requests should never see "admin" anywhere in that URL or its layout, because it's a page they use routinely, not an administrative tool they're being let into. What differs is visible content, not the address: a regular user sees their own pending requests, history, and requests made to them; an admin additionally sees a processing queue for everyone else's requests and a Manual Ownership tool for bulk transfers.

A request's detail page shows exactly what's being transferred: a single rule for an individual request, or the full list of rules covered for a bulk manual grant — so "what did this actually affect" is always answerable, never a mystery buried in a count.

Bundles — Curated Rule Collections

If a rule is the atom, a bundle is the molecule — how a coherent, shareable "detection pack" gets assembled and distributed as a single thing.

A bundle is a named collection of rules that can be organized into folders (not just a flat list) via a drag-and-drop structure editor — useful when a bundle mirrors the layout of a source repository, or when a large bundle benefits from being grouped by technique, log source, or campaign phase. Like rules, bundles get the full community treatment: voting, view/download counts, and comments.

Access control is the other half of what makes bundles useful: a bundle can be public (anyone can see it) or private (visible only to its owner and admins) — so a "starter kit" can be iterated on privately and published only once it's actually ready.

Capabilities

• Create, edit, and delete a bundle (owner or admin).
• Add rules individually or via a bulk rule-selector.
• Arrange rules into a folder-style structure tree.
• An "official" verified badge, presumably admin-granted, for particularly trusted bundles.

Rule History & Audit Trail

The place a reader goes to answer "what happened to this rule over time, and who did it" — regardless of which mechanism actually caused the change.

Every accepted change to a rule's content or ownership appends an entry to that rule's own History tab: what changed, who did it, and when — with a link back to the originating edit proposal or ownership request where one exists. It's deliberately additive-only: there's no way to edit or delete a past history entry after the fact, because the point of an audit trail is that it can't be quietly rewritten.

Tags, MISP Taxonomies & Galaxies

Free-text search only goes so far — a shared vocabulary lets rules be classified consistently across an entire community instead of every team inventing its own labels.

Three related but distinct words matter here, and mixing them up is the single most common point of confusion for newcomers:

Every new rule gets tlp:clear and pap:clear attached automatically the moment it's created — a sensible, shareable default that a user can tighten later if the content warrants a stricter classification.

MITRE ATT&CK Mapping

Ties every rule to the industry-standard adversary-behavior framework, so coverage can be reasoned about as a whole — not counted rule by rule by hand.

A rule can be linked to one or more ATT&CK techniques (identified by their standard ID, like T1068) either manually, or via an auto-parse pass that attempts to extract technique references directly from a rule's own content — an accelerator for bulk imports, not a substitute for a human glancing over the result.

Community Discussion — Comments, Reactions & Moderation

Detection rules get better under scrutiny — this is the mechanism for that scrutiny to happen in the open, attached directly to the content it's actually about.

The exact same threaded comment experience — replies, emoji-style reactions — appears in every place discussion can happen: on a rule, on a bundle, inside an edit proposal, and under a blog post. Learning it once means you already know it everywhere. A separate Comment Hub view lets you catch up on everything being discussed right now across the whole platform, instead of hunting object by object for what's new.

Moderation is deliberately kept separate from ordinary discussion: any comment, rule, or bundle can be reported/flagged by any user, which raises it — privately — into an admin moderation queue for review, resolution, or dismissal. The reported party never sees that a report was filed against them.

Blog & Knowledge Sharing

Rules alone don't carry the "why" — a blog post is where the narrative context a set of rules is responding to actually gets told.

A post can be drafted privately and iterated on before publishing, and — critically — can directly associate itself with specific rules, bundles, ATT&CK techniques, and CVE identifiers, so the write-up and the actionable content it discusses are one linked unit rather than two things a reader has to reconcile themselves. Readers discuss a post through the exact same comment system used everywhere else (chapter 15).

As a starting accelerator, a draft post can be generated from a CVE reference automatically — useful as a first pass a human still needs to review and rewrite before publishing, not an autonomous authoring feature.

Personal Workspaces

An investigation rarely fits neatly into "one rule" or "one bundle" — a workspace is the flexible scratch space for everything in between.

A workspace lets you gather a working set of rules alongside freeform notes (documents) and reference links, with a quick KPI panel summarizing what's inside — all without committing to publishing anything. It's the working-notes layer that sits before a bundle, not a replacement for one.

Gamification & Leaderboard

Community platforms live or die on sustained contribution — recognizing effort is the incentive layer that keeps people coming back to review, propose, and own rules.

Actions across the platform — an edit proposal being accepted, a rule attracting likes, taking on ownership of orphaned content — accumulate into a points total, which maps to a level. A contributor's own profile shows their full breakdown; a global leaderboard (searchable, sortable, paginated) shows how everyone stacks up, with category-specific views for different kinds of contribution.

Notifications

With this many collaborative workflows running at once, users need one place that says "something happened that needs your attention" — instead of having to poll every page just in case.

Nearly every collaborative action described elsewhere in this report — a proposal submitted or decided, a new comment or reply, a report filed, ownership requested or granted, a long-running job finishing — creates a notification for whoever needs to know: the owner, an admin, a follower. A bell icon shows a live unread count and a short recent list; a full page lists and paginates everything with read/unread state, and a preferences page lets each user control which event types actually notify them.

Rule Tester

A rule that's syntactically valid isn't necessarily a rule that matches anything real — the Rule Tester is where you find out before you trust it.

Sample data is attached to a rule, the test is run, and matches (or the lack of them) are reviewed with notes kept alongside for future reference. A test can be kept private or shared, and bulk testing lets a larger validation effort run across many rules against a reference dataset at once rather than one at a time.

Customizable Dashboard

Different people care about different signals — a manager wants trend charts, an analyst wants a rule list — a fixed homepage can never serve both well.

Widgets — KPI tiles, charts, a rule list, an ATT&CK coverage heatmap, trending vulnerabilities, an activity feed, an activity calendar, a "format race" comparison, and summary stat rows — can be added, removed, resized, and rearranged on a drag-and-drop grid. The layout is saved per user and reloaded automatically next time, with a one-click reset back to the platform default if an experiment doesn't work out.

Connectors & Federation

No single Rulezet instance should be an island — connectors let instances share content with each other, so a smaller or private deployment still benefits from a larger community's work.

An admin configures a connector pointing at another Rulezet instance (or a MISP source), tests connectivity, previews exactly what a pull would bring in, and then runs it — as a trackable background job (chapter 23), not a black-box operation. Every pull is logged in the connector's own history for later audit.

Matching between instances is done strictly by a stable UUID, never by title or name — this avoids the obvious failure mode of two unrelated rules that happen to share a name being incorrectly merged.

Background Jobs & Async Operations

Several operations across this report — bulk transfers, GitHub imports, similarity scans, connector pulls — are slow by nature. This is what keeps them visible and safe instead of freezing the interface.

Any operation heavy enough to matter runs as a trackable job with a visible status (pending, running, paused, completed, failed, cancelled) instead of tying up a request. A live progress view shows what's happening as it happens, and a structured, timestamped log is attached to every job for troubleshooting after the fact. If the server restarts mid-job, the job is automatically recovered back to a pending state rather than being silently lost.

Crucially, jobs can be paused and resumed without starting over — a large operation doesn't have to run start-to-finish in one sitting, and doesn't lose the work already done if it's interrupted.

This mechanism underlies operations described throughout this report: bulk tag add/remove, GitHub rule deletion, activity log cleanup, MISP data refresh, trash restore/purge, connector pulls, bulk ownership transfer, ATT&CK data refresh and bulk parsing, bulk field parsing, and CVE-based blog draft generation — each covered in its own chapter; this one is about the shared mechanism they all run on.

Activity Log & Audit Trail (Platform-Wide)

Complements the per-rule history from chapter 12 with a platform-wide, cross-feature trail — the answer to "what has been happening on this instance," mainly for admins.

Every significant action anywhere on the platform is recorded consistently, and each action type carries configurable metadata — an admin can adjust its visibility and description rather than that being hard-coded — which is what powers a curated, public-facing activity feed alongside the full admin-only log. Old entries can be bulk-purged as a background job (chapter 23) rather than growing forever unchecked.

Administration & Platform Settings

Someone has to run the instance day to day — this is the admin's operational chapter, distinct from the feature-specific admin actions already covered per topic elsewhere in this report.

Everything here is admin-only, without exception: user management, the rule format catalogue (enabling or disabling formats, and whether a format is treated as "executable"), the Trash (restoring or permanently purging soft-deleted rules, individually or in bulk), system/package/environment configuration, backups, and the instance's own configuration — including the "official instance" flag that enables the daily telemetry phone-home, deliberately true only on the canonical rulezet.org deployment.

A separate Platform Insights view gives instance-wide usage analytics — distinct from the per-user dashboard in chapter 21, this one is about the health of the whole deployment, not one person's workflow.

Public REST API

Not every interaction with Rulezet should require clicking through a browser — the API is what lets a team automate rule pulls or build Rulezet into their own tooling.

Authentication is a personal API key (generated from your profile, chapter 6) sent in a request header. Every namespace is documented and directly exercisable through interactive documentation built into the running instance — you can try a real request before writing a single line of integration code.

Every action still respects the exact same ownership and admin rules described in chapter 6 — the API is a different door into the platform, not a way around its permission model.

System Architecture Overview

The thirty-thousand-foot view every contributor should have before touching anything else described in this Part.

Rulezet is built as a fairly classical web application: a server that renders pages and handles requests, a relational database holding everything durable, and a lightweight interactive layer in the browser that takes over once a page has loaded — no separate build pipeline stands between writing a page's code and seeing it run. That choice is deliberate: it keeps the barrier to contributing low. Anyone can open a single file, see the page's structure and its interactive behavior together, and understand the whole picture without first learning a separate front-end toolchain.

Alongside ordinary request/response handling, three things run continuously in the background, all triggered by the same everyday user actions described throughout Part II:

• The background job engine (chapter 28) — anything too slow to do inline becomes a trackable, resumable task instead.
• The audit trail (chapter 24) — nearly every meaningful action writes a record as it happens.
• Notifications (chapter 19) — the same actions fan out to whoever needs to know about them.

A single example ties all three together: an admin runs a bulk ownership transfer (chapter 10). That transfer runs as a background job so the browser stays responsive throughout; each affected rule's ownership change is written to the audit trail as it happens; and the new owner receives a notification the moment it's done. Three chapters, one action — this is the pattern to recognize whenever a new feature is being designed.

The Background Job Engine

The mechanism behind every "this might take a while" operation from chapter 23 — explained for someone who wants to make a brand-new operation work the same way.

The core idea is simple to state and easy to get wrong in practice: a background operation processes its work in small chunks, and after each chunk it writes down exactly how far it's gotten — a "bookmark." Nothing about its progress is allowed to live only in memory, because the operation might be paused by a user, or the whole server might restart, at any moment between chunks. When it resumes — whether a second later or the next day — it starts by reading its own bookmark and continuing from there, not from the beginning.

Conceptually, adding a new kind of background operation means:

The Rule Format Parsing Engine — How to Add a New Format

How Rulezet treats nine very different detection languages identically everywhere else in the platform — and exactly what's involved in adding a tenth.

Concretely, a format only ever needs to answer three questions about a piece of content: is this valid for the format (and if not, what exactly is wrong with it), what metadata does it carry (title, author, whatever the format naturally exposes), and — only relevant for bulk import — how do I find individual rules inside a larger file or repository that might contain many of them. Every existing format (YARA, Sigma, Suricata, Zeek, and the rest) answers those same three questions in its own way; nothing else in the platform needs to know or care how.

Adding a new format, conceptually

Frontend Architecture & Shared Components

How the interactive layer is organized, and why the same handful of building blocks show up in nearly every chapter of Part II.

Rather than every feature reinventing its own version of a code viewer, a diff viewer, a comment thread, or a rule list, a small catalogue of shared building blocks exists and gets reused everywhere the same need comes up. This is why, across this entire report, the same interaction patterns keep reappearing: the comment thread on a rule (chapter 15), on a bundle (chapter 11), and under a blog post (chapter 16) isn't three separate implementations that could quietly drift apart — it's the same one, used three times.

Development Conventions & Use Cases to Respect

A short list of hard rules — each one exists because breaking it caused a real problem before, not as an arbitrary style preference.

Deleted content stays deleted, everywhere

A rule (or bundle, or post) that's been removed must not resurface anywhere it's referenced — search results, listings, the API — and everything attached to it (like its discussion thread) needs to be cleaned up consistently at the same time, not left behind pointing at something that no longer exists. This principle underlies the comment-cleanup guarantee described in chapter 15.

Soft delete before hard delete

Destructive actions get a recoverable, reviewable middle step before anything is truly, permanently gone — the Trash described in chapters 7 and 25. Treat "permanently remove" as a deliberate, separate, admin-only second action, never the direct result of an ordinary delete click.

Ownership and admin rights are the only two ways in

The rule from chapter 6 — only a resource's owner or an admin can change or remove it — applies everywhere a resource can be acted on, without a feature-by-feature exception. A new feature that lets someone act on a resource needs to apply this same check, not invent its own variant.

Shared pages gate only their admin-specific parts

A page that both regular users and admins need — like the requests page in chapter 10 — must gate only the pieces that are genuinely admin-only, never the whole page. Locking an entire shared page behind an admin check by mistake is a real regression this project has hit before, and is exactly the kind of thing worth testing deliberately from a non-admin account.

A structural change and its rollout are one action, not two

If how data is organized changes, the operational step that applies that change to the running system must happen at the same time — not "eventually," not "before the next deploy." A structural change that's only half-applied can break the live system the moment anything touches it.

Ordered lists need to be told their order

A paginated list with no explicit, deliberate ordering can present newly added items on any page at all, not predictably at the top — a bug that looks like "data is missing" when the data is actually just unpredictably placed. Every list a user pages through needs an intentional order, not an assumed one.

Every meaningful action leaves a trace

Anything worth knowing happened — the kind of thing chapter 24's audit trail exists to answer questions about — needs to be recorded at the moment it happens. A missing record is invisible right up until the moment someone goes looking for an entry that was never made, which is always the worst possible time to discover the gap.

Glossary of Terms & Acronyms

Every acronym and term used across this report, in one place — link back here any time a chapter uses one you don't recognize.

Roadmap & Future Directions

Where the platform is headed next — dated deliberately, since a roadmap is the part of any report that goes stale fastest.

• MISP import/export — the ability to import and export rules and bundles directly to and from MISP, closing the loop between Rulezet's detection-rule focus and MISP's indicator focus.
• Vulnerability Lookup integration — linking rules to CIRCL's own Vulnerability Lookup service (vulnerability.circl.lu) for faster, more direct CVE traceability than a plain identifier field.

Both items reflect the same underlying goal: deepening Rulezet's integration with the rest of CIRCL's open tooling ecosystem, rather than growing it as an isolated product.

Screenshot & Media Master Checklist

Every "Screenshot to capture" note from this report, aggregated in chapter order — a one-stop shot list for an actual capture session.

Chapters not listed here (Part I's remaining chapters, and all of Part III) are narrative or conceptual and don't need a screenshot.