---
name: "cpan-audit"
section: "1p"
platform: "linux"
package: "libcpan-audit-perl"
version: "20250115.001-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cpan-audit"
---

# cpan-audit(1p)

Audit CPAN modules

## NAME

cpan-audit - Audit CPAN modules

## SYNOPSIS

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:

```
    --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
```

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
```

## DESCRIPTION

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

## LICENSE

Copyright (C) Viacheslav Tykhanovskyi.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.