A lightweight AUR package security scanner that parses PKGBUILDs for malicious patterns before installation.
- PKGBUILD Static Analysis: Parses PKGBUILDs against known malicious patterns, base64 payload heuristics, and IP address sources.
- AUR Metadata Checks: Inspects votes, package age, maintainer status, and out-of-date flags via AUR RPC API.
- Native ALPM Pacman Hook: Hooks directly into pacman pre-transactions (
PreTransaction) to scan packages before installation/upgrade. - Process Tree Search: Inspects parent process (
paru/yay) working directories via/procto scan local PKGBUILDs in-place without disk duplication. - Verification Database & Caching: Tracks package verification status in
/var/lib/pkgscan/database.jsonand logs transactions to/var/log/pkgscan.logto prevent duplicate scans. - PGP Signature Verification: Bypasses hashing for signed packages verified by GPG key signatures.
- Official Package Skipping: Automatically checks package repositories and skips non-AUR official repository packages.
- Suspicion Flag System: Scopes anomalous package behaviour with warning levels and colored terminal danger scoring.
gitbase-develcurlcjson
git clone https://github.com/Vikyek/pkgscan
cd pkgscan
make && sudo make installOr via AUR:
paru -S pkgscanScan a package directly:
pkgscan <package>
pkgscan pkg1 pkg2 pkg3Scan a local PKGBUILD directory:
pkgscan --test /path/to/pkgbuild_dirEnable native ALPM pacman hook:
sudo pkgscan --hook enableCheck hook status:
pkgscan --hook statusDisable hook:
sudo pkgscan --hook disable| Flag | Description |
|---|---|
--hook enable |
Installs ALPM pacman hook to /etc/pacman.d/hooks/pkgscan.hook |
--hook disable |
Removes ALPM pacman hook and cleans legacy shell hooks |
--hook status |
Shows current ALPM and shell hook installation status |
--hook-mode |
Runs pkgscan in pacman hook mode (reads packages from stdin) |
--test <path> |
Scans a local PKGBUILD directory without cloning |
--scan-all |
Forces scanning of packages regardless of database cache |
--force-hash |
Always verifies SHA256 hashes even if PGP signature matches |
--database <path> |
Specifies custom database JSON path (default: /var/lib/pkgscan/database.json) |
--log <path> |
Specifies custom transaction log path (default: /var/log/pkgscan.log) |
--help |
Displays help message and CLI usage |
When scanning an AUR package, pkgscan:
- Checks whether the target is an official Arch repository package (via
pacman -Si) and skips scanning if it is not an AUR package. - Checks the local JSON database (
/var/lib/pkgscan/database.json) and GPG signatures/SHA256 hashes to skip already verified packages. - Locates local PKGBUILD sources in parent process (
paru/yay) working directories via/procor local caches to inspect in-place, falling back to cloning from AUR to/tmpif necessary. - Scores PKGBUILD contents against weighted pattern keywords in
keywords.h, checks for obfuscated base64 payloads, and detects IP addresses in source URLs. - Queries the AUR RPC v5 API for package metadata and flags suspicious conditions (e.g. low vote count, newly submitted packages, or recent edits after long inactivity).
- Prompts for user confirmation before proceeding with installation and logs the result to
/var/log/pkgscan.log.
Keywords are defined in keywords.h and can be customized before compiling.
| Level | Score | Description |
|---|---|---|
| Low | 0 | No suspicious patterns found |
| Medium | 1-15 | Some patterns detected |
| High | 16-35 | Suspicious patterns, review advised |
| Critical | 35+ | Multiple serious patterns detected |
- Static analysis only, so obfuscated or encoded payloads may bypass detection
- Keyword list is open source and can be studied by malicious package authors
- Metadata flags are heuristics, not guarantees
- Not a substitute for manual PKGBUILD review on high risk packages
- Sophisticated attacks are outside the scope of this tool
Pull requests are welcome to help improve detection patterns or features. To adjust detection rules, edit keywords.h and recompile.
pkgscan is authored and maintained by Vikyek as an independent open-source project. Everything is 100% open-source, telemetry-free, and public.
Target: 2,710 PLN / ~$680 USD per month (
630 PLN / week) — Rent & Essential Utilities
Covering basic living essentials directly unlocks dedicated, sustainable full-time independent open-source engineering across Arch Linux utilities, developer tools, and AI middleware free from corporate telemetry, ads, or paywalls.
If this project saves you time, optimizes your setup, or accelerates your workflow, consider supporting ongoing work:
- GitHub Sponsors: github.com/sponsors/Vikyek (Monthly tiers and one-time tips)
- Liberapay: liberapay.com/Vikyek (0% platform fee recurrent patronage in EUR/USD/PLN)
- Direct Stripe Profile: profile.stripe.com/@vikyek (Direct one-time tips & sponsorship)
Every contribution—monthly or one-time—directly supports active maintenance, hardware testbeds, and new feature development!
