Source code for plaso.output.kml

"""An output module that writes event with geography data to a KML XML file.

The Keyhole Markup Language (KML) is an XML notation for expressing geographic
annotation and visualization within Internet-based, two-dimensional maps and three-
dimensional Earth browsers.
"""

import codecs

from xml.etree import ElementTree

from plaso.output import manager
from plaso.output import rawpy




class KMLOutputModule(rawpy.NativePythonOutputModule):
    """Output module for a Keyhole Markup Language (KML) XML file."""

    NAME = "kml"
    DESCRIPTION = "Saves events with geography data into a KML format."



    def WriteFieldValues(self, output_mediator, field_values):
        """Writes field values to the output.

        Args:
          output_mediator (OutputMediator): mediates interactions between output
              modules and other components, such as storage and dfVFS.
          field_values (dict[str, str]): output field values per name.
        """
        latitude = field_values.get("latitude")
        longitude = field_values.get("longitude")
        if None in (latitude, longitude):
            return

        # TODO: make description_text KML values.
        description_text = self._GetString(field_values)

        placemark_xml_element = ElementTree.Element("Placemark")

        name_xml_element = ElementTree.SubElement(placemark_xml_element, "name")
        name_xml_element.text = field_values["_event_identifier"]

        description_xml_element = ElementTree.SubElement(
            placemark_xml_element, "description"
        )
        description_xml_element.text = f"{description_text:s}\n"

        point_xml_element = ElementTree.SubElement(placemark_xml_element, "Point")

        coordinates_xml_element = ElementTree.SubElement(
            point_xml_element, "coordinates"
        )
        coordinates_xml_element.text = f"{longitude!s},{latitude!s}"

        # Note that ElementTree.tostring() will appropriately escape the input data.
        output_text = ElementTree.tostring(placemark_xml_element)

        output_text = codecs.decode(output_text, output_mediator.encoding)

        self.WriteText(output_text)




    def WriteFooter(self):
        """Writes the footer to the output."""
        self.WriteText("</Document></kml>")




    def WriteHeader(self, output_mediator):
        """Writes the header to the output.

        Args:
          output_mediator (OutputMediator): mediates interactions between output
              modules and other components, such as storage and dfVFS.
        """
        self.WriteText(
            (
                f'<?xml version="1.0" encoding="{output_mediator.encoding:s}"?>'
                f'<kml xmlns="http://www.opengis.net/kml/2.2"><Document>'
            )
        )




manager.OutputManager.RegisterOutput(KMLOutputModule)