orchestrator.py

orchestrator.py Orchestrator

This document describes the detailed step-by-step process of how the Orchestrator class works, including the specific methods, classes, and functions used at each step, particularly when it is launched by the Bjorn application via orchestrator.run().

Initialization and Start of Orchestrator

Importing Modules

The orchestrator imports several modules, including:

• Standard libraries: json, importlib, time, logging, sys, threading, datetime
• Custom modules: NmapVulnScanner, shared_data, Logger

Creating Orchestrator Instance

• An instance of the Orchestrator class is created.
• Attributes such as shared_data, actions, standalone_actions, failed_scans_count, network_scanner, and last_vuln_scan_time are initialized.
• The load_actions method is called to load actions from the configuration file.
• A semaphore is initialized to limit the number of active threads to 10.

Orchestrator Class

__init__ Method

Purpose: Initializes the orchestrator. Key Steps:

1. Initializes various attributes including shared data, actions lists, scan counters, and scanners.
2. Loads actions from a configuration file.
3. Sets up a semaphore for managing concurrent threads.

load_actions Method

Purpose: Loads all actions from the actions configuration file. Key Steps:

1. Reads the configuration file containing action definitions.
2. Iterates through each action and delegates loading to specific methods (load_scanner, load_nmap_vuln_scanner, load_action).

load_scanner Method

Purpose: Loads and initializes the network scanner module.

load_nmap_vuln_scanner Method

Purpose: Loads the Nmap vulnerability scanner module.

load_action Method

Purpose: Loads a specific action from the configuration file. Key Steps:

1. Imports the required module for the action.
2. Instantiates the action class and sets necessary attributes.

execute_action Method

Purpose: Executes an action on a specified target. Key Steps:

1. Checks if the required port for the action is open.
2. Handles retry logic for previously successful or failed actions.
3. Executes the action and updates the status in shared data based on the result.

execute_standalone_action Method

Purpose: Executes a standalone action not tied to specific network targets. Key Steps:

1. Initializes standalone action data if not present.
2. Handles retry logic for successful or failed standalone actions.
3. Executes the standalone action and updates the status in shared data.

run Method

Purpose: Main loop to continuously execute actions. Key Steps:

1. Reads current data from shared data file.
2. Iterates over actions and executes them on eligible targets.
3. Updates shared data with the results of action executions.
4. Initiates network scans if no actions were executed.
5. Periodically performs vulnerability scans based on configured intervals.

Detailed Execution Flow when orchestrator.run() is called

Step 1: Read Current Data

• Reads the current state of network data from the shared data source to determine the targets for action execution.

Step 2: Iterate Over Actions

• Loops through each predefined action to determine which need to be executed.
• Checks the list of targets and evaluates whether the action should be performed based on the target's status.

Step 3: Execute Actions

• For each target-action combination:
  • Checks if the action's port is open.
  • Evaluates retry logic based on previous success or failure timestamps and configured retry delays.
  • Executes the action and updates the status in shared data.
  • Ensures dependent child actions are executed in the correct order.

Step 4: Update Data

• Writes changes back to the shared data to ensure the latest state is saved.

Step 5: Handle Idle State and Network Scans

• If no actions are executed, sets status to "IDLE".
• Initiates a network scan to discover new targets.
• Enters an idle state if no new targets are found, waiting before retrying.

Step 6: Perform Vulnerability Scans

• Periodically checks if it is time to perform a vulnerability scan based on the configured interval.
• Executes vulnerability scans on alive targets and updates their status accordingly.

Summary

The Orchestrator class is the heuristic AI component responsible for coordinating and executing various network scanning and actions. It manages the loading and execution of actions, handles retries for successful and failed actions, continuously scans for new targets, and ensures actions are executed in a logical order. The orchestrator updates statuses and logs events for maintainability and debugging, ensuring smooth operation within the Bjorn application framework.