pkglint

A security-focused linter for Arch Linux packages.

pkglint statically analyzes PKGBUILDs and their install scriptlets — without ever sourcing them — and reports findings about source integrity, build hermeticity, code execution, and persistence patterns, condensed into a letter grade per package. It also reproduces makepkg's own build-breaking metadata checks, so a PKGBUILD that would fail to build is caught (and, where the fix is mechanical, rewritten) before you run makepkg. It is built on a real bash AST (mvdan.cc/sh), so the quoting/line-continuation tricks that evade regex-based scanners don't work here.

Built packages (*.pkg.tar.zst and friends) are first-class inputs too: pkglint inspects the archive the way namcap does — ELF hardening (PIE, RELRO, executable stacks, text relocations, RPATH), stripping and placement, dependencies inferred from linked shared libraries and script shebangs (via pacman's local database), packaged .INSTALL scriptlets, and filesystem hygiene from FHS layout to stale python bytecode — while never executing anything from the package (no ldd, no interpreter launches; ELF files are parsed, not loaded).

$ pkglint ~/pkgbuilds/somepkg
somepkg: grade F, 3 finding(s)
  PKGBUILD:16:3: critical [PB304] a network download is piped straight into bash and executed
  PKGBUILD:11:1: error [PB101] remote source "http://..." has no checksum (SKIP): the download is never verified
  PKGBUILD:24:3: error [PB402] sudo escalates privileges during a build; ...

1 package linted: 1 with findings
1 finding(s) fixable with --unsafe-fix

Packages with nothing to report stay out of the way — they are only counted in the closing summary line (--verbose lists them individually). The line after it tallies the findings a rule can rewrite, split by the flag that applies them (--fix for behavior-preserving fixes, --unsafe-fix for the rest). A few fixes also need state the linter does not have — the sources on disk for a digest, an https host that answers — so the tally is what a fix run will attempt, not a promise of that many rewrites.

Install

AUR

yay -S pkglint

PyPi

uv tool install pkglint

Go

go install github.com/jmelahman/pkglint@latest

Usage

pkglint [flags] [path ...]     # paths are package dirs, PKGBUILD files,
                               # or built packages (*.pkg.tar.*) (default: .)

  --format text|json|sarif     # output format (sarif = SARIF 2.1.0, for code scanning)
  --fail-on SEVERITY           # exit 1 at or above: info, warn (default), error, critical, never
  --ignore PB105,PB206         # disable rules
  --color auto|always|never    # colorize text output (auto = only on a terminal; honors NO_COLOR)
  --verbose                    # list packages with no findings individually, not just in the summary
  --rules                      # list every rule with its documentation
  --fix                        # apply safe auto-fixes in place
  --unsafe-fix                 # also apply behavior-changing fixes (implies --fix)
  --diff                       # with --fix/--unsafe-fix/--add-ignores: show changes instead of writing
  --offline                    # with --fix: skip fixes needing network (VCS ref resolution, https probing)
  --add-ignores                # insert ignore directives suppressing every current finding
  --no-inline-ignores          # disregard ignore directives (audit an untrusted package)

Suppress a reviewed, intentional finding inline:

# pkglint: ignore=PB204
go build -o "$pkgname" .

The directive covers its own line and the line below it, in the file it appears in only: an ignore= in an .install scriptlet never affects the PKGBUILD, or vice versa. --add-ignores writes these directives for you, one per finding still reported, so a package can adopt pkglint without first fixing (or while deliberately keeping) what it flags; --diff previews the insertions.

Directives are audited, not just obeyed. A directive that no longer matches a finding on its line or the next — the issue was fixed, or the ID was never a pkglint rule — is itself flagged (PB913, stale-ignore-directive), and --fix deletes it, so a fixed issue cannot leave behind a comment that would silence its return. And when reviewing a package you don't trust, --no-inline-ignores disregards every directive and reports whatever the maintainer suppressed.

Auto-fixing

--fix rewrites what it can and prints every change; --diff previews without writing. Fixes come in two tiers:

Safe fixes preserve behavior or restore a security default; unsafe fixes are mechanical but change what the build does, so review them. The PB902 rename is all-or-nothing: it lands only when every occurrence of the name is accounted for, and it stands down entirely when the variable is exported (a build tool may read it from the environment), when the underscored spelling is taken, or when the file reaches variables in ways no rewrite can follow — run-time naming (eval, ${!x}, declare -n), source, a reference spelled in literal text such as a trap string — because a half-applied rename would leave the PKGBUILD reading a variable nothing sets. An inline # pkglint: ignore= on a finding's line also suppresses its fix. Findings whose remediation isn't a mechanical rewrite print a one-line suggestion instead: updpkgsums for checksums, makepkg --printsrcinfo for a stale .SRCINFO. Those suggestions are computed from what is left after fixing, so a checksum --fix repaired is not then nagged about.

The PB102 fix is the one whose remedy is data rather than syntax, so it applies only where it can prove what it writes. It hashes sources already downloaded into the package directory or $SRCDEST — pkglint never fetches a source, since that would mean issuing requests to URLs read out of an untrusted file — and it emits a digest only after re-computing the existing md5/sha1 from the same read and finding it matches. The sha256sums it adds therefore covers bytes the weak digest already vouched for: replacing them would take an md5 preimage, not the collision that makes md5 unfit for new use. Sources that aren't present, a digest that doesn't match, or an array pkglint can't pair index-for-index all leave the finding standing, and updpkgsums remains the way to close it. The weak array is kept — makepkg checks every array present, so the edit is purely additive.

Commit hook

This repo ships hooks for any runner that understands the .pre-commit-config.yaml convention, so a packaging tree can lint its PKGBUILDs on every commit:

repos:
  - repo: https://github.com/jmelahman/pkglint
    rev: v1.2.0
    hooks:
      - id: pkglint

Three hook ids are available: pkglint builds from source with the Go toolchain, pkglint-system runs whatever pkglint is already on $PATH, and pkglint-fix applies the safe auto-fixes in place (offline by default). Tune any of them with e.g. args: [--ignore, PB105, --fail-on, critical].

Rules

pkglint --rules prints the full documentation for each. A full reference including examples of each rule is available in the documentation.

Relationship to namcap

pkglint covers namcap's rule set — both the PKGBUILD checks and the built-package checks — with a few deliberate differences: nothing from the analyzed package is ever executed (namcap runs ldd -r -u on packaged binaries; pkglint compares dynamic symbol tables instead), findings the lint host cannot actually verify (a library owned by a package that isn't installed here, a declared dependency that isn't installed) are reported informationally instead of as hard errors, and everything is folded into the same graded, suppressible, JSON/SARIF-capable reporting the PKGBUILD rules use. Dependency inference reads pacman's local database directly (/var/lib/pacman/local) and degrades gracefully on non-Arch hosts by skipping just those rules.

Grading: any critical → F, any error → D, 3+ warns → C, 1–2 warns → B, otherwise A.

A grade is a static hygiene score, not a malware verdict — it measures how reviewable and reproducible a PKGBUILD is. A low grade means "worth reviewing", never "malicious", and a high grade is not an endorsement. Static analysis cannot catch a malicious upstream release pinned with a perfectly valid checksum.

License

GPLv3 — see LICENSE.