msticpy.vis.foliummap module

Folium map class.

class msticpy.vis.foliummap.FoliumMap(title: str = 'OpenStreetMap', zoom_start: float = 2.5, tiles=None, width: str = '100%', height: str = '100%', location: list | None = None)

Bases: object

Wrapper class for Folium/Leaflet mapping.

Create an instance of the folium map.

Parameters:

• title (str, optional) – Name of the main tile layer (the default is ‘OpenStreetMap’)

• zoom_start (int, optional) – The zoom level of the map (the default is 7)

• tiles ([type], optional) – Custom set of tiles or tile URL (the default is None)

• width (str, optional) – Map display width (the default is ‘100%’)

• height (str, optional) – Map display height (the default is ‘100%’)

• location (list, optional) – Location to center map on

folium_map

The map object.

Type:

folium.Map

add_feature_sub_groups(subgroups: Iterable[folium.plugins.FeatureGroupSubGroup])

Add FeatureGroupSubGroups and to the map.

Parameters:

subgroups (Iterable[FeatureGroupSubGroup]) – Iterable of FeatureGroupSubGroups

add_geo_hashes(geohashes: Iterable[str], **kwargs)

Add decoded geohashes to the map.

Parameters:

• geohashes (Iterable[str]) – Iterable of geolocation hashes

• layer (str, optional) – If not none, it will add the entities to a new layer.

• kwargs (icon properties to use for displaying this cluster)

add_geoloc_cluster(geo_locations: Iterable[GeoLocation], **kwargs)

Add a collection of GeoLocation objects to the map.

Parameters:

• geo_locations (Iterable[GeoLocation]) – Iterable of GeoLocation entities.

• layer (str, optional) – If not none, it will add the entities to a new layer.

• kwargs (icon properties to use for displaying this cluster)

add_ip_cluster(ip_entities: Iterable[IpAddress], layer: str | None = None, **kwargs)

Add a collection of IP Entities to the map.

Parameters:

• ip_entities (Iterable[IpAddress]) – a iterable of IpAddress Entities

• layer (str, optional) – If not none, it will add the entities to a new layer.

• kwargs (icon properties to use for displaying this cluster)

add_ips(ip_addresses: Iterable[str], **kwargs)

Add a collection of GeoLocation objects to the map.

Parameters:

• ip_addresses (Iterable[str]) – Iterable of ip strings.

• layer (str, optional) – If not none, it will add the entities to a new layer.

• kwargs (icon properties to use for displaying this cluster)

add_locations(locations: Iterable[Tuple[float, float]], **kwargs)

Add a collection of lat/long tuples to the map.

Parameters:

• locations (Iterable[Tuple[float, float]]) – Iterable of location tuples.

• layer (str, optional) – If not none, it will add the entities to a new layer.

• kwargs (icon properties to use for displaying this cluster)

add_locations_to_feature_subgroup(locations: Iterable[Tuple[float, float]], subgroup: folium.plugins.FeatureGroupSubGroup, **kwargs)

Create markers from locations and add the FeatureGroupSubGroup.

Parameters:

• locations (Iterable[Tuple[float, float]]) – Collection of Latitude/Longitude coordinates to be added to the FeatureGroupSubGroup

• subgroup (FeatureGroupSubGroup) – Subgroup to add locations to, then add to the map

add_locations_to_marker_cluster(locations: Iterable[Tuple[float, float]], cluster: folium.plugins.MarkerCluster, **kwargs)

Create markers from locations and add to MarkerCluster.

Parameters:

• locations (Iterable[Tuple[float, float]]) – Collection of Latitude/Longitude coordinates to be added to the MarkerCluster

• cluster (MarkerCluster) – Marker cluster to add locations to, then add to the map

add_marker_clusters(clusters: Iterable[folium.plugins.MarkerCluster])

Add MarkerClusters and to the map.

Parameters:

clusters (Iterable[MarkerCluster]) – Iterable of MarkerClusters

center_map()

Calculate and set map center based on current coordinates.

static create_feature_sub_group_of_marker_cluster(cluster: folium.plugins.MarkerCluster, name: str) → folium.plugins.FeatureGroupSubGroup

Return a FeatureGroupSubGroup with name for a MarkerCluster.

Parameters:

• cluster (MarkerCluster) – Folium MarkerCluster to add FeatureGroupSubGroup to

• name (str) – Desired name of the MarkerCluster

Returns:

A Folium FeatureGroupSubGroup with the provided name as part of the given MarkerCluster

Return type:

FeatureGroupSubGroup

static create_marker(location: Tuple[float, float], tooltip: str | None = None, popup: str | None = None, **kwargs) → folium.Marker

Create and return a Folium Marker at a given location.

Parameters:

• location (Tuple[float,float]) – Latitude/Longitude coordinates for the Marker

• tooltip (str [Optional]) – Tooltip text for the Marker

• popup (str [Optional]) – Popup text for the Marker

Returns:

A Folium Marker at the given location coordinates

Return type:

Marker

static create_marker_cluster(name: str)

Create and return a MarkerCluster with name.

Parameters:

name (str) – Name of the MarkerCluster

Returns:

A Folium MarkerCluster with the provided name

Return type:

MarkerCluster

create_new_cluster_with_geohashes(geohashes: Iterable[str], name: str, **kwargs)

Create a MarkerCluster and add geohash locations.

Parameters:

• geohashes (Iterable[str]) – Collection of geohashes to be decoded and added to the MarkerCluster

• name (str) – Name of Marker Cluster to create, add locations to, then add to the map

create_new_cluster_with_locations(locations: Iterable[Tuple[float, float]], name: str, **kwargs)

Create a MarkerCluster with locations.

Parameters:

• locations (Iterable[Tuple[float, float]]) – Collection of Latitude/Longitude coordinates to be added to the MarkerCluster

• name (str) – Name of Marker Cluster to create, add locations to, then add to the map

create_new_subgroup_with_geohashes(geohashes: Iterable[str], subgroup_name: str, cluster_name: str, **kwargs)

Create a FeatureSubGroup with collection of geohash locations.

Parameters:

• geohashes (Iterable[str]) – Collection of geohashes to be decoded and added to the FeatureGroupSubGroup

• subgroup_name (str) – Name of SubGroup to create, add locations to, then add to the map

• cluster_name (str) – Name of the Marker Cluster to create and add the SubGroup to

create_new_subgroup_with_locations(locations: Iterable[Tuple[float, float]], subgroup_name: str, cluster_name: str, **kwargs)

Create subgroup of markers from locations.

Parameters:

• locations (Iterable[Tuple[float, float]]) – Collection of Latitude/Longitude coordinates to be added to the FeatureGroupSubGroup

• subgroup_name (str) – Name of FeatureGroupSubGroup to create, add locations to, then add to the map

• cluster_name (str) – Name of the cluster

Notes

This function creates a marker cluster and FeatureGroupSubGroup, then add the locations to the subgroup, then add the subgroup to the map.

enable_layer_control()

Enable Layer Control on the map.

Parameters:

None

save_map(path: str)

Save the map to path.

Parameters:

path (str) – File path to save the current map

msticpy.vis.foliummap.decode_geo_hash(geohash: str) → Tuple[float, float, float, float]

Decode a geohash.

Parameters:

geohash (str) – A string representation of a location

Returns:

Tuple representation of a geohash, format of: (Latitude, Longitude, Latitude Error interval, Longitude Error Interval)

Return type:

Tuple

Raises:

MsticpyMissingDependencyError – If pygeohash is not installed.

msticpy.vis.foliummap.decode_geohash_collection(geohashes: Iterable[str])

Return collection of geohashes decoded into location coordinates.

Parameters:

geohashes (Iterable[str]) – Collection of geohashes to be decoded

Returns:

Collection of location coordinates in Latitude/Longitude

Return type:

Iterable[Tuple[float, float]]

msticpy.vis.foliummap.get_center_geo_locs(loc_entities: Iterable[GeoLocation], mode: str = 'median') → Tuple[float, float]

Return the geographical center of the geo locations.

Parameters:

• loc_entities (Iterable[GeoLocation]) – GeoLocation entities with location information

• mode (str, optional) – The averaging method to use, by default “median”. “median” and “mean” are the supported values.

Returns:

Tuple of latitude, longitude

Return type:

Tuple[Union[int, float], Union[int, float]]

msticpy.vis.foliummap.get_center_ip_entities(ip_entities: Iterable[IpAddress], mode: str = 'median') → Tuple[float, float]

Return the geographical center of the IP address locations.

Parameters:

• ip_entities (Iterable[IpAddress]) – IpAddress entities with location information

• mode (str, optional) – The averaging method to us, by default “median”. “median” and “mean” are the supported values.

Returns:

Tuple of latitude, longitude

Return type:

Tuple[Union[int, float], Union[int, float]]

msticpy.vis.foliummap.get_map_center(entities: Iterable[Entity], mode: str = 'modal')

Calculate median point between Entity IP locations.

Parameters:

• entities (Iterable[Entity]) – An iterable of entities containing IpAddress geolocation information. The entities can be IpAddress entities or other entities that have IpAddress properties. The entities must all be of the same type.

• mode (str, optional) – The averaging method to use, by default “median”. “median” and “mean” are the supported values.

Returns:

The Latitude and Longitude calculated

Return type:

Tuple

Notes

The function uses the first entity in the entities to determine how to process the collection. E.g. if the first entity has properties src_ip and dest_ip of type IpAddress, these are the only properties that will be processed for the remainder of the entities.

msticpy.vis.foliummap.plot_map(data: DataFrame, ip_column: str | None = None, lat_column: str | None = None, long_column: str | None = None, layer_column: str | None = None, icon_column: str | None = None, icon_map: Callable[[str], Dict[str, Any]] | Dict[str, Any] | None = None, popup_columns: List[str] | None = None, tooltip_columns: List[str] | None = None, **kwargs) → folium.Map

Plot folium map from DataFrame.

Parameters:

• data (pd.DataFrame) – The input DataFrame, must have either an IP address column or latitude and longitude columns.

• ip_column (Optional[str], optional) – The name of the IP Address column, by default None

• lat_column (Optional[str], optional) – The name of the location ‘latitude’ column, by default None

• long_column (Optional[str], optional) – The name of the location ‘longitude’ column, by default None

• layer_column (Optional[str], optional) – The column to group markers into for displaying on different map layers, by default None

• icon_column (Optional[str], optional) – Optional column containing the name of the icon to use for the marker in this row, by default None

• icon_map (IconMapper, optional) – Mapping dictionary or function, by default None See Notes for more details.

• popup_columns (Optional[List[str]], optional) – List of columns to use for the popup text, by default None

• tooltip_columns (Optional[List[str]], optional) – List of columns to use for the tooltip text, by default None

• marker_cluster (bool, optional) – Use marker clustering, default is True.

• default_color (str, optional) – Default color for marker icons, by default “blue”

• title (str, optional) – Name of the layer (the default is ‘layer1’) (passed to FoliumMap constructor)

• zoom_start (int, optional) – The zoom level of the map (the default is 7) (passed to FoliumMap constructor)

• tiles ([type], optional) – Custom set of tiles or tile URL (the default is None) (passed to FoliumMap constructor)

• width (str, optional) – Map display width (the default is ‘100%’) (passed to FoliumMap constructor)

• height (str, optional) – Map display height (the default is ‘100%’) (passed to FoliumMap constructor)

• location (list, optional) – Location to center map on

Returns:

Folium Map object.

Return type:

folium.Map

Raises:

• ValueError – If neither ip_column nor lat_column and long_column are passed.

• LookupError – If one of the passed columns does not exist in data

Notes

There are two ways of providing custom icon settings based on the the row of the input DataFrame.

If icon_map is a dict it should contain keys that map to the value of icon_col and values that a dicts of valid folium Icon properties (“color”, “icon_color”, “icon”, “angle”, “prefix”). The dict should include a “default” entry that will be used if the value in the DataFrame[icon_col] doesn’t match any key. For example:

icon_map = {
    "high": {
        "color": "red",
        "icon": "warning",
    },
    "medium": {
        "color": "orange",
        "icon": "triangle-exclamation",
        "prefix": "fa",
    },
    "default": {
        "color": "blue",
        "icon": "info-sign",
    },
}

If icon_map is a function it should take a single str parameter (the item key) and return a dict of icon properties. It should return a default set of values if the key does not match a known key. The icon_col value for each row will be passed to this function and the return value used to populate the Icon arguments.

For example:

FontAwesome icon (prefix “fa”) names are available at https://fontawesome.com/ GlyphIcons icons (prefix “glyphicon”) are available at https://www.glyphicons.com/