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

Packages with nothing to report stay out of the way — they are only counted in the closing summary line (--verbose lists them individually).

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 (e.g. VCS ref resolution)
  --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. An inline # pkglint: ignore= on a finding's line also suppresses its fix. Findings whose remediation isn't a mechanical rewrite (checksums, .SRCINFO) print a one-line suggestion (updpkgsums, makepkg --printsrcinfo) instead.

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.