TrustSight¶
Audits AUR PKGBUILDs before you update: catches careless malice and structural risk, and tells you what it can't verify.
TrustSight is an instrument, not a judge. It reports evidence - and the absence of evidence - and never substitutes its report for your decision. Absence of alerts is not a promise of safety. The security model states the boundaries behind that promise, and how each one is enforced.
Ready to get started? Head over to the Tutorial for installation and your first review.
What a run produces¶
Every review is a deterministic, structured evidence report, computed locally from the bytes on disk. Findings come first:
- Findings - each is a named rule with the file, side and line it matched, and a plain-English description of what it saw.
- The change summary - what the update altered: modified files, source and checksum array moves, dependency additions, and maintainer or version changes.
- Coverage gaps - what the run could not fully assess, stated outright so an incomplete analysis is never mistaken for a clean one.
- A template verdict - the findings rendered into a review direction. It describes what fired; it never grants permission to skip review.
The default output is evidence, not a verdict, and nothing it prints is a promise of safety. The evidence is what you decide on. See How TrustSight Works for the full pipeline and the security model for what a result does and does not claim.
Rules Reference
TrustSight ships 254 documented detection rules across eleven families: 37 R-series detection rules, 104 H-series heuristics, 32 C-series structural rules, five D-series dependency rules, eight S-series sabotage rules, 34 X-series crossfire rules, six M-series meta rules, three E-series entropy rules, five T-series temporal rules, and ten G-series correlation rules, and ten U-series rules (six manifest, four upstream-release). The identifier space is intentionally non-contiguous, so a range is not a count; the catalog is authoritative. Two further families are reported but never weighted: declared-practice findings P001-P009 (eight findings; P004 is skipped) and unverifiable findings W001-W012. The optional L9 build lane adds eight artifact rules A001-A008, reported outside the heuristic when enabled. Each rule has a severity, match target, and scope that determine how it fires and what it reports.
Assurance layers¶
Every rule also carries an evidence layer, L1-L8, naming the kind of
evidence a finding is. Layers are not ordered barriers: a finding at L4 does
not mean L1-L3 were passed, and a layer that stayed silent is not proof of
safety.
| Layer | The question its evidence answers | Rule families |
|---|---|---|
L1 Structural coherence |
Does the change hang together as an honest edit? | C, M |
L2 Readability |
Was anything hidden from the reader? | W, and the refusal rules X026/X027 |
L3 Payload signature |
Does it do a known-bad thing? | R, S |
L4 Evasion shape |
Was it written to defeat reading? | X, E |
L5 Behavioral suspicion |
Does the package's story make sense? | H |
L6 Ecosystem memory |
Has the ecosystem seen this before? | D, T |
L7 Known indicators |
Is it on the list? | I |
L8 Campaign correlation |
Do other packages tell the same story? | G |
The report keeps detection and coverage independent - L3 fired records the
check that matched, L1 passed records that a check was read in full and stayed
silent, and L8 not_applicable records a check that could not run - and the
optional L9 build lane inspects the built package rather than the diff.
How TrustSight groups security evidence covers the labels,
the coverage states, and a worked report example.
Tutorial¶
| Page | What it covers |
|---|---|
| Installation | Build the repository's PKGBUILD with makepkg. |
| Quickstart | Run your first review, read the output table, understand the verdicts. |
| Reading a Report | Deep dive into the findings, evidence tiers, rule firings, and novelty context. |
Explanation¶
| Page | What it covers |
|---|---|
| How TrustSight Works | Full pipeline: parse, analyse, classify, translate. |
| Assurance Layers | How rules group into L1-L8 evidence categories, detection vs coverage, and what a layer label does and does not mean. |
| Security Model | What TrustSight guarantees while reading hostile input, why every result is deterministic and reproducible, what a verdict claims, and how each invariant is enforced. |
| Cold Start and Maturity | Why novelty is meaningless on run one; maturity gating. |
| Corpus and Priors | AUR-wide snapshot, global priors, local novelty weighting. |
| Fire Rates | Per-rule false-positive rates on the benign corpus. |
| What TrustSight Cannot See | The reasoned ceiling of the tool. |
| Why Static Analysis | SAST by design, customization surface. |
| Benchmarks and Methodology | Per-class separation, CI gates, reproducible evaluation. |
| Recipe-Targeted User Rules | A second rule kind that matches typed recipe structure, its five primitives, and the HIGH cap. |
| Cross-File Consistency | How the recipe is compared against .SRCINFO, the committed tree and shipped hooks. |
| The Typed Core | Why the diff and the PKGBUILD are each read once, so every finding cites the real file, side and line and unreadable structure is reported, never guessed. |
Guides¶
| Guide | When to use it |
|---|---|
| Auditing Before Update | Everyday workflow: scan AUR packages before yay -Syu. |
| Using in CI | Gate package installs in CI/CD on the JSON report. |
| Acting on a Flag | A package flagged above the review bar or returned INCONCLUSIVE - next steps. |
| Configuring Rules and Weights | Edit rules.toml or config.toml to match your threat model. |
| Tuning False Positives | A rule is firing too often on your packages - identify and fix it. |
Reference¶
| Page | What it covers |
|---|---|
| Rules | Complete R/H/C/D/S/X catalog with severity, weight, and description. |
| Rule Nature (by series) | How each series detects: Regex, Heuristic, Check, Dependency, Sabotage, Crossfire, Practice, and Warning. |
| Rule Nature (by category) | Where each category's rules come from and what a finding means in the world. |
| CLI | Full command reference for review, inspect, history, config. |
| Configuration | config.toml and its sibling rule, host, pattern, naming, threshold, and domain files. |
| Report Schema | Stored PackageFact and CLI/API report JSON shapes. |
| Glossary | The vocabulary: rule family, subject, evidence category, evidence tier, detection, coverage, boundary. |
| Evidence Tiers | A/B/C/D evidence taxonomy with maturity gating. |
| Exit Codes | 0 (analysis completed), 2 (error), and why a flag is not an exit code. |
Contributing¶
| Page | What it covers |
|---|---|
| Development Setup | Set up a local dev environment. |
| Writing a Rule | R-series regex, H-series heuristic and C-series rule guidelines. |
| Re-baselining | Update benchmarks after detection changes. |