Rule Labels Explained¶
A TrustSight finding carries more than one label, and several of the names sound like they mean the same thing. They do not. This page puts the labels side by side, says which ones are independent, and says where each one shows up when you read a report.
The short version¶
| Label | Question it answers | Values | Where it is defined | Independent axis? |
|---|---|---|---|---|
| Rule series (family) | How does the rule reach its conclusion? | R, H, C, D, S, X, T, G, E, I, M, A, U, P, W |
The first letter of the rule ID | Yes |
Subject (RuleCategory) |
What kind of claim does the rule make? | 22 slugs: fetch-and-execution, integrity, temporal, … |
src/trustsight/categories.py |
Yes |
Capability (the category field in rules.toml) |
What capability did this match touch? | network_execution, obfuscation, installer, … |
Per rule in rules.toml |
No, per match |
| Evidence layer | What kind of evidence is the finding? | L1-L8 (plus the optional L9 build lane) |
Derived from the series in src/trustsight/layers.py |
Mostly derived |
| Evidence tier | How is the signal sourced for scoring? | A, B, C, D |
Scoring documentation | No, a scoring concept |
Only the first two are independent classification axes. The rest are either derived (layer), per-match metadata (capability), or scoring vocabulary (tier).
Two real axes: series and subject¶
Series is mechanism. It is the leading letter of the rule ID: R for a
regex, H for a heuristic, C for a structural invariant, D for a graph
walk, X for an evasion check, and so on. It determines what you can tune,
where the detection code lives, and what it costs to replay. The
Rule Series page documents all of them.
Subject is claim. It is the closed RuleCategory set: fetch and
execution, obfuscation, integrity, temporal context, and the rest. It decides
which reference page owns the rule and how the documentation is grouped. The
Rules Overview is the catalog by subject.
The two cross-cut. A temporal finding can come from an H heuristic
(H020) or a T history read (T001). An integrity claim can be a regex
(R024), a heuristic (H001), or a structural invariant (C001). Neither
axis can be computed from the other.
One canonical page per subject¶
A subject now gets one page, not a System page and a Nature page. The category page carries both halves:
- the mechanics: threat context, detection mechanisms, severity, target, scope, per-rule definitions and limitations; and
- the interpretation: what a finding means in the world and what it does not establish.
The split existed so that the system view and the nature view could be read
independently. Keeping both as separate pages made readers maintain a mental
map of which half held an answer, and let the two drift apart. The page still
labels the halves clearly (Detection mechanisms, Individual rules,
Interpretation, Related documentation), so the two readings survive inside
one canonical destination.
Series remains separate because it cross-cuts every subject; see Rule Series.
Layer is evidence kind, derived from series¶
The evidence layer answers a different question: what kind of check produced
this finding? L1 is structural coherence, L3 is a payload signature, L6
is ecosystem memory, L8 is campaign correlation, and so on.
The mapping is mostly a per-series default:
| Series | Default layer |
|---|---|
C, P |
L1 |
W |
L2 |
R, S, U |
L3 |
X, E |
L4 |
H |
L5 |
D, T |
L6 |
I |
L7 |
G |
L8 |
A small override table splits three series where the mechanism diverges from
the evidence: history-backed H rules move to L6, H056 and U007/U008
move to L7, H099/H101/H103 and U009 move to L1, and X026/X027
move to the readability boundary at L2. M has no layer at all because it
fires at its inputs' layer.
Two consequences:
- The numbers are not stages.
L1toL8is a stable display order, not a sequence of barriers an attacker passes. A finding is labelled by the check that caught it, not by every layer that might have caught it. The report saysL4 fired, L3 nonewhen an evasion rule catches what the payload rules missed; that is not a claim that the attacker reachedL4. - The layer is a report and coverage view. A tokenizer gap blinds
L1toL4, a history gap blinds onlyL6, and the report can say that without pretending a series is unread.L9is the optional artifact build lane, outside the staticL1-L8set;L0is the release process, not a rule.
See Assurance Layers and evidence categories for the full model.
Tier is about sourcing, not classification¶
The evidence tier (A-D) says how much external data a scoring signal
needs: A structural and always available, B static priors, C history
that needs a warm corpus, D declared verification that is reported but
never scored. It is not a field every rule is filed under; it describes the
signal's sourcing and confidence. See
Evidence Tiers.
Capability is the category field, not the subject¶
rules.toml has a per-rule field literally named category. That is a
historical name for the capability a match touched
(network_execution, installer, obfuscation). It is fine-grained, set per
rule, and used by H027 to count capability density. It is not the subject
and does not decide which documentation page owns the rule.
A worked example: R001¶
| Label | Value for R001 |
|---|---|
| Series | R (regex) |
| Rule ID | R001 |
| Subject | Fetch and Execution |
| Capability | network_execution |
| Layer | L3 (payload signature, the R default) |
| Tier | A (structural) |
Reading the report:
- The finding line
+25 HIGH R001 …shows the series (R) as part of the ID, plus the rule number and severity. - The
layersobject showsL3fired and carriesR001. - The subject appears only in the documentation; it is not in the finding payload.
- The tier and capability are analysis and scoring vocabulary, not report fields.
Reading a finding¶
A finding is a statement about evidence found in the analysed text, not a verdict on the package. When you read one:
- Read the matched line, not only the rule name. The name is a category of behaviour; the line is what actually matched.
- Read the target and scope on the definition. A
raw_linematch on a message or a comment is evidence about the recipe's text, not about what the build executes. - Check the coverage state in the report. A finding on an incomplete analysis is still a finding, but it does not license conclusions about the parts that were not read.
- Treat a weight-0 finding (
P,W, or a weight-0M) as context, never as risk. It is shown because its absence would be misleading.
What a finding does not establish¶
A firing rule establishes that its condition matched. It does not establish
intent, capability, or that the package is malicious. The common false
positives are shape mismatches: a legitimate build-time download, a defensive
grep, a package manager using --ignore-scripts, or a fork that deliberately
replaces a dependency. Each category page's interpretation section names the
shapes that rule family misreads, and
Tuning False Positives gives the
operational workflow.
Where to go next¶
- Rule Series; the mechanism axis in full
- Rules Overview; the subject catalog
- Rule Interpretation; the interpretation half of each subject
- Assurance Layers; layers, coverage and verdicts
- Reading a Report; the report itself