Scenario Generator

This module contains functionality for generating scenarios.

Specifically, it generates network configurations and action space configurations based on number of hosts and services in network using standard formula.

class nasim.scenarios.generator.ScenarioGenerator

Generates a scenario based on standard formula

For explanation of the details of how scenarios are generated see Scenario Generation Explanation.

Notes

Exploit Probabilities:

Success probabilities of each exploit are determined based on the value of the exploit_probs argument, as follows:

  • exploit_probs=None - probabilities generated randomly from uniform distribution
  • exploit_probs="mixed" - probabilities are chosen from [0.3, 0.6, 0.9] with probability [0.2, 0.4, 0.4] (see Generated Exploit Probabilities for explanation).
  • exploit_probs=float - probability of each exploit is set to value
  • exploit_probs=list[float] - probability of each exploit is set to corresponding value in list

For deterministic exploits set exploit_probs=1.0.

Privilege Escalation Probabilities:

Success probabilities of each privilege escalation are determined based on the value of the privesc_probs argument, and are determined the same as for exploits with the exclusion of the “mixed” option.

Host Configuration distribution:

  1. if uniform=True then host configurations are chosen uniformly at random from set of all valid possible configurations
  2. if uniform=False host configurations are chosen to be correlated (see Correlated Configurations for explanation)
generate(num_hosts, num_services, num_os=2, num_processes=2, num_exploits=None, num_privescs=None, r_sensitive=10, r_user=10, exploit_cost=1, exploit_probs=1.0, privesc_cost=1, privesc_probs=1.0, service_scan_cost=1, os_scan_cost=1, subnet_scan_cost=1, process_scan_cost=1, uniform=False, alpha_H=2.0, alpha_V=2.0, lambda_V=1.0, restrictiveness=5, random_goal=False, base_host_value=1, host_discovery_value=1, seed=None, name=None, step_limit=None, address_space_bounds=None, **kwargs)

Generate the network configuration based on standard formula.

Parameters:
  • num_hosts (int) – number of hosts to include in network (minimum is 3)
  • num_services (int) – number of services running on network (minimum is 1)
  • num_os (int, optional) – number of OS running on network (minimum is 1) (default=2)
  • num_processes (int, optional) – number of processes running on hosts on network (minimum is 1) (default=2)
  • num_exploits (int, optional) – number of exploits to use. minimum is 1. If None will use num_services (default=None)
  • num_privescs (int, optional) – number of privilege escalation actions to use. minimum is 1. If None will use num_processes (default=None)
  • r_sensitive (float, optional) – reward for sensitive subnet documents (default=10)
  • r_user (float, optional) – reward for user subnet documents (default=10)
  • exploit_cost (int or float, optional) – cost for an exploit (default=1)
  • exploit_probs (None, float, list of floats or "mixed", optional) – success probability of exploits (default=1.0)
  • privesc_cost (int or float, optional) – cost for an privilege escalation action (default=1)
  • privesc_probs (None, float, list of floats, optional) – success probability of privilege escalation actions (default=1.0)
  • service_scan_cost (int or float, optional) – cost for a service scan (default=1)
  • os_scan_cost (int or float, optional) – cost for an os scan (default=1)
  • subnet_scan_cost (int or float, optional) – cost for a subnet scan (default=1)
  • process_scan_cost (int or float, optional) – cost for a process scan (default=1)
  • uniform (bool, optional) – whether to use uniform distribution or correlated host configs (default=False)
  • alpha_H (float, optional) – (only used when uniform=False) Scaling/concentration parameter for controlling corelation between host configurations (must be > 0) (default=2.0)
  • alpha_V (float, optional) – (only used when uniform=False) scaling/concentration parameter for controlling corelation between services across host configurations (must be > 0) (default=2.0)
  • lambda_V (float, optional) – (only used when uniform=False) parameter for controlling average number of services running per host configuration (must be > 0) (default=1.0)
  • restrictiveness (int, optional) – max number of services allowed to pass through firewalls between zones (default=5)
  • random_goal (bool, optional) – whether to randomly assign the goal user host or not (default=False)
  • base_host_value (int, optional,) – value of non sensitive hosts (default=1)
  • host_discovery_value (int, optional) – value of discovering a host for the first time (default=1)
  • seed (int, optional) – random number generator seed (default=None)
  • name (str, optional) – name of the scenario, if None one will be generated (default=None)
  • step_limit (int, optional) – max number of steps permitted in a single episode, if None there is no limit (default=None)
  • address_space_bounds ((int, int), optional) – bounds for the (subnet#, host#) address space. If None bounds will be determined by the number of subnets in the scenario and the max number of hosts in any subnet.
Returns:

scenario description
Return type:

Scenario