cpan-audit(1p)

Usage

cpan-audit [command] [options]

Commands:

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

Options:

Examples:

cpan-audit dist Catalyst-Runtime

cpan-audit dist Catalyst-Runtime 7.0

cpan-audit dist Catalyst-Runtime '>5.48'

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

Overview

"cpan-audit" 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>.

"cpan-audit" 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 "--fresh", which warns if the database version is older than a month:

        % cpan-audit --fresh ...
        % cpan-audit -f ...
        % env CPAN_AUDIT_FRESH_DAYS=7 cpan-audit -f ...

Finding dependencies

"cpan-audit" can automatically detect dependencies from the following sources:

`"Carton"`	Parses cpanfile.snapshot file and checks the distribution versions.
`cpanfile`	Parses cpanfile taking into account the required versions.

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.

JSON data

If you request JSON output, the data looks like:

    {
      "meta" : {
          ... meta information ...
      "dists": {
        "<distribution1>": {
          ... distribution info ...
        }
      }
      "errors" : [
        ... list of errors - if any ...
      ]
    }

Meta information

The meta data contains information about the run of "cpan-audit".

    {
      "args": [
        "Mojo::File",
        "Mojo::UserAgent",
        "LWP::UserAgent"
      ],
      "cpan_audit": {
        "version": "20230601.002"
      },
      "total_advisories": 19,
      "command": "modules"
    }

These information are shown:

•

cpan_audit

The version of "cpan_audit" that is used for the audit

•

command

The command of "cpan_audit" that was run

•

args

Arguments for the command

•

total_advisories

Number of found advisories

Distribution information

For each distribution where at least one advisory was found, the JSON looks like:

    "Dist-Name": {
      "queried_modules": [
        "Queried::Namespace"
      ],
      "version": "Any",
      "advisories": [
        {
          ... advisory data as in the audit database ...
        },
          ... more advisories ...
      ]
    },

The advisory data is basically the data from the database. So this depends on what is known for the given advisory.

The distribution information contains:

•

version

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".

•

queried_modules

The actual namespaces queried, either from the command line or another source, such as a cpanfile.

•

advisories

A list of all vulnerabilities found for the version range

Exit values

In prior versions, "cpan-audit" exited with the number of advisories it found. Starting with 1.001, if there are advisories found, "cpan-audit" exits with 64 added to that number. The maximum number of reported advisories is 62, since values over 126 are spoken for.

If the option "--exit-zero" is set "cpan-audit" exits always with a normal exit code (0). This allows you to use "cpan-audit" in build environments together with bash exit mode activated ("set -e").

•: 0 - no advisories found

•: 2 - problem with program invocation, such as bad switches or values

•: 64+n - advisories found. Subtract 64 to get the advisory count, up to 62 advisories

•: 255 - unspecified program error

Releases

3 releases since Debian 11 (Bullseye); the text changed 2 times.

11
12
13