Developer Guide - Skybox Security

Skybox

Developer Guide

10.1.500

Revision: 11

Proprietary and Confidential to Skybox Security. © 2020 Skybox Security, Inc. All rights reserved.

Due to continued product development, the information contained in this document may change without notice. The information and intellectual property contained herein are confidential and remain the exclusive intellectual property of Skybox Security. If you find any problems in the documentation, please report them to us in writing. Skybox Security does not warrant that this document is error-free.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means—electronic, mechanical, photocopying, recording, or otherwise—without the prior written permission of Skybox Security.

Skybox®, Skybox® Security, Skybox Firewall Assurance, Skybox Network Assurance, Skybox Vulnerability Control, Skybox Threat Manager, Skybox Change Manager, Skybox Appliance 5500/6000/7000/8000/8050, and the Skybox Security logo are either registered trademarks or trademarks of Skybox Security, Inc., in the United States and/or other countries. All other trademarks are the property of their respective owners.

Contact information

Contact Skybox using the form on our website or by emailing [email protected]

Customers and partners can contact Skybox technical support via the Skybox Support portal

https://lp.skyboxsecurity.com/ContactMe1.html

mailto:[email protected]

https://www.skyboxsecurity.com/support/portal


Skybox version 10.1.500 3

Intended Audience .................................................................................... 6 How this manual is organized ..................................................................... 6 Related documentation .............................................................................. 6 Technical support ..................................................................................... 6

Introduction ........................................................................................... 8 Skybox overview ...................................................................................... 8

Part I: Integration .................................................................................. 13

Introduction to integration ...................................................................... 14 Skybox integration package ................................................................ 14 Integrating user data into a Skybox model ........................................... 14 Skybox model ................................................................................... 15

iXML elements ....................................................................................... 17 List of iXML elements, subelements, and attributes ................................ 17 Hierarchical order of iXML elements ..................................................... 25 Examples of iXML code ....................................................................... 27 Description of iXML elements .............................................................. 32

Perl API methods ................................................................................... 93 Parameters of API methods ................................................................. 93 API methods and generated iXML code ................................................. 93 Mandatory include statements for Perl scripts........................................ 94 Examples of Perl scripts ...................................................................... 94 Description of Perl API methods ........................................................... 96

Enums for iXML elements and Perl API methods ....................................... 155 Enum for the Business Asset Group dependency parameter .................. 155 Enum for the damage level parameter................................................ 156 Enum for the discovery method parameter ......................................... 156 Enum for the asset type parameter .................................................... 156 Enum for the network interface type parameter ................................... 157 Enum for the network type parameter ................................................ 157 Enum for the threat probability parameter .......................................... 157 Enum for the definition parameter ..................................................... 157 Generic Vulnerability Definitions in the Vulnerability Dictionary .............. 158

Modeling scenarios ............................................................................... 161 Modeling load balancers ................................................................... 161 Modeling a Business Asset Group that is based on a network ................ 161

Contents

Skybox Developer Guide


Part II: SOAP APIs ............................................................................... 163

Introduction to Skybox SOAP APIs ......................................................... 164 APIs and their methods .................................................................... 164 Connecting to the Skybox APIs .......................................................... 165

Administration API ............................................................................... 167 Administration API methods .............................................................. 167 Using the Administration API ............................................................. 174

Firewall Changes API ............................................................................ 175 Firewall Changes API methods ........................................................... 175 Using the Firewall Changes API ......................................................... 180

Network API ........................................................................................ 181 Basic field types used in the API ........................................................ 181 Network API methods....................................................................... 182 Using the Network API ..................................................................... 206

Tickets API .......................................................................................... 209 Tickets API methods ........................................................................ 209 Using the Tickets API ....................................................................... 247

Vulnerabilities API ................................................................................ 249 Vulnerabilities API methods .............................................................. 249 Using the Vulnerabilities API ............................................................. 254

API code example ................................................................................ 256

Data structures .................................................................................... 259 Data structures: A to C .................................................................... 259 Data structures: D to H .................................................................... 280 Data structures: I to R ..................................................................... 300 Data structures: S to Z..................................................................... 314

Part III: REST APIs ............................................................................... 328

Introduction to Skybox REST APIs .......................................................... 329 Overview of the public REST APIs ...................................................... 329 Overview of the additional REST APIs ................................................. 330 Conventions .................................................................................... 330 HTTP requests ................................................................................. 331 Authentication ................................................................................. 331

Public REST APIs .................................................................................. 332 Pagination ...................................................................................... 332 Data structures (models) .................................................................. 332

Contents


Additional REST APIs ............................................................................ 334 Endpoints ....................................................................................... 334 Pagination ...................................................................................... 335 Threat Alert Tickets v1 ..................................................................... 335 Access Policy Management ................................................................ 336 Locations ........................................................................................ 339 Models ........................................................................................... 339 Custom Entity Fields ........................................................................ 341


Preface

Intended Audience The Skybox Developer Guide describes:

› Integration of data from non-standard devices and sources with the Skybox platform.

› Integration of Skybox data between Skybox and other applications.

The intended audience is developers and programmers responsible for these tasks.

How this manual is organized This manual includes the following parts:

› Integration (on page 13): Explains how to integrate data from non-standard devices and sources with the Skybox platform

› SOAP APIs (on page 163): Explains how to integrate Skybox data into other applications using SOAP requests

› REST APIs (on page 328): Explains how to work with Skybox data using REST APIs

Related documentation The following documentation is available for Skybox:

› Skybox Installation and Administration Guide › Skybox Reference Guide › Skybox Release Notes

The entire documentation set (in PDF format) is available here

Note: If you are not using the latest version of Skybox, you can find the documentation for your version at http://downloads.skyboxsecurity.com/files/Installers/Skybox_View/<your major version/<your minor version>/Docs. For example, http://downloads.skyboxsecurity.com/files/Installers/Skybox_View/10.0/10.0.600/Docs

You can access a comprehensive Help file from any location in Skybox Manager by using the Help menu or by pressing F1.

Technical support You can contact Skybox using the form on our website or by emailing [email protected]

http://downloads.skyboxsecurity.com/files/Installers/Skybox_View/latestDocs

https://lp.skyboxsecurity.com/ContactMe1.html


Preface


Customers and partners can contact Skybox technical support via the Skybox Support portal

When you open a case, you need:

› Your contact information (telephone number and email address) › Skybox version and build numbers › Platform (Windows or Linux) › Problem description › Any documentation or relevant logs

You can compress logs before attaching them by using the Pack Logs tool (see Packing log files for technical support, in the Skybox Installation and Administration Guide).




Chapter 1

This chapter provides an overview of Skybox for readers who are not familiar with the Skybox platform.

Skybox overview Skybox® Security arms security professionals with the broadest platform of solutions for security operations, analytics, and reporting. By integrating with more than 100 networking and security technologies organizations, the Skybox Security Suite merges data silos into a dynamic network model of your organization’s attack surface, giving comprehensive visibility of public, private, and hybrid IT environments. Skybox provides the context needed for informed action, combining attack vector analytics and threat-centric vulnerability intelligence to continuously assess vulnerabilities in your environment and correlate them with exploits in the wild. This makes the accurate prioritization and mitigation of imminent threats a systematic process, decreasing the attack surface and enabling swift response to exposures that truly put your organization at risk.

Introduction

Chapter 1 Introduction


Skybox arms security leaders with a comprehensive cybersecurity management platform to address the security challenges of large, complex networks. The Skybox Security Suite breaks down data silos to build a dynamic network model that gives complete visibility of an organization’s attack surface and the context needed for informed action across physical, multicloud, and industrial networks. We leverage data by integrating with 120 security technologies, using analytics, automation, and advanced threat intelligence from the Skybox Research Lab to continuously analyze vulnerabilities in your environment and correlate them with exploits in the wild. This makes the prioritization and mitigation of imminent threats an efficient and systematic process, decreasing the attack surface and enabling swift response to exposures that truly put your organization at risk. Our award-winning solutions automate as much as 90 percent of manual processes and are used by the world’s most security-conscious enterprises and government agencies, including Forbes Global 2000 companies. For additional information visit the Skybox website

The Skybox Security Suite includes:

› Skybox Vulnerability Control: Powers threat-centric vulnerability management by correlating intelligence on vulnerabilities in your environment, the surrounding network and security controls and exploits in the wild focusing remediation on your most critical threats

https://www.skyboxsecurity.com/



› Skybox Threat Manager: Consolidates threat intelligence sources and prioritizes advisories in the context of your attack surface, automatically analyzing the potential impact of a threat and providing remediation guidance

› Skybox Firewall Assurance: Brings multivendor firewall environments into a single view and continuously monitors policy compliance, optimizes firewall rule sets and finds attack vectors that others miss

› Skybox Network Assurance: Analyzes hybrid environments end to end across physical, virtual and cloud – even operational technology – networks, illuminating complex security zones, access paths and policy compliance violations

› Skybox Change Manager: Ends risky changes with network-aware planning and risk assessments, making firewall changes a secure, consistent process with customizable workflows and automation

› Skybox Horizon: Visualizes an organization’s unique attack surface and indicators of exposure (IOEs), giving threat-centric insight to critical risks, visibility across an entire organization or down to a single access rule and metrics to track risk reduction over time

Skybox Vulnerability Control Vulnerability Control harnesses total attack surface visibility and threat-centric vulnerability intelligence to spot vulnerabilities that are most likely to be used in an attack against your organization. Eliminate risks 100-times faster than traditional scanning and manual analysis with on-demand vulnerability discovery, threat-centric prioritization and remediation guidance based on the context of your attack surface and threats in the wild. Reduce false positives to near-zero levels, streamline workflows, optimize gradual risk reduction and respond to imminent threats within hours—not days.

› Finds vulnerability exposures and exploitable attack vectors on-demand with intelligence on exploits in the wild

› Prioritizes vulnerabilities based on threats and the risk imposed to your network

› Detects vulnerabilities on network devices and ‘unscannable’ systems › Targets imminent threats for immediate response and systematically reduces

potential threats with context-aware remediation guidance

Skybox Threat Manager Threat Manager consolidates threat intelligence sources and identifies relevant advisories in the context of your attack surface. With detailed threat impact analysis and remediation recommendations, your team can prioritize and respond to critical threats in minutes.

› Automate the collection and normalization of threat intelligence › Get analyst–validated threat intelligence from Skybox Research Lab’s

investigations of 30+ security data feeds and 700,000+ sites in the dark web › Correlate and prioritize threats with your organization’s attack surface › Target response at imminent threats with efficient remediation options

tailored to you

Chapter 1 Introduction


› Track remediation status with an integrated ticketing workflow and evaluate progress in gradual risk reduction

Skybox Firewall Assurance Firewall Assurance covers the most comprehensive list of firewall vendors, complex rulesets and virtual- and cloud-based firewalls, bringing your entire firewall estate into a single view. With continuous monitoring of firewalls and network devices, Firewall Assurance verifies that firewalls are clean, optimized and working effectively. It extends beyond firewall rule checks, analyzing possible traffic between network zones to find hidden attack vectors, flagging unauthorized changes and finding vulnerabilities on firewalls.

› Identify security policy violations and platform vulnerabilities to reduce your attack surface

› Visualize how network traffic can flow through your firewalls to troubleshoot access issues

› Clean and optimize firewall rulesets to maintain top performance › Manage traditional, next-generation, virtual- and cloud-based firewalls with a

single consistent and efficient process

Skybox Firewall Assurance is most often used to automate firewall audits and to test policy compliance on other types of forwarding devices.

Skybox Network Assurance Network Assurance provides complete visibility across physical, virtual, and cloud networks, giving you the context to understand how network devices and security controls work together or leave you exposed. Uncover potential attack vectors, troubleshoot the root causes of network outages and check correct implementation of security zone policies and security groups.

› Visualizes your entire hybrid network and security controls in an interactive model

› Keeps security zones and device configurations in continuous compliance and working to reduce your attack surface

› Troubleshoots access paths to ensure business continuity

Skybox Change Manager Change Manager ends risky changes with network-aware planning and risk assessment that keep your network secure and in continuous compliance with policies. Change Manager incorporates customizable workflows and provides comprehensive management of rule lifecycles to automate change processes.

› Fully automates firewall change management workflows, improving communication and efficiency across security teams

› Validates proposed firewall changes by checking for policy violations, security gaps and vulnerabilities that could be exposed by the change

› Ensures that changes are made as intended and do not introduce new risk › Customizes and simplifies workflows to reduce change management time by

80 percent



› Establishes end-to-end rule life cycle management for secure infrastructure and optimized firewalls

Skybox Horizon Skybox Horizon combines data integration, network modeling, and attack vector analytics with visualization technology to provide unprecedented visibility of the attack surface, IOEs and how threats in the wild could impact your organization. Horizon provides deep insight from a simple picture, making it easier for operational teams to understand security risks and cyberthreats. This visual, threat-centric intelligence helps you to focus on imminent threats, systematically reduce potential threats and build a strategic, adaptable security program.

› Provides at-a-glance visibility to your attack surface and security issues most likely to be used in an attack

› Visualizes hybrid network topology and connections, business units, locations of IOEs, and more—all from a single platform

› Drills down to sites or zooms out for panoramic attack surface visibility › Customizes views to focus on IOE types and severity levels or see IOE trends

and history to track risk-reduction progress

This part provides information about how to integrate data from various sources into the Skybox database using Skybox Integration XML (iXML) or Perl.

Part I: Integration


Chapter 2

This chapter provides an overview of integrating data into the Skybox database.

In this chapter

Skybox integration package ................................................. 14

Integrating user data into a Skybox model ............................. 14

Skybox model .................................................................... 15

SKYBOX INTEGRATION PACKAGE Skybox includes tasks for importing data directly from most standard scanners and network devices. You can model devices that are not supported directly using Skybox Integration XML (iXML) and then import them into the model.

Using iXML you can:

› Add network devices to the model even if they are not officially supported by Skybox

› Add information from custom databases to the model using scripting, so that you do not need to add the information manually

To facilitate iXML file generation, the Skybox integration package includes the IntermediateSecurityModel.pm Perl module for writing Perl scripts. Using the API methods of this module, you can create entities to add to the network model.

INTEGRATING USER DATA INTO A SKYBOX MODEL User data that cannot be imported directly (by running a predefined task) is integrated into the model by importing an iXML file from an external source.

There are 2 ways to prepare an iXML file:

› Code the iXML file directly › Use the Perl library (the Perl API methods) to generate the iXML file

Usually, it is faster and easier to use the Perl API methods to generate an iXML file. The following figure shows the typical process (using Perl).

Although you can use any offline file import task to import an iXML file into the model, we recommend that you use an Import – Directory task.

Introduction to integration

Chapter 2 Introduction to integration


(For basic file import tasks set Format or File Type to Integration XML and for advanced file import tasks use INTERMEDIATE_XML as the file import format type. For additional information, see the File import tasks chapter in the Skybox Reference Guide.)

SKYBOX MODEL If you create your own data source integration module, you must translate the data into Skybox ‘language’—normalization.

For normalizing the data, it is important that you understand the data scheme of Skybox. For example:

› When you import a custom router, construct an iXML that:

• Describes an asset of type router

• Specifies a list of network interfaces with their names, IP addresses, and other information

• Provides a list of routing rules

› When you build the tree of Business Units and Business Asset Groups, construct an iXML that:

• Describes a hierarchical list of Business Units

• For each Business Unit, describes the list of Business Asset Groups

• For each Business Asset Group, describes the assets that it contains

The Skybox data scheme includes:

› Network entities

• Locations

• Networks

• Assets

— Network interfaces

— Services (products and ports)

— Routing rules

— Access rules

— Vulnerability occurrences

— Patches and fixes

› Grouping entities

• Asset groups (for example, management units, clusters, and virtual firewall groups)

• Network groups (used for Skybox Network Assurance zone mapping)

• Firewall folders (groups of firewalls and subfolders in Skybox Firewall Assurance)

Note: Each management unit imported into Skybox Firewall Assurance is represented as a separate firewall folder.



› Organizational entities

• Business Units

• Business Asset Groups

› Threat entities

• Threat Origin Categories

• Threat Origins


Chapter 3

This chapter describes the elements of Skybox Integration XML (iXML).

In this chapter

List of iXML elements, subelements, and attributes ................. 17

Hierarchical order of iXML elements ...................................... 25

Examples of iXML code ........................................................ 27

Description of iXML elements ................................................ 32

LIST OF IXML ELEMENTS, SUBELEMENTS, AND ATTRIBUTES In iXML, the network information in the model is contained under the <network_model> element and other information is contained under the <business_model> element.

All iXML elements, and their 1st-level subelements and attributes, are listed in the following tables. Use these tables to determine the attributes for each element. For detailed information about each element, see the individual topics in Description of iXML elements (on page 32).

The iXML elements are listed hierarchically in Hierarchical order of iXML elements (on page 25).

Note: The relevant <..._ref> subelements are listed with their attributes at the end of each table.

Element Subelements Attributes

<intermediate_model> (on page 62)

<creation_time> <network_model> <business_model>

version method creation_time last_scan_time

<intermediate_model> subelements

<creation_time> (on page 49)

time

<network_model> (on page 72)

<network> <asset> <host_group> <asset_category> <asset_group> <vpn_tunnel> <config_check_result> <tenant> <security_tag> <security_group>

iXML elements




<business_model> (on page 46)

<application> <business_unit> <damage> <dependency> <regulation> <business_impact_type> <location> <threat> <threat_group>

<network_model> subelements


<network> (on page 70)

<segment> name number mask type last_scan_time do_not_outdate source_alternative_ip_ranges source_excluded_ip_ranges destination_alternative_ip_ranges destination_excluded_ip_ranges owner zone_id include_hosts is_forwarding comment

<asset> (on page 40)

<interface> <service> <routing_rule> <access_rule> <ips_access_rule> <ips_rule_group> <nat_rule> <vulnerability_occurrence> <patch> <vpn_unit> <vrouter> <config_file> <address_object> <address_group_object> <service_object> <service_group_object> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <custom_property>

assetname ip_forwarding dynamic_routing layer2 do_not_outdate os platform outbound_chains inbound_chains type last_scan_time status unique_tag name_tag owner comment is_virtual is_distributed primary_chain secondary_chain domain user last_login_time

Chapter 3 iXML elements


Element Subelements Attributes latitude longitude high_availability_active

<host_group> (on page 59)

<host_ref> <network_ref>

name group_type owner ip_network comment

<asset_category> (on page 44)

<asset_ref> <network_ref>

name owner ip_network comment

<asset_group> (on page 44)

<asset_ref> <network_ref>

name owner ip_network comment

<vpn_tunnel> (on page 87)

name number mask type endpoint1 endpoint2 last_scan_time display_as_cloud do_not_outdate comment

<config_check_result> (on page 48)

<host_ref> key type status detection_time file_name line_number actual_result

<tenant> (on page 85)

<host_ref> <security_group_ref> <security_tag_ref>

id name description type data_mode comment

<security_tag> (on page 76)

<host_ref> <access_rule> <nat_rule> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <address_object> <address_group_object> <service_object> <service_group_object>

id name description tag_position comment




<security_group> (on page 75)

<host_ref> id name description comment

<network> subelements

<segment> (on page 77)

<host_ref> <ip_range_ref>

name type is_virtual private_vlan_type parent_vlan_id vlan_id is_distributed is_promiscuous other_names

<asset> subelements

<interface> (on page 60)

ip_address ip_mask locked mac_address name network segment type is_primary layer2 status proxy_arp_type public_arp_range zone vrouter comment abi description

<service> (on page 79)

<vulnerability_occurrence>

banner vendor_banner product_banner version_banner port interfaces last_scan_time status comment

<routing_rule> (on page 74)

destination gateway dynamic interface vrouter via_vrouter via_global null_route preference comment

<access_rule> (on id



Element Subelements Attributes page 33) source

destination service action direction chain applied_interfaces source_interfaces source_orig_text destination_orig_text service_orig_text orig_text implied disabled orig_name vpn user_groups authenticated comment description uid application source_obj destination_obj service_obj source_zone destination_zone log_enable is_negated_source is_negated_destination is_negated_service is_negated_application user routed_interface source_security_group_obj destination_security_group_obj acl_expiration_date

<ips_access_rule> (on page 63)

id source destination service direction chain applied_interfaces source_interfaces ips_rule_group_ref source_orig_text destination_orig_text service_orig_text orig_text implied disabled comment description source_obj



Element Subelements Attributes destination_obj service_obj source_zone destination_zone application user acl_expiration_date

<ips_rule_group> (on page 65)

<ips_rule> name

<nat_rule> (on page 68)

id uid source destination service translated_source translated_destination translated_service direction chain applied_interfaces source_interfaces source_orig_text destination_orig_text service_orig_text orig_text implied disabled comment description translated_source_obj translated_destination_obj translated_service_obj source_obj destination_obj service_obj source_zone destination_zone log_enable is_negated_source is_negated_destination is_negated_service user acl_expiration_date

<vulnerability_occurrence> (on page 90)

definition id sbv_id title policy last_scan_time scanner_severity scanner_description comment




<patch> (on page 73)

product code comment

<vpn_unit> (on page 88)

name orig_text my_domain peer_domain service interface

<vrouter> (on page 88)

name

<config_file> (on page 49)

path

<address_object> (on page 36)

name domains ip_ranges comment

<address_group_object> (on page 35)

<address_object_ref> name comment

<service_object> (on page 81)

name fw_services comment

<service_group_object> (on page 80)

<service_object_ref> name comment

<firewall_application> (on page 53)

name standard_ports

<firewall_application_group> (on page 53)

<firewall_app_ref> name standard_ports

<firewall_user> (on page 54)

name

<firewall_user_group> (on page 54)

<firewall_user_ref> name

<custom_property> (on page 50)

property_name property_value

<ips_rule_group> subelements

<ips_rule> (on page 66)

title action protocol FP_level FP_original FN_level FN_original severity disabled severity_original user_defined vendor_rule_id vulnerabilities



Element Subelements Attributes comment

<..._ref> subelements

<address_object_ref> (on page 36)

name

<asset_ref> (on page 45)

ip unique_tag

<firewall_app_ref> (on page 53)

name

<firewall_user_ref> (on page 55)

name

<host_ref> (on page 60)

ip unique_tag

<ip_range_ref> (on page 63)

ip

<network_ref> (on page 72)

ip

<security_group_ref> (on page 76)

id

<security_tag_ref> (on page 77)

id

<service_object_ref> (on page 81)

name

<business_model> subelements


<application> (on page 37)

<host_ref> <ip_range_ref>

name dependency owner comment uid

<business_unit> (on page 47)

<application_ref> <business_unit_ref> <group_ref> <location_ref>

name owner comment uid

<damage> (on page 50)

<application_ref> <host_ref>

name effect per_member value rate

<dependency> (on page 51)

<source> <destination>

name effect any

<regulation> (on page 73)

<application_ref> name effect value rate




<business_impact_type> (on page 46)

<application_ref> name effect value rate

<location> (on page 67)

<network_ref> <location_ref>

name

<threat> (on page 85)

<application_ref> <host_ref> <network_ref>

name probability skill value

<threat_group> (on page 86)

<threat_ref> name

<dependency> subelements

<source> (on page 82)


effect

<destination> (on page 52)


effect

<..._ref> subelements

<application_ref> (on page 38)

name uid

<business_unit_ref> (on page 48)

name uid

<group_ref> (on page 55)

name

<host_ref> (on page 60)

ip unique_tag

<ip_range_ref> (on page 63)

ip

<location_ref> (on page 67)

name

<network_ref> (on page 72)

ip

<threat_ref> (on page 86)

name

HIERARCHICAL ORDER OF IXML ELEMENTS The following lists the iXML elements in hierarchical order.

For clarity, the closing tags are omitted. An element that can appear under many other elements is listed under each. Unless stated otherwise, all elements can appear any number of times per XML file or per other element.

<intermediate_model> Note: Exactly 1 instance per XML file <creation_time> Note: At most 1 instance per XML file <network_model> <network> <segment> <host_ref>



<ip_range_ref> <asset> <interface> Note: At least 1 instance per <asset> <service> <vulnerability_occurrence> <routing_rule> <access_rule> <ips_access_rule> <ips_rule_group> <ips_rule> <nat_rule> <vulnerability_occurrence> <patch> <vpn_unit> <vrouter> <config_file> <address_object> <address_group_object> <address_object_ref> <service_object> <service_group_object> <service_object_ref> <firewall_application> <firewall_application_group> <firewall_app_ref> <firewall_user> <firewall_user_group> <firewall_user_ref> <custom_property> <host_group> <host_ref> Note: At least 1 instance per <host_group> <network_ref> <asset_category> <asset_ref> Note: At least 1 instance per <asset_category> <network_ref> <asset_group> <asset_ref> Note: At least 1 instance per <asset_group> <network_ref> <vpn_tunnel> <config_check_result> <host_ref> Note: At least 1 instance per <config_check_result> <tenant> <host_ref> <security_group_ref> <security_tag_ref> <security_tag> <host_ref> <access_rule> <nat_rule> <firewall_application> <firewall_application_group> <firewall_app_ref> <firewall_user> <firewall_user_group> <firewall_user_ref> <address_object> <address_group_object> <address_object_ref> <service_object> <service_group_object> <service_object_ref> <security_group>



<host_ref> <business_model> <application> <host_ref> <ip_range_ref> <business_unit> <business_unit_ref> <location_ref> <group_ref> <application_ref> <damage> <application_ref> <host_ref> <dependency> <source> <application_ref> <host_ref> <destination> <application_ref> <host_ref> <regulation> <application_ref> <business_impact_type> <application_ref> <location> <network_ref> <location_ref> <threat> <application_ref> <host_ref> <network_ref> <threat_group> <threat_ref>

EXAMPLES OF IXML CODE This section contains the following iXML code examples:

› Example of iXML code for network and business models (on page 27) › Example of iXML code for an L2 firewall (on page 30) › Example of iXML code for VPN (on page 30) › Example of iXML code for an IPS device (on page 31) › Example of iXML code for the Application & Service repository (on page 32)

Example of iXML code for network and business models This an example of iXML code for a very simple model. It includes the following entities:

Network model

› Network with no assets › Network with 4 assets and 2 asset groups

• Asset AssetA: Non-forwarding, only 1 interface

• Asset AssetB: Non-forwarding, only 1 interface

• Asset gonzo.il.skyboxsecurity.com: Forwarding, with:



— 2 interfaces

— 3 services with 1 vulnerability occurrence each

— 2 routing rules

— 2 access rules

— 1 NAT rule

— 1 vulnerability occurrence for which a service is not specified

• Asset goofy.il.skyboxsecurity.com: Non-forwarding, only 1 interface

• Asset group new_cluster containing AssetA and AssetB

• Asset group grp1 containing AssetA and goofy

Business model

› Business Asset Group bag1 containing AssetA and goofy › Damage damage1, which affects AssetA and AssetB › Damage damage2, which affects bag1 and goofy › Threat new_threat, which affects bag1, AssetA, goofy, and both networks › Threat big_threat, which affects bag1 and 1 network (192.168.80.0) › Threat group new_group, which includes both threats › Dependency new, which states that if either bag1 or AssetA are

compromised, then bag1, AssetA, and goofy are affected in the same way <?xml version="1.0" encoding="UTF-8" ?> <intermediate_model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" method="CONFIG"> <creation_time time="Aug 01, 2018 08:30"/> <network_model> <network name="192.168.80.0" number="192.168.80.0" mask="255.255.255.0"/> <network number="192.168.90.0"/> <asset assetname="AssetA"> <interface ip_address="192.168.80.1" ip_mask="255.255.255.0"/> </asset> <asset assetname="AssetB"> <interface ip_address="192.168.80.10" ip_mask="255.255.255.0"/> </asset> <asset assetname="gonzo.il.skyboxsecurity.com" ip_forwarding="true" os="SunOS 8.2" platform="intel"> <interface ip_address="192.168.80.3"/> <interface ip_address="192.168.90.1" ip_mask="255.255.255.0"/> <service banner="Apache Web Server X.X" port="80/TCP"> <vulnerability_occurrence id="CVE-2018-0899" definition="CVE" policy="My local network scan"/> </service> <service banner="FTP" port="21/TCP"> <vulnerability_occurrence id="CVE-2018-0899" definition="CVE" policy="My local network scan"/> </service> <service banner="telnet" port="23/TCP"> <vulnerability_occurrence id="CVE-2018-0899" definition="CVE" policy="My local network scan"/> </service> <routing_rule destination="192.168.80.0/24" gateway="192.168.80.1"/> <routing_rule destination="192.168.90.0/24" gateway="192.168.90.1"/>



<access_rule source="192.168.80.0/24" destination="0.0.0.0/0" service="0-65535/80-80/IP" action="Allow"/> <access_rule source="192.168.90.0/16" destination="10.0.0.0/8" service="23t" action="Deny" direction="Inbound"/> <nat_rule source="172.20.0.0/16" destination="10.0.0.0/8" service="21/TCP" translated_source="10.1.1.1-10.1.1.10"/> <vulnerability_occurrence id="CVE-2018-0899" definition="CVE" policy="My local network scan"/> </asset> <asset assetname="goofy.il.skyboxsecurity.com"> <interface ip_address="192.168.80.200" ip_mask="255.255.255.0" mac_address="FF:02:B3:A8:15:44"/> </asset> <asset_group name="new_cluster"> <asset_ref ip="192.168.80.1"/> <asset_ref ip="192.168.80.10"/> </asset_group> <asset_group name="grp1"> <asset_ref ip="192.168.80.1"/> <asset_ref ip="192.168.80.200"/> </asset_group> </network_model> <business_model> <application name="bag1"> <host_ref ip="192.168.80.1"/> <host_ref ip="192.168.80.200"/> </application> <damage name="damage1" effect="cia" per_member="true" rate="2950"> <host_ref ip="192.168.80.1"/> <host_ref ip="192.168.80.2"/> </damage> <damage name="damage2" effect="cia" per_member="true" value="high"> <application_ref name="bag1"/> <host_ref ip="192.168.80.200"/> </damage> <threat name="new_threat" probability="high" skill="low" value="high"> <application_ref name="bag1"/> <host_ref ip="192.168.80.1"/> <host_ref ip="192.168.80.200"/> <network_ref ip="192.168.90.0/24"/> <network_ref ip="192.168.80.0"/> </threat> <threat name="big_threat" probability="high" skill="low" value="high"> <application_ref name="bag1"/> <network_ref ip="192.168.80.0"/> </threat> <threat_group name="new_group"> <threat_ref name="new_threat"/> <threat_ref name="big_threat"/> </threat_group> <dependency name="new" effect="cia" skill="low" value="high"> <source effect="cia"> <application_ref name="bag1"/> <host_ref ip="192.168.80.1"/> </source> <destination effect="cia"> <application_ref name="bag1"/> <host_ref ip="192.168.80.1"/> <host_ref ip="192.168.80.200"/> </destination> </dependency> </business_model> </intermediate_model>



Example of iXML code for an L2 firewall The following example of iXML code creates an L2 firewall. The Perl script used to create this iXML code is at Perl script for creating an L2 firewall (on page 94). <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <intermediate_model creation_time="Jan 7, 2008 11:57" version="Revision: 1.1.2.9.2.4.14.12.10.1 "> <creation_time/> <network_model> <network mask="0.0.0.0" name="Inet-Cloud" number="0.0.0.0" source_excluded_ip_ranges="10.0.0.0-10.255.255.255" type="Cloud"/> <network mask="255.255.255.0" name="NetworkA" number="10.0.0.0"> <segment name="SegEXT"/> <segment name="SegINT"/> </network> <asset dynamic_routing="true" assetname="l2fw" inbound_chains="Nat, Access" ip_forwarding="true" os="Juniper Networks ScreenOS" outbound_chains="Access, Nat" platform="Juniper Networks NetScreen" type="Firewall"> <interface ip_address="10.0.0.1" ip_mask="255.255.255.0" name="eth0" network="NetworkA" segment="SegINT" type="Ethernet"/> <interface ip_address="10.0.0.2" ip_mask="255.255.255.0" name="eth1" network="NetworkA" segment="SegEXT" type="Ethernet"/> <service banner="HTTP" port="80/TCP"/> <service banner="FTP" interfaces="10.0.0.1" port="21/TCP"/> <access_rule action="Allow" destination="any" direction="Both" service="any" source="any"/> <access_rule action="Deny" destination="any" direction="Both" service="any" source="any"/> </asset> <asset assetname="srv" ip_forwarding="false" os="Microsoft Windows Server 2003" type="Server"> name="eth10" <interface ip_address="10.0.0.10" ip_mask="255.255.255.0" network="NetworkA" segment="SegINT" type="Ethernet"/> </asset> <asset assetname="router" ip_forwarding="true" os="Linux" type="Router"> <interface ip_address="10.0.0.254" ip_mask="255.255.255.0" name="eth10" network="NetworkA" segment="SegEXT" type="Ethernet"/> <interface ip_address="15.15.15.254" ip_mask="255.255.255.0" name="eth15" network="Inet-Cloud" type="Ethernet"/> </asset> </network_model> <business_model/> </intermediate_model>

Example of iXML code for VPN

Example of iXML code for modeling a VPN <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <intermediate_model version="Revision: 1.7.2.2" method="CONFIG"> <creation_time /> <network_model> <vpn_tunnel name="10.1.1.1_to_10.1.1.2" number="0.0.0.0" mask="0.0.0.0" type="Tunnel" endpoint1="10.10.10.1" endpoint2="10.10.10.2" /> <asset assetname="R1" ip_forwarding="true" os="Cisco IOS" platform="Cisco CSS" type="Router">



<interface ip_address="10.10.10.1" ip_mask="255.255.255.0" name="eth0" type="Ethernet" /> <interface ip_address="0.0.0.0" ip_mask="0.0.0.0" name="vpn_from_10.10.10.1_to_10.10.10.2" type="Vpn" network="10.1.1.1_to_10.1.1.2" /> <vpn_unit name="10.10.10.1_to_10.10.10.2" original_text="cisco" my_domain="10.1.1.1-10.1.1.20" peer_domain="192.168.80.0/24" service="80/TCP" interface="vpn_from_10.10.10.1_to_10.10.10.2" /> <access_rule source="any" destination="Any" service="Any" action="Allow" vpn="10.10.10.1_to_10.10.10.2" /> </asset> <asset assetname="R2" ip_forwarding="true" os="Cisco IOS" platform="Cisco CSS" type="Router"> <interface ip_address="10.10.10.2" ip_mask="255.255.255.0" name="eth0" type="Ethernet" /> <interface ip_address="0.0.0.0" ip_mask="0.0.0.0" name="vpn_from_10.10.10.2_to_10.10.10.1" type="Vpn" network="10.1.1.1_to_10.1.1.2" /> <vpn_unit name="10.10.10.2_to_10.10.10.1" original_text="cisco" my_domain="any" peer_domain="any" service="any" interface="vpn_from_10.10.10.2_to_10.10.10.1" /> </asset> </network_model> <business_model /> </intermediate_model>

Example of iXML code for an IPS device The following example of iXML code is for an L2 IPS device. The device has 2 IPS access rules; each rule has a reference to a different IPS rule group. The rule group includes custom rules and vendor rules. <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <intermediate_model version="Revision: 1.7.2.3"> <network_model> <network number="16.0.0.0" mask="255.255.255.0" name="to internet"> <segment name="Inside" /> <segment name="Outside" /> </network> <asset assetname="IPS1" layer2="true" inbound_chains="Access,IPS" outbound_chains="Access" ip_forwarding="true" type="IPS"> <interface ip_address="192.170.23.44" name="Management" /> <interface ip_address="0.0.0.0" name="in" network="16.0.0.0/24" segment="Inside" layer2="true" /> <interface ip_address="0.0.0.0" name="out" segment="Outside" layer2="true" /> <ips_access_rule chain="IPS" source="Any" destination="Any" service="Any" source_interfaces="Any" ips_rule_group_ref="DNS" /> <ips_access_rule chain="IPS" source="Any" destination="Any" service="Any" source_interfaces="Any" ips_rule_group_ref="Web Servers" /> <ips_rule_group name="DNS"> <ips_rule title="Buffer Overflow in Bind 8.2 (CVE-1999-0883)" vulnerabilities="SBV/34" action="prevent" /> </ips_rule_group> <ips_rule_group name="Web Servers"> <ips_rule title="IIS 5.0 with Index Server Directory (CVE-2000-0951)" vulnerabilities="SBV/279" action="prevent" /> <ips_rule vendor_rule_id="ISS_IPS/4773" action="prevent" />



</ips_rule_group> </asset> </network_model> </intermediate_model>

Example of iXML code for the Application & Service repository You can enter the data for the Skybox Application & Service repository manually or it can be imported from your organization’s configuration management database (CMDB).

To import from a CMDB 1 Output the data of the CMDB to a file. 2 Create a script to convert this data to iXML format. 3 Import the iXML to Skybox using an Import task.

Example of iXML script to convert CMDB data to iXML format <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <intermediate_model method="CONFIG"> <creation_time/> <network_model> <app_conf_item name="aci1" ip_ranges="107.129.12.21-107.129.12.21" is_enable="true" owner="shuki"/> <app_conf_item name="aci2" ip_ranges="107.129.12.22-107.129.12.22" is_enable="true" owner="shuki"/> <app_group_conf_item name="agci1" is_enable="false" owner="shuki" approvers="Request: guyk"> <app_conf_item_ref name="aci1"/> <app_group_conf_item_ref name="agci2"/> </app_group_conf_item> <app_group_conf_item name="agci2"> <app_conf_item_ref name="aci2"/> </app_group_conf_item> <srv_conf_item name="sci1" fw_services="0-65535/80/TCP" is_enable="false" owner="shuki"/> <srv_conf_item name="sci2" fw_services="0-65535/520/TCP"/> <srv_conf_item name="sci777" fw_services="0-65535/777/TCP"/> <srv_group_conf_item name="sgci1"> <srv_group_conf_item_ref name="sgci2"/> </srv_group_conf_item> <srv_group_conf_item name="sgci2"> <srv_group_conf_item_ref name="sgci3"/> </srv_group_conf_item> <srv_group_conf_item name="sgci3"> <srv_conf_item_ref name="sci2"/> </srv_group_conf_item> </network_model> </intermediate_model>

DESCRIPTION OF IXML ELEMENTS All the iXML elements are described in the following sections. The elements are listed in alphabetic order. In these descriptions, examples are given of iXML code. In these examples, the closing element of the iXML code is omitted for elements that can contain subelements.



Note: All iXML element values in the code must be surrounded by straight quotation marks ("").

<access_rule> element

Syntax with 1st-level subelements This element has no subelements.

Description The <access_rule> element adds an access rule to an asset.

Attributes The attributes of the <access_rule> element are described in the following table.

Attribute Description

id An ID (for the asset containing the access rule) that Skybox uses to sort the access rules. If this attribute is not included, the access rules are sorted according to creation time.

source A semicolon-separated list of source IP addresses or networks that are permitted for the access rule. • Separate the values of a range with a hyphen.

The default value is 0.0.0.0-255.255.255.255.

destination A semicolon-separated list of destination IP addresses or networks that are permitted for the access rule. • Separate the values of a range with a hyphen.


service A comma-separated list of access rule services that are permitted for the access rule; the format of each service can be: • Source port, destination port, and protocol, separated

by semicolons • Destination port and protocol, separated by a

semicolon • The string ANY (default): Any source port, destination

port, and protocol are permitted action The access rule action.

• Allow • Deny

direction The access rule direction. • Inbound • Outbound • Both (default)

chain The name of the rule chain to which the access rule belongs. Rule chain names are set by the <asset> element (on page 40).

applied_interfaces A semicolon-separated list of the IP address of each network interface for the access rule. • IP address ranges are not permitted.




source_interfaces A semicolon-separated list of the IP address of each source interface for the access rule. • IP address ranges are not permitted.

source_orig_text The source specified in the configuration file.

destination_orig_text

The destination specified in the configuration file.

service_orig_text The service specified in the configuration file.

orig_text The access rule as specified in the configuration file.

implied Specifies whether the access rule is implied. The default value is false.

disabled Specifies whether the access rule is disabled. The default value is false.

orig_name The ID or name of the access rule in the asset configuration.

vpn (For an access rule in an asset that is part of a VPN) The VPN unit over which the data travels.

user_groups A semicolon-separated list of the user groups that are permitted for the access rule.

authenticated Specifies whether the access rule is authenticated.

comment A free-form user comment.

description A description of the access rule.

uid The ID of the access rule (used when comparing routing rules).

application A semicolon-separated list of applications that are permitted for the access rule.

source_obj A semicolon-separated list of the source IP address object names.

destination_obj A semicolon-separated list of destination IP address object names.

service_obj A semicolon-separated list of service object names.

source_zone A semicolon-separated list of source zone names.

destination_zone A semicolon-separated list of destination zone names.

log_enable Specifies whether the access rule is loggable. The default value is true.

is_negated_source

Specifies whether the access rule applies to all source addresses except those in the source attribute. The default value is false.

is_negated_destination

Specifies whether the access rule applies to all destination addresses except those in the destination attribute. The default value is false.




is_negated_service

Specifies whether the access rule applies to all services except those in the service attribute. The default value is false.

is_negated_application

Specifies whether the access rule applies to all applications except those in the application attribute. The default value is false.

user KNOWN, UNKNOWN, or a semicolon-separated list of <firewall_user> (on page 54) elements.

routed_interface (Cisco firewalls only) The egress interface configured in the access rule. Note: If you provide an egress interface, there is no route lookup.

source_security_group_obj

A semicolon-separated list of the names of source security group objects that are permitted for the access rule.

destination_security_group_obj

A semicolon-separated list of the names of destination security group objects that are permitted for the access rule.

acl_expiration_date

The expiration date of the access rule. If a rule has passed its expiration date, Skybox does not use it in access analysis, Access Compliance, or attack simulation. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

See also

› <asset> element (on page 40) › <firewall_user> element (on page 54) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › AddAccessRule method (on page 96) › AddComment method (on page 105) › The Assets topic in the Skybox Reference Guide › SetRuleVpnValue method (on page 153)

<address_group_object> element

Syntax with 1st-level subelements <address_group_object> <address_object_ref name> </address_group_object>

Description The <address_group_object> element adds an address group object to an asset.



Attributes The attributes of the <address_group_object> element are described in the following table.


name The name of the object.


See also

› <asset> element (on page 40)

<address_object> element


Description The <address_object> element adds an address object to an asset.

Attributes The attributes of the <address_object> element are described in the following table.



domains A semicolon-separated list of domain names. Note: You must include at least one of domains and ip_ranges in the element.

ip_ranges A semicolon-separated list of IP address ranges. • Separate the values of a range with a hyphen.

Note: You must include at least one of ip_ranges and domains in the element.


See also

› <access_rule> element (on page 33) › <asset> element (on page 40)

<address_object_ref> element


Description The <address_object_ref> element references an address group object.



Attributes The attributes of the <address_object_ref> element are described in the following table.


name The name of the generic address or group.

See also

› <address_group_object> element (on page 35)

<application> element

Syntax with 1st-level subelements <application> <host_ref> <ip_range_ref> </application>

Description The <application> element adds a Business Asset Group to the model. A Business Asset Group is a group of assets that serve a common business purpose. Each Business Asset Group has an associated set of rules that define the impact of security loss on that Business Asset Group.

Note: To create a script for a Business Asset Group based on a network, use the <ip_range_ref> element together with the Location Hint field of an offline file import task (or, for advanced file import tasks, add location hints to the definition file). For information about creating this script, see Modeling a Business Asset Group that is based on a network (on page 161).

Attributes The attributes of the <application> element are described in the following table.


name The name of the Business Asset Group.

dependency Specifies how the security of the Business Asset Group depends on the security of its member assets. For possible values, see Enum for the Business Asset Group dependency parameter (on page 155).

owner The owner of the Business Asset Group.


uid The ID of the Business Asset Group.

See also

› <application_ref> element (on page 38) › <host_ref> element (on page 60) › <ip_range_ref> element (on page 63) › AddApplication method (on page 99)



<application_ref> element


Description The <application_ref> element references a Business Asset Group.

Attributes The attributes of the <application_ref> element are described in the following table.


name The name of the referenced Business Asset Group.

uid The ID of the referenced Business Asset Group.

See also

› <application> element (on page 37) › AddApplicationBusinessImpactTypeRef method (on page 100) › AddApplicationRef method (on page 101) › AddApplicationRegulationRef method (on page 102)

<app_conf_item> element


Description The <app_conf_item> element adds an application object to the Skybox Application & Service repository available in Skybox Change Manager.

Attributes The attributes of the <app_conf_item> element are described in the following table.




is_enable Specifies whether the application object is enabled in the repository.

owner The owner of the application.

approvers A semicolon-separated list of phases and their approvers. The syntax is: <phase name1>: <approver11>[, <approver12>[, <approver13> ...]]; <phase name2>: <approver21>[, <approver22>[, <approver23> ...]] For example, "Request: guyk, maryz; Implementation: joes".



See also

› <app_group_conf_item> element (on page 39) › Example of iXML code for the Application & Service repository (on page 32)

<app_conf_item_ref> element


Description The <app_conf_item_ref> element references an application object in the repository.

Attributes The attributes of the <app_conf_item_ref> element are described in the following table.


name The name of the application object.

See also

› <app_conf_item> element (on page 38) › <app_group_conf_item> element (on page 39)

<app_group_conf_item> element

Syntax with 1st-level subelements <app_group_conf_item> <app_conf_item_ref> <app_group_conf_item_ref> </app_group_conf_item>

Description The <app_group_conf_item> element adds an application group object to the Skybox Application & Service repository available in Skybox Change Manager. Application groups can contain applications and other application groups.

Attributes The attributes of the <app_group_conf_item> element are described in the following table.



is_enable Specifies whether the application group object is enabled in the repository.

owner The owner of the application group.

approvers A semicolon-separated list of phases and their approvers. The syntax is: <phase name1>: <approver11>[, <approver12>[, <approver13> ...]]; <phase name2>:



Attribute Description <approver21>[, <approver22>[, <approver23> ...]] For example, "Request: guyk, maryz; Implementation: joes".

See also

› Example of iXML code for the Application & Service repository (on page 32) › <app_conf_item> element (on page 38) › <app_group_conf_item_ref> element (on page 40)

<app_group_conf_item_ref> element


Description The <app_group_conf_item_ref> element references an application object in the repository.

Attributes The attributes of the <app_group_conf_item_ref> element are described in the following table.


name The name of the application group object.

See also

› <app_group_conf_item> element (on page 39)

<asset> element

Note: The <asset> element supersedes the <host> element. (The <host> element is retained for backward compatibility.)

Syntax with 1st-level subelements <asset> <access_rule> <interface> <nat_rule> <routing_rule> <service> <vulnerability_occurrence> <patch> <vpn_unit> <ips_access_rule> <ips_rule_group> <vrouter> <config_file> <address_object> <address_group_object> <service_object> <service_group_object> <firewall_application>



<firewall_application_group> <firewall_user> <firewall_user_group> <custom_property> </asset>

Description The <asset> element adds an asset to the model.

Attributes The attributes of the <asset> element are described in the following table.


assetname The comma-separated names of the asset. Note: The equivalent <host> element attribute is hostname. Optionally, append a colon and the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID

For example, "gonzo,vm-16:VM_NAME, DFB65A24-E1FF-4F2F-BFFA-B483284BA3BF-vm-16:VM_UNIQUE_ID"

ip_forwarding Specifies whether the asset can forward. • true (default for firewalls, routers, and IPS devices) • false (default for all other asset types)

dynamic_routing Specifies whether dynamic routing is enabled. The default value is false. Note: This attribute is applicable only if type is set to Router.

layer2 Specifies whether this asset is an L2 gateway. Note: An L2 gateway must have at least one L2 network interface.

do_not_outdate Specifies whether the asset is protected against aging. The default value is false. Assets that are not marked as protected against aging are checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, assets imported using iXML are not updated on a regular basis so should not be outdated. In this case, set this flag to true.

os The operating system vendor, name, and version. Note: The value for this attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)




platform The platform vendor, name, and, if applicable, version. Note: The value for this attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

inbound_chains A comma-separated list of the names of inbound rule chains to use for access rules. Note: This attribute is applicable only if type is set to Firewall.

outbound_chains A comma-separated list of the names of outbound rule chains to use for access rules. Note: This attribute is applicable only if type is set to Firewall.

type The asset type. For a list of possible values, see Enum for the asset type parameter (on page 156).

last_scan_time The time of the most recent scan of the asset. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

status • Up (default) • Down • Unknown

unique_tag Add this attribute to an asset if: • The assetname (or IP address) might not be a unique

identifier in the network • Your organization has a unique ID for each asset

(based on a proprietary database) and wants to use this ID as the key (instead of the IP address or asset name) when merging assets in the model

name_tag An additional name for the asset used when merging data.

owner The name of the asset owner.


is_virtual Specifies whether the asset is a virtual machine. The default value is false.

is_distributed Specifies whether the asset is a distributed virtual switch. The default value is false.

primary_chain The name and direction of the primary chain. Note: This attribute is applicable only if type is set to Firewall.

secondary_chain The name and direction of the secondary chain. Note: This attribute is applicable only if type is set to Firewall.

domain The domain of the asset. If this field is empty, the asset is not part of a known domain.




user The user that is associated with the asset.

last_login_time The time of the most recent login to the asset. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

latitude The latitude coordinate of the asset.

longitude The longitude coordinate of the asset.

high_availability_active

Specifies whether the asset is the active or passive member of a high availability cluster.

See also

› <access_rule> element (on page 33) › <interface> element (on page 60) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › <service> element (on page 79) › <vulnerability_occurrence> element (on page 90) › <patch> element (on page 73) › <vpn_unit> element (on page 88) › <ips_access_rule> element (on page 63) › <ips_rule_group> element (on page 65) › <vrouter> element (on page 88) › <config_file> element (on page 49) › <custom_property> element (on page 50) › <address_group_object> element (on page 35) › <address_object> element (on page 36) › <service_group_object> element (on page 80) › <service_object> element (on page 81) › <firewall_application> element (on page 53) › <firewall_user> element (on page 54) › <firewall_user_group> element (on page 54) › <host_ref> element (on page 60) › <asset_ref> element (on page 45) › Banners (on page 80) › AddComment method (on page 105) › AddConfigFile method (on page 106) › AddHost method (on page 115) › SetLastScanTime method (on page 152) › SetEntityValue method (on page 150) › The Assets topic in the Skybox Reference Guide



<asset_category> element

Note: The <asset_category> element supersedes the <host_group [group_type=Generic]> element. (This <host_group> element functionality is retained for backward compatibility.)

Syntax with 1st-level subelements <asset_category> <asset_ref> <network_ref> </asset_category>

Description The <asset_category> element adds a generic asset group to the model.

(To add other types of asset groups, use the <host_group> element (see page 59).)

Attributes The attributes of the <asset_category> element are described in the following table.


name The name of the asset group.

owner The name of the asset group owner.

ip_network The IP network of the asset group.


See also

› <group_ref> element (on page 55) › <asset_ref> element (on page 45) › AddHostGroup method (on page 117) › The Asset groups topic in the Skybox Reference Guide

<asset_group> element

Note: The <asset_group> element supersedes the <host_group group_type=BusinessUnit> element. (This <host_group> element functionality is retained for backward compatibility.)

Syntax with 1st-level subelements <asset_group> <asset_ref> <network_ref> </asset_group>

Description The <asset_group> element adds a Business Unit asset group to the model.

(To add other types of asset groups, use the <host_group> element (see page 59).)



Attributes The attributes of the <asset_group> element are described in the following table.






See also

› <group_ref> element (on page 55) › <asset_ref> element (on page 45) › AddHostGroup method (on page 117) › The Asset groups topic in the Skybox Reference Guide

<asset_ref> element


Description The <asset_ref> element references an asset.

Note: Use the <asset_ref> element as a subelement of the <asset_category> element (see page 44) and the <asset_group> element (see page 44) only. To reference an asset elsewhere, use the <host_ref> element (see page 59).

Attributes The attributes of the <asset_ref> element are described in the following table.


ip The name or IP address of the referenced asset.

unique_tag Add this attribute to an <asset_ref> element if: • The IP address might not be a unique identifier in the

network • Your organization has a unique ID for each asset

(based on a proprietary database) and wants to use this ID as the key (instead of the name or IP address) when merging assets in the model

See also

› <asset> element (on page 40) › AddHostRef method (on page 118)



<business_impact_type> element

Syntax with 1st-level subelements <business_impact_type> <application_ref> </business_impact_type>

Description The <business_impact_type> element adds a Business Impact to the model. A Business Impact is a way of measuring loss from damages on a Business Asset Group.

Attributes The attributes of the <business_impact_type> element are described in the following table.


name The name of the Business Impact.

effect The effect of the Business Impact. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

value The qualitative value (Business Impact level) of the damage. For a list of possible values, see Enum for the damage level parameter (on page 156).

rate The quantitative value of the damage, in default currency units. The default value is 10000. Note: This attribute is applicable only if the value attribute is not included or if this attribute is named and placed before the value attribute.

See also

› <application_ref> element (on page 38) › AddBusinessImpactType method (on page 103)

<business_model> element

Syntax with 1st-level subelements <business_model> <application> <business_unit> <damage> <dependency> <regulation> <business_impact_type> <location> <threat> <threat_group> </business_model>



Description The <business_model> element contains the elements that define the business hierarchy of the model (see Skybox model (on page 15)).

A <business_model> element is generated for the 1st occurrence in the file of an AddApplication, AddDamage, AddThreat, AddDependency, AddLocation, or AddBusinessUnit method. Only one <business_model> element is generated per file.

Attributes The <business_model> element has no attributes.

See also

› <application> element (on page 37) › <business_unit> element (on page 47) › <damage> element (on page 50) › <dependency> element (on page 51) › <regulation> element (on page 73) › <business_impact_type> element (on page 46) › <location> element (on page 67) › <threat> element (on page 85) › <threat_group> element (on page 86) › AddApplication method (on page 99) › AddDamage method (on page 109) › AddThreat method (on page 138) › AddDependency method (on page 110) › AddLocation method (on page 125) › AddBusinessUnit method (on page 104)

<business_unit> element

Syntax with 1st-level subelements <business_unit> <application_ref> <business_unit_ref> <group_ref> <location_ref> </business_unit>

Description The <business_unit> element adds a Business Unit to the model. A Business Unit is a group of Business Asset Groups.

Attributes The attributes of the <business_unit> element are described in the following table.




name The name of the Business Unit.

owner The name of the Business Unit owner.


uid The ID of the Business Unit.

See also

› <application_ref> element (on page 38) › <business_unit_ref> element (on page 48) › <group_ref> element (on page 55) › <location_ref> element (on page 68) › AddBusinessUnit method (on page 104)

<business_unit_ref> element


Description The <business_unit_ref> element references a Business Unit.

Attributes The attributes of the <business_unit_ref> element are described in the following table.


name The name of the referenced Business Unit.

uid The ID of the referenced Business Unit.

See also

› <business_unit> element (on page 47) › AddBusinessUnitRef method (on page 105)

<config_check_result> element

Syntax with 1st-level subelements <config_check_result> <host_ref> </config_check_result>

Description The <config_check_result> element adds a Configuration Check result to the model.

Attributes The attributes of the <config_check_result> element are described in the following table.




key A unique value that Skybox uses to match the result of the Configuration Check to the check definition in Skybox.

type Specifies whether this is a Network Assurance result or a Firewall Assurance result. • Network • Device

status Specifies whether the Configuration Check passed (GREEN) or failed (RED).

detection_time The time of the analysis. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

file_name The configuration file that contains the violation.

line_number The line number in the configuration file that contains the violation, if relevant.

actual_result A string that describes the violation.

See also

› <network_model> element (on page 72) › <host_ref> element (on page 60)

<config_file> element


Description The <config_file> element retrieves the original configuration file of an asset and stores it as part of the asset data.

Attributes The attributes of the <config_file> element are described in the following table.


path The full path (including the file name) of the configuration file

See also

› <asset> element (on page 40) › AddConfigFile method (on page 106)

<creation_time> element


Description The <creation_time> element sets the model creation time.



Use only one instance of this element per iXML file.

Functionally, this element is equivalent to the creation_time attribute of the <intermediate_model> element.

Note: If both this element and the creation_time attribute of the <intermediate_model> element are in an iXML file, Skybox uses the creation_time attribute.

Attributes The attributes of the <creation_time> element are described in the following table.


time The creation time of the model. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes. The default value is the current date and time.

See also

› <intermediate_model> element (on page 62) › SetCreationTime method (on page 149)

<custom_property> element


Description The <custom_property> element adds a business attribute to an asset.

Attributes The attributes of the <custom_property> element are described in the following table.


property_name The name of the business attribute.

property_value The value of the business attribute.

See also


<damage> element

Syntax with 1st-level subelements <damage> <host_ref> <application_ref> </damage>



Description The <damage> element adds a Business Impact to the model. (Business Impacts quantify damage caused to Business Asset Groups.)

Attributes The attributes of the <damage> element are described in the following table.


name The name of the damage.

effect The effect of the damage. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

per_member Specifies how the security of a Business Asset Group depends on the security of its member assets. • true • false

value The qualitative value (damage level) of the damage. For a list of possible values, see Enum for the damage level parameter (on page 156).

rate The quantitative value of the damage, in default currency units. Note: This attribute is applicable only if the value attribute is not included or if this attribute is placed before the value attribute.

See also

› <application_ref> element (on page 38) › AddDamage method (on page 109)

<dependency> element

Syntax with 1st-level subelements <dependency> <source> <destination> </dependency>

Description The <dependency> element adds a dependency rule to the model. Dependency rules specify how attacks on assets affect the security of the Business Asset Groups. For example, an availability loss of a DNS server might imply an availability loss for a Business Asset Group.

Note: A dependency rule also needs a <source> element (cause) and a <destination> element (effect).

Attributes The attributes of the <dependency> element are described in the following table.




name The name of the dependency rule.

effect The effect of the dependency. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

any Specifies whether compromise of any member asset or network entity causes the damage listed under effect. • true (default) (compromise if any member causes

damage) • false (only compromise if all members cause damage)

See also

› <destination> element (on page 52) › <source> element (on page 82) › AddDependency method (on page 110) › The Adding dependency rules topic in the Skybox Vulnerability Control User

Guide

<destination> element

Syntax with 1st-level subelements <destination> <application_ref> <host_ref> </destination>

Description The <destination> element adds a destination to a dependency rule. A destination is the effect of possible damage (for example, an availability loss on a payment system).

Attributes The attributes of the <destination> element are described in the following table.


effect Any combination of: • C (confidentiality) • I (integrity) • A (availability)

See also

› <dependency> element (on page 51) › <source> element (on page 82) › <application_ref> element (on page 38) › <host_ref> element (on page 60) › AddDependency method (on page 110) › AddDependencyDestination method (on page 111)



› AddDependencySource method (on page 112)

<firewall_application> element


Description The <firewall_application> element adds a firewall application to a firewall.

Attributes The attributes of the <firewall_application> element are described in the following table.


name The name of the firewall application.

standard_ports A comma-separated list of ports

See also


<firewall_application_group> element

Syntax with 1st-level subelements <firewall_application_group> <firewall_app_ref> </firewall_application_group>

Description The <firewall_application_group> element adds a firewall application group to a firewall.

Attributes The attributes of the <firewall_application_group> element are described in the following table.


name The name of the firewall application group

standard_ports A comma-separated list of ports

See also

› <firewall_application> element (on page 53) › <asset> element (on page 40)

<firewall_app_ref> element




Description The <firewall_app_ref> element references a firewall application.

Attributes The attributes of the <firewall_user_ref> element are described in the following table.


name The name of the referenced firewall application.

See also

› <firewall_application> element (on page 53)

<firewall_user> element


Description The <firewall_user> element adds a firewall user to a firewall.

Attributes The attributes of the <firewall_user> element are described in the following table.


name The name of the firewall user.

See also


<firewall_user_group> element

Syntax with 1st-level subelements <firewall_user_group> <firewall_user_ref> </firewall_user_group>

Description The <firewall_user_group> element adds a firewall user group to a firewall.

Attributes The attributes of the <firewall_user_group> element are described in the following table.


name The name of the firewall user group.

See also

› <firewall_user> element (on page 54)




<firewall_user_ref> element


Description The <firewall_user_ref> element references a firewall user.

Attributes The attributes of the <firewall_user_ref> element are described in the following table.


name The name of the referenced firewall user.

See also

› <firewall_user> element (on page 54)

<group_ref> element


Description The <group_ref> element references an asset group.

Attributes The attributes of the <group_ref> element are described in the following table.


name The name of the referenced asset group.

See also

› <host_group> element (on page 59) › <asset_category> element (on page 44) › <asset_group> element (on page 44) › AddGroupRef method (on page 115)

<host> element

Note: The <host> element is superseded by the <asset> element (see page 40). It is retained for backward compatibility.

Syntax with 1st-level subelements <host> <access_rule> <interface> <nat_rule>



<routing_rule> <service> <vulnerability> <patch> <vpn_unit> <ips_access_rule> <ips_rule_group> <vrouter> <config_file> <address_object> <address_group_object> <service_object> <service_group_object> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <custom_property> </asset>

Description The <host> element adds an asset to the model.

Attributes The attributes of the <host> element are described in the following table.


hostname The comma-separated names of the asset. Note: The equivalent <asset> element attribute (see page 40) is assetname. Optionally, append a colon and the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID



dynamic_routing Specifies whether dynamic routing is enabled. The default value is false. Note: This attribute is applicable only if the value of type is set to Router.

layer2 Specifies whether this asset is an L2 gateway. Note: An L2 gateway must have at least one L2 network interface.

do_not_outdate Specifies whether the asset is protected against aging. The default value is false. Assets that are not marked as protected against aging are



Attribute Description checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, assets imported using iXML are not updated on a regular basis so should not be outdated. In this case, set this flag to true.

os The operating system vendor, name, and version. Note: The value for this attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

platform The platform vendor, name, and, if applicable, version. Note: The value for this attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

inbound_chains A comma-separated list of the names of inbound rule chains to use for access rules. Note: This attribute is applicable only if type is set to Firewall.

outbound_chains A comma-separated list of the names of outbound rule chains to use for access rules. Note: This attribute is applicable only if type is set to Firewall.


last_scan_time The time of the most recent scan of the asset. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.


unique_tag Add this attribute to an asset if: • The hostname (or IP address) might not be a unique

identifier in the network • Your organization has a unique ID for each asset

(based on a proprietary database) and wants to use this ID as the key (instead of the IP address or asset name) when merging assets in the model

name_tag An additional name for the asset used when merging data.

owner The name of the asset owner.


is_virtual Specifies whether the asset is a virtual machine. The default value is false.




is_distributed Specifies whether the asset is a distributed virtual switch. The default value is false.

primary_chain The name and direction of the primary chain. Note: This attribute is applicable only if type is set to Firewall.

secondary_chain The name and direction of the secondary chain. Note: This attribute is applicable only if type is set to Firewall.

domain The domain of the asset. If this field is empty, the asset is not part of a known domain.

user The user that is associated with the asset.

last_login_time The date and time of the most recent login to the asset. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

latitude The latitude coordinate of the asset.

longitude The longitude coordinate of the asset.

high_availability_active

Specifies whether the asset is the active or passive member of a high availability cluster.

See also

› <asset> element (on page 40) › <access_rule> element (on page 33) › <interface> element (on page 60) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › <service> element (on page 79) › <vulnerability_occurrence> element (on page 90) › <patch> element (on page 73) › <vpn_unit> element (on page 88) › <ips_access_rule> element (on page 63) › <ips_rule_group> element (on page 65) › <host_ref> element (on page 60) › <vrouter> element (on page 88) › <config_file> element (on page 49) › <custom_property> element (on page 50) › <address_group_object> element (on page 35) › <address_object> element (on page 36) › <firewall_application> element (on page 53) › <firewall_user> element (on page 54)



› <firewall_user_group> element (on page 54) › <service_group_object> element (on page 80) › <service_object> element (on page 81) › Banners (on page 80) › AddComment method (on page 105) › AddConfigFile method (on page 106) › AddHost method (on page 115) › SetLastScanTime method (on page 152) › SetEntityValue method (on page 150) › The Assets topic in the Skybox Reference Guide

<host_group> element

Note: The <host_group> element with no group_type or group_type = Generic (the default) is superseded by the <asset_category> element (see page 44). The <host_group> element with group_type = BusinessUnit is superseded by the <asset_group> element (see page 44). Functionality is retained for backward compatibility.

Syntax with 1st-level subelements <host_group> <host_ref> <network_ref> </host_group>

Description The <host_group> element adds an asset group to the model.

Attributes The attributes of the <host_group> element are described in the following table.



group_type The type of the asset group. • Location • Generic (default) • Role • Cluster • Application • BusinessUnit • DeviceFolder • MAP_GROUP • VirtualFirewallGroup • NetworkGroup • VirtualizationCluster • VirtualizationDataCenter







See also

› <asset_category> element (on page 44) › <asset_group> element (on page 44) › <group_ref> element (on page 55) › <host_ref> element (on page 60) › AddHostGroup method (on page 117) › The Asset groups topic in the Skybox Reference Guide

<host_ref> element


Description The <host_ref> element references an asset.

Attributes The attributes of the <host_ref> element are described in the following table.



unique_tag Add this attribute to a <host_ref> element if: • The IP address might not be a unique identifier in the

network • Your organization has a unique ID for each asset

(based on a proprietary database) and wants to use this ID as the key (instead of the name or IP address) when merging assets in the model

See also

› <asset> element (on page 40) › AddHostRef method (on page 118)

<interface> element


Description The <interface> element adds an asset’s network interface to the model.

Attributes The attributes of the <interface> element are described in the following table.




ip_address The IP address of the interface.

ip_mask The netmask of the interface.

locked Specifies whether to lock the interface to a network. The default value is false.

mac_address The MAC address of the interface. Note: This attribute is applicable only if type is set to Ethernet.

name The name of the interface.

network The network to which the interface is connected. Note: To attach an interface to an empty network, omit the network attribute for that interface.

segment The segment to which the interface is connected. (Segments are used for interfaces of L2 gateway devices.)

type The interface type. For a list of possible values, see Enum for the network interface type parameter (on page 157). The default value is Ethernet.

is_primary Specifies whether the interface is the primary interface of the network. The default value is false.

layer2 Specifies whether the interface is an L2 interface. The default value is false.


proxy_arp_type The ARP state of the interface: • Static: The interface acts as a proxy for ARP requests

for IP address ranges. The address ranges are set by the public_arp_range attribute.

• Disabled: Proxy ARP is disabled on the interface. • Unknown: The ARP state of the interface is unknown.

In Skybox, proxy ARP is not simulated on the interface.

public_arp_range (Relevant if proxy_arp_type = Static.) The IP address ranges for which the interface acts as a proxy for ARP requests.

zone The zone to which the interface belongs.

vrouter (Used when working with virtual routers) The virtual router to which the interface belongs.


abi The ABI (addresses behind interface) of the interface. A semicolon-separated list of IP addresses or networks. • Separate the values of a range with a hyphen.

description A description of the interface.



Note: In Skybox Manager, you can define multiple virtual interfaces with the same IP address for the same device; in iXML only 1 virtual interface can have the same IP address as the physical interface. By using VPN-type interfaces and not virtual interfaces, you can define multiple interfaces with the same IP address.

See also

› <asset> element (on page 40) › AddComment method (on page 105) › AddInterface method (on page 118) › The Network interfaces section in the Skybox Reference Guide › SetEntityValue method (on page 150)

<intermediate_model> element

Syntax with 1st-level subelements <intermediate_model> <creation_time> <network_model> <business_model> </intermediate_model>

Description The <intermediate_model> element is the root element of the model (see Skybox model (on page 15)).

The 1st line of code in an iXML document must be: <?xml version="1.0" encoding="UTF-8" ?>

The 2nd line of code in an iXML document must be the <intermediate_model> root element.

Use only one <intermediate_model> element per iXML document.

Note: This element is generated by the IntegrationSecurityModel method.

Attributes The attributes of the <intermediate_model> element are described in the following table.


version The version of the model.

method The discovery method for the data. For a list of possible values, see Enum for the discovery method parameter (on page 156). The default value is INTERMEDIATE.

creation_time The creation time of model. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes. The default value is the current date and time.




last_scan_time The time of the most recent scan of all elements of the model. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

See also

› <business_model> element (on page 46) › <creation_time> element (on page 49) › <network_model> element (on page 72) › IntegrationSecurityModel method (on page 145) › SetCreationTime method (on page 149) › SetLastScanTime method (on page 152) › SetDiscoveryMethod method (on page 150)

<ip_range_ref> element


Description The <ip_range_ref> element references an IP address range.

Attributes The attributes of the <ip_range_ref> element are described in the following table.


ip A semicolon-separated list of IP addresses and address ranges. If you specify an address range, use the start and end addresses separated by a hyphen.

See also

› AddIPRangeRef method (on page 120)

<ips_access_rule> element


Description The <ips_access_rule> element adds an IPS access rule to an asset. Every packet that matches the rule scope is inspected using the rules in the referenced IPS rule group (protection domain). For information about IS devices, see the IPS support in Skybox section in the Skybox Vulnerability Control User Guide.



Attributes The attributes of the <ips_access_rule> element are described in the following table.


id A unique value (for the asset containing this IPS access rule). If this attribute is not included, a value is assigned.

source A semicolon-separated list of source IP addresses or networks for this IPS access rule. • Separate the values of a range with a hyphen.

The default value is ANY.

destination A semicolon-separated list of destination IP addresses or networks for this IPS access rule. • Separate the values of a range with a hyphen.

The default value is ANY.

service The IPS access rule service; the format of each service can be: • Source port, destination port, and protocol, separated



port, and protocol are permitted direction The IPS access rule direction.

• Inbound • Outbound • Both (default)

chain The name of the rule chain to which the IPS access rule belongs. Rule chain names are set by the <asset> element (on page 40). The default value is IPS.

applied_interfaces A semicolon-separated list of the IP addresses or interface names of the network interfaces for the IPS access rule. • IP address ranges are not permitted.

The default is all interfaces.

source_interfaces A semicolon-separated list of the IP addresses or interface names of the source interfaces for the IPS access rule. • IP address ranges are not permitted.

The default is all interfaces.

ips_rule_group_ref

A reference to the associated <ips_rule_group> element (see page 65).





orig_text The IPS access rule specified in the configuration file.




implied Specifies whether the IPS access rule is implied. The default value is false.

disabled Specifies whether the IPS access rule is disabled. The default value is false.







application A semicolon-separated list of applications that are permitted for this IPS access rule.

user KNOWN, UNKNOWN, or a semicolon-separated list of user names.

acl_expiration_date

The expiration date of the IPS access rule. If a rule has passed its expiration date, Skybox does not use it in access analysis, Access Compliance, or attack simulation. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

See also

› <asset> element (on page 40) › <ips_rule_group> element (on page 65) › AddIpsAccessRule method (on page 121) › AddIpsRuleGroup method (on page 124) › The Assets topic in the Skybox Reference Guide

<ips_rule_group> element

Syntax with 1st-level subelements <ips_rule_group> <ips_rule> <ips_rule_group>

Description The <ips_rule_group> element adds an IPS rule group to an asset.

Attributes The attributes of the <ips_rule_group> element are described in the following table.




name The name of the IPS rule group. The name must be the same as the ips_rule_group_ref attribute of the <ips_access_rule> element (see page 65).

See also

› <asset> element (on page 40) › <ips_access_rule> element (on page 63) › AddIpsAccessRule method (on page 121) › AddIpsRuleGroup method (on page 124) › The Assets topic in the Skybox Reference Guide

<ips_rule> element


Description The <ips_rule> element adds an IPS rule to an IPS rule group.

Attributes The attributes of the <ips_rule> element are described in the following table.


title A title for the IPS rule.

action The IPS rule action. • detect • prevent (default)

protocol • http • unknown (default)

FP_level The estimated probability that this rule generates a false positive.

FP_original The probability of a false positive specified in the configuration file.

FN_level The estimated probability that this rule generates a false negative.

FN_original The probability of a false negative specified in the configuration file.

severity • info • low • medium (default) • high • critical

disabled Specifies whether the rule is disabled. The default value is false.

severity_original The severity specified in the configuration file.




user_defined Specifies whether the rule is user-defined. • true: A custom rule is created even if

vendor_rule_id is in the Skybox Vulnerability Dictionary

• false (default) vendor_rule_id The name of the vendor vulnerability database, followed

by a “/”, followed by the ID in the database of the Vulnerability Definition to which this rule applies. For a list of possible vendor databases, see Enum for the definition parameter (on page 157). You must include either vendor_rule_id or vulnerabilities.

vulnerabilities The string “SBV/” followed by the ID (from the Skybox Vulnerability Dictionary) of the Vulnerability Definition to which this rule applies. You must include either vulnerabilities or vendor_rule_id.


See also

› <ips_rule_group> element (on page 65) › AddIpsRule method (on page 123) › The Assets topic in the Skybox Reference Guide

<location> element

Syntax with 1st-level subelements <location> <network_ref> <location_ref> </location>

Description The <location> element adds a location to the model.

Attributes The attributes of the <location> element are described in the following table.


name The name of the location.

See also

› <location_ref> element (on page 68) › AddLocation method (on page 125)



<location_ref> element


Description The <location_ref> element references a location.

Attributes The attributes of the <location_ref> element are described in the following table.


name The name of the referenced location.

See also

› <location> element (on page 67) › AddLocationRef method (on page 126)

<nat_rule> element


Description The <nat_rule> element adds a NAT access rule to an asset.

Attributes The attributes of the <nat_rule> element are described in the following table.


id A unique value (for the asset containing the NAT rule). If this attribute is not included, a value is assigned.

uid The ID of the NAT rule (used when comparing routing rules).

source A semicolon-separated list of source IP addresses or networks. • Separate the values of a range with a hyphen.


destination A semicolon-separated list of destination IP addresses or networks. • Separate the values of a range with a hyphen.


service The NAT rule service; the format of each service can be: • Source port, destination port, and protocol, separated


semicolon • The string ANY (default): Any source port,

destination port, and protocol are permitted




translated_source The translated source IP address.

translated_destination

The translated destination IP address.

translated_service The translated service.

direction The NAT rule direction. • Inbound • Outbound • Both (default)

chain The name of the rule chain to which to add the NAT rule. Rule chain names are set by the <asset> element (on page 40). Note: Rules are added in the order in which they occur in the iXML.

applied_interfaces A semicolon-separated list of the IP address of each network interface for the NAT rule. • IP address ranges are not permitted.

source_interfaces A semicolon-separated list of the IP address of each source interface for the NAT rule. • IP address ranges are not permitted.





orig_text The NAT rule specified in the configuration file.

implied Specifies whether the NAT rule is implied. The default value is false.

disabled Specifies whether the NAT rule is disabled. The default value is false.


description A description of the NAT rule.

translated_source_obj

A semicolon-separated list of translated source IP address object names.

translated_destination_obj

A semicolon-separated list of translated destination IP address object names.

translated_service_obj

A semicolon-separated list of translated service object names.









log_enable Specifies whether the NAT rule is loggable. The default value is true.

is_negated_source Specifies whether the NAT rule applies to all source addresses except those in the source attribute. The default value is false.


Specifies whether the NAT rule applies to all destination addresses except those in the destination attribute. The default value is false.

is_negated_service Specifies whether the NAT rule applies to all services except those in the service attribute. The default value is false.


acl_expiration_date

The expiration date of the NAT rule. If a rule has passed its expiration date, Skybox does not use it in access analysis, Access Compliance, or attack simulation. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

See also

› <asset> element (on page 40) › <access_rule> element (on page 33) › <routing_rule> element (on page 74) › AddComment method (on page 105) › AddNatRule method (on page 126) › The Assets topic in the Skybox Reference Guide

<network> element

Syntax with 1st-level subelements <network> <segment> </network>

Description The <network> element adds a network to the model.

Attributes The attributes of the <network> element are described in the following table.


name The name or IP address of the network.

number The IP address of the network.

mask The netmask of the network.




type The network type. For a list of possible values, see Enum for the network type parameter (on page 157). The default value is Regular.

last_scan_time The time of the most recent scan of the network. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

do_not_outdate Specifies whether the network is protected against aging. The default value is false. Entities in a network that is not marked as protected against aging are checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, networks imported using iXML are not updated on a regular basis so should not be outdated. In this case, set this flag to true.

source_alternative_ip_ranges

This attribute is applicable only if type is set to Cloud. A comma-separated list of IP address ranges to include in the network scope.

source_excluded_ip_ranges

This attribute is applicable only if type is set to Cloud. A comma-separated list of IP address ranges to exclude from the network scope.

destination_alternative_ip_ranges

This attribute is applicable only if type is set to Cloud. A comma-separated list of IP address ranges to use as destination addresses from the network.

destination_excluded_ip_ranges

This attribute is applicable only if type is set to Cloud. A comma-separated list of IP address ranges to exclude from the destination address ranges of the network.

owner The name of the network owner.

zone_id The GUID of the zone to which this network belongs.

include_hosts

is_forwarding This attribute is applicable only if type is set to Cloud. Specifies whether forwarding is enabled (that is, whether the network can forward packets from one interface to another).


See also

› <network_ref> element (on page 72) › <segment> element (on page 77) › AddComment method (on page 105) › AddNetwork method (on page 128) › SetCloudDestinationAlternativeIPRanges method (on page 146)



› SetCloudDestinationExcludedIPRanges method (on page 147) › SetCloudSourceAlternativeIPRanges method (on page 147) › SetCloudSourceExcludedIPRanges method (on page 148) › SetEntityValue method (on page 150) › SetLastScanTime method (on page 152) › The Networks topic in the Skybox Reference Guide

<network_model> element

Syntax with 1st-level subelements <network_model> <network> <asset> <host_group> <asset_category> <asset_group> <vpn_tunnel> <config_check_result> </network_model>

Description The <network_model> element contains the elements that define the network information of the model (see Skybox model (on page 15)).

A <network_model> element is generated for the 1st occurrence in the file of an AddNetwork, AddHost, or AddInterface method. Only one <network_model> element is generated per file.

Attributes The <network_model> element has no attributes.

See also

› <host_group> element (on page 59) › <asset_category> element (on page 44) › <asset_group> element (on page 44) › <asset> element (on page 40) › <network> element (on page 70) › <vpn_tunnel> element (on page 87) › <config_check_result> element (on page 48) › AddNetwork method (on page 128) › AddHost method (on page 115) › AddInterface method (on page 118)

<network_ref> element




Description The <network_ref> element references a network.

Attributes The attributes of the <network_ref> element are described in the following table.


ip The IP address of the referenced network.

See also

› <network> element (on page 70) › AddNetworkRef method (on page 130)

<patch> element


Description The <patch> element adds patch information to an asset.

Attributes The attributes of the <patch> element are described in the following table.


product The product banner (of the product to which the patch is applied). The value must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

code The patch code (patch ID).


See also

› AddComment method (on page 105) › AddPatch method (on page 131)

<regulation> element

Syntax with 1st-level subelements <regulation> <application_ref> </regulation>



Description The <regulation> element adds a Regulation to the model. A Regulation is a way of measuring loss on a Business Asset Group. Regulations involve damage to Business Asset Groups as a compromise to a security regulation with which organizations must comply.

Attributes The attributes of the <regulation> element are described in the following table.


name The name of the Regulation.

effect The effect of the Regulation. Any combination of: • C (confidentiality) • I (integrity) • A (availability)


rate The quantitative value of the damage, in default currency units. The default value is 10000. Note: This attribute is applicable only if the value attribute is not included or if this attribute is named and placed before the value attribute.

See also

› <application_ref> element (on page 38) › AddRegulation method (on page 132)

<routing_rule> element


Description The <routing_rule> element adds a routing rule to an asset.

Attributes The attributes of the <routing_rule> element are described in the following table.


destination The name or IP address of the destination network for the rule.

gateway The gateway IP address for the rule.

dynamic Specifies whether the rule was created by a dynamic routing protocol (see the Specifying routing rules section in the Skybox Reference Guide).

interface The network interface for the rule.




vrouter The virtual router through which to route traffic.

via_vrouter Specifies whether to direct the traffic through a specific virtual router.

via_global Specifies whether to direct the traffic through the global virtual router.

null_route Specifies whether the route is considered as a route to null (that is, packets arriving after a match is made are discarded).

preference The Skybox routing rule metric value for the network destination. The value is 1 by default.


See also

› <asset> element (on page 40) › <access_rule> element (on page 33) › <nat_rule> element (on page 68) › <vrouter> element (on page 88) › AddComment method (on page 105) › AddRoutingRule method (on page 133) › The Assets topic in the Skybox Reference Guide › The Working with routing rules chapter in the Skybox Reference Guide

<security_group> element

Syntax with 1st-level subelements <security_group> <host_ref> </security_group>

Description The <security_group> element adds a security group to the model.

Attributes The attributes of the <security_group> element are described in the following table.


id A unique ID (for the asset containing this security group) that Skybox uses to sort the security groups. If this attribute is not included, the security groups are sorted according to creation time.

name The name of the security group.

description A description of the security group.




See also

› The Virtualization and clouds topic in the Skybox Vulnerability Control User Guide or the Skybox Network Assurance User Guide

<security_group_ref> element


Description The <security_group_ref> element references a security group.

Attributes The attributes of the <security_group_ref> element are described in the following table.


id The ID of the referenced security group.

See also

› <tenant> element (on page 85)

<security_tag> element

Syntax with 1st-level subelements <security_tag> <host_ref> <access_rule> <nat_rule> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <address_object> <address_group_object> <service_object> <service_group_object> </security_tag>

Description The <security_tag> element adds a security tag to the model.

Attributes The attributes of the <security_tag> element are described in the following table.


id A unique ID (for the asset containing this security tag) that Skybox uses to sort the security tags. If this attribute is not included, the security tags are sorted according to creation time.

name The name of the security tag.




description A description of the security tag.

tag_position The position of the security tag (in the asset containing the tag).


See also


<security_tag_ref> element


Description The <security_tag_ref> element references a security tag.

Attributes The attributes of the <security_tag_ref> element are described in the following table.


id The ID of the referenced security tag.

See also

› <tenant> element (on page 85)

<segment> element

Syntax with 1st-level subelements <segment> <host_ref> <ip_range_ref> </segment>

Description The <segment> element adds a segment to a network.

Attributes The attributes of the <segment> element are described in the following table.


name The name of the segment to add to the network.




type The segment type. • Regular: Used for physical segments • Virtual Machines • Service Console • VMkernel • Virtual Uplinks

Note: Regular is the default value and the value of segments that have no type (for backward compatibility). The other values relate to VMware port groups.

is_virtual Specifies whether the segment represents a virtual network. The default value is false.

private_vlan_type The type of a private VLAN segment (in the context of VMware private VLANs). • Promiscuous • Community • Isolated • Non Private

Note: The default value (and the value to use unless the segment is a private VLAN) is null.

parent_vlan_id The VLAN ID of the parent segment (for VMware PVLAN segments). Note: If the segment is not a VLAN network, the value is null.

vlan_id The VLAN ID of an L2 network. Note: If the segment is not a VLAN network, the value is null.

is_distributed Specifies whether the segment represents a distributed virtual network. The default value is false.

is_promiscuous Specifies whether the segment is promiscuous. The default value is false.

other_names Additional, comma-separated names for the segment. Optionally, append a colon and the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID


See also

› <host_ref> element (on page 60) › <ip_range_ref> element (on page 63)



› AddComment method (on page 105) › AddSegment method (on page 135)

<service> element

Syntax with 1st-level subelements <service> <vulnerability_occurrence> </service>

Description The <service> element adds a service to an asset.

Attributes The attributes of the <service> element are described in the following table.


banner The service banner, which helps Skybox to select the service definition from the Skybox Vulnerability Dictionary to apply. The value must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

vendor_banner The vendor name specified in the service banner.

product_banner The product name specified in the service banner.

version_banner The version specified in the service banner.

port The service port number and protocol.

interfaces A semicolon-separated list of interfaces to which the service is bound (the applied interfaces). • Separate the values of a range with a hyphen.

last_scan_time The time of the most recent scan of the service. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

status • Up • Down • Unknown


See also

› <asset> element (on page 40) › <vulnerability_occurrence> element (on page 90) › Banners (on page 80) › AddComment method (on page 105) › AddService method (on page 135) › SetEntityValue method (on page 150) › SetLastScanTime method (on page 152)



› The Services topic in the Skybox Reference Guide

Banners The banner is a service-related text field that Skybox processes as part of offline file import or online collection. The banner helps Skybox to identify details of the device that is running this service.

The banner text can comprise the initial service output (for example, the Telnet banner for UNIX Telnet services) or a free text description.

If this field contains a value, Skybox checks whether it contains the vendor name, device name, version, or other useful information (for example, the name and version of the operating system). Successful device identification using the banner field enables Skybox to more precisely model the service. The content of the banner field must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (The file includes examples for each regular expression.) Services whose device cannot be identified are classified as Generic.

Examples of banner strings

› Telnet banner for Linux Red Hat Linux release 7.2 (Enigma) Kernel 2.4.7-10 on an i686 login:

From this banner, Skybox extracts the asset operating system (Red Hat Linux v.7.2) and understands that the Telnet service is native to the operating system.

› FTP service banner 220 snoopy FTP server (Version wu-2.6.1-18) ready. User (snoopy:(none)):

From this banner Skybox extracts the name and version of the FTP service (Washington University FTPD software, version 2.6.1-18). Unfortunately, this banner does not provide information about other services.

› Windows banner Microsoft Windows [Version 6.1.7601] Copyright (c) 2009 Microsoft Corporation. All rights reserved.

From this banner, Skybox extracts the necessary device details—operating system name, vendor, and version.

<service_group_object> element

Syntax with 1st-level subelements <service_group_object name> <service_object_ref name> </service_group_object>

Description The <service_group_object> element adds a service group object to an asset.



Attributes The attributes of the <service_group_object> element are described in the following table.




See also


<service_object> element


Description The <service_object> element adds a service object to an asset.

Attributes The attributes of the <service_object> element are described in the following table.



fw_services A semicolon-separated list of firewall services; the format of each service can be: • Source port, destination port, and protocol, separated



port, and protocol are permitted comment A free-form user comment.

See also

› <asset> element (on page 40) › <access_rule> element (on page 33) › AddServiceObject method (on page 136)

<service_object_ref> element


Description The <service_object_ref> element references a service group object.



Attributes The attributes of the <service_object_ref> element are described in the following table.


name The name of the generic service or group.

See also

› <service_group_object> element (on page 80)

<source> element

Syntax with 1st-level subelements <source> <application_ref> <host_ref> </source>

Description The <source> element adds a source to a dependency rule. A source describes the cause of possible damage (for example, an integrity or availability loss on the web servers in your system).

Attributes The attributes of the <source> element are described in the following table.


effect Any combination of: • C (confidentiality) • I (integrity) • A (availability)

See also

› <dependency> element (on page 51) › <destination> element (on page 52) › <application_ref> element (on page 38) › <host_ref> element (on page 60) › AddDependency method (on page 110) › AddDependencyDestination method (on page 111) › AddDependencySource method (on page 112)

<srv_conf_item> element


Description The <srv_conf_item> element adds a service object to the Skybox Application & Service repository available in Skybox Change Manager.



Attributes The attributes of the <srv_conf_item> element are described in the following table.



fw_services A semicolon-separated list of firewall services. • Separate the values of a range with a hyphen.

For example, "0-65535/80/TCP".

is_enable Specifies whether the service object is enabled in the repository.

owner The owner of the service.


See also

› <srv_group_conf_item> element (on page 83) › Example of iXML code for the Application & Service repository (on page 32)

<srv_conf_item_ref> element


Description The <srv_conf_item_ref> element references a service object in the repository.

Attributes The attributes of the <srv_conf_item_ref> element are described in the following table.


name The name of the service object.

See also

› <srv_conf_item> element (on page 82) › <srv_group_conf_item> element (on page 83)

<srv_group_conf_item> element

Syntax with 1st-level subelements <srv_group_conf_item name> <srv_group_conf_item_ref name> <srv_conf_item_ref name> </srv_group_conf_item>



Description The <srv_group_conf_item> element adds a service group object to the Skybox Application & Service repository available in Skybox Change Manager. Service groups can contain services and other service groups.

Attributes The attributes of the <srv_group_conf_item> element are described in the following table.



is_enable Specifies whether the service group object is enabled in the repository.

owner The owner of the service group.


See also

› Example of iXML code for the Application & Service repository (on page 32) › <srv_conf_item> element (on page 82) › <srv_group_conf_item_ref> element (on page 84)

<srv_group_conf_item_ref> element


Description The <srv_group_conf_item_ref> element references a service group object in the repository.

Attributes The attributes of the <srv_group_conf_item_ref> element are described in the following table.


name The name of the service group object.

See also

› <srv_group_conf_item> element (on page 83)



<tenant> element

Syntax with 1st-level subelements <tenant> <host_ref> <security_group_ref> <security_tag_ref> </tenant>

Description The <tenant> element adds a tenant (virtual domain) to the model.

Attributes The attributes of the <tenant> element are described in the following table.


id A unique ID (for the asset containing this tenant) that Skybox uses to sort the tenants. If this attribute is not included, the tenants are sorted according to creation time.

name The name of the tenant.

description A description of the tenant.

type The tenant type.

data_mode


See also


<threat> element

Syntax with 1st-level subelements <threat> <application_ref> <host_ref> <network_ref> </threat>

Description The <threat> element adds a threat to the model. (In Skybox Manager, a threat is named a Threat Origin.)

Attributes The attributes of the <threat> element are described in the following table.


name The name of the threat.

probability The probability of threat. For a list of possible values, see Enum for the threat



Attribute Description probability parameter (on page 157).

skill The skill required to actualize the threat. • LOW • MEDIUM • HIGH

value The value (damage level) of the threat. For a list of possible values, see Enum for the damage level parameter (on page 156).

See also

› <threat_group> element (on page 86) › <threat_ref> element (on page 86) › AddThreat method (on page 138)

<threat_group> element

Syntax with 1st-level subelements <threat_group> <threat_ref> </threat_group>

Description The <threat_group> element adds a threat group to the model. (In Skybox Manager, a threat group is named a Threat Category.)

Attributes The attributes of the <threat_group> element are described in the following table.


name The name of the threat group.

See also

› <threat> element (on page 85) › <threat_ref> element (on page 86)

<threat_ref> element


Description The <threat_ref> element references a threat.

Attributes The attributes of the <threat_ref> element are described in the following table.




name The name of the referenced threat.

See also

› <threat> element (on page 85) › <threat_group> element (on page 86) › AddThreatRef method (on page 139)

<vpn_tunnel> element


Description The <vpn_tunnel> element adds a secure VPN to the model.

Attributes The attributes of the <vpn_tunnel> element are described in the following table.





type The network type. For a list of possible values, see Enum for the network type parameter (on page 157).

endpoint1 One endpoint of the VPN tunnel.

endpoint2 The other endpoint of the VPN tunnel.

last_scan_time The time of the most recent scan of the VPN tunnel. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

display_as_cloud Specifies whether the VPN tunnel is displayed as a cloud.

do_not_outdate Specifies whether the VPN tunnel network is protected against aging. The default value is false. The entities of a network that is not marked as protected against aging are checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, VPN tunnels imported using iXML are not updated on a regular basis so should not be outdated. In this case, set this flag to true.




See also

› <vpn_unit> element (on page 88) › AddVpnTunnel method (on page 139) › SetLastScanTime method (on page 152)

<vpn_unit> element


Description The <vpn_unit> element adds a VPN unit to the model.

Attributes The attributes of the <vpn_unit> element are described in the following table.


name VPN unit name.

orig_text Original text of the VPN unit definition. This field might be filled during configuration parsing; it contains the relevant line that defines the VPN unit.

my_domain The domain of the VPN unit. The default value is ANY.

peer_domain The domain to which to connect. The default value is ANY.

service The service port number and protocol. The default value is ANY.

interface The name of the network interface that connects the VPN unit to the tunnel.

See also

› <vpn_tunnel> element (on page 87) › AddVpnUnit method (on page 141)

<vrouter> element


Description The <vrouter> element adds a vrouter (virtual router) to an asset.

Attributes The attributes of the <vrouter> element are described in the following table.


name The name of the vrouter.



Attribute Description The name must be the same as the vrouter attribute of the <routing_rule> element (see page 74) and the <interface> element (see page 60).

See also

› <asset> element (on page 40) › <routing_rule> element (on page 74) › <interface> element (on page 60) › AddVrouter method (on page 142)

<vulnerability> element

Note: The <vulnerability> element is superseded by the <vulnerability_occurrence> element (see page 90). It is retained for backward compatibility.


Description The <vulnerability> element adds a vulnerability occurrence to an asset or to a service.

Attributes The attributes of the <vulnerability> element are described in the following table.


type The name of the vulnerability database of the Vulnerability Definition of the vulnerability occurrence. Note: The equivalent <vulnerability_occurrence> element attribute (see page 90) is definition. For a list of possible values, see Enum for the definition parameter (on page 157).

id The ID (an integer) of the Vulnerability Definition in the database specified by type.

sbv_id The ID of the Vulnerability Definition of the vulnerability occurrence in the Skybox Vulnerability Dictionary. Note: If the Vulnerability Definition of the vulnerability occurrence is from the Vulnerability Dictionary rather than an external vulnerability database, it is sufficient to specify sbv_id; it is unnecessary to specify type (= SBV) and id.

title A title for the vulnerability occurrence. If provided, this title is used in Skybox Manager in the following cases: • Custom Vulnerability Definition: type, id, and sbv_id

are all specified, and sbv_id is the ID of a generic Vulnerability Definition in the Vulnerability Dictionary




(see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158)).

• The type + id pair is not in the Vulnerability Dictionary. (The vulnerability occurrence is mapped to ID 3326 (Uncataloged Generic Vulnerability) in the Vulnerability Dictionary.)

In all other cases, the title is taken from the Vulnerability Dictionary.

policy The scan from which the vulnerability occurrence came. Use this attribute to relate all vulnerability occurrences that come from the same scan.

last_scan_time The most recent time that the vulnerability occurrence was scanned. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

scanner_severity A severity for the vulnerability occurrence. • Info • Low • Medium • High • Critical

If provided, overwrites the Vulnerability Dictionary severity for custom Vulnerability Definitions only.

scanner_description

The description of the vulnerability occurrence from the scanner. If provided, overwrites the Vulnerability Dictionary description of custom Vulnerability Definitions only.


See also

› <vulnerability_occurrence> element (on page 90) › <asset> element (on page 40) › <service> element (on page 79) › AddComment method (on page 105) › AddCustomVulnerability method (on page 107) › AddVulnerability method (on page 142) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158)

(for custom Vulnerability Definitions) › SetLastScanTime method (on page 152) › The Vulnerability occurrences topics in the Skybox Reference Guide

<vulnerability_occurrence> element

Note: The <vulnerability_occurrence> element supersedes the <vulnerability> element. (The <vulnerability> element is retained for backward compatibility.)




Description The <vulnerability_occurrence> element adds a vulnerability occurrence to an asset or to a service.

Attributes The attributes of the <vulnerability_occurrence> element are described in the following table.


definition The name of the vulnerability database of the Vulnerability Definition of the vulnerability occurrence. Note: The equivalent <vulnerability> element attribute is type. For a list of possible values, see Enum for the definition parameter (on page 157).

id The ID (an integer) of the Vulnerability Definition in the database specified by definition.

sbv_id The ID of the Vulnerability Definition of the vulnerability occurrence in the Skybox Vulnerability Dictionary. Note: If the Vulnerability Definition of the vulnerability occurrence is from the Vulnerability Dictionary rather than an external vulnerability database, it is sufficient to specify sbv_id; it is unnecessary to specify definition (= SBV) and id.

title A title for the vulnerability occurrence. If provided, this title is used in Skybox Manager in the following cases: • Custom Vulnerability Definition: definition, id, and

sbv_id are all specified, and sbv_id is the ID of a generic Vulnerability Definition in the Vulnerability Dictionary (see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158)).

• The definition + id pair is not in the Vulnerability Dictionary. (The vulnerability occurrence is mapped to ID 3326 (Uncataloged Generic Vulnerability) in the Vulnerability Dictionary.)

In all other cases, the title is taken from the Vulnerability Dictionary.

policy The scan from which the vulnerability occurrence came. Use this attribute to relate all vulnerability occurrences that come from the same scan.

last_scan_time The time of the most recent scan of the vulnerability occurrence. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

scanner_severity A severity for the vulnerability occurrence. • Info • Low




• Medium • High • Critical

If provided, overwrites the Vulnerability Dictionary severity for custom Vulnerability Definitions only.

scanner_description

The description of the vulnerability occurrence from the scanner. If provided, overwrites the Vulnerability Dictionary description of custom Vulnerability Definitions only.


See also

› <asset> element (on page 40) › <service> element (on page 79) › AddComment method (on page 105) › AddCustomVulnerability method (on page 107) › AddVulnerability method (on page 142) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158)

(for custom Vulnerability Definitions) › SetLastScanTime method (on page 152) › The Vulnerability occurrences topics in the Skybox Reference Guide


Chapter 4

This chapter describes the Perl API methods that you can use to prepare an iXML file, including the relationships between API methods and iXML elements. For general information about how the API methods relate to iXML, see Integrating user data into a Skybox model (on page 14).

In this chapter

Parameters of API methods .................................................. 93

API methods and generated iXML code .................................. 93

Mandatory include statements for Perl scripts ......................... 94

Examples of Perl scripts ....................................................... 94

Description of Perl API methods ............................................ 96

PARAMETERS OF API METHODS Specify the parameters of an API method:

› In the order that they appear in the description of the API method › By name

If a parameter is specified by name, all following parameters must also be specified by name.

Enclose parameters in straight quotation marks (""). Quotation marks must appear even if the parameter is not set to any value; however, you can omit unset parameters at the end of the parameter list.

API METHODS AND GENERATED IXML CODE

Order of parameters in generated iXML code The order of parameters in the API methods is fixed (and explained in the documentation). The order of attributes in an iXML statement is not important. In generated iXML code elements, the attributes are listed alphabetically by attribute names.

Automatic generation of iXML code Under the following circumstances, some API methods additional generate iXML code:

› A <network_model> element is generated for the 1st occurrence in the file of an AddNetwork, AddHost, or AddInterface method. Only one <network_model> element is generated per file.

Perl API methods



› A <business_model> element is generated for the 1st occurrence in the file of an AddApplication, AddDamage, AddThreat, AddDependency, AddLocation, or AddBusinessUnit method. Only one <business_model> element is generated per file.

The automatically generated iXML code is inserted at the start of the method.

Attributes of elements that are not set by the corresponding API methods Most attributes of iXML elements are set using the corresponding API methods. For example, the AddHost method (see page 115) sets most of the attributes of an <asset> element (see page 40) and the AddService method (see page 135) sets most of the attributes of a <service> element (see page 79). However, some attributes cannot be set using these methods. Occasionally there are special methods to set these attributes, but attributes can always be added (or modified) using the SetEntityValue method (see page 150).

MANDATORY INCLUDE STATEMENTS FOR PERL SCRIPTS Perl scripts that generate iXML files for Skybox must contain the following include statements:

› use lib qw(<Skybox_Home>\intermediate\lib);

› use lib qw(<Skybox_Home>\intermediate\lib\external);

› use intermediate::IntermediateSecurityModel;

EXAMPLES OF PERL SCRIPTS You can use the Perl API methods to create iXML documents. The following sections contain example Perl scripts.

Perl script for creating an L2 firewall The iXML code output by the following script is at Example of iXML code for an L2 firewall (on page 30). ################################################################## # # cloud -> router -> net10 { l2fw -> protected_host } # ################################################################## use lib qw(../../lib); use lib qw(../../lib/external); use Getopt::Std; use strict; use util::Netstat; use util::Helper; use intermediate::IntermediateSecurityModel; my $now = localtime time; print "Sample ($now)\n\n"; my $outfile = "sampleL2.xml"; unlink($outfile); # initialize intermediate object and create the firewall

Chapter 4 Perl API methods


my $inm = new intermediate::IntermediateSecurityModel($outfile); # create internet cloud, with all addresses except network 10.0.0.0/8 my $cloud = $inm->AddNetwork("Inet-Cloud", "0.0.0.0", "0.0.0.0", "Cloud"); $inm->SetCloudSourceExcludedIPRanges($cloud, "10.0.0.0-10.255.255.255"); # create internal network with 2 segments my $netA = $inm->AddNetwork("NetworkA", "10.0.0.0", "255.255.255.0"); $inm->AddSegment($netA, "SegEXT"); $inm->AddSegment($netA, "SegINT"); # create l2fw # order of params: assetname, ip-forwarding, os, platform, inbound-chains, # outbound-chains, type, dynamic-routing my $swAsset = $inm->AddHost("l2fw", "true", "Juniper Networks ScreenOS", "Juniper Networks NetScreen", "Nat, Access", "Access, Nat", "Firewall", "true"); my $iface1 = $inm->AddInterface($swAsset, "10.0.0.1", "255.255.255.0", "", "eth0", "Ethernet"); $inm->AssignInterfaceToNetwork($iface1, "NetworkA"); $inm->AssignInterfaceToSegment($iface1, "SegINT"); my $iface2 = $inm->AddInterface($swAsset, "10.0.0.2", "255.255.255.0", "", "eth1", "Ethernet"); $inm->AssignInterfaceToNetwork($iface2, "NetworkA"); $inm->AssignInterfaceToSegment($iface2, "SegEXT"); $inm->AddService($swAsset, "HTTP", "80/TCP"); $inm->AddService($swAsset, "FTP", "21/TCP", "10.0.0.1"); my $acl1 = $inm->AddAccessRule($swAsset, "any", "any", "any", "Allow", "Both"); my $acl2 = $inm->AddAccessRule($swAsset, "any", "any", "any", "Deny", "Both"); # create server, put it on protected segment (segINT) my $srvAsset = $inm->AddHost("srv", "false", "Microsoft Windows Server 2003", "", "", "", "Server"); my $srvIface = $inm->AddInterface($srvAsset, "10.0.0.10", "255.255.255.0", "", "eth10", "Ethernet"); $inm->AssignInterfaceToNetwork($srvIface, "NetworkA"); $inm->AssignInterfaceToSegment($srvIface, "SegINT"); # create router, put it between inet and network 10 (external segment) my $router = $inm->AddHost("router", "true", "Linux", "", "", "", "Router"); my $internalIface = $inm->AddInterface($router, "10.0.0.254", "255.255.255.0", "", "eth10", "Ethernet"); $inm->AssignInterfaceToNetwork($internalIface, "NetworkA"); $inm->AssignInterfaceToSegment($internalIface, "SegEXT"); my $externalIface = $inm->AddInterface($router, "15.15.15.254", "255.255.255.0", "", "eth15", "Ethernet"); $inm->AssignInterfaceToNetwork($externalIface, "Inet-Cloud"); $inm->SetCreationTime(Helper::getCreationTime()); print "Writing $outfile\n"; $inm->Write($outfile); exit(0); # Main End



DESCRIPTION OF PERL API METHODS The Perl API methods are described in the following sections. The methods are listed in alphabetic order.

In these descriptions, examples are given of iXML code. The closing element of the iXML code is omitted for elements that can contain subelements.

Parameters that have a default value are optional; other parameters are mandatory unless specified as optional.

AddAccessRule method

Syntax The syntax of the Perl AddAccessRule method is: AddAccessRule(asset, source, destination, service, action, direction, chain, applied_interfaces, source_interfaces, disabled, implied, orig_name, uid)

Description The AddAccessRule method adds an access rule to an asset.

You can use multiple instances of this method per asset.

Parameters The parameters of the AddAccessRule method are described in the following table.

Parameter Description

asset A reference to the asset instance returned by the AddHost method.

source A comma-separated list of the source IP addresses or networks. • Separate the values of a range with a hyphen.

destination A comma-separated list of the destination IP addresses or networks. • Separate the values of a range with a hyphen.

service A comma-separated list of access rule services; the format of each service can be: • Source port or port range, destination port or port

range, and protocol, comma-separated • Destination port or port range and protocol, separated

by a comma • The string ANY: Any source port, destination port, and

protocol are permitted action The access rule action.

• Allow (default) • Deny

direction The access rule direction. • Inbound • Outbound • Both (default)

chain (Optional) The rule change to which the access rule is appended.



Parameter Description Rule chain names are set by the AddHost method (on page 115).

applied_interfaces A comma-separated list of the IP addresses of the interfaces to which the rule is applied. • IP address ranges are not permitted.

source_interfaces A comma-separated list of the IP addresses of the source interfaces for the rule. • IP address ranges are not permitted.


implied Specifies whether the rule was concluded from another setting in the device configuration (and not explicitly defined by the user). The default value is false. For example, a device whose default behavior is to block all packets when no access rules are defined has an implied rule of "src=any, dest=any, action=Deny".

orig_name (Optional) The rule’s original name or ID.

uid (Optional) A unique ID for this rule (used when comparing routing rules).

is_negated_source

Specifies whether the rule applies to all source addresses except those listed in the source parameter. The default value is false.


Specifies whether the rule applies to all destination addresses except those listed in the destination parameter. The default value is false.

is_negated_service

Specifies whether the rule applies to all services except those listed in the service parameter. The default value is false.


Some <access_rule> element attributes, including source_orig_text, destination_orig_text, and service_orig_text, are not included in the AddAccessRule method. You can add these attributes using the SetEntityValue method (see page 150). For a complete list of access rule attributes, see <access_rule> element (see page 33).

Example The following example uses this method. $inm->AddAccessRule($asset1, "1.1.1.0", "1.1.1.2", "0-65535/80/IP", "Allow", "Both");

iXML code generated The following iXML code is generated by the preceding example of the AddAccessRule method.



<access_rule source="1.1.1.0" destination="1.1.1.2" service="0-65535/80/IP" action="Allow" direction="Both" />

See also

› AddHost method (on page 115) › AddNatRule method (on page 126) › AddRoutingRule method (on page 133) › <access_rule> element (on page 33) › <asset> element (on page 40) › The Assets topic in the Skybox Reference Guide

AddAddressObject method

Syntax The syntax of the Perl AddAddressObject method is: AddAddressObject(asset, ip_ranges, name, domains)

Description The AddAddressObject method adds an address object to an asset.


Parameters The parameters of the AddAddressObject method are described in the following table.




Note: You must give a value to at least one of ip_ranges and domains.

name The name of the address object.

domains A semicolon-separated list of domain names. Note: You must give a value to at least one of domains and ip_ranges.

Example The following examples use this method. $inm->AddAddressObject("1.1.1.1", "net1", "") $inm->AddAddressObject("", "news", "www.a.co.il;www.b.co.il")

iXML code generated The following iXML code is generated by the preceding examples of the AddAddressObject method.



<address_object name="net1" ip_ranges="1.1.1.1" /> <address_object name="news" domains="www.a.co.il;www.b.co.il" />

See also

› <asset> element (on page 40) › <address_object> element (on page 36)

AddAddressGroupObject method

Syntax The syntax of the Perl AddAddressGroupObject method is: AddAddressGroupObject(asset, name, object_name)

Description The AddAddressGroupObject method adds an address group object to an asset.


Parameters The parameters of the AddAddressGroupObject method are described in the following table.



name The name of the address group.

object_name A semicolon-separated list of references to address objects contained in this group.

Example The following example uses this method. $inm->AddAddressGroupObject(asset, "address_group1", "net1;news");

iXML code generated The following iXML code is generated by the preceding example of the AddAddressGroupObject method. <address_group_object name="address_group1" > <address_object_ref name="net1" /> <address_object_ref name="news" /> </address_group_object>

See also

› <asset> element (on page 40) › <address_group_object> element (on page 35)

AddApplication method

Syntax The syntax of the Perl AddApplication method is:



AddApplication(name, dependency)

Description The AddApplication method adds an empty Business Asset Group to the model.

To add assets to the Business Asset Group, use the AddHostRef method. To add a network to the Business Asset Group (used when all assets in the network are part of the Business Asset Group), see Modeling a Business Asset Group that is based on a network (on page 161).

You can use multiple instances of this method per file.

Parameters The parameters of the AddApplication method are described in the following table.


name The name of the Business Asset Group.

dependency Specifies how the security of the Business Asset Group depends on the security of its member assets. For possible values, see Enum for the Business Asset Group dependency parameter (on page 155).

Example The following example uses this method. $inm->AddApplication("BusinessAssetGroup1" "Simple");

iXML code generated The following iXML code is generated by the preceding example of the AddApplication method. <application name="BusinessAssetGroup1" dependency="Simple" />

See also

› AddApplicationRef method (on page 101) › AddHostRef method (on page 118) › <application> element (on page 37) › <application_ref> element (on page 38) › <host_ref> element (on page 60)

AddApplicationBusinessImpactTypeRef method

Syntax The syntax of the Perl AddApplicationBusinessImpactTypeRef method is: AddApplicationBusinessImpactTypeRef(bizImpactType, name)

Description The AddApplicationBusinessImpactTypeRef method attaches a Business Impact to a Business Asset Group.



Parameters The parameters of the AddApplicationBusinessImpactTypeRef method are described in the following table.


bizImpactType A reference to the Business Impact instance returned by the AddBusinessImpactType method.

name The name of the Business Asset Group to which to attach the Business Impact.

Example The following example uses this method. $inm-> AddApplication("bag1"); $biz_impact_type = $inm-> AddBusinessImpactType("biz_impact_type1", "CIA", "", "2950"); $app_ref = $inm-> AddApplicationBusinessImpactTypeRef($biz_impact_type, "bag1");

iXML code generated The following iXML code is generated by the preceding example of the AddApplicationBusinessImpactTypeRef method. <business_impact_type effect="CIA" name=" biz_impact_type1" rate="2950"> <application_ref name="bag1" /> </business_impact_type>

See also

› AddBusinessImpactType method (on page 103) › <application_ref> element (on page 38)

AddApplicationRef method

Syntax The syntax of the Perl AddApplicationRef method is: AddApplicationRef(entity, name)

Description The AddApplicationRef method attaches an entity to a Business Asset Group.

Parameters The parameters of the AddApplicationRef method are described in the following table.


entity A reference to the entity instance returned by the AddApplication, AddDamage, or AddThreat methods.

name The name of the Business Asset Group to which to attach the entity.



Example The following example uses this method. # create Business Unit $bu = $inm->AddBusinessUnit("MyBU"); # add reference to Business Asset Group "MyBAG" in the new Business Unit. $inm->AddApplicationRef($bu, "MyBAG");

iXML code generated The following iXML code is generated by the preceding example of the AddApplicationRef method. <business_unit name="MyBU"> <application_ref name="MyBAG" /> </business_unit>

See also

› AddApplication method (on page 99) › AddDamage method (on page 109) › AddThreat method (on page 138) › <application_ref> element (on page 38)

AddApplicationRegulationRef method

Syntax The syntax of the Perl AddApplicationRegulationRef method is: AddApplicationRegulationRef(reg, name)

Description The AddApplicationRegulationRef method attaches a Regulation to a Business Asset Group.

Parameters The parameters of the AddApplicationRegulationRef method are described in the following table.


reg A reference to the Regulation instance returned by the AddRegulation method.

name The name of the Business Asset Group to which to attach the Regulation.

Example The following example uses this method. $inm-> AddApplication("bag1"); $reg = $inm->AddRegulation("regulation1", "CIA", "", "2950"); $app_ref = $inm-> AddApplicationRegulationRef($reg, "bag1");



iXML code generated The following iXML code is generated by the preceding example of the AddApplicationRegulationRef method. <regulation effect="CIA" name="regulation1" rate="2950"> <application_ref name="bag1" /> </regulation>

See also

› AddRegulation method (on page 132) › <application_ref> element (on page 38)

AddBusinessImpactType method

Syntax The syntax of the Perl AddBusinessImpactType method is: AddBusinessImpactType(name, effect, value, rate)

Description The AddBusinessImpactType method adds a Business Impact to the model. A Business Impact (for example, mission-critical damage or low-level financial damage) is a way of measuring loss from damages on a Business Asset Group.


Parameters The parameters of the AddBusinessImpactType method are described in the following table.



effect The effect of the Business Impact. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

value The qualitative value (Business Impact level) of the damage. For a list of possible values, see Enum for the damage level parameter (on page 156).

rate The quantitative value of the damage, in default currency units. The default value is 10000. Note: This parameter is applicable only if the value parameter is not set.

Example The following example uses this method. $inm->AddBusinessImpactType("biz_impact_type1", "CIA", "", "2950");



iXML code generated The following iXML code is generated by the preceding example of the AddBusinessImpactType method. <business_impact_type name="biz_impact_type1" effect="CIA" rate="2950" />

See also

› <business_impact_type> element (on page 46)

AddBusinessUnit method

Syntax The syntax of the Perl AddBusinessUnit method is: AddBusinessUnit(name)

Description The AddBusinessUnit method adds an empty Business Unit to the model. After you create the Business Unit, you add Business Asset Groups, nested Business Units, asset groups, and locations according to the hierarchy of your organization.


Parameters The parameters of the AddBusinessUnit method are described in the following table.


name The name of the Business Unit.

Example The following example uses this method. $inm->AddBusinessUnit("myNewBusinessUnit");

iXML code generated The following iXML code is generated by the preceding example of the AddBusinessUnit method. <business_unit name="myNewBusinessUnit" />

See also

› AddApplicationRef method (on page 101) › AddBusinessUnitRef method (on page 105) › AddGroupRef method (on page 115) › AddLocationRef method (on page 126) › <application_ref> element (on page 38) › <business_unit> element (on page 47) › <business_unit_ref> element (on page 48)



› <group_ref> element (on page 55) › <location_ref> element (on page 68)

AddBusinessUnitRef method

Syntax The syntax of the Perl AddBusinessUnitRef method is: AddBusinessUnitRef(businessUnit, name)

Description The AddBusinessUnitRef method attaches a Business Unit to another Business Unit.

Parameters The parameters of the AddBusinessUnitRef method are described in the following table.


businessUnit A reference to the Business Unit instance returned by the AddBusinessUnit method.

name The name of the Business Unit to which to attach the Business Unit.

Example The following example uses this method. $inm->AddBusinessUnitRef($businessunit1, "myBusinessUnit");

iXML code generated The following iXML code is generated by the preceding example of the AddBusinessUnitRef method. <business_unit_ref name="myBusinessUnit" />

See also

› AddBusinessUnit method (on page 104) › <business_unit_ref> element (on page 48)

AddComment method

Syntax The syntax of the Perl AddComment method is: AddComment(entity, comment)

Description The AddComment method adds a comment to a network, asset, interface, segment, service, routing rule, access rule, NAT rule, IPS access rule, IPS rule, vulnerability occurrence, or patch.

Use only one instance of this method per entity.



Parameters The parameters of the AddComment method are described in the following table.


entity A reference to the entity instance (network, asset, segment, interface, service, routing rule, access rule, NAT rule, IPS access rule, IPS rule, vulnerability occurrence, or patch) to which a comment is added.


Example The following example uses this method. $inm->AddComment($asset1, "My new comment");

iXML code generated The following iXML code is generated by the preceding example of the AddComment method. <asset comment="My new comment" />

See also

› <access_rule> element (on page 33) › <application> element (on page 37) › <business_unit> element (on page 47) › <host_group> element (on page 59) › <asset_category> element (on page 44) › <asset_group> element (on page 44) › <asset> element (on page 40) › <interface> element (on page 60) › <ips_access_rule> element (on page 63) › <ips_rule> element (on page 66) › <nat_rule> element (on page 68) › <network> element (on page 70) › <patch> element (on page 73) › <routing_rule> element (on page 74) › <segment> element (on page 77) › <service> element (on page 79) › <vpn_tunnel> element (on page 87) › <vulnerability_occurrence> element (on page 90)

AddConfigFile method

Syntax The syntax of the Perl AddConfigFile method is: AddConfigFile(asset, full_path_to_config_file)



Description The AddConfigFile method retrieves the original configuration file of an asset and stores it as part of the asset data.


Parameters The parameters of the AddConfigFile method are described in the following table.


asset The name of the asset instance returned by the AddHost method

full_path_to_config_file

The full path (including the file name) of the configuration file to add to the asset

Example The following example uses this method. $inm->AddConfigFile($asset1, "path1");

iXML code generated The following iXML code is generated by the preceding example of the AddConfigFile method. <config_file path="path1" />

See also

› AddHost method (on page 115) › <config_file> element (on page 49)

AddCustomVulnerability method

Syntax The syntax of the Perl AddCustomVulnerability method is: AddCustomVulnerability(parent, type, id, sbv_id, title, policy, scan_severity, scan_description)

Description The AddCustomVulnerability method adds a vulnerability occurrence of a custom Vulnerability Definition to an asset or to a service.

Using custom Vulnerability Definitions, you can manage the results output by proprietary plugins for vulnerability scanners. These results are included in vulnerability scanner reports and you can view them in Skybox as custom (generic) Vulnerability Definitions.

The custom Vulnerability Definitions are displayed on the services defined for them in iXML. An asset or a service can have vulnerability occurrences of multiple custom Vulnerability Definitions.

Parameters The parameters of the AddCustomVulnerability method are described in the following table.




parent A reference to the entity instance returned by the AddHost or AddService method.

type The name of the external vulnerability database with the Vulnerability Definition of the vulnerability occurrence. For a list of possible values, see Enum for the definition parameter (on page 157).

id The ID (an integer) of the Vulnerability Definition of the vulnerability occurrence in the external vulnerability database specified by type.

sbv_id The ID of the Vulnerability Definition of the vulnerability occurrence in the Skybox Vulnerability Dictionary. • For Qualys scan results: The ID of the (custom)

Vulnerability Definition of the vulnerability occurrence. • For all other scanners: Use the ID of a generic

Vulnerability Definition. For a list of valid values, see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158); any other value is mapped to ID 3326 (Uncataloged Generic Vulnerability) and Skybox does not use the Vulnerability Definition during attack simulation.

title (Optional) A title for the vulnerability occurrence. If provided, this value is used in Skybox Manager. Otherwise, the name associated with sbv_id is used (see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158)).

policy (Optional) The scan from which the vulnerability occurrence came. Use this parameter to relate all vulnerability occurrences that come from the same scan.

scan_severity (Optional) A severity for the Vulnerability Definition of the vulnerability occurrence. • Info • Low • Medium • High • Critical

If provided, this value overwrites the Vulnerability Dictionary severity.

scan_description (Optional) A description of the vulnerability occurrence. If provided, overwrites the Vulnerability Dictionary description.

Example The following example uses this method. $inm->AddCustomVulnerability($asset1, "NESSUS", "102006", "3504");



iXML code generated The following iXML code is generated by the preceding example of the AddCustomVulnerability method. <vulnerability_occurrence definition="NESSUS" id="102006" sbv_id="3504" />

See also

› <vulnerability_occurrence> element (on page 90) › AddHost method (on page 115) › AddService method (on page 135) › AddVulnerability method (on page 142) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 158) › The Vulnerability occurrences topic in the Skybox Reference Guide

AddDamage method

Syntax The syntax of the Perl AddDamage method is: AddDamage(name, effect, per_member, value, rate)

Description The AddDamage method adds a Business Impact to the model. (Business Impacts quantify damage caused to Business Asset Groups.)


Parameters The parameters of the AddDamage method are described in the following table.



effect The effect of the damage (Business Impact). Any combination of: • C (confidentiality) • I (integrity) • A (availability)

per_member Specifies whether compromise of any member asset or network entity causes the type of damage listed under effect. • true (default) (compromise if any member causes



rate The quantitative value of the damage, in default currency units. Note: This parameter is applicable only if the value parameter is not set.



Example The following example uses this method. $inm->AddDamage("damage1", "CIA", "true", "", "2950");

iXML code generated The following iXML code is generated by the preceding example of the AddDamage method. <damage name="damage1" effect="CIA" per_member="true" rate="2950" />

See also

› <damage> element (on page 50)

AddDependency method

Syntax The syntax of the Perl AddDependency method is: AddDependency(name, effect, any)

Description The AddDependency method adds a dependency rule to the model. A dependency rule defines how the security of a Business Asset Group depends on the security of its members, infrastructure servers, and other assets. For example, an availability loss of a DNS server might imply an availability loss for a Business Asset Group.


Note: A dependency rule also needs a <source> element (cause) and <destination> (effect).

Parameters The parameters of the AddDependency method are described in the following table.


name The name of the dependency rule.


any Specifies whether compromise of member assets or network entities causes the type of damage listed under effect. • true (default) (compromise if any member causes


Example The following example uses this method. $inm->AddDependency("myDependency", "CIA", "true");



iXML code generated The following iXML code is generated by the preceding example of the AddDependency method. <dependency name="myDependency" effect="CIA" any="true" />

See also

› AddDependencyDestination method (on page 111) › AddDependencySource method (on page 112) › <dependency> element (on page 51) › <destination> element (on page 52) › <source> element (on page 82)

AddDependencyDestination method

Syntax The syntax of the Perl AddDependencyDestination method is: AddDependencyDestination(dependency, effect)

Description The AddDependencyDestination method adds a dependency rule destination to the model that describes the effect of possible damage (for example, an availability loss on a payment system).


Parameters The parameters of the AddDependencyDestination method are described in the following table.


dependency A reference to the dependency rule instance created by the AddDependency method.


Example The following example uses this method. $inm->AddDependencyDestination($myDependency, "CIA");

iXML code generated The following iXML code is generated by the preceding example of the AddDependencyDestination method. <destination effect="CIA" />

See also

› AddDependency method (on page 110)



› AddDependencySource method (on page 112) › <destination> element (on page 52)

AddDependencySource method

Syntax The syntax of the Perl AddDependencySource method is: AddDependencySource(dependency, effect)

Description The AddDependencySource method adds a dependency rule source to the model that describes the cause of possible damage (for example, an integrity or availability loss on the web servers in your system).


Parameters The parameters of the AddDependencySource method are described in the following table.


dependency A reference to the dependency rule instance created by the AddDependency method.


Example The following example uses this method. $inm->AddDependencySource($myDependency, "CIA");

iXML code generated The following iXML code is generated by the preceding example of the AddDependencySource method. <source effect="CIA" />

See also

› AddDependency method (on page 110) › AddDependencyDestination method (on page 111) › <source> element (on page 82)

AddFirewallApplication method

Syntax The syntax of the Perl AddFirewallApplication method is: AddFirewallApplication(firewall, name, standard_ports)



Description The AddFirewallApplication method adds a firewall application to a firewall.

You can use multiple instances of this method per firewall.

Parameters The parameters of the AddFirewallApplication method are described in the following table.


firewall A reference to the firewall instance returned by the AddHost method.

name The name of the firewall application.

standard_ports

Example The following example uses this method. $inm->AddFirewallApplication($swFirewall, "app", "80");

iXML code generated The following iXML code is generated by the preceding example of the AddFirewallApplication method. <firewall_application name="app" standard_ports="80"/>

See also

› AddHost method (on page 115) › <asset> element (on page 40) › <firewall_application> element (on page 53)

AddFirewallUser method

Syntax The syntax of the Perl AddFirewallUser method is: AddFirewallUser(firewall, name)

Description The AddFirewallUser method adds a firewall user to a firewall.


Parameters The parameters of the AddFirewallUser method are described in the following table.



name The name of the firewall user.



Example The following example uses this method. $inm->AddFirewallUser($swFirewall, "user");

iXML code generated The following iXML code is generated by the preceding example of the AddFirewallUser method. <firewall_user name="user"/>

See also

› AddHost method (on page 115) › <asset> element (on page 40) › <firewall_user> element (on page 54)

AddFirewallUserGroup method

Syntax The syntax of the Perl AddFirewallUserGroup method is: AddFirewallUserGroup(firewall, name, object_name)

Description The AddFirewallUserGroup method adds a firewall user group to a firewall.


Parameters The parameters of the AddFirewallUserGroup method are described in the following table.



name The name of the firewall user group.

object_name The name of a user to add to the firewall group.

Example The following example uses this method. $inm->AddFirewallUserGroup($swFirewall, "group", "user1;user2;user3");

iXML code generated The following iXML code is generated by the preceding example of the AddFirewallUserGroup method. <firewall_user_group name="group"> <firewall_user_ref name="user1"/> <firewall_user_ref name="user2"/> <firewall_user_ref name="user3"/> </firewall_user_group>



See also

› AddHost method (on page 115) › <asset> element (on page 40) › <firewall_user_group> element (on page 54)

AddGroupRef method

Syntax The syntax of the Perl AddGroupRef method is: AddGroupRef(businessUnit, name)

Description The AddGroupRef method attaches a Business Unit to an asset group.

Parameters The parameters of the AddGroupRef method are described in the following table.


businessUnit A reference to the Business Unit instance returned by the AddBusinessUnit method.

name The name of the asset group to which to attach the Business Unit.

Example The following example uses this method. $inm->AddGroupRef($businessunit1, "myGroup");

iXML code generated The following iXML code is generated by the preceding example of the AddGroupRef method. <group_ref name="myGroup" />

See also

› AddHostGroup method (on page 117) › <group_ref> element (on page 55)

AddHost method

Syntax The syntax of the Perl AddHost method is: AddHost(assetname, ip_forwarding, os, platform, inbound_chains, outbound_chains, type, dynamic_routing, do_not_outdate, layer2)

Description The AddHost method adds an asset to the model.




Parameters The parameters of the AddHost method are described in the following table.


assetname The name of the asset. Optionally, append a colon and the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID


os Operating system vendor, name, and version. • For information about permitted values, see the note

following the table. platform (Optional) Platform vendor, name, and, if applicable,

version. • For information about permitted values, see the note

following the table. inbound_chains A comma-separated list of the names of inbound rule

chains to use for access rules. Note: This parameter is applicable only if type is set to Firewall.

outbound_chains A comma-separated list of the names of outbound rule chains to use for access rules. Note: This parameter is applicable only if type is set to Firewall.


dynamic_routing Specifies whether dynamic routing is enabled. The default value is false. Note: This parameter is applicable only if type is set to Router.

do_not_outdate Specifies whether the asset is protected against aging. The default value is false. Assets that are not marked as protected against aging are checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, assets imported using iXML are not updated on a regular basis so should not be outdated. In this case, set this flag to true.

layer2 Specifies whether the asset is an L2 gateway. Note: An L2 gateway must have at least one L2 network interface.



Note: Values for the os and platform parameters must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

Some <asset> element attributes are not included in the AddHost method. You can add these attributes using the SetEntityValue method (on page 150). For a complete list of asset attributes, see <asset> element (on page 40).

Example The following example uses this method. $inm->AddHost("gonzo.il.skyboxsecurity.com", "true", "SunOS 8.2");

iXML code generated The following iXML code is generated by the preceding example of the AddHost method. <asset assetname="gonzo.il.skyboxsecurity.com" ip_forwarding="true" os="SunOS 8.2" />

See also

› <asset> element (on page 40) › Banners (on page 80) › The Assets topic in the Skybox Reference Guide

AddHostGroup method

Syntax The syntax of the Perl AddHostGroup method is: AddHostGroup(name)

Description The AddHostGroup method adds an asset group to the model.


Parameters The parameters of the AddHostGroup method are described in the following table.



Example The following example uses this method. $inm->AddHostGroup("grp1");

iXML code generated The following iXML code is generated by the preceding example of the AddHostGroup method. <host_group name="grp1" />



See also

› AddHostRef method (on page 118) › <host_group> element (on page 59) › <asset_category> element (on page 44) › <asset_group> element (on page 44) › <host_ref> element (on page 60) › The Asset groups topic in the Skybox Reference Guide

AddHostRef method

Syntax The syntax of the Perl AddHostRef method is: AddHostRef(entity, ip)

Description The AddHostRef method references an asset.

Parameters The parameters of the AddHostRef method are described in the following table.


entity A reference to the entity returned by the AddApplication, AddDamage, or AddThreat methods.


Example The following example uses this method. $inm->AddHostRef($asset1, "192.170.1.64");

iXML code generated The following iXML code is generated by the preceding example of the AddHostRef method. <host_ref ip="192.170.1.64" />

See also

› AddApplication method (on page 99) › AddDamage method (on page 109) › AddThreat method (on page 138) › <host_ref> element (on page 60)

AddInterface method

Syntax The syntax of the Perl AddInterface method is:



AddInterface(asset, ip_address, ip_mask, mac_address, name, type, add_directly_connected_route, network, is_primary, layer_2, vrouter, zone, locked)

Description The AddInterface method adds an asset’s network interface to the model.

At least one instance of this method must appear per asset.

Parameters The parameters of the AddInterface method are described in the following table.



ip_address The IP address of the asset interface.

ip_mask The netmask of the asset interface. The default value is 255.255.255.0.

mac_address The MAC address of the asset interface. Note: This parameter is applicable only if type is set to Ethernet.

name The name of the interface.

type The interface type. For a list of possible values, see Enum for the network interface type parameter (on page 157). The default value is Ethernet.

add_directly_connected_route

Specifies whether a routing rule to the network to which the interface is connected can be added implicitly. The default value is false. If set to true, this method adds an additional routing rule (between the interface and its connected network) to the asset.

network The name of the network to which the interface is connected. Note: If this parameter is omitted, the interface is not attached to any network.

is_primary Specifies whether this is the primary interface for the network. The default value is false.

layer_2 Specifies whether this is an L2 interface. The default value is false.

vrouter (Used when working with virtual routers) The name of the virtual router to which the interface belongs.

zone The zone to which the interface belongs.

locked Specifies whether to lock the interface to the specified network. The default value is false.



Note: In Skybox Manager, you can define multiple virtual interfaces with the same IP address for the same device; in iXML only 1 virtual interface can have the same IP address as the physical interface. By using VPN-type interfaces rather than virtual interfaces, you can define multiple interfaces with the same IP address.

Some <interface> element attributes are not included in the AddInterface method. You can add these attributes using the SetEntityValue method (see page 150). For a complete list of interface attributes, see <interface> element (on page 60).

Example The following example uses this method. $inm->AddInterface($asset1, "192.168.90.200", "255.255.255.0", "FF:34:23:33:44:11", "myNewInterface", "Ethernet", "", "myNetwork");

iXML code generated The following iXML code is generated by the preceding example of the AddInterface method. <interface ip_address="192.168.90.200" ip_mask="255.255.255.0" mac_address="FF:34:23:33:44:11" name="myNewInterface" type="Ethernet" network="myNetwork" />

See also

› AddHost method (on page 115) › <interface> element (on page 60) › The Network interfaces topic in the Skybox Reference Guide

AddIPRangeRef method

Syntax The syntax of the Perl AddIPRangeRef method is: AddIPRangeRef(entity, ip_range)

Description The AddIPRangeRef method references an IP address range.

You can use multiple instances of this method per Business Asset Group.

Parameters The parameters of the AddIPRangeRef method are described in the following table.


entity A reference to the Business Asset Group returned by the AddApplication method.

ip_range The start IP address and end IP address of the range.



Example The following example uses this method. $inm->AddIPRangeRef($BAG1, "192.168.80.0-192.168.80.255");

iXML code generated The following iXML code is generated by the preceding example of the AddIPRangeRef method. <ip_range_ref ip="192.168.80.0-192.168.80.255" />

See also

› AddApplication method (on page 99) › <ip_range_ref> element (on page 63)

AddIpsAccessRule method

Syntax The syntax of the Perl AddIpsAccessRule method is: AddIpsAccessRule(asset, ips_rule_group_name, source, destination, service, direction, chain, applied_interfaces, source_interfaces, disabled, implied, source_orig_text, destination_orig_text, service_orig_text, orig_text, comment)

Description The AddIpsAccessRule method adds an IPS access rule to an asset. Every packet that matches the scope of the rule is inspected using the rules in the referenced IPS rule group (protection domain). For information about IPS dvices, see the IPS support in Skybox topic in the Skybox Vulnerability Control User Guide.

Use at least one instance of this method for each IPS rule group.

Parameters The parameters of the AddIpsAccessRule method are described in the following table.



ips_rule_group_name

The name of the associated IPS rule group. Each IPS rule group represents a protection domain in the IPS device.



service The access rule service; the format of each service can be: • Source port, destination port, and protocol, comma-

separated



Parameter Description • Destination port and protocol, separated by a comma • The string ANY: Any source port, destination port,

and protocol are permitted direction The access rule direction.

• Inbound • Outbound • Both (default)

chain (Optional) The name of the rule chain. Rule chain names are set by the AddHost method (on page 115).

applied_interfaces A comma-separated list of the IP addresses of the interfaces to which the rule is applied. • IP address ranges are not permitted.

source_interfaces A comma-separated list of the IP addresses of the source interfaces for the rule. • IP address ranges are not permitted.


implied Specifies whether the rule is implied. The default value is false.





orig_text The rule specified in the configuration file.


Example The following example uses this method. $inm-> AddIpsAccessRule($asset1, "DNS", "any", "any", "any", "", "IPS");

iXML code generated The following iXML code is generated by the preceding example of the AddIpsAccessRule method. <ips_access_rule ips_rule_group_ref="DNS" source="any" destination="any" service="any" chain="IPS" />

See also

› <asset> element (on page 40) › <ips_rule_group> element (on page 65) › <ips_access_rule> element (on page 63) › AddIpsRuleGroup method (on page 124) › The Assets topic in the Skybox Reference Guide



AddIpsRule method

Syntax The syntax of the Perl AddIpsRule method is: AddIpsRule(ips_group, disabled, action, title, comment, protocol, fp_level, fp_original, fn_level, fn_original, severity, severity_original, user_defined, vendor_rule_id, vulnerabilities)

Description The AddIpsRule method adds an IPS rule to an IPS rule group.

You can use multiple instances of this method per IPS rule group.

Parameters The parameters of the AddIpsRule method are described in the following table.


ips_group A reference to the IPS rule group instance returned by the AddIpsRuleGroup method.


action The IPS rule action. • detect • prevent (default)

title A title for the IPS rule.


protocol • http • unknown (default)

fp_level The estimated probability that this rule generates a false positive.

fp_original The probability of a false positive specified in the configuration file.

fn_level The estimated probability that this rule generates a false negative.

fn_original The probability of a false negative specified in the configuration file.

severity • info • low • medium (default) • high • critical

severity_original The severity specified in the configuration file.

user_defined Specifies whether the rule is user-defined. • true: A custom rule is created even if

vendor_rule_id is in the Skybox Vulnerability Dictionary

• false (default) vendor_rule_id The name of the vendor vulnerability database followed

by a “/”, followed by the ID (in the database) of the Vulnerability Definition of the vulnerability occurrence to



Parameter Description which this rule applies. For a list of possible vendor vulnerability databases, see Enum for the definition parameter (on page 157). You must give a value to either vendor_rule_id or vulnerabilities.

vulnerabilities The string SBV/ followed by the ID (in the Vulnerability Dictionary) of the Vulnerability Definition of the vulnerability occurrence to which this rule applies. You must give a value to either vulnerabilities or vendor_rule_id.

Example The following example uses this method. $inm->AddIpsRule($ipsRuleGroup, "true", "Detect", "first custom rule", "this is a comment", "http", "0", "low in device", "0.5", "low in device", "High", "very high", "true", "ISS_IPS/my rule def", "SBV/123,ISS/11111");

iXML code generated The following iXML code is generated by the preceding example of the AddIpsRule method. <ips_rule disabled="true" action="Detect" title="first custom rule" comment="this is a comment" protocol="http" FP_level="0" FP_original="low in device" FN_level="0.5" FN_original="low in device" severity="High" severity_original="very high" user_defined="true" vendor_rule_id="ISS_IPS/my rule def" vulnerabilities="SBV/123,ISS/11111" />

See also

› <ips_rule> element (on page 66) › <ips_rule_group> element (on page 65) › The Assets topic in the Skybox Reference Guide

AddIpsRuleGroup method

Syntax The syntax of the Perl AddIpsRuleGroup method is: AddIpsRuleGroup(asset, ips_rule_group_name)

Description The AddIpsRuleGroup method adds an IPS rule group to an asset.


Parameters The parameters of the AddIpsRuleGroup method are described in the following table.





ips_rule_group_name

The name of the IPS rule group. This name must match the name in the ips_rule_group_name parameter of the corresponding IPS access rule (added using the AddIpsAccessRule method (see page 121)).

Example The following example uses this method. $inm->AddIpsRuleGroup($asset1, "DNS");

iXML code generated The following iXML code is generated by the preceding example of the AddIpsRuleGroup method. <ips_rule_group name="DNS" />

See also

› <asset> element (on page 40) › <ips_rule_group> element (on page 65) › <ips_access_rule> element (on page 63) › AddIpsAccessRule method (on page 121) › The Assets topic in the Skybox Reference Guide

AddLocation method

Syntax The syntax of the Perl AddLocation method is: AddLocation(name)

Description The AddLocation method adds a location to the model.


Parameters The parameters of the AddLocation method are described in the following table.


name The name of the location.

Example The following example uses this method. $inm->AddLocation("myNewLocation");



iXML code generated The following iXML code is generated by the preceding example of the AddLocation method. <location name="myNewLocation" />

See also

› <location> element (on page 67)

AddLocationRef method

Syntax The syntax of the Perl AddLocationRef method is: AddLocationRef(entity, name)

Description The AddLocationRef method references a location.

Parameters The parameters of the AddLocationRef method are described in the following table.


entity A reference to the entity returned (for example, by the AddLocation method (see page 125)).

name The name of the referenced location.

Example The following example uses this method. $inm->AddLocationRef($location1, "myLocation");

iXML code generated The following iXML code is generated by the preceding example of the AddLocationRef method. <location_ref name="myLocation" />

See also

› AddLocation method (on page 125) › <location_ref> element (on page 68)

AddNatRule method

Syntax The syntax of the Perl AddNatRule method is: AddNatRule(asset, source, destination, service, translated_source, translated_destination, translated_service, direction, chain, applied_interfaces, source_interfaces, disabled, implied)



Description The AddNatRule method adds a NAT rule to an asset.


Parameters The parameters of the AddNatRule method are described in the following table.





service The NAT rule service; the format of each service can be: • Source port, destination port, and protocol, comma-

separated • Destination port and protocol, separated by a

comma • The string ANY: Any source port, destination port,

and protocol are permitted translated_source (Optional) The translated source IP address.

translated_destination

(Optional) The translated destination IP address.

translated_service (Optional) The translated service.

direction The NAT rule direction. • Inbound • Outbound • Both (default)

chain The name of the chain to which the rule belongs. Rule chain names are set by the AddHost method (see page 115).

applied_interfaces (Optional) A comma-separated list of the IP addresses of the interfaces to which the rule is applied. • IP address ranges are not permitted.

source_interfaces (Optional) A comma-separated list of the IP addresses of the source interfaces for the rule. • IP address ranges are not permitted.


implied Specifies whether the rule is implied. The default value is false.

Example The following example uses this method.



$inm->AddNatRule($asset1, "172.20.0.0/16", "10.0.0.0/8", "21/TCP", "10.1.1.1-10.1.1.10");

iXML code generated The following iXML code is generated by the preceding example of the AddNatRule method. <nat_rule source="172.20.0.0/16" destination="10.0.0.0/8" service="21/TCP" translated_source="10.1.1.1-10.1.1.10" />

See also

› AddHost method (on page 115) › AddAccessRule method (on page 96) › AddRoutingRule method (on page 133) › <nat_rule> element (on page 68) › <asset> element (on page 40) › The Assets topic in the Skybox Reference Guide

AddNetwork method

Syntax The syntax of the Perl AddNetwork method is: AddNetwork(name, number, mask, type, do_not_outdate)

Description The AddNetwork method adds a network to the model.


Parameters The parameters of the AddNetwork method are described in the following table.


name The name of the network.



type The network type. For a list of possible values, see Enum for the network type parameter (on page 157). The default value is Regular.

do_not_outdate Specifies whether the network is protected against aging. • true • false

Entities in a network that is not marked as protected against aging are checked by Model – Outdated Removal tasks. These tasks mark entities that were not updated for a specific period as Down and later delete them from the model. Important: Usually, networks imported using iXML are



Parameter Description not updated on a regular basis so should not be outdated.

Example The following example uses this method. $inm->AddNetwork("192.168.80", "192.168.80.0", "255.255.255.0" "Regular" "true");

iXML code generated The following iXML code is generated by the preceding example of the AddNetwork method. <network name="192.168.80" number="192.168.80.0" mask="255.255.255.0" type="Regular" do_not_outdate="true" />

See also

› <network> element (on page 70) › The Networks topic in the Skybox Reference Guide

AddNetworkGroup method

Syntax The syntax of the Perl AddNetworkGroup method is: AddNetworkGroup(name)

Description The AddNetworkGroup method adds an asset group for a network to the model.


Parameters The parameters of the AddNetworkGroup method are described in the following table.


name The name of the network group.

grouptype Set to "NetworkGroup".


See also

› AddHostRef method (on page 118) › <host_group> element (on page 59) › <host_ref> element (on page 60) › The Network groups topic in the Skybox Reference Guide



AddNetworkRef method

Syntax The syntax of the Perl AddNetworkRef method is: AddNetworkRef(entity, ip)

Description The AddNetworkRef method references a network.

Parameters The parameters of the AddNetworkRef method are described in the following table.


entity A reference to the entity returned by the AddThreat, AddDamage, or AddLocation methods.

ip The IP address of the referenced network.

Example The following example uses this method. $inm->AddNetworkRef($location1, "192.168.80.0/24");

iXML code generated The following iXML code is generated by the preceding example of the AddNetworkRef method. <network_ref ip="192.168.80.0/24" />

See also

› AddApplication method (on page 99) › AddDamage method (on page 109) › AddThreat method (on page 138) › <network_ref> element (on page 72)

AddOwner method

Syntax The syntax of the Perl AddOwner method is: AddOwner(entity, owner)

Description The AddOwner method adds an owner to an entity.

Use only one instance of this method per entity.

Parameters The parameters of the AddOwner method are described in the following table.




entity The name of the entity to which to add an owner.

owner The name of the owner.

Example The following example uses this method. $inm->AddOwner("NewBusinessUnit", "CSO");

See also

› <application> element (on page 37) › <business_unit> element (on page 47) › <host_group> element (on page 59) › <asset_category> element (on page 44) › <asset_group> element (on page 44) › <asset> element (on page 40) › <network> element (on page 70)

AddPatch method

Syntax The syntax of the Perl AddPatch method is: AddPatch(asset, code, product)

Description The AddPatch method adds patch information to an asset.


Parameters The parameters of the AddPatch method are described in the following table.



code The patch code (patch ID).

product The product banner (of the product to which the patch is applied). • For information about permitted values, see the note

following the table.

Note: The product parameter must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

Example The following example uses this method. $inm->AddPatch($asset1, "KB3163912", "Microsoft Windows 10");



iXML code generated The following iXML code is generated by the preceding example of the AddPatch method. <patch code="KB3163912" product="Microsoft Windows 10" />

See also

› <patch> element (on page 73) › AddHost method (on page 115) › The Assets topic in the Skybox Reference Guide

AddRegulation method

Syntax The syntax of the Perl AddRegulation method is: AddRegulation(name, effect, value, rate)

Description The AddRegulation method adds a Regulation to the model. A Regulation is a way of measuring loss on a Business Asset Group. Regulations involve damage to Business Asset Groups as a compromise to a security regulation with which organizations must comply.


Parameters The parameters of the AddRegulation method are described in the following table.


name The name of the Regulation.

effect The effect of the Regulation. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

value The qualitative value of the damage. For a list of possible values, see Enum for the damage level parameter (on page 156).

rate The quantitative value of the damage, in default currency units. The default value is 10000. Note: This parameter is applicable only if the value parameter is not set.

Example The following example uses this method. $inm->AddRegulation("regulation1", "CIA", "", "2950");



iXML code generated The following iXML code is generated by the preceding example of the AddRegulation method. <regulation name="regulation1" effect="CIA" rate="2950" />

See also

› <regulation> element (on page 73)

AddRoutingRule method

Syntax The syntax of the Perl AddRoutingRule method is: AddRoutingRule(asset, destination, gateway, dynamic, vrouter, via_vrouter, via_global, null_route)

Description The AddRoutingRule method adds a routing rule to an asset.


Parameters The parameters of the AddRoutingRule method are described in the following table.



destination The name or IP address of the destination network.

gateway The gateway IP address.

dynamic Specifies whether the routing rule is dynamic. The default value is false.

vrouter The virtual router through which to route traffic.

via_vrouter Specifies whether traffic is directed through a specific virtual router.

via_global Specifies whether the traffic is directed through the global virtual router.

null_route Specifies whether the route is considered as a route to null (that is, packets arriving after a match is made are discarded).

Example The following example uses this method. $inm->AddRoutingRule($asset1, "1.1.1.0/24", "1.1.1.2");

iXML code generated The following iXML code is generated by the preceding example of the AddRoutingRule method.



<routing_rule destination="1.1.1.0/24" gateway="1.1.1.2" />

See also

› AddHost method (on page 115) › <asset> element (on page 40) › <routing_rule> element (on page 74) › <vrouter> element (on page 88) › The Assets topic in the Skybox Reference Guide › The Working with routing rules chapter in the Skybox Reference Guide

AddRuleOriginalText method

Syntax The syntax of the Perl AddRuleOriginalText method is: AddRuleOriginalText(rule, orig_text, source_orig_text, destination_orig_text, service_orig_text)

Description The AddRuleOriginalText method adds the original text to an access rule or NAT rule (the text of the rule properties specified in the configuration file).

Use only one instance of this method per rule.

Parameters The parameters of the AddRuleOriginalText method are described in the following table.


rule A reference to the rule returned by the AddAccessRule or AddNatRule method.

orig_text The rule specified in the configuration file.

source_orig_text (Optional) The source specified in the configuration file.


(Optional) The destination specified in the configuration file.

service_orig_text (Optional) The service specified in the configuration file.

Example The following example uses this method. $rule = $inm->AddRuleOriginalText($myAccessRule, "050801");

iXML code generated The following iXML code is generated by the preceding example of the AddRuleOriginalText method. <access_rule orig_text="050801" />

See also

› AddAccessRule method (on page 96)



› AddNatRule method (on page 126) › <access_rule> element (on page 33) › <nat_rule> element (on page 68)

AddSegment method

Syntax The syntax of the Perl AddSegment method is: AddSegment(network, name)

Description The AddSegment method adds a segment to the specified network.

You can use multiple instances of this method per network.

Parameters The parameters of the AddSegment method are described in the following table.


network A reference to the network returned by the AddNetwork method.

name The name of the segment to add to the specified network.

Example The following example uses this method. $inm->AddSegment($network1, "mySegment");

iXML code generated The following iXML code is generated by the preceding example of the AddSegment method. <segment name="mySegment" />

See also

› AddNetwork method (on page 128) › <segment> element (on page 77)

AddService method

Syntax The syntax of the Perl AddService method is: AddService(asset, banner, port, interfaces)

Description The AddService method adds a service to an asset.


Parameters The parameters of the AddService method are described in the following table.




asset The name of the asset instance returned by the AddHost method.

banner The service banner, which helps Skybox to select the service definition from the Skybox Vulnerability Dictionary to apply. • For information about permitted values, see the note

following the table. port The service port number and protocol.

interfaces (Optional) A semicolon-separated list of interfaces to which the service is bound (the applied interfaces). • Separate the values of a range with a hyphen.

Note: The banner parameter must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

Some <service> element attributes are not included in the AddService method. You can add these attributes using the SetEntityValue method (see page 150). For a complete list of service attributes, see <service> element (on page 79).

Note: You can set the scan time with the SetLastScanTime method (see page 152).

Example The following example uses this method. $inm->AddService($asset1, "Apache HTTP", "80/TCP" "192.168.80.123/24");

iXML code generated The following iXML code is generated by the preceding example of the AddService method. <service banner="Apache HTTP" port="80/TCP" interfaces="192.168.80.123/24" />

See also

› AddHost method (on page 115) › <service> element (on page 79) › Banners (on page 80) › The Services topic in the Skybox Reference Guide

AddServiceObject method

Syntax The syntax of the Perl AddServiceObject method is: AddServiceObject(fw_services, name)

Description The AddServiceObject method adds a service object to an asset.




Parameters The parameters of the AddServiceObject method are described in the following table.


fw_services A semicolon-separated list of firewall services; the format of each service can be: • Source port, destination port, and protocol, separated



port, and protocol are permitted name The name of the object.

Example The following example uses this method. $inm->AddServiceObject("0-65535/80/TCP", "srv1");

iXML code generated The following iXML code is generated by the preceding example of the AddServiceObject method. <service_object name="srv1" fw_services="0-65535/80/TCP" />

See also

› <access_rule> element (on page 33) › <asset> element (on page 40) › <service_object> element (on page 81)

AddServiceGroupObject method

Syntax The syntax of the Perl AddServiceGroupObject method is: AddServiceGroupObject(asset, name, object_name)

Description The AddServiceGroupObject method adds a service group object to an asset.


Parameters The parameters of the AddServiceGroupObject method are described in the following table.


asset The asset to which to add the service group object.

name The name of the service group.




object_name A semicolon-separated list of references to service objects contained in this group.

Example The following example uses this method. $inm->AddServiceGroupObject(asset, "service_group1", "srv1;srv2");

iXML code generated The following iXML code is generated by the preceding example of the AddServiceGroupObject method. <service_group_object name="service_group1" > <service_object_ref name="srv1" /> <service_object_ref name="srv2" /> </service_group_object>

See also

› <asset> element (on page 40) › <service_group_object> element (on page 80)

AddThreat method

Syntax The syntax of the Perl AddThreat method is: AddThreat(name, probability, skill, value)

Description The AddThreat method adds a threat to the model.


Parameters The parameters of the AddThreat method are described in the following table.


name The name of the threat.

probability The probability of the threat. For a list of possible values, see Enum for the threat probability parameter (on page 157).

skill The skill required to actualize the threat. • low • medium • high

value The value (damage level) of the threat. For a list of possible values, see Enum for the damage level parameter (on page 156).

Example The following example uses this method.



$inm->AddThreat("BadNews", "high", "low", "high");

iXML code generated The following iXML code is generated by the preceding example of the AddThreat method. <threat name="BadNews" probability="high" skill="low" value="high" />

See also

› AddThreatRef method (on page 139) › <threat> element (on page 85)

AddThreatRef method

Syntax The syntax of the Perl AddThreatRef method is: AddThreatRef(threat, name)

Description The AddThreatRef method references a threat.

Parameters The parameters of the AddThreatRef method are described in the following table.


threat A reference to the threat instance returned by the AddThreat method.

name The name of the referenced threat.

Example The following example uses this method. $inm->AddThreatRef($threat1, "BadNews");

iXML code generated The following iXML code is generated by the preceding example of the AddThreatRef method. <threat_ref name="BadNews" />

See also

› AddThreat method (on page 138) › <threat_ref> element (on page 86)

AddVpnTunnel method

Syntax The syntax of the Perl AddVpnTunnel method is: AddVpnTunnel(name, number, netmask, type, endpoint1, endpoint2, do_not_outdate, display_as_cloud)



Description The AddVpnTunnel method adds a secure VPN to the model.


Parameters The parameters of the AddVpnTunnel method are described in the following table.




netmask The netmask of the network.

type The network type. For a list of possible values, see Enum for the network type parameter (on page 157).

endpoint1 One endpoint of the VPN tunnel.

endpoint2 The other endpoint of the VPN tunnel.

do_not_outdate Specifies whether the VPN tunnel network is protected against aging. • true • false

In a network that is not marked as protected against aging, entities are checked to see how much time has passed since they were updated. Entities that were not updated for more than a specific period are deleted from the model. Important: Usually, networks imported using iXML are not updated on a regular basis so should not be outdated.

display_as_cloud Specifies whether to display the VPN tunnel as a cloud. • true • false

Example The following example uses this method. $inm->AddVpnTunnel("192.168.80", "192.168.80.0", "255.255.255.0" "Cloud" "10.10.10.1" "10.10.10.2" "true");

iXML code generated The following iXML code is generated by the preceding example of the AddVpnTunnel method. <vpn_tunnel name="192.168.80" number="192.168.80.0" mask="255.255.255.0" type="Cloud" endpoint1="10.10.10.1" endpoint2="10.10.10.2" do_not_outdate="true" />

See also

› AddVpnUnit method (on page 141) › <vpn_tunnel> element (on page 87)



› The Networks topic in the Skybox Reference Guide

AddVpnUnit method

Syntax The syntax of the Perl AddVpnUnit method is: AddVpnUnit(asset, name, my_domain, peer_domain, service, interface)

Description The AddVpnUnit method adds a VPN Unit to the model.


Parameters The parameters of the AddVpnUnit method are described in the following table.



name VPN Unit name.

my_domain The networks protected by this gateway. The default value is ANY.

peer_domain The networks protected by the endpoint gateway. Only packets with networks that match these domains can pass thought the VPN tunnel. Note: This field is named the encryption domain in Check Point terminology and the proxy in Cisco terminology The default value is ANY.

service The port number and protocol of the protected services. The default value is ANY.

interface The name of the network interface that connects the VPN Unit to the tunnel.

Example The following example uses this method. $inm->AddVpnUnit($asset1, "10.1.1.1_to_10.1.1.20", "10.1.1.1-10.1.1.20", "192.168.80.0/24", "80/TCP", "vpn_from_10.1.1.1_to_10.1.1.20");

iXML code generated The following iXML code is generated by the preceding example of the AddVpnUnit method. <vpn_unit name="10.1.1.1_to_10.1.1.20" my_domain="10.1.1.1-10.1.1.20" peer_domain="192.168.80.0/24" service="80/TCP" interface="vpn_from_10.1.1.1_to_10.1.1.20" />

See also

› AddHost method (on page 115) › AddVpnTunnel method (on page 139)



› <vpn_unit> element (on page 88) › The Networks topic in the Skybox Reference Guide

AddVrouter method

Syntax The syntax of the Perl AddVrouter method is: AddVrouter(asset, name)

Description The AddVrouter method adds a virtual router to an asset.


Parameters The parameters of the AddVrouter method are described in the following table.


asset The name of the asset instance returned by the AddHost method.

name The name of the virtual router.

Example The following example uses this method. $inm->AddVrouter($asset1, "vr1");

iXML code generated The following iXML code is generated by the preceding example of the AddVrouter method. <vrouter name="vr1" />

See also

› AddHost method (on page 115) › <vrouter> element (on page 88)

AddVulnerability method

Syntax The syntax of the Perl AddVulnerability method is: AddVulnerability(parent, type, id, policy)

Description The AddVulnerability method adds a vulnerability occurrence to an asset or to a service.

An asset or a service can have multiple vulnerability occurrences.



Parameters The parameters of the AddVulnerability method are described in the following table.


parent A reference to the entity instance returned by the AddHost or AddService method.

type The name of the vulnerability database of the Vulnerability Definition of the vulnerability occurrence. For a list of possible values, see Enum for the definition parameter (on page 157).

id The ID (an integer) of the Vulnerability Definition of the vulnerability occurrence in the database specified by type.

policy (Optional) The scan from which the vulnerability occurrence came. Use this parameter to relate all vulnerability occurrences that come from the same scan.

Example The following example uses this method. $inm->AddVulnerability($asset1, "CVE", "2018-9999");

iXML code generated The following iXML code is generated by the preceding example of the AddVulnerability method. <vulnerability_occurrence definition="CVE" id="2018-9999" />

See also

› AddCustomVulnerability method (on page 107) › AddHost method (on page 115) › AddService method (on page 135) › <vulnerability_occurrence> element (on page 90) › The Vulnerability occurrences topic in the Skybox Reference Guide

AssignInterfaceToNetwork method

Syntax The syntax of the Perl AssignInterfaceToNetwork method is: AssignInterfaceToNetwork(interface, name)

Description The AssignInterfaceToNetwork method connects a network interface (on an asset) to the specified network.

Use only one instance of this method per network interface.



Parameters The parameters of the AssignInterfaceToNetwork method are described in the following table.


interface A reference to the network interface instance returned by the AddInterface method.

name The name of the network to which to connect the network interface.

Example The following example uses this method. $inm->AssignInterfaceToNetwork($interface1, "myNetwork");

See also

› AddInterface method (on page 118) › AddNetwork method (on page 128) › AssignInterfaceToSegment method (on page 144) › The Network interfaces topic in the Skybox Reference Guide

AssignInterfaceToSegment method

Syntax The syntax of the Perl AssignInterfaceToSegment method is: AssignInterfaceToSegment(interface, name)

Description The AssignInterfaceToSegment method connects a network interface to a segment.

Use only one instance of this method per network interface.

Parameters The parameters of the AssignInterfaceToSegment method are described in the following table.


interface A reference to the network interface instance returned by the AddInterface method.

name The name of the segment to which to connect the network interface.

Example The following example uses this method. $inm->AssignInterfaceToSegment($interface1, "SegA");

See also

› AddInterface method (on page 118)



› AddSegment method (on page 135) › AssignInterfaceToNetwork method (on page 143) › The Network interfaces topic in the Skybox Reference Guide

IntegrationSecurityModel method

Description The IntegrationSecurityModel method places a line of non-XML code at the beginning of the iXML file (<?xml...) and then inserts the 1st line of XML code, which contains the <intermediate_model> element.

When you add or modify a model, you must call the IntegrationSecurityModel method before any other method.

Use only one instance of this method per file.

Syntax The syntax of the Perl IntegrationSecurityModel method is: Skybox::IntegrationSecurityModel(file_name)

Parameters The parameters of the IntegrationSecurityModel method are described in the following table.


file_name File name of output iXML document.

Example The following example uses this method. $inm = new Skybox::IntegrationSecurityModel(myNewModel);

iXML code generated The following iXML code is generated by the preceding example of the IntegrationSecurityModel method. <?xml version="1.0" encoding="UTF-8" ?> <intermediate_model xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

Note: The file_name parameter is not included in the iXML code.

See also

› <intermediate_model> element (on page 62)

Print method

Syntax The syntax of the Perl Print method is: Print

Description The Print method prints the current model to the screen (console window).



Parameters The Print method does not have any parameters.

Example The following example uses this method. $inm->Print;

iXML code generated The Print method does not generate any iXML code.

See also

› Write method (on page 154)

SetCloudDestinationAlternativeIPRanges method

Syntax The syntax of the Perl SetCloudDestinationAlternativeIPRanges method is: SetCloudDestinationAlternativeIPRanges(network, iprange)

Description The SetCloudDestinationAlternativeIPRanges method adds alternative (included) destination IP address ranges to a cloud.

Use only one instance of this method per cloud.

Parameters The parameters of the SetCloudDestinationAlternativeIPRanges method are described in the following table.


network A reference to the cloud network instance returned by AddNetwork method.

iprange A semicolon-separated list of the IP address ranges.

Example The following example uses this method. $inm->SetCloudDestinationAlternativeIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 128) › SetCloudDestinationExcludedIPRanges method (on page 147) › SetCloudSourceAlternativeIPRanges method (on page 147) › SetCloudSourceExcludedIPRanges method (on page 148) › <network> element (on page 70)



SetCloudDestinationExcludedIPRanges method

Syntax The syntax of the Perl SetCloudDestinationExcludedIPRanges method is: SetCloudDestinationExcludedIPRanges(network, iprange)

Description The SetCloudDestinationExcludedIPRanges method adds excluded destination IP address ranges to a cloud.


Parameters The parameters of the SetCloudDestinationExcludedIPRanges method are described in the following table.



iprange A semicolon-separated list of IP address ranges to exclude.

Example The following example uses this method. $inm->SetCloudDestinationExcludedIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 128) › SetCloudDestinationAlternativeIPRanges method (on page 146) › SetCloudSourceAlternativeIPRanges method (on page 147) › SetCloudSourceExcludedIPRanges method (on page 148) › <network> element (on page 70)

SetCloudSourceAlternativeIPRanges method

Syntax The syntax of the Perl SetCloudSourceAlternativeIPRanges method is: SetCloudSourceAlternativeIPRanges(network, iprange)

Description The SetCloudSourceAlternativeIPRanges method adds alternative (included) source IP address ranges to a cloud.


Parameters The parameters of the SetCloudSourceAlternativeIPRanges method are described in the following table.





iprange A semicolon-separated list of the IP address ranges.

Example The following example uses this method. $inm->SetCloudSourceAlternativeIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 128) › SetCloudDestinationAlternativeIPRanges method (on page 146) › SetCloudDestinationExcludedIPRanges method (on page 147) › SetCloudSourceExcludedIPRanges method (on page 148) › <network> element (on page 70)

SetCloudSourceExcludedIPRanges method

Syntax The syntax of the Perl SetCloudSourceExcludedIPRanges method is: SetCloudSourceExcludedIPRanges(network, iprange)

Description The SetCloudSourceExcludedIPRanges method adds excluded source IP address ranges to a cloud.


Parameters The parameters of the SetCloudSourceExcludedIPRanges method are described in the following table.



iprange A semicolon-separated list of IP address ranges to exclude.

Example The following example uses this method. $inm->SetCloudSourceExcludedIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 128) › SetCloudDestinationAlternativeIPRanges method (on page 146)



› SetCloudDestinationExcludedIPRanges method (on page 147) › SetCloudSourceAlternativeIPRanges method (on page 147) › <network> element (on page 70)

SetCreationTime method

Syntax The syntax of the Perl SetCreationTime method is: SetCreationTime(time)

Description The SetCreationTime method sets the model creation time.

Use only one instance of this method per file.

The method must appear immediately after the IntegrationSecurityModel method.

If you do not use this method, the following line of iXML code is generated automatically (every iXML file must contain either a <creation_time> element or a creation_time attribute in the <intermediate_model> element): <creation_time />

Parameters The parameters of the SetCreationTime method are described in the following table.


time The creation time of the model. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

Example The following example uses this method. $inm->SetCreationTime("Aug 1, 2018 8:30");

iXML code generated The following iXML code is generated by the preceding example of the SetCreationTime method. <creation_time time="Aug 1, 2018 08:30" />

See also

› <creation_time> element (on page 49) › <intermediate_model> element (on page 62) › IntegrationSecurityModel method (on page 145)



SetDiscoveryMethod method

Syntax The syntax of the Perl SetDiscoveryMethod method is: SetDiscoveryMethod(method)

Description The SetDiscoveryMethod method sets the discovery method used by the model.

Use only one instance of this method per file (because it affects the entire model).

Parameters The parameters of the SetDiscoveryMethod method are described in the following table.


method Discovery method used by the model for the data. For a list of possible values, see Enum for the discovery method parameter (on page 156).

Example The following example uses this method. $inm->SetDiscoveryMethod("NMAP");

iXML code generated The following iXML code is generated by the preceding example of the SetDiscoveryMethod method. <intermediate_model method="NMAP" />

See also

› <intermediate_model> element (on page 62)

SetEntityValue method

Syntax The syntax of the Perl SetEntityValue method is: SetEntityValue(entity, attribute, value)

Description The SetEntityValue method is a generic method that sets or changes an attribute of an entity.

Parameters The parameters of the SetEntityValue method are described in the following table.


entity A reference to the entity to which the attribute value is



Parameter Description added.

attribute The attribute to change or add to the entity.

value The value of the attribute.

Example The following example demonstrates setting the status of an asset to Down: my $asset = $inm->AddHost("Asset1"); $inm->SetEntityValue($asset, "status", "down");

iXML code generated The following iXML code is generated by the preceding example of the SetEntityValue method. <asset assetname="Asset1" status="down" />

SetHostUniqueTag method

Syntax The syntax of the Perl SetHostUniqueTag method is: SetHostUniqueTag(asset, tag)

Description The SetHostUniqueTag method assigns a tag to an asset. This is useful if the name or IP address of the asset might not be unique in the network.

Use this method if your organization has a unique ID for each asset (based on a proprietary database) and wants to use this ID as the key (instead of the name or IP address of the asset) when merging assets in the model.

Use only one instance of this method per asset.

Parameters The parameters of the SetHostUniqueTag method are described in the following table.



tag A (unique) tag to assign to the asset.

Example The following example uses this method. $inm->SetHostUniqueTag($asset1, "asset123");

See also

› AddHost method (on page 115) › <asset> element (on page 40)



SetLastScanTime method

Syntax The syntax of the Perl SetLastScanTime method is: SetLastScanTime(entity, last_scan_time)

Description The SetLastScanTime method sets the scan time for the specified entity.

Parameters The parameters of the SetLastScanTime method are described in the following table.


entity The name of the entity for which the specified scan time is applicable. The entity might be a network, asset, service, or vulnerability occurrence.

last_scan_time The scan time for the specified entity. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

Example The following example uses this method. $inm->SetLastScanTime("myAsset", "Aug 1, 2018 8:30");

iXML code generated The following iXML code is generated by the preceding example of the SetLastScanTime method. <asset assetname="myAsset" last_scan_time="Aug 1, 2018 08:30" />

See also

› <asset> element (on page 40) › <intermediate_model> element (on page 62) › <network> element (on page 70) › <service> element (on page 79) › <vulnerability_occurrence> element (on page 90)

SetRuleID method

Syntax The syntax of the Perl SetRuleID method is: SetRuleID(rule, id)

Description The SetRuleID method adds an ID to an access rule or NAT rule.




Parameters The parameters of the SetRuleID method are described in the following table.


rule The name of the access rule or NAT rule.

id The ID of the rule.

Example The following example uses this method. $inm->SetRuleID("myAccessRule", "abc789");

See also

› AddAccessRule method (on page 96) › AddNatRule method (on page 126) › <access_rule> element (on page 33) › <nat_rule> element (on page 68)

SetRuleVpnValue method

Syntax The syntax of the Perl SetRuleVpnValue method is: SetRuleVpnValue(access_rule, vpn)

Description After adding a VPN tunnel, there must be an access rule on each of its gateways that permits data to pass through the VPN tunnel; add the rule (using AddAccessRule or AddNatRule) and then set the VPN value (that is, the VPN unit over which the data travels).

The SetRuleVpnValue method adds a VPN value to an access rule or NAT rule.


Parameters The parameters of the SetRuleVpnValue method are described in the following table.


access_rule A reference to the access or NAT rule returned by the AddAccessRule or AddNatRule method.

vpn The name of the VPN unit over which the data passes.

Example The following example uses this method. $inm->SetRuleVpnValue($myNatRule, "myVPN");

See also

› AddAccessRule method (on page 96)



› AddNatRule method (on page 126) › <access_rule> element (on page 33) › <nat_rule> element (on page 68)

Write method

Syntax The syntax of the Perl Write method is: Write(file_name)

Description The Write method writes the current model to a file.

Parameters The parameters of the Write method are described in the following table.


file_name The name of the file to which to write the model.

Example The following example uses this method. $inm->Write("mySavedModel");

iXML code generated The Write method does not generate any iXML code.

See also

› Print method (on page 145)


Chapter 5

This chapter lists the possible values of enums that are used in attributes of iXML elements and parameters of Perl API methods.

In this chapter

Enum for the Business Asset Group dependency parameter .... 155

Enum for the damage level parameter .................................. 156

Enum for the discovery method parameter ............................ 156

Enum for the asset type parameter ...................................... 156

Enum for the network interface type parameter ..................... 157

Enum for the network type parameter .................................. 157

Enum for the threat probability parameter ............................ 157

Enum for the definition parameter ....................................... 157

Generic Vulnerability Definitions in the Vulnerability Dictionary 158

ENUM FOR THE BUSINESS ASSET GROUP DEPENDENCY PARAMETER

The Business Asset Group dependency parameter specifies how the security of the Business Asset Group depends on the security of its member assets.

The possible values for the parameter are described in the following table.

Value Description

Default Security loss of any type (confidentiality, integrity, or availability) on a member asset implies the same type of security loss on the Business Asset Group; integrity loss on a member asset also implies an availability and confidentiality security loss on the Business Asset Group.

Simple Security loss of any type (confidentiality, integrity, or availability) on a member asset implies the same type of security loss on the Business Asset Group.

None (Used if the Default and Simple options of describing dependency are not sufficient.) State explicitly how a security loss on each of the member assets affects the Business Asset Group.

Enums for iXML elements and Perl API methods



ENUM FOR THE DAMAGE LEVEL PARAMETER Possible values for the damage level parameter are:

• UNDEFINED • VERY_LOW • LOW • MEDIUM • HIGH • VERY_HIGH

ENUM FOR THE DISCOVERY METHOD PARAMETER Possible values for the discovery method parameter are:

• ALTIRIS • APPSCAN • BANNER • BIGFIX • CLOUND_MANAGER • CMDB • CONFIG • CONFIG_APPLICATION • CONFIG_PARTIAL • CYBERX • DIRECTORY • END_POINT_COLLECTOR • END_POINT_PROTECTOR • EPO • FOUNDSCAN • FW1_CPINFO • GENERIC_CMDB • HARRIS • HFNETCHK • HPOV • INTERMEDIATE • ISS • ISS_SITEPROTECTOR • LANDESK • MAXPATROL • NAC • NCIRCLE • NESSUS • NETWORK_SCANNER • NMAP • NMB • OUTPOST24 • PATCH_MANAGER • QUALYS • RAPID7 • RETINA • SATELLITE • SCCM • SNMPWALK • SNMPWALK_NIFS • SNMPWALK_RR • TIPPINGPOINT • TRACEROUTE • UNKNOWN • USER • VCLOUD_DIRECTORY • VIRTUALIZATION_MANAGER • VSHIELD • VSPHERE • VULNERABILITY_DETECTOR • VULNERABILITY_DETECTOR_RPM • VULNERABILITY_SCANNER • WSUS

ENUM FOR THE ASSET TYPE PARAMETER Possible values for the asset type parameter are:

• Host • Server • Firewall • Router • Workstation • Printer • LoadBalancer • Proxy • NetworkDevice • WirelessDevice • IPS • Switch • Mobile

Chapter 5 Enums for iXML elements and Perl API methods


ENUM FOR THE NETWORK INTERFACE TYPE PARAMETER Possible values for the network interface type parameter are:

• NAT • Ethernet • WLAN • TokenRing • PPP • Slip • Virtual • Other • Unknown • Loopback • Serial • LoadBalancer • Tunnel • Vpn • Peering

ENUM FOR THE NETWORK TYPE PARAMETER Possible values for the network type parameter are:

• Cloud • ConnectingCloud • Link • Regular • Tunnel • VpnTunnel • SerialLink • Peering

ENUM FOR THE THREAT PROBABILITY PARAMETER Possible values for the threat probability parameter are:

• VERY_LOW • LOW • MEDIUM • HIGH • VERY_HIGH

ENUM FOR THE DEFINITION PARAMETER Possible values for the definition parameter are:

• CVE • Nessus • ISS • SecurityFocus • Retina • Qualys • Microsoft • FoundScan • nCircle • Cisco PSIRT • SBV • Rapid7 • OVAL • Oracle • Adobe



GENERIC VULNERABILITY DEFINITIONS IN THE VULNERABILITY DICTIONARY

You can use generic Vulnerability Definitions to create custom Vulnerability Definitions based on the results of proprietary plugins for vulnerability scanners; each vulnerability occurrence reported by such a plugin must be mapped to a generic Vulnerability Definition in Skybox. Make a mapping between the proprietary plugin and the ID of the generic Vulnerability Definition in the Skybox Vulnerability Dictionary (SBV ID) according to the content of the plugin—each such plugin can be classified according to the type of Vulnerability Definition that it tests and then matched to a generic SBV ID according to the potential effects of that Vulnerability Definition.

The generic Vulnerability Definitions included in the Vulnerability Dictionary are listed in the following table.

SBV ID Title

3500 DoS on a Service Using Unidirectional Communication (Remote Attack)

3501 DoS on a Service Using Bidirectional Communication (Remote Attack)

3502 DoS on a Host Using Unidirectional Communication (Remote Attack)

3503 DoS on a Host Using Bidirectional Communication (Remote Attack)

3504 Gain Access to a Host with User Privileges (Remote Attack)

3505 Gain Access to a Host with Root Privileges (Remote Attack)

3507 Gain Access to a Host with Root Privileges (Local Attack)

3508 Gain User Privilege on a Service Capabilities (Remote Attack)

3509 Gain Root Privilege on a Service Capabilities (Remote Attack)

3510 Weak User Authentication (Remote Attack)

3511 Weak Root Authentication (Remote Attack)

3513 Weak Root Authentication (Local Attack)

3514 DoS on a Service (Local Attack)

3515 DoS on a Host (Local Attack)

3516 Gain User Write Permissions to a Filesystem (Remote Attack)

3517 Gain Root Write Permissions to a Filesystem (Remote Attack)

3519 Gain Root Write Permissions to a Filesystem (Local Attack)

3520 Gain User Write Permissions to a Database (Remote Attack)

3521 Gain Root Write Permissions to a Database (Remote Attack)

3523 Gain Root Write Permissions to a Database (Local Attack)

3524 User Defined Vulnerability – Gain Root Privilege on a Service Capabilities (Local Attack)

3525 User Defined Vulnerability – Service Detected on Host

3526 User Defined Vulnerability – Device Configuration Policy Violation

69049 User Defined Vulnerability – Malware Detected

Chapter 5 Enums for iXML elements and Perl API methods


SBV ID Title

69071 User Defined Vulnerability – SCADA Security Event

72218 User Defined Vulnerability – Generic Web Application Vulnerability

72219 User Defined Vulnerability – Information Exposure Through an Error Message (CWE-209)

72220 User Defined Vulnerability – Information Exposure Through Debug Information (CWE-215)

72221 User Defined Vulnerability – Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal') (CWE-22)

72222 User Defined Vulnerability – Plaintext Storage of a Password (CWE-256)

72223 User Defined Vulnerability – Improper Authorization (CWE-285)

72224 User Defined Vulnerability – Improper Authentication (CWE-287)

72225 User Defined Vulnerability – Missing Encryption of Sensitive Data (CWE-311)

72226 User Defined Vulnerability – Cleartext Storage of Sensitive Information (CWE-312)

72227 User Defined Vulnerability – Cleartext Transmission of Sensitive Information (CWE-319)

72228 User Defined Vulnerability – Missing Required Cryptographic Step (CWE-325)

72229 User Defined Vulnerability – Inadequate Encryption Strength (CWE-326)

72230 User Defined Vulnerability – Use of a Broken or Risky Cryptographic Algorithm (CWE-327)

72231 User Defined Vulnerability – Reversible One-Way Hash (CWE-328)

72232 User Defined Vulnerability – Insufficiently Protected Credentials (CWE-522)

72233 User Defined Vulnerability – Unprotected Transport of Credentials (CWE-523)

72234 User Defined Vulnerability – Information Exposure Through Directory Listing (CWE-548)

72235 User Defined Vulnerability – SQL Injection: Hibernate (CWE-564)

72236 User Defined Vulnerability – URL Redirection to Untrusted Site ('Open Redirect') (CWE-601)

72237 User Defined Vulnerability – Insufficient Session Expiration (CWE-613)

72238 User Defined Vulnerability – Unverified Password Change (CWE-620)

72239 User Defined Vulnerability – Authorization Bypass Through User-Controlled Key (CWE-639)

72240 User Defined Vulnerability – Weak Password Recovery Mechanism for Forgotten Password (CWE-640)

72241 User Defined Vulnerability – Improper Neutralization of Special



SBV ID Title Elements used in a Command ('Command Injection') (CWE-77)

72242 User Defined Vulnerability – Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection') (CWE-78)

72243 User Defined Vulnerability – Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting') (CWE-79)

72244 User Defined Vulnerability – Argument Injection or Modification (CWE-88)

72245 User Defined Vulnerability – Improper Neutralization of Special Elements used in a SQL Command ('SQL Injection') (CWE-89)

72246 User Defined Vulnerability – Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection') (CWE-90)

72247 User Defined Vulnerability – XML Injection ('Blind XPath Injection') (CWE-91)

72248 User Defined Vulnerability – Improper Control of Resource Identifiers ('Resource Injection') (CWE-99)

72252 User Defined Vulnerability – Sensitive Cookie in HTTPS Session Without 'Secure' Attribute (CWE-614)

72253 User Defined Vulnerability – Information Exposure Through Comments (CWE-615)

72254 User Defined Vulnerability – Improper Neutralization of Directives in Dynamically Evaluated Code ('Eval Injection') (CWE-95)

72255 User Defined Vulnerability – Improper Neutralization of Directives in Statically Saved Code ('Static Code Injection') (CWE-96)

72256 User Defined Vulnerability – Improper Neutralization of Server-Side Includes (SSI) Within a Web Page (CWE-97)

72257 User Defined Vulnerability – Improper Control of Filename for Include/Require Statement in PHP Program ('PHP Remote File Inclusion') (CWE-98)

72258 User Defined Vulnerability – Information Exposure (CWE-200)

72262 User Defined Vulnerability – Authorization Bypass Through User-Controlled SQL Primary Key (CWE-566)

72263 User Defined Vulnerability – Protection Mechanism Failure (CWE-693)

72264 User Defined Vulnerability – Predictability Problems (CWE-340)

72265 User Defined Vulnerability – Information Exposure Through Server Error Message (CWE-550)

72266 User Defined Vulnerability – Information Exposure Through Browser Caching (CWE-525)

72267 User Defined Vulnerability – Improper Neutralization of CRLF Sequences in HTTP Headers ('HTTP Response Splitting') (CWE-113)

72268 User Defined Vulnerability – Information Exposure Through Query Strings in GET Request (CWE-598)


Chapter 6

This chapter explains the workflow of different modeling scenarios.

In this chapter

Modeling load balancers ...................................................... 161

Modeling a Business Asset Group that is based on a network ... 161

MODELING LOAD BALANCERS The main iXML elements that model load balancers are similar to those used in routers and firewalls. However, because load balancers have complicated logic that can be hard to model, a helper Perl module is provided as part of the Skybox integration package. By working with the helper Perl module instead of directly with the IntermediateSecurityModel.pm Perl module, the script writer only needs to parse the device configuration file because:

› Most of the complicated data structures are kept with the helper module › The helper module does the modeling work

Note: If this load balancer has logic that is not found in other load balancers, additional scripting might be necessary.

The full path for the load balancer helper module is:

› <Skybox_Home>\intermediate\lib\parsers\loadBalancers\LbModeler.pm

MODELING A BUSINESS ASSET GROUP THAT IS BASED ON A NETWORK

You can create a script for a Business Asset Group based on a network:

› Use the <ip_range_ref> element (on page 63) or the AddIPRangeRef method (on page 120) to add a range of IP addresses or a network to a Business Asset Group.

› If the IP address range includes overlapping networks, use the Location Hint field of the selected offline file import task (see the Basic file import tasks topic or the Collector file import tasks topic in the Skybox Reference Guide) to define the part of the network whose assets are included in the Business Asset Group (or, for advanced file import tasks, add location hints to the lines of the definition file).

Note: Location hint information is not saved to the Skybox database.

On import, all assets that are part of the specified IP address range are included as part of the Business Asset Group.

Modeling scenarios



Note: Skybox does not automatically update the association between networks and Business Asset Groups. If you create a Business Asset Group that includes networks, run a Model – Integrity task every time that the network is updated. For information about these tasks, see the Model integrity tasks topic in the Skybox Reference Guide.

This part describes how to use Skybox SOAP APIs to retrieve data from Skybox and use its core methods remotely.

Part II: SOAP APIs


Chapter 7

Skybox is an open platform that enables integration with external systems, including SOC, ticketing systems, and organizational portals.

The Skybox SOAP APIs are based on web services and are applicable from most programming environments including Java, .NET, and Perl.

This chapter describes the SOAP APIs that you can use for the integration.

In this chapter

APIs and their methods ...................................................... 164

Connecting to the Skybox APIs ............................................ 165

APIS AND THEIR METHODS The main integration SOAP APIs are:

› SkyboxAdministrationService (on page 167): Retrieves administrative information and performs administrative actions (for example, launching a Skybox task or reading the Skybox event log)

For a list of the Administration web service methods, see Administration API methods (on page 167)

› SkyboxFirewallChangesService (on page 175): Retrieves changes to firewall access rules and objects, including functions for change reconciliation (that is, correlating the changes with change requests to verify that the changes are not arbitrary)

For a list of the Firewall Changes web service methods, see Firewall Changes API methods (on page 175)

› SkyboxNetworkService (on page 181): Provides access analysis and Access Policy analysis; you can check change requests for connectivity (Access Analyzer) and see whether they comply with the Access Policy

For a list of the Network web service methods, see Network API methods (on page 182)

› SkyboxTicketsService (on page 209): Retrieves and updates Skybox tickets

For a list of the Tickets web service methods, see Tickets API methods (on page 209)

› SkyboxVulnerabilitiesService (on page 249): Retrieves Vulnerability Definitions, vulnerability occurrences, and threat alert tickets from Skybox

Introduction to Skybox SOAP APIs

Chapter 7 Introduction to Skybox SOAP APIs


For a list of the Vulnerabilities web service methods, see Vulnerabilities API methods (on page 249)

Note: Each web service includes a testService method (see page 173) that you can use to confirm that the service is running.

Note: If there are multiple versions of a method, use the latest version.

URLs The URL of the Administration, Firewall Changes, Networks, and Vulnerabilities web services is https://<Skybox server>:8443/skybox/webservice/jaxws, where <Skybox server> is the name or IP address of the Skybox Server. You can view the WSDL files from this page.

The URL of the Tickets web service is https://<Skybox server>:8443/skybox/webservice/jaxws/tickets?wsdl

CONNECTING TO THE SKYBOX APIS The topics in this section explain how to connect to the Skybox APIs.

Authentication The Skybox web service APIs use HTTP basic access authentication (a standard authentication mechanism defined for the HTTP protocol). For information about authentication, see https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

Under this scheme, properties for user name and password are attached during the creation of the client’s web service port (interface). When a property is defined, it is transmitted by the HTTP infrastructure on each web service call via a special Authorization HTTP header.

For Skybox Manager (the Java Client), these properties are defined in https://docs.oracle.com/javase/8/docs/api/javax/xml/ws/BindingProvider.html

Code example (in the context of a Java web service client)

Note: This example assumes that appropriate stubs were generated from WSDL.

SkyboxVulnerabilities vulnerabilitiesWebServicePort = new SkyboxVulnerabilitiesService().getSkyboxVulnerabilitiesPort(); BindingProvider bp = (BindingProvider) vulnerabilitiesWebServicePort; bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "https://127.0.0.1:8443/skybox/webservice/jaxws/vulnerabilities"); bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "<user name>"); bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "<password>");

Sessions The Skybox web service APIs use HTTP session (a standard session mechanism implemented for the HTTP protocol). For information about HTTP session, see https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#HTTP_session

Under this scheme, all the technical issues of session IDs, cookies and URL rewriting are resolved by the underlying HTTP infrastructure.

To maintain a session, add the following line of code:

https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

https://docs.oracle.com/javase/8/docs/api/javax/xml/ws/BindingProvider.html

https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#HTTP_session



bp.getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

If the session flag is false, the server side logs in automatically on each call. If the session flag is true, the server side logs in on the initial call and subsequent calls are automatically attached to the existing session.

Note: Clients other than Java (including PHP, Perl, and Python) have similar capabilities. Contact Skybox Support for examples.

Using API calls on behalf of other users Admins can use the API on behalf of another user by adding a header to the API call. This enables automation scripts to authenticate via one user and password, but to work on tickets for another user without needing their password.

The header contains the name of the user on whose behalf to operate. After the caller is authorized with the regular authorization header and is identified as an administrator, the system is switched to the other user. The permissions of the other user are used and their name is logged under any changes made.

The format of the header is: <Header> <onBehalfOfOptions xmlns="http://skyboxsecurity.com"> <userName>ONBEHALFOF USERNAME</userName> </onBehalfOfOptions> </Header>

Debugging during development The following properties in <Skybox_Home>\server\conf\sb_common.properties enable Skybox to log the messages that are output by your API calls:

› (SOAP messages) jaxws_debug_message_enabled

› (REST messages) jaxrs_debug_message_enabled

The full requests and responses are captured in the Skybox Server debug log (<Skybox_Home>\server\log\debug\debug.log).

We recommend that you set these properties to true while developing with the API.



Chapter 8

This chapter describes the SkyboxAdministrationService API, which provides administrative services related to Skybox, including:

› Retrieving administrative information › Performing administrative actions (for example, launching a Skybox task or

reading the Skybox event log)

In this chapter

Administration API methods ................................................ 167

Using the Administration API ............................................... 174

ADMINISTRATION API METHODS The methods in the Administration web service are described in the following table.

Method Description

exportOptimizationAndCleanupCSVByTask (on page 168)

Runs a CSV – Optimization & Cleanup Export task and returns the full path name of the file output by the task.

findAllUsers (on page 168)

Returns a list of all users in the Skybox database.

findUserByName (on page 169)

Finds a user in the Skybox database by name and returns information about the user.

getCollectorsFileStoreSpace (on page 169)

Returns information about the available space on each file store of each Skybox Collector.

getCollectorsUptime (on page 169)

Returns information about the uptime of each Skybox Collector.

getCSVReport (on page 170)

Returns the specified CSV or ZIP file.

getEvents (on page 170)

Retrieves a list of events from Skybox.

getModelLockStatuses (on page 171)

Returns the lock statuses of all models in the Skybox database.

getRunningTaskNames (on page 172)

Returns an array of names of running tasks.

getRunningTasksInfo (on page 172)

Returns information about the Skybox tasks that are running.

Administration API



Method Description

getServerVersion (on page 172)

Returns the version of the Skybox Server.

launchTaskOrSequence (on page 173)

Launches a Skybox task.

listCSVReports (on page 173)

Lists the CSV reports that meet the criteria of the filter.

ping Pings the Skybox server.

testService (on page 173)

Tests communication with the web service. Note: This method is in every web service.

exportOptimizationAndCleanupCSVByTask method

Description The exportOptimizationAndCleanupCSVByTask method runs a CSV – Optimization & Cleanup Export task and returns the full path name of the file output by the task.

The method:

1 Copies all the parameters from the task specified by the method

2 Changes the scope of the task to that specified by the method

3 Runs the temporary task

4 Provides the full path name of the resultant CSV

Syntax csvfilepath = exportOptimizationAndCleanupCSVByTask (taskName, fwScope)

Parameters The parameters of the exportOptimizationAndCleanupCSVByTask method are described in the following table.

Parameter Type Comments

taskName String Mandatory The name of the CSV – Optimization & Cleanup Export task from which all the parameters (except the firewall scope) are copied.

fwScope FWScope The firewall scope on which to run the CSV – Optimization & Cleanup Export task.

Result The method returns the full path of the CSV file that was created by the task.

findAllUsers method

Description The findAllUsers method returns a list of all users in the Skybox database.

Chapter 8 Administration API


Syntax users = findAllUsers ()

Parameters The findAllUsers method has no parameters.

Result The method returns a list of User data structures (see page 319).

findUserByName method

Description The findUserByName method finds a user in the Skybox database by name and returns information about the user.

Syntax user = findUserByName (userName)

Parameters The parameters of the findUserByName method are described in the following table.


userName String The name of a user in the Skybox database

Result The method returns a User data structure (see page 319).

getCollectorsFileStoreSpace method

Description The getCollectorsFileStoreSpace method returns information about the available space on each file store of each Skybox Collector. A file store is a disk in Windows and a partition in Unix.

Syntax collectorFileStores = getCollectorsFileStoreSpace ()

Parameters The getCollectorsFileStoreSpace method has no parameters.

Result The method returns a list of CollectorFileStoreInfo data structures (on page 276).

getCollectorsUptime method

Description The getCollectorsUptime method returns information about the uptime of each Skybox Collector.



Syntax uptimeInfo = getCollectorsUptime ()

Parameters The getCollectorsUptime method has no parameters.

Result The method returns a list of CollectorUptimeInfo data structures (on page 277).

getCSVReport method

Description The getCSVReport method returns the specified CSV or ZIP file from the <Skybox_Home>\data\csv directory on the Skybox Server.

For security purposes, only Admins can retrieve reports. If a non-Admin user tries to use this method, the method fails.

Syntax file = getCSVReport (fileName)

Parameters The parameters of the getCSVReport method are described in the following table.


fileName String The name of the report to return.

Result The method returns the requested file as a csvContent data structure (on page 278).

Note: The output of this method is the content of the file after encoding in Base64. Decode the string to get the original file content.

getEvents method

Description The getEvents method enables integration of Skybox with external ticketing systems and Security Operation Center (SOC) systems, providing data to any external program that can parse and process Skybox event records.

The getEvents method retrieves events created by the Skybox Server.

› No filtering mechanisms are available; all stored events (starting at the requested sequence ID) are included in the results. However, if your organization uses only specific event types, you can store only events of those types. See Configuring Skybox to store events (on page 171).

You can filter results on the caller side.

› On the first call, the method returns the oldest events in the system. On subsequent calls, the caller can retrieve only events with later sequence IDs by providing the sequence ID of the last returned event.



Syntax events = getEvents (sequenceNumber)

Parameters The parameter of the getEvents method is described in the following table.


sequenceNumber Integer

Result The method returns a list of Event data structures (see page 281).

Configuring Skybox to store events By default, Skybox is configured to store all events in the event log for use with the events API. Each event type is controlled by a separate property in <Skybox_Home>\server\conf\sb_server.properties

If you know that your organization only works with specific event types, disable the other event types. Otherwise, do not disable any event types.

The following properties in sb_server.properties control the events that are stored:

› event_TICKET_CREATION_enabled

› event_TICKET_UPDATE_enabled

› event_TICKET_DELETE_enabled

› event_KPI_NOTIFICATION_enabled

› event_OPERATIONAL_enabled

› event_TASK_END_enabled

› event_APR_NOTIFICATION_enabled

There is another property, events_result_limit, that specifies the maximum number of events that can be returned by a call to getEvents. The default value (1000) is usually sufficient, but if there are many events in your organization, you can increase this.

getModelLockStatuses method

Description The getModelLockStatuses method returns the lock statuses of all models in the Skybox database: Live, Forensics, What If, and Core.

Note: Core is an internal database that contains operational and system information that is required by Skybox.

A model can be locked for reading, writing, and updating at any time.

Syntax getModelLockStatuses ()



Parameters The getModelLockStatuses method has no parameters.

Result The method returns an array of ModelLockStatus data structures (see page 300).

getRunningTaskNames method

Description The getRunningTaskNames method returns an array of names of running tasks. If no task is running, an empty array is returned.

Syntax getRunningTaskNames ()

Parameters The getRunningTaskNames method has no parameters.

Result The method returns an array (list) of String objects. If no tasks are running, the array is empty.

getRunningTasksInfo method

Description The getRunningTasksInfo method returns information about the Skybox tasks that are running.

Syntax tasksInfo = getRunningTasksInfo ()

Parameters The getRunningTasksInfo method has no parameters.

Result The method returns a list of TaskWSDL data structures (see page 316).

getServerVersion method

Description The getServerVersion method returns the version of the Skybox Server as found in <Skybox_Home>\server\conf\aboutserver.properties

Syntax getServerVersion ()

Parameters The getServerVersion method has no parameters.



Result The method returns the Skybox Server version.

launchTaskOrSequence method

Description The launchTaskOrSequence method launches a Skybox task.

Syntax launchTaskOrSequence (userName)

Parameters The parameter of the launchTaskOrSequence method is described in the following table.


name String The name of a predefined Skybox task or task sequence.

Result If the method is not successful, an exception is returned.

listCSVReports method

Description The listCSVReports method lists the CSV reports that meet the criteria of the filter.

Syntax reports = listCSVReports (reportFilter)

Parameters The parameter of the listCSVReports method is described in the following table.


reportFilter csvReportFilter (on page 278)

Result The method returns a list of csvReportInfo data structures (on page 278).

testService method

Description The testService method tests communication with the service.

Note: This method is in each web service.

Syntax result = testService (anyValue)



Parameters The parameter of the testService method is described in the following table.


anyValue Integer

Result The method returns the value that it was sent.

USING THE ADMINISTRATION API Use the following URL to view or access the Administration web service (<Skybox server> is the name or IP address of your Skybox Server):

› Endpoint address: https://<Skybox server>:8443/skybox/webservice/jaxws/administration

› WSDL: {http://skyboxsecurity.com}SkyboxAdministrationService

› Target namespace: http://skyboxsecurity.com


Chapter 9

This chapter describes the Firewall Changes API, which retrieves changes to firewall access rules and objects, including functions for change reconciliation.

The Firewall Changes API enables you to get a list of changes for firewalls over time. You can get a list of change records by firewall or firewall group and date ranges. For each change, you can get the details of the change (before and after). You can correlate the changes with change requests to verify that the changes were not made arbitrarily.

In this chapter

Firewall Changes API methods ............................................. 175

Using the Firewall Changes API ............................................ 180

FIREWALL CHANGES API METHODS The methods in the Firewall Changes web service are described in the following table.

Method Description

countFirewallChanges (on page 176)

Counts the number of change records that match the specified filter (date range, firewalls, change reconciliation status, or violation status).

findChangeReconciliationInfo (on page 176)

Returns change reconciliation information for the specified change record (including reconciliation fields, IDs of matched tickets, and matched change requests).

findFirewallChanges (on page 177)

Returns an array containing all the firewall change records that match the search criteria.

getAccessRulesHistory (on page 177)

Retrieves a list of changes to an access rule.

getFirewallChangeDetails (on page 178)

Returns all data related to the specified change record.

setChangeReconciliationInfo (on page 178)

Sets the change reconciliation information for the specified change record.


Tests communication with the service.

updateFirewallChangeComment (on page 179)

Adds a comment to the specified firewall change record.

Firewall Changes API



countFirewallChanges method

Description The countFirewallChanges method counts the number of change records that match the specified filter (date range, firewall, change reconciliation status, or violation status). The output is used for page calculations. The method works in conjunction with findFirewallChanges (see page 177), which returns the changes.

Syntax numChanges = countFirewallChanges (filter)

Parameters The parameter of the countFirewallChanges method is described in the following table.


filter FirewallChangesSearchFilter (see page 294)

The type of changes to search for.

Result The method returns an integer representing the number of firewall changes that match the search criteria.

findChangeReconciliationInfo method

Description The findChangeReconciliationInfo method returns change reconciliation information for the specified change record (including reconciliation fields, IDs of matched tickets, and matched change requests).

Syntax changeReconciliationDetails = findChangeReconciliationInfo (firewallChangeId)

Parameters The parameter of the findChangeReconciliationInfo method is described in the following table.


firewallChangeId Integer The change ID is taken from the results of findFirewallChanges (see page 177).

Result The method returns a FirewallChangeReconciliationDetails data structure (see page 293) for the specified change record.

Chapter 9 Firewall Changes API


findFirewallChanges method

Description The findFirewallChanges method returns an array containing all the firewall change records that match the search criteria.

We recommend that you use countFirewallChanges (on page 176) to count the number of firewall changes for display purposes and then run findFirewallChanges.

Syntax matchingChanges = findFirewallChanges (filter)

Parameters The parameter of the findFirewallChanges method is described in the following table.


filter FirewallChangesSearchFilter (see page 294)

The type of changes to search for.

Result The method returns an array of FirewallChange data structures (see page 291).

getAccessRulesHistory method

Description The getAccessRulesHistory method retrieves a list of changes to an access rule.

Run getAccessRulesV4 (on page 199) to get accessRuleGuid before running getAccessRulesHistory.

Syntax change_history = getAccessRulesHistory (accessRuleGuid, firewallElement, filter, subRange)

Parameters The parameters of the getAccessRulesHistory method are described in the following table.


accessRuleGuid String The ID of the access rule in the firewall ACL.

firewallElement FirewallElement (see page 294)

The firewall to which the access rule belongs.

filter ACLRuleHistoryFilter (see page 266)

The time frame for returning access rule history records.

subRange SubRange (see page 316)

The range of access rules to return from the list of access rules in the firewall that match the filter.



Result The method returns an array of FirewallChange data structures (see page 291).

getFirewallChangeDetails method

Description The getFirewallChangeDetails method returns all data related to the specified change record. Call this method after findFirewallChanges (see page 177), when you want to focus on the details of a change.

Syntax changeDetails = getFirewallChangeDetails (firewallChangeId)

Parameters The parameters of the getFirewallChangeDetails method are described in the following table.


firewallChangeId Integer The change ID is taken from the results of findFirewallChanges.

Result The method returns a FirewallChangeDetails data structure (see page 293).

setChangeReconciliationInfo method

Description The setChangeReconciliationInfo method sets the change reconciliation information for the specified change record (including IDs of matched tickets and IDs of matched change requests). The operation overwrites the list of connected ticket IDs and change request IDs with the lists in the ticketIds and accessRequestIds fields.

Syntax setChangeReconciliationInfo (firewallChangeId, status, comment, ticketIds, accessRequestIds)

Parameters The parameters of the setChangeReconciliationInfo method are described in the following table.


firewallChangeId Integer (Mandatory) The change ID is taken from the results of findFirewallChanges (see page 177).

status String The new status of the firewall change. Possible values: • PENDING • AUTHORIZED • UNAUTHORIZED • IGNORED

Chapter 9 Firewall Changes API



If null, the status is not changed.

comment String A string that is added to the comment of the firewall change record. Note: When a comment is added, it includes a timestamp and the user name.

ticketIds Array of Integer An array of ticket IDs to connect to the change record. Note: This list is used to attach tickets without specific change requests.

accessRequestIds Array of Integer A list of change requests IDs to connect to the change record. Note: For a specific change request, use this field only; do not add the ticket ID of the change request to the list of tickets IDs.

Result The method updates the change reconciliation information for the specified firewall change record.

updateFirewallChangeComment method

Description The updateFirewallChangeComment method adds a comment to the specified firewall change record. Use it after viewing changes (findFirewallChanges (see page 177)), if you want to enter any notes that you have on the change or to record the fact that you reviewed the change.

Syntax updateFirewallChangeComment (firewallChangeId, comment)

Parameters The parameters of the updateFirewallChangeComment method are described in the following table.


firewallChangeId Integer The change ID is taken from the results of findFirewallChanges.

comment String

Result The method adds a comment to the Comment field of the specified firewall change record.

Note: Comments in change records are cumulative, and each comment includes a timestamp and the user name.



USING THE FIREWALL CHANGES API Use the following URLs to view or access the Firewall Changes web service (<Skybox server> is the name or IP address of your Skybox Server):

› Endpoint address: https://<Skybox server>:8443/skybox/webservice/jaxws/firewallchanges

› WSDL: {http://skyboxsecurity.com}SkyboxFirewallChangesService


Important: If there are multiple versions of an API method available, always use the most recent method when writing SOAP requests.

Sample workflows for firewall change management

Workflow for viewing changes for a firewall Use the web services client application to view changes for a firewall:

1 Use findFirewallsByName (on page 194) (from the Network API) to retrieve the ID of the desired firewall.

2 Use countFirewallChanges (on page 176) to find the number of changes that match the specifications that you want.

This facilitates the display of the actual changes.

3 Use findFirewallChanges (on page 177) with the same parameters to display the change records.

4 Call getFirewallChangeDetails (on page 178) (with the desired change ID) for each change record that you select.

For access rule changes, you can see the before and after states of the rule.

For firewall object changes, you can see the before and after state of the object, and a list of the access rules in which the object is used.

5 (Optional) Use updateFirewallChangeComment (on page 179) to add a user comment to the Comments field of the change record. A timestamp and user name are included in the comment.

Workflow for change reconciliation This workflow is a continuation of the previous workflow. At this point, you have viewed the changes and focused on a specific change record. You want to check that this change was made according to a specific request and fulfills the requirements of that request.

1 Use findAccessRequests (on page 221) (from the Tickets API) to display all the change requests for the firewall created during the relevant period (typically 1 to 2 weeks before the change was implemented).

2 Select the change request (or requests) that best match the change.

3 Attach the selected change requests to the change record using setChangeReconciliationInfo (on page 178).


Chapter 10

This chapter describes the Network API, which provides access analysis and Access Policy analysis. Use the API in conjunction with the change assurance process.

The Network API enables you to utilize, from external applications, Skybox’s ability to analyze policy compliance and access.

The API supports the process of change assurance, starting with network change requests, usually submitted by users. These requests must be validated to make sure that they comply with your policy and then passed to firewall administrators for deployment.

In this chapter

Basic field types used in the API .......................................... 181

Network API methods ......................................................... 182

Using the Network API ........................................................ 206

BASIC FIELD TYPES USED IN THE API

IP addresses

› Address: Valid IP address › Address Range: <address1>-<address2> › Network Address: <address>/<n>

• n: Netmask number, 0-31

› Address Element: [<address> | <address range> | <network address>] › Addresses: <address element1>[, <address element2>[...]]

Ports and protocols

› The format for a port is: <port 1>[-<port 2>]/<protocol 1>,...,<protocol n>. › Protocol names and their port numbers include:

• ICMP: Message Type (0-255)

• IGMP: Message Type (0-255)

• TCP: Port (0-65535)

• UDP: Port (0-65535)

• RPC: Program (0-2^32-1)

› Ports: A comma-separated list of ports (for example: 53/UDP, 53/TCP)

Network API



Firewall list

› Firewall Element:

Note: A firewall element describes a firewall in Skybox with its identification details. It uniquely identifies a firewall.

• Firewall Name: <text>

• Firewall Path: <text>

• Firewall ID: <integer>

› Firewall List: Array of [zero | one | many] Firewall Elements

Zone list

› Zone: <text> › Zone List: Array of [zero | one | many] Zones

Network entities

Note: A network entity describes a network in Skybox with its identification details in Skybox. It uniquely identifies a network.

› Network entity ID: Integer › Network entity: <ID>, <network type>, <location>, <name>

• Network type: [NETWORK | CLOUD | VPN-PEER]

› Network entity list: Array of network entities

NETWORK API METHODS The methods in the Network web service are described in the following table.

Method Description

checkAccessV3 (on page 185)

Activates Skybox access analysis from another application. For any combination of source, destination, and port, you can discover whether there is a connection and the firewalls that permit or deny the connection. The method returns the 1st route describing the path between the source and destination.

checkAccessCompliance (on page 186)

Checks whether a change request (source-destination-port) complies with your Access Policy.

countAssetsByIps (on page 187)

Counts the number of assets that match any of the specified IP address ranges. The output is used for page calculations.

countAssetsByNames (on page 187)

Counts the number of assets that match any of the specified full or partial name strings. The output is used for page calculations.

countObjectAffectedAccessRules (on page 188)

Counts the number of access rules that use the specified firewall object. The output is used for page calculations.

Chapter 10 Network API


Method Description

createFirewallException (on page 188)

Creates an exception in Skybox.

createRulePolicyException (on page 189)

Creates a Rule exception in Skybox.

deleteFirewallException (on page 189)

Deletes an exception from Skybox.

deleteRulePolicyException (on page 190)

Deletes a Rule exception from Skybox.

doCheckRuleCompliance (on page 190)

Checks whether a change request (source-destination-port) complies with your Rule Policies.

findAccessRulesV2 (on page 191)

Searches for access rules using the same search parameters that are used in Skybox Manager.

findAssetsByIps (on page 191)

Returns an array containing all the assets that match any of the specified IP address ranges.

findAssetsByNames (on page 192)

Returns an array containing all the assets that match any of the specified full or partial name strings.

findFirewallElementFAFolderPath (on page 192)

Returns the Skybox Firewall Assurance folder paths of the specified firewalls.

findFirewallObjectByName (on page 193)

Returns detailed information about the specified object as it occurs in the selected firewall.

findFirewallObjectsIdentifications (on page 193)

Returns firewall objects in the specified firewall that match the search string.

findFirewalls (on page 193)

Returns a list of firewalls that contain an interface with the source IP address range and a different interface with the destination IP address range.

findFirewallsByLocation (on page 194)

Returns a list of the firewalls stored under the specified folder in the All Firewalls tree.

findFirewallsByName (on page 194)

Returns a list of firewalls whose name includes the specified string.

findFirewallsByObjectName (on page 195)

Returns a list of the firewalls (in the All Firewalls tree) that have access rules that use the specified object.

findNetworkElementZone (on page 195)

Returns the zones of the specified networks.

findNetworkEntitiesBySourceAndDestination (on page 196)

Returns all the source and destination network pairs in the model for a given source IP address range and destination IP address range.



Method Description

findNetworks (on page 196)

Finds networks (Skybox network entities) with IP address ranges intersecting the specified IP address range.

findNetworksForIPRange (on page 197)

Finds network elements (Skybox network entities) whose IP address ranges intersect the specified range.

findObjectAffectedAccessRulesV2 (on page 197)

Returns an array containing access rules that use the specified firewall object.

getAccessRule (on page 198)

Returns the access rule specified by the ID.

getAccessRuleAttributes (on page 198)

Returns the business attributes of the specified access rule.

getAccessRuleEntityFields (on page 199)

Returns the list of access rule business assets used in the model.

getAccessRulesV4 (on page 199)

Returns the access rules from the requested firewall according to the specified filters. The returned access rules include translated IP addresses for NAT rules.

getAccessRulesSections (on page 200)

Returns the firewall policy sections for the specified asset and chain.

getHostAttributes (on page 201)

Returns the business attributes of the specified firewall.

getHostCluster (on page 201)

Returns the name and ID of the cluster of the specified firewall, or null if the firewall is not part of a cluster.

getHostEntityFields (on page 201)

Returns the list of asset business assets used in the model.

getHostNetworkInterfaces (on page 202)

Returns a list of all the network interfaces for the specified firewall.

getNetInterfacesByAssetId (on page 202)

Returns detailed information about the network interfaces of the specified firewall.

getNetInterfacesByNetworkId (on page 202)

Returns detailed information about the network interfaces of the specified network.

getZoneFromFW (on page 203)

Finds the zone name of a network IP address according to the zone of the firewall interface that matches this IP address.

getZoneFromNetwork (on page 203)

Finds the zone name of a network in the model.

isBackwardRouteExist (on page 204)

Specifies whether a backward route exists between the given destination entity and the source entity (using reversed NAT rules).



Method Description

modifyFirewallException (on page 204)

Modifies an exception in Skybox.

modifyRulePolicyException (on page 205)

Modifies a Rule exception in Skybox.



updateAccessRuleAttributes (on page 205)

Updates the business attributes of access rules.

updateFwAccessRuleAttributes (on page 206)

Updates the business attributes of access rules of the specified firewall.

updateHostAttributes (on page 206)

Updates the business attributes for an asset.

checkAccessV3 method

Description The checkAccessV3 method activates Skybox’s access analysis from another application. For any combination of source, destination, and port, you can discover whether there is connection and the firewalls that permit or deny the connection.

› In a network context, access is analyzed holistically, listing all gateways (firewalls and other devices).

› In a per-firewall context, access is analyzed between 2 network interfaces of the specified firewall

The method returns the 1st route describing the path between the source and destination.

Syntax result = checkAccessV3 (query, routeOutputType)

Parameters The parameters of the checkAccessV3 method are described in the following table.


query AccessQueryElementV3 (on page 261)

routeOutputType Integer Possible values: • 0: Return the route in HTML format • 1: Return the route in XML format



Result The method returns a CheckAccessResult data structure (see page 275) that includes a list of accessible IP addresses (source, destination, ports, and authentication), a list of inaccessible IP addresses, and the 1st route describing the path between the source and the destination.

checkAccessCompliance method

Description The checkAccessCompliance method checks whether a change request (source-destination-port) complies with your Access Policy.

Example

› The source is an IP address in a partner zone. › The destination is an IP address in the DMZ. › The requested port is 80/TCP.

Partner to DMZ on port 80/TCP is permitted according to the Access Policy, but a different Access Check in the Access Policy states that if the requested port is 23/TCP, so the access is in violation of the Access Policy.

How to use the method 1 The source and destination of the request are translated into zones.

2 Skybox checks whether the traffic from the source zone to the destination zone via the specified port is permitted.

› In a network context:

• sourceZone = getZoneFromNetwork (sourceAddress) (see page 203)

• destinationZone = getZoneFromNetwork (destinationAddress) (see page 203)

• checkAccessCompliance (sourceAddress, sourceZone, destinationAddress, destinationZone, ports)

› In a firewall context:

• fw = findFirewalls () (see page 193)

• sourceZone = getZoneFromFW (fw, sourceAddress) (see page 203)

• destinationZone = getZoneFromFW (fw, destinationAddress) (see page 203)

• checkAccessCompliance (sourceAddress, sourceZone, destinationAddress, destinationZone, ports)

Syntax result = checkAccessCompliance (request)

Parameters The parameter of the checkAccessCompliance method is described in the following table.




request CheckAccessComplianceRequest (see page 275)

Result The method returns a CheckAccessComplianceResponse data structure (see page 275) that includes the compliance status of the request and a list of violations.

countAssetsByIps method

Description The countAssetsByIps method counts the number of assets that match any of the specified IP address ranges. The output is used for page calculations. The method works in conjunction with findAssetsByIps (see page 191), which returns the assets.

Syntax numAssets = countAssetsByIps (IPFilter)

Parameters The parameter of the countAssetsByIps method is described in the following table.


IPFilter List of IPRangeElement (see page 300)

Search the assets in the model to see if they match any of the IP address ranges in the filter. All interfaces of each asset are searched for a match, not just the primary address.

Result The method returns an integer representing the number of assets that match the IP address filter.

countAssetsByNames method

Description The countAssetsByNames method counts the number of assets that match any of the specified full or partial name strings. The output is used for page calculations. The method works in conjunction with findAssetsByNames (see page 192), which returns the assets.

Syntax numAssets = countAssetsByNames (NameFilter)

Parameters The parameter of the countAssetsByNames method is described in the following table.




NameFilter List of strings The strings can be full or partial names. Use the characters ? and * for standard pattern matching.

Result The method returns an integer representing the number of assets that match the name filter.

countObjectAffectedAccessRules method

Description The countObjectAffectedAccessRules method counts the number of access rules in the specified rule chains of the firewall that use the specified firewall object. The output is used for page calculations.

The method works in conjunction with findObjectAffectedAccessRulesV2 (on page 197), which returns the access rules.

Syntax numObjects = countObjectAffectedAccessRules (hostId, objectName, chainFilterMode, chainNames)

Parameters The parameters of the countObjectAffectedAccessRules method are described in the following table.


hostId Integer

objectName String

chainFilterMode Integer Limits the rule chains searched for affected access rules. Possible values: • 0: Search all chains • 1: Search only primary chain • 2: Search by chain name

chainNames String A list of chain names in which to search for the object. Relevant only if chainFilterMode=2.

Result The method returns an integer representing the number of access rules in the firewall that use the object.

createFirewallException method

Description The createFirewallException method takes the information for an exception on a firewall and returns the exception with an ID.



Syntax exception = createFirewallException (firewallException)

Parameters The parameters of the createFirewallException method are described in the following table.


firewallException FirewallException (see page 294)

The ID field in the exception data is ignored.

Result The method returns an exception (see page 294).

createRulePolicyException method

Description The createRulePolicyException method takes the information for a Rule exception and returns the Rule exception with an ID.

Syntax exception = createRulePolicyException (policyException)

Parameters The parameter of the createRulePolicyException method is described in the following table.


policyException RulePolicyException (see page 313)

The ID field in the exception data is ignored.

Result The method returns a Rule exception (see page 313).

deleteFirewallException method

Description The deleteFirewallException method deletes an exception from Skybox.

Syntax deleteFirewallException (firewallException)

Parameters The parameter of the deleteFirewallException method is described in the following table.





Result The method deletes the specified exception in Skybox.

deleteRulePolicyException method

Description The deleteRulePolicyException method deletes a Rule exception from Skybox.

Syntax deleteRulePolicyException (policyException)

Parameters The parameter of the deleteRulePolicyException method is described in the following table.



Result The method deletes the specified Rule exception from Skybox.

doCheckRuleCompliance method

Description The doCheckRuleCompliance method checks whether a change request (source-destination-port) complies with your organization Rule Policies.

How to use the method Skybox checks whether the traffic from the source to the destination via the specified port is permitted according to the specified Rule Policy (or all Rule Policies, if none is specified).

Syntax result = doCheckRuleCompliance (req)

Parameters The parameter of the doCheckRuleCompliance method is described in the following table.


req CheckRuleComplianceRequest (see page 276)

Result The method returns a CheckRuleComplianceResponse data structure (see page 276) that includes the compliance status of the request and a list of violations.



findAccessRulesV2 method

Description The findAccessRulesV2 method searches for access rules using the search parameters that are used in Skybox Manager.

Syntax list = findAccessRulesV2 (filter)

Parameters The parameter of the findAccessRulesV2 method is described in the following table.


filter AccessRuleSearchFilter (see page 264)

Result The method returns an array of AccessRuleElementV4 (on page 263).

findAssetsByIps method

Description The findAssetsByIps method returns an array containing all the assets that match any of the specified IP address ranges.

We recommend that you use countAssetsByIps (see page 187) to count the number of assets for display purposes and then run findAssetsByIps.

Syntax Assets = findAssetsByIps (IPFilter, subRange)

Parameters The parameters of the findAssetsByIps method are described in the following table.


IPFilter List of IPRangeElement (see page 300)

Search for assets in the model that match any of the IP address ranges in the filter. All interfaces of each asset are searched for a match, not just the primary address.


The range of assets to return from the list of assets that match the filter criteria.

Result The method returns an array of assets (see page 269) sorted by ID.



findAssetsByNames method

Description The findAssetsByNames method returns an array containing all the assets that match any of the specified full or partial name strings.

We recommend that you use countAssetsByNames (see page 187) to count the number of assets for display purposes and then run findAssetsByNames.

Syntax Assets = findAssetsByNames (NameFilter, subRange)

Parameters The parameters of the findAssetsByNames method are described in the following table.


NameFilter List of strings The strings can be full or partial names. Use the characters ? and * for standard pattern matching.


The range of assets to return from the list of assets that match the filter criteria.

Result The method returns an array of assets (see page 269) sorted by ID.

findFirewallElementFAFolderPath method

Description The findFirewallElementFAFolderPath method finds the Firewall Access folder paths for the specified firewalls.

Syntax list = findFirewallElementFAFolderPath (firewallElements)

Parameters The parameters of the findFirewallElementFAFolderPath method are described in the following table.


firewallElements FirewallElement (see page 294)

Result The method returns a FindFirewallElementsFAFolderPathResult data structure (see page 289) that includes a list of firewalls and a matching list of Firewall Access folder paths.



findFirewallObjectByName method

Description The findFirewallObjectByName method returns detailed information about the specified object as it occurs in this firewall.

Syntax objectDetails= findFirewallObjectByName (hostId, objectName)

Parameters The parameters of the findFirewallObjectByName method are described in the following table.


hostId Integer

objectName String

Result The method returns detailed information about the specified object.

findFirewallObjectsIdentifications method

Description The findFirewallObjectsIdentifications method returns firewall objects in the specified firewall that match the search string. This is similar to the object finder in Change Manager.

Syntax firewallObjects = findFirewallObjectsIdentifications (hostId, objectNameFilter)

Parameters The parameters of the findFirewallObjectsIdentifications method are described in the following table.


hostId Integer The ID of the firewall

objectNameFilter String The search string

Result The method returns an array of FirewallObjectIdentification data structures (see page 295).

findFirewalls method

Description The findFirewalls method finds firewalls that are probably relevant for a request (and filters between a source and a destination).



The method looks for firewalls in the All Firewalls tree that contain an interface with the source IP address range and a different interface with the destination IP address range.

Syntax list = findFirewalls (sourceIpRange, destinationIpRange)

Parameters The parameters of the findFirewalls method are described in the following table.


sourceIpRange Address element

destinationIpRange

Address Element

Result The method returns a list of firewalls (see page 294).

findFirewallsByLocation method

Description The findFirewallsByLocation method returns a list of the firewalls stored under the specified folder in the Firewall Assurance tree.

Syntax list = findFirewallsByLocation (locationName)

Parameters The parameters of the findFirewallsByLocation method are described in the following table.


locationName String The name of a firewall folder in the Firewall Assurance tree. Null signifies the root folder.

Result The method returns a list of firewalls.

findFirewallsByName method

Description The findFirewallsByName method returns a list of firewalls in the All Firewalls tree whose name includes the specified string.

Syntax list = findFirewallsByName (firewallName)

Parameters The parameters of the findFirewallsByName method are described in the following table.




firewallName String If the search string is empty, all firewalls are returned.

Result The method returns a list of firewalls.

findFirewallsByObjectName method

Description The findFirewallsByObjectName method checks whether access rules of the firewalls in the All Firewalls tree use the specified object. The method returns a list of the firewalls that have access rules that use the object. If the object name provided uses wildcards, the search can match multiple objects.

You can use the results of this method as input for the following methods:

› countObjectAffectedAccessRules (see page 188) › findObjectAffectedAccessRulesV2 (on page 197)

Syntax list = findFirewallsByObjectName (objectName)

Parameters The parameters of the findFirewallsByObjectName method are described in the following table.


objectName String The name of the object. If the search string is empty, all firewalls are returned. Note: The object name can include * as a wildcard. The search is not case-sensitive.

Result The method returns a FirewallFindByObjectResult data structure (see page 295) that includes a list of firewalls and a list of objects for each firewall found.

findNetworkElementZone method

Description The findNetworkElementZone method finds the zones for the specified networks.

You can use the results of this method as input for checkAccessCompliance (see page 186).

Syntax list = findNetworkElementZone (networkElements)



Parameters The parameter of the findNetworkElementZone method is described in the following table.


networkElements NetworkElement (see page 305)

Result The method returns a FindNetworkElementsZoneResult data structure (see page 289) that includes a list of networks and a matching list of network zones.

findNetworkEntitiesBySourceAndDestination method

Description The findNetworkEntitiesBySourceAndDestination method returns all the source and destination network pairs in the model for a given source IP address range and destination IP address range.

Syntax pairs = findNetworkEntitiesBySourceAndDestination (sourceIpRangeElem, destinationIpRangeElem, checkBackwardRoute)

Parameters The parameters of the findNetworkEntitiesBySourceAndDestination method are described in the following table.


sourceIpRangeElem

IPRangeElement (see page 300)

The IP address range to check for the source.

destinationIpRangeElem

IPRangeElement (see page 300)

The IP address range to check for the destination.

checkBackwardRoute

Boolean Specifies, when searching for network pairs, whether to also check for backward routing. (By default, only forward routing is checked.)

Result The method returns a FindNetworkEntitiesResult data structure (see page 290).

findNetworks method

Description The findNetworks method finds network elements (Skybox network entities) (see page 305) whose IP address ranges intersect the specified range.

Use this method for unique identification of networks. Calling this method is a prerequisite for calling checkAccessV3 (see page 185) and checkAccessCompliance (see page 186) when working with a network model (not individual firewalls).



Syntax list = findNetworks (ipRange)

Parameters The parameter of the findNetworks method is described in the following table.


ipRange Address Element

Result The method returns a list of NetworkElement data structures (see page 305) that match the specified IP address range.

findNetworksForIPRange method

Description The findNetworksForIPRange method finds network elements (Skybox network entities) (see page 305) whose IP address ranges intersect the specified range.

Use this method for unique identification of networks. Calling this method is a prerequisite for calling checkAccessV3 (see page 185) and checkAccessCompliance (see page 186) when working with a network model (not individual firewalls).

Syntax list = findNetworksForIPRange (ipRange)

Parameters The parameters of the findNetworksForIPRange method are described in the following table.


ipRange Address Element

Result The method returns a list of IPAndNetworkPair data structures (see page 300) that match the specified IP address range.

findObjectAffectedAccessRulesV2 method

Description The findObjectAffectedAccessRulesV2 method returns an array containing all or a subset of the access rules in the specified rule chains that use the specified firewall object.

We recommend that you use countObjectAffectedAccessRules (see page 188) to count the number of access rules for display purposes and then run findObjectAffectedAccessRulesV2.

Syntax matchingObjects = findObjectAffectedAccessRulesV2 (hostId, objectName, subRange, chainFilterMode, chainNames)



Parameters The parameters of the findObjectAffectedAccessRulesV2 method are described in the following table.


hostId Integer

objectName String


The range of access rules to return from the list of access rules in the firewall that are affected by the object.



Result The method returns a findObjectAffectedAccessRulesResultV2 data structure (on page 289) that contains access rules and a return status.

getAccessRule method

Description The getAccessRule method returns an access rule.

Syntax rule = getAccessRule (accessRuleId)

Parameters The parameter of the getAccessRule method is described in the following table.


accessRuleId Integer The rule ID of the access rule.

Result The method returns an AccessRuleElementV4 data structure (on page 263) and a return status (see page 312).

getAccessRuleAttributes method

Description The getAccessRuleAttributes method returns a list of the business attributes of the access rule.



Syntax ruleAttributes = getAccessRuleAttributes (Id)

Parameters The parameter of the getAccessRuleAttributes method is described in the following table.


Id Integer Access rule ID

Result The method returns a ruleAttributes data structure (see page 312) that contains the list of business attributes for the specified access rule.

getAccessRuleEntityFields method

Description The getAccessRuleEntityFields method returns the list of attributes for access rules, as defined in Tools > Server Options > Options > Business Attributes > Access Rules.

Syntax getAccessRuleEntityFields ()

Parameters The getAccessRuleEntityFields method has no parameters.

Result The method returns a list of EntityField data structures (see page 281). Ignore the following in each EntityField:

› id: Always 0

› value: Always null

getAccessRulesV4 method

Description The getAccessRulesV4 method retrieves a list of the access rules that lie within the given range of access rules for the requested firewall.

Use this method:

› To export firewall access rules from Skybox › In conjunction with checkAccessV3 (on page 185), to show the rules that

permitted or denied the access › In conjunction with getAccessRulesHistory (see page 177), to show the

history of an access rule

Syntax list = getAccessRulesV4 (fw, range, chainName)



Parameters The parameters of the getAccessRulesV4 method are described in the following table.


fw Firewall element The firewall from which to retrieve access rules. Use findFirewalls (on page 193) to get this firewall.

range Range element The range of rule numbers to return (according to the order of the rules in the rule chain). Null returns all rules in the chain.

chainName String The rule chain from which to retrieve the rules. • Null and a range: Retrieve rules

from the default chain • Null and null range: Retrieve all

access rules across the firewall

Result The method returns a list of AccessRuleElementV4 (on page 263) data structures.

getAccessRulesSections method

Description The getAccessRulesSections method returns the firewall policy sections for the specified asset and chain.

Syntax accessRulesSections= getAccessRulesSections (hostId, chain)

Parameters The parameters of the getAccessRulesSections method are described in the following table.


hostId Integer The ID of the firewall

chain Integer The ID of the rule chain

Result The method returns the following information about the firewall policy sections for the specified asset and chain: ID of the last access rule in the section, section name, and ID of the first access rule in the section. For example: <endID>100</endID> <section>section 5</section> <startID>50</startID>



getHostAttributes method

Description The getHostAttributes method returns a list of the business attributes of the specified firewall.

Syntax hostAttributes = getHostAttributes (Id)

Parameters The parameter of the getHostAttributes method is described in the following table.


Id Integer Firewall ID

Result The method returns a hostAttributes data structure (on page 298) that contains the list of business attributes for the specified firewall.

getHostCluster method

Description The getHostCluster method returns the name and ID of the cluster of the specified firewall, or null if the firewall is not part of a cluster.

Syntax hostGroupEntityItem = getHostCluster (Id)

Parameters The parameter of the getHostCluster method is described in the following table.


Id Integer Firewall ID

Result The method returns a HostGroupEntityItem (on page 299) data structure with the ID and name of the host group (cluster).

getHostEntityFields method

Description The getHostEntityFields method returns the list of business attributes for assets, as defined in Tools > Server Options > Options > Business Attributes > Assets.

Syntax getHostEntityFields ()

Parameters The getHostEntityFields method has no parameters.



Result The method returns a list of EntityField data structures (see page 281). Ignore the following in each EntityField:

› id: Always 0

› value: Always null

getHostNetworkInterfaces method

Description The getHostNetworkInterfaces method returns a list of the network interfaces of the specified firewall.

Syntax hostInterfaces = getHostNetworkInterfaces (hostId)

Parameters The parameter of the getHostNetworkInterfaces method is described in the following table.


hostId Integer

Result The method returns a FindNetInterfaceResult data structure (see page 289) that contains the list of network interfaces.

getNetInterfacesByAssetId method

Description The getNetInterfacesByAssetId method returns detailed information about the network interfaces of the specified firewall.

Syntax networkInterfaces = getNetInterfacesByAssetId (assetId)

Parameters The parameter of the getNetInterfacesByAssetId method is described in the following table.


assetId Integer

Result The method returns an array of network interfaces (see page 303).

getNetInterfacesByNetworkId method

Description The getNetInterfacesByNetworkId method returns detailed information about the network interfaces of the specified network.



Syntax networkInterfaces = getNetInterfacesByNetworkId (networkId)

Parameters The parameter of the getNetInterfacesByNetworkId method is described in the following table.


networkId Integer

Result The method returns an array of network interfaces (see page 303).

getZoneFromFW method

Description The getZoneFromFW method finds the zone name of a network IP address according to the zones of the firewall interface that matches this address.

Usually an IP address matches 1 interface and 1 zone is returned. However, if the address covers a wide range that spans multiple network interfaces, the result contains the zones of all the matched interfaces.

The method is a prerequisite for checkAccessCompliance (see page 186), which checks whether access via a port is permitted from zone to zone (after translating the specified networks to zones).

Syntax zone = getZoneFromFW (firewall, ipRange)

Parameters The parameters of the getZoneFromFW method are described in the following table.


firewall Firewall name or firewall ID

The name or ID of the firewall in the model. Use findFirewalls (on page 193) to get this firewall.

ipRange Address element

Result The method returns the zones in the model that matches the address element of the firewall. The list is empty if the address element is not part of any zone in the specified firewall.

getZoneFromNetwork method

Description The getZoneFromNetwork method finds the zone name of a network in the model.



This method is a prerequisite for checkAccessCompliance (see page 186), which checks whether access via a port is permitted from zone to zone (after translating the networks to zones).

Syntax zone = getZoneFromNetwork (network)

Parameters The parameters of the getZoneFromNetwork method are described in the following table.


network NetworkElement (see page 305)

The ID field of the NetworkElement is mandatory. Use findNetworks (on page 196) to get this network.

Result The method returns the name of the zone in the model that matches the network. The name is blank if there is no zone for this network.

isBackwardRouteExist method

Description The isBackwardRouteExist method checks whether a backward route exists between the given destination entity and the source entity (using reversed NAT rules).

Syntax Exists = isBackwardRouteExist (sourceEntity, destinationEntity)

Parameters The parameters of the isBackwardRouteExist method are described in the following table.


sourceEntity IPAndNetworkPair (see page 300)

destinationEntity IPAndNetworkPair (see page 300)

Result The method returns a Boolean specifying whether any backward routes exist.

modifyFirewallException method

Description The modifyFirewallException method takes an exception (with the original ID) on which changes were made and returns the fixed exception.



Syntax modifiedException = modifyFirewallException (firewallException)

Parameters The parameters of the modifyFirewallException method are described in the following table.



Result The method returns an updated FirewallException data structure (see page 294).

modifyRulePolicyException method

Description The modifyRulePolicyException method takes a Rule exception (with the original ID) on which changes were made and returns the fixed exception.

Syntax modifiedException = modifyRulePolicyException (policyException)

Parameters The parameters of the modifyRulePolicyException method are described in the following table.



Result The method returns an updated Rule exception (see page 313).

updateAccessRuleAttributes method

Description The updateAccessRuleAttributes method updates the business attributes of access rules.

Syntax updatedAccessRuleAttributes = updateAccessRuleAttributes (updateInfo)

Parameters The parameters of the updateAccessRuleAttributes method are described in the following table.


updateInfo RulesAttributesUpdateInfo (on page 313)



Result The method returns an AccessRulesResponse data structure (on page 265).

updateFwAccessRuleAttributes method

Description The updateFwAccessRuleAttributes method updates the business attributes of access rules of the specified firewall.

Syntax updatedFwRuleAttributes = updateFwAccessRuleAttributes (updateInfo)

Parameters The parameter of the updateFwAccessRuleAttributes method is described in the following table.


updateInfo FwRulesAttributesUpdateInfo (on page 297)

Result The method returns an AccessRulesByFwResponse data structure (on page 265).

updateHostAttributes method

Description The updateHostAttributes method updates the business attributes for an asset.

Syntax updatedHostAttributes = updateHostAttributes (updateInfo)

Parameters The parameter of the updateHostAttributes method is described in the following table.


updateInfo HostsAttributesUpdateInfo (on page 299)

Result The method returns a HostsResponse data structure (on page 299).

USING THE NETWORK API Use the following URL to view or access the Network web service (<Skybox server> is the name or IP address of your Skybox Server):

› Endpoint address: https://<Skybox server>:8443/skybox/webservice/jaxws/network



› WSDL: {http://skyboxsecurity.com}SkyboxNetworkService



Using the Network API to check access

Typical scenario using the Network API to check access 1 You need access from your computer to an application. Create a ticket in an

external ticketing system to request this access.

2 Provide a source-destination-port combination in the ticket form:

• Source: Your computer

• Destination: The application to which you want access

• Port: The service over which you need the access

3 Click Check Access.

4 The external ticketing system calls the Skybox checkAccessV3 (on page 185) method.

5 The external ticketing system receives an answer from Skybox stating whether the desired access is blocked (not accessible) or available (accessible). If Skybox cannot process the data provided, it returns an error.

6 As required:

• If you are satisfied with the answer, finish processing the external ticket

• If you are not satisfied with the answer, assign the ticket to an expert

Note: The following steps relate to the 2nd option.

7 The expert sees the ticket and decides to use Skybox Manager to check the access.

8 The expert, as required:

• Opens the Skybox Access Analyzer, retypes the source-destination-port combination and checks it there

• Clicks Pass ticket info to Skybox on the external ticket form.

Note: The following steps relate to the 2nd option.

9 The external ticketing system calls the Skybox createChangeManagerTicket method (see page 216), which creates a ticket in Skybox whose properties are based on the external ticket.

10 The expert finds the open ticket, which includes the source-destination-port combination that needs checking. The expert uses the Skybox Access Analyzer to view and understand the access, and can use the information gained there to decide how to process the original ticket in the external ticketing system.

11 After checking the access, the expert closes or rejects the ticket.



Sample workflows for checking access

Workflow for the checkAccess method when checking access across networks Use the web services client application to check whether access from a source IP address to a destination IP address is permitted in the model:

1 Use findNetworks (on page 196) to find the network in the model that contains the source IP address.

2 Use findNetworks (on page 196) to find the network in the model that contains the destination IP address.

3 Create an AccessQueryElement object (see page 260) using the source and destination IP addresses, and network elements found on the previous step.

4 Call checkAccessV3 (on page 185) and analyze its results.

Workflow for the checkAccess method across a firewall Use the web services client application to check whether access from a source IP address to a destination IP address is permitted by a firewall:

1 Use findFirewalls (on page 193) to find the firewall that controls traffic between the specified source and destination IP addresses.

2 Create an AccessQueryElement object (see page 260) using the source and destination IP addresses, and the firewall element found in the previous step

3 Call checkAccessV3 (on page 185) and analyze its results.

Sample workflow for checking Access Compliance

To check whether access between 2 zones violates your Access Policy 1 Use getZoneFromNetwork (on page 203) (twice) to find the zone names

corresponding to the source and destination IP addresses.

2 (Optional) Use findFirewalls (on page 193) to find firewalls that control traffic between the specified source and destination IP addresses.

3 Create a CheckAccessComplianceRequest (see page 275) object using sourceZone, destinationZone, ports and (optionally) firewall elements.

4 Call checkAccessCompliance (see page 186) and analyze its results (list of violated Access Checks).


Chapter 11

This chapter describes the Tickets API, which retrieves and updates Skybox tickets.

The Tickets API supports:

› Integration with external ticketing systems

• Tickets created in Skybox can be replicated in an external ticketing system and status updates from the external ticketing system can be sent back to Skybox tickets.

• Tickets events are available using the Administration API, and the Tickets API enables you to get and set specific ticket fields.

› Integration with workflow applications for firewall change requests:

• These applications can use the Network API (on page 181) to check connectivity and policy compliance of change requests.

• The applications can send tickets to Skybox, enabling you to use Skybox Manager to analyze the requests.

• You can create and manage firewall change tickets (named access change tickets in Skybox) using the Tickets API.

In this chapter

Tickets API methods ........................................................... 209

Using the Tickets API ......................................................... 247

TICKETS API METHODS The Tickets web service enables you to update tickets.

Note: The API enables you to change all the fields of Access Change Tickets. For other ticket types, it enables you to change the general fields only (for example, owner, status, priority, and due date).

The methods in the Tickets web service are described in the following table.

Method Description

addAttachmentFile (on page 213)

Creates an attachment to a ticket in Skybox.

addDerivedChangeRequests (on page 214)

Adds a derived change request to a ticket if the original change request is of type Access Update.

addOriginalChangeRequestsV6

Obsolete method. Information is in the documentation of version

Tickets API



Method Description 10.0.300.

addOriginalChangeRequestsV7 (on page 214)

Adds original change requests to a ticket and then calculates the derived change requests, checks whether a change is required, and checks for policy compliance violations and potential vulnerabilities.

analyzeAccessChangeTicket (on page 215)

Analyzes policy compliance and access for change requests of the specified ticket.

countAccessChangeTickets (on page 215)

Counts tickets by owner, phase, status, ID, or free text. This method is used for page calculations.

createChangeManagerTicket (on page 216)

Creates an Access Change ticket with a workflow and phases.

createRecertifyTicketV2 (on page 217)

Creates tickets for certification of a firewall’s access rules.

createTicketAccessRequestsForObjectChange (on page 217)

Adds change requests to a ticket. The method finds the access rules in which the specified object appears and creates a change request for each access rule.

deleteAccessChangeTicket (on page 218)

Deletes the specified Access Change ticket in Skybox.

deleteChangeRequests (on page 219)

Deletes change requests from a ticket.

expandFirewallsForAccessChangeTicket (on page 219)

Finds all the firewalls for the change requests (sets of source, destination, and port) in a ticket and expands the list of change requests in the ticket so that each change request includes the firewall, source, destination, and port.

findAccessChangeTickets (on page 220)

Retrieves all Access Change tickets that match the search criteria.

findAccessRequests (on page 221)

Retrieves all change requests for the specified firewall created during the specified time frame.

findConfigurationItems (on page 221)

Retrieves the configuration items that are defined in the system.

findTickets (on page 222)

Retrieves all the Access Change tickets in the specified analysis.

getAccessChangeTicket (on page 222)

Retrieves an Access Change ticket from Skybox. Note: There are separate methods for retrieving attachments, phases, events, and change requests.

getAccessRequests (on page 223)

Retrieves change requests according to their ID numbers.

getAnalysisTree (on page 223)

Returns a list of analyses; each analysis includes its ID, path, name, and type.

getAttachmentFile (on page 224)

Retrieves the specified attachment from Skybox.

Chapter 11 Tickets API


Method Description

getAttachmentList (on page 224)

Retrieves the list of attachments to a ticket in Skybox.

getChangeRequestRuleAttributes (on page 225)

Retrieves the rule attributes for the access rule in a change request.

getDerivedChangeRequestRouteInfoV1 (on page 225)

Retrieves the route information from a derived change request.

getDerivedChangeRequestsV6

Obsolete method. Information is in the documentation of version 10.0.300.

getDerivedChangeRequestsV7 (on page 227)

Retrieves the list of derived change requests for an original change request.

getGeneratedCommands (on page 228)

Retrieves the generated command output for the given change request. For Cisco firewalls, the command is in Cisco format. For other firewalls, the command is in a generic format.

getImplementedChangeRequests (on page 228)

Retrieves the list of implemented change requests in Skybox Change Manager according to the permissions of the user sending the request.

getNotImplementedChangeRequests (on page 229)

Retrieves the list of unimplemented change requests in Skybox Change Manager according to the permissions of the user sending the request.

getOriginalChangeRequestV6

Obsolete method. Information is in the documentation of version 10.0.300.

getOriginalChangeRequestV7 (on page 232)

Retrieves all the (original) change requests in the specified ticket.

getOriginalChangeRequestRouteInfoV1 (on page 229)

Retrieves the route information from an original change request.

getPolicyViolations (on page 232)

Retrieves the list of Access Policy violations associated with a change request.

getPotentialVulnerabilities (on page 233)

Retrieves the list of Vulnerability Definitions that, if the requested change is made, are directly exposed to assets.

getSponsoringApplication (on page 233)

Retrieves the sponsoring application of the specified ticket. Sponsoring applications determine who the phase owners are for the ticket.

getTicketAccessRequests (on page 234)

Retrieves from Skybox the list of change requests for the specified ticket.

getTicketDeferChangeRequestsCalculationStatus (on page 234)

Returns the calculation status of the specified ticket (whether calculation of the change requests is deferred).



Method Description

getTicketEvents (on page 235)

Retrieves the history of a ticket.

getTicketFields (on page 235)

Retrieves ticket data from Skybox. You can use this method with all ticket types.

getTicketPhases (on page 236)

Retrieves from Skybox the list of ticket phases for a ticket type.

getTicketsImplementedChangeRequests (on page 237)

Retrieves the list of implemented change requests in the specified tickets according to the permissions of the user sending the request.

getTicketsNotImplementedChangeRequests (on page 237)

Retrieves the list of unimplemented change requests in the specified tickets according to the permissions of the user sending the request.

getTicketTypePhasesByTicketType (on page 236)

Retrieves the list of phases for the specific ticket type.

getTicketWorkflows (on page 237)

Retrieves the list of ticket workflows in Skybox, including an ID and a name for each ticket.

getVerificationDetails (on page 238)

Retrieves the verification details (that is, the matching FirewallChange objects) for Add Rule or Modify Rule change requests that are already verified. If the change request is not verified, the method returns null.

implementChangeRequests (on page 238)

Implements the specified change requests.

operateOnAccessChangeTicket (on page 239)

Enables you to change the phase of a ticket without sending the full ticket data.

operateOnVulnerabilityDefinitionTicket (on page 240)

Enables you to change the phase of a Vulnerability Definition ticket without sending the full ticket data.

recalculateTicketChangeRequests (on page 241)

Recalculates the change requests of the specified ticket.

removeAttachmentFile (on page 241)

Deletes an attachment from a ticket in Skybox.

setAddRuleChangeRequestFields (on page 241)

Makes changes to specific fields of a change request.

setChangeRequestRuleAttributes (on page 242)

Sets the rule attributes for the rules in the specified change requests.

setRecertificationStatus (on page 243)

Sets the recertification status for the specified change requests in the ticket and can be used to change any other rule attributes for the rules in the specified change requests.

setSponsoringApplication (on page 243)

Sets the sponsoring application for a ticket.



Method Description

setTicketAccessRequests (on page 244)

Sets the list of change requests to the specified ticket.

setTicketDeferChangeRequestsCalculationStatus (on page 245)

Enables you to defer the automatic calculation of a ticket until all the change requests are created.

setTicketFields (on page 245)

Sets ticket data in Skybox. You can use this method with all ticket types.

setTicketPhases (on page 246)

Sets the list of ticket phases for a ticket type in Skybox.



updateAccessChangeTicket (on page 246)

Enables you to modify an Access Change ticket. Note: There are separate methods for updating attachments, phases, events, and change requests.

addAttachmentFile method

Description The addAttachmentFile method creates an attachment to the specified ticket in Skybox. The attachment includes the metadata and the attachment file.

Syntax attachmentId = addAttachmentFile (Owner, attachmentDesc, sourceFileName, attachmentData, ticketId, phaseName)

Parameters The parameters of the addAttachmentFile method are described in the following table.


Owner String

attachmentDesc String

sourceFileName String

attachmentData DataHandler javax.activation.DataHandler

ticketId Integer

phaseName String The phase for which to add the attachment

Result The method returns the ID of the attachment.



addDerivedChangeRequests method

Description The addDerivedChangeRequests method adds a derived change request to a ticket if the original change request is of type Access Update.

Validation for this method The change request is only added if the user has permissions to edit the ticket.

Syntax derivedRequests = addDerivedChangeRequests (ticketId, changeRequestId, firewalls)

Parameters The parameters of the addDerivedChangeRequests method are described in the following table.


ticketId Integer The ID of the ticket

changeRequestId Integer The ID of the original change request

firewalls Array of Asset (see page 269)

Array of firewalls for which to add derived change requests

Result The method returns an array of derived change requests (see page 271) for the specified firewalls.

addOriginalChangeRequestsV7 method

Description The addOriginalChangeRequestsV7 method adds original change requests to a ticket. The method then calculates the derived change requests, checks whether a change is required, and checks for policy compliance violations and potential vulnerabilities.

Validations for this method The change requests are only added if:

› The user has permissions to edit the ticket › They are permitted in the workflow of the ticket

Note: The derived change requests are not optimized.

Note: Firewall identification is based on the mode set in Tools > Options > Server > Change Manager Settings.

Syntax originalChangeRequests = addOriginalChangeRequestsV7 (ticketId, changeRequests)



Parameters The parameters of the addOriginalChangeRequestsV7 method are described in the following table.



changeRequests Array of ChangeRequestV3 (on page 271)

Any type of change request extensions; not abstract change requests

Result The method returns an array of change requests.

analyzeAccessChangeTicket method

Description The analyzeAccessChangeTicket method analyzes access and Access Policy compliance for change requests of the specified ticket.

Syntax ticket = analyzeAccessChangeTicket (ticketId, accessRequests, Mode)

Parameters The parameters of the analyzeAccessChangeTicket method are described in the following table.


ticketId Integer The ID of the ticket to analyze

accessRequests Array of Integer A list of change request IDs in the ticket to analyze. An empty list means that all change requests are analyzed. Note: To retrieve a list of the change requests in a ticket, use getTicketAccessRequests (on page 234).

Mode Integer The type of analysis: • 0: Access analysis only • 1: Access Policy compliance

analysis only • 2: Both

Result The method returns an AccessChangeTicket data structure (see page 259), with updated change requests.

countAccessChangeTickets method

Description The countAccessChangeTickets method counts the number of tickets that match the specified filter (owner, phase, status, ID, created by, or modified by parameters; or free text search). The output is used for page calculations.



The method works in conjunction with findAccessChangeTickets (see page 220), which returns the tickets.

Syntax numTickets = countAccessChangeTickets (Filter, subRange)

Parameters The parameters of the countAccessChangeTickets method are described in the following table.


Filter TicketsSearchFilter (see page 318)

Mandatory


Mandatory

Result The method returns an integer representing the number of Access Change tickets that match the search criteria.

createChangeManagerTicket method

Description The createChangeManagerTicket method creates an Access Change ticket with a workflow and phases.

Note that:

› If the user creating the ticket does not have permission to create tickets in the selected workflow, no ticket is created.

› If you do not provide a workflow, the ticket is created in the user’s default workflow. If no default workflow was defined for the user, no ticket is created.

You can retrieve an Access Change ticket using getAccessChangeTicket (on page 222) and update it using updateAccessChangeTicket (on page 246).

Syntax ticket = createChangeManagerTicket (accessChangeTicket, phases, workflowId)

Parameters The parameters of the createChangeManagerTicket method are described in the following table.


accessChangeTicket

AccessChangeTicket (see page 259)

Mandatory

phases Array of Phase (see page 307)

Default phases are created (according to the workflow) if the list is empty.

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 237).



Result The method returns an AccessChangeTicket data structure (see page 259).

createRecertifyTicketV2 method

Description The createRecertifyTicketV2 method creates tickets for certification of a firewall’s access rules. The workflow is checked to ascertain that it permits recertification. Ticket creation uses the same logic as that used by Rule Recertification tasks.

Syntax ticketList = createRecertifyTicketV2 (accessChangeTicket, accessRuleElements, workflowId)

Parameters The parameters of the createRecertifyTicketV2 method are described in the following table.


accessChangeTicket


Mandatory

accessRuleElements

Array of AccessRuleElementV4 (on page 263)

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 237).

Result The method returns a RecertifyTicketCreationResultV2 data structure (on page 310) that contains a list of new ticket IDs and a list of the access rules that are not included in these tickets.

createTicketAccessRequestsForObjectChange method

Description The createTicketAccessRequestsForObjectChange method adds change requests to a ticket. The method finds the access rules in which the specified object occurs and creates a change request for each access rule.

Syntax createTicketAccessRequestsForObjectChange (ticketId, hostId, objectName, changeType, addressChange, portChange, maxAccessRequestsToCreate, chainFilterMode, chainNames)

Parameters The parameters of the createTicketAccessRequestsForObjectChange method are described in the following table.


ticketId Integer The ID of the ticket to which the change requests are attached.




hostId Integer The ID of the device to change.

objectName String The name of the object to change. The object can be an IP address object or Service object.

changeType Integer The type of the change: • 0: Add to the object

addressChange Array of String The IP address to add to or delete from the object. Relevant only if the object is an IP address object.

portChange String The service to add to or deleted from the object. Relevant only if the object is a Service object.

maxAccessRequestsToCreate

Integer Limits the number of change requests that are created.



Result The method creates change requests on the specified ticket.

deleteAccessChangeTicket method

Description The deleteAccessChangeTicket method deletes the specified Access Change ticket in Skybox.

Syntax deleteAccessChangeTicket (ticketId)

Parameters The parameter of the deleteAccessChangeTicket method is described in the following table.



Result The method deletes the specified ticket in Skybox and writes the deletion in the activity log. (For information about this log, see the Activity log section in the Skybox Installation and Administration Guide.)



deleteChangeRequests method

Description The deleteChangeRequests method deletes change requests from a ticket.

Validation for this method The change requests are only deleted if the user has permissions to edit the ticket.

Syntax deleteChangeRequests (ticketId, changeRequestIds)

Parameters The parameters of the deleteChangeRequests method are described in the following table.



changeRequestIds Array of Integer The IDs of the change requests to delete

Result The method deletes the specified change requests from the ticket.

expandFirewallsForAccessChangeTicket method

Description The expandFirewallsForAccessChangeTicket method finds all the firewalls for the change requests (sets of source, destination, and port) in a ticket and expands the list of change requests in the ticket so that each change request includes the firewall, source, destination, and port. The source and destination are redefined to include the network interfaces that are attached to the specified networks.

The method saves writing code that explicitly calls findFirewalls (see page 193) for each source-destination-port combination and then creates a list of change requests per firewall per source-destination-port combination.

Note: If the source or destination of a change request is updated, set the Recalculate flag to true. If you are adding a change request, you might not need to set the flag.

An example of a ticket that includes 2 change requests is shown in the following table.

Source Destination Ports Firewall

Source Zone

Destination Zone

NetworkA NetworkB 80

NetworkC NetworkD 21

After calling this method, the expanded ticket includes the change requests listed in the following table.



Source Destination Ports Firewall

Source Zone

Destination Zone

NetworkA (int_2)

NetworkB (int_3)

80 main_FW

External DMZ

NetworkA (int_54)

NetworkB (int_55)

80 prod FW

External Internal

NetworkC (int_4)

NetworkD (int_7)

21 vlab-cisco

External DMZ

NetworkC (int_1)

NetworkD (int_2)

21 dev FW External Partner

NetworkC (int_49)

NetworkD (int_53)

21 prod FW

External Internal

Syntax ticket = expandFirewallsForAccessChangeTicket (ticketId, accessRequestIds, Recalculate)

Parameters The parameters of the expandFirewallsForAccessChangeTicket method are described in the following table.



accessRequestIds Array of Integer A list of change request IDs. If the list is empty, all change requests are expanded.

Recalculate Boolean Specifies whether to expand the selected change requests.

Result The method returns an AccessChangeTicket data structure (see page 259) with updated change requests that include firewalls, network interfaces, and zones for each change request.

findAccessChangeTickets method

Description The findAccessChangeTickets method returns an array containing all the Access Change tickets that match the search criteria.

We recommend that you use countAccessChangeTickets (on page 215) to count the number of tickets for display purposes and then run findAccessChangeTickets.

Syntax matchingTickets = findAccessChangeTickets (filter)

Parameters The parameter of the findAccessChangeTickets method is described in the following table.




filter TicketsSearchFilter (see page 318)

Result The method returns an array of AccessChangeTicket data structures (see page 259).

findAccessRequests method

Description The findAccessRequests method retrieves all change requests for the specified firewall created during the specified time frame. The change requests might not all be from the same ticket.

Use this method with setChangeReconciliationInfo (see page 178) (in the Firewall Changes API) to connect change requests to a change record.

Syntax accessRequests = findAccessRequests (hostId, dateRange)

Parameters The parameters of the findAccessRequests method are described in the following table.


hostId Integer The ID of the firewall for which to find change requests.

dateRange DateRange (see page 280)

The time frame for which to find change requests.

Result The method returns a list of AccessRequest data structures (see page 262) for the specified time frame and the specified asset.

findConfigurationItems method

Description The findConfigurationItems method retrieves the configuration items defined in the system. A filter can be used to limit the search.

Syntax list = findConfigurationItems (filter, subRange)

Parameters The parameters of the findConfigurationItems method are described in the following table.




filter ConfigurationItemFilter (see page 277)


Limits the results to the specified subrange

Result The method returns a list of configuration items (see page 270).

findTickets method

Description The findTickets method retrieves all the Access Change tickets in the specified analysis.

Note: This method supports only Access Change tickets.

Syntax list = findTickets (analysis, subRange)

Parameters The parameters of the findTickets method are described in the following table.


analysis Analysis The analysis from which to retrieve the tickets


Limits the results to the specified subrange

Result The method returns a list of Access Change tickets (see page 259).

getAccessChangeTicket method

Description The getAccessChangeTicket method retrieves an Access Change ticket from Skybox.

Note: There are separate methods for retrieving attachments, phases, events, and change requests.

Use this method before calling updateAccessChangeTicket (see page 246) to modify a ticket.

Syntax ticket = getAccessChangeTicket (ticketId)

Parameters The parameter of the getAccessChangeTicket method is described in the following table.





Result The method returns an AccessChangeTicket data structure (see page 259).

getAccessRequests method

Description The getAccessRequests method retrieves change requests according to their ID numbers.

The result of calling findChangeReconciliationInfo (see page 176) (in the Firewall Changes API) for a change record includes a list of the IDs of change requests that are relevant to the specified change record. Use this method to get the details of the change requests (that is, the source, destination, and service) so that you can display it in the application.

Syntax accessRequests = getAccessRequests (accessRequestIds)

Parameters The parameter of the getAccessRequests method is described in the following table.


accessRequestIds Array of Integer The IDs of the desired change requests

Result The method returns a list of the specified AccessRequest data structures (see page 262).

getAnalysisTree method

Description The getAnalysisTree method returns a list of analyses; each analysis includes its ID, path, name, and type.

Note: This method supports analyses in the Tickets workspace only.

Syntax tree = getAnalysisTree (type)

Parameters The parameter of the getAnalysisTree method is described in the following table.


type String Legal values: • Network Assurance Tickets Public • Network Assurance Tickets Private



Result The method returns a list of analyses.

getAttachmentFile method

Description The getAttachmentFile method retrieves the specified ticket attachment from Skybox.

You can retrieve a list of ticket attachments using getAttachmentList (on page 224) and then run getAttachmentFile to pass the ID of the desired attachment to retrieve the file. You can use the attachment ID to delete the attachment from the ticket using removeAttachmentFile (on page 241).

Syntax attachment = getAttachmentFile (attachmentId)

Parameters The parameter of the getAttachmentFile method is described in the following table.


attachmentId Integer The ID of the attachment file (retrieved using getAttachmentList (on page 224))

Result The method returns the attachment file (javax.activation.DataHandler).

getAttachmentList method

Description The getAttachmentList method retrieves the list of attachments to a ticket in Skybox.

Note: The method returns metadata about each attachment (see page 269). To retrieve an attachment, call getAttachmentFile (on page 224) with the ID of the desired attachment.

Syntax list = getAttachmentList (ticketId)

Parameters The parameter of the getAttachmentList method is described in the following table.



Result The method returns a list of Attachment data structures (see page 269) for the specified ticket.



getChangeRequestRuleAttributes method

Description The getChangeRequestRuleAttributes method retrieves the rule attributes for the access rule in a change request.

Syntax changeRequestRuleAttributes = getChangeRequestRuleAttributes (ticketId, changeRequestId)

Parameters The parameters of the getChangeRequestRuleAttributes method are described in the following table.




Result The method returns a data structure of type RuleAttributes (see page 312) that contains the rule attributes of the access rule in the specified change request.

getDerivedChangeRequestRouteInfoV1 method

Description The getDerivedChangeRequestRouteInfoV1 method retrieves the route information from a derived change request.

Syntax changeRequestRouteInfo = getDerivedChangeRequestRouteInfoV1 (ticketId, changeRequestId)

Parameters The parameters of the getDerivedChangeRequestRouteInfoV1 method are described in the following table.




Result The method returns a data structure of type RouteV1 (on page 312) that contains the route information in the specified change request.

Sample call <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <Body> <getDerivedChangeRequestRouteInfoV1 xmlns="http://skyboxsecurity.com"> <ticketId xmlns="">413</ticketId> <changeRequestId xmlns="">595</changeRequestId> </getDerivedChangeRequestRouteInfoV1>



</Body> </Envelope>

Sample response <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:getDerivedChangeRequestRouteInfoV1Response xmlns:ns2="http://skyboxsecurity.com"> <return> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Internet</name> <networkId>1</networkId> </networkItems> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.1.97</displayIPAddress> <displayName>main_FW</displayName> <hostGroupName></hostGroupName> <hostId>5</hostId> <inboundNetInterfaceId>445</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Firewall</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.8.1</displayIPAddress> <displayName>Main Router</displayName> <hostGroupName></hostGroupName> <hostId>1</hostId> <inboundNetInterfaceId>2</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.8.2</displayIPAddress> <displayName>Internal Router</displayName> <hostGroupName></hostGroupName> <hostId>2</hostId> <inboundNetInterfaceId>3</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1">



<destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.1.1</displayIPAddress> <displayName>dev FW</displayName> <hostGroupName></hostGroupName> <hostId>294</hostId> <inboundNetInterfaceId>424</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Firewall</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.19.1</displayIPAddress> <displayName>Dev. L3 Switch</displayName> <hostGroupName></hostGroupName> <hostId>6</hostId> <inboundNetInterfaceId>17</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>192.170.17.0/24</ipNetwork> <name>developmentWindowsWS</name> <networkId>5</networkId> </networkItems> </routeNodes> </return> </ns2:getDerivedChangeRequestRouteInfoV1Response> </soap:Body> </soap:Envelope>

getDerivedChangeRequestsV7 method

Description The getDerivedChangeRequestsV7 method retrieves the list of derived change requests for an original change request.

Validation for this method The derived change requests are only returned if the user has permissions to view this ticket. If the user has no permissions for the ticket, they get an error message.

Syntax derivedChangeRequests = getDerivedChangeRequestsV7 (ticketId, changeRequestId)

Parameters The parameters of the getDerivedChangeRequestsV7 method are described in the following table.






Result The method returns an array of ChangeRequestV3 (on page 271) (the derived requests).

getGeneratedCommands method

Description The getGeneratedCommands method retrieves the generated command output for the given change request.

Note: This method supports generation of commands for Cisco assets only.

Validation for this method The generated commands are only returned if the user has permissions to view this ticket.

Syntax generatedCommands = getGeneratedCommands (ticketId, changeRequestId)

Parameters The parameters of the getGeneratedCommands method are described in the following table.



changeRequestId Integer The ID of the change request for which to retrieve the generated commands

Result The method returns the generated command output (as a string).

getImplementedChangeRequests method

Description The getImplementedChangeRequests method retrieves the list of implemented change requests in Skybox Change Manager according to the permissions of the user sending the request.

Syntax implementedChangeRequests = getImplementedChangeRequests ()

Parameters The getImplementedChangeRequests method has no parameters.



Result The method returns an array of ChangeRequestImplementation (on page 273) data structures.

getNotImplementedChangeRequests method

Description The getNotImplementedChangeRequests method retrieves the list of unimplemented change requests in Skybox Change Manager according to the permissions of the user sending the request.

This list can then be sent for implementation using implementChangeRequests (on page 238).

Note: For information about the supported change request types and devices, see Automatic implementation, in the Change Manager User Guide.

Syntax notImplementedChangeRequests = getNotImplementedChangeRequests ()

Parameters The getNotImplementedChangeRequests method has no parameters.


getOriginalChangeRequestRouteInfoV1 method

Description The getOriginalChangeRequestRouteInfoV1 method retrieves the route information from an original change request.

Syntax changeRequestRouteInfo = getOriginalChangeRequestRouteInfoV1 (ticketId, changeRequestId)

Parameters The parameters of the getOriginalChangeRequestRouteInfoV1 method are described in the following table.




Result The method returns a data structure of type RouteV1 (on page 312) that contains the route information in the specified change request.

Sample call <Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <Body>



<getOriginalChangeRequestRouteInfoV1 xmlns="http://skyboxsecurity.com"> <ticketId xmlns="">413</ticketId> <changeRequestId xmlns="">594</changeRequestId> </getOriginalChangeRequestRouteInfoV1> </Body> </Envelope>

Sample response <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:getOriginalChangeRequestRouteInfoV1Response xmlns:ns2="http://skyboxsecurity.com"> <return> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Tunnel_52.72.96.127_to_31.168.135.156</name> <networkId>113</networkId> </networkItems> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Tunnel_54.165.250.119_to_31.168.135.156</name> <networkId>114</networkId> </networkItems> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>internet_cloud_AWS</name> <networkId>101</networkId> </networkItems> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Tunnel_52.72.96.127_to_31.168.135.156</name> <networkId>113</networkId> </networkItems> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Tunnel_54.165.250.119_to_31.168.135.156</name> <networkId>114</networkId> </networkItems> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>internet_cloud_AWS</name> <networkId>101</networkId> </networkItems> </routeNodes> </return> <return> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>0.0.0.0/0</ipNetwork> <name>Internet</name> <networkId>1</networkId> </networkItems> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1">



<destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.1.97</displayIPAddress> <displayName>main_FW</displayName> <hostGroupName></hostGroupName> <hostId>5</hostId> <inboundNetInterfaceId>445</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Firewall</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.8.1</displayIPAddress> <displayName>Main Router</displayName> <hostGroupName></hostGroupName> <hostId>1</hostId> <inboundNetInterfaceId>2</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.8.2</displayIPAddress> <displayName>Internal Router</displayName> <hostGroupName></hostGroupName> <hostId>2</hostId> <inboundNetInterfaceId>3</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.1.1</displayIPAddress> <displayName>dev FW</displayName> <hostGroupName></hostGroupName> <hostId>294</hostId> <inboundNetInterfaceId>424</inboundNetInterfaceId> <performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Firewall</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:gatewayRouteNodeV1"> <destinationRanges>192.170.17.4-192.170.17.4</destinationRanges> <displayIPAddress>192.170.19.1</displayIPAddress> <displayName>Dev. L3 Switch</displayName> <hostGroupName></hostGroupName> <hostId>6</hostId> <inboundNetInterfaceId>17</inboundNetInterfaceId>



<performsNAT>false</performsNAT> <services>1-65535/25-25/TCP</services> <sourceRanges>7.7.7.7-7.7.7.7</sourceRanges> <typeEnum>Router</typeEnum> </routeNodes> <routeNodes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:networkRouteNodeV1"> <networkItems> <ipNetwork>192.170.17.0/24</ipNetwork> <name>developmentWindowsWS</name> <networkId>5</networkId> </networkItems> </routeNodes> </return> </ns2:getOriginalChangeRequestRouteInfoV1Response> </soap:Body> </soap:Envelope>

getOriginalChangeRequestV7 method

Description The getOriginalChangeRequestV7 method retrieves all the (original) change requests in the specified ticket.

Validation for this method The original change requests are only returned if the user has permissions to view this ticket. If the user has no permissions for the ticket, they get an error message.

Syntax originalChangeRequests = getOriginalChangeRequestV7 (ticketId)

Parameters The parameter of the getOriginalChangeRequestV7 method is described in the following table.



Result The method returns an array of ChangeRequestV3 (on page 271) (the original requests).

getPolicyViolations method

Description The getPolicyViolations method retrieves the list of Access Policy violations associated with a change request.

Validation for this method The policy violations are only returned if the user has permissions to view this ticket.



Syntax policyViolations = getPolicyViolations (ticketId, changeRequestId)

Parameters The parameters of the getPolicyViolations method are described in the following table.



changeRequestId Integer The ID of the change request for which you want to see policy violations

Result The method returns an array of ChangeRequestComplianceViolationElement (see page 272).

getPotentialVulnerabilities method

Description The getPotentialVulnerabilities method retrieves the list of Vulnerability Definitions that, if the requested change is made, are directly exposed to assets.

Validation for this method The potential vulnerabilities are only returned if the user has permissions to view this ticket.

Syntax potentialVulnerabilities = getPotentialVulnerabilities (ticketId, changeRequestId)

Parameters The parameters of the getPotentialVulnerabilities method are described in the following table.



changeRequestId Integer The ID of the change request for which you want to see policy violations

Result The method returns an array of ChangeRequestPotentialVulnerability (see page 274).

getSponsoringApplication method

Description The getSponsoringApplication method retrieves the sponsoring application of the specified ticket. Sponsoring applications determine who the phase owners are for the ticket.



Syntax application = getSponsoringApplication (ticketId)

Parameters The parameter of the getSponsoringApplication method is described in the following table.



Result The method returns a BaseConfigurationItem data structure (see page 270).

getTicketAccessRequests method

Description The getTicketAccessRequests method retrieves the list of change requests for the specified ticket. You can add or update change requests for the ticket by inputting the list to setTicketAccessRequests (see page 244).

Syntax accessRequests = getTicketAccessRequests (ticketId)

Parameters The parameter of the getTicketAccessRequests method is described in the following table.



Result The method returns an array of AccessRequest data structures (see page 262) for the specified ticket.

getTicketDeferChangeRequestsCalculationStatus method

Description The getTicketDeferChangeRequestsCalculationStatus method returns the calculation status of the specified ticket. By default, change requests are always calculated as soon as there is a change in the ticket. However, you can defer calculation until all the change requests are added to the ticket.

Syntax status = getTicketDeferChangeRequestsCalculationStatus (ticketId)

Parameters The parameter of the getTicketDeferChangeRequestsCalculationStatus method is described in the following table.





Result The method returns a Boolean value specifying whether calculation was deferred for the specified ticket; a value of true means that calculation was deferred.

getTicketEvents method

Description The getTicketEvents method retrieves the history (that is, the list of changes made) of the specified ticket.

Syntax getTicketEvents (ticketId)

Parameters The parameter of the getTicketEvents method is described in the following table.



Result The method returns an array of TicketEvent data structures (see page 317) for the specified ticket.

getTicketFields method

Description The getTicketFields method gets ticket data from Skybox. You can use it with all ticket types.

Note: This method and setTicketFields translate between the external ticket ID and the Skybox ticket ID. All other methods use the Skybox ticket ID.

Syntax ticket = getTicketFields (ticketIdType, ticketId)

Parameters The parameters of the getTicketFields method are described in the following table.


ticketIdType Integer Signifies whether the ticket ID is the Skybox ticket ID or the ID from the external ticketing system Possible values: • 1 (SBV ID) • 2 (ID from external ticketing

system) ticketId String The ID of the ticket

Result The method returns an array of TicketField data structures (see page 317).



getTicketPhases method

Description The getTicketPhases method retrieves the list of phases for the specified ticket. You can change the due dates and assignees for the ticket by inputting the list to setTicketPhases (see page 246).

Syntax phases = getTicketPhases (ticketId)

Parameters The parameter of the getTicketPhases method is described in the following table.



Result The method returns an array of Phase data structures (see page 307) for the specified ticket.

getTicketTypePhasesByTicketType method

Description The getTicketTypePhasesByTicketType method retrieves the list of phases for the specified ticket type.

Note: It is not necessary to use this method if Skybox defines the phases for each ticket when creating the ticket (using createChangeManagerTicket (on page 216)) and then calls getTicketPhases (on page 236) (using the ticket ID) and edits the phases for the ticket.

Syntax phases = getTicketTypePhasesByTicketType (ticketType)

Parameters The parameter of the getTicketTypePhasesByTicketType method is described in the following table.


ticketType String (enum) • VulnerabilityTicket • ApplicationTicket • VulnerabilityDefinitionTicket • AccessChangeTicket • PolicyViolationTicket

Result The method returns a list of TicketTypePhase data structures (see page 318) for the specified ticket type.



getTicketWorkflows method

Description The getTicketWorkflows method retrieves the list of ticket workflows in Skybox, and includes an ID and a name for each workflow.

Syntax ticketWorkflows = getTicketWorkflows ()

Parameters The getTicketWorkflows method has no parameters.

Result The method returns an array of TicketWorkflow data structures (see page 319).

getTicketsImplementedChangeRequests method

Description The getTicketsImplementedChangeRequests method retrieves the list of implemented change requests in the specified tickets according to the permissions of the user sending the request.

Syntax ticketsImplementedChangeRequests = getTicketsImplementedChangeRequests (ticketIds)

Parameters The parameter of the getTicketsImplementedChangeRequests method is described in the following table.


ticketIds Array of Integer The IDs of the tickets in Skybox Change Manager


getTicketsNotImplementedChangeRequests method

Description The getTicketsNotImplementedChangeRequests method retrieves the list of unimplemented change requests in the specified tickets according to the permissions of the user sending the request.

This list can then be sent for implementation using implementChangeRequests (on page 238).

Note: For information about the supported change request types and devices, see Automatic implementation, in the Change Manager User Guide.



Syntax ticketsNotImplementedChangeRequests = getTicketsNotImplementedChangeRequests (ticketIds)

Parameters The parameter of the getTicketsNotImplementedChangeRequests method is described in the following table.


ticketIds Array of Integer The IDs of the tickets in Skybox Change Manager


getVerificationDetails method The getVerificationDetails method retrieves the verification details (that is, the matching FirewallChange objects) for Add Rule or Modify Rule change requests that are verified. If the change request is not verified, the method returns null.

Validation for this method The verification details are returned only if the user has permissions to view this ticket.

Syntax verificationDetails= getVerificationDetails (ticketId, changeRequestId)

Parameters The parameters of the getVerificationDetails method are described in the following table.


ticketId Integer The ID of the ticket.

changeRequestId Integer The ID of the (derived) change request for which you want to see the firewall objects that are changed.

Result The method returns an array of FirewallChange data structures (see page 291); if the change request is not verified, the method returns null.

Note: For change requests other than Add Rule or Modify Rule, an exception is returned if the request type is not supported.

implementChangeRequests method

Description The implementChangeRequests method implements the specified change requests. After this, you can use getImplementedChangeRequests (on page 228) to see the implemented change requests.



Syntax implementedRequests = implementChangeRequests (changeRequests, comment)

Parameters The parameters of the implementChangeRequests method are described in the following table.


changeRequests Array of ChangeRequestImplementation (on page 273)

comment String The formula for the comment to add to rules when the rules are implemented. For example, <DATE> - Created by <USERNAME> for ticket <TICKET_ID>. The comment must include at least 1 of the parameters (date, user name, or ticket ID).

Result If automatic implementation is not enabled or no ticket ID is included for a request, the relevant error messages are returned.

If the method is not successful, an exception is returned.

For information about automatic implementation, see Automatic implementation, in the Change Manager User Guide.

operateOnAccessChangeTicket method

Description The operateOnAccessChangeTicket method enables you to change the phase of an Access Change ticket without sending the full ticket data.

The following changes can be made using this method:

› Accept a ticket › Change a ticket’s phase › Close a ticket › Demote a ticket › Change the status of the ticket to Ignored › Promote a ticket › Reassign a ticket › Reopen a ticket › Request to close a ticket

Syntax operatedOnAccessChangeTicket (ticketId, phaseOperation)



Parameters The parameters of the operateOnAccessChangeTicket method are described in the following table.


ticketId Integer

phaseOperation PhaseOperation (see page 308)


operateOnVulnerabilityDefinitionTicket method

Description The operateOnVulnerabilityDefinitionTicket method enables you to change the phase of a Vulnerability Definition ticket without sending the full ticket data.

The following changes can be made using this method:

› Accept a ticket › Change a ticket’s phase › Close a ticket › Demote a ticket › Change the status of the ticket to Ignored › Promote a ticket › Reassign a ticket › Reopen a ticket › Request to close a ticket

Syntax operateOnVulnerabilityDefinitionTicket (ticketId, phaseOperation)

Parameters The parameters of the operateOnVulnerabilityDefinitionTicket method are described in the following table.


ticketId Integer





recalculateTicketChangeRequests method

Description The recalculateTicketChangeRequests method recalculates the change requests of the specified ticket.

Syntax recalculateTicketChangeRequests (ticketId)

Parameters The parameter of the recalculateTicketChangeRequests method is described in the following table.




removeAttachmentFile method

Description The removeAttachmentFile method deletes the specified attachment from a ticket in Skybox.

Syntax removeAttachmentFile (attachmentId)

Parameters The parameter of the removeAttachmentFile method is described in the following table.


attachmentId Integer The ID of the attachment. Find the ID using getAttachmentList (on page 224).

Result The method deletes the specified attachment from its ticket in Skybox.

setAddRuleChangeRequestFields method

Description The setAddRuleChangeRequestFields method supports changes to the following fields of a derived change request:

› isLogEnabled › isSharedObject › isInstallOnAny › isGlobal



› securityProfileGroup › loggingProfile › implementBeforeAccessRuleOrder (0 represents the last rule) › expirationDate

You can change multiple fields per call. You can also reset securityProfileGroup, loggingProfile, and expirationDate by sending an empty value.

Syntax setAddRuleChangeRequestFields (ticketId, changeRequestId, fields)

Parameters The parameters of the setRecertificationStatus method are described in the following table.


ticketId String The ID of the ticket

changeRequestId Integer The ID of the change request in which to make the changes

fields Array Each element of the array is a key (name of field) + value set


setChangeRequestRuleAttributes method

Description The setChangeRequestRuleAttributes method sets the rule attributes for the rules in the specified change requests. For example, you can change the status of a group of change requests to recertified, and change their owner and owner email at the same time.

Syntax setChangeRequestRuleAttributes (ticketId, changeRequestIds, ruleAttributes)

Parameters The parameters of the setChangeRequestRuleAttributes method are described in the following table.



changeRequestIds Array of Integer The IDs of the change requests for which to update the rule attributes

ruleAttributes RuleAttributes (see page 312)




setRecertificationStatus method

Description The setRecertificationStatus method sets the recertification status for the specified change requests in the ticket. Possible recertification statuses are:

› NONE › IN_PROGRESS › REJECTED › CERTIFIED

The method can be used to change any other rule attributes for the rules in the specified change requests. For example, you can change the status of a group of change requests to recertified, and change their owner and owner email at the same time.

Syntax setRecertificationStatus (ticketId, changeRequestIds, ruleAttributes)

Parameters The parameters of the setRecertificationStatus method are described in the following table.



changeRequestIds Array of Integer The IDs of the change requests for which to set the recertification status



setSponsoringApplication method

Description Sponsoring applications for tickets enables setting the default owners for ticket phases. If an application is associated with a ticket, the phase approver settings of the selected application define the default owners for the phases. If there are no approvers defined for the application or for a phase, the default phase owners are those defined for the phases.

The setSponsoringApplication method sets the sponsoring application for a ticket.

Syntax setSponsoringApplication (ticketId, sponsoringApplicationId)



Parameters The parameters of the setSponsoringApplication method are described in the following table.


ticketId Integer

sponsoringApplicationId

Integer


setTicketAccessRequests method

Description The setTicketAccessRequests method sets the list of change requests for the specified ticket.

The method overwrites the existing list; to add to the list of change requests or update requests, retrieve the original list (using getTicketAccessRequests (on page 234)), make the changes, and then use this method to send the updated list back to Skybox.

For new requests, fill the sourceAddresses, destinationAddresses, and ports fields of the AccessQueryElement data structure (see page 260), and leave the other fields. You can define the firewall for each request or use expandFirewallsForAccessChangeTicket (on page 219).

Note: After you create change requests for a ticket (including the firewall for each request), call analyzeAccessChangeTicket (on page 215) to check the access.

Syntax setTicketAccessRequests (ticketId, accessRequests)

Parameters The parameters of the setTicketAccessRequests method are described in the following table.



accessRequests Array of AccessRequest (see page 262)




setTicketDeferChangeRequestsCalculationStatus method

Description The setTicketDeferChangeRequestsCalculationStatus method enables you to defer the automatic calculation of a ticket until all the change requests are created.

When you create or update access change tickets, all the new or modified change requests are calculated. This method enables you to defer the calculation of the ticket until all the change requests are created.

Typical workflow 1 Create a ticket or open a ticket for modification.

2 Set the defer ticket calculation flag to true.

3 Create a change request and save the ticket.

The new change request is not calculated.

4 (Optional) Create additional change requests.

5 Set the defer ticket calculation flag to false.

All the new change requests are calculated.

Syntax setTicketDeferChangeRequestsCalculationStatus (ticketId, deferChangeRequestsCalculation)

Parameters The parameters of the setTicketDeferChangeRequestsCalculationStatus method are described in the following table.


ticketId Integer

deferChangeRequestsCalculation

Boolean • True: Defer calculation of the change requests

• False: Do not defer calculation


setTicketFields method

Description The setTicketFields method sets ticket data in Skybox. You can use it with all ticket types.

Note: This method and getTicketFields translate between the external ticket ID and the Skybox ticket ID. All other methods use the Skybox ticket ID.

Syntax setTicketFields (ticketIdType, ticketId, ticketField)



Parameters The parameters of the setTicketFields method are described in the following table.


ticketIdType String Specifies whether the ticket ID is the Skybox ticket ID or the ID from the external ticketing system Possible values: • SBV • EXTERNAL


ticketField Array of TicketField (see page 317)


setTicketPhases method

Description The setTicketPhases method sets the list of phases for the specified ticket.

The method overwrites the existing list. Retrieve the original list (using getTicketPhases (on page 236)), make the changes (usually due dates and assignees for phases), and then use this method to send the updated list back to Skybox.

Syntax setTicketPhases (ticketId, Phases, phaseOperation)

Parameters The parameters of the setTicketPhases method are described in the following table.



Phases Array of Phase (see page 307)



updateAccessChangeTicket method

Description The updateAccessChangeTicket method makes changes to an Access Change ticket.



The method overwrites the existing ticket. To add fields or update field values, retrieve the original ticket (using getAccessChangeTicket (on page 222)), make the changes, and then use this method to send the updated ticket back to Skybox.

Note: There are separate methods for updating attachments, phases, events, and change requests.

Syntax ticket = updateAccessChangeTicket (accessChangeTicket)

Parameters The parameter of the updateAccessChangeTicket method is described in the following table.


accessChangeTicket


Make any necessary changes.

Result The method returns an updated Access Change ticket data structure (see page 259).

USING THE TICKETS API Use the following URLs to view or access the Tickets web service (<Skybox server> is the name or IP address of your Skybox Server):

› Endpoint address: https://<Skybox server>:8443/skybox/webservice/jaxws/tickets

› WSDL: {http://skyboxsecurity.com}SkyboxTicketsService



Sample workflow for bidirectional ticket integration 1 Use getEvents (on page 170) to read Skybox events.

2 Filter the output for relevant events.

3 For each ticket created in Skybox:

a. Create a ticket in the external ticketing system and remember the external ticket ID.

b. Use setTicketFields (on page 245) to set the External ID field in the Skybox ticket.

If this field is set, ticket update events from Skybox include the external ticket ID.

c. (Optional) Use setTicketFields (on page 245) to set the External Ticket Status field in the Skybox ticket.



d. If you get a ticket update event from Skybox and the external ID is missing, it might mean that an update event in Skybox occurred before the external ID was set. If this happens, use getTicketFields (on page 235) to reread the external ID from the external ticketing system.

Sample workflow for creating an Access Change ticket The following is a typical scenario for creating a ticket that describes a network change request in Skybox. The starting point is a request for access that includes the source, destination and port for the requested access.

1 Use createChangeManagerTicket (on page 216) to pass the parameters for creation of a Skybox ticket describing the change request.

The information passed is metadata, including workflow, title, owner, priority, and due date. Information about the change request is only passed after the ticket is created.

2 Decide whether you are working at the network level or on a firewall-by-firewall basis.

• To work at the firewall level, call expandFirewallsForAccessChangeTicket (on page 219). This method checks the firewalls for source-port-destination and expands the list of change requests so that each change request includes firewall-source-destination-port for each relevant firewall.

3 Use updateAccessChangeTicket (on page 246) to pass the change request.

4 Call analyzeAccessChangeTicket (on page 215) to check connectivity and policy compliance; the result is in the relevant fields of each change request.

To work at the network level, find and complete the network elements for the source and destination, as explained in findNetworks (on page 196).


Chapter 12

This chapter describes the Vulnerabilities API, which retrieves Vulnerability Definitions, vulnerability occurrences, and threat alert tickets from Skybox.

The Vulnerabilities API enables you to retrieve Vulnerability Definitions, vulnerability occurrences, and threat alert tickets from Skybox. For each Vulnerability Definition, you can retrieve its details, instances, and tickets.

You can use the API to check whether the new and updated Vulnerability Definitions occur within your organization, or to check if the updated Vulnerability Definitions already have open tickets.

In this chapter

Vulnerabilities API methods ................................................. 249

Using the Vulnerabilities API ................................................ 254

VULNERABILITIES API METHODS The methods in the Vulnerabilities web service are described in the following table.

Method Description

countVulnerabilities (on page 250)

Counts the number of vulnerability occurrences that match the specified filter. This method is used for page calculations.

countVulnerabilityTypes (on page 250)

Counts the number of Vulnerability Definitions that match the specified filter. This method is used for page calculations.

countVulnerabilityTypeTickets (on page 251)

Counts the number of threat alert tickets that match the specified filter. This method is used for page calculations.

getVulnerabilitiesV1 (on page 251)

Retrieves a list of vulnerability occurrences that match the specified filter.

getVulnerabilityTypeByIdV4 (on page 252)

Returns a threat alert that matches the specified ID. This method returns CVSS information: • CVSS V3 for vulnerabilities published from Jan 1,

2016 • CVSS V2 for vulnerabilities published until Dec 31,

2015 Information about the threat alert includes the date on which it was reported.

Vulnerabilities API



Method Description

getVulnerabilityTypesV4 (on page 253)

Returns a list of threat alerts that match the search criteria. Each threat alert can be a Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses: • CVSS V3 for vulnerabilities published from Jan 1,

2016 • CVSS V2 for vulnerabilities published until Dec 31,

2015 getVulnerabilityTypeTickets (on page 253)

Retrieves a list of threat alert tickets that match the specified filter.



countVulnerabilities method

Description The countVulnerabilities method counts the number of vulnerability occurrences that match the specified filter. The output is used for page calculations. The method works in conjunction with getVulnerabilitiesV1 (see page 251), which returns the vulnerability occurrences.

Syntax numVuls = countVulnerabilities (filter)

Parameters The parameter of the countVulnerabilities method is described in the following table.


filter VulnerabilitySearchFilter (see page 321)

The set of vulnerability occurrences that are returned.

Result The method returns an integer representing the number of vulnerability occurrences that match the search criteria.

countVulnerabilityTypes method

Description The countVulnerabilityTypes method counts the number of Vulnerability Definitions that match the specified filter. The output is used for page calculations. The method works in conjunction with getVulnerabilityTypes, which returns the Vulnerability Definitions.

Syntax numVulTypes = countVulnerabilityTypes (filter)

Chapter 12 Vulnerabilities API


Parameters The parameter of the countVulnerabilityTypes method is described in the following table.


filter VulnerabilityTypeSearchFilterV2 (see page 324)

The set of Vulnerability Definitions that are returned.

Result The method returns an integer representing the number of Vulnerability Definitions that match the search criteria.

countVulnerabilityTypeTickets method

Description The countVulnerabilityTypeTickets method counts the number of threat alert tickets for Vulnerability Definitions that have the IDs specified in the filter. The output is used for page calculations. The method works in conjunction with getVulnerabilityTypeTickets (see page 253), which returns the tickets.

Syntax numTickets = countVulnerabilityTypeTickets (filter)

Parameters The parameter of the countVulnerabilityTypeTickets method is described in the following table.


filter VulnerabilityTypeIdFilter (see page 324)

Result The method returns an integer representing the number of tickets that match the search criteria.

getVulnerabilitiesV1 method

Description The getVulnerabilitiesV1 method returns an array containing all the vulnerability occurrences that match the search criteria. Event history is included for each vulnerability occurrence.

We recommend that you use countVulnerabilities (on page 250) to count the number of vulnerability occurrences for display purposes and then run getVulnerabilitiesV1.

Syntax matchingVuls = getVulnerabilitiesV1 (filter, subRange)



Parameters The parameters of the getVulnerabilitiesV1 method are described in the following table.


filter VulnerabilitySearchFilter (see page 321)

The set of vulnerability occurrences that are returned.


The range of vulnerability occurrences to return from the list of Vulnerability Definitions that match the filter criteria.

Result The method returns an array of VulnerabilityV1 data structures (on page 320) sorted by ID.

getVulnerabilityTypeByIdV4 method

Description The getVulnerabilityTypeByIdV4 method returns a threat alert that matches the specified ID. This method returns CVSS information in the appropriate version:

› CVSS V3 for vulnerabilities published from Jan 1, 2016 › CVSS V2 for vulnerabilities published until Dec 31, 2015

Information about the threat alert includes the date on which it was reported.

Syntax vulType = getVulnerabilityTypeByIdV4 (vulnerabilityTypeId, cvssNullIndication)

Parameters The parameters of the getVulnerabilityTypeByIdV4 method are described in the following table.


vulnerabilityTypeId

VulnerabilityTypeIdV1 (on page 324)

Specifies the ID of the Vulnerability Definition to return.

cvssNullIndication Boolean If there is no valid value for any of the following CVSS Base Score properties, returns null instead of N\A: • Access Vector (AV) • Access Complexity (AC) • Authentication (Au) • Confidentiality Impact (C) • Integrity Impact (I) • Availability Impact (A)

Result The method returns the VulnerabilityTypeV4 (on page 322) threat alert that has the specified ID.



getVulnerabilityTypesV4 method

Description The getVulnerabilityTypesV4 method returns a list of threat alerts that match the search criteria. Each threat alert can be a Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses:

› CVSS V3 for vulnerabilities published from Jan 1, 2016 › CVSS V2 for vulnerabilities published until Dec 31, 2015

We recommend that you use countVulnerabilityTypes (on page 250) to count the number of Vulnerability Definitions for display purposes and then run getVulnerabilityTypesV4.

Syntax vulTypes = getVulnerabilityTypesV4 (filter, subRange, cvssNullIndication)

Parameters The parameters of the getVulnerabilityTypesV4 method are described in the following table.


filter VulnerabilityTypeSearchFilterV2 (see page 324)

The set of Vulnerability Definitions that are returned.


The range of Vulnerability Definitions to return from the list of Vulnerability Definitions that match the filter criteria.

cvssNullIndication Boolean If there is no valid value for any of the following CVSS Base Score properties in a Vulnerability Definition, returns null instead of N\A: • Access Vector (AV) • Access Complexity (AC) • Authentication (Au) • Confidentiality Impact (C) • Integrity Impact (I) • Availability Impact (A)

Result The method returns an array of VulnerabilityTypeV4 data structures (on page 322) sorted by ID.

getVulnerabilityTypeTickets method

Description The getVulnerabilityTypeTickets method returns an array containing all the threat alert tickets for Vulnerability Definitions that match the search filter (of catalog and IDs).

We recommend that you use countVulnerabilityTypeTickets (on page 251) to count the number of threat alert tickets for display purposes and then run getVulnerabilityTypeTickets.



Syntax tickets = getVulnerabilityTypeTickets (vulnerabilityTypeId)

Parameters The parameter of the getVulnerabilityTypeTickets method is described in the following table.


vulnerabilityTypeId

VulnerabilityTypeIdFilter (see page 324)

Specifies the IDs of the Vulnerability Definitions that are returned.

Result The method returns an array of VulnerabilityTypeTicket data structures (see page 326) for Vulnerability Definitions with the specified IDs.

USING THE VULNERABILITIES API Use the following URL to view or access the Vulnerabilities web service (<Skybox server> is the name or IP address of your Skybox Server):

› Endpoint address: https://<Skybox server>:8443/skybox/webservice/jaxws/vulnerabilities

› WSDL: {http://skyboxsecurity.com}SkyboxVulnerabilitiesService



Sample workflow for vulnerabilities

Workflow for retrieving Vulnerability Definitions and their related tickets and vulnerability occurrences 1 Use countVulnerabilityTypes (on page 250) to find the number of Vulnerability

Definitions that match your filter criteria.

2 Use getVulnerabilityTypesV4 (on page 253) to retrieve the Vulnerability Definitions that match your filter criteria. Depending on the number of Vulnerability Definitions found at the previous step, you might need to retrieve the Vulnerability Definitions by chunks (using the subRange object).

3 Go over the list of Vulnerability Definitions and use their IDs as input to getVulnerabilityTypeTickets (on page 253) to retrieve all matching tickets of the retrieved Vulnerability Definitions.

4 Use the Vulnerability Definition IDs from the previous step as input to countVulnerabilities (on page 250) to find the number of vulnerability occurrences that match the retrieved Vulnerability Definitions.

5 Use the Vulnerability Definition IDs from the previous step as input to getVulnerabilitiesV1 (on page 251) to retrieve all vulnerability occurrences of the retrieved Vulnerability Definitions. Depending on the number of vulnerability occurrences found at the previous step, you might need to retrieve them by chunks (using the subRange object).



Workflow for retrieving vulnerability occurrences and their related Vulnerability Definitions 1 Use countVulnerabilities (on page 250) to find the number of vulnerability

occurrences that match your filter criteria.

2 Use getVulnerabilitiesV1 (on page 251) to retrieve the vulnerability occurrences that match your filter criteria. Depending on the number of vulnerability occurrences found at the previous step, you might need to retrieve them by chunks (using the subRange object).

3 Use getVulnerabilityTypeByIdV4 (on page 252) to retrieve all data related to the Vulnerability Definitions of the retrieved vulnerability occurrences.


Chapter 13

This code shows an example of connecting to a Skybox web service. The client stubs were generated by wsimport from WSDL and the client is using Apache CXF JAX-WS.

Note: For information about wsimport, see https://docs.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html

HttpServiceParameters sp = new HttpServiceParameters(); sp.setUsername("<user name>"); sp.setPassword("<password>"); SkyboxVulnerabilities sv = new SkyboxVulnerabilitiesService().getSkyboxVulnerabilitiesPort(); HttpUtils.initWebService(sv, "https://127.0.0.1:8443/skybox/webservice/jaxws/vulnerabilities ", null, sp, false, true, null); public class HttpProxyParameters implements Serializable { private String proxyHost; private int proxyPort; private String proxyUsername; private String proxyPassword; private String proxyNTLMDomain; private String proxyNTLMClientHostName; private String nonProxyHosts; } public class HttpServiceParameters implements Serializable { private String username; private String password; private boolean maintainSession; } import javax.net.ssl.HostnameVerifier; import javax.net.ssl.SSLSession; import javax.net.ssl.TrustManager; import javax.net.ssl.X509TrustManager; import javax.xml.namespace.QName; import javax.xml.ws.BindingProvider; import javax.xml.ws.Service; import org.apache.cxf.common.logging.Log4jLogger; import org.apache.cxf.common.logging.LogUtils; import org.apache.cxf.configuration.jsse.TLSClientParameters; import org.apache.cxf.configuration.security.AuthorizationPolicy; import org.apache.cxf.configuration.security.ProxyAuthorizationPolicy; import org.apache.cxf.endpoint.Client; import org.apache.cxf.frontend.ClientProxy; import org.apache.cxf.headers.Header; import org.apache.cxf.interceptor.LoggingInInterceptor; import org.apache.cxf.interceptor.LoggingOutInterceptor; import org.apache.cxf.transport.http.HTTPConduit;

API code example

https://docs.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html

Chapter 13 API code example


import org.apache.cxf.transports.http.configuration.HTTPClientPolicy; public class HttpUtils { public static HostnameVerifier getTrustingHostnameVerifier() { return new HostnameVerifier() { @Override public boolean verify(String hostname, SSLSession session) { return true; } }; } public static TrustManager[] getTrustingTrustManagers() { return new TrustManager[] { new X509TrustManager() { public java.security.cert.X509Certificate[] getAcceptedIssuers() { return null; } public void checkClientTrusted(java.security.cert.X509Certificate[] certs, String authType) { } public void checkServerTrusted(java.security.cert.X509Certificate[] certs, String authType) { } } }; } public static TLSClientParameters getTrustingTLSClientParameters() { TLSClientParameters tlscp = new TLSClientParameters(); tlscp.setDisableCNCheck(true); tlscp.setTrustManagers(getTrustingTrustManagers()); tlscp.setHostnameVerifier(getTrustingHostnameVerifier()); return tlscp; } public static void initWebService(Object webServicePort, String url, HttpProxyParameters pp, HttpServiceParameters sp, boolean validateCertificate, boolean debug, List<Header> headers) { BindingProvider bp = (BindingProvider) webServicePort; Client client = ClientProxy.getClient(webServicePort); HTTPConduit httpConduit = (HTTPConduit) client.getConduit(); if (debug) { LogUtils.setLoggerClass(Log4jLogger.class); client.getInInterceptors().add(new LoggingInInterceptor()); client.getOutInterceptors().add(new LoggingOutInterceptor()); } if (!validateCertificate) httpConduit.setTlsClientParameters (HttpUtils.getTrustingTLSClientParameters()); HTTPClientPolicy cp = new HTTPClientPolicy(); cp.setConnectionTimeout(150000); cp.setReceiveTimeout(150000); if (pp != null) { if ((pp.getProxyHost() != null) && !pp.getProxyHost().isEmpty()) { cp.setProxyServer(pp.getProxyHost()); cp.setProxyServerPort(pp.getProxyPort());



} if ((pp.getNonProxyHosts() != null) && !pp.getNonProxyHosts().isEmpty()) cp.setNonProxyHosts(pp.getNonProxyHosts()); } httpConduit.setClient(cp); if ((sp != null) && (sp.getUsername() != null)) { AuthorizationPolicy ap = new AuthorizationPolicy(); ap.setAuthorizationType("Basic"); ap.setUserName(sp.getUsername()); ap.setPassword(sp.getPassword()); httpConduit.setAuthorization(ap); //bp.getRequestContext().put (BindingProvider.USERNAME_PROPERTY, "<user name>"); //bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "<password>"); } if ((pp != null) && (pp.getProxyUsername() != null) && !pp.getProxyUsername().isEmpty()) { ProxyAuthorizationPolicy pap = new ProxyAuthorizationPolicy(); pap.setUserName(pp.getProxyUsername()); pap.setPassword(pp.getProxyPassword()); httpConduit.setProxyAuthorization(pap); } if (sp != null) bp.getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, sp.getMaintainSession()); if (url != null) { httpConduit.getTarget().getAddress().setValue(url); bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, url); } if ((headers != null) && !headers.isEmpty()) bp.getRequestContext().put(Header.HEADER_LIST, headers); } }


Chapter 14

This chapter defines the data structures used in the Skybox web services.

In this chapter

Data structures: A to C ....................................................... 259

Data structures: D to H ...................................................... 280

Data structures: I to R ....................................................... 300

Data structures: S to Z ....................................................... 314

DATA STRUCTURES: A TO C AccessChangeTicket data structure

The fields of the AccessChangeTicket data structure are listed in the following table.

Field Type Comments

id Integer Read-only

comment String

description String

creationTime Date Read-only

lastModificationTime

Date Read-only

createdBy String Read-only

lastModifiedBy String Read-only

externalTicketId String

externalTicketStatus

String Possible values: • Pending • Open • Closed • Error • Rejected

status String Possible values: • New • InProgress • Resolved • Closed • Rejected • Ignored • Verified • Reopened • Demoted

title String

Data structures



Field Type Comments

changeDetails String

priority String Possible values: • P1 • P2 • P3 • P4 • P5

owner String

dueDate Date

doneDate Date Read-only

likelihood String Possible values: • Unknown • Low • Medium • High • Priority • Critical

ccList Array of EmailRecipient (see page 281)

customFields Array of CustomField (see page 278)

AccessQueryElement data structure The fields of the AccessQueryElement data structure are listed in the following table.

Field Type Comments

destinationAddresses

Address elements

An array of address elements to use as the destination of the query.

destinationElements

Array of NetworkElement (see page 305)

Mandatory for network-context analysis; null for firewall-context analysis. Each network entity consists of a network IP address and a network ID in the model that you can find using findNetworks (on page 196).

firewall Empty or Firewall Name or Firewall ID

Mandatory for firewall-context analysis; null for network-context analysis. Use findFirewalls (on page 193) to get this entity.

mode Integer Specifies whether the answer is to include accessible or inaccessible paths. • 0: Accessible • 1: Inaccessible • 2: Both

Chapter 14 Data structures


Field Type Comments

ports Port list A list of ports (also referred to as services) to use in the query.

sourceAddresses Address elements

An array of address elements to use as the source of the query

sourceElements Array of NetworkElement (see page 305)

Mandatory for network-context analysis; null for firewall-context analysis. Each network entity consists of a network IP address and a network ID in the model that you can find using findNetworks (on page 196).

The AccessQueryElementV2 (on page 261) data structure is an extension to the AccessQueryElement data structure.

AccessQueryElementV2 data structure The AccessQueryElementV2 data structure is an extended version of the AccessQueryElement (see page 260) data structure that enables you to specify whether Skybox takes access and routing rules into consideration when checking access.

The additional fields of the AccessQueryElementV2 data structure (that is, fields that are not included in the AccessQueryElement data structure) are listed in the following table.

Field Type Comments

useAccessRules Integer Possible values: • 0: Use All • 1: Ignore All Rules • 2: Use Only NAT Rules

useRoutingRules Integer Possible values: • 0: Ignore All Rules • 1: Ignore Dynamic Rules Only • 2: Use All

The AccessQueryElementV3 (on page 261) data structure is an extension to the AccessQueryElementV2 data structure.

AccessQueryElementV3 data structure The AccessQueryElementV3 data structure is an extended version of the AccessQueryElementV2 (see page 261) data structure that enables you to specify how many routes per service and destination addresses and ports for the query.

The additional fields of the AccessQueryElementV3 data structure (that is, fields that are not included in the AccessQueryElementV2 data structure) are listed in the following table.

Field Type Comments

routesPerService Integer (Optional) Possible values: 1, 10, 20, or 50

sendTo SendToElement (on page 314)

(Optional) Destination address and ports



AccessRequest data structure The fields of the AccessRequest data structure are listed in the following table.

Field Type Comments

id Integer

comment String

description String

creationTime Date


Date

createdBy String

lastModifiedBy String

accessType String

accessQuery AccessQueryElement (see page 260)

accessStatus String Possible values: • UNCOMPUTED • ACCESSIBLE • UNACCESSIBLE • ERROR

sourceZones String List of zone names

destinationZones String List of zone names

complianceStatus String Possible values: • UNCOMPUTED • YES • NO • ERROR

complianceViolations

Array of ComplianceViolationElement (see page 277)

potentialVulnerabilities

Array of PotentialVulnerability (see page 309)

isDisabled Boolean

accessQueryMode String Possible values: • FirewallMode • NetworkMode

The ExtendedAccessRequest (on page 288) data structure is an extension to the AccessRequest data structure.



AccessResultElement data structure The fields of the AccessResultElement data structure are listed in the following table.

Field Type Comments

auth String

destination String

network NetworkElement (see page 305)

ports String

source String

AccessRuleElementV4 data structure The fields of the AccessRuleElementV4 data structure are listed in the following table.

Field Type Comments

id Integer The ID of the access rule.

action Integer Possible values: • 0: Undefined • 1: Allow • 2: Deny • 3: Translate • 4: IPS

comment String

destinationAddresses Array of String Addresses are resolved to ranges.

description String

direction Integer Possible values: • 0: Undefined • 1: Inbound • 2: Outbound • 3: Both

disabled Integer Possible values: • 0: False • 1: True

firewall FirewallElement (see page 294)

The name or ID of the firewall.

globalUniqueId String The GUID of the access rule.

implied Integer Possible values: • 0: False • 1: True

isAuthenticated Integer Possible values: • 0: False • 1: True

netInterfaces Array of String

orgDestinationText String The original text in the destination field.



Field Type Comments

id Integer The ID of the access rule.

orgPortsText String The original text in the services field.

orgRuleNumber String The original rule ID as taken from device.

orgRuleText String The text (definition) of the access rule as taken from the device.

orgSourceText String The original text in the source field.

ports Array of String Services resolved to object names, in the form of 80/TCP or 80-80/TCP.

ruleChain String The name of the rule chain.

sbOrder Integer The order of the rule in its chain.

services Array of String The services (ports) used by the rule.

sourceAddresses Array of String Addresses are resolved to ranges.

sourceNetworkInterfaces

Array of String

translatedDestinations

Array of String

translatedServices Array of String

translatedSources Array of String

userUsage String Possible values: • ANY • KNOWNUSER • UNKNOWN • SELECT

users Array of String Array of user names

AccessRuleSearchFilter data structure The fields of the AccessRuleSearchFilter data structure are listed in the following table.

Field Type Comments

description String (Optional) The description of the access rule.

destination (Optional) An IP address list or range, or object names, comma-separated. Notes: • Numbers that are not IP addresses

are used to search for object names.

• You can use the wildcard * in IP address searches (for example, 192.*).

findMode String (Mandatory) Possible values: • AND (all fields) • OR (any field)



Field Type Comments

firewallScope FWScope (see page 298)

The list of firewalls to include in the search scope. The default value is All.

ignoreRulesWithAny Boolean The default value is true.

matchCriteria String (Optional) This field is only relevant for numeric searches, not character searches. Possible values: • Contained within • Entire field match • Exact match • Intersection

originalRuleId (Optional) The original rule ID of the access rule.

originalText (Optional) The original text of the access rule.

services String (Optional) A list of ports and protocols or service object names, comma-separated. Each set must have the format: port[/protocol]. Note: If you provide only the port number, the default protocol is TCP.

source String (Optional) An IP address list or range, or object names, comma-separated. Notes: • Numbers that are not IP addresses

are used to search for object names.

• You can use the wildcard * in IP address searches (for example, 192.*).

AccessRulesResponse data structure The fields of the AccessRulesResponse data structure are listed in the following table.

Field Type Comments

accessRuleIds Array of Integer

results Array of String

AccessRulesByFwResponse data structure The fields of the AccessRulesByFwResponse data structure are listed in the following table.

Field Type Comments

hostId Integer

originalRuleIds Array of String




ACLRuleHistoryFilter data structure The fields of the ACLRuleHistoryFilter data structure are listed in the following table.

Field Type Comments

ChangeTime DateRange (see page 280)

The time frame for which to search for access rule history records.

AddRuleChangeRequestV7 data structure The AddRuleChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Add Rule change requests.

The additional fields of the AddRuleChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments

applications Array of FirewallObjectIdentification (see page 295)

Applications for the rule.

createAfter String Where in the ACL to create the rule.


Array of String Destination addresses for the rule.

destinationObjects

Array of FirewallObjectIdentification (see page 295)

Destination objects for the rule.

expirationDate Date (Check Point firewalls only) Sets the expiration date for the rule.

firewall Asset (see page 269)

The name or ID of the firewall to which to add the access rule.

hideSourceBehindGW

Boolean Specifies whether to hide the source behind the gateway address. If ON, the NATSourceAddresses and NATSourceObjects are ignored.

implementBeforeAccessRule

SlimAccessRule (see page 315)

Specifies the access rule before which to add the rule from this change request.

implementingAccessRules

Array of SlimAccessRule (see page 315)

isDestinationNegated

Boolean Specifies whether to negate the destination IP addresses (“all IP addresses except...”)

isInstallOnAny Boolean Specifies whether to add the requested change to all firewalls in the specified device group. Note: For Panorama only.



Field Type Comments

isLogEnabled Boolean Specifies whether to enable logging of the rule on the firewall.

isServicesNegated Boolean Specifies whether to negate the services (“all services except...”)

isSharedObject Boolean Specifies that all objects used by and created for this access rule are shared by all the firewalls managed by a specific device. Note: For Panorama only.

isSourceNegated Boolean Specifies whether to negate the source IP addresses (“all IP addresses except...”)

NATDestinationAddresses

Array of String Translated destination addresses for the rule.

NATDestinationObjects


Translated destination objects for the ne rule.

NATPortObjects Array of FirewallObjectIdentification (see page 295)

Translated port objects for the rule.

NATPorts Array of String Translated ports for the rule.

NATSourceAddresses

Array of String Translated source addresses for the rule.

NATSourceObjects


Translated source objects for the rule.

portObjects Array of FirewallObjectIdentification (see page 295)

Port objects for the rule.

ports String Ports for the rule.


Business attributes for the rule.

ruleGroup String The rule group to which to add the rule.

ruleType String

securityProfileGroup

securityProfileGroup

Specifies the security profile group to use for the rule.

sourceAddresses Array of String Source addresses for the rule.

sourceObjects Array of FirewallObjectIdentification (see page 295)

Source objects for the rule.



Field Type Comments

useApplicationDefaultPorts

Boolean Specifies whether to use the default ports of the applications as the ports for the change request.

userUsage String

users Array of String

vpn String Describes the VPN (if a VPN exists), for the rule.

Analysis data structure The fields of the Analysis data structure are listed in the following table.

Field Type Comments

id Integer

name String

type Possible values: • Business Assets • Hosts • Vulnerabilities • Threat Origins • Locations • Regulation Compliance • Tickets • Networks • Access • Worms • Network Interfaces

path String The full path from the root directory to this analysis.

ApplicationConfigurationItem data structure The ApplicationConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 270) used for items containing a list of IP address ranges.

The additional fields of the ApplicationConfigurationItem data structure (that is, the fields that are not in the BaseConfigurationItem data structure) are listed in the following table.

Field Type Comments

ipRanges Array of String

ApplicationGroupConfigurationItem data structure The ApplicationGroupConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 270) used for groups of ApplicationConfigurationItem (see page 268). The structure holds the names of the members and the sum of all their IP address ranges.

The additional fields of the ApplicationGroupConfigurationItem data structure (that is, fields that are not included in the BaseConfigurationItem data structure) are listed in the following table.



Field Type Comments


memberNames Array of String

Asset data structure The fields of the Asset data structure are listed in the following table.

Field Type Comments

id Integer The ID of the asset

name String The asset name

type Possible values: • Firewall • Router • LoadBalancer • Proxy • NetworkDevice • WirelessDevice • IPS • Switch

primaryIP IP The primary IP address of the asset

netInterfaces List of NetInterfaces (see page 304)

The network interfaces of the asset

status The status of the asset: • Up • Down • Not Found • Unknown

osVendor The asset operating system vendor

os The asset operating system

osVersion String The version of the asset operating system

interfaces Integer The number of network interfaces on this asset

accessRules Integer The number of access rules in the asset

routingRules Integer The number of routing rules in this asset

services Integer The number of services in this asset

vulnerabilities Integer The number of vulnerability occurrences on the asset

Attachment data structure The fields of the Attachment data structure are listed in the following table.

Field Type Comments

id Integer



Field Type Comments

comment String

description String

creationTime Date


Date

createdBy String


owner String

filename String

phaseName String The name of the phase in which the attachment was created.

destinationFileName

String

attachmentExists Boolean

attachmentSizeInBytes

Long

BaseConfigurationItem data structure The fields of the BaseConfigurationItem data structure are listed in the following table.

Note: The BaseConfigurationItem data structure is an abstract data structure.

Field Type Comments

enabled Boolean

id Integer

name String

The following data structures are extensions to the BaseConfigurationItem data structure:

› ApplicationConfigurationItem (on page 268) › ApplicationGroupConfigurationItem (on page 268) › ServiceConfigurationItem (on page 314) › ServiceGroupConfigurationItem (on page 314)

BlockAccessChangeRequestV7 data structure The BlockAccessChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Access Update (block access) change requests.

The additional fields of the BlockAccessChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.



Field Type Comments


Array of String Destination addresses to block in the rule.

destinationObjects


Destination objects to block in the rule.


Port objects to block in the rule.

ports String Ports to block in the rule.



sourceAddresses Array of String Source addresses to block in the rule.


Source objects to block in the rule.

ChangeLog data structure The fields of the ChangeLog data structure are listed in the following table.

Field Type Comments

Date Date The date of the change log entry.

Text String The content of the change log entry.

ChangeRequestV3 data structure The fields of the ChangeRequestV3 data structure are listed in the following table.

Note: The ChangeRequestV3 data structure is an abstract data structure.

Field Type Comments

comment String

complianceStatus String Possible values: • UNCOMPUTED • YES • NO • ERROR

createdBy String

creationTime Date

description String

id Integer

isRequiredStatus String Possible values: • UNCOMPUTED • YES (change required) • NO (already permitted)



Field Type Comments • Computing • ERROR

lastModificationTime Date


messages Array of ChangeRequestMessage (on page 274)

Messages for the user about the change request that was calculated by the Skybox Server. For example, the change request cannot be calculated because the source and destination are behind the same interface; there is no firewall matching the request; or the request is a duplicate of another request in the ticket.

originalChangeRequestId

Integer The ID number of the original change request, when relevant.

verificationStatus String Possible values: • Verified • Not Verified • Error • Computing • Unknown

The following data structures are extensions to the ChangeRequestV3 data structure:

› AddRuleChangeRequestV7 (on page 266) › BlockAccessChangeRequestV7 (on page 270) › DeactivateRuleChangeRequestV7 (on page 280) › DeleteObjectChangeRequestV7 (on page 280) › ModifyObjectChangeRequestV7 (on page 301) › ModifyRulesChangeRequestV7 (on page 301) › ReactivateRuleChangeRequestV7 (on page 309) › RecertifyChangeRequestV7 (on page 310) › RequireAccessChangeRequestV7 (on page 310)

ChangeRequestComplianceViolationElement data structure The fields of the ChangeRequestComplianceViolationElement data structure are listed in the following table.

Field Type Comments

aprId Integer

aprName String

aprPath String

destinationNetInterfaces

Array of NetInterfaceElement (see page 304)



Field Type Comments

destinationNetworks

Array of NetworkElement (see page 305)

firewalls String

importance String Possible Values: • 0=Very Low • 1=Low • 2=Medium • 3=High • 4=Critical

new Boolean

sourceNetInterfaces

Array of NetInterfaceElement (see page 304)

sourceNetworks Array of NetworkElement (see page 305)

ChangeRequestImplementation data structure The fields of the ChangeRequestImplementation data structure are listed in the following table.

Field Type Comments

id Integer The ID of the change request

ticketId Integer The ID of the change request ticket

dueDate Date The due date of the change request

ticketPriority String Possible values: • P1 • P2 • P3 • P4 • P5

changeType String The type of the change request

firewallName String The name of the firewall on which to make the change

firewallManagementName

String The name of the firewall management on which to make the change

objectId String The ID of the object to change

globalUniqueId String The GUID of the entity to change

changeDetails String

additionalDetails String

isRequiredStatus String Possible values: • UNCOMPUTED • YES (change required) • NO (already permitted)



Field Type Comments • Computing • ERROR

owner String The owner of the change request

completeStatus String

completeDate Date

workflowName String

comment String

lastModificationTime Date

implementationStatus String

ChangeRequestMessage data structure The fields of the ChangeRequestMessage data structure are listed in the following table.

Field Type Comments

args String

formatedMessage String

key String

level String Possible values: • INFO • WARN • ERROR

ChangeRequestPotentialVulnerability data structure The fields of the ChangeRequestPotentialVulnerability data structure are listed in the following table.

Field Type Comments

catalogId String

cveId String

fixCount Integer

hostNames String

new Boolean

reportedDate Date

serviceName String

servicePorts String

severityLevel String

severityScore Float

title String

vulDefId Integer



CheckAccessComplianceRequest data structure The fields of the CheckAccessComplianceRequest data structure are listed in the following table.

Field Type Comments

Source Address (Optional) Used to find Access Checks that are limited by the source field.

Source Zone Zone name Use getZoneFromNetwork (on page 203) or getZoneFromFW (on page 203) with the specified source as the input to get the source zone.

Destination Address

(Optional) Used to find Access Checks that are limited by the destination field.

Destination Zone Zone name Use getZoneFromNetwork (on page 203) or getZoneFromFW (on page 203) with the specified destination as the input to get the destination zone.

Port Port

Firewall Firewall name or firewall ID

The name or ID of the firewall in the model. Use findFirewalls (on page 193) to get this entity. When working with Skybox Network Assurance, leave this field empty.

CheckAccessComplianceResponse data structure The fields of the CheckAccessComplianceResponse data structure are listed in the following table.

Field Type Comments

complianceStatus Integer Possible values: • 0: Compliant • 1: Non-compliant • 2: Not resolved

violations Array of ComplianceViolationElement (see page 277)

CheckAccessResult data structure The fields of the CheckAccessResult data structure are listed in the following table.

Field Type Comments

accessible Array of AccessResultElement (on page 263)

List of accessible IP addresses (source, destination, ports, and authentication).

inaccessible Array of AccessResultElement (on page 263)

List of inaccessible IP addresses (source, destination, ports, and authentication).



Field Type Comments

route String The 1st route describing the path between the source and the destination. Note: If the result contains multiple accessible or inaccessible source-destination-port sets, there might be multiple routes; the result field contains the 1st set. To get more routes, call the method again with the relevant accessible or inaccessible row as the query.

status ReturnStatus (see page 312)

CheckRuleComplianceRequest data structure The fields of the CheckRuleComplianceRequest data structure are listed in the following table.

Field Type Comments

sourceAddress Address list or range, comma-separated. To check rule compliance using any source, set this field to Any.

destinationAddress

Address list or range, comma-separated. To check rule compliance using any destination, set this field to Any.

port Port Port list or range, comma-separated.

rulePolicy String (Optional) The name of the Rule Policy (1 policy per request).

firewallId Firewall ID For future versions.

CheckRuleComplianceResponse data structure The fields of the CheckRuleComplianceResponse data structure are listed in the following table.

Field Type Comments

complianceStatus Integer Possible values: • 0: Compliant • 1: Non-compliant • 2: Not resolved

violations Array of RuleComplianceViolationElement (see page 313)

CollectorFileStoreInfo data structure The fields of the CollectorFileStoreInfo data structure are listed in the following table.



Field Type Comments

fileStores Array of FileStoreSpaceInfo (on page 288)

ipAddress String

name String

status Integer Possible values: • 0: Success • -1: Failure

CollectorUptimeInfo data structure The fields of the CollectorUptimeInfo data structure are listed in the following table.

Field Type Comments

ipAddress String

name String

status Integer Possible values: • 0: Success • -1: Failure (for example, if uptime=0)

uptime Integer Machine uptime in seconds

ComplianceViolationElement data structure The fields of the ComplianceViolationElement data structure are listed in the following table.

Field Type Comments

aprName String The name of the Access Check in Skybox

aprPath String The path of the Access Check in Skybox

importance Integer Possible values: • 0=Very Low • 1=Low • 2=Medium • 3=High • 4=Critical

portsViolating List of String

ConfigurationItemFilter data structure The fields of the ConfigurationItemFilter data structure are listed in the following table.

Field Type Comments

ancestorOf Array of Integer

childrenOf Array of Integer

configurationItemTypes

Array of String



Field Type Comments

freeTextFilter String

ids Array of Integer

ignoreEmptyGroups Boolean

isEnabled Boolean

nameFilter String

csvContent data structure The fields of the csvContent data structure are listed in the following table.

Field Type Comments

data base64Binary

csvReportFilter data structure The fields of the csvReportFilter data structure are listed in the following table.

Field Type Comments

recency Integer

reportName String

csvReportInfo data structure The fields of the csvReportInfo data structure are listed in the following table.

Field Type Comments

creationDate Date

fileName String

fileSize Long

CustomField data structure The fields of the CustomField data structure are listed in the following table.

Field Type Comments

id Integer

comment String

description String

creationTime Date


Date

createdBy String


name String

typeCode Integer

value String



CVSSV1 data structure The fields of the CVSSV1 data structure are listed in the following table.

Field Type Comments

AttackVector String Possible values: • NETWORK • LOCAL • ADJACENT_NETWORK • PHYSICAL • NULL

AttackComplexity String Possible values: • LOW • HIGH • NULL

PrivilegesRequired String Possible values: • NONE • LOW • HIGH • NULL

ConfidentialityImpact

String Possible values: • NONE • HIGH • LOW • NULL

cvssVersion String Possible values: • V2 • V3

IntegrityImpact String Possible values: • NONE • HIGH • LOW • NULL

AvailabilityImpact String Possible values: • NONE • HIGH • LOW • NULL

ExploitCodeMaturity

String Possible values: • UNPROVEN • HIGH • FUNCTIONAL • PROOF_OF_CONCEPT • NOT_DEFINED

RemediationLevel String Possible values: • OFFICIAL_FIX • TEMPORARY_FIX • WORKAROUND • UNAVAILABLE • NOT_DEFINED

ReportConfidence String Possible values: • CONFIRMED • REASONABLE • UNKNOWN • NOT_DEFINED



Field Type Comments

Scope String Possible values: • UNCHANGED • CHANGED

UserInteraction String Possible values: • NONE • REQUIRED

DATA STRUCTURES: D TO H DateRange data structure

The fields of the DateRange data structure are listed in the following table.

Field Type Comments

endDate Long In UNIX epoch format (including milliseconds)

startDate Long In UNIX epoch format (including milliseconds)

Note: You must give values for both fields.

DeactivateRuleChangeRequestV7 data structure The DeleteObjectChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Delete Object change requests.

The additional fields of the DeleteObjectChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments

object FirewallObjectIdentification (see page 295)

The object to delete.

DeactivateRuleChangeRequestV7 data structure The DeactivateRuleChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Deactivate Rule change requests.

The additional fields of the DeactivateRuleChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments

accessRules Array of SlimAccessRule (see page 315)

deactivationType String Possible values: • Disable Rule • Delete Rule



Field Type Comments


DoubleRange data structure The fields of the DoubleRange data structure are listed in the following table.

Field Type Comments

from Double

to Double

EmailRecipient data structure Email recipients can be identified by their Skybox user names or by explicit email addresses.

The fields of the EmailRecipient data structure are listed in the following table.

Field Type Comments

email String

userName String

EntityField data structure The fields of the EntityField data structure are listed in the following table.

Field Type Comments

dataType String

defId Integer

entityType String

id Integer

name String

value String

Event data structure The fields of the Event data structure are listed in the following table.

Field Type Comments

timestamp Date

id Integer So that users can request the returned information to start from a specific event

eventType Integer For a list of event types, see Event types (on page 282).

Parameters String List of parameters, including an ID (enum) and a text value for each parameter. For information about these parameters, see Event parameter enumerations (on page 282).



Event types The supported event types for the Events API are listed in the following table.

Event type Event name Code

Ticket creation SBVAPI_EVENT_TYPE_TICKET_CREATION 1

Ticket update SBVAPI_EVENT_TYPE_TICKET_UPDATE 2

Ticket deletion SBVAPI_EVENT_TYPE_TICKET_DELETE 3

Security Metric notification

SBVAPI_EVENT_TYPE_KPI_NOTIFICATION 4

Operational (for example, Server start and Server stop)

SBVAPI_EVENT_TYPE_OPERATIONAL 5

Task end SBVAPI_EVENT_TYPE_TASK 6

Firewall compliance violation notification

SBVAPI_EVENT_TYPE_APR_NOTIFICATION 7

Event parameter enumerations In the Events API, each event record is composed of different parameters according to the event type. Each parameter has its own name and code number. Some parameters are relevant to multiple event types. For example, the ticket ID is used for ticket creation events, ticket update events, and ticket deletion events.

Ticket creation parameters The values that are used for ticket creation events (Event type code = 1) are listed in the following tables.

Enums for ticket creation parameters

Description Event name Code Possible values

Ticket ID SBVAPI_EVENT_PARAM_TICKET_ID

1 Integer

External ID SBVAPI_EVENT_PARAM_TICKET_EXTERNAL_ID

2 Text

Title SBVAPI_EVENT_PARAM_TITLE 3 Text

Owner name SBVAPI_EVENT_PARAM_OWNER 4 Text

The most recent comment

SBVAPI_EVENT_PARAM_COMMENT

5 Text

Ticket priority SBVAPI_EVENT_PARAM_PRIORITY

6 • Critical • High • Medium • Low • Very Low

Ticket status SBVAPI_EVENT_PARAM_STATUS

7 • Closed • Ignored • In Progress • New • Rejected • Resolved • Verified



Description Event name Code Possible values • Reopened • Demoted

Due date SBVAPI_EVENT_PARAM_DUE_DATE

8 Date (MM/dd/yyyy)

Ticket type SBVAPI_EVENT_PARAM_TICKET_TYPE

9 • Vulnerability Occurrence

• Vulnerability Definition

• Business Asset Group

Ticket creation policy that created this ticket

SBVAPI_EVENT_PARAM_TICKET_RULE_NAME

36 • Text • Null if the

ticket was created manually

Additional enums for vulnerability occurrence ticket parameters


Vulnerability Definition ID

SBVAPI_EVENT_PARAM_VULN_ID

10 Text

Exposure level SBVAPI_EVENT_PARAM_EXPOSURE

11 • Direct • Indirect • Inaccessible • Unknown • Excluded • Potential • Protected

Risk level SBVAPI_EVENT_PARAM_RISK_LEVEL


Risk Score SBVAPI_EVENT_PARAM_RISK_SCORE

13 0-100

Severity SBVAPI_EVENT_PARAM_VULN_SEVERITY

14 • Critical • High • Medium • Low • Info • Unknown

Asset name SBVAPI_EVENT_PARAM_HOST_NAME

15 Text

Asset IP address SBVAPI_EVENT_PARAM_HOST_IP

16 IP address

Vulnerable service SBVAPI_EVENT_PARAM_HOST_SERVICE

17 Text

Selected Solutions SBVAPI_EVENT_PARAM_VULN_SELECTED_SOLUTIONS

54 Text

All Solutions SBVAPI_EVENT_PARAM_VULN_ALL_SOLUTION

55 Text



Additional enums for threat alert ticket parameters


Vulnerability Definition ID

SBVAPI_EVENT_PARAM_VULN_ID

10 Text

Severity SBVAPI_EVENT_PARAM_VULN_SEVERITY

14 • Critical • High • Medium • Low • Info • Unknown


54 Text


55 Text

Additional enums for Business Asset Group ticket parameters


The name of the Business Asset Group

SBVAPI_EVENT_PARAM_BUSINESS_ASSET_NAME

18 Text

The path of the Business Asset Group in your organization’s hierarchy

SBVAPI_EVENT_PARAM_BUSINESS_ASSET_PATH

19 Text: Path in the Business Unit hierarchy: • Levels are

separated by “/”

• Paths are separated by “,”

Risk level SBVAPI_EVENT_PARAM_RISK_LEVEL


Risk Score SBVAPI_EVENT_PARAM_RISK_SCORE

13 0-100

Additional enums for Policy Compliance ticket parameters


Access Check name

SBVAPI_EVENT_PARAM_APR_NAME

31 Text

Access Check path

SBVAPI_EVENT_PARAM_APR_PATH

32 Text: Path of the Access Check in the Access Policies folder hierarchy • Levels are

separated by “/”




The source scope of the violation

SBVAPI_EVENT_PARAM_TEST_SOURCE_SCOPE

33 Text

The destination scope of the violation

SBVAPI_EVENT_PARAM_TEST_DESTINATION_SCOPE

34 Text

The services checked for access between the source and the destination

SBVAPI_EVENT_PARAM_TEST_SERVICES

35 Text

The importance of the Access Check

SBVAPI_EVENT_PARAM_APR_IMPORTANCE

37 • Critical • High • Medium • Low • Info

Ticket update parameters The values that are used for ticket update events (Event type code = 2) are listed in the following table.



1 Integer


2 Text

Title SBVAPI_EVENT_PARAM_TITLE 3 Text

Owner name SBVAPI_EVENT_PARAM_OWNER 4 Text



5 Text

Ticket priority SBVAPI_EVENT_PARAM_PRIORITY


Ticket status SBVAPI_EVENT_PARAM_STATUS

7 • Closed • Ignored • In Progress • New • Rejected • Resolved • Verified • Reopened • Demoted

Due date SBVAPI_EVENT_PARAM_DUE_DATE

8 Date (MM/dd/yyyy)

Ticket type SBVAPI_EVENT_PARAM_TICKET_TYPE

9 • Vulnerability Occurrence

• Vulnerability Definition

• Business Asset Group





54 Text


55 Text

Ticket deletion parameters The values that are used for ticket deletion events (Event type code = 3) are listed in the following table.



1 Integer


2 Text

Security Metric notification parameters The values that are used for Security Metric notification events (Event type code = 4) are listed in the following table.


The name of the Business Asset Group

SBVAPI_EVENT_PARAM_BUSINESS_ASSET_NAME

18 Text

The type of the security metric

SBVAPI_EVENT_PARAM_KPI_TYPE

20 Text (RLI or VLI)

Whether the security metric for the Business Asset Group increased

SBVAPI_EVENT_PARAM_KPI_IS_INCREASE

21 • True • False

The new security metric level

SBVAPI_EVENT_PARAM_KPI_LEVEL

22 Text



5 Text

Operational event parameters The values that are used for operational events (Event type code = 5) are listed in the following table.


The event severity

SBVAPI_EVENT_PARAM_OPS_SEVERITY

23 • Fatal • Error • Warn • Debug • Trace

The event type (server start or stop, or error)

SBVAPI_EVENT_PARAM_OPS_MESSAGE

24 Text



Task end parameters The values that are used for task end events (Event type code = 6) are listed in the following table.


Task type SBVAPI_EVENT_PARAM_TASK_TYPE

25 Text (Skybox task type)

Task name SBVAPI_EVENT_PARAM_TASK_NAME

26 Text

Task start time SBVAPI_EVENT_PARAM_TASK_START_TIME

27 Date-Time

Task end time SBVAPI_EVENT_PARAM_TASK_END_TIME

28 Date-Time

Task exit code SBVAPI_EVENT_PARAM_TASK_EXIT_CODE

29 • Error • Fatal • Success • Success (No

Update) • Terminated • Time Out • Warning

Summary message provided by the task

SBVAPI_EVENT_PARAM_TASK_MESSAGE

30 Text

Access Check notification parameters The values that are used for Access Check (Access Compliance violation) notification events (Event type code = 7) are listed in the following table.


The ID of the violated access test

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_ID

38 Text

The importance of the Access Check

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_IMPORTANCE

39 • VERY_LOW • LOW • MEDIUM • HIGH • CRITICAL

The name of the firewall used in the access test

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_FIREWALL_NAME

40 Text

The IP address of the firewall used in the access test

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_FIREWALL_IP

41 Text

The name of the Access Check

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_APR_NAME

42 Text

The type of the Access Check

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_APR_TYPE

43 • ACCESS_QUERY

• SECURITY_ACCESS_RULE

• CONNECTIVITY_ACCESS_R



Description Event name Code Possible values ULE

• LIMITED_ACCESS_RULE

The path of the Access Check in the Access Policies tree

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_APR_PATH

44 Text

The source (taken from the Access Policy)

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_SOURCE

45 Text

The destination (taken from the Access Policy)

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_DESTINATION

46 Text

ExtendedAccessRequest data structure The ExtendedAccessRequest data structure is an extended version of the AccessRequest data structure (see page 262).

The additional fields of the ExtendedAccessRequest data structure (that is, fields that are not included in the AccessRequest data structure) are listed in the following table.

Field Type Comments

accessChangeTicket


ExternalCatalogId data structure The fields of the ExternalCatalogId data structure are listed in the following table.

Field Type Comments

Catalog String Possible values: • CVE • FoundScan • Nessus • nCircle • ISS • Cisco PSIRT • SecurityFocus • Rapid7 • Retina • OVAL • SBV • Oracle • Qualys • Adobe • Microsoft

Id String ID; external vulnerability database ID

FileStoreSpaceInfo data structure The fields of the FileStoreSpaceInfo data structure are listed in the following table.

Field Type Comments

name String

totalSize Long

unallocatedSize Long



FindAccessRulesResultV2 data structure The fields of the FindAccessRulesResultV2 data structure are listed in the following table.

Field Type Comments

AccessRules Array of AccessRuleElementV4 (on page 263)

Status ReturnStatus (see page 312)

FindFirewallElementsFAFolderPathResult data structure The fields of the FindFirewallElementsFAFolderPathResult data structure are listed in the following table.

Field Type Comments

faPaths List of String Element[i] of this list is the Firewall Assurance folder path found for fwElements[i].

fwElements List of FirewallElement (see page 294)

The firewall elements of the input.


FindNetInterfaceResult data structure The fields of the FindNetInterfaceResult data structure are listed in the following table.

Field Type Comments


netInterfaceElements

List of NetInterfaceElement (see page 304)

FindNetworkElementsZoneResult data structure The fields of the FindNetworkElementsZoneResult data structure are listed in the following table.

Field Type Comments

networkElements List of NetworkElement (see page 305)

The network elements of the input.


zones List of String Element[i] of this list is the zone for networkElements[i].



FindNetworkEntitiesResult data structure The fields of the FindNetworkEntitiesResult data structure are listed in the following table.

Field Type Comments

networkEntitiesResultElementArray

NetworkEntitiesResultElement (see page 306)


FirewallAclSnapshotData data structure The fields of the FirewallAclSnapshotData data structure are listed in the following table.

Field Type Comments

aclId Integer

aclUserComment String

aclDescription String

aclCreationTime Date

aclLastModificationTime

Date

aclCreatedBy String

aclModifiedBy String

ruleOrder Long

actionType String Possible values: • Undefined • Allow • Deny • Translate • Ips

directionType String Possible values: • UNDEFINED • Inbound • Outbound • Both

vpnUnitUsageType String Possible values: • None • Specific • Any • RemoteAccess

sourceIpSpace IPSpace (see page 300)

targetIpSpace IPSpace (see page 300)

firewallServiceSpace FirewallServiceSpace (see page 297)



Field Type Comments

isImplied Boolean

isDisabled Boolean

isFiltering Boolean

isUnsupported Boolean

originalRuleText String

translatedSourceIpSpace

IPSpace (see page 300)

translatedTargetIpSpace


translatedFirewallService

String

chainNumber Integer

originalRuleName String

ruleType String Possible values: • Regular • AntiSpoofing • HideNat • DenyAny • Mip • PixNat

globalUniqueId String

isExcluded Boolean

isAuthenticalted Boolean

isLogEnabled Boolean

netInterfaces String

sourceNetInterfaces String

vpnUnits String

idpRuleGroups String

chainName String

preChangeId Integer

postChangeId Integer

affectedChangeId Integer

FirewallChange data structure The fields of the FirewallChange data structure are listed in the following table.

Field Type Comments

id Integer

Comment String

Description String

createdBy String



Field Type Comments

creationTime Date



Date

hostName String

hostIpAddress String

hostId Integer

firewallType String Possible values: • LOAD_BALANCER • GENERIC • GENERIC2 • GENERIC3 • CHECKPOINT • CHECKPOINT_NG • CISCO • NETSCREEN • IPTABLES • CISCO_PIX • SYMANTEC • FORTIGATE • ISS_PROVENTIA • JUNOS

changeType String Possible values: • ACL • OBJECT • ACCESS_LIST

changeState String Possible values: • NEW • MODIFIED • DELETED

entityName String

configurationChangeTime

Date

changeTime Date

changedBy String

availabilityImpact Boolean

changeReconciliationStatus

String Possible values: • PENDING • AUTHORIZED • UNAUTHORIZED • IGNORED

lastReviewer String

changeReconciliationCoverage

Integer

ticketByComment String

isViolatingEnum String Possible values:



Field Type Comments • UNKNOWN • VIOLATING • POTENTIALLY • NOT_VIOLATING

violations String

The following data structures are extensions to this data structure:

› FirewallChangeDetails (see page 293) › FirewallChangeReconciliationDetails (see page 293)

FirewallChangeDetails data structure The FirewallChangeDetails data structure is an extended version of the FirewallChange data structure (see page 291).

The additional fields of the FirewallChangeDetails data structure (that is, fields that are not included in the FirewallChange data structure) are listed in the following table.

Field Type Comments

rootPreObjectTreeNode

FirewallObjectTreeNode (see page 296)

The state of the firewall object before the change. Note: Relevant only for OBJECT changes.

rootPostObjectTreeNode

FirewallObjectTreeNode (see page 296)

The state of the firewall object after the change. Note: Relevant only for OBJECT changes.

preAclData FirewallAclSnapshotData (see page 290)

The state of the access rule before the change. Note: Relevant only for ACL changes.

postAclData FirewallAclSnapshotData (see page 290)

The state of the access rule after the change. Note: Relevant only for ACL changes.

affectedAclsData Array of FirewallAclSnapshotData (see page 290)

A list of the access rules affected by this change. Note: Relevant only for OBJECT changes.

FirewallChangeReconciliationDetails data structure The FirewallChangeReconciliationDetails data structure is an extended version of the FirewallChange data structure (see page 291).

The additional fields of the FirewallChangeReconciliationDetails data structure (that is, fields that are not included in the FirewallChange data structure) are listed in the following table.

Field Type Comments

ticketRelationDetailsList

Array of TicketRelationDetails (see page



Field Type Comments 317)

FirewallChangesSearchFilter data structure The fields of the FirewallChangesSearchFilter data structure are listed in the following table.

Field Type Comments

trackingPeriod DateRange (see page 280)

Include only changes created between the specified dates.

folderId Integer Include only changes from firewalls that are in the specified firewall folder.

firewallId Integer Include only changes from the specified firewall.

changeReconciliationStatusFilter

Comma-separated list of reconciliation statuses

Include only changes with the specified reconciliation statuses. Possible values: • PENDING • AUTHORIZED • UNAUTHORIZED • IGNORED

violationStatusFilter

Comma-separated list of violation statuses

Include only changes with the specified violation statuses. Possible values: • UNKNOWN • VIOLATING • POTENTIALLY • NOT_VIOLATING

FirewallElement data structure The fields of the FirewallElement data structure are listed in the following table.

Field Type Comments

id Integer

name String

path String

FirewallException data structure The fields of the FirewallException data structure are listed in the following table.

Field Type Comments

id Integer The ID of the exception

sourceAddress Address elements (Mandatory) An array of address elements that are the source of the exception

isSourceNegated Boolean (Mandatory) If true, the source is negated

destinationAddress

Address elements (Mandatory) An array of address elements that are the destination of



Field Type Comments the exception

isDestinationNegated

Boolean (Mandatory) If true, the destination is negated

services Port list (Mandatory) A list of ports that are the services of the exception.

isServicesNegated Boolean (Mandatory) If true, the service is negated

firewall FirewallElement (see page 294)

(Mandatory if policy is empty) The firewall name or ID

policy String (Mandatory if firewall is empty) If firewall is empty, the exception is created as a Network Assurance exception on an Access Policy Scope. This parameter provides the full path of the Access Policy scope on which the exception is set.

expirationDate Long (Optional) An expiration date for the exception Note: UNIX epoch format (including milliseconds)

tag String (Optional) A tag string on the exception

ticketId Integer (Optional) The ticket ID of a ticket related to the exception

originalRuleId String (Optional) The original rule ID of the access rule

originalRuleText String (Optional) The original text of the access rule

userComments String Comment on the exception

FirewallFindByObjectResult data structure The fields of the FirewallFindByObjectResult data structure are listed in the following table.

Field Type Comments


fwElements List of FirewallElement (see page 294)

The firewalls that match the specified object name.

objectNames List of String Element[i] of this list is the list of object names found for fwElements[i].

FirewallObjectIdentification data structure The fields of the FirewallObjectIdentification data structure are listed in the following table.



Field Type Comments

firewallId Integer The ID of the firewall.

firewallName String

firewallIP String

firewallFolder String

firewallManagementId

Integer The ID of the firewall management server.

firewallManagementName

String

firewallManagementType

String

objectName String

objectType String


ports String

members String A comma-separated list of the members of this object. If a group object includes other group objects, only their names are included; their content is not.

affectedAccessRules

Integer

newObject Boolean Specifies whether this is a new object.

FirewallObjectTreeNode data structure The fields of the FirewallObjectTreeNode data structure are listed in the following table.

Field Type Comments

type String See FWObjectTypeEnum (on page 296) for a list of possible values

name String

isTemporary Boolean

Data String

subNodes Array of FirewallObjectTreeNode

FWObjectTypeEnum values Possible firewall object types:

• FW1Host • FW1Cluster • FW1Network • FW1Group • FW1Service • FW1ServiceGroup • FW1VPNCommunity • FW1AddressRange • FW1Module • FW1Domain • PIXNetworkGroup • PIXServiceGroup



• PIXProtocolGroup • PIXICMPTypeGroup • PIXHost • PIXNetwork • PIXProtocol • PIXPortObject • PIXServiceObject • NSAddress • NSService • NSZone • NSAddressGroup • NSServiceGroup • NSMultiIpRangeAddress • FortiGateIPAddress • FortiGateFQDNAddress • FortiGateRangeAddress • FortiGateAddressGroup • FortiGateService • FortiGateServiceGroup • FortiGateZone • FortiGateVipNatAddress • TempIP • TempService • FW1Extension • PIXExtension • NSExtension • FG_EXTENSION • JunosACLExtension • NSDomainAddress • JunosAddress • JunosAddressSet • JunosApplication • JunosApplicationSet • JunosZone

FirewallServiceSpace data structure The fields of the FirewallServiceSpace data structure are listed in the following table.

Field Type Comments

FirewallServices String

isNegated Boolean

originalText String

Folder data structure The fields of the Folder data structure are listed in the following table.

Field Type Comments

id Integer

name String

subfolders Array of Folder

analyses Array of Analysis (see page 268)

FwRulesAttributesUpdateInfo data structure The fields of the FwRulesAttributesUpdateInfo data structure are listed in the following table.

Field Type Comments

hostId Integer

originalRuleIds Array of String




FWScope data structure The fields of the FWScope data structure are listed in the following table.

Field Type Comments

fwList List of FirewallElement (see page 294)

fwFolders Comma-separated list of strings representing FW folders in Firewall Assurance.

GatewayRouteNodeV1 data structure The GatewayRouteNodeV1 data structure is an extended version of the RouteNodeV1 (on page 312) data structure used to extract route information from change requests.

The additional fields of the GatewayRouteNodeV1data structure (that is, fields that are not included in the RouteNodeV1 data structure) are listed in the following table.

Field Type Comments

destinationNAT Array of String

destinationRanges Array of String

displayIPAddress String

displayName String

hostGroupName String

hostId Integer

inboundNetInterfaceId

Integer

performsNAT Boolean

services Array of String

servicesNAT Array of String

sourceNAT Array of String

sourceRanges Array of String

typeEnum String

HostAttributes data structure The fields of the HostAttributes data structure are listed in the following table.

Field Type Comments

businessFunction String

customFields Array of EntityField (see page 281)

Custom attributes created by this organization

email String



Field Type Comments

owner String

site String

userComment String

userNameTag String

HostGroupEntityItem data structure The fields of the HostGroupEntityItem data structure are listed in the following table.

Field Type Comments

Id Integer The ID of the host group (cluster)

Name String The name of the host group (cluster)

Type String The type of the host group Possible values: • Location • Generic • Role • Cluster • Application • BusinessUnit • VirtualFirewallGroup • DeviceFolder • NetworkGroup • MAP_GROUP • Management • Site • SiteAssetGroup • AdHocNetwork • VirtualDomainFolder • VirtualDomain • SecurityTag • SecurityGroup

HostsAttributesUpdateInfo data structure The fields of the HostsAttributesUpdateInfo data structure are listed in the following table.

Field Type Comments

hostAttributes HostAttributes (on page 298)

hostIds Array of Integer

HostsResponse data structure The fields of the HostsResponse data structure are listed in the following table.

Field Type Comments

hostIds Array of Integer




DATA STRUCTURES: I TO R IntRange data structure

The fields of the IntRange data structure are listed in the following table.

Field Type Comments

from Integer

to Integer

IpAndCntNetGraphObjectPair data structure The fields of the IpAndCntNetGraphObjectPair data structure are listed in the following table.

Field Type Comments

IPRange IpRangeElement (see page 300)

NetworkOrHost cntNetGraphObject

Note: Information about this parameter is available on the WSDL page.

IPAndNetworkPair data structure The fields of the IPAndNetworkPair data structure are listed in the following table.

Field Type Comments

IPRange IPRangeElement (see page 300)

network cntNetGraphObject

Note: Information about this parameter is available on the WSDL page.

IPRangeElement data structure The fields of the IPRangeElement data structure are listed in the following table.

Field Type Comments

endIP String

startIP String

IPSpace data structure The fields of the IPSpace data structure are listed in the following table.

Field Type Comments

ipRanges String

isNegated Boolean

originalText String

ModelLockStatus data structure The fields of the ModelLockStatus data structure are listed in the following table.



Field Type Comments

isReadLocked Boolean

isUpdateLocked Boolean

isWriteLocked Boolean

modelName String • LIVE • FORENSICS • WHAT_IF • CORE (an internal model used for

operational and system purposes)

ModifyObjectChangeRequestV5 data structure The ModifyObjectChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Modify Object change requests.

The additional fields of the ModifyObjectChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments

addedAddresses Array of String The IP addresses to add to the object being modified.

addedObjects Array of FirewallObjectIdentification (see page 295)

The objects to add to the object being modified.

addedPorts String The ports to add to the object being modified.

newObjectName String A new name for the object.

object FirewallObjectIdentification (see page 295)

The object to modify.

removedAddresses

Array of String The IP addresses to delete from the object being modified.

removedObjects Array of FirewallObjectIdentification (see page 295)

The objects to delete from the object being modified.

removedPorts String The ports to delete from the object being modified.

ModifyRulesChangeRequestV5 data structure The ModifyRulesChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Modify Rule change requests.

The additional fields of the ModifyRulesChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.



Field Type Comments


addedAddresses Array of String

addedObjects Array of FirewallObjectIdentification (see page 295)

addedPorts String

addedApplications Array of FirewallObjectIdentification (see page 295)

addedUsers String


The firewall for which the rules are to be modified.

modifiedField String The field to modify. Possible values: • Source • Destination • Service • Source NAT • Destination NAT • Service NAT

negationChangeType

String Specifies whether to negate the value of the field to be modified. Possible values: • NO_CHANGE • NEGATE • NOT_NEGATE

removedAddresses

Array of String

removedObjects Array of FirewallObjectIdentification (see page 295)

removedPorts String

removedApplications


removedUsers String


rulePosition SlimAccessRule (see page 315)

submitOnAllClusterMembers

Boolean



Field Type Comments

useApplicationsDefaultPortsChangeType

String Specifies whether to use the default ports of the applications as the ports for the change request. Possible values: • NO_CHANGE • YES • NO


NetInterfaceDetails data structure The fields of the NetInterfaceDetails data structure are listed in the following table.

Field Type Comments

ABISize Long

assetId Integer

assetName String

comment String

connectivityIssue String

createdBy String

creationTime Date

description String

id Integer

ipAddress String

isDefaultGateway Boolean


Date

layer2 Boolean

locked Boolean

lockedToNetwork Boolean

macAddress String

missingNeighbors String

modifiedBy String

name String

netMask String

networkId Integer

networkName String

networkZoneType String



Field Type Comments

primary Boolean

status String

type String Possible values: • NAT • ETHERNET • WLAN • TOKEN_RING • PPP • SLIP • VIRTUAL • OTHER • UNKNOWN • LOOPBACK • SERIAL • LOAD_BALANCER • TUNNEL • VPN • CONNECTING_CLOUD_INTERFACE

virtualRouter String

zoneName String

zoneType String

NetInterfaceElement data structure The fields of the NetInterfaceElement data structure are listed in the following table.

Field Type Comments

id Integer

name String

type String Possible values: • NAT • ETHERNET • WLAN • TOKEN_RING • PPP • SLIP • VIRTUAL • OTHER • UNKNOWN • LOOPBACK • SERIAL • LOAD_BALANCER • TUNNEL • VPN • CONNECTING_CLOUD_INTERFACE

ipAddress String

zoneType String

zoneName String

Description String



NetworkElement data structure The fields of the NetworkElement data structure are listed in the following table.

Field Type Comments

IPAddress String

id Integer

name String

netMask Integer

path String

type Integer The possible values for this field are listed following this table.

The possible values for the type field when it represents a network are:

› 0: Regular › 1: Cloud › 2: Tunnel › 3: Link › 4: VPN Tunnel › 5: SerialLink › 6: Connecting Cloud › 7: Artificial Layer2 › 99: Unknown

The possible values for the type field when it represents a network interface are:

› 100: NAT › 101: Ethernet › 102: WLAN › 103: TokenRing › 104: PPP › 105: Slip › 106: Virtual › 107: Other › 108: Unknown › 109: Loopback › 110: Serial › 111: Load Balancer › 112: Tunnel › 113: Vpn › 114: Connecting Cloud Interface



NetworkEntitiesResultElement data structure The fields of the NetworkEntitiesResultElement data structure are listed in the following table.

Field Type Comments

sourceEntity IpAndCntNetGraphObjectPair (on page 300)

<sourceEntity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:ipAndNetworkPair">

destinationEntity IpAndCntNetGraphObjectPair (on page 300)

<destinationEntity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:ipAndNetworkPair">

preNATSource Boolean Specifies whether the source entity represents a pre-NAT address.

postNATDestination

Boolean Specifies whether the destination entity represents a post-NAT address.

forwardingRoute Boolean Specifies whether a forward route is possible from the source entity to the destination entity.

backwardRoute Boolean Specifies whether a backward route is possible from the destination entity to the source entity. Null means that there was no examination.

NetworkEntityItem data structure The fields of the NetworkEntityItem data structure are listed in the following table.

Field Type Comments

id Integer The ID of the network entity

Name String The name of the network entity

Type String The type of the network entity Possible values: • Network • Location • Host • Network Group • Host Group • Business Asset • Business Group

NetworkItemV1 data structure The fields of the NetworkItemV1 data structure are listed in the following table.

Field Type Comments

ipNetwork String

name String

networkId Integer



NetworkRouteNodeV1 data structure The NetworkRouteNodeV1 data structure is an extended version of the RouteNodeV1 (on page 312) data structure.

The additional fields of the NetworkRouteNodeV1 data structure (that is, fields that are not included in the RouteNodeV1 data structure) are listed in the following table.

Field Type Comments

networkItems Array of NetworkItemV1 (on page 306)

OwnersFilter data structure You can use multiple filter fields in the same search. The search uses all fields that contain values.

The fields of the OwnersFilter data structure are listed in the following table.

Field Type Comments

isMyGroups Boolean Specifies whether the custom Vulnerability Definition was created by users from my group.

UserGroupsIds Integer ID of user groups.

UserIds Array of Integer List of user IDs.

userNames Array of String List of user names.

Phase data structure The fields of the Phase data structure are listed in the following table.

Field Type Comments


comment String

description String

creationTime Date Read-only


Date Read-only

createdBy String Read-only

lastModifiedBy String Read-only

dueDate Date

revisedDueDate Date

owner String Read-only

startDate Date Read-only

endDate Date Read-only

isCurrent Boolean Read-only

demotionsCount Integer Read-only



Field Type Comments

ticketTypePhase TicketTypePhase (see page 318)

Read-only

PhaseOperation data structure The fields of the PhaseOperation data structure are listed in the following table.

Field Type Comments

phaseId Integer Optional, depending on phase type

phaseOwner String Optional, depending on phase type

reject Boolean Optional, depending on phase type

type String (Mandatory) Possible values: • ACCEPT • CHANGE_PHASE • CLOSE • DEMOTE • IGNORED • PROMOTE • REASSIGN • REOPEN • REQUEST_TO_CLOSE

The use of each field according to the selected phase operation is explained in the following table.

Phase operation (type)

phaseId phaseOwner isReject

ACCEPT Ignored Ignored Ignored

CHANGE_PHASE Change the phase of the ticket to this phase

Change the phase owner to this owner

Ignored

CLOSE Ignored Ignored Mandatory True if the user rejects the tickets

DEMOTE Ignored Change the phase owner to this owner

Ignored

IGNORED Ignored Ignored Ignored

PROMOTE Ignored Change the phase owner to this owner

Ignored

REASSIGN Ignored Mandatory The new owner of the phase

Ignored

REOPEN Change the phase of the ticket to this phase

Change the phase owner to this owner

Ignored



Phase operation (type)

phaseId phaseOwner isReject

REQUEST_TO_CLOSE

Ignored Ignored Ignored

PotentialVulnerability data structure The fields of the PotentialVulnerability data structure are listed in the following table.

Field Type Comments

catalogID String

cveId String

hostIp String

hostName String

id Integer

severity String

title String

Product data structure The fields of the Product data structure are listed in the following table.

Field Type Comments

Vendor String The product vendor

Product String The product name

AffectedVersions String Comma-separated list of the affected versions or “Any” for all versions

MappedInProductList

Boolean • True: If there is a mapping in the product list (in the Skybox Admin window)

• False: If there is no mapping RunningWith String Environment details (for example, the

version per operating system)

ReactivateRuleChangeRequestV7 data structure The ReactivateRuleChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Reactivate Rule change requests.

The additional fields of the ReactivateRuleChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments





RecertifyChangeRequestV7 data structure The RecertifyChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Recertify Rule change requests.

The additional fields of the RecertifyChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.

Field Type Comments

accessRuleId Integer

reviewedAccessRule

SlimAccessRule (see page 315)

RecertifyTicketCreationResultV2 data structure The fields of the RecertifyTicketCreationResultV2 data structure are listed in the following table.

Field Type Comments

newTicketIds Array of integer

rejectedAccessRuleElements

Array of AccessRuleElementV4 (on page 263)

RepositoryProduct data structure The fields of the RepositoryProduct data structure are listed in the following table.

Field Type Comments

disabled Boolean True if the repository product is disabled; otherwise, false.

installedVersions String Comma-separated string of all installed versions of the product.

product String Name of the product.

vendor String Name of the vendor.

id Integer ID of the product.

productGroups String Names of the product groups to which the repository product belongs.

userComments String User comments.

RequireAccessChangeRequestV5 data structure The RequireAccessChangeRequestV7 data structure is an extended version of the ChangeRequestV3 data structure (on page 271) used for Access Update change requests.

The additional fields of the RequireAccessChangeRequestV7 data structure (that is, fields that are not included in the ChangeRequestV3 data structure) are listed in the following table.



Field Type Comments

applications Array of FirewallObjectIdentification (see page 295)

Array of firewall applications to use. (For use with next-generation firewalls).


Array of String Array of addresses to use as the destination of the rule.

destinationObjects


Array of firewall objects to use as the destination of the rule.

expirationDate Date Sets the expiration date for the access rules.

isInstallOnAny Boolean Specifies whether to add the requested change to all firewalls in the specified device group. Note: Panorama only.

isLogEnabled Boolean Specifies whether logging of the rule is enabled on the firewall.

isSharedObject Boolean Specifies that all objects used by and created for this access rule are shared by all the firewalls managed by a specific device. Note: Panorama only.

NATDestinationAddresses

Array of String Translated destination addresses.

NATDestinationObjects


Translated destination objects.

NATPortObjects Array of FirewallObjectIdentification (see page 295)

Translated port objects.

NATPorts String Translated ports.

NATSourceAddresses

Array of String Translated source addresses.

NATSourceObjects


Translated source objects.


Array of port objects to use as the ports of the rule.

ports String Array of ports and services for the rule.





Field Type Comments

sourceAddresses Array of String Array of addresses to use as the source of the rule.


Array of firewall objects to use as the source of the rule.

useApplicationsDefaultPorts

Boolean Specifies whether to use the default ports of the applications as the ports for the change request.


users Array of String Array of user names

ReturnStatus data structure The fields of the ReturnStatus data structure are listed in the following table.

Field Type Comments

code Integer • 0: Success • 1: Error

Reason String If there is an error, this field contains the error message.

RouteNodeV1 data structure

Note: The RouteNodeV1 data structure is an abstract data structure.

The following data structures are extensions to the RouteNodeV1 data structure:

› GatewayRouteNodeV1 (on page 298) › NetworkRouteNodeV1 (on page 307)

RouteV1 data structure The fields of the RouteV1 data structure are listed in the following table.

Field Type Comments

routeNode Array of routeNodeV1

RuleAttributes data structure The RuleAttributes data structure holds the business attributes (meta-data) for an access rule. The fields of this data structure are listed in the following table. If any field has a value, the value is copied to the matching field of the access rule.

Field Type Comments

businessFunction String

comment String



Field Type Comments

customFields Array of EntityField (see page 281)

email String

nextReviewDate Date

owner String

status String The recertification status of the rule. Possible values: • NONE • IN_PROGRESS • REJECTED • CERTIFIED

ticketId String

RulesAttributesUpdateInfo data structure The fields of the RulesAttributesUpdateInfo data structure are listed in the following table.

Field Type Comments

accessRuleIds

Array of Integer


RuleComplianceViolationElement data structure The fields of the RuleComplianceViolationElement data structure are listed in the following table.

Field Type Comments

importance Integer Possible values: • 0=Very Low • 1=Low • 2=Medium • 3=High • 4=Critical

ruleCheckName String The name of the Rule Check in Skybox

rulePolicyName String The name of the Rule Policy in Skybox

violationExplanation

String

RulePolicyException data structure The fields of the RulePolicyException data structure are listed in the following table.

Field Type Comments

id Integer The ID of the Rule exception.

ruleGuid String (Mandatory) The GUID of the access rule.



Field Type Comments

rulePolicyScope Comma-separated list of rule check policies

A comma-delimited list of Rule Policy names. The default value is All Rule Checks.

expirationDate Date For exceptions with expiration dates. The default value is no expiration date.

expiratioAccessRuleModification

Boolean If true, modifying the access rule causes the exception to expire. The default value is true.

comment String A comment on the exception.

DATA STRUCTURES: S TO Z Scope data structure

The fields of the Scope data structure are listed in the following table.

Field Type Comments

Assets List of asset IDs List of asset IDs in the model. The list can include ranges.

SendToElement data structure The fields of the SendToElement data structure are listed in the following table.

Field Type Comments

destinationAddress

List of String

ports String

ServiceConfigurationItem data structure The ServiceConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 270) used for items containing a list of services and ports.

The additional fields of the ServiceConfigurationItem data structure (that is, fields that are not included in the BaseConfigurationItem data structure) are listed in the following table.

Field Type Comments

ports Array of String

ServiceGroupConfigurationItem data structure The ServiceGroupConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 270) used for groups of ServiceConfigurationItem (on page 314). The structure holds the names of the members and the sum of all their ports.

The additional fields of the ServiceGroupConfigurationItem data structure (that is, fields that are not included in the BaseConfigurationItem data structure) are listed in the following table.



Field Type Comments

memberNames Array of String

ports Array of String

SlimAccessRule data structure The fields of the SlimAccessRule data structure are listed in the following table.

Field Type Comments

accessRuleId Integer

actionType String

chainNumber Integer

comment String

firewallServiceSpace

FirewallServiceSpace (see page 297)

globalUniqueId String

order Integer

originalRuleName String

originalRuleText String

primaryChain Boolean

sourceIPSpace IPSpace (see page 300)

targetIPSpace IPSpace (see page 300)

translatedFirewallServiceSpace

FirewallServiceSpace (see page 297)

translatedSourceIPSpace


translatedTargetIPSpace


Solution data structure The fields of the Solution data structure are listed in the following table.

Field Type Comments

ID Numeric The ID of the solution.

Name String The name of the solution.

Type String The type of the solution: • Other (General) • Config • Block • Patch • Remove • Upgrade • Workaround



Field Type Comments • Note • MitigateByIPS

Description String The description of the solution.

Product String The product name to which the solution applies or empty if it applies to all products.

Vendor String The vendor name of the product to which the solution applies or empty if it applies to all products.

Environment String The environment (that is, operating system) to which the solution applies or empty if it applies to all products.

EnvironmentVersion

String The environment version (that is, version of operating system) to which the solution applies or empty if it applies to all products

EnvironmentVendor

String The environment version (that is, version of operating system) to which the solution applies or empty if it applies to all products.

CustomSolution Boolean • True: A custom solution (user’s solution)

• False: Otherwise

Source data structure The fields of the Source data structure are listed in the following table.

Field Type Comments

id String The ID of the external source.

Severity String The severity of the external source.

Source String The name of the external source.

SubRange data structure The fields of the SubRange data structure are listed in the following table.

Field Type Comments

start Integer

size Integer

TaskWSDL data structure The fields of the TaskWSDL data structure are listed in the following table.

Field Type Comments

duration Long

launchedBy String

sequenceName String

startDate Date



Field Type Comments

taskType String

TicketEvent data structure The fields of the TicketEvent data structure are listed in the following table.

Field Type Comments

id Integer

user String

date String

modifiedField String

oldValue String

newValue String

TicketField data structure The fields of the TicketField data structure are listed in the following table.


Ticket ID SBVAPI_EVENT_PARAM_TICKET_ID 1 Integer


2 Text

Ticket status SBVAPI_EVENT_PARAM_STATUS 7 • Closed • Ignored • In Progress • New • Rejected • Resolved • Verified • Reopened • Demoted

TicketRelationDetails data structure The fields of the TicketRelationDetails data structure are listed in the following table.

Field Type Comments

changeReconciliationBy

String

changeReconciliationCoverage

Integer

ticketCoverage Integer

fwChangeId Integer

ticketId Integer

accessRequestId Integer



TicketsSearchFilter data structure You can use multiple filter fields in the same search. The search uses all fields that contain values.

The fields of the TicketsSearchFilter data structure are listed in the following table.

Field Type Comments

ticketIdsFilter Array of Integer Search tickets by IDs

statusFilter Array of String Each string is a ticket status

Search tickets by status. Possible values: • New • InProgress • Resolved • Closed • Rejected • Ignored • Verified • Reopened • Demoted

owner String Search tickets by owner

phaseName String Search tickets by current phase

freeTextFilter String Free text search in the following ticket fields: • Title • Comment • Owner • ID • Status • Priority • Vendor reference • Solutions • CVE catalog ID • Custom fields of type String

createdBy String User name

modifiedBy String User name

TicketTypePhase data structure The fields of the TicketTypePhase data structure are listed in the following table.

Field Type Comments


ticketType String Possible values: • VulnerabilityTicket • ApplicationTicket • VulnerabilityDefinitionTicket • AccessChangeTicket • PolicyViolationTicket • EOLTicket

order Integer

waitingForClosure Boolean



Field Type Comments

name String

defaultOwner String

TicketWorkflow data structure The fields of the TicketWorkflow data structure are listed in the following table.

Field Type Comments

id Integer The ID of the ticket workflow.

name String The name of the ticket workflow.

URLInfo data structure The fields of the URLInfo data structure are listed in the following table.

Field Type Comments

Source String Source of the URL (for example, CVE or SecurityFocus)

Title String Title of the URL

Info String

User data structure The fields of the User data structure are listed in the following table.

Field Type Comments

username String

email String

phone String

department String

baseRole String Possible values: • ADMIN • ADMIN_OPS • ADMIN_USERS • SECURE_ADMIN • ASSURE_ADMIN • User • SECURE_USER • ASSURE_USER • READONLY • SECURE_READONLY • ASSURE_READONLY • TICKET_HANDLER • TICKET_REQUESTOR • RECIPIENT

lastLogin Date

firstName String

lastName String

groups Array of String List of groups to which the user belongs



Field Type Comments

isDisabled Boolean

comment String

VulnerabilityV1 data structure The fields of the VulnerabilityV1 data structure are listed in the following table.

Field Type Comments

VulnerabilityTypeId

VulnerabilityTypeIdV1 (on page 324)

The ID and vulnerability database (according to how it was searched) of the Vulnerability Definition of the vulnerability occurrence

Title String The title of the Vulnerability Definition of the vulnerability occurrence

Severity String The severity of the Vulnerability Definition Possible values: • Info • Low • Medium • High • Critical • Unknown

CVE String The CVE of the Vulnerability Definition

hostId Integer The ID of the asset in Skybox

hostIp String The IP address of the asset

hostName String The name of the asset

Id Integer

ServiceName String The name of the service on which the vulnerability occurrence exists

ServicePorts String The ports of the service, comma-separated

NetworkNames String The names of the networks to which the asset belongs (comma-separated), or empty for unassigned assets

NetworkGroupNames

String The names of the network groups to which the network of the asset is attached, comma-separated

Exposure String Exposure of the vulnerability occurrence Possible values: • Direct • Indirect • Protected • Potential • Inaccessible • Excluded • Unknown



Field Type Comments

History Array of VulnerabilityEvent (on page 321)

History events for this vulnerability occurrence

Risk String Possible values: • Very Low • Low • Medium • High • Critical

Status String Possible values: • Found • Ignored • Fixed

ScannerID String The ID of the scanner that was the source of the vulnerability occurrence

LastScanTime Long The most recent scan time of the vulnerability occurrence; -1 represents no value

LastModificationTime

Long The last modification time of the vulnerability occurrence

LastModifiedBy String The last user who modified the vulnerability occurrence

DiscoveryMethod String The discovery method of the vulnerability occurrence See Enum for the discovery method parameter (on page 156) for the list of possible values

Comment String User comments

VulnerabilityEvent data structure The fields of the VulnerabilityEvent data structure are listed in the following table.

Field Type Comments

Date String

ModifiedBy String

Text String

VulnerabilitySearchFilter data structure You can use multiple filter fields in the same search. The search uses all fields that contain values.

The fields of the VulnerabilitySearchFilter data structure are listed in the following table.

Field Type Comments

SeverityLevels Array of String Search the vulnerability occurrences by list of severity levels. Possible values:



Field Type Comments • Info • Low • Medium • High • Critical

SeverityScoreRange

IntRange (see page 300)

Search for vulnerability occurrences by severity score range.

ReportedDateRange

DateRange (see page 280)

Search for vulnerability occurrences by reported date.

ScanTimeRange DateRange (see page 280)

Search for vulnerability occurrences by scan time.

ModificationDateRange


Search for vulnerability occurrences by modification date.

CVSSBaseScoreRange

DoubleRange (see page 281)

Search for vulnerability occurrences by a CVSS base score range.

CVSSTemporalScoreRange


Search for vulnerability occurrences by a CVSS temporal score range.

VulnerabilityTypeIdFilter

VulnerabilityTypeIdFilter (see page 324)

Search for vulnerability occurrences by a range of ID filters.

Scope Scope (see page 314)

Search for vulnerability occurrences by scope (list of asset IDs). If the scope is a group object, search in all hierarchy levels.

VulnerabilityTypeV4 data structure The fields of the VulnerabilityTypeV4 data structure are listed in the following table.

Field Type Comments

id VulnerabilityTypeIdV1 (see page 324)

The ID and vulnerability database of the Vulnerability Definition.

title String The title of the Vulnerability Definition.

description String The description of the Vulnerability Definition.

comment String The user comment of the Vulnerability Definition.

cve String The corresponding CVE (the latest CVE is presented because there could be multiple related CVEs).

creationTime Long The reported date of the Vulnerability Definition or its creation time if it is a custom Vulnerability Definition (-1 represents no value).

createdBy String For custom Vulnerability Definitions, the name of the user who created the Vulnerability Definition; otherwise, empty.



Field Type Comments

lastModificationSource

String The source that modified the Vulnerability Definition most recently: system or user.

lastModifiedBy String For custom Vulnerability Definitions, the name of the user who updated the Vulnerability Definition; otherwise, empty.

lastSystemModificationTime

Long The most recent time that the Vulnerability Definition was modified by the system; -1 represents no value.

lastUserModificationDate

Long The most recent time that the Vulnerability Definition was modified by a user; -1 represents no value.

status String The status of the Vulnerability Definition. Possible values: • Unassigned • In Process • Irrelevant • Resolved

isForReview Boolean True if the Vulnerability Definition was updated (either major update or any update, according to the user setting).

reportedDate Date The date on which the Vulnerability Definition was reported.

severityLevel String Possible values: • Info • Low • Medium • High • Critical

severityScore Float The severity score of the Vulnerability Definition.

cvssBase Float The CVSS base score, in 0.1 resolutions. Note: The user value is provided if it was updated by the user.

cvssTemporal Float The CVSS temporal score, in 0.1 resolutions. Note: The user value is provided if it was updated by the user.

vulnerabilityCount

Integer Vulnerability occurrences instance count.

cvss CVSSV1 (see page 279)

The CVSS information for the Vulnerability Definition, including whether the information is based on CVSS V3 (vulnerabilities published from Jan 1, 2016) or CVSS V2 (vulnerabilities published until Dec 31, 2015).



Field Type Comments

relatedSources Array of Source (see page 316)

The related sources of the Vulnerability Definition.

products Array of Product (see page 309)

The affected products of the Vulnerability Definition.

cpeProducts String The CPE string of all affected products of the Vulnerability Definition.

solutions List of Solution (see page 315)

externalURLs Array of URLInfo (see page 319)

All related URLInfo objects.

history Array of ChangeLog (see page 271)

List of all change log entries.

VulnerabilityTypeIdV1 data structure The fields of the VulnerabilityTypeIdV1 data structure are listed in the following table.

Field Type Comments

ID Integer The GUID of the Vulnerability Definition.

Dictionary String (Mandatory) Possible values: • SBV • DEEPSIGHT • IDEFENSE

threatAlertType String • VULNERABILITY_DEFINITION • SECURITY_BULLETIN

VulnerabilityTypeIdFilter data structure The fields of the VulnerabilityTypeIdFilter data structure are listed in the following table.

Field Type Comments

IDs Array of Integer Specifies the Vulnerability Definition IDs to search.

Ranges Array of IntRange (see page 300)


VulnerabilityTypeSearchFilterV2 data structure You can use multiple filter fields in the same search. The search uses all fields that contain values.

The fields of the VulnerabilityTypeSearchFilterV2 data structure are listed in the following table.



Field Type Comments


SeverityLevels Array of String Search the Vulnerability Definitions by list of severity levels. Possible values: • Info • Low • Medium • High • Critical

SeverityScoreRange


Search for Vulnerability Definitions by severity score range.

Statuses Array of String Search for Vulnerability Definitions by statuses. Possible values: • Irrelevant • Resolved • In Process • Unassigned

Title String Search for Vulnerability Definitions by title.

CVSSBaseScores DoubleRange (see page 281)

Search for Vulnerability Definitions by CVSS base score range.

CVSSTemporalScores


Search for Vulnerability Definitions by CVSS temporal score range.

ReportedDate DateRange (see page 280)

Search for Vulnerability Definitions by reported date.

modificationSource String Search for Vulnerability Definitions by the source of their most recent change: system or user.

systemModificationDate


Search for Vulnerability Definitions by the most recent system modification date.

userModificationDate


Search for Vulnerability Definitions by the most recent user modification date.

ExternalCatalog ExternalCatalogId (see page 288)

Search for Vulnerability Definitions by catalog name or catalog and ID.

isCVSSOverridden Boolean Search for Vulnerability Definitions by the CVSS Overridden flag.

VulnerabilityCountThreshold

Integer Search for Vulnerability Definitions by vulnerability occurrence count threshold.

threatAlertType String Possible values: • VULNERABILITY_DEFINITION • SECURITY_BULLETIN



Field Type Comments

isCustomVtOnly Boolean Search only for custom Vulnerability Definitions.

CreatedByFilter OwnersFilter (see page 307)

Search for Vulnerability Definitions by users or user groups who created them (used for custom Vulnerability Definitions).

VulnerabilityTypeTicket data structure The fields of the VulnerabilityTypeTicket data structure are listed in the following table.

Field Type Comments

id Integer The ID of the ticket.

title String The title of the ticket.

priority String The priority of the ticket. Possible values: • Very Low • Low • Medium • High • Critical

dueDate Long The due date of the ticket (when the ticket should be resolved); -1 represents no due date.

doneDate Long The date the ticket was closed, or -1 if empty.

status String The status of the ticket. Possible values: • New • InProgress • Resolved • Rejected • Closed • Reopened • Verified • Ignored

owner String The owner of the current phase or the owner of the ticket if there are no phases.

products List of RepositoryProduct (see page 310)

The repository products of the ticket.

currentPhaseName String The name of the current phase or empty if no phases exist or the ticket is closed.

currentPhaseDueDate

Long The due date of the current phase or -1 if no phases exist or the ticket is closed.



Field Type Comments

customFields Array of CustomField (see page 278)

A list of all custom fields for this ticket type.

demotions Integer The number of times the ticket was demoted. If no phases exist, this field is empty.

externalTicketId Integer The external ticket ID if this exists; otherwise, empty.

externalTicketStatus

String The status of the external ticket. Possible values: • Pending • Open • Closed • Error • Rejected

comment String User comments.

selectedSolutions Array of Solution (see page 315)

A list of all selected solutions for the ticket.

networkScope Array of NetworkEntityItem (see page 306)

A list of all network entities of the ticket.

createdBy String The name of the user that created the ticket.

creationTime Long The creation time of the ticket, or -1 if empty.


Long The most recent modification time of the ticket, or -1 if empty.

lastModifiedBy String Name of the user that most recently modified the ticket.

This part describes how to use Skybox REST APIs to retrieve data and manage Skybox data remotely.

Part III: REST APIs


Chapter 15

Skybox provides 2 sets of REST APIs that enable users to manage or view certain features in Skybox without using the Skybox UIs (the Java Client or the Web Client).

This part provides general information about what is in each set and how use the REST APIs.

In this chapter

Overview of the public REST APIs ........................................ 329

Overview of the additional REST APIs ................................... 330

Conventions ...................................................................... 330

HTTP requests ................................................................... 331

Authentication ................................................................... 331

OVERVIEW OF THE PUBLIC REST APIS The Skybox public REST APIs are located at: https://<Skybox_server>:8443/skybox/webservice/jaxrs/model/v1

Only users with the following roles can work with the public REST APIs:

› API User - read-only: These users retrieve information from Skybox using the REST API calls (GET)

› API User - admin: These users retrieve and manage information from Skybox using all REST API calls

The following entities can be retrieved via the public REST APIs:

› Access Rules › Asset Groups › Assets › Business Units › Locations › Network Groups › Network Interfaces › Networks › Organizational Services (used for working with the Skybox Application &

Service repository) › Routing Rules › Vulnerability Definitions

Introduction to Skybox REST APIs



The public REST APIs can be viewed and tested at https://<server_name>:8443/skybox/webservice/model/v1/swagger-ui/

For additional information, see Public REST APIs (on page 332).

OVERVIEW OF THE ADDITIONAL REST APIS Skybox’s additional REST APIs are located at: https://<Skybox_server>:8443/skybox/webservice/jaxrs

The following entities can be managed via the additional REST APIs:

› Skybox models › Access Policies and zones › Threat alert tickets › Location-related requests that enable you to add networks to a location › Models

The additional REST APIs can be viewed and tested at https://<Skybox_server>:8443/skybox/webservice/swagger-ui/index.html

To use the additional REST APIs, log in with your Skybox user name and password.

Endpoints and requests marked as Internal Most of the endpoints and requests in this set of REST APIs are marked as Internal.

› Skybox takes no responsibility if you use these endpoints and requests. › Support is provided only for the listed endpoints and requests. › Using internal requests may adversely affect server performance. › Internal requests may change between releases, but backward compatibility

will not be maintained.

For additional information, see Additional REST APIs (on page 334).

CONVENTIONS The following conventions apply throughout this document:

› Responses

• Responses are listed under Responses for each method.

• Responses are in JSON format.

• For each request, the Server returns a 3-digit HTTP status code.

• Response examples are available in Swagger.

• Global definitions for HTTP response codes can be found at https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

› Requests

• Parameters that are mandatory are marked *required in Swagger.

› Timestamps

Chapter 15 Introduction to Skybox REST APIs


• All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

HTTP REQUESTS API calls must be written as HTTP requests, and include the following components:

› HTTP method: Describes the type of HTTP action (POST, GET, PUT, or DELETE)

› URL: Describes the resource you are creating or accessing, along with any optional arguments

› HTTP headers: Specifies attributes of the request, including authentication, encoding and request format

› Request body: The data being sent to the server

Request parameters that are mandatory are marked *required in Swagger.

AUTHENTICATION The REST APIs identify users via HTTP basic authentication, using a special HTTP header that includes username:password encoded in base64.


Chapter 16

The Skybox public REST APIs are located at: https://<Skybox_server>:8443/skybox/webservice/jaxrs/model/v1

They can be viewed and tested at: https://<server_name>:8443/skybox/webservice/model/v1/swagger-ui/

The public REST APIs require special API user roles.

In this chapter

Pagination ......................................................................... 332

Data structures (models) .................................................... 332

PAGINATION To paginate responses, use the offset and limit parameters in a request. The 1st page of results has an offset of 0.

For example, the following call brings the first 30 access rules from the result set.

› https://<host_name>:8443/skybox/webservice/jaxrs/model/v1/access-rules?ignoreRulesWithAny=true&matchCriteria=Contained_within&sort=FIREWALL_NAME&offset=0&limit=30

DATA STRUCTURES (MODELS) The schema of all the input and output objects are in Swagger, in the Models section. You can see each of the fields, its type, and possible values (for enums).

The following is a sample object:

In addition, the Swagger example for each REST API request includes an example value for the body parameter (when data is uploaded) or the response (when data is retrieved).

Public REST APIs

Chapter 16 Public REST APIs


› Click Model to switch between the example (default) and the schema.


Chapter 17

Skybox’s additional REST APIs are located at https://<Skybox_server>:8443/skybox/webservice/jaxrs

The additional REST APIs can be viewed and tested at https://<Skybox_server>:8443/skybox/webservice/swagger-ui/index.html

To use the additional REST APIs, log in with your Skybox user name and password.

Important: Most of the endpoints and requests in this set of REST APIs are marked as Internal. Skybox takes no responsibility for the use of internal endpoints and requests.

In this chapter

Endpoints ......................................................................... 334

Pagination ......................................................................... 335

Threat Alert Tickets v1 ....................................................... 335

Access Policy Management .................................................. 336

Locations .......................................................................... 339

Models ............................................................................. 339

Custom Entity Fields .......................................................... 341

ENDPOINTS The following endpoints are supported for end users:

› /models/export and /models

Used to manage Skybox models (on page 339), for example to export and import models

› /accesspolicytemplate/

Used to manage Access Policies (on page 336) and zones.

› /threatalert/v1 and /threatalerttickets/v1

These calls work with threat alert tickets (on page 335).

› Location-related requests that enable you to add networks to a location (on page 339)

› /customentityfields

Used to retrieve custom business attributes of various types of entities.

Additional REST APIs

Chapter 17 Additional REST APIs


Endpoints and requests marked as Internal Most of the endpoints and requests in this set of REST APIs are marked as Internal.

› Skybox takes no responsibility if you use these endpoints and requests. › Support is provided only for the listed endpoints and requests. › Using internal requests may adversely affect server performance. › Internal requests may change between releases, but backward compatibility

will not be maintained.

PAGINATION To paginate responses, use the startIndex (or start) and size parameters in a request; first, send a different request to get the number of this type of entity.

THREAT ALERT TICKETS V1 Threat alert ticket calls are at: /threatalerttickets/v1

These calls are used for managing threat alert tickets.

Requests The following requests are available for threat alert tickets.

Method and Endpoint Parameters Description

GET /threatalert/v1 • withSLAOnly • exploitabilityScop

e • start • size • sort • isDescending • status

GET /threatalert/v1/count

(none) Retrieves the total number of vulnerability occurrences in the model

POST /threatalerttickets/v1

• body Creates a threat alert ticket for vulnerability occurrences An example of body can be seen in Swagger

GET /threatalerttickets/v1/{id}

• id Retrieves the threat alert ticket with the specified ID

POST /threatalerttickets/v1/{id}/customsolutions

• id • body

Adds a custom solution to the specified threat alert ticket An example of body can be seen in Swagger

GET /threatalerttickets/v1/{id}/solutions

• id Retrieves all the solutions for the specified threat alert ticket




PUT /threatalerttickets/v1/{id}/solutions

• id • body

Updates the list of selected solutions for the specified threat alert ticket An example of body can be seen in Swagger

GET /threatalerttickets/v1/{id}/threatalerts

• id • startIndex • size

Retrieves the threat alerts (Vulnerability Definitions) related to the specified threat alert ticket

GET /threatalerttickets/v1/{id}/threatalerts/count

• id Retrieves the number of threat alerts related to the specified threat alert ticket

GET /threatalerttickets/v1/{id}/ticketevents

• id Retrieves the event log history for the specified threat alert ticket

GET /threatalerttickets/v1/{id}/ticketevents/count

• id Retrieves the number of history events for the specified threat alert ticket

POST /threatalerttickets/v1/{id}/usercomments

• id • comment

Adds a user comment (string) to the specified threat alert ticket

GET /threatalerttickets/v1/{id}/vulnerabilities

• id • startIndex • size

Retrieves the vulnerability occurrences related the specified threat alert ticket

GET /threatalerttickets/v1/{id}/vulnerabilities/count

• id Retrieves the number of vulnerability occurrences related to the specified threat alert ticket

Parameters Parameters for threat alert tickets are listed in the following table.

Parameter Name Type Description

startIndex Integer Used for pagination

size Integer Used for pagination

id Integer The ID of the threat alert ticket

body Body The data needed to create a custom solution

comment String The comment to add to a threat alert ticket

ACCESS POLICY MANAGEMENT Access Policy management calls are at: /accesspolicytemplate/

Note: Do not use /accesspolicytemplate/v2

These calls are used for managing Access Policies and zones.

Requests The following requests are available for Access Policy management.




POST /accesspolicytemplate/folders

• folderName • description

Creates an (empty) Access Policy folder with the specified name and description Note: In the Web Client, this is called an Access Policy Returns the folder ID of the folder

GET /accesspolicytemplate/folders/{folderId}/zonemappings

• folderId Retrieves all the zone mappings in the specified Access Policy folder, where a zone mapping is a set of source zone, destination zone, and Access Policies (which are known as Access Check Groups in the Web Client) Each zone mapping is equivalent to an Access Policy section For example, in the demo model: source=App, destination=DB, and Access Policy=NIST-App to DB and Default Access Check Group - NIST-App to DB

POST /accesspolicytemplate/folders/{folderId}/zonemappings

• folderId • body

Creates zone mappings (Access Policy sections) in the specified folder An example of body can be seen in Swagger

GET /accesspolicytemplate/folders/{folderId}/zonemappings/{id}

• folderId • id

Retrieves the specified zone mapping from the specified Access Policy folder

PUT /accesspolicytemplate/folders/{folderId}/zonemappings/{id}

• folderId • id • body

Updates the specified zone mapping in the specified Access Policy folder An example of body can be seen in Swagger

DELETE /accesspolicytemplate/folders/{folderId}/zonemappings/{id}

• folderId • id

Deletes the specified zone mapping from the specified Access Policy folder

GET /accesspolicytemplate/folders/name/{folderName}

• folderName Retrieves the folder ID of the specified Access Policy folder For example, in the demo model, NIST 800-41 & Application returns 3035

GET /accesspolicytemplate/templates

(none) Retrieves all the Access Policy templates (also known as Access Policy sections in the Java Client or Access Check Groups in the Web Client) For example: NIST-External to Partner, with all its Access Checks

POST /accesspolicytemplate/templates

• body Creates an Access Policy template/Access Check Group An example of body can be seen in Swagger




GET /accesspolicytemplate/templates/{id}

• id Retrieves the specified Access Policy template by its ID

PUT /accesspolicytemplate/templates/{id}

• id • body

Updates the specified Access Policy template An example of body can be seen in Swagger

DELETE /accesspolicytemplate/templates/{id}

• id Deletes the specified Access Policy template

POST /accesspolicytemplate/templates/{id}/ruletemplates

• id • body

Creates an Access Policy rule template (also known as an Access Check) in the specified Access Policy template

PUT /accesspolicytemplate/templates/{id}/ruletemplates/{ruleId}

• id • ruleId • body

Updates an Access Policy rule template, identified by the Access Policy template ID and Access Policy rule template ID An example of body can be seen in Swagger

DELETE /accesspolicytemplate/templates/{id}/ruletemplates/{ruleId}

• id • ruleId

Deletes an Access Policy rule template, identified by the Access Policy template ID and the Access Policy rule template ID

GET /accesspolicytemplate/zones

(none) Retrieves all zones in from all the existing Access Policies For example, External, DMZ, App

POST /accesspolicytemplate/zones

• body Creates a zone that can be used in an Access Policy

DELETE /accesspolicytemplate/zones/{globalUniqueId}

• globalUniqueId Deletes the specified zone Note: The zone is not deleted if it is used in any Access Policies

Parameters Parameters for Access Policy management are listed in the following table.


folderName String The name of the Access Policy folder (Access Policy)

folderId Integer The ID of the Access Policy folder

id Integer The ID of a zone mapping (Access Policy section) or Access Policy template (Access Check Group)

description String The description of the Access Policy folder

globalUniqueId String The ID of a zone

body Body The data needed for creating or updating entities




Sample body data can be found in Swagger for each call

ruleId Integer The ID of the Access Policy rule (Access Check)

LOCATIONS These calls are used for finding locations and assigning a network to a location.

If you want to add networks to a location, you can search for the location by name to get its ID (and other information), and then add the networks to the location using the network IDs and the location ID.

Find location by name Finds a location in your network by name.

Request: GET /netmodel/location/findLocationByName/{name}

The parameters for this request are listed in the following table.


name String The name of the location to find (you can use the wildcards * and ?) Returns the metadata of the location, including its ID (which can be used as the location ID for adding networks) and its networks

Assign networks to location Assigns a group of networks to a location.

Request: PUT /netmodel/v1/networks/location

The parameters for this request are listed in the following table.


networkIds Array of Integer The IDs of the networks to add to the location

locationId Integer The ID of the location

MODELS Calls at /models/export and /models/ are used for managing Skybox models.

Requests The following requests are available for Skybox models.


GET /models/properties (none) Retrieves the model properties of the Live model (as seen in File > Models > Model Properties in Skybox Manager, or Model in Skybox Web Client)




GET /models/snapshot (none) Retrieves counts of many entities in the current Live model, including vulnerabilities according to their severity and relevance, Access Policy tests, network interfaces, and tickets

GET /models/specificHostsToXmlx

Exports specific hosts from the model to an xmlx file The file is saved to <Skybox_Home>\data\sqlx_models

GET /models/sqlx • sqlxFileName • modelType • excludeRuleUsa

geData • excludeChangeTr

ackingData • overwrite

Exports the model data (of the selected model type) to the specified SQLX file, with options to exclude rule usage data and change tracking data to make the output file smaller. The overwrite parameter specifies whether to overwrite a file with the same name (if there is one) The file is saved to <Skybox_Home>\data\sqlx_models

POST /models/sqlx • sqlxFileName • modelType • importDictionari

es • importModel • importDefinition

s • importUsers

Loads model data to Skybox from the specified SQLX file, which must be located at <Skybox_Home>\data\sqlx_models You can choose which parts of the model to load

GET /models/sqlx/files (none) Retrieves a list of all the SQLX models saved in <Skybox_Home>\data\sqlx_models, and their last modified dates

GET /models/version (none) Retrieves the filename and creation date of the current Live model

GET /models/xmlx • xmlxFileName • modelType • exportDictionary • exportModel • exportDefinition

s • exportUsers

Exports the model data (of the selected model type) to the specified XML file. You can choose which parts of the model to export The file is saved to <Skybox_Home>\data\xml_models

POST /models/xmlx • xmlxFileName • modelType • importDictionari

es • importModel • importDefinition

s • importUsers

Loads model data to Skybox from the specified XMLX file, which must be located at <Skybox_Home>\data\xml_models You can choose which parts of the model to load

POST /models/xmlx/demo (none) Loads the demo model (from DemoModel.xmlx) to Skybox




GET /models/xmlx/files (none) Retrieves a list of all the XMLX models saved in <Skybox_Home>\data\xml_models, and their last modified dates

Parameters Parameters for model management are listed in the following table.


modelType String The model to export: LIVE, WHAT_IF, or FORENSICS

sqlxFileName String The name of the SQLX file to export to or import from, including the extension .sqlx

xmlxFileName String The name of the XML file to export to or import from, including the extension .xmlx

excludeRuleUsageData

Boolean Specifies whether to export the rule usage data as part of the model

excludeChangeTrackingData

Boolean Specifies whether to export the change tracking data as part of the model

overwrite Boolean Specifies whether to overwrite a file of the same name, if one exists

importDictionaries Boolean Specifies whether to import the Skybox Vulnerability Dictionary

importModel Boolean Specifies whether to import the core model

importDefinitions Boolean Specifies whether to import task and report definitions

importUsers Boolean Specifies whether to import users

exportDictionary Boolean Specifies whether to export the Skybox Vulnerability Dictionary to the output file

exportModel Boolean Specifies whether to export the core model to the output file

exportDefinitions Boolean Specifies whether to export task and report definitions to the output file

exportUsers Boolean Specifies whether to export users to the output file

CUSTOM ENTITY FIELDS Calls at /customentityfields are used for managing custom business attributes (also named custom tags) for various types of entities.

› Use GET /customentityfields to retrieve all the custom business attributes for the entities of the specified type with the specified IDs.

For example, you can use this call to retrieve the custom business attributes of a range of products in the deployed products list.

These calls can be used with the following entities:



› Access rules › Assets (entityType = HOST) › Vulnerability Definitions › Networks › Asset Groups (entityType = HOST_GROUP) › Services › Service products › Products in the deployed products list (entityType = REPOSITORY_PRODUCT)

Documents

Developer Guide - Skybox Security