Feat/agile operations

agile_operations/network_infrastructure/queries/device_failure_impact_radius_visualization.gsql

@@ -1,6 +1,26 @@
 CREATE OR REPLACE QUERY device_failure_impact_radius_visualization (
     VERTEX<Device> device
 ) {
+    /*
+  Query Name:
+    device_failure_impact_radius_visualization
+
+  Purpose:
+    1. Find devices that do NOT have an alternative communication path.
+    2. Determine devices that will be impacted if the input device fails.
+    3. Display impacted devices and their interconnections.
+
+  Concept:
+    - If a device has an alternative path (redundant connectivity), it won't fail.
+    - Devices without alternative paths are marked as 'impacted'.
+
+  Inputs:
+    - device: The device whose failure we are analyzing.
+
+  Outputs:
+    - impacted_devices: Devices that will fail if the input device fails.
+    - @@edges_to_display: Edges between impacted devices for visual impact analysis.
+    */
 
     SetAccum<EDGE> @@edges_to_display;
     OrAccum<BOOL> @has_alternative_path;

agile_operations/network_infrastructure/queries/device_failure_impact_radius_visualization_with_subgraph_topology.gsql

@@ -1,6 +1,25 @@
 CREATE OR REPLACE QUERY device_failure_impact_radius_visualization_with_subgraph_topology (
     VERTEX<Device> device
 ) {
+    /*  
+  Query Name:
+    device_failure_impact_radius_visualization_with_subgraph_topology
+
+  Purpose:
+    1. Build the subgraph that contains the input device (based on connectivity).
+    2. Explore and detect devices that have alternative network paths (redundancy).
+    3. Identify devices that will be impacted (fail) if the given device fails.
+    4. Collect and return visualization data: subgraph topology and failure impact edges.
+
+  Input:
+    - device: The starting device whose failure impact we want to analyze.
+
+  Output:
+    - all_vertices_in_subgraph: Devices in the connectivity region of the input device.
+    - @@edges_to_display_in_subgraph: Edges representing overall subgraph structure.
+    - impacted_devices: Devices that do not have an alternative path (will fail).
+    - @@edges_to_display: Edges among impacted devices (failure impact radius).
+    */
     SetAccum<EDGE> @@edges_to_display;
     SetAccum<EDGE> @@edges_to_display_in_subgraph;
     OrAccum<BOOL> @has_alternative_path;

agile_operations/network_infrastructure/queries/downstream_device_topology_visualization.gsql

@@ -2,6 +2,29 @@ CREATE OR REPLACE QUERY downstream_device_topology_visualization (
     VERTEX<Device> device,
     UINT k_hop_switch_limit = 3
 ) {
+    /*
+  Query Name:
+    downstream_device_topology_visualization
+
+  Purpose:
+    Visualize the downstream topology from a given device, following the device hierarchy:
+      Router → Firewall → Switch → Server
+    Also explores multiple downstream Switch layers (k-hop depth traversal).
+
+  Key Features:
+    ✔ Identifies all downstream devices classified by device type.
+    ✔ Follows device hierarchy dynamically based on input device type.
+    ✔ Limits multi-hop Switch traversal using k_hop_switch_limit.
+    ✔ Returns devices and connecting edges for visualization.
+
+  Inputs:
+    - device: Starting device.
+    - k_hop_switch_limit: Maximum depth for switch-to-switch iterations (default = 3).
+
+  Outputs:
+    - impacted_devices: All discovered downstream devices.
+    - @@edges_to_display: Edges to visualize the downstream network path.
+*/
 
     SetAccum<VERTEX> @@impacted_devices;
     SetAccum<EDGE> @@edges_to_display;

agile_operations/network_infrastructure/queries/explore_topology_from_all_router.gsql

@@ -1,4 +1,18 @@
 CREATE OR REPLACE QUERY explore_topology_from_all_router () {
+    /*
+  Query Name:
+    explore_topology_from_all_router
+
+  Purpose:
+    Visualize the entire network topology by:
+      - Retrieving all devices in the graph
+      - Exploring all connected edges using Connect_To
+      - Displaying both devices and their connections
+
+  Outputs:
+    - all_devices_with_connections: List of devices connected via Connect_To edges
+    - @@edges_to_display: All edges among connected devices for visualization
+*/
     SetAccum<EDGE> @@edges_to_display;
 
     all_devices = {Device.*};

agile_operations/network_infrastructure/queries/explore_topology_from_multiple_routers.gsql

@@ -1,4 +1,27 @@
 CREATE OR REPLACE QUERY explore_topology_from_multiple_routers (SET<VERTEX<Router>> starter_router_set) {
+    /*
+  Query Name:
+    explore_topology_from_multiple_routers
+
+  Purpose:
+    Visualizes the downstream network topology starting from one or more routers.
+    Traverses devices in this structured order:
+      Router → Firewall → Switch → Server
+
+  Key Features:
+    ✔ Uses BFS to exhaustively discover downstream switches.
+
+  Inputs:
+    starter_router_set — Set of router vertices to start the topology exploration.
+      If empty, all routers in the graph are selected automatically.
+
+  Outputs:
+    - all_visited_router_devices — Routers connected to input routers via Device_Has_Type
+    - all_visited_firewalls — First downstream stage (Firewalls)
+    - all_visited_switches — All connected Switches (multi-hop via BFS)
+    - all_visited_servers — Downstream Servers
+    - @@edges_to_display — All edges to display full topology
+*/
     OrAccum<BOOL> @visited;
     SetAccum<EDGE> @@edges_to_display;
 

agile_operations/network_infrastructure/queries/explore_topology_from_one_router.gsql

@@ -1,4 +1,28 @@
 CREATE OR REPLACE QUERY explore_topology_from_one_router (VERTEX<Router> starter_router) {
+    /*
+  Query Name:
+    explore_topology_from_one_router
+
+  Purpose:
+    Visualizes the downstream network topology starting from a single router.
+    Traverses devices in this structured order:
+      Router → Firewall → Switch → Server
+
+  Key Features:
+    ✔ Discovers all downstream Firewalls and Switches (including bypass paths)
+    ✔ Uses BFS to find all connected Switches (multi-hop exploration)
+    ✔ Captures all edges forming the full topology view
+
+  Input:
+    starter_router — A single Router vertex that acts as the exploration starting point.
+
+  Outputs:
+    - all_visited_router_devices — Devices directly connected to starter router via Device_Has_Type
+    - all_visited_firewalls — Firewalls downstream of the router
+    - all_visited_switches — All discovered Switches (including BFS expansion)
+    - all_visited_servers — Servers connected downstream of switches
+    - @@edges_to_display — Complete collection of edges forming the explored topology
+*/
     OrAccum<BOOL> @visited;
     SetAccum<EDGE> @@edges_to_display;
 

agile_operations/network_infrastructure/queries/find_events_by_impacted_device_and_time_range.gsql

@@ -4,6 +4,35 @@ CREATE OR REPLACE QUERY find_events_by_impacted_device_and_time_range (
     DATETIME end_time,
     BOOL show_event_types_vis = FALSE
 ) {
+    /*
+  Query Name:
+    find_events_by_impacted_device_and_time_range
+
+  Purpose:
+    Finds and visualizes events linked to a specific device within a given time range.
+    Also traces time hierarchy (Minute → Hour → Date → Month → Year) for chronological visualization.
+    Optionally includes detailed event type information (Alert, Incident, and their classifications).
+
+  Key Features:
+    ✔ Filters events by impacted device and time window.
+    ✔ Visualizes full time-based hierarchy for each event.
+    ✔ Option to include related event type, alert, and incident classifications.
+    ✔ Collects all traversal edges for easy visualization.
+
+  Inputs:
+    input_device — The impacted device to search events for.
+    start_time — Minimum timestamp of events to include.
+    end_time — Maximum timestamp of events to include.
+    show_event_types_vis — (Optional) If TRUE, includes event/alert/incident types.
+
+  Outputs:
+    - linked_events_within_time — Events impacting the input device within the time range.
+    - linked_time_date_minute / hour / date / month / year — Chronologically related time vertices.
+    - linked_event_types — Event classification (if enabled).
+    - linked_alerts_within_time, linked_incidents_within_time — Associated alerts and incidents.
+    - linked_alert_types, linked_incident_types — Alert/Incident categories.
+    - @@edges_to_display — All edges used to visualize event and time relationships.
+*/
     SetAccum<EDGE> @@edges_to_display;
     input_device_set = {input_device};
 

agile_operations/network_infrastructure/queries/find_events_by_time_range_and_event_type.gsql

@@ -3,6 +3,30 @@ CREATE OR REPLACE QUERY find_events_by_time_range_and_event_type (
     DATETIME end_time,
     STRING input_event_type_filter = ""
 ) {
+    /*
+  Query Name:
+    find_events_by_time_range_and_event_type
+
+  Purpose:
+    Retrieves events occurring within a specific time range and optionally filters by event type.
+    Additionally, collects related metadata such as impacted devices, alert types,
+    and incident types for comprehensive event analysis.
+
+  Inputs:
+    start_time — Minimum datetime filter for event retrieval.
+    end_time — Maximum datetime filter for event retrieval.
+    input_event_type_filter — (Optional) Filters by event type. If empty, all types are included.
+
+  Outputs:
+    - selected_events_with_info:
+        • event_id — Event identifier
+        • event_time — Timestamp of the event
+        • event_type — Type classification (Security, System, Network, etc.)
+        • event_alert_type — Enriched alert type data (if any)
+        • event_incident_type — Enriched incident type data (if any)
+        • impacted_devices_list — Devices affected by this event
+
+*/
     MaxAccum<STRING> @event_type;
     MaxAccum<STRING> @incident_type;
     MaxAccum<STRING> @alert_type;

agile_operations/network_infrastructure/queries/find_potential_incident_source_of_event_by_time.gsql

@@ -3,6 +3,31 @@ CREATE OR REPLACE QUERY find_potential_incident_source_of_event_by_time (
     INT max_radius = 3,
     INT num_seconds_before_event_start = 3600
 ) {
+    /*
+  Query Name:
+    find_potential_incident_source_of_event_by_time
+
+  Purpose:
+    Identifies potential root-cause incidents for a given input event by:
+      • Retrieving impacted devices of the event
+      • Exploring connected devices within a specified hop radius
+      • Scanning for past incident events within a defined timeframe
+      • Linking discovered incidents with their incident types
+
+  Inputs:
+    input_event — The event vertex to investigate potential source incidents for
+    max_radius — Max number of hops allowed for device connectivity exploration (default: 3)
+    num_seconds_before_event_start — Time window (in seconds) before input_event.timestamp to search for related incidents (default: 3600)
+
+  Outputs:
+    • input_event_set — Original event input
+    • related_devices_within_radius — Connected devices marked by event radius
+    • incident_events_from_related_devices — Incident events found in time range
+    • incidents_from_related_devices — Linked incident entities
+    • incident_types_of_related_devices — Final categorized incident types
+    • @@edges_to_display — All traversal edges for visualization/UI mapping
+
+*/
     SetAccum<VERTEX> @@related_devices_set;
     SetAccum<EDGE> @@edges_to_display;
     MinAccum<DATETIME> @@end_time_accum;

agile_operations/network_infrastructure/queries/find_potential_related_events_from_incident_by_time.gsql

@@ -3,6 +3,35 @@ CREATE OR REPLACE QUERY find_potential_related_events_from_incident_by_time (
     INT max_radius = 3,
     INT num_seconds_from_incident_start = 3600
 ) {
+    /*
+  Query Name:
+    find_potential_related_events_from_incident_by_time
+
+  Purpose:
+    Identifies events that could be potentially related to a given input incident.
+    It does so by:
+      • Discovering all devices impacted by the incident
+      • Expanding outward through connected devices within max_radius hops
+      • Searching for events (Alerts, Incidents) that occurred within a time window
+        starting from the incident occurrence time
+      • Classifying and linking detected related alerts and incidents with types
+
+  Inputs:
+    input_incident — Starting Incident vertex for event correlation analysis
+    max_radius — Max number of hops to discover connected impacted devices (default: 3)
+    num_seconds_from_incident_start — Time window (in seconds) after incident start to look for related events (default: 3600)
+
+  Outputs:
+    • input_incident_set — Original input incident
+    • linked_event — Event directly linked to input incident
+    • impacted_devices_within_radius — All devices reached via radius traversal
+    • alerts_from_impacted_devices — Related Alerts discovered in time range
+    • incidents_from_impacted_devices — Related Incidents discovered
+    • alert_types_of_impacted_devices — Enriched alert category details
+    • incident_types_of_impacted_devices — Enriched incident category details
+    • @@edges_to_display — All collected edges for UI / Graph visualization
+
+*/
     SetAccum<VERTEX> @@impacted_devices_set;
     SetAccum<EDGE> @@edges_to_display;
     MinAccum<DATETIME> @@start_time_accum;

agile_operations/network_infrastructure/queries/find_unsecured_servers_visualization.gsql

@@ -1,4 +1,27 @@
-CREATE OR REPLACE QUERY find_unsecured_servers_visualization (UINT k_hop_switch_limit = 3) { 
+CREATE OR REPLACE QUERY find_unsecured_servers_visualization (UINT k_hop_switch_limit = 3) {
+    /*
+  Query: find_unsecured_servers_visualization
+
+  Purpose:
+    Visualizes unsecured network paths from Routers to Servers through Switches.
+    It identifies Servers that are reachable via Switches without passing through security devices (like Firewalls).
+
+  What It Does:
+    • Finds all Routers, Switches, and Servers.
+    • Traverses paths from Routers → Switches → Servers using Connect_To edges.
+    • Expands through Switch-to-Switch connections up to 'k_hop_switch_limit' hops.
+    • Collects all involved vertices and edges for visualization.
+
+  Key Outputs:
+    - routers_to_display     → Starting routers
+    - switches_to_display    → Switches on the unsecured path
+    - servers_to_display     → Potentially unsecured servers
+    - edges_to_display       → All traversal edges for graph visualization
+
+  Parameter:
+    k_hop_switch_limit → Maximum number of Switch-to-Switch traversal hops (default: 3)
+
+*/
 
     SetAccum<VERTEX> @@routers_to_display;
     SetAccum<VERTEX> @@switches_to_display;

agile_operations/network_infrastructure/queries/incident_impact_by_max_radius.gsql

@@ -2,6 +2,31 @@ CREATE OR REPLACE QUERY incident_impact_by_max_radius (
     VERTEX<Incident> input_incident,
     INT max_radius = 4
 ) {
+    /*
+  Query: incident_impact_by_max_radius
+
+  Purpose:
+    Determines how far an incident can propagate through the network.
+    It finds all devices that may be impacted by a given incident,
+    up to a specified hop limit (max_radius).
+
+  What It Does:
+    1. Gets the Event linked to the input Incident.
+    2. Finds devices directly impacted by the incident (radius 0).
+    3. Iteratively explores additional devices connected via Connect_To edges,
+       marking each with its hop distance (incident_radius).
+    4. Collects all impacted devices and edges for visualization.
+
+  Key Outputs:
+    - input_incident_set → The provided incident
+    - linked_event → Event associated with the incident
+    - impacted_devices_within_radius → All potentially impacted devices
+    - @@edges_to_display → Edges used during traversal
+
+  Parameters:
+    max_radius → Max number of hops to explore propagation (default: 4)
+
+*/
     SetAccum<VERTEX> @@impacted_devices_set;
     SetAccum<EDGE> @@edges_to_display;
     OrAccum<BOOL> @visited;

agile_operations/network_infrastructure/queries/top_k_devices_with_most_alerts.gsql

@@ -1,4 +1,23 @@
 CREATE OR REPLACE QUERY top_k_devices_with_most_alerts (INT k) {
+    /*
+  Query: top_k_devices_with_most_alerts
+
+  Purpose:
+    Identifies the devices that are associated with the highest number of alerts.
+    Useful for prioritizing monitoring, troubleshooting, and risk assessment.
+
+  What It Does:
+    1. Counts how many alerts are linked to each Event.
+    2. Aggregates alert counts from Events to connected Devices.
+    3. Sorts devices by total alert frequency in descending order.
+    4. Returns the top K most alert-prone devices.
+
+  Key Outputs:
+    - devices → Top K devices with highest aggregated alert_count
+
+  Parameter:
+    k → Number of devices to return (top K)
+*/
 
     SumAccum<INT> @alert_count;