vulnlog report impact

vulnlog report impact generates an HTML report of the entries in one or more Vulnlog files: their state, verdict, severity, and the releases they affect. Several files are merged into one report.

Synopsis

vulnlog report impact <inputs>... [-o <path>] [<filter-options>] [--state <state>]... [--verdict <verdict>]... [--disposition <disposition>]...

Arguments and options

Name Value Default Description

<inputs>

One or more Vulnlog files, or -

required

Files to report on, all with the same project block. For how files are merged, see Input files. - reads one file from stdin.

-o, --output

A file path, or -

vulnlog-impact-report.html

File to write, in the current directory by default. - writes the HTML to stdout.

--reporter, --as-of, --tag

See Filter options

Select the entries. With --as-of, an entry whose fix ships in a later release shows the state it had before the fix.

--state

under investigation, open, accepted, resolved, or not applicable

all states

Select entries in this state. Repeatable. With --as-of, the state at that release counts.

--verdict

under investigation, affected, or not affected

all verdicts

Select entries with this verdict. Repeatable. under investigation selects entries without a verdict. --as-of doesn’t change the verdict.

--disposition

will fix or wont fix

all entries

Select affected entries with this disposition. Repeatable. Entries without a disposition don’t match either value.

Repeat an option to select entries that match any of its values. Different options combine, so an entry must match each of them. For the states and what they mean, see States. For global options and standard input and output, see Global options and Standard input and output.

Output

The report is one HTML file that opens offline in a browser. It shows:

  • The organisation, project, and author, the generation time, the input files, and the filters you applied.

  • A summary with the total number of entries, the number in each state, and the severities of the Open (state open) and Accepted (state accepted) entries.

  • A table with a row for each entry: its IDs, its state, the details (verdict, severity, disposition, justification, description, and analysis), and the affected releases.

The rows are sorted by state, in the order open, under investigation, accepted, resolved, and not applicable. Within a state, they’re sorted by severity and then by ID.

This is the report for acme-shop.vl.yaml without filters:

The impact report of Acme Shop. The About and Summary boxes are above a table with one row for each of the six vulnerabilities. Select the image to open it in full size.

A filter that selects no entry produces a report with an empty table. The command never fails because of what the report contains.

Exit codes

Code When

0

The report was written.

1

A general error. For the general errors, see Exit codes.

2

A file doesn’t pass validation, or the files have different project blocks.

5

A filter names an unknown reporter, release, tag, state, verdict, or disposition.

Examples

Report every entry:

$ vulnlog report impact acme-shop.vl.yaml
Wrote: vulnlog-impact-report.html

Report the entries that were still open when 4.3.0 shipped, and show what the filters matched:

$ vulnlog -v report impact acme-shop.vl.yaml --as-of 4.3.0 --state open -o open-4.3.0.html
verbose: parsed acme-shop.vl.yaml: schema version 1, releases: 3, tags: 4, vulnerabilities: 6
verbose: as-of filter expanded to releases: 4.2.0, 4.3.0
verbose: state filter: open
Wrote: open-4.3.0.html
verbose: wrote open-4.3.0.html

The report lists Spring4Shell only. With --as-of 4.2.0 instead, Log4Shell is open as well, because its fix ships in 4.3.0.

Report the risks you accepted:

$ vulnlog report impact acme-shop.vl.yaml --verdict affected --disposition "wont fix" -o accepted.html
Wrote: accepted.html

The report lists the lodash entry CVE-2021-23337.

Merge the files of two release lines of one project:

$ vulnlog report impact acme-shop.vl.yaml acme-shop-3.vl.yaml
Wrote: vulnlog-impact-report.html

Files of different projects stop the command:

$ vulnlog report impact acme-shop.vl.yaml acme-admin.vl.yaml
error: all input files must share the same project metadata, found 2 different ones
  hint: give every input the same project block, or report each project on its own