.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\"
.\" @(#)pkg.8
.\"
.Dd March 1, 2022
.Dt PKG-AUDIT 8
.Os
.Sh NAME
.Nm "pkg audit"
.Nd audit installed packages against known vulnerabilities
.Sh SYNOPSIS
.Nm
.Op Fl Fqr
.Op Fl f Ar filename
.Op Fl R Ns Op Ar format
.Op Ar pkg-name
.Pp
.Nm
.Op Cm --{fetch,quiet,recursive}
.Op Fl -file Ar filename
.Op Fl -raw Ns Op Cm = Ns Ar format
.Op Ar pkg-name
.Sh DESCRIPTION
.Nm
checks installed packages for known vulnerabilities and generates reports
including references to security advisories.
Its intended audience is system
administrators and individual users.
.Pp
.Nm
uses a database maintained by port committers and the
.Fx
security team
to check if security advisories for any installed packages exist.
Note that a current ports tree (or any local copy of the ports tree) is not
required for operation.
.Pp
The URL that is used to fetch the database can be overridden via
the VULNXML_SITE config variable.
See
.Xr pkg.conf 5
for more information.
.Pp
If you have a vulnerable package installed, you are advised to update or
deinstall it immediately.
.Pp
Supplying a
.Ar pkg-name
will audit only that package.
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width indent
.It Fl F , Cm --fetch
Fetch the database before checking.
.It Fl f Ar filename , Fl -file Ar filename
Use
.Pa filename
as the local copy of the vulnerability database.
If used in combination with
.Fl F
download the vulnerability database to the named
.Pa filename
before auditing installed ports against it.
.It Fl q , Fl -quiet
Be
.Dq quiet .
Prints only the requested information without
displaying many hints.
.It Fl R Ns Oo Ar format Oc , Fl -raw Ns Op Cm = Ns Ar format
Present the output in one of the following formats:
.Pp
.Bl -bullet -compact
.It
.Cm json
.It
.Cm json-compact
.It
.Cm ucl
.It
.Cm yaml
.El
.Pp
In case
.Ar format
is not provided, it defaults to
.Cm ucl .
.It Fl r , Fl -recursive
Prints packages that depend on vulnerable packages and are thus
potentially vulnerable as well.
.El
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
See
.Xr pkg.conf 5
for further description.
.Bl -tag -width ".Ev NO_DESCRIPTIONS"
.It Ev PKG_DBDIR
.It Ev VULNXML_SITE
.El
.Sh FILES
See
.Xr pkg.conf 5 .
.Sh SEE ALSO
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8
