Update docs for YAML and Prolog rule engines by wrhalpin · Pull Request #139 · wrhalpin/GNAT

wrhalpin · 2026-04-21T16:38:32Z

CLAUDE.md: repository layout notes YAML/Prolog support, adds [rules-prolog] extras to install examples
README.md: Rule Engine row updated to mention three engines, [rules-prolog] added to install section
CHANGELOG.md: separate entry for YAML+Prolog engines with details
docs/architecture.md: new Analysis Rule Engine subsection with ADR-0054 cross-reference
docs/reference/rule-engine-spec.md: new Section 6 documenting YAML condition DSL and Prolog syntax with examples
docs/explanation/rule-engine.md: new "Three engine implementations" section explaining when to use each
docs/how-to/authoring-rules.md: YAML alternative section with equivalent example

https://claude.ai/code/session_01H5UbjsuiiGya5n1eUCxoaR

- CLAUDE.md: repository layout notes YAML/Prolog support, adds [rules-prolog] extras to install examples - README.md: Rule Engine row updated to mention three engines, [rules-prolog] added to install section - CHANGELOG.md: separate entry for YAML+Prolog engines with details - docs/architecture.md: new Analysis Rule Engine subsection with ADR-0054 cross-reference - docs/reference/rule-engine-spec.md: new Section 6 documenting YAML condition DSL and Prolog syntax with examples - docs/explanation/rule-engine.md: new "Three engine implementations" section explaining when to use each - docs/how-to/authoring-rules.md: YAML alternative section with equivalent example https://claude.ai/code/session_01H5UbjsuiiGya5n1eUCxoaR

Copilot

Pull request overview

Updates GNAT documentation to describe the newly available YAML and Prolog analysis rule-engine implementations alongside the existing Hy engine, including installation extras and rule authoring/spec guidance.

Changes:

Document rule engine selection ([rules] engine = hy|yaml|prolog) and when to use each engine.
Add YAML condition DSL and Prolog rule syntax/spec examples to the reference docs.
Update install guidance and changelog entries to mention the new [rules-prolog] extra.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/reference/rule-engine-spec.md	Adds “Alternative Engines” section with YAML DSL + Prolog syntax and updates error-handling notes.
docs/how-to/authoring-rules.md	Adds a YAML-based authoring alternative example and points to the spec.
docs/explanation/rule-engine.md	Explains three engine implementations and their intended use cases.
docs/architecture.md	Adds an “Analysis Rule Engine” architecture subsection with ADR link.
README.md	Updates capability matrix row and installation section to mention YAML/Prolog engines and extras.
CLAUDE.md	Updates repo layout + installation examples to mention YAML/Prolog engines and extras.
CHANGELOG.md	Adds an entry describing YAML/Prolog engine additions and updated extras/tests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-21T16:44:24Z

+## Three engine implementations
+
+The `[rules] engine` config key selects the rule language:
+
+- **`hy`** (default) — Lisp/S-expression syntax via the `defrule` macro.
+  Most expressive; supports arbitrary Python interop. Best for power
+  users comfortable with functional programming.
+- **`yaml`** — Declarative YAML with a structured condition DSL. No code
+  authoring required; conditions reference the 26 helpers by name with
+  comparison operators (`gte`, `lt`, etc.) and boolean combinators
+  (`all`/`any`/`not`). Lowest barrier to entry.
+- **`prolog`** — SWI-Prolog via pyswip. Best for complex inference
+  chains, backward chaining, and rules with inter-hypothesis
+  dependencies. Hypothesis facts are asserted into the KB before each
+  evaluation and retracted after.


This new section describes a YAML engine, but earlier in this same document (the “Why Hy” section) it still says YAML “was considered but rejected” and “may be added later”. Please update/remove that earlier rationale so the explanation is internally consistent with YAML/Prolog now being supported.

Copilot · 2026-04-21T16:44:25Z

+  Most expressive; supports arbitrary Python interop. Best for power
+  users comfortable with functional programming.
+- **`yaml`** — Declarative YAML with a structured condition DSL. No code
+  authoring required; conditions reference the 26 helpers by name with


The docs hard-code “26 helpers”, but the YAML condition DSL currently exposes 29 helper names (see _HELPERS_NO_CTX + _HELPERS_WITH_CTX in gnat.analysis.rules.yaml_condition). Please update the number (or avoid hard-coding it) to keep docs accurate as helpers evolve.

Suggested change

authoring required; conditions reference the 26 helpers by name with

authoring required; conditions reference available helpers by name with

Copilot · 2026-04-21T16:44:25Z

+- **YAML** — declarative condition DSL referencing 26 helpers by name
+- **Prolog** — SWI-Prolog logic rules via pyswip for complex inference
+
+All engines share the evaluation pipeline: `RuleContext`, `Decision` types, `AuditWriter`,
+`RuleOrchestrator`, and 26 helper functions (evidence, confidence, temporal, status, policy,


This section says YAML references “26 helpers” and later mentions “26 helper functions”, but the current helper surface is 29 (21 no-ctx + 8 ctx-based) per gnat.analysis.rules.yaml_condition / gnat.analysis.rules.helpers.__init__.hy. Please update the count (or remove the fixed number) so architecture docs don’t drift from implementation.

Suggested change

- **YAML** — declarative condition DSL referencing 26 helpers by name

- **Prolog** — SWI-Prolog logic rules via pyswip for complex inference

All engines share the evaluation pipeline: `RuleContext`, `Decision` types, `AuditWriter`,

`RuleOrchestrator`, and 26 helper functions (evidence, confidence, temporal, status, policy,

- **YAML** — declarative condition DSL referencing helper functions by name

- **Prolog** — SWI-Prolog logic rules via pyswip for complex inference

All engines share the evaluation pipeline: `RuleContext`, `Decision` types, `AuditWriter`,

`RuleOrchestrator`, and shared helper functions (evidence, confidence, temporal, status, policy,

Copilot · 2026-04-21T16:44:25Z

 | **HuntGNAT** | STIX pattern → detection rule translation (Sigma, YARA, Suricata, Snort), hunt packages with lifecycle management, ATT&CK coverage matrix, deployment tracking with drift detection, validation scoring |
 | **Telemetry Ingestion** | High-volume sensor ingestion from Kafka topics (honeypot, netflow, IDS alert, DNS log); Redis-backed deduplication; automatic campaign linking of ingested indicators |
-| **Rule Engine** | Hy/Lisp declarative rule engine for automated hypothesis evaluation; 26 analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default |
+| **Rule Engine** | Three-engine hypothesis evaluation (Hy/Lisp, YAML declarative DSL, Prolog logic); 26 analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default |


This row still claims “26 … helper predicates”, but the rule helper surface currently exposes 29 helper names (see _HELPERS_NO_CTX + _HELPERS_WITH_CTX in gnat.analysis.rules.yaml_condition). Please update/remove the hard-coded count to keep the README accurate.

Suggested change

| **Rule Engine** | Three-engine hypothesis evaluation (Hy/Lisp, YAML declarative DSL, Prolog logic); 26 analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default |

| **Rule Engine** | Three-engine hypothesis evaluation (Hy/Lisp, YAML declarative DSL, Prolog logic); analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default |

Copilot · 2026-04-21T16:44:26Z

+  rules without code authoring. Conditions reference the 26 Python
+  helpers by name with comparison operators (`eq`/`neq`/`gt`/`gte`/
+  `lt`/`lte`), boolean combinators (`all`/`any`/`not`), and special
+  args (`{days: N}` for temporal helpers). 4 example YAML rules.


This entry says the YAML engine conditions reference “26 Python helpers”, but the YAML condition DSL currently maps 29 helper names (see _HELPERS_NO_CTX + _HELPERS_WITH_CTX in gnat.analysis.rules.yaml_condition). Please update/remove the fixed number so the changelog description matches the implementation.

Suggested change

rules without code authoring. Conditions reference the 26 Python

helpers by name with comparison operators (`eq`/`neq`/`gt`/`gte`/

`lt`/`lte`), boolean combinators (`all`/`any`/`not`), and special

args (`{days: N}` for temporal helpers). 4 example YAML rules.

rules without code authoring. Conditions reference Python helpers

by name with comparison operators (`eq`/`neq`/`gt`/`gte`/`lt`/`lte`),

boolean combinators (`all`/`any`/`not`), and special args

(`{days: N}` for temporal helpers). 4 example YAML rules.

Copilot · 2026-04-21T16:44:26Z

+
+Hypothesis facts are asserted into the Prolog KB before each evaluation
+and retracted after. Pre-loaded helper predicates in `prolog_helpers.pl`
+mirror the Python helper library.


Saying prolog_helpers.pl “mirror[s] the Python helper library” is a bit misleading: Prolog currently preloads a limited helper set (and asserts only a subset of facts), not a 1:1 parity with all rule helpers. Consider rewording to clarify it mirrors a subset / provides equivalents for common helpers, or enumerate what’s available.

Suggested change

mirror the Python helper library.

provide Prolog equivalents for a common subset of the Python helper library;

they do not currently offer complete 1:1 parity with all rule helpers.

Copilot AI review requested due to automatic review settings April 21, 2026 16:38

wrhalpin merged commit 186464b into main Apr 21, 2026
11 of 19 checks passed

Copilot started reviewing on behalf of wrhalpin April 21, 2026 16:39 View session

wrhalpin deleted the claude/create-gnat-admin-guide-BOSrp branch April 21, 2026 16:43

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for YAML and Prolog rule engines#139

Update docs for YAML and Prolog rule engines#139
wrhalpin merged 1 commit intomainfrom
claude/create-gnat-admin-guide-BOSrp

wrhalpin commented Apr 21, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	authoring required; conditions reference the 26 helpers by name with
	authoring required; conditions reference available helpers by name with

	\| Rule Engine \| Three-engine hypothesis evaluation (Hy/Lisp, YAML declarative DSL, Prolog logic); 26 analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default \|
	\| Rule Engine \| Three-engine hypothesis evaluation (Hy/Lisp, YAML declarative DSL, Prolog logic); analyst-authorable helper predicates; priority-based first-match with audit trail; AI-60 confidence ceiling; feature flag OFF by default \|

	mirror the Python helper library.
	provide Prolog equivalents for a common subset of the Python helper library;
	they do not currently offer complete 1:1 parity with all rule helpers.

Conversation

wrhalpin commented Apr 21, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants