-
Notifications
You must be signed in to change notification settings - Fork 732
Adding a New Report Format
Brakeman can output reports in several formats. The format is determined either by the option passed via the -f flag or the extensions of the file name passed to -o. Note Brakeman can output several formats at once if -o is used multiple times.
Add the new format to the command line options in lib/brakeman/options.rb.
The mapping from -f or -o occurs in Brakeman.get_formats_from_output_format and Brakeman.get_formats_from_output_files.
After that, report types are mapped to the formatter class in lib/brakeman/report.rb.
Report formatters live in lib/brakeman/report/. New report formatters should inherit from Brakeman::Report::Base and implement a generate_report method. See Brakeman::Report::JSON for a short example.
The all_warnings method should be used to access an array of all (not ignored) warnings. Warnings may have varying information depending on the location and type of the warning. When formatting warnings for machine consumption, keep in mind the warning_code is an unchanging integer which should be used to identify the "type" of warning, while warning_type is a string description of the broader "category" of the warning, which may change format over time.
If the formatter always needs absolute paths to files, use Warning#file. If the formatter always needs relative paths, use relative_path(warning.file). If it should be up to the user, use warning_file(warning) to choose automatically.
Use rails_version to get a string representation of the detected Rails version.
TEXT_CONFIDENCE can be used to convert Warning#confidence to a string with TEXT_CONFIDENCE[warning.confidence]. Alternatively, 0 is the highest confidence, while 2 is currently the lowest. (In Brakeman confidence is basically confidence + severity).
If a machine-readable format needs to compare warnings across scans, use Warning#fingerprint as an identifier.
At a minimum, new formats should have a simple test in test/tests/report_generation.rb. For machine-readable formats, it's recommended to parse the report back into memory as a data structure. Ensure the expected keys and number of warnings are present.
More sophisticated tests that make sense for the format are appreciated, but try to avoid brittle tests that may have to be updated frequently when the underlying test apps change.