The Firewall Shell Standard is a project used to define a standard for all Firewall Shells that integrate with CloudShell. The standard defines the Shell’s data model, commands and a set of guidelines that should be followed in Firewall Shells development and customization.
| Version | Date | Notes |
|---|---|---|
| 3.0.2 | 2018-05-01 | 1) Added SNMP V3 Authentication Protocol attribute. 2) Added SNMP V3 Privacy Protocol attribute. |
| 3.0.1 | 2017-07-03 | Added a Model Name attribute on the root resource |
| 3.0.0 | 2017-01-23 | 1) Added letters to resources address. 2) Changed the type of the following attributes to "Password": "SNMP Read Community", "SNMP Write Community" and "SNMP V3 Password". Those changes are NOT backwards compatible. |
| 2.0.0 | 2016-08-16 | 1) Added a new attribute named “CLI TCP Port” on the root model. That attribute will be filled in by the administrator (optional). 2) The "Configuration Type" input in the Save and Restore command is now not mandatory, the default value if kept empty is Running. 3) Descriptions were added to the attributes, commands and command inputs (only commands visible in the UI). 4) A “Health check” command was added. This command performs checks on the device that validates that the Shell can work. In a firewall device this checks usually include connectivity check for the protocols used by the Shell. 5) Removed the attribute “Protocol Type” from the standard. 6) Added the attributes “Enable SNMP” and “Disable SNMP” on the root model. Those attribute will allow automatic configuration of SNMP before and after the execution of the Autoload command which requires SNMP. 7) The value of the attribute “Bandwidth” is now in MB instead of Bytes. 8) Added orchestration_save and orchestration_restore commands according to the Save and Restore Orchestration Standard. Those commands wrap the Shell’s Save and Restore commands with a standard interface to be used by the Sandbox orchestration. 9) The command name and command input names are now defined in the standard. Prior to this standard version only the command alias and command input aliases were defined. 10) The inputs of the load_firmware command were changed and alligned with the inputs of the restore command. 11) The expected syntax of the path and folder_path inputs of the restore, load_firmware and save commands in case of FTP protocol was clarified. The 9th and 10th items aren't backwards compatible and will require modification of any existing automation which calls the Shell’s commands. However, upcoming shells will still have the old commands available as hidden command so the shells themselves will remain backwards compatible until their next major verion. |
| 1.0.0 | 2016-06-23 | First release of the Firewall Shell Standard |
A Firewall Shell should support all Firewall devices with the same Vendor and OS. For example a correct shell granularity will be “Cisco ASA Shell” and not “Cisco ASA 5500 Shell”.
Each released Shell should have a list of certified models. Model certification can be done only by Quali’s engineering, and validates that all the Shell’s capabilities are working for a specific model. The Shell should also work for non-certified models, and in case some gaps are found a new version of the Shell will be released with the gaps addressed and the model certified.
All Firewall Shells share the same generic data model, except the model of the root level which is different per each Shell. The data model shouldn’t be modified. The attributes associated with those generic models are also shared by all firewall Shells and their values are populated by the driver. It is allowed to add custom attributes to any resource level, and it isn’t allowed to remove attributes from any level.
The Firewall Shell version follows Semantic Versioning Guidelines (see details in http://semver.org). In short, the version structure is Major.Minor.Patch, for example “1.0.2”. A Path version is promoted when making backward-compatibility bug fixes, a Minor version is promoted when adding functionality in a backwards-compatible manner and a Major version is promoted when making a backwards incompatible changes.
In case the Firewall shell is written in Python and has dependencies to Python packages (that follow Semantic Versioning Guidelines) the dependency should be to a range of Patch versions, for example to “cloudshell-firewall-cisco-asa 2.1.X”. The dependency to cloudshell-automation-api will be to the latest Patch version (cloudshell-automation-api package version is of the format “CloudShell_Version.X”, for example 7.0.X”).
The firewall shell standard supports Firewall devices.
- Firewall
- Chassis
- Module
- Port
- Sub Module
- Port
- Port
- Power Port
- Module
- Port Channel
- Family: Firewall, Model: Cisco ASA Firewall
- Family: Chassis, Model: Generic Chassis
- Family: Module, Model: Generic Module
- Family: Port, Model: Generic Port
- Family: Sub Module, Model: Generic Sub Module
- Family: Port, Model: Generic Port
- Family: Port, Model: Generic Port
- Family: Power Port, Model: Generic Power Port
- Family: Module, Model: Generic Module
- Family: Port Channel, Model: Generic Port Channel
| Family | Rules |
|---|---|
| Firewall | Searchable |
| Chassis | Searchable |
| Module | Searchable |
| Sub Module | Searchable |
| Port | Searchable, Connectable, Locked By Default |
| Port Channel | Searchable, Connectable, Locked By Default |
| Power Port | Searchable, Connectable, Locked By Default |
The Port Channel is a logical entity that allows grouping of several physical ports to create one logical link. In CloudShell, all the ports configured to the port channel shouldn’t be “physically connected” and instead the port channel resource will be “physically connected”. The names of all the ports configured to the port channel will appear in the “Associated Ports” attribute on the port channel. Addition or removal of ports from the port channel will require execution of Autoload to update the resource representation in CloudShell and a manual update of the physical connections in CloudShell by the administrator.
| Family | Model | Resource Name | Resource Address |
|---|---|---|---|
| Firewall | [Vendor] [OS] Firewall | (user defined) | (user defined - IP) |
| Chassis | Generic Chassis | Chassis[ID] | CH[ID] |
| Module | Generic Module | Module[ID] | MO[ID] |
| Sub Module | Generic Sub Module | SubModule[ID] | SM[ID] |
| Port | Generic Port | The name of the interface as appears in the device. Any “/” character is replaced with “-“, spaces trimmed.] | PO[ID] |
| Port Channel | Generic Port Channel | The name of the interface as appears in the device. Any “/” character is replaced with “-“, spaces trimmed. | PC[ID] |
| Power Port | Generic Power Port | PP[ContainerID][ID] | PP[ContainerID][ID] |
Note: The [ID] for each sub-resource is taken from the device itself (corresponds to the names defined in the device).
- Attributes which aren’t relevant to a devices won’t be populated by the driver.
- All attributes which aren't user-input are "read only"
- The attribute rules are as follows - all attributes which are user input should have the rule "Configuration" enabled, all attributes which aren't user input should have the rules "Settings" and "Available For Abstract Resources" enabled.
- It is possible to customize the attribute rules selection after importing the Shell to CloudShell.
- Attributes shouldn’t be removed.
- Custom attributes can be added to any resource level.
- All attributes are of type String unless mentioned otherwise
- Attributes associated with the family level can't be changed in the shelldefinition.yaml of the shell and are commonly used in abstract resources.
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| User | String | Yes | No | |
| Password | Password | Yes | No | |
| Enable Password | Password | Yes | The enable password is required by some CLI protocols such as Telnet and is required according to the device configuration. | No |
| System Name | String | No | A unique identifier for the device, if exists in the device terminal/os. | Yes |
| Contact Name | String | No | The name of a contact registered in the device. | Yes |
| OS Version | String | No | Version of the Operating System. | Yes |
| Vendor | String | No | The name of the device manufacture. | Yes |
| Location | String | No | The device physical location identifier. For example Lab1/Floor2/Row5/Slot4. | Yes |
| Model | String | No | The device model. This information is typically used for abstract resource filtering. | Yes |
| SNMP Read Community | Password | Yes | The SNMP Read-Only Community String is like a password. It is sent along with each SNMP Get-Request and allows (or denies) access to device. | No |
| SNMP Write Community | Password | Yes | The SNMP Write Community String is like a password. It is sent along with each SNMP Set-Request and allows (or denies) chaning MIBs values. | No |
| SNMP V3 User | String | Yes | Relevant only in case SNMP V3 is in use. | No |
| SNMP V3 Password | Password | Yes | Relevant only in case SNMP V3 is in use. | No |
| SNMP V3 Private Key | String | Yes | Relevant only in case SNMP V3 is in use. | No |
| SNMP Version | String | Yes | The version of SNMP to use. Possible values are v1, v2c and v3. | No |
| SNMP V3 Authentication Protocol | String | Yes | Possible 3 optionS are: No Authentication Protocol, MD5, SHA. | No |
| SNMP V3 Privacy Protocol | String | Yes | Possible 6 options: No Privacy Protocol, DES, 3DES-EDE, AES-128, AES-192, AES-256. | No |
| Console Server IP Address | String | Yes | The IP address of the console server, in IPv4 format. | No |
| Console User | String | Yes | No | |
| Console Port | Numeric | Yes | The port on the console server, usually TCP port, which the device is associated with. | No |
| Console Password | Password | Yes | No | |
| CLI Connection Type | Lookup | Yes | The CLI connection type that will be used by the driver. Possible values are Auto, Console, SSH, Telnet and TCP. If Auto is selected the driver will choose the available connection type automatically. Default value is Auto. | No |
| Power Management | Boolean | Yes | Used by the power management orchestration, if enabled, to determine whether to automatically manage the device power status. Enabled by default. | No |
| Backup Location | String | Yes | The location in which configuration files will be saved in case no backup location input is passed to the Save command. | No |
| Sessions Concurrency Limit | Numeric | Yes | The maximum number of concurrent sessions that the driver will open to the device. Default is 1 (no concurrency). | No |
| CLI TCP Port | String | Yes | TCP Port to user for CLI connection. If kept empty a default CLI port will be used based on the chosen protocol, for example Telnet will use port 23. | No |
| Enable SNMP | Boolean | Yes | If set to True and SNMP isn’t enabled yet in the device the Shell will automatically enable SNMP in the device when Autoload command is called. SNMP must be enabled on the device for the Autoload command to run successfully. True by default. | No |
| Disable SNMP | Boolean | Yes | If set to True SNMP will be disabled automatically by the Shell after the Autoload command execution is completed. False by default. | No |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| Model | String | No | The device model. This information is typically used for abstract resource filtering. | No |
| Serial Number | String | No | No | |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| Model | String | No | The device model. This information is typically used for abstract resource filtering. | No |
| Version | String | No | The firmware version of the resource. | No |
| Serial Number | String | No | No | |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| Model | String | No | The device model. This information is typically used for abstract resource filtering. | No |
| Version | String | No | The firmware version of the resource. | No |
| Serial Number | String | No | No | |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| MAC Address | String | No | No | |
| L2 Protocol Type | String | No | The L2 protocol type configured on the interface. For example POS, Serial. | No |
| IPv4 Address | String | No | No | |
| IPv6 Address | String | No | No | |
| Port Description | String | No | The description of the port as configured in the device. | No |
| Bandwidth | Numeric | No | The current interface bandwidth, in MB. | No |
| MTU | Numeric | No | The current MTU configured on the interface. | No |
| Duplex | Lookup | No | The current duplex configuration on the interface. Possible values are Half or Full. | No |
| Adjacent | String | No | The adjacent device (system name) and port, based on LLDP or CDP protocol. | No |
| Auto Negotiation | Boolean | No | The current auto negotiation configuration on the interface. | No |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| Associated Ports | String | No | Ports associated with this port channel. The value is in the format “[portResourceName],…”, for example “GE0-0-0-1,GE0-0-0-2” | No |
| IPv4 Address | String | No | No | |
| IPv6 Address | String | No | No | |
| Port Description | String | No | The description of the port as configured in the device. | No |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
| Attribute Name | Data Type | User input? | Description | Family Attribute? |
|---|---|---|---|---|
| Model | String | No | The device model. This information is typically used for abstract resource filtering. | No |
| Serial Number | String | No | No | |
| Version | String | No | The firmware version of the resource. | No |
| Port Description | String | No | The description of the port as configured in the device. | No |
| Model Name | String | No | Automatically populated model name that will be presented in the Sandbox diagram | Yes |
Below is a list of all the commands that will be part of the standard Shell, their names and interfaces. Each firewall Shell that will be released by Quali’s engineering will include implementation for all those commands.
When creating a new shell according to the standard it is OK not to implement all commands and/or implement additional command, but a command with a functionality that fits one of the predefined list commands should be implemented according to the standard.
Command outputs: On failure an exception containing the error will be thrown and the command will be shown as failed. A failure is defined as any scenario in which the command didn’t complete its expected behavior, regardless if the issue originates from the command’s input, device or the command infrastructure itself. On success the command will just return as passed with no output. The “Autoload” command has a special output on success that CloudShell reads when building the resource hierarchy. The “Save” command will return an output on success with the file name (exact syntax below).
def get_inventory (self, context)This function queries the device, discovers it's specification and structure and autoload it into CloudShell. When new resource is created Cloudshell asks the user to specify some user input (i.e user name & psasword) and then it calls the get_inventory function.
The standard recommended way of communicating and discovering the device is via SNMP protocol and therefore this command requires SNMP to be configured in the device. In case SNMP isn’t configured in the device and the attribute “Enable SNMP” on the root model is set to True the Autoload command will configure SNMP in the device. If the attribute “Disable SNMP” on the root model is set to True the Autoload command will disable the SNMP in the device once the discovery of the device is completed. In case SNMP isn't configured and "Enable SNMP" on the root model is set to false a relevant error message will be displayed.
System command, it has no display name
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | context | - | object | system parameter | object of type AutoLoadCommandContext which includes API connectivity details and the details of the resource including attributes that the user entered during the resource creation. |
| Output | AutoLoadDetails | - | object | Yes | object of type AutoLoadDetails with the discovered resource structure and attributes. |
def save (folder_path, configuration_type)Create and save a configuration file
Save
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | folder_path | Folder Path | string | No | The path in which the configuration file will be saved. Won't include the name of the file but only the folder. This input is optional and in case this input is empty the value will be taken from the "Backup Location" attribute on the root resource. The path should include the protocol type, for TFTP use "tftp://asdf", for FTP use "ftp://username:password@server_address/folder1/file1.bin". |
| Input | configuration_type | Configuration Type | string | No | The type of configuration that will be saved. Possible values are StartUp and Running. If kept empty the default configuration type that will be used is Running. |
| Output | string | Yes | . The configuration file name should be “[ResourceName]-[ConfigurationType]-[DDMMYY]-[HHMMSS]”. |
def restore (path, configuration_type, restore_method)Restore a configuration file
Restore
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | path | Path | string | Yes | The path to the configuration file, including the configuration file name. The path should include the protocol type, for TFTP use "tftp://asdf", for FTP use "ftp://username:password@server_address/folder1/file1.bin". |
| Input | configuration_type | Configuration Type | string | No | The configuration type to restore. Possible values are StartUp and Running. If kept empty the configuration type that will be restored is Running. |
| Input | restore_method | Restore Method | string | No | The restore method to use when restoring the configuration file. Possible Values are Append and Override. If kept empty the restore method will be Override. |
def load_firmware (path)Loads a firmware onto the device
This command is CLI based and applies to the whole device, also in case of multi-chassis device.
Load Firmware
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | path | Path | string | Yes | The path to the firmware file, including the firmware file name. The path should include the protocol type, for TFTP use "tftp://asdf", for FTP use "ftp://username:password@server_address/folder1/file1.bin". |
def run_custom_command (custom_command)Executes any custom command entered in the input on the device.
Run Custom Command
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | custom_command | Custom Command | string | Yes | The command to execute. Note that commands that require a reponse aren't supported. |
def run_custom_command (custom_command)Executes any custom config command entered in the input on the device.
This command should be hidden from the UI.
Run Custom Config Command
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | custom_command | Custom Command | string | Yes | The command to execute. Note that commands that require a reponse aren't supported. |
def shutdown()Sends a graceful shutdown to the device.
Not all devices support a shutdown command. In such cases the command just won’t be implemented.
Shutdown
No input parameters.
def health_check()Performs checks on the device that validates that the Shell can work. In a firewall device this checks usually include connectivity check for the protocols used by the Shell. The healtcheck result will be visible in the resource live status and command output.
In case the performed checks fail the live status of the resource should be "Error" and both the live status description and the output of the command should be "Health check on resource [root_resource_name] failed". In case all performed checks passed the live status of the resource should be "Online" and both the live status description and the output of the command should be "Health check on resource [root_resource_name] passed". CLI check is the check that is currently supported by the networking devices.
Health Check
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Output | string | Yes | The health check result |
def orchestration_save(mode="shallow", custom_params = null)Based on the Orchestration Save and Restore Standard - https://github.com/QualiSystems/sandbox_orchestration_standard/blob/master/save%20%26%20restore/save%20%26%20restore%20standard.md The command wraps the Save command with a standard interface that will be used by the Sandbox orchestration. This command will call the Save command which will create a configuration file. The command should be hidden from the UI. In case there is no folder_path input and the attribute "Backup Location" on the root model is empty the command should throw an error.
orchestration_save
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | mode | mode | string | Yes | The save mode. Possible values are "Shallow" and "Deep". In a firewall device both modes will have the same behavior of saving a configuration file. |
| Input | custom_params | custom_params | string | Yes | A JSON data structure with optional parameters. If no parameters are passed the defaults defined on the root resource and in the Save command will be used. |
| Output | saved_artifact_info | saved_artifact_info | string | Yes | A composite data structure that represents the details of the snapshot. |
An example for the "custom_params" input:
{
"custom_params": {
"configuration_type" : "StartUp"
"folder_path" : "tftp://10.0.0.1/folder1"
}
}An example for the "saved_artifact_info" output:
{
"saved_artifact_info": {
"resource_name": "CiscoNXOSSwitch1",
"resource_id" : "5F2EAA6C-E3FD-4DF0-8E2D-F05C81D61631",
"created_date": "3577-04-27T00:17:48.819Z",
"restore_rules": {
"requires_same_resource": true
},
"saved_artifact" :{
"artifact_type": "tftp",
"identifier": "/folder1/CiscoNXOSSwitch1-Running-080816-13:20:53",
"server": "server1"
}
}
}The artifact types supported by firewall orchestration_save command are "ftp", "tftp" and "filesystem". The "requires_same_resource" restore rule for firewall devices is always True.
def orchestration_restore(saved_artifact_info, custom_params = null)Based on the Orchestration Save and Restore Standard - https://github.com/QualiSystems/sandbox_orchestration_standard/blob/master/save%20%26%20restore/save%20%26%20restore%20standard.md The command wraps the Restore command with a standard interface that will be used by the Sandbox orchestration. This command will call the Save command which will create a configuration file. The command should be hidden from the UI. In case the saved artifact type is FTP the FTP credentials are saved on the FTP resource, so the orchestration_restore command will access the FTP resource to get them and pass them to the Restore command.
orchestration_restore
| Input / Output | Parameter | Alias | Data Type | Required | Description |
|---|---|---|---|---|---|
| Input | saved_artifact_info | saved_artifact_info | string | Yes | A composite data structure that represents the details of the snapshot. The value that will be passed as input must be the same as the exact value that the save function returned. |
| Input | custom_params | custom_params | string | Yes | A JSON data structure with optional parameters. If no parameters are passed the defaults defined on the root resource and in the Restore command will be used. |
An example for the "custom_params" input:
{
"custom_params": {
"path" : "tftp://10.0.0.1/folder1"
"restore_method" : "Append"
"configuration_type" : "StartUp"
}
}An example for the "saved_artifact_info" input:
{
"saved_artifact_info": {
"resource_name": "CiscoASAFirewall1",
"resource_id" : "5F2EAA6C-E3FD-4DF0-8E2D-F05C81D61631",
"created_date": "3577-04-27T00:17:48.819Z",
"restore_rules": {
"requires_same_resource": true
},
"saved_artifact" :{
"artifact_type" : "ftp",
"ftp_resource" : "ftp_srv1",
"identifier": "/folder1/CiscoNXOSSwitch1-Running-080816-13:20:53"
}
}
}The artifact types supported by firewall orchestration_restore command are "ftp", "tftp" and "filesystem". The "requires_same_resource" restore rule for firewall devices is always True.