Rule Configuration¶
Rules live in two files. rules.toml defines what a regex or structural rule
matches; config.toml controls how the shipped rule set behaves at runtime.
When both set the same field, config.toml wins. The complete key reference,
including every non-rule key, is in the
Configuration Reference.
Two namespaces are distinguished by mechanism rather than by subject. An
R-series rule is a regex defined in ~/.config/trustsight/rules.toml and
loaded at runtime by load_rules() in src/trustsight/config/__init__.py;
you can read it, retune it, or switch it off. An H-series rule is a
heuristic emitted by an analysis module because it needs diff context a
single-line regex cannot see (what changed, what it changed relative to, what
the corpus has seen before), and it has no entry in rules.toml.
The fields below describe an R-series rule. H-series rules carry the same severity, category and weight vocabulary in their findings, but they are not configured through this file.
The rules.toml rule fields¶
Each rule supports these fields:
| Field | Type | Description |
|---|---|---|
id |
string |
Rule identifier. Every id in rules.toml is an R id: R001-R003, R007-R008, R010-R013, R017, R039-R059, R078, R091, R099, R104, R144, and R152. |
name |
string |
Human-readable name. |
pattern |
string |
Python regex applied to the match target. |
severity |
string |
FATAL, CRITICAL, HIGH, MEDIUM, LOW, or INFO. |
category |
string |
The capability the match touched (network_execution, obfuscation, installer, privilege, network_usage, injection, unicode, integrity). This is not the rule's subject: see Rule labels explained. |
match_target |
string |
"resolved" : apply to variable-resolved command strings after tokenization. "raw_line" : apply to raw diff lines after stripping the +/- prefix. |
scope |
list[string] |
(Optional, raw_line only) Restrict matching to line contexts (["function_body"], ["message"], ["other"]) or to a named PKGBUILD function (["pkgver"], ["package"], ["package_foo"]). When absent, matches all lines. |
added_only |
bool |
(Optional, raw_line only) Match only added (+) lines. Raw diff lines include removals, so without this a maintainer deleting a suspicious line raises the score. All raw_line R039+ rules set it. |
experimental |
bool |
(Optional) Skip the rule unless [rules] experimental = true in config.toml. Used for rules whose false-positive rate has not been measured against the benign corpus. |
include_comments |
bool |
(Optional) Also match comment lines, which are filtered out for every other rule. Only for rules whose target is the reader rather than the shell (R012, R013): a commented-out command does not run, but a comment is exactly where an injection or a hidden character lives. |
exclude_if_matches |
list[string] |
(Optional) Defer to a more precise rule: suppress this rule's finding when any listed rule id also matches the same item, with the same match target and enabled. Keeps one finding per operation without making evaluation order part of the rule contract. |
Structural rules¶
A second table in the same file, [[structural]], asks the typed recipe
instead of the raw line. It has its own fields and five match primitives;
the design, the partial-diff rule and the severity cap are in
Recipe-Targeted User Rules.
| Field | Type | Description |
|---|---|---|
id |
string |
Rule identifier following the R-series convention, R###. |
field |
string |
An array name (source, depends, sha256sums) or scalars. plus a scalar name (scalars.install). |
match |
string |
entry_added, entry_removed, host_added, scalar_changed, or renamed. |
pattern |
string |
Python regex searched against the value the primitive selects, never against a raw line. |
severity |
string |
(Optional) Defaults to MEDIUM; FATAL and CRITICAL clamp to HIGH. |
name |
string |
(Optional) Defaults to the id. |
category |
string |
(Optional) Capability touched; defaults to structural. |