feat: AURSCAN_DISABLE=1 to skip scanning entirely

[HaleTom]

What

Adds AURSCAN_DISABLE=1, a build-hook and plain-scan kill switch. Disabled packages receive an immediate SKIPPED verdict and pass through with exit 0; no directory collection, AUR lookup/snapshot fetch, static rules, or model call runs.

--score is deliberately different: it is an explicit scoring query, ignores AURSCAN_DISABLE, and always produces a real score.

$ AURSCAN_DISABLE=1 aurscan ./pkg
[SKIPPED] pkg - scanning disabled (AURSCAN_DISABLE=1)

Scanning disabled — all packages skipped.

Why

• Re-run an interrupted build without re-scanning unchanged package sources.
• Skip expected hash-only changes without filesystem, network, or model overhead.
• Let users opt out without uninstalling the yay/paru hooks.

How

The early exits are at the actual work boundaries: standalone scans skip before CollectDir, recursive AUR scans skip before RPC/snapshot access, and yay/paru hooks skip before directory collection. pipeline.Run retains a defence-in-depth gate; RunScored bypasses it for --score.

SKIPPED has a dimmed badge, an inline disabled message, and is explicitly allowed through the gates/hooks. It is not a trust verdict, so --score never emits it.

Verification

• make test (go vet ./... and go test ./...) clean
• Disabled standalone empty directory: SKIPPED, exit 0, no collection error
• Disabled paru prebuild empty directory: SKIPPED, exit 0, no collection error
• Disabled yay editor-hook against an uncollectable package root: SKIPPED, exits cleanly and chains to /bin/true
• AURSCAN_DISABLE=1 AURSCAN_RULES_ONLY=1 aurscan --score ./PKGBUILD: real score 80, exit 80

PR template not found, looked in: .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE/*.md.

[manticore-projects]

Greetings @HaleTom.

Is this really needed? How often will one run /w AURSCAN_DISABLE=1 and what is the impact of not having it? If you really want it, we can merge this of course -- but I am rather a fan of keeping things small and simple and this one only seem to complicate things without yielding in much.

Your call, its team effort after all. Best and cheers!

One more concern: how do we harden this against being exploited? I have seen to many "this can never happens" in my life.

[HaleTom]

My use case:

I wanted to remove aurscan as it was greatly slowing down my most common workflow -- update my AUR packages.
In the most common case, I expect to see only checksums changing.

With this shell env disable, I can skip any PKGBUILDs that need a "second look" and then aurscan on the remainder.

Re security: If the current shell is compromised to be able to set variables, then it could also be compromised to run arbitrary commands. Can you be clearer about the threat model where this could be set without a much larger compromise?

[manticore-projects]

Greetings @HaleTom.

Thank you for the explanation, I clearly understand your use-case now. While it may not be relevant for "average Joe", you have contribute so much that your certainly shall get every additional comfort.

If the current shell is compromised to be able to set variables, then it could also be compromised to run arbitrary commands.
Yes, you are not wrong.
Also, when I see AUR packages for update I still check what AURSCAN had to say about even when flagged "ok".

So, ready to merge when you are.

[HaleTom]

I've not actually done a review on this yet (it should have been in my private fork, but my agent got ambitious!)

I'm dogfooding and it tastes good so far.

I hope to review and merge in the next few days.

[HaleTom]

Production-ready bar for this PR

• Disabled build-hook/plain-scan paths avoid collection, static rules, model calls, and AUR RPC/snapshot access.
• Disabled results render SKIPPED, do not prompt, and exit 0.
• --score ignores the switch and retains its numeric-score/255 contract.
• Collection, snapshot, backend, and adverse-verdict paths remain fail-closed when not disabled.
• Standalone, recursive AUR, yay, and paru paths enforce the contract before their respective expensive work.
• Output, README, changelog, and PR body describe the same runtime behaviour.
• Tests prove local no-collection, AUR no-network, no-backend invocation, --score wiring, and progress suppression; make test is green.

Findings

1. Correctness & functional completeness

• No issues found in this area based on the diff and reviewed context.

2. Architecture & boundary integrity

• No issues found in this area based on the diff and reviewed context.

3. Code clarity, clean code & maintainability

• No issues found in this area based on the diff and reviewed context.

4. Comments & code documentation

• No issues found in this area based on the diff and reviewed context.

5. Tests & validation

• No issues found in this area based on the diff and reviewed context. make test passed locally; remote test, vendor, amd64 release, and arm64 release checks passed.

6. Performance

• No issues found in this area based on the diff and reviewed context. Disabled paths now return before CollectDir, AUR RPC, and snapshot retrieval.

7. Operational risk

• No issues found in this area based on the diff and reviewed context. The PR body now matches the implemented switch and --score contracts.

8. Adversarial review

• No issues found in this area based on the diff and reviewed context. The first-pass boundary-placement defect is covered by local no-collection and AUR no-network tests.

What I could not fully verify

• Real yay/paru host-process lifecycle behaviour was not exercised with the external package managers installed; their aurscan hook entrypoints were exercised directly with disabled uncollectable paths.
• A live enabled AUR RPC/snapshot scan was not run; the disabled no-network path is covered by an isolated transport test.

Final verdict

✅ Ready to merge — no blocking issues.

[HaleTom]

Almost ready for final review / merge.

EDIT -- actually, I should manually test the changes that came out of code review... marked as draft again.

[manticore-projects]

Greetings @HaleTom.

Close, but three things before we merge:

1. TrustScore for SKIPPED returns 0, which on our scale means
"maximally malicious" -- the opposite of what the comment claims. And
default: already returns 0, so the case does nothing today except wait for
someone to trip over it. Drop it, or return 255, which we already document as
"scan could not complete".

2. Rank["SKIPPED"] = 0 collides with #68. Right now "never looked" ranks
the same as "looked, it is fine". Harmless while the switch is global, but #68
wants a lookup miss to be SKIPPED with a non-zero exit -- opposite contract,
same verdict string. Let us settle it before merging: I would keep SKIPPED as a
pass-through marker only and give #68 its own verdict.

3. On hardening. Your answer holds for the interactive case, but env vars
are inherited and they persist. One line in ~/.bashrc or
~/.config/environment.d/, written once by the install script of exactly the
package we are meant to catch, and aurscan is blind forever after. Compromise
once, never scanned again. We cannot detect the source, so the answer is
visibility: the banner must print even under progress/quiet suppression, and I
would send it to /dev/tty rather than only stderr, since the hooks can
swallow stderr. Plus a README line that this variable belongs on the command
line, never in an rc file.

Minor: squash the 22 identical commits; add a test that a disabled run neither
reads nor writes the verdict cache.

The five enforcement points I can live with -- forgetting one means we scan,
which is the right way to fail.

Best and cheers!