reportng¶
reportng
is a python module to build on the fly reports.
It leverages Bootstrap 4 to automatically create using user defined bootswatch themes.
reportng
is capable of handling any python out including but not limited to api output, stdio output, sql queries etc.
Some example use cases of reportng
are
- Create a report for a tool
- Create a report of a test
- Create a report of debugging
- etc…
reportng
is designed to be stackable. This means that it follows the following convention
- section
- …
- footer
Installation¶
pip install reportng
Documentation¶
Reportng¶
-
class
reportng.
Reportng
(report_name: str, brand: str, use_asciinema: bool = False, show_progress_bar: bool = True, show_search: bool = True, highlight_code: bool = True, theme_preview: bool = False, user_javascript: str = None, user_css: str = None, theme: str = 'lux', use_bootstrap: bool = False, search_highlight_color: str = '#f1c40f', navbar_background: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary')¶ -
__init__
(report_name: str, brand: str, use_asciinema: bool = False, show_progress_bar: bool = True, show_search: bool = True, highlight_code: bool = True, theme_preview: bool = False, user_javascript: str = None, user_css: str = None, theme: str = 'lux', use_bootstrap: bool = False, search_highlight_color: str = '#f1c40f', navbar_background: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary')¶ The __init__ method for the Reportng class. The init method is used to set the brand and report_name for the report, along with optional arguments that can control custom css, js, and other built in features of Reportng. Features that can be enabled or disabled includes asciinema, progress bar, search, highlight etc.
Parameters: - report_name (str) – The name of the report
- brand (str) – The author/brand of the report.
- use_asciinema (bool, optional) – If asciinema player should be used. Defaults to False.
- show_progress_bar (bool, optional) – Enable a top scrolling progress bar. Defaults to True.
- show_search (bool, optional) – Enable search. Defaults to True.
- highlight_code (bool, optional) – Enable code highlight. Defaults to True.
- theme_preview (bool, optional) – Preview themes. Defaults to False.
- user_javascript (str, optional) – Custom Javascript to inject in the header. Defaults to None.
- user_css (str, optional) – Custom CSS to inject in the header. Defaults to None.
- theme (str, optional) – A valid Bootstrap 4 theme. Defaults to “lux”.
- use_bootstrap (bool, optional) – Base Bootstrap 4 theme. Defaults to False.
- search_highlight_color (str, optional) – Highlight color for matching search results. Defaults to “#f1c40f”.
- navbar_background (Literal[, optional) – Color for navbar. Defaults to “primary”.
-
asciinema
(asciinema_link: str, title: str = '', is_section: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)¶ Add an asciinema section
Parameters: - asciinema_link (str) – Link to asciinema
- title (str, optional) – Title for asciinema. Defaults to “”.
- is_section (bool, optional) – Add as extra data to previous section. Defaults to False.
- add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns: The Reportng object.
Return type:
Add captions to the previous section
Parameters: - content (str) – Caption content
- text_color (Literal[, optional) – Color of caption. Defaults to “primary”.
- is_section (bool, optional) – Add as extra data to previous section. Defaults to True.
- raw_html (str, optional) – Add raw html. Defaults to None.
Returns: The Reportng object.
Return type:
-
cards
(cards: List[reportng.rngtypes.Cards], is_section: bool = False, border_only: bool = False, section_title: str = None, add_alert: reportng.rngtypes.Alert = None, add_modal: reportng.rngtypes.Modal = None)¶ Add a cards section
Parameters: - cards (List[Cards]) – List of cards. Each card is a dictionary
- is_section (bool, optional) – Add as data to previous section. Defaults to False.
- border_only (bool, optional) – Show cards with borders only. Defaults to False.
- section_title (str, optional) – Card title. Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Raises: TypeError
– Cards should be a list of cardsReturns: The Reportng object.
Return type:
-
code
(title: str, content: str, is_section: bool = True, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)¶ Add a code section with highlighting
Parameters: - title (str) – Title of section
- content (str) – Section content
- is_section (bool, optional) – Add as extra data to previous section. Defaults to False.
- add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns: The Reportng object.
Return type:
-
custom_html
(html: str)¶ Add a custom section with raw html inside a jumbotron
Parameters: html (str) – Raw html Returns: The Reportng object. Return type: Reportng
Add a footer section
Parameters: - message (str, optional) – Footer message. Defaults to “”.
- twitter (str, optional) – Twitter link. Defaults to None.
- linkedin (str, optional) – Linkedin link. Defaults to None.
- github (str, optional) – Github link. Defaults to None.
- email (str, optional) – Email address. Defaults to None.
- raw_html (str, optional) – Add raw html. Defaults to None.
Returns: The Reportng object.
Return type:
-
image_carousel
(images: List[reportng.rngtypes.ImageCarouselType])¶ Create an image carousel
Parameters: images (List[ImageCarouselType]) – List of image paths Returns: The Reportng object. Return type: Reportng
-
list_group
(section_title: str, items: List[str], is_section: bool = False, raw_html: str = None, add_reference: reportng.rngtypes.Reference = None, add_modal: reportng.rngtypes.Modal = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None)¶ Add a list group section. A list group is a collection of strings presented as a list
Parameters: - section_title (str) – Section title
- items (List[str]) – An array of list items as strings
- is_section (bool, optional) – Add as data to previous section. Defaults to False.
- raw_html (str, optional) – Add raw html. Defaults to None.
- add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns: The Reportng object.
Return type:
-
save
(path: str) → None¶ Save the report
Parameters: path (str) – Path to save the report.
-
section
(title: str, content: str, raw_html_content: Optional[str] = None, keep_formatting: bool = True, section_color: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary', title_background: bool = False, overflow_control: str = 'max-height: 70%; overflow: auto; margin-bottom: 20', text_color: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary', use_h2_title: bool = False, is_section: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)¶ A section is considered the main container used by Reportng to hold values. Any string type value can be passed into a section.
Parameters: - title (str) – Title of the section
- content (str) – Content for the section
- raw_html_content (Union[str, None], optional) – Raw html content to include. Defaults to None.
- keep_formatting (bool, optional) – Use a pre tag for the content to keep formatting. Defaults to True.
- section_color (Literal[, optional) – Color of the section title bar. Defaults to “primary”.
- title_background (bool, optional) – If true, background color is applied. Else, text color is changed. Defaults to False.
- overflow_control (str, optional) – Uses valid CSS to control overflow of data. Defaults to rng.CSSControl.css_overflow.
- text_color (Literal[, optional) – Text color of section. Defaults to “primary”.
- use_h2_title (bool, optional) – Use h2 as title instead of h1. If h2, it will not allow jumping from navbar. Defaults to False.
- is_section (bool, optional) – Add as extra data to the previous container. Defaults to False.
- add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns: The Reportng object
Return type:
-
section_collapsible
(title: str, content: str = '', section_color: str = 'default', raw_html_content: str = '', keep_formatting: bool = True, **kwargs)¶ Create a collapsed section.
Parameters: - title (str) – Title for section
- content (str, optional) – Section Content. Defaults to “”.
- section_color (str, optional) – Section color. Defaults to “default”.
- raw_html_content (str, optional) – Raw html content. Defaults to “”.
- keep_formatting (bool, optional) – Preserve formatting. Defaults to True.
Returns: The Reportng object.
Return type:
-
table
(table_header: List[str], data: List[List[str]], is_section: bool = False, section_title: str = '', header_color: typing_extensions.Literal['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark', 'default', 'red', 'green', 'blue', 'yellow', 'light'][primary, secondary, success, danger, warning, info, light, dark, default, red, green, blue, yellow, light] = 'dark', show_index: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)¶ Add a table section
Parameters: - table_header (List[str]) – Table header. Should be a list of strings corresponding to the number of data points.
- data (List[List[str]]) – Table data. Should be a list of list of strings. For example [[1,2,3], [‘a’, ‘b’, ‘c’]].
- is_section (bool, optional) – Add extra data to previous section. Defaults to False.
- section_title (str, optional) – Title for section. Defaults to “”.
- header_color (Literal[, optional) – Title header color. Defaults to “dark”.
- show_index (bool, optional) – Show the table index. Defaults to False.
- add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
- add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
- add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
- add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns: The Reportng object.
Return type:
-
Helpers¶
JSCSS¶
-
class
reportng.rnghelpers.
JSCSS
¶ This class controls constants that can be modified by the user and can be pointed to local files to host them locally. Can be used with
DownloadAssets(download_path, rel_path)
class to save all files locally and point them correctly-
asciinema_css
= 'https://cdnjs.cloudflare.com/ajax/libs/asciinema-player/2.4.1/asciinema-player.min.css'¶ Constant that handles asciinema-player.min.js
Type: asciinema_css
-
asciinema_js
= 'https://cdnjs.cloudflare.com/ajax/libs/asciinema-player/2.4.1/asciinema-player.min.js'¶ Constant that handles asciinema-player.min.js
Type: asciinema_js
-
bootswatch
= 'https://bootswatch.com/4/lux/bootstrap.min.css'¶ bootswatch theme
-
bs4_js
= 'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js'¶ Constant that handles bootstrap.min.js
Type: bs4_js
-
font_awesome
= 'https://use.fontawesome.com/releases/v5.0.6/css/all.css'¶ Constant that handles font awesomes all.min.js
Type: font_awesome
-
highlightjs_css
= 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css'¶ Constant that handles highlight.js default.min.js
Type: highlighjs_css
-
highlightjs_js
= 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js'¶ Constant that handles highlight.min.js
Type: highlight_js
-
jquery
= 'https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js'¶ Constant that handles jqery.min.js
Type: jquery
-
mark_js
= 'https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js'¶ Constant that handles mark.js
Type: mark_js
-
popper_js
= 'https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.0/umd/popper.min.js'¶ popper_js = Constant that handles popper.js
-
progressbar_js
= 'https://cdn.rawgit.com/securisec/reportng/master/js/progressbar.js'¶ Constant that handles progressbar.js
Type: progressbar
-
CSSControl¶
-
class
reportng.rnghelpers.
CSSControl
¶ CSS control
-
css_overflow
= 'max-height: 70%; overflow: auto; margin-bottom: 20'¶ This value can be modified globally so that all containers are the same size similar to the output report_code_section. Can be modified directly, or using overflow option in report_section
Type: css_overflow
-
jumbotron_style
= 'padding-bottom:3; padding-top:40'¶ Style attribute values of jumbotron
Type: jumbotron_style
-
not_sticky_section
= 'padding-bottom:3; padding-top:40;'¶ Controls if the section is not a sticky
Type: not_stick_section
-
sticky_section_css
= 'padding:0; margin-top:-2rem;'¶ Controls if section should sticky with preceeding section
Type: sticky_section_css
-
JSCustom¶
-
class
reportng.rnghelpers.
JSCustom
¶ Class that handles all the custom JS code. It is best not to modify any of this code.
HelperFunctions¶
-
class
reportng.rnghelpers.
HelperFunctions
¶ Some helper functions that does not impact how enduser uses reportng
-
static
accordian_collapse
(color, title, content, pre, raw_html, **kwargs)¶ Creates a collapsible accordian
-
static
color_to_tag
(s)¶ Maps colors to their appropriate tags
-
static
convert_to_string
(s)¶ Converts an object to string
-
static
create_badges
(b)¶ Creates badges at the bottom of a section
-
static
make_alert
(data)¶ Helper function that creates dismissable alerts
-
static
make_cards
(b_only, k, h, v)¶ Helper function that helps making cards
Places a button with href on it.
-
static
slide_indicator
(num)¶ Helper function that controls how image slide count works
Valid options for colors/cards etc
-
static
Exceptions¶
-
exception
reportng.rnghelpers.
NotValidTag
¶ Exception to handle invalid tag for background color control
-
exception
reportng.rnghelpers.
ObjectNotInitiated
¶ Exception when a method is called but not initiated
-
exception
reportng.rnghelpers.
TooManyValues
¶ Exception when too many args are passed
-
exception
reportng.rnghelpers.
TableError
¶ Exception when there are problems with creating a table
Example¶
import reportng
from subprocess import Popen, PIPE
import requests
r = reportng.Reportng(report_name='Demo report',
brand='securisec')
# Multiline support
report.section(
'Multiline Demo',
"""
One line
Two line
""")
# Example stdio reporting
output = Popen('ls /tmp', shell=True, stdout=PIPE).stdout.read()
report += r.section('Output of ls', output,
tag_color='success')
# Example using web requests
req = requests.get('https://httpbin.org/status/418').text
report += r.section('Output of requests',
req, tag_color='info')
# Add an image carousel
report += r.image_carousel(
'foo.jpg',
'bar.jpg',
'baz.jpg')
# Add description for image carousel
report += r.caption('Nice pictures!')
# Add a footer
report += r.footer(message='Hello from securisec!',
twitter='https://twitter.com/securisec',
github='https://github.com/securisec')
# Save the report!
r.save('demo_report.html')
Social¶