.\" $NetBSD: download-vulnerability-list.1.in,v 1.2 2007/07/16 09:57:57 joerg Exp $
.\"
.\" Copyright (c) 2003 Jeremy C. Reed.  All rights reserved.
.\"
.\" 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Jeremy C. Reed
.\"      for the NetBSD project.
.\" 4. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 07, 2007
.Os
.Dt AUDIT-PACKAGES 1
.Sh NAME
.Nm audit-packages ,
.Nm download-vulnerability-list
.Nd show vulnerabilities in installed packages
.Sh SYNOPSIS
.Nm
.Op Fl desVv
.Op Fl c Ar config_file
.Op Fl g Ar file
.Op Fl h Ar file
.Op Fl K Ar pkg_dbdir
.Op Fl n Ar package
.Op Fl p Ar package
.Op Fl Q Ar varname
.Op Fl t Ar type
.Nm download-vulnerability-list
.Op Fl hs
.Op Fl c Ar config_file
.Sh DESCRIPTION
The
.Nm
program compares the installed packages with the
.Pa pkg-vulnerabilities
file and reports any known security issues to standard output.
This output contains the name and version of the package, the
type of vulnerability, and an URL for further information for each
vulnerable package.
.Pp
The following flags are supported:
.Bl -tag -width Ar
.It Fl d
Attempt to download the vulnerabilities
file using the
.Pa download-vulnerability-list
script before scanning the installed packages for vulnerabilities.
.It Fl e
Check for end-of-life (eol) packages.
.It Fl s
Verify the signature of the current
.Pa pkg-vulnerabilities
file.  The key used to sign the file is available from:
.Pa ftp.netbsd.org/pub/NetBSD/security/PGP/pkgsrc-security@NetBSD.org.asc
.Pp
In order for this to function correctly the above key must be
added to the gpg keyring of the user who runs 
.Pa audit-packages -s 
and/or
.Pa download-vulnerability-list -s .
In addition to this the gpg binary must be installed on your system.
The path to the gpg binary can be set in
.Xr audit-packages.conf 5 .
.Pp
The requirement for GnuPG may go away in the future when a suitable
replacement is implemented.
.It Fl V
Display the version number and exit.
.It Fl v
Be more verbose. Specify multiple -v flags to increase verbosity.
Currently a maximum level of three is supported.
.It Fl c Ar conf_file
Specify a custom
.Ar conf_file
configuration file to use.
.It Fl g Ar file
Compute the SHA512 hash on 
.Ar file .
.It Fl h Ar file
Check the SHA512 hash of a
.Ar file
against the internally stored value.
.It Fl K Ar pkg_dbdir
Use package database directory
.Ar pkg_dbdir .
.It Fl n Ar package
Check only the package
.Ar package
for vulnerabilities.
.It Fl p Ar package
Check only the installed package
.Ar package
for vulnerabilities.
.It Fl Q Ar varname
Display the current value of
.Ar varname
and exit.  Currently supported
.Ar varname
are GPG, PKGVULNDIR and IGNORE_URLS.
.It Fl t Ar type
Only check for the specified
.Ar type
of vulnerability.
.El
.Pp
The
.Nm download-vulnerability-list
program downloads the
.Pa pkg-vulnerabilities
file from
.Pa ftp.NetBSD.org
using
.Xr ftp 1
by default.  This vulnerabilities file documents all known security issues in
pkgsrc packages and is kept up-to-date by the
.Nx
pkgsrc-security team.
.Pp
The following flags are supported:
.Bl -tag -width Ar
.It Fl h
Display program usage.
.It Fl s
Verify the signature of the current
.Pa pkg-vulnerabilities
file.  In order for this to function correctly you will need to add the
pkgsrc Security Team key to your gpg keyring and trust it.  The key is
available from:
.Pa ftp.netbsd.org/pub/NetBSD/security/PGP/pkgsrc-security@NetBSD.org.asc
In addition to this the gpg binary must be installed on your system.
The path to the gpg binary can be set in
.Xr audit-packages.conf 5 .
.It Fl c Ar conf_file
Specify a custom
.Ar conf_file
configuration file to use.
.El
.Pp
By default
.Nm download-vulnerability-list
will download a compressed version of
.Pa pkg-vulnerabilities
from ftp.netbsd.org.  The default file downloaded is compressed using
.Xr gzip 1 .
The compression tool used can set in
.Xr audit-packages.conf 5 .
Currently only
.Xr gzcat 1
and
.Xr bzcat 1
are supported.
.Pp
Each line lists the package and vulnerable versions, the type of exploit,
and an Internet address for further information:
.Bl -item
.It
.Aq package pattern
.Aq type
.Aq url
.El
.Pp
The type of exploit can be any text, although
some common types of exploits listed are:
.Bl -bullet -compact -offset indent
.It
cross-site-html
.It
cross-site-scripting
.It
denial-of-service
.It
eol
.It
file-permissions
.It
local-access
.It
local-code-execution
.It
local-file-read
.It
local-file-removal
.It
local-file-write
.It
local-root-file-view
.It
local-root-shell
.It
local-symlink-race
.It
local-user-file-view
.It
local-user-shell
.It
privacy-leak
.It
remote-code-execution
.It
remote-command-inject
.It
remote-file-creation
.It
remote-file-read
.It
remote-file-view
.It
remote-file-write
.It
remote-key-theft
.It
remote-root-access
.It
remote-root-shell
.It
remote-script-inject
.It
remote-server-admin
.It
remote-use-of-secret
.It
remote-user-access
.It
remote-user-file-view
.It
remote-user-shell
.It
unknown
.It
weak-authentication
.It
weak-encryption
.It
weak-ssl-authentication
.El
.Pp
The type
.Pa eol
implies that the package is no longer maintained by the software vendor but
is provided by the pkgsrc team for your convenience only.  It may contain any
number of the above mentioned vulnerabilities.  Any packages of type eol
are not reported by default. Run
.Nm Fl e
to also report on eol packages.
.Pp
By default, the vulnerabilities file is stored in the
PKG_DBDIR
directory.  On a standard installation this will be set to @pkgdbdir@.
If you have installed pkgsrc on a supported platform this will be what
ever you specifed when bootstrapping pkgsrc i.e. --pkgdbdir <pkgdbdir>.
The path to the
.Pa pkg-vulnerabilities
file can be set in
.Xr audit-packages.conf 5 .
.Sh EXIT STATUS
.Ex -std audit-packages
.Sh FILES
@pkgdbdir@/pkg-vulnerabilities
.Pp
@sysconfdir@/audit-packages.conf
.Sh EXAMPLES
The
.Nm download-vulnerability-list
command can be run via
.Xr cron 8
to update the
.Pa pkg-vulnerabilities
file daily.
And
.Nm
can be run via
.Xr cron 8
(or with
.Nx Ap s
.Pa /etc/security.local
daily security script).
.Pp
The
.Nm download-vulnerability-list
command can be forced to use IPv4 with the following setting in
@sysconfdir@/audit-packages.conf:
.Pp
FETCH_ARGS="-4"
.Pp
The
.Nm download-vulnerability-list
command can be forced to use http to download the
.Pa pkg-vulnerabilities
file with the following setting in
@sysconfdir@/audit-packages.conf:
.Pp
FETCH_PROTO="http"
.Sh SEE ALSO
.Xr pkg_info 1 ,
.Xr audit-packages.conf 5 ,
.Xr mk.conf 5 ,
.Xr pkgsrc 7 ,
.%T "Documentation on the NetBSD Package System"
.Sh HISTORY
The
.Nm
and
.Nm download-vulnerability-list
commands were originally implemented and added to
.Nx Ap s
pkgsrc by
.An Alistair Crooks
on September 19, 2000.  During April 2007
.Nm
was re-written by Adrian Portelli
and support was added for compressed files and checking signatures on downloaded
files.
The original idea came from Roland Dowdeswell and Bill Sommerfeld.