.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CPAN-AUDIT 1p"
.TH CPAN-AUDIT 1p 2024-05-15 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
cpan\-audit \- Audit CPAN modules
.SH SYNOPSIS
.IX Header "SYNOPSIS"
cpan-audit [command] [options]
.PP
Commands:
.PP
.Vb 6
\&    module         [version range]    audit module with optional version range (all by default)
\&    modules        [version range]    audit module list with optional version range (all by default)
\&    dist|release   [version range]    audit distribution with optional version range (all by default)
\&    deps           [directory]        audit dependencies from the directory (. by default)
\&    installed                         audit all installed modules
\&    show           [advisory id]      show information about specific advisory
.Ve
.PP
Options:
.PP
.Vb 10
\&    \-\-ascii               use ascii output
\&    \-\-fresh|f             check the database for freshness (CPAN::Audit::FreshnessCheck)
\&    \-\-help|h              show the help message and exit
\&    \-\-no\-color            switch off colors
\&    \-\-no\-corelist         ignore modules bundled with perl version
\&    \-\-perl                include perl advisories
\&    \-\-quiet               be quiet (overrules \-\-verbose)
\&    \-\-verbose             be verbose (off if \-\-quiet in effect)
\&    \-\-version             show the version and exit
\&    \-\-exit\-zero           always exit with 0 even if advisories are reported
\&    \-\-exclude <str>       exclude/ignore the specified advisory/cve (multiple)
\&    \-\-exclude\-file <file> read exclude/ignore patterns from file
\&    \-\-json                output JSON
.Ve
.PP
Examples:
.PP
.Vb 3
\&    cpan\-audit dist Catalyst\-Runtime
\&    cpan\-audit dist Catalyst\-Runtime 7.0
\&    cpan\-audit dist Catalyst\-Runtime \*(Aq>5.48\*(Aq
\&
\&    cpan\-audit module Catalyst 7.0
\&
\&    cpan\-audit modules "Catalyst;7.0" "Mojolicious;>8.40,<9.20"
\&
\&    cpan\-audit deps .
\&    cpan\-audit deps /path/to/distribution
\&
\&    cpan\-audit installed
\&    cpan\-audit installed local/
\&    cpan\-audit installed local/ \-\-exclude CVE\-2011\-4116
\&    cpan\-audit installed local/ \-\-exclude CVE\-2011\-4116 \-\-exclude CVE\-2011\-123
\&    cpan\-audit installed local/ \-\-exclude\-file ignored\-cves.txt
\&
\&    cpan\-audit installed \-\-json
\&
\&    cpan\-audit installed \-\-json \-\-exit\-zero
\&
\&    cpan\-audit show CPANSA\-Mojolicious\-2018\-03
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`cpan\-audit\*(C'\fR is a command line application that checks the modules or
distributions for known vulnerabilities. It is using its internal
database that is automatically generated from a hand-picked database
<https://github.com/briandfoy/cpan\-security\-advisory>.
.PP
\&\f(CW\*(C`cpan\-audit\*(C'\fR does not connect to anything, that is why it is
important to keep it up to date. Every update of the internal database
is released as a new version. Ensure that you have the latest database
by updating CPAN::Audit frequently; the database can change daily.
You can use enable a warning for a possibly out-of-date database by
adding \f(CW\*(C`\-\-fresh\*(C'\fR, which warns if the database version is older
than a month:
.PP
.Vb 2
\&        % cpan\-audit \-\-fresh ...
\&        % cpan\-audit \-f ...
\&
\&        % env CPAN_AUDIT_FRESH_DAYS=7 cpan\-audit \-f ...
.Ve
.SS "Finding dependencies"
.IX Subsection "Finding dependencies"
\&\f(CW\*(C`cpan\-audit\*(C'\fR can automatically detect dependencies from the following
sources:
.ie n .IP """Carton""" 4
.el .IP \f(CWCarton\fR 4
.IX Item "Carton"
Parses \fIcpanfile.snapshot\fR file and checks the distribution versions.
.IP \fIcpanfile\fR 4
.IX Item "cpanfile"
Parses \fIcpanfile\fR taking into account the required versions.
.PP
It is assumed that if the required version of the module is less than
a version of a release with a known vulnerability fix, then the module
is considered affected.
.SS "JSON data"
.IX Subsection "JSON data"
If you request JSON output, the data looks like
.PP
.Vb 12
\&    {
\&      "meta" : {
\&          ... meta information ...
\&      "dists": {
\&        "<distribution1>": {
\&          ... distribution info ...
\&        }
\&      }
\&      "errors" : [
\&        ... list of errors \- if any ...
\&      ]
\&    }
.Ve
.PP
\fIMeta information\fR
.IX Subsection "Meta information"
.PP
The meta data contains information about the run of \f(CW\*(C`cpan\-audit\*(C'\fR.
.PP
.Vb 12
\&    {
\&      "args": [
\&        "Mojo::File",
\&        "Mojo::UserAgent",
\&        "LWP::UserAgent"
\&      ],
\&      "cpan_audit": {
\&        "version": "20230601.002"
\&      },
\&      "total_advisories": 19,
\&      "command": "modules"
\&    }
.Ve
.PP
These information are shown
.IP \(bu 4
cpan_audit
.Sp
The version of \f(CW\*(C`cpan_audit\*(C'\fR that is used for the audit
.IP \(bu 4
command
.Sp
The command of \f(CW\*(C`cpan_audit\*(C'\fR that was run
.IP \(bu 4
args
.Sp
Arguments for the command
.IP \(bu 4
total_advisories
.Sp
Number of found advisories
.PP
\fIDistribution information\fR
.IX Subsection "Distribution information"
.PP
For each distribution where at least one advisory was found, the JSON
looks like:
.PP
.Vb 12
\&    "Dist\-Name": {
\&      "queried_modules": [
\&        "Queried::Namespace"
\&      ],
\&      "version": "Any",
\&      "advisories": [
\&        {
\&          ... advisory data as in the audit database ...
\&        },
\&          ... more advisories ...
\&      ]
\&    },
.Ve
.PP
The advisory data is basically the data from the database. So this depends
on what is known for the given advisory.
.PP
The distribution information contains:
.IP \(bu 4
version
.Sp
The version (range) that is checked for advisories. If there's no
version specified, all versions are checked and the version is report
as "Any".
.IP \(bu 4
queried_modules
.Sp
The actual namespaces queried, either from the command line or another
source, such as a \fIcpanfile\fR.
.IP \(bu 4
advisories
.Sp
A list of all vulnerabilities found for the version range
.SS "Exit values"
.IX Subsection "Exit values"
In prior versions, \f(CW\*(C`cpan\-audit\*(C'\fR exited with the number of advisories
it found. Starting with 1.001, if there are advisories found, \f(CW\*(C`cpan\-audit\*(C'\fR
exits with 64 added to that number. The maximum number of reported advisories
is 62, since values over 126 are spoken for.
.PP
If the option \f(CW\*(C`\-\-exit\-zero\*(C'\fR is set \f(CW\*(C`cpan\-audit\*(C'\fR exits always with a normal
exit code (0). This allows to use \f(CW\*(C`cpan\-audit\*(C'\fR in build environments together
with bash exit mode activated (\f(CW\*(C`set \-e\*(C'\fR).
.IP \(bu 4
0 \- no advisories found
.IP \(bu 4
2 \- problem with program invocation, such as bad switches or values
.IP \(bu 4
64+n \- advisories found. Subtract 64 to get the advisory count, up to 62 advisories
.IP \(bu 4
255 \- unspecified program error
.SH LICENSE
.IX Header "LICENSE"
Copyright (C) Viacheslav Tykhanovskyi.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.