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 rules (prompt injection, unicode bidi overrides) hard-stop at 100.
Key numbers: 69.1% benign zero-rate, benign p95 = 45 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 with detection and context rules spanning R001-R131, C001-C007, and D001-D004 (R-series identifiers are non-contiguous by design; see the catalog for reserved gaps). R001-R013 detect command patterns (curl pipe bash, base64 decode, sudo in functions, checksum manipulation, unicode bidi overrides, prompt injection). R039-R059 extend that surface (eval of dynamic content, reverse shells, setuid bits, network access in pkgver(), writes outside $pkgdir). R060-R131 inspect build-function behaviour (hidden network fetches, install hooks, untrusted patches, foreign package managers, shell obfuscation density), temporal signals (recency, age, revival), install and maintainer context (GPG removal, env subversion, maintainer takeover), naming (package-name typosquatting), dependencies-set expansion, and metadata (capability density, release cadence). D001-D004 analyse dependency-graph changes (novel dependencies, typosquatted deps, hijack via provides, network makedepends). C001-C007 catch structural anomalies that a single-line pattern cannot express (checksum changed without source change, source URLs swapped without version bump, checksum removed for an unchanged source, command substitution in the source array). 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 | Install via pip, AUR, or from source. |
| 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. |
| 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. |
| Running the Sandbox | Sandbox a PKGBUILD's build and install scripts before approving. |
Reference¶
| Page | What it covers |
|---|---|
| Rules | R001-R131, C001-C007, and D001-D004 with severity, weight, and description. |
| CLI | Full command reference for review, inspect, history, config. |
| Configuration | config.toml, rules.toml, and trusted_domains.toml schema. |
| Report Schema | PackageFact JSON structure. |
| 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 and C-series rule guidelines. |
| Re-baselining | Update benchmarks after scoring changes. |