@@ -7,7 +7,7 @@ use IO::Interactive qw(is_interactive);
7
7
8
8
use CPAN::Audit;
9
9
10
- our $VERSION = " 1.501 " ;
10
+ our $VERSION = " 1.502 " ;
11
11
12
12
__PACKAGE__ -> run( @ARGV ) unless caller ;
13
13
@@ -216,6 +216,208 @@ sub usage {
216
216
my ( $class , $exit_code ) = @_ ;
217
217
no warnings qw( once) ;
218
218
Pod::Usage::pod2usage( -input => $FindBin::Bin . " /" . $FindBin::Script );
219
+ print <<'HERE' ;
220
+ NAME
221
+ cpan-audit - Audit CPAN modules
222
+
223
+ SYNOPSIS
224
+ cpan-audit [command] [options]
225
+
226
+ Commands:
227
+
228
+ module [version range] audit module with optional version range (all by default)
229
+ modules [version range] audit module list with optional version range (all by default)
230
+ dist|release [version range] audit distribution with optional version range (all by default)
231
+ deps [directory] audit dependencies from the directory (. by default)
232
+ installed audit all installed modules
233
+ show [advisory id] show information about specific advisory
234
+
235
+ Options:
236
+
237
+ --ascii use ascii output
238
+ --fresh|f check the database for freshness (CPAN::Audit::FreshnessCheck)
239
+ --help|h show the help message and exit
240
+ --no-color switch off colors
241
+ --no-corelist ignore modules bundled with perl version
242
+ --perl include perl advisories
243
+ --quiet be quiet (overrules --verbose)
244
+ --verbose be verbose (off if --quiet in effect)
245
+ --version show the version and exit
246
+ --exit-zero always exit with 0 even if advisories are reported
247
+ --exclude <str> exclude/ignore the specified advisory/cve (multiple)
248
+ --exclude-file <file> read exclude/ignore patterns from file
249
+ --json output JSON
250
+
251
+ Examples:
252
+
253
+ cpan-audit dist Catalyst-Runtime
254
+ cpan-audit dist Catalyst-Runtime 7.0
255
+ cpan-audit dist Catalyst-Runtime '>5.48'
256
+
257
+ cpan-audit module Catalyst 7.0
258
+
259
+ cpan-audit modules "Catalyst;7.0" "Mojolicious;>8.40,<9.20"
260
+
261
+ cpan-audit deps .
262
+ cpan-audit deps /path/to/distribution
263
+
264
+ cpan-audit installed
265
+ cpan-audit installed local/
266
+ cpan-audit installed local/ --exclude CVE-2011-4116
267
+ cpan-audit installed local/ --exclude CVE-2011-4116 --exclude CVE-2011-123
268
+ cpan-audit installed local/ --exclude-file ignored-cves.txt
269
+
270
+ cpan-audit installed --json
271
+
272
+ cpan-audit installed --json --exit-zero
273
+
274
+ cpan-audit show CPANSA-Mojolicious-2018-03
275
+
276
+ DESCRIPTION
277
+ "cpan-audit" is a command line application that checks the modules or
278
+ distributions for known vulnerabilities. It is using its internal
279
+ database that is automatically generated from a hand-picked database
280
+ <https://github.com/briandfoy/cpan-security-advisory>.
281
+
282
+ "cpan-audit" does not connect to anything, that is why it is important
283
+ to keep it up to date. Every update of the internal database is released
284
+ as a new version. Ensure that you have the latest database by updating
285
+ CPAN::Audit frequently; the database can change daily. You can use
286
+ enable a warning for a possibly out-of-date database by adding
287
+ "--fresh", which warns if the database version is older than a month:
288
+
289
+ % cpan-audit --fresh ...
290
+ % cpan-audit -f ...
291
+
292
+ % env CPAN_AUDIT_FRESH_DAYS=7 cpan-audit -f ...
293
+
294
+ Finding dependencies
295
+ "cpan-audit" can automatically detect dependencies from the following
296
+ sources:
297
+
298
+ "Carton"
299
+ Parses cpanfile.snapshot file and checks the distribution versions.
300
+
301
+ cpanfile
302
+ Parses cpanfile taking into account the required versions.
303
+
304
+ It is assumed that if the required version of the module is less than a
305
+ version of a release with a known vulnerability fix, then the module is
306
+ considered affected.
307
+
308
+ JSON data
309
+ If you request JSON output, the data looks like
310
+
311
+ {
312
+ "meta" : {
313
+ ... meta information ...
314
+ "dists": {
315
+ "<distribution1>": {
316
+ ... distribution info ...
317
+ }
318
+ }
319
+ "errors" : [
320
+ ... list of errors - if any ...
321
+ ]
322
+ }
323
+
324
+ Meta information
325
+ The meta data contains information about the run of "cpan-audit".
326
+
327
+ {
328
+ "args": [
329
+ "Mojo::File",
330
+ "Mojo::UserAgent",
331
+ "LWP::UserAgent"
332
+ ],
333
+ "cpan_audit": {
334
+ "version": "20230601.002"
335
+ },
336
+ "total_advisories": 19,
337
+ "command": "modules"
338
+ }
339
+
340
+ These information are shown
341
+
342
+ * cpan_audit
343
+
344
+ The version of "cpan_audit" that is used for the audit
345
+
346
+ * command
347
+
348
+ The command of "cpan_audit" that was run
349
+
350
+ * args
351
+
352
+ Arguments for the command
353
+
354
+ * total_advisories
355
+
356
+ Number of found advisories
357
+
358
+ Distribution information
359
+ For each distribution where at least one advisory was found, the JSON
360
+ looks like:
361
+
362
+ "Dist-Name": {
363
+ "queried_modules": [
364
+ "Queried::Namespace"
365
+ ],
366
+ "version": "Any",
367
+ "advisories": [
368
+ {
369
+ ... advisory data as in the audit database ...
370
+ },
371
+ ... more advisories ...
372
+ ]
373
+ },
374
+
375
+ The advisory data is basically the data from the database. So this
376
+ depends on what is known for the given advisory.
377
+
378
+ The distribution information contains:
379
+
380
+ * version
381
+
382
+ The version (range) that is checked for advisories. If there's no
383
+ version specified, all versions are checked and the version is
384
+ report as "Any".
385
+
386
+ * queried_modules
387
+
388
+ The actual namespaces queried, either from the command line or
389
+ another source, such as a cpanfile.
390
+
391
+ * advisories
392
+
393
+ A list of all vulnerabilities found for the version range
394
+
395
+ Exit values
396
+ In prior versions, "cpan-audit" exited with the number of advisories it
397
+ found. Starting with 1.001, if there are advisories found, "cpan-audit"
398
+ exits with 64 added to that number. The maximum number of reported
399
+ advisories is 62, since values over 126 are spoken for.
400
+
401
+ If the option "--exit-zero" is set "cpan-audit" exits always with a
402
+ normal exit code (0). This allows to use "cpan-audit" in build
403
+ environments together with bash exit mode activated ("set -e").
404
+
405
+ * 0 - no advisories found
406
+
407
+ * 2 - problem with program invocation, such as bad switches or values
408
+
409
+ * 64+n - advisories found. Subtract 64 to get the advisory count, up
410
+ to 62 advisories
411
+
412
+ * 255 - unspecified program error
413
+
414
+ LICENSE
415
+ Copyright (C) Viacheslav Tykhanovskyi.
416
+
417
+ This library is free software; you can redistribute it and/or modify it
418
+ under the same terms as Perl itself.HERE
419
+ HERE
420
+
219
421
exit ( $exit_code );
220
422
}
221
423
0 commit comments