msticpy.vis package

Submodules

msticpy.vis.entity_graph_tools module

Creates an entity graph for a Microsoft Sentinel Incident.

class msticpy.vis.entity_graph_tools.EntityGraph(entity: Union[msticpy.datamodel.soc.incident.Incident, msticpy.datamodel.entities.alert.Alert, pandas.core.frame.DataFrame, pandas.core.series.Series, msticpy.datamodel.entities.entity.Entity, msticpy.nbtools.security_alert.SecurityAlert])

Bases: object

Create a graph for visualizing and tracking links between entities.

Create a new instance of the entity graph.

Parameters

entity (Union[Incident, Alert, pd.DataFrame, pd.Series, Entity, SecurityAlert]) – The initial item to add to the graph. Can be an Incident, Alert, SecurityAlert or other Entity

add_entity(ent: msticpy.datamodel.entities.entity.Entity, attached_to: Optional[str] = None)

Add an entity to the graph.

Parameters

  • ent (Entity) – The entity object to add the graph

  • attached_to (str, optional) – The name of the node to attach the entity to, by default None

add_incident(incident: Union[msticpy.datamodel.soc.incident.Incident, msticpy.datamodel.entities.alert.Alert, pandas.core.frame.DataFrame])

Add another incident or set of incidents to the graph.

Parameters

incident (Union[Incident, Alert, pd.DataFrame]) – This can be an alert, and incident or a DataFrame of alerts or incidents

Add a link between 2 nodes on the graph.

Parameters

  • source (str) – Name of node to link from

  • target (str) – Name of node to link to

Raises

MsticpyUserError – If nodes aren’t present in the graph

add_note(name: str, description: Optional[str] = None, attached_to: Optional[Union[str, List]] = None)

Add a node to the graph representing a note or comment.

Parameters

  • name (str) – The name of the node to add

  • description (Optional[str], optional) – A description of the note, by default None

  • attached_to (Union[str, List], optional) – What existing nodes on the graph to attach it the note to, by default None

  • user (str, optional) – What user to associate the note with

property graph: networkx.classes.graph.Graph

Return the raw NetworkX graph.

plot(hide: bool = False, timeline: bool = False, **kwargs) → bokeh.models.layouts.LayoutDOM

Plot a graph of entities.

Parameters

  • hide (bool, optional) – Set true to not display the graphic, by default False

  • timeline (bool, optional) – Set to True to display a timeline, by default False

  • node_size (int, optional) – Size of the nodes in pixels, by default 25

  • font_size (int, optional) – Font size for node labels, by default 10 Can be an integer (point size) or a string (e.g. “10pt”)

  • width (int, optional) – Width in pixels, by default 800

  • height (int, optional) – Image height (the default is 800)

  • scale (int, optional) – Position scale (the default is 2)

Returns

A Bokeh figure object

Return type

LayoutDOM

Remove a link between 2 nodes on the graph.

Parameters

  • source (str) – Name of node to remove link from

  • target (str) – name of node to remove link to

Raises

MsticpyUserError – If edge isn’t present in the graph

remove_node(name: str)

Remove a node from the graph.

Parameters

name (str) – The name of the node to remove.

to_df() → pandas.core.frame.DataFrame

Generate a dataframe of nodes in the graph.

msticpy.vis.entity_graph_tools.plot_entitygraph(entity_graph: networkx.classes.graph.Graph, node_size: int = 25, font_size: Union[int, str] = 10, height: int = 800, width: int = 800, scale: int = 2, hide: bool = False) → bokeh.plotting.figure.figure

Plot entity graph with Bokeh.

Parameters

  • entity_graph (nx.Graph) – The entity graph as a networkX graph

  • node_size (int, optional) – Size of the nodes in pixels, by default 25

  • font_size (int, optional) – Font size for node labels, by default 10 Can be an integer (point size) or a string (e.g. “10pt”)

  • width (int, optional) – Width in pixels, by default 800

  • height (int, optional) – Image height (the default is 800)

  • scale (int, optional) – Position scale (the default is 2)

  • hide (bool, optional) – Don’t show the plot, by default False. If True, just return the figure.

Returns

The network plot.

Return type

bokeh.plotting.figure

msticpy.vis.matrix_plot module

Bokeh matrix plot.

class msticpy.vis.matrix_plot.PlotParams(title: Optional[str] = 'Interaction Plot', x: Optional[str] = None, x_col: Optional[str] = None, y: Optional[str] = None, y_col: Optional[str] = None, intersect: bool = False, height: int = 700, width: int = 900, color: str = 'red', value_col: Optional[str] = None, dist_count: bool = False, log_size: bool = False, invert: bool = False, sort: Optional[Union[str, bool]] = None, sort_x: Optional[Union[str, bool]] = None, sort_y: Optional[Union[str, bool]] = None, hide: bool = False, font_size: Optional[int] = None, max_label_font_size: int = 11)

Bases: object

Plot params for time_duration.

Method generated by attrs for class PlotParams.

color: str
dist_count: bool
classmethod field_list() → List[str]

Return field names as a list.

font_size: Optional[int]
height: int
hide: bool
intersect: bool
invert: bool
log_size: bool
max_label_font_size: int
sort: Optional[Union[str, bool]]
sort_x: Optional[Union[str, bool]]
sort_y: Optional[Union[str, bool]]
title: Optional[str]
value_col: Optional[str]
width: int
x: Optional[str]
x_col: Optional[str]
property x_column: Optional[str]

Return the current x column value.

y: Optional[str]
y_col: Optional[str]
property y_column: Optional[str]

Return the current y column value.

msticpy.vis.matrix_plot.plot_matrix(data: pandas.core.frame.DataFrame, **kwargs) → bokeh.models.layouts.LayoutDOM

Plot data as an intersection matrix.

Parameters

  • data (pd.DataFrame) – The data to plot.

  • x (str) – Column to plot on the x (horizontal) axis

  • x_col (str) – Alias for ‘x’

  • y (str) – Column to plot on the y (vertical) axis

  • y_col (str) – Alias for ‘y’

  • title (str, optional) – Custom title, default is ‘Intersection plot’

  • value_col (str, optional) – Column from the DataFrame used to size the intersection points.

  • dist_count (bool, optional) – Calculates a count of distinct values (from value_col) and uses this to size the intersection points. Requires value_col to be specified.

  • log_size (bool, optional) – Takes the log of the size value before calculating the intersection display point size. Can be combined with invert.

  • invert (bool, optional) – Takes the inverse of the size value as the basis for calculating the intersection display point size. This is useful for highlighting rare interactions. Can be combined with log_size.

  • intersect (bool, optional) – Plots points of a fixed size, rather than using a sizing value. This is useful for just showing the presence/absence of an interaction.

  • height (int, optional) – The plot height. Default is 700

  • width (int) – The plot width. Default is 900

  • color (str) – The color of the plotted points, default is “red”

  • sort (Union[str, bool], optional) – Sorts the labels of both axes, default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • sort_x (str, optional) – Sorts the labels of the x axis (takes precedence over sort), default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • sort_y (str, optional) – Sorts the labels of the y axis (takes precedence over sort), default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • hide (bool, optional) – Creates and returns but does not display the plot, default is False.

  • font_size (int, optional) – Manually specify the font size for axis labels, in points, the default is to automatically calculate a size based on the number of items in each axis.

  • max_label_font_size (int, optional) – The maximum size, in points, of the X and Y labels, default is 11.

Returns

The Bokeh plot

Return type

LayoutDOM

msticpy.vis.mp_pandas_plot module

Module docstring.

class msticpy.vis.mp_pandas_plot.MsticpyPlotAccessor(pandas_obj)

Bases: object

Pandas api extension for MSTICPy visualizations.

Instantiate pandas extension class.

incident_graph(timeline: bool = False, hide: bool = False, **kwargs) → bokeh.models.layouts.LayoutDOM

Plot an incident graph if the dataframe contains incidents or alerts.

Parameters

  • timeline (bool, optional) – True to plot the entity timeline, by default False

  • hide (bool, optional) – True to hide the plot, by default False

  • node_size (int, optional) – Size of the nodes in pixels, by default 25

  • font_size (int, optional) – Font size for node labels, by default 10 Can be an integer (point size) or a string (e.g. “10pt”)

  • width (int, optional) – Width in pixels, by default 800

  • height (int, optional) – Image height (the default is 800)

  • scale (int, optional) – Position scale (the default is 2)

Raises

MsticpyUserError – Raised if the dataframe does not contain incidents or alerts.

matrix(**kwargs) → bokeh.models.layouts.LayoutDOM

Plot data as an intersection matrix.

Parameters

  • data (pd.DataFrame) – The data to plot.

  • x (str) – Column to plot on the x (horizontal) axis

  • x_col (str) – Alias for ‘x’

  • y (str) – Column to plot on the y (vertical) axis

  • y_col (str) – Alias for ‘y’

  • title (str, optional) – Custom title, default is ‘Intersection plot’

  • value_col (str, optional) – Column from the DataFrame used to size the intersection points.

  • dist_count (bool, optional) – Calculates a count of distinct values (from value_col) and uses this to size the intersection points. Requires value_col to be specified.

  • log_size (bool, optional) – Takes the log of the size value before calculating the intersection display point size. Can be combined with invert.

  • invert (bool, optional) – Takes the inverse of the size value as the basis for calculating the intersection display point size. This is useful for highlighting rare interactions. Can be combined with log_size.

  • intersect (bool, optional) – Plots points of a fixed size, rather than using a sizing value. This is useful for just showing the presence/absence of an interaction.

  • height (int, optional) – The plot height. Default is 700

  • width (int) – The plot width. Default is 900

  • color (str) – The color of the plotted points, default is “red”

  • sort (Union[str, bool], optional) – Sorts the labels of both axes, default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • sort_x (str, optional) – Sorts the labels of the x axis (takes precedence over sort), default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • sort_y (str, optional) – Sorts the labels of the y axis (takes precedence over sort), default is None. Acceptable values are: ‘asc’ (or string starting with ‘asc’) - Sort ascending ‘desc’ (or string starting with ‘asc’) - Sort descending False or None (no sort) True - Sort ascending

  • hide (bool, optional) – Creates and returns but does not display the plot, default is False.

  • font_size (int, optional) – Manually specify the font size for axis labels, the default is to automatically calculate a size based on the number of items in each axis.

  • max_label_font_size (int, optional) – The maximum size, in points, of the X and Y labels, default is 11.

Returns

The Bokeh plot

Return type

LayoutDOM

process_tree(**kwargs) → Tuple[bokeh.plotting.figure.figure, bokeh.models.layouts.LayoutDOM]

Build and plot a process tree.

Parameters

  • schema (ProcSchema, optional) – The data schema to use for the data set, by default None (if None the schema is inferred)

  • output_var (str, optional) – Output variable for selected items in the tree, by default None

  • legend_col (str, optional) – The column used to color the tree items, by default None

  • show_table (bool) – Set to True to show a data table, by default False.

  • height (int, optional) – The height of the plot figure (the default is 700)

  • width (int, optional) – The width of the plot figure (the default is 900)

  • title (str, optional) – Title to display (the default is None)

  • hide_legend (bool, optional) – Hide the legend box, even if legend_col is specified.

  • pid_fmt (str, optional) – Display Process ID as ‘dec’ (decimal) or ‘hex’ (hexadecimal), default is ‘hex’.

Returns

figure - The main bokeh.plotting.figure Layout - Bokeh layout structure.

Return type

Tuple[figure, LayoutDOM]

timeline(**kwargs) → bokeh.models.layouts.LayoutDOM

Display a timeline of events.

Parameters

  • time_column (str, optional) – Name of the timestamp column (the default is ‘TimeGenerated’)

  • source_columns (list, optional) – List of default source columns to use in tooltips (the default is None)

  • title (str, optional) – Title to display (the default is None)

  • alert (SecurityAlert, optional) – Add a reference line/label using the alert time (the default is None)

  • ref_event (Any, optional) – Add a reference line/label using the alert time (the default is None)

  • ref_time (datetime, optional) – Add a reference line/label using ref_time (the default is None)

  • group_by (str) – The column to group timelines on.

  • legend (str, optional) – “left”, “right”, “inline” or “none” (the default is to show a legend when plotting multiple series and not to show one when plotting a single series)

  • yaxis (bool, optional) – Whether to show the yaxis and labels (default is False)

  • ygrid (bool, optional) – Whether to show the yaxis grid (default is False)

  • xgrid (bool, optional) – Whether to show the xaxis grid (default is True)

  • range_tool (bool, optional) – Show the the range slider tool (default is True)

  • height (int, optional) – The height of the plot figure (the default is auto-calculated height)

  • width (int, optional) – The width of the plot figure (the default is 900)

  • color (str) – Default series color (default is “navy”)

  • overlay_data (pd.DataFrame:) – A second dataframe to plot as a different series.

  • overlay_color (str) – Overlay series color (default is “green”)

  • ref_events (pd.DataFrame, optional) – Add references line/label using the event times in the dataframe. (the default is None)

  • ref_time_col (str, optional) – Add references line/label using the this column in ref_events for the time value (x-axis). (this defaults the value of the time_column parameter or ‘TimeGenerated’ time_column is None)

  • ref_col (str, optional) – The column name to use for the label from ref_events (the default is None)

  • ref_times (List[Tuple[datetime, str]], optional) – Add one or more reference line/label using (the default is None)

Returns

The bokeh plot figure.

Return type

LayoutDOM

timeline_duration(group_by: Union[Iterable[str], str], time_column: str = 'TimeGenerated', end_time_column: Optional[str] = None, **kwargs) → bokeh.models.layouts.LayoutDOM

Display a duration timeline of events grouped by one or more columns.

Parameters

  • group_by (Union[Iterable[str], str]) – The column name or iterable of column names to group the data by.

  • time_column (str) – Primary time column - will be used to calculate the start time of the duration for each group. If end_time_column is not specified it will also be used to calculate the end time.

  • end_time_column (Optional[str]) – If supplied, it will be used to calculate the end time of the duration for each group.

  • title (str, optional) – Title to display (the default is None)

  • ylabel_cols (Optional[Iterable[str]], optional) – The subset of the group columns to use for the y-axis labels.

  • yaxis (bool, optional) – Whether to show the yaxis and labels

  • range_tool (bool, optional) – Show the the range slider tool (default is True)

  • source_columns (list, optional) – List of default source columns to use in tooltips (the default is None)

  • height (int, optional) – The height of the plot figure (the default is auto-calculated height)

  • width (int, optional) – The width of the plot figure (the default is 900)

  • color (str) – Default series color (default is “navy”)

  • ref_events (pd.DataFrame, optional) – Add references line/label using the event times in the dataframe. (the default is None)

  • ref_col (str, optional) – The column name to use for the label from ref_events (the default is None)

  • ref_times (List[Tuple[datetime, str]], optional) – Add one or more reference line/label using (the default is None)

Returns

The bokeh plot figure.

Return type

LayoutDOM

timeline_values(value_col: Optional[str] = None, **kwargs) → bokeh.models.layouts.LayoutDOM

Display a timeline of events.

Parameters

  • time_column (str, optional) – Name of the timestamp column (the default is ‘TimeGenerated’)

  • value_col (str) – The column name holding the value to plot vertically

  • source_columns (list, optional) – List of default source columns to use in tooltips (the default is None)

  • x (str, optional) – alias of time_column

  • y (str, optional) – alias of value_col

  • title (str, optional) – Title to display (the default is None)

  • ref_event (Any, optional) – Add a reference line/label using the alert time (the default is None)

  • ref_time (datetime, optional) – Add a reference line/label using ref_time (the default is None)

  • ref_label (str, optional) – A label for the ref_event or ref_time reference item

  • group_by (str) – (where data is a DataFrame) The column to group timelines on

  • legend (str, optional) – “left”, “right”, “inline” or “none” (the default is to show a legend when plotting multiple series and not to show one when plotting a single series)

  • yaxis (bool, optional) – Whether to show the yaxis and labels

  • range_tool (bool, optional) – Show the the range slider tool (default is True)

  • height (int, optional) – The height of the plot figure (the default is auto-calculated height)

  • width (int, optional) – The width of the plot figure (the default is 900)

  • color (str) – Default series color (default is “navy”). This is overridden by automatic color assignments if plotting a grouped chart

  • kind (Union[str, List[str]]) – one or more glyph types to plot., optional Supported types are “circle”, “line” and “vbar” (default is “vbar”)

  • ref_events (pd.DataFrame, optional) – Add references line/label using the event times in the dataframe. (the default is None)

  • ref_time_col (str, optional) – Add references line/label using the this column in ref_events for the time value (x-axis). (this defaults the value of the time_column parameter or ‘TimeGenerated’ time_column is None)

  • ref_col (str, optional) – The column name to use for the label from ref_events (the default is None)

  • ref_times (List[Tuple[datetime, str]], optional) – Add one or more reference line/label using (the default is None)

Returns

The bokeh plot figure.

Return type

LayoutDOM

Module contents

Visualization sub-package.