docs: changelog and readme for v0.8.0

Author: manticore-projects

CHANGELOG.md

@@ -7,7 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-24
+
 ### Added
+- **Install-scriptlet scanning — the `xsnow` / `xsnow-bin` worm class.** A
+  pacman install scriptlet is never executed by makepkg: it is embedded in the
+  built package as `.INSTALL` and run by libalpm **as root on the installing
+  machine**, on every install and every upgrade, with no `$pkgdir`. Nothing in
+  the PKGBUILD sources it — the only link is a filename string in `install=`. A
+  scanner that reviews the PKGBUILD alone can therefore report a package clean
+  with complete syntactic honesty while never having seen its payload. This is
+  exactly what the hostile `xsnow` package exploited: a dot-prefixed
+  `.xsnow.install` that fetched a binary over Tor into `/usr/local/bin`,
+  persisted it as a systemd unit, harvested `~/.ssh`, `/root/.ssh` and
+  `/home/*/.ssh`, and pushed **itself** back to every AUR repository the
+  victim's key could reach — so each new victim's PKGBUILD looked as clean as
+  the last one's.
+- **`REF-001`…`REF-004` — reference resolution.** Every file the package names
+  (`install=`, local `source=()` entries) is resolved against the file set the
+  scanner actually received, with iterative variable substitution so
+  `install=$pkgname.install` resolves through `pkgname=jdk${java_}-graalvm-bin`.
+  A referenced file that was **not supplied** means the scan is *incomplete*,
+  which is a different claim from "the package is clean" and now blocks an `OK`
+  verdict (`REF-001`, `REF-003`). A dot-prefixed `install=` is concealment —
+  pacman resolves it, `ls` and dotfile-skipping tools do not — and is **fatal on
+  its own** (`REF-002`). `REF-004` reports a local source file that is genuinely
+  absent.
+- **Eleven rules for the worm family.** `PERSIST-007` (remote payload into a
+  system binary directory), `PERSIST-008` (`chmod +x` on a system path),
+  `PERSIST-009` (scriptlet writes a systemd unit), `PERSIST-010` (timer
+  directives in a scriptlet), `PKGMGR-001` (`pacman -S` from a scriptlet),
+  `EXFIL-004` (`.onion` C2), `EXFIL-005` (SOCKS proxying), `CRED-004`
+  (root/all-user SSH enumeration), `CRED-005` (`~/.ssh` moved or symlinked
+  away), `WORM-001` (script copies itself), `WORM-002`/`WORM-003` (AUR push
+  credentials, `git push`), and `HOOK-001` (scriptlet detaches into the
+  background). The install-scoped rules only fire in files pacman actually
+  executes; `WORM-002`/`WORM-003` are further scoped away from maintainer
+  tooling (`release`, `update.sh`) that makepkg never runs.
+- **Redirection targets in the deobfuscated command view.** The payload of a
+  heredoc-written systemd unit lives in a `Redirect`, not in the command's
+  arguments, so `cat <<EOF >/etc/systemd/system/X.service` was previously
+  invisible to every command-scoped rule. Redirect operators and targets are now
+  rendered, along with a background (`&`) flag.
+- **Trusted file manifest in the auditor prompt.** The model is told exactly
+  which files it received, so it can distinguish "this package has no install
+  scriptlet" from "I was not given the install scriptlet" — a distinction the
+  PKGBUILD alone cannot express.
+
+### Changed
+- **Static findings are folded into the checklist rather than bolted on.**
+  Deterministic rule hits are converted to first-class `Check` entries and run
+  through the same `deriveVerdict` as the model's own answers, so one derivation
+  produces the verdict, per-finding severities, confidence and summary. The
+  model may always **escalate**; it has no mechanism to **clear** a finding in
+  the non-overridable set. This is a floor, not an override: an ordinary
+  critical hit in a PKGBUILD is still the model's call, and
+  `AURSCAN_STRICT_FLOOR=1` widens it for those who want it.
+- **Collectors no longer overstate their coverage.** `maxTotalBytes` raised from
+  240 KB to 512 KB (`openssl-1.1` ships 41 patches totalling 382 KB, whose tail
+  was silently dropped), and a file the collector skips — oversized, non-text,
+  or past the aggregate cap — is now **recorded** rather than discarded. It
+  appears in the file set marked as omitted, so reference resolution does not
+  report the scanner's own truncation as a missing source, and the prompt lists
+  it as *not reviewed* instead of asserting the supplied set is exhaustive.
+- **Verdict-cache version bumped to `v3`** for the new checklist ids
+  (`install_scriptlet_worm`, `hidden_install_scriptlet`,
+  `scriptlet_system_takeover`, `incomplete_scan`).
+
+### Fixed
+
+The rule catalog was calibrated against **158 real AUR packages** cloned from
+upstream. The unit suite was green at every stage below, including the stages
+where a rule was wrong on every real package it touched. Across the corpus,
+**53 MALICIOUS verdicts and ~120 findings became 1 and 20**, with no known false
+positives remaining. The recurring defect was rules reporting the *scanner's*
+confusion as a property of the package.
+
+- **`PERSIST-002` matched a bare `.timer` in any file** — a `REUSE.toml` listing
+  `"*.timer"` among its licence globs read as systemd persistence, 51 hits, all
+  wrong. It now requires an *action* (`systemctl enable|start … .timer`, or a
+  redirection into a systemd directory) and is scoped to shell content.
+  Installing a timer unit into `$pkgdir` is normal packaging and no longer
+  fires. `PERSIST-001`/`PERSIST-004` gained the same file scoping.
+- **`PRIV-001` flagged `optdepends = sudo:` in `.SRCINFO`** — a dependency
+  *declaration*, not an invocation. Command rules are now scoped to shell files:
+  a non-shell file fails to parse and previously fell back to raw-text matching.
+- **`DLE-001`/`DLE-002` matched `wget … | sha256sum`**, because `sh` matched the
+  head of `sha256sum`. Both codes are non-overridable, so a missing word
+  boundary would have made an ordinary checksum helper permanently unpassable.
+- **`CHK-005` rewritten from a regex to positional pairing.** `SKIP` is correct
+  and universal for a VCS checkout and for a detached signature verified by gpg.
+  The crux was **brace expansion**: `source=(url{,.sig})` is one array token but
+  two sources, so every checksum after it was off by one and the trailing `SKIP`
+  — belonging to the signature — was attributed to whatever came next. Now also
+  covers `b2sums`/`sha512sums`/etc. (previously `sha256sums` only) and
+  arch-suffixed arrays, and exempts local files, whose integrity is the
+  repository's. 13 hits became 2, both genuine.
+- **Source-array parsing unified.** Quote stripping (never truncation — the
+  `name::url` separator routinely sits outside the quotes), brace expansion,
+  `$( )`-aware tokenisation (a substitution may contain spaces) and
+  local-vs-remote classification (the scheme is often inside `$url`) are now done
+  once and shared, after four separate bugs lived in the same decision.
+- **Host classification split into three questions.** Canonical distribution
+  points and language registries (`ftp.gnu.org`, `files.pythonhosted.org`,
+  `registry.npmjs.org`, Maven Central, …) no longer trip a `url=` mismatch — a
+  project's homepage is never its distribution host. GitHub's raw and object
+  origins inherit `github.com`. Community asset hosts (`opendesktop.org`,
+  `pling.com`, `store.kde.org`, …) are classified as **generic** rather than
+  allowlisted: the upload path is chosen by whoever uploads, so the host
+  establishes nothing about who produced the file.
+
 - **Verdict reproducibility (discussion #56).** An identical re-scan no longer
   risks flipping the verdict. Two changes: sampling **temperature now defaults to
   0** (greedy) on the `api` and `openai` backends — the `api` path previously
@@ -415,7 +524,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Makefile, installer with update/uninstall, AUR `PKGBUILD`, and CI that
   attaches UPX-packed release artifacts on tags.
 
-[Unreleased]: https://github.com/manticore-projects/aurscan/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/manticore-projects/aurscan/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/manticore-projects/aurscan/compare/v0.7.1...v0.8.0
 [0.7.1]: https://github.com/manticore-projects/aurscan/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/manticore-projects/aurscan/compare/v0.6.4...v0.7.0
 [0.2.2]: https://github.com/manticore-projects/aurscan/compare/v0.2.1...v0.2.2

README.md

@@ -64,7 +64,9 @@ In July 2025 the AUR packages `firefox-patch-bin`, `librewolf-fix-bin`, and `zen
 
 Then in June 2026 the **Atomic Arch** campaign made the point at scale. Attackers adopted **1,500+ orphaned** AUR packages and added a post-install step running `npm install atomic-lockfile`, later `bun install js-digest`, which pulled a Rust credential stealer and, when built as root, an **eBPF rootkit**. Some used git commit forgery to impersonate a trusted maintainer. The package name and history were unchanged. Only the build instructions, and who wrote them, had quietly changed.
 
-aurscan is built for exactly this: the unfamiliar trick, not just the one you happen to know. Its prompt and static rules encode both of the signatures above, and the model is there to catch the next one nobody has seen yet.
+Then in August 2026 `xsnow` and `xsnow-bin` moved the payload out of the PKGBUILD entirely. The PKGBUILD was clean. The attack lived in a dot-prefixed **`.xsnow.install`** scriptlet, which `makepkg` never executes — it is embedded in the built package as `.INSTALL` and run by pacman **as root on the installing machine**, on every install and every upgrade. It fetched a binary over Tor into `/usr/local/bin`, persisted it as a systemd unit, harvested `~/.ssh`, `/root/.ssh` and `/home/*/.ssh`, and then pushed **itself** into every AUR repository the victim's key could reach — so each new victim's PKGBUILD looked exactly as clean as the last one's. The only link between the PKGBUILD and the payload was a filename string in `install=`, and the leading dot hid the file from `ls` and from any tool that skips dotfiles.
+
+aurscan is built for exactly this: the unfamiliar trick, not just the one you happen to know. Its prompt and static rules encode all three of the signatures above, and the model is there to catch the next one nobody has seen yet.
 
 ## Install
 
@@ -419,6 +421,7 @@ aurscan --debug --score ./PKGBUILD
 | `AURSCAN_TIMEOUT` | `180` | per-request budget in **seconds**; raise it for slow CPU-only models |
 | `AURSCAN_INSTRUCTIONS` | — | path to extra auditor instructions (appended) |
 | `AURSCAN_RULES_ONLY` | — | `1` = static rules only, never call a model |
+| `AURSCAN_STRICT_FLOOR` | — | `1` = any critical static hit prevents an `OK` verdict, not only the non-overridable ones |
 | `AURSCAN_NO_CACHE` | — | `1` = disable the verdict cache (no read, no write) |
 | `AURSCAN_CACHE_DIR` | `$XDG_CACHE_HOME/aurscan/verdicts` | verdict-cache location |
 | `AURSCAN_CACHE_TTL` | `30` | verdict-cache lifetime in **days**; `0` = never expire |
@@ -457,6 +460,10 @@ aurscan --rules-only <pkgname|./dir>     # or set AURSCAN_RULES_ONLY=1
 
 **Quote-aware — obfuscation does not slip past.** The command, flag and path rules do not match raw text. The `PKGBUILD` and `.install` scripts are parsed with a real shell parser ([`mvdan.cc/sh`](https://github.com/mvdan/sh), pure-Go, vendored, **never executed**) and the rules run against the *deobfuscated* command view. So split-token tricks like `s"ud"o`, `cu""rl … | sh`, `su$'\x64'o` and `${IFS:0:0}sudo` are caught as the commands they actually run, while a `sudo` printed inside an `echo` instruction is correctly ignored instead of false-flagging. The splicing itself is also reported as **`OBF-004` (critical)** — a PKGBUILD has no honest reason to disguise a command name, so any attempt is treated as a strong signal in its own right, even when the disguised command is otherwise harmless.
 
+**Install scriptlets are scanned, and a missing one is not a pass.** A `.install` scriptlet is where a package gets root on *your* machine, and it is reachable from the PKGBUILD only through a filename string in `install=`. aurscan resolves every referenced file — `install=`, local `source=()` entries — against the files it actually received, substituting PKGBUILD variables to do it. If a referenced file was **not supplied**, the scan is *incomplete*, which is a different claim from "clean": an `OK` verdict is no longer possible (**`REF-001`/`REF-003`**). A dot-prefixed `install=` is treated as concealment and is fatal on its own (**`REF-002`**). Within a scriptlet, rules cover the root-level behaviour that has no legitimate form there: a remote payload dropped into a system binary directory and made executable, a systemd unit written and enabled, `pacman` pulling in the payload's own dependencies, `.onion` C2 and SOCKS proxying, SSH material read or relocated, AUR push credentials used, and a script that copies **itself** — the signature of a worm, full stop.
+
+**A rule hit is a fact; a model verdict is a judgement.** Deterministic findings are folded into the auditor's checklist as first-class checks and derived through the same code path as the model's own answers, so one derivation produces the verdict, severities, confidence and summary. The model can always **escalate**. It has no mechanism to **clear** a finding in the non-overridable set — which is how a scanner ends up reporting "97% confidence, no concerns" on a package whose payload it never read. This is deliberately a narrow floor: an ordinary critical hit in a PKGBUILD is still the model's call to dismiss, and `AURSCAN_STRICT_FLOOR=1` widens it if you would rather it were not.
+
 **Build-cache hygiene — your `$HOME` should stay yours.** A `go build`/`go install` without a confined `GOPATH`/`GOMODCACHE` writes the module cache to `~/go/pkg/mod` (read-only files, unless `-modcacherw`); a `cargo build`/`cargo fetch` without `CARGO_HOME` writes registry and git caches to `~/.cargo`. Not malicious — failure by omission — but a scanner that promises "nothing ran yet" should tell you the build will write outside `$srcdir`. Reported as **`BLD-001`/`BLD-002` (info)**. Suppressed when the PKGBUILD exports or inline-prefixes the variable (an export in `prepare()` covers `build()` — same makepkg process) or, for Go, builds vendored with `-mod=vendor`. These checks use the same command-position-aware view: an echo'd `go build` does not fire.
 
 ## Reproducibility