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 Getting Started guide for installation and your first review.
How scoring works¶
TrustSight computes a deterministic score from 0 to 100 for every AUR package update. The score is calculated entirely in Python from structured data: rule firings, URL classification, novelty tracking, and verification metadata.
The scoring system is organized into four evidence tiers:
| Tier | Name | What it measures |
|---|---|---|
| A | Structural | Pattern-matched rules against PKGBUILD commands (curl pipe bash, checksum disabled, sudo in functions) |
| B | Priors/Context | Domain reputation of new source URLs (trusted forge, official, unknown, homograph) |
| C | History/Novelty | First-seen URLs and maintainers, scaled by observation count |
| D | Verification | Declared integrity metadata (checksums, PGP keys, GPG verify) reported at weight 0, never scored |
A package with checksums, a trusted forge source, and no rule firings scores 0. A package with curl | bash on an unknown domain with no checksum scores 75+. FATAL rule findings (prompt injection or Unicode deception) hard-stop at 100. Confirmed IOC matches are reported separately with their curator attribution; they do not change the score or risk band.
Key numbers: 68.4% benign zero-rate, benign p95 = 35 against malicious p5 = 60 on the 3,246-diff locked corpus, 100% CRITICAL recall. The novelty seed recognises 86% of source URLs in a package's most recent update.
See How TrustSight Works for the full pipeline explanation and Rules Reference for the complete rule catalog.
Rules Reference
TrustSight ships 179 documented scoring rules across six families: 36 R-series detection rules, 97 H-series heuristics, nine C-series structural rules, four D-series dependency rules, eight S-series sabotage rules, and 25 X-series crossfire rules. The identifier space is intentionally non-contiguous, so a range is not a count; the catalog is authoritative. Two further families report without scoring: declared-practice findings P001-P008 (seven findings; P004 is skipped) and unverifiable findings W001-W006 are weight zero and never move a number. Each rule has a severity, weight, match target, and scope that determine how it fires and what it contributes to the score.
Getting started¶
| 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 score breakdown, evidence tiers, rule firings, and novelty context. |
Explanation¶
| Page | What it covers |
|---|---|
| How TrustSight Works | Full pipeline: parse, analyze, score, classify, translate. |
| Security Model | What TrustSight guarantees while reading hostile input, why the score is deterministic and reproducible, what a verdict claims, and how each invariant is enforced. |
| Scoring Philosophy | Evidence tiers, why verification is declared rather than scored, corpus-derived weights, rule design decisions. |
| 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. |
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 scored above 20 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 | How each series detects: Regex, Heuristic, Check, Dependency, Sabotage, Crossfire, Practice, and Warning. |
| 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. |
| Evidence Tiers | A/B/C/D 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 scoring changes. |