CPAN-AUDIT(1)

💖 NAME 💖

Bestie, welcome to the CPAN-AUDIT(1) manual page from the User Contributed Perl Documentation — aka the cpan-audit manual. cpan-audit audits CPAN modules. Periodt.

✨ SYNOPSIS ✨

Okay so the whole vibe is:

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
• --freshcheck|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
• --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 show CPANSA-Mojolicious-2018-03

🌸 DESCRIPTION 🌸

cpan-audit is a command line application that checks modules or distributions for known vulnerabilities. It uses its internal database, which is automatically generated from a hand-picked database at https://github.com/briandfoy/cpan-security-advisory.

cpan-audit does not connect to anything — which is exactly why keeping it up to date matters so much. Every update of the internal database is released as a new version. Ensure you have the latest database by updating CPAN::Audit frequently; the database can change daily. You can enable a warning for a possibly out-of-date database by adding --freshcheck, which warns if the database version is older than a month:

% cpan-audit --freshcheck ...
% 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 reported 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.

• 0 — normal operation
• 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 — 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.

---

Byeee bestie! This page comes from perl v5.42.3, dated 2023-08-26, and its manual tag is CPAN-AUDIT(1). Stay patched and hydrated 💜🧚✨