developer’s guide - skybox...

Skybox

Developer’s Guide

8.5.100

Revision: 11

Proprietary and Confidential to Skybox Security. © 2017 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, 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 8.5.100 3

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

Introduction ........................................................................................... 7 Skybox overview ...................................................................................... 7

Part I: Integration .................................................................................. 11

Introduction to integration ...................................................................... 12 Skybox integration package ................................................................ 12 Integrating user data into a Skybox model ........................................... 12 Skybox model ................................................................................... 13

iXML elements ....................................................................................... 15 List of iXML elements and attributes ..................................................... 15 Examples of iXML documents .............................................................. 23 Description of iXML elements .............................................................. 28

Perl API methods ................................................................................... 85 Parameters of API methods ................................................................. 85 API methods and generated iXML code ................................................. 85 Examples of Perl scripts ...................................................................... 86 Mandatory include statements for Perl scripts........................................ 87 Description of Perl API methods ........................................................... 88 Enums for parameters of API methods ............................................... 149

Specific modeling scenarios ................................................................... 153 Modeling load balancers ................................................................... 153 Modeling a Business Asset Group that is based on a network ................ 153

Part II: APIs ........................................................................................ 155

Introduction to Skybox APIs .................................................................. 156 APIs ............................................................................................... 156 Methods ......................................................................................... 156 Connecting to the Skybox APIs .......................................................... 164

Administration API ............................................................................... 167 Administration API methods .............................................................. 167 Using the Administration API ............................................................. 172

Contents

Skybox Developer’s Guide


Firewall Changes API ............................................................................ 173 Firewall Changes API methods ........................................................... 173 Using the Firewall Changes API ......................................................... 178

Network API ........................................................................................ 180 Basic field types used in the API ........................................................ 180 Network API methods....................................................................... 181 Using the Network API ..................................................................... 208

Tickets API .......................................................................................... 211 Tickets API methods ........................................................................ 211 Using the Tickets API ....................................................................... 240

Vulnerabilities API ................................................................................ 242 Vulnerabilities API methods .............................................................. 242 Using the Vulnerabilities API ............................................................. 250

API code example ................................................................................ 252

Data structures .................................................................................... 255 Data structures: A to C .................................................................... 255 Data structures: D to H .................................................................... 276 Data structures: I to R ..................................................................... 295 Data structures: S to Z..................................................................... 311


Preface

Intended Audience The Skybox Developer’s 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 11): Explains how to integrate data from non-standard devices and sources with the Skybox platform

› APIs (on page 155): Explains how to integrate Skybox data into other applications

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.

You can access a comprehensive Help file from any location in the 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].

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

When opening a case, you need the following information:

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

http://downloads.skyboxsecurity.com/files/Installers/Skybox_View/8.5/8.5.100/Docs

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






› 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 The Skybox Security Suite provides the most comprehensive set of cybersecurity management solutions on an advanced security analytics platform. The Suite gives your operational team continuous visibility of the attack surface, enabling them to eliminate attack vectors and respond to security threats and incidents in minutes. This proven solution set has protected the most security-conscious enterprises in the world by solving challenges ranging from vulnerability and threat intelligence management to firewall policy management and change management.

Introduction



The Skybox Security solutions portfolio includes:

› Skybox Vulnerability Control: Goes beyond scanners, using analytics and the context of the attack surface to identify exposures, prioritize risks, fill in blind spots and quickly focus remediation efforts

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

› Skybox Network Assurance: Illuminates complex network security zones and policy compliance violations, giving the insight needed to reduce attack vectors and network disruptions

› Skybox Change Manager: Ends risky changes with network-aware planning and risk assessment, speeding up firewall change processes with customizable workflows and automation

› Skybox Threat Manager: Keeps security leaders abreast of the latest threat intelligence, alerting to new advisories that are important to the network, assets that are at stake and where to begin response

› Skybox Horizon: Gives unprecedented visibility of the attack surface, including a range of Indicators of Exposure (IOEs), so security leaders can better understand and manage security risks, cyberthreats, and remediation options.

Skybox Vulnerability Control Skybox Vulnerability Control is a context-aware vulnerability management solution that goes beyond traditional vulnerability assessment. Vulnerability Control consolidates vulnerability sources and uses scanless vulnerability detection to fill in blind spots. It then applies attack simulation, superior vulnerability intelligence and powerful, analytics to quickly prioritize and eliminate attack vectors.

› View all vulnerabilities to eliminate exploitable attack vectors › Assess the impact of a new vulnerability advisory in minutes — no waiting for

a scan › Add network and security controls context to vulnerability analysis for more

accurate prioritization › Calculate remediation options tailored to your network › Leverage vulnerability and attack vector intelligence, updated daily by Skybox

Research Lab

Skybox Firewall Assurance Skybox Firewall Assurance completely automates firewall management tasks across different firewall vendors and complex rule-sets. It readies your network for action by continuously verifying that firewalls are clean, optimized, and working effectively. Firewall Assurance extends beyond firewall rule checks, analyzing possible traffic between network zones to find hidden risk factors, flagging unauthorized changes and finding vulnerabilities on firewalls.

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

Chapter 1 Introduction


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

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

single consistent and efficient process.

Skybox Network Assurance Skybox Network Assurance provides total network visibility in the context of your network devices and security controls, showing how they work together — or leave you exposed. With Network Assurance, you can find potential attack vectors, check correct implementation of security zone policies or troubleshoot the root causes of network outages.

› Visualize and understand your network and interactions of network devices and controls.

› Analyze network path between any source and destination — including the cloud — to uncover access issues and attack vectors.

› Stay secure and compliant by checking security zones, routers and switches for security violations.

› Troubleshoot in a virtual model to avoid disrupting network services.

Skybox Change Manager Skybox 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.

› Evaluate proposed firewall changes for compliance violations and exposed vulnerabilities.

› Accurately identify firewalls that need to be changed using complete network context.

› Translate change requests to a detailed plan for quick, error-free implementation.

› Automate and optimize rule lifecycle management. › Customize workflows to match organizational needs. › Verify that changes were completed as intended.

Skybox Threat Manager Skybox 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 respond to critical threats in minutes.

› Automate the collection and normalization of threat intelligence. › Enable fast correlation between threats and your IT infrastructure. › Get recommendations for remediation options. › Integrate ticketing workflow for remediation tracking.



Skybox Horizon Skybox Horizon provides unprecedented visibility of the attack surface, including a range of IOEs, giving security leaders the insight needed to build a mature security management program that is more effective against advanced cyberthreats.

› Explore the attack surface with a visual, interactive model that links network topology, network connections, business units and organizational hierarchy

› Present IOEs, including exploitable attack vectors, hot spots of vulnerabilities, network security misconfigurations and non–compliant firewalls

› Drill down with interactive tools to get quick summaries and actionable intelligence

› Provide insights for security strategy and resource planning; quickly communicate security status to business executives

This part provides information about how to integrate data from various sources into the Skybox database using Skybox’s 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 ................................................. 12

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

Skybox model .................................................................... 13

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’s Integration XML (iXML) and 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 the various entities to be added 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 typical process (using Perl) looks something like this:

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


(Otherwise, for basic file import tasks set the Format or File Type property 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.)

Note: To work with iXML scripts that you created or that you received from Skybox, you must have Perl (version 5.6 or higher) installed on your machine (see the Enabling Perl-based Collectors topic in the Skybox Installation and Administration Guide).

SKYBOX MODEL When creating your own data source integration module, you must translate the data into Skybox ‘language’. This is normalization.

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

› When importing a proprietary router, you must 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 building the tree of Business Units and Business Asset Groups, you must 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 which assets it contains

The Skybox data scheme includes the following information:

› Network entities

• Locations

• Networks

• Assets (for example, servers, desktops, firewalls, and routers)

— 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 in Skybox Firewall Assurance, including firewalls and subfolders)

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’s Integration XML (iXML).

In this chapter

List of iXML elements and attributes ...................................... 15

Examples of iXML documents ............................................... 23

Description of iXML elements ................................................ 28

LIST OF IXML ELEMENTS AND ATTRIBUTES In iXML, the network information in the model is contained under the <network_model> element and the other types of information (business, security, and threat) are contained under the <business_model> element.

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

The iXML elements are listed hierarchically in the following section.

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

Element Subelements Attributes

<intermediate_model> (on page 57)

<creation_time> <network_model> <business_model>

version method creation_time last_scan_time

<intermediate_model> subelements

<creation_time> (on page 45)

time

<network_model> (on page 66)

<network> <asset> <host_group> <asset_category> <asset_group> <vpn_tunnel> <config_check_result>

<business_model> (on page 42)

<application> <business_unit> <damage> <dependency>

iXML elements



Element Subelements Attributes <regulation> <business_impact_type> <location> <threat> <threat_group>

<network_model> subelements

<network> (on page 65)

<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 comment

<asset> (on page 36)

<interface> <service> <routing_rule> <access_rule> <ips_access_rule> <ips_rule_group> <nat_rule> <vulnerability_occurrence> <patch> <vpn_unit> <vrouter> <config_file> <address_group_object> <address_object> <service_group_object> <service_object> <firewall_application> <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 latitude longitude

<host_group> (on page 54)

<host_ref> name group_type owner comment

<asset_category> (on page 39)

<asset_ref> name owner comment

Chapter 3 iXML elements



<asset_group> (on page 40)

<asset_ref> name owner comment

<vpn_tunnel> (on page 79)

name number mask type endpoint1 endpoint2 last_scan_time display_as_cloud do_not_outdate comment

<config_check_result> (on page 44)

<host_ref> key type status detection_time file_name line_number actual_result

<network> subelements

<segment> (on page 69)

<host_ref> <ip_range_ref>

name type is_virtual private_vlan_type parent_vlan_id vlan_id is_distributed other_names comment

<asset> subelements

<interface> (on page 56)

ip_address ip_mask locked mac_address name network segment type is_primary layer2 status zone vrouter comment

<service> (on page 71)

<vulnerability_occurrence>

banner port interfaces last_scan_time status comment




<routing_rule> (on page 68)

destination gateway dynamic vrouter via_vrouter via_global null_route comment

<access_rule> (on page 29)

id 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 comment uid source_obj destination_obj service_obj source_zone destination_zone loggable is_negated_source is_negated_destination is_negated_service user routed_interface

<ips_access_rule> (on page 58)

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




<ips_rule_group> (on page 60)

<ips_rule> name

<nat_rule> (on page 63)

id 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 translated_source_obj translated_destination_obj translated_service_obj

<vulnerability_occurrence> (on page 82)

definition id sbv_id title policy last_scan_time scanner_severity scanner_description comment

<patch> (on page 67)

product code comment

<vpn_unit> (on page 80)

name original_text my_domain peer_domain service interface

<vrouter> (on page 80)

name

<config_file> (on page 45)

path

<address_group_object> (on page 31)

<address_object_ref> name comment

<address_object> (on page 31)

name domains ip_ranges comment




<service_group_object> (on page 72)

<service_object_ref> name comment

<service_object> (on page 73)

name fw_services comment

<firewall_application> (on page 49)

name standard_ports

<firewall_user> (on page 49)

name

<firewall_user_group> (on page 49)

<firewall_user_ref> name

<custom_property> (on page 46)

property_name property_value

<ips_rule_group> subelements

<ips_rule> (on page 61)

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

<business_model> subelements

<application> (on page 32)

<host_ref> <ip_range_ref>

name dependency owner comment

<business_unit> (on page 43)

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

name owner comment

<damage> (on page 46)

<application_ref> <host_ref>

name effect per_member value rate

<dependency> (on page 47)

<source> <destination>

name effect any

<regulation> (on page 68)

<application_ref> name effect value rate




<business_impact_type> (on page 41)

<application_ref> name effect value rate

<location> (on page 62)

<network_ref> <location_ref>

name

<threat> (on page 77)

<application_ref> <host_ref> <network_ref>

name probability skill value

<threat_group> (on page 78)

<threat_ref> name

<dependency> subelements

<source> (on page 74)


effect

<destination> (on page 48)


effect

<..._ref> subelements

<address_object_ref> (on page 32)

name

<application_ref> (on page 33)

name

<asset_ref> (on page 41)

ip unique_tag

<business_unit_ref> (on page 44)

name

<firewall_user_ref> (on page 50)

name

<group_ref> (on page 50)

name

<host_ref> (on page 55)

ip unique_tag

<ip_range_ref> (on page 58)

ip

<location_ref> (on page 62)

name

<network_ref> (on page 67)

ip

<service_object_ref> (on page 73)

name

<threat_ref> (on page 78)

name



Hierarchical order of iXML elements The following lists the iXML elements in hierarchical order.

For clarity, the closing tags (for example, </asset>) are omitted. An element (for example, <host_ref>) 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_user> <firewall_user_group> <firewall_user_ref> <host_group> <host_ref> Note: At least 1 instance per <host_group> <asset_category> <asset_ref> Note: At least 1 instance per <asset_category> <asset_group> <asset_ref> Note: At least 1 instance per <asset_group> <vpn_tunnel> <config_check_result> <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 DOCUMENTS This section contains the following iXML code examples:

› Example of iXML code for network and business models (on page 23) › Example of iXML code for an L2 firewall (on page 25) › Example of iXML code for VPN (on page 26) › Example of iXML code for an IPS device (on page 27) › Example of iXML code for an Application and Service Repository (on page 28)

Example of iXML code for network and business models The following is 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, 2014 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-2014-0899" definition="CVE" policy="My local network scan"/> </service> <service banner="FTP" port="21/TCP"> <vulnerability_occurrence id="CVE-2014-0899" definition="CVE" policy="My local network scan"/> </service> <service banner="telnet" port="23/TCP"> <vulnerability_occurrence id="CVE-2014-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-2014-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 is an example of iXML code for creating an L2 firewall. To view the Perl script used to create this iXML code, see Perl script for creating an L2 firewall (on page 86). <?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 The following is an example of iXML code for modeling a VPN network. <?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 is an example of iXML code for an IPS device that includes the specification of an L2 IPS device.

The device has 2 IPS access rules, each of which 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" /> network="16.0.0.0/24" <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 an Application and Service Repository You can enter the data for the Application and 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.

The following is an example of iXML code for this conversion.

3 Import the iXML to Skybox using any of the Import tasks. <?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 of 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 A unique ID (for the asset containing this access rule) that is used to sort the access rules in ascending order. 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. • 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. • 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 any of the following: • 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. For a list of possible values, see Enum for the Access/NAT rule direction parameter (on page 149).

chain The name of the rule chain to which the access rule belongs. Rule chain names are defined in the <asset> element (on page 36).

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

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




source_orig_text The source as it appeared in the configuration file.

destination_orig_text

The destination as it appeared in the configuration file.

service_orig_text The service as it appeared in the configuration file.

orig_text The rule as it appeared in the configuration file.

implied Specifies whether the rule is implied. • true • false (default)

disabled Specifies whether the rule is disabled. • true • false (default)

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

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

comment A free-form user comment.

uid The unique ID of this rule (used when comparing routing rules).

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.

loggable A Boolean specifying whether the access rule is loggable. (The value is TRUE by default.)

is_negated_source

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

is_negated_destination

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

is_negated_service

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

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

routed_interface (Cisco firewalls only) The egress interface configured in the NAT rule. Note: When an egress interface is provided, no route lookup is done.



See also

› <asset> element (on page 36) › <nat_rule> element (on page 63) › <routing_rule> element (on page 68) › AddAccessRule method (on page 88) › AddComment method (on page 98) › The Assets topic in the Skybox Reference Guide › SetRuleVpnValue method (on page 148)

<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 36)

<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.



Attribute Description Note: At least 1 of the ip_ranges and domains attributes must be included in the element.

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

Note: At least 1 of the ip_ranges and domains attributes must be included in the element.


See also

› <access_rule> element (on page 29) › <asset> element (on page 36)

<address_object_ref> element


Description The <address_object_ref> element references a specific 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 31)

<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 lines of the definition file). For information about creating this script, see Modeling a Business Asset Group that is based on a network (on page 153).

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


name The name of the Business Asset Group to add.

dependency Specifies how the security of the Business Asset Group depends on the security of its member assets. • Default • Simple • None

For an explanation of these values, see Enum for the Business Asset Group dependency parameter (on page 149).

owner The name of the owner of the Business Asset Group.


See also

› <application_ref> element (on page 33) › <host_ref> element (on page 55) › <ip_range_ref> element (on page 58) › AddApplication method (on page 92)

<application_ref> element


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

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


name The name of the Business Asset Group to which to refer.

See also

› <application> element (on page 32)



› AddApplicationBusinessImpactTypeRef method (on page 93) › AddApplicationRef method (on page 93) › AddApplicationRegulationRef method (on page 94)

<app_conf_item> element


Description The <app_conf_item> element adds an application object to the repository of application and service objects 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 35) › Example of iXML code for an Application and Service Repository (on page 28)

<app_conf_item_ref> element


Description The <app_conf_item_ref> element references a specific 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 34) › <app_group_conf_item> element (on page 35)

<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 repository of application and service objects 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.


See also

› Example of iXML code for an Application and Service Repository (on page 28) › <app_conf_item> element (on page 34) › <app_group_conf_item_ref> element (on page 35)

<app_group_conf_item_ref> element




Description The <app_group_conf_item_ref> element references a specific 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 35)

<asset> element 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> <custom_property> <address_group_object> <address_object> <service_group_object> <service_object> <firewall_application> <firewall_user> <firewall_user_group> </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 name of the asset to add. Note: The equivalent <host> element attribute is



Attribute Description hostname. Optionally, specify the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID

Note: Multiple names must be comma-separated. 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 types of assets)

dynamic_routing Specifies whether dynamic routing is enabled. • true • false (default)

Note: This attribute is applicable only if the value of type is Router.

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

do_not_outdate Specifies whether the asset is protected against aging. • true • false (default)

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 of time as Down and later remove 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 the value of type



Attribute Description is 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 the value of type is Firewall.

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

last_scan_time The last scan time of the asset. The time 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 when the assetname (or IP address) might not be a unique identifier in the network. Alternatively, use it when your organization has a unique ID for each asset (based on some 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 owner of the asset.


is_virtual Specifies whether the asset is a virtual machine. • true • false (default)

is_distributed Specifies whether the asset is a distributed virtual switch. • true • false (default)

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

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

domain The domain of the asset. If this field is empty, the asset is not part of a domain or is part of an unknown domain.

user The user that is associated with the asset.

last_login_time The date and time of the last login to the asset. The time 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.

See also

› <access_rule> element (on page 29) › <interface> element (on page 56) › <nat_rule> element (on page 63) › <routing_rule> element (on page 68) › <service> element (on page 71) › <vulnerability_occurrence> element (on page 82) › <patch> element (on page 67) › <vpn_unit> element (on page 80) › <ips_access_rule> element (on page 58) › <ips_rule_group> element (on page 60) › <vrouter> element (on page 80) › <config_file> element (on page 45) › <custom_property> element (on page 46) › <address_group_object> element (on page 31) › <address_object> element (on page 31) › <service_group_object> element (on page 72) › <service_object> element (on page 73) › <firewall_application> element (on page 49) › <firewall_user> element (on page 49) › <firewall_user_group> element (on page 49) › <host_ref> element (on page 55) › <asset_ref> element (on page 41) › Banners (on page 72) › AddComment method (on page 98) › AddConfigFile method (on page 99) › AddHost method (on page 108) › SetLastScanTime method (on page 146) › SetEntityValue method (on page 145) › The Assets topic in the Skybox Reference Guide

<asset_category> element 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> </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 54).)

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


name The name of the asset group to add.

owner The name of the owner of the asset group.


See also

› <group_ref> element (on page 50) › <asset_ref> element (on page 41) › AddHostGroup method (on page 110) › The Asset groups topic in the Skybox Reference Guide

<asset_group> element 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> </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 54).)

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








See also

› <group_ref> element (on page 50) › <asset_ref> element (on page 41) › AddHostGroup method (on page 110) › The Asset groups topic in the Skybox Reference Guide

<asset_ref> element


Description The <asset_ref> element references a specific asset.

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

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


ip The name or IP address of the asset to which to refer.

unique_tag Add this attribute to an <asset_ref> element when the IP address might not be a unique identifier in the network. Alternatively, use it when your organization has a unique ID for each asset (based on some 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 36) › AddHostRef method (on page 111)

<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 (for example, mission-critical damage or low-level financial damage) 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 to add.

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 149).

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 33) › AddBusinessImpactType method (on page 95)

<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 13)).



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

Attributes The <business_model> element has no attributes.

See also

› <application> element (on page 32) › <business_unit> element (on page 43) › <damage> element (on page 46) › <dependency> element (on page 47) › <regulation> element (on page 68) › <business_impact_type> element (on page 41) › <location> element (on page 62) › <threat> element (on page 77) › <threat_group> element (on page 78)

<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 to add.

owner The name of the owner of the Business Unit.


See also

› <application_ref> element (on page 33) › <business_unit_ref> element (on page 44)



› <group_ref> element (on page 50) › <location_ref> element (on page 62) › AddBusinessUnit method (on page 96)

<business_unit_ref> element


Description The <business_unit_ref> element references a specific Business Unit.

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


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

See also

› <business_unit> element (on page 43) › AddBusinessUnitRef method (on page 97)

<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 is used 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 Date and time of analysis, in the following format: • MMM dd, yyyy HH:mm

file_name The configuration file in which the violation is found.

line_number The number of the line in the configuration file in which the violation is found, if relevant.

actual_result A string that describes the violation.

See also

› <network_model> element (on page 66) › <host_ref> element (on page 55)

<config_file> element


Description The <config_file> element retrieves the original configuration file of an existing 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 36) › AddConfigFile method (on page 99)

<creation_time> element


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

Use only 1 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, the creation_time attribute is used.



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


time The creation time of the model. The time 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 57) › SetCreationTime method (on page 143)

<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 to add.

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 149).

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 33) › AddDamage method (on page 101)

<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 requires 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 to add.




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 is liable to cause the type of 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 48) › <source> element (on page 74) › AddDependency method (on page 102) › The Adding dependency rules topic in the Skybox Vulnerability Control User’s

Guide

<destination> element

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

Description The <destination> element supplies a destination for a dependency. The destination is the effect of possible damage (for example, an availability loss on the Back End Payment System).

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


effect Dependency effect on destination. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

See also

› <dependency> element (on page 47) › <source> element (on page 74) › <application_ref> element (on page 33) › <host_ref> element (on page 55) › AddDependency method (on page 102)



› AddDependencyDestination method (on page 104) › AddDependencySource method (on page 104)

<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 Name of the firewall application.

standard_ports A comma-separated list of ports (for example, 1-65535/80/TCP)

See also


<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 to add.

See also

› <firewall_user> element (on page 49) › <asset> element (on page 36)

<firewall_user_ref> element


Description The <firewall_user_ref> element references a specific firewall user.

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


name The name of the firewall user to which to refer.

See also

› <firewall_user> element (on page 49)

<group_ref> element


Description The <group_ref> element references a specific asset group.

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


name The name of the asset group to which to refer.



See also

› <host_group> element (on page 54) › <asset_category> element (on page 39) › <asset_group> element (on page 40) › AddGroupRef method (on page 108)

<host> element The <host> element is superseded by the <asset> element (see page 36). 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> <custom_property> <address_group_object> <address_object> <service_group_object> <service_object> <firewall_application> <firewall_user> <firewall_user_group> </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 name of the asset to add. Note: The equivalent <asset> element attribute (see page 36) is assetname. Optionally, specify the type of the name: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID







Note: This attribute is applicable only if the value of type is Router.

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

do_not_outdate Specifies whether the asset is protected against aging. • true • false (default)


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 the value of type is 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 the value of type is Firewall.





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


unique_tag Add this attribute to an asset when the hostname (or IP address) might not be a unique identifier in the network. Alternatively, use it when your organization has a unique ID for each asset (based on some 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 owner of the asset.


is_virtual Specifies whether the asset is a virtual machine. • true • false (default)

is_distributed Specifies whether the asset is a distributed virtual switch. • true • false (default)

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

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

domain The domain of the asset. If this field is empty, the asset is not part of a domain or is part of an unknown domain.

user The user that is associated with the asset.

last_login_time The date and time of the last login to the asset. The time 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.

See also

› <asset> element (on page 36) › <access_rule> element (on page 29) › <interface> element (on page 56) › <nat_rule> element (on page 63)



› <routing_rule> element (on page 68) › <service> element (on page 71) › <vulnerability_occurrence> element (on page 82) › <patch> element (on page 67) › <vpn_unit> element (on page 80) › <ips_access_rule> element (on page 58) › <ips_rule_group> element (on page 60) › <host_ref> element (on page 55) › <vrouter> element (on page 80) › <config_file> element (on page 45) › <custom_property> element (on page 46) › <address_group_object> element (on page 31) › <address_object> element (on page 31) › <firewall_application> element (on page 49) › <firewall_user> element (on page 49) › <firewall_user_group> element (on page 49) › <service_group_object> element (on page 72) › <service_object> element (on page 73) › Banners (on page 72) › AddComment method (on page 98) › AddConfigFile method (on page 99) › AddHost method (on page 108) › SetLastScanTime method (on page 146) › SetEntityValue method (on page 145) › The Assets topic in the Skybox Reference Guide

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

Syntax with 1st-level subelements <host_group> <host_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 to add. • Location • Generic (default) • Role • Cluster • Application • BusinessUnit • DeviceFolder • MAP_GROUP • VirtualFirewallGroup • NetworkGroup • VirtualizationHost • VirtualizationCluster • VirtualizationDataCenter



See also

› <asset_category> element (on page 39) › <asset_group> element (on page 40) › <group_ref> element (on page 50) › <host_ref> element (on page 55) › AddHostGroup method (on page 110) › The Asset groups topic in the Skybox Reference Guide

<host_ref> element


Description The <host_ref> element references a specific 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 when the IP address might not be a unique identifier in the network. Alternatively, use it when your organization has a unique ID for each asset (based on some 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 36) › AddHostRef method (on page 111)

<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 mask of the interface.

locked Specifies whether to lock the interface to a network. • true • false (default)

mac_address The MAC address of the interface. Note: This attribute is applicable only if the value of type is 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 type of the interface. For a list of possible values, see Enum for the network interface type parameter (on page 151). The default value is Ethernet.

is_primary Specifies whether this is the primary interface of the network. • true • false (default)

layer2 Specifies whether this is an L2 interface. • true • false (default)


zone The zone of the interface.

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





Note: In the GUI, you can define several virtual interfaces with the same IP address for the same device. This is not possible when using 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 several interfaces with the same IP address.

See also

› <asset> element (on page 36) › AddComment method (on page 98) › AddInterface method (on page 112) › The Network interfaces section in the Skybox Reference Guide › SetEntityValue method (on page 145)

<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 13)).

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 1 <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 Version of the model.

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




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

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

See also

› <business_model> element (on page 42) › <creation_time> element (on page 45) › <network_model> element (on page 66) › IntegrationSecurityModel method (on page 139) › SetCreationTime method (on page 143) › SetLastScanTime method (on page 146) › SetDiscoveryMethod method (on page 144)

<ip_range_ref> element


Description The <ip_range_ref> element references a specific 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. When specifying an address range, use the start and end addresses separated by a hyphen.

See also

› AddIPRangeRef method (on page 113)

<ips_access_rule> element




Description The <ips_access_rule> element 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 additional information, see the IPS support in Skybox section in the Skybox Vulnerability Control User’s 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 access rule). If this attribute is not included, a value is assigned.


The default value is ANY.


The default value is ANY.

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



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

For a list of possible values, see Enum for the Access/NAT rule direction parameter (on page 149).

chain The name of the rule chain. Rule chain names are defined in the <asset> element (on page 36). The default value is IPS.

applied_interfaces A semicolon-separated list of the IP addresses or interface names of the network interfaces for the 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 rule. • IP address ranges are not permitted.

The default is all interfaces.

ips_rule_group_ref

The name of the associated <ips_rule_group> element (see page 60).












See also

› <asset> element (on page 36) › <ips_rule_group> element (on page 60) › AddIpsAccessRule method (on page 114) › AddIpsRuleGroup method (on page 118) › 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 to add. The name must be the same as the ips_rule_group_ref attribute of the <ips_access_rule> element (see page 60).

See also

› <asset> element (on page 36) › <ips_access_rule> element (on page 58) › AddIpsAccessRule method (on page 114)



› AddIpsRuleGroup method (on page 118) › 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 as it appeared in the configuration file.

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

FN_original The probability of a false negative as it appeared in the configuration file.

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


severity_original The severity as it appeared 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 151).




You must give a value to 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 give a value to either vendor_rule_id or vulnerabilities.


See also

› <ips_rule_group> element (on page 60) › AddIpsRule method (on page 116) › 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 to add.

See also

› <location_ref> element (on page 62) › AddLocation method (on page 119)

<location_ref> element


Description The <location_ref> element references a specific location.



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


name The name of the location to which to refer.

See also

› <location> element (on page 62) › AddLocationRef method (on page 119)

<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 this NAT rule). If this attribute is not included, a value is assigned.





service The NAT rule service. The format can be any of the following: • 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. For a list of possible values, see Enum for the



Attribute Description Access/NAT rule direction parameter (on page 149).

chain The name of the rule chain to which to add this NAT rule. Rule chain names are defined in the <asset> element (on page 36). Note: Rules are added in the order in which they appear in the iXML.

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

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









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.

See also

› <asset> element (on page 36) › <access_rule> element (on page 29) › <routing_rule> element (on page 68) › AddComment method (on page 98) › AddNatRule method (on page 120) › 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 mask of the network.

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

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

do_not_outdate Specifies whether the network is protected against aging. • true • false (default)

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 of time as Down and later remove 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.

source_excluded_ip_ranges


destination_alternative_ip_ranges


destination_excluded_ip_ranges


owner The name of the owner of the network.




See also

› <network_ref> element (on page 67) › <segment> element (on page 69) › AddComment method (on page 98) › AddNetwork method (on page 122) › SetCloudDestinationAlternativeIPRanges method (on page 140) › SetCloudDestinationExcludedIPRanges method (on page 141) › SetCloudSourceAlternativeIPRanges method (on page 142) › SetCloudSourceExcludedIPRanges method (on page 142) › SetEntityValue method (on page 145) › SetLastScanTime method (on page 146) › 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 13)).

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

Attributes The <network_model> element has no attributes.

See also

› <host_group> element (on page 54) › <asset_category> element (on page 39) › <asset_group> element (on page 40) › <asset> element (on page 36) › <network> element (on page 65) › <vpn_tunnel> element (on page 79) › <config_check_result> element (on page 44)



<network_ref> element


Description The <network_ref> element references a specific network.

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


ip The IP address of the network to which to refer.

See also

› <network> element (on page 65) › AddNetworkRef method (on page 123)

<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). • For information about permitted values, see the note

following the table. code The patch code (patch ID).


Note: The value of the product attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

See also

› AddComment method (on page 98) › AddPatch method (on page 124)



<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 (for example, SOX or GLBA).

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


name The name of the Regulation to add.

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 33) › AddRegulation method (on page 125)

<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.

gateway The gateway IP address.

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

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 following a match are discarded).


See also

› <asset> element (on page 36) › <access_rule> element (on page 29) › <nat_rule> element (on page 63) › <vrouter> element (on page 80) › AddComment method (on page 98) › AddRoutingRule method (on page 126) › The Assets topic in the Skybox Reference Guide › The Specifying routing rules section in the Skybox Reference Guide

<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 be added to the network.




type The type of the segment. • 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 types of port groups.

is_virtual Specifies whether the segment represents a virtual network. • true • false (default)

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 when the segment is not 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. • true • false (default)

other_names Additional names for the segment. Optionally, specify the types of the names: • WINS • DNS • GENERATED • OTHER • SYSNAME (default) • VM_NAME • VM_UNIQUE_ID



See also

› <host_ref> element (on page 55)



› <ip_range_ref> element (on page 58) › AddComment method (on page 98) › AddSegment method (on page 128)

<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 to decide which 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 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 last scan time of the service. The time format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

status • Up • Down • Unknown


Note: The value of the banner attribute must match a regular expression in the <Skybox_Home>\data\dictionary\OSFingerprints.xml Dictionary file. (This file includes examples for each regular expression.)

See also

› <asset> element (on page 36) › <vulnerability_occurrence> element (on page 82) › AddComment method (on page 98) › AddService method (on page 129) › SetEntityValue method (on page 145) › SetLastScanTime method (on page 146)



› The Services topic in the Skybox Reference Guide

Banners The banner is a service-related text field that is processed as part of the offline file import or online collection process. The banner helps Skybox to identify details of the product that is running this specific 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 to see whether it contains the vendor name, product name, version, or other useful information (for example, the name and version of the asset’s operating system). Successful product identification using the banner field enables Skybox to more precisely model the service. The value 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 product cannot be identified are classified as Generic.

The following are some examples of banner strings and the information that Skybox extracts from them:

› 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’s 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 product 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 any of the following: • Source port, destination port, and protocol, separated



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

See also

› <asset> element (on page 36) › <access_rule> element (on page 29) › AddServiceObject method (on page 130)

<service_object_ref> element




Description The <service_object_ref> element references a specific 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 72)

<source> element

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

Description The <source> element supplies a source for a dependency. The 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 Dependency effect of source. Any combination of: • C (confidentiality) • I (integrity) • A (availability)

See also

› <dependency> element (on page 47) › <destination> element (on page 48) › <application_ref> element (on page 33) › <host_ref> element (on page 55) › AddDependency method (on page 102) › AddDependencyDestination method (on page 104) › AddDependencySource method (on page 104)



<srv_conf_item> element


Description The <srv_conf_item> element adds a service object to the repository of application and service objects 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 76) › Example of iXML code for an Application and Service Repository (on page 28)

<srv_conf_item_ref> element


Description The <srv_conf_item_ref> element references a specific 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 75) › <srv_group_conf_item> element (on page 76)

<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 repository of application and service objects 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 an Application and Service Repository (on page 28) › <srv_conf_item> element (on page 75) › <srv_group_conf_item_ref> element (on page 76)

<srv_group_conf_item_ref> element




Description The <srv_group_conf_item_ref> element references a specific service 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 76)

<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 the GUI, 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 to add.

probability Probability of threat. For a list of possible values, see Enum for the threat probability parameter (on page 151).

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

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

See also

› <threat_group> element (on page 78) › <threat_ref> element (on page 78)



› AddThreat method (on page 132)

<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 the GUI, 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 to add.

See also

› <threat> element (on page 77) › <threat_ref> element (on page 78)

<threat_ref> element


Description The <threat_ref> element references a specific threat.

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


name The name of the threat to which to refer.

See also

› <threat> element (on page 77) › <threat_group> element (on page 78) › AddThreatRef method (on page 132)



<vpn_tunnel> element


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

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





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

endpoint1 The 1st endpoint of the VPN tunnel.

endpoint2 The 2nd endpoint of the VPN tunnel.

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

display_as_cloud Specifies whether the VPN tunnel should be displayed as a cloud.

do_not_outdate Specifies whether the VPN tunnel network is protected against aging. • true • false (default)

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 of time as Down and later remove 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 80) › AddVpnTunnel method (on page 133) › SetLastScanTime method (on page 146)



<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.

original_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 79) › AddVpnUnit method (on page 134)

<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 to add. The name must be the same as the vrouter attribute of the <routing_rule> element (see page 68) and the <interface> element (see page 56).



See also

› <asset> element (on page 36) › <routing_rule> element (on page 68) › <interface> element (on page 56) › AddVrouter method (on page 136)

<vulnerability> element The <vulnerability> element is superseded by the <vulnerability_occurrence> element (see page 82). 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 82) is definition. For a list of possible values, see Enum for the definition parameter (on page 151).

id The ID of the Vulnerability Definition in the database specified by type. This attribute must take a numeric value.

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 the GUI in the following 2 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 152)).

• The <type, id> pair is not in the Vulnerability Dictionary. (The vulnerability occurrence is mapped to




ID 3326 (UNCATALOGED) 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 time 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

A description of the vulnerability occurrence. If provided, overwrites the Vulnerability Dictionary description of custom Vulnerability Definitions only.


See also

› <vulnerability_occurrence> element (on page 82) › <asset> element (on page 36) › <service> element (on page 71) › AddComment method (on page 98) › AddCustomVulnerability method (on page 100) › AddVulnerability method (on page 136) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 152)

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

<vulnerability_occurrence> element 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 151).

id The ID of the Vulnerability Definition in the database specified by definition. This attribute must take a numeric value.

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 the GUI in the following 2 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 152)).

• The <definition, id> pair is not in the Vulnerability Dictionary. (The vulnerability occurrence is mapped to ID 3326 (UNCATALOGED) 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 last scan time of the vulnerability occurrence. The time 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

A description of the vulnerability occurrence. If provided, overwrites the Vulnerability Dictionary description of custom Vulnerability Definitions only.


See also

› <asset> element (on page 36) › <service> element (on page 71) › AddComment method (on page 98) › AddCustomVulnerability method (on page 100) › AddVulnerability method (on page 136) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 152)

(for custom Vulnerability Definitions) › SetLastScanTime method (on page 146) › 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 specific 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 12).

In this chapter

Parameters of API methods .................................................. 85

API methods and generated iXML code .................................. 85

Examples of Perl scripts ....................................................... 86

Mandatory include statements for Perl scripts ......................... 87

Description of Perl API methods ............................................ 88

Enums for parameters of API methods.................................. 149

PARAMETERS OF API METHODS The parameters of an API method must be specified in the order that they appear in the description of the API method or specified by name. If a parameter is specified by name, all following parameters must also be specified by name.

Parameters must be enclosed 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 generate iXML code in addition to the code that the method normally generates.

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

› A <business_model> element is generated upon the 1st occurrence in the file of an AddApplication, AddDamage, AddThreat, AddDependency, AddLocation,

Perl API methods



or AddBusinessUnit method. Only 1 <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 108) sets most of the attributes of an <asset> element (see page 36) and the AddService method (see page 129) sets most of the attributes of a <service> element (see page 71). However, some attributes cannot be added using these methods. Occasionally, there are special methods for these attributes (for example, the SetCloudDestinationAlternativeIPRanges (see page 140) method), but attributes can always be added (or modified) using the SetEntityValue method (see page 145).

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 To view the iXML code output by the following script, see Example of iXML code for an L2 firewall (on page 25). ################################################################## # # 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 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");

Chapter 4 Perl API methods


# 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

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;



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.

Multiple instances of this method can appear 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 any of the following: • 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. For a list of possible values, see Enum for the Access/NAT rule direction parameter (on page 149).




chain (Optional) The rule change to which the access rule is appended. Rule chain names are defined in the AddHost method (on page 108).

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 some other setting in the device configuration (and not explicitly defined by the user). • true • false (default)

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) The 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 value is FALSE by default.

is_negated_destination

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

is_negated_service

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

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

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 145). For a complete list of access rule attributes, see <access_rule> element (see page 29).

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 108) › AddNatRule method (on page 120) › AddRoutingRule method (on page 126) › <access_rule> element (on page 29) › <asset> element (on page 36) › 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: A value for at least 1 of the ip_ranges and domains parameters must be included.

name The name of the address object to add.

domains A semicolon-separated list of domain names. Note: A value for at least 1 of the ip_ranges and domains parameters must be included.

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 36) › <address_object> element (on page 31)

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




› <address_group_object> element (on page 31)

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 specific 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 153).

Multiple instances of this method can appear per file.

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


name The name of the Business Asset Group to add.

dependency Specifies how the security of the Business Asset Group depends on the security of its member assets. • Default (default) • Simple • None

For an explanation of these values, see Enum for the Business Asset Group dependency parameter (on page 149).

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 93) › AddHostRef method (on page 111) › <application> element (on page 32) › <application_ref> element (on page 33)



› <host_ref> element (on page 55)

AddApplicationBusinessImpactTypeRef method

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

Description The AddApplicationBusinessImpactTypeRef method attaches an existing 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 95) › <application_ref> element (on page 33)

AddApplicationRef method

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



Description The AddApplicationRef method attaches an existing 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 92) › AddDamage method (on page 101) › AddThreat method (on page 132) › <application_ref> element (on page 33)

AddApplicationRegulationRef method

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

Description The AddApplicationRegulationRef method attaches an existing 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 125) › <application_ref> element (on page 33)

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:



Parameter Description • 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 149).

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 41)

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 to add.



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 93) › AddBusinessUnitRef method (on page 97) › AddGroupRef method (on page 108) › AddLocationRef method (on page 119) › <application_ref> element (on page 33) › <business_unit> element (on page 43) › <business_unit_ref> element (on page 44) › <group_ref> element (on page 50) › <location_ref> element (on page 62)

AddBusinessUnitRef method

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

Description The AddBusinessUnitRef method attaches an existing 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 96) › <business_unit_ref> element (on page 44)

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 1 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 29) › <application> element (on page 32) › <business_unit> element (on page 43)



› <host_group> element (on page 54) › <asset_category> element (on page 39) › <asset_group> element (on page 40) › <asset> element (on page 36) › <interface> element (on page 56) › <ips_access_rule> element (on page 58) › <ips_rule> element (on page 61) › <nat_rule> element (on page 63) › <network> element (on page 65) › <patch> element (on page 67) › <routing_rule> element (on page 68) › <segment> element (on page 69) › <service> element (on page 71) › <vpn_tunnel> element (on page 79) › <vulnerability_occurrence> element (on page 82)

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 existing 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 be added 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 AddVrouter method:



<config_file path="path1" />

See also

› AddHost method (on page 108) › <config_file> element (on page 45)

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 151).

id The ID of the Vulnerability Definition of the vulnerability occurrence in the external vulnerability database specified by type. This parameter must take a numeric value.

sbv_id The ID of the Vulnerability Definition of the vulnerability occurrence in the Skybox Vulnerability Dictionary. You must use the ID of a generic Vulnerability Definition; for a list of valid values, see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 152). Any other value is mapped to ID 3326 (UNCATALOGED) and the Vulnerability Definition is not used by Skybox during attack simulation.

title (Optional) A title for the vulnerability occurrence.



Parameter Description If provided, this value is used in the GUI. Otherwise, the name associated with sbv_id is used (see Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 152)).

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 AddVulnerability method: <vulnerability_occurrence definition="NESSUS" id="102006" sbv_id="3504" />

See also

› <vulnerability_occurrence> element (on page 82) › AddHost method (on page 108) › AddService method (on page 129) › AddVulnerability method (on page 136) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 152) › 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 is liable to cause 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 46)

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 requires 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 to add.


any Specifies whether compromise of member assets or network entities is liable to cause 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 104) › AddDependencySource method (on page 104) › <dependency> element (on page 47) › <destination> element (on page 48) › <source> element (on page 74)



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 the Back End 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 102) › AddDependencySource method (on page 104) › <destination> element (on page 48)

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 102) › AddDependencyDestination method (on page 104) › <source> element (on page 74)

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.

Multiple instances of this method can appear 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 to add.

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 108) › <asset> element (on page 36) › <firewall_application> element (on page 49)

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 to add.

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 108) › <asset> element (on page 36) › <firewall_user> element (on page 49)

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 to add.

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 108)



› <asset> element (on page 36) › <firewall_user_group> element (on page 49)

AddGroupRef method

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

Description The AddGroupRef method attaches an existing 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 110) › <group_ref> element (on page 50)

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 to add. 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 the value of type is 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 the value of type is Firewall.



Note: This parameter is applicable only if the value of type is Router.

do_not_outdate Specifies whether the asset is protected against aging. • true • false





layer2 Specifies whether the asset is an L2 gateway. Note: An L2 gateway must have at least 1 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 145). For a complete list of asset attributes, see <asset> element (on page 36).

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 36) › Banners (on page 72) › 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 111) › <host_group> element (on page 54) › <asset_category> element (on page 39) › <asset_group> element (on page 40) › <host_ref> element (on page 55) › 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 a specific 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 92) › AddDamage method (on page 101) › AddThreat method (on page 132) › <host_ref> element (on page 55)

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 1 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 mask 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 the value of type is Ethernet.

name The name of the interface.

type The type of the interface. For a list of possible values, see Enum for the network interface type parameter (on page 151). 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. • true • false (default)

When 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. • true • false (default)

layer_2 Specifies whether this is an L2 interface. • true • false (default)

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. • true • false (default)

Note: In the GUI, you can define several virtual interfaces with the same IP address for the same device. This does not work when using 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 several interfaces with the same IP address.

Some <interface> element attributes (for example, comment) are not included in the AddInterface method. You can add these attributes using the SetEntityValue method (see page 145). For a complete list of interface attributes, see <interface> element (on page 56).

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 108) › <interface> element (on page 56) › 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 a specific IP address range.

Multiple instances of this method can appear 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 92) › <ip_range_ref> element (on page 58)

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 additional information, see the IPS support in Skybox topic in the Skybox Vulnerability Control User’s Guide.

Use at least 1 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 can be any of the following: • 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. direction The access rule direction.

For a list of possible values, see Enum for the Access/NAT rule direction parameter (on page 149).

chain (Optional) The name of the rule chain. Rule chain names are defined in the AddHost method (on page 108).

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.











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 36) › <ips_rule_group> element (on page 60) › <ips_access_rule> element (on page 58) › AddIpsRuleGroup method (on page 118) › 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.

Multiple instances of this method can appear 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 as it appeared in the configuration file.

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

fn_original The probability of a false negative as it appeared in the configuration file.

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

severity_original The severity as it appeared 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 which this rule applies. For a list of possible vendor vulnerability databases, see Enum for the definition parameter (on page 151). 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 vendor_rule_id or vulnerabilities.

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 61) › <ips_rule_group> element (on page 60) › 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 to add. 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 114)).

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




› <ips_rule_group> element (on page 60) › <ips_access_rule> element (on page 58) › AddIpsAccessRule method (on page 114) › 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 to add.

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 62)

AddLocationRef method

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

Description The AddLocationRef method references a specific location.

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




entity A reference to the entity returned by, for example, the AddLocation method (see page 119).

name The name of the location to which to refer.

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 119) › <location_ref> element (on page 62)

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 can be any of the following: • Source port, destination port, and protocol, comma-



Parameter Description 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. For a list of possible values, see Enum for the Access/NAT rule direction parameter (on page 149).

chain The name of the chain to which the rule belongs. Rule chain names are defined in the AddHost method (see page 108).

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.



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 108) › AddAccessRule method (on page 88) › AddRoutingRule method (on page 126) › <nat_rule> element (on page 63)



› <asset> element (on page 36) › 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 type of the network. For a list of possible values, see Enum for the network type parameter (on page 151). 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 of time as Down and later remove them from the model. Important: Usually, networks imported using iXML are not updated on a regular basis so should not be aged and outdated (that is, set this flag to true).

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 65) › The Networks 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 specific 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 network to which to refer.

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 92) › AddDamage method (on page 101) › AddThreat method (on page 132) › <network_ref> element (on page 67)

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 1 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 32) › <business_unit> element (on page 43) › <host_group> element (on page 54) › <asset_category> element (on page 39) › <asset_group> element (on page 40) › <asset> element (on page 36) › <network> element (on page 65)

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 Patch code (patch ID).

product Product banner (of the product to which the patch is applied).



Parameter Description • For information about permitted values, see the note

following the table.

Note: The value of 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, "Q823559", "Microsoft Windows XP SP1");

iXML code generated The following iXML code is generated by the preceding example of the AddPatch method: <patch code="Q823559" product="Microsoft Windows XP SP1" />

See also

› <patch> element (on page 67) › AddHost method (on page 108) › 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 (for example, SOX or GLBA).


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


name The name of the Regulation to add.

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 149).

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 68)

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. • true • false (default)




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 following a match 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 108) › <asset> element (on page 36) › <vrouter> element (on page 80) › The Assets topic in the Skybox Reference Guide › The Specifying routing rules section 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’s properties as they appeared in the configuration file).

Use only 1 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.





source_orig_text (Optional) The source as it appeared in the configuration file.


(Optional) The destination as it appeared in the configuration file.

service_orig_text (Optional) The service as it appeared 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 88) › AddNatRule method (on page 120) › <access_rule> element (on page 29) › <nat_rule> element (on page 63)

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.

Multiple instances of this method can appear 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 122) › <segment> element (on page 69)

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 to decide which 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 value of 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 (for example, last_scan_time and comment) are not included in the AddService method. You can add these attributes using the SetEntityValue method (see page 145). For a complete list of service attributes, see <service> element (on page 71).

Note: You can set the last scan time with the SetLastScanTime method (see page 146).



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 108) › <service> element (on page 71) › Banners (on page 72) › 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 any of the following: • 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 29) › <asset> element (on page 36) › <service_object> element (on page 73)

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




› <service_group_object> element (on page 72)

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 to add.

probability Probability of the threat. For a list of possible values, see Enum for the threat probability parameter (on page 151).

skill Skill required to actualize the threat. • low • medium • high

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

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 132) › <threat> element (on page 77)

AddThreatRef method

Syntax The syntax of the Perl AddThreatRef method is:



AddThreatRef(threat, name)

Description The AddThreatRef method references a specific 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 threat to which to refer.

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 132) › <threat_ref> element (on page 78)

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 network to the model.


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







netmask The mask of the network.

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

endpoint1 The 1st endpoint of the VPN tunnel.

endpoint2 The 2nd endpoint of the VPN tunnel.

do_not_outdate Specifies whether the VPN tunnel network is protected against aging. • true • false

Entities in a network that is not marked as protected against aging are checked to see how much time has passed since they were updated. If they were not updated for more than a specific period of time, they are removed from the model. Important: Usually, networks imported using iXML are not updated on a regular basis so should not be aged and outdated (that is, set this flag to true).

display_as_cloud Specifies whether the VPN tunnel should be displayed 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 134) › <vpn_tunnel> element (on page 79) › 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 referred to as 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 108) › AddVpnTunnel method (on page 133) › <vpn_unit> element (on page 80) › 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 vrouter (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 108) › <vrouter> element (on page 80)

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 151).

id The ID of the Vulnerability Definition of the vulnerability occurrence in the database specified by type. This parameter must take a numeric value.

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", "2014-9999");

iXML code generated The following iXML code is generated by the preceding example of the AddVulnerability method: <vulnerability_occurrence definition="CVE" id="2014-9999" />

See also

› AddCustomVulnerability method (on page 100) › AddHost method (on page 108) › AddService method (on page 129) › <vulnerability_occurrence> element (on page 82) › 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 1 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 112) › AddNetwork method (on page 122) › AssignInterfaceToSegment method (on page 138) › 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 1 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 112) › AddSegment method (on page 128) › AssignInterfaceToNetwork method (on page 137) › The Network interfaces topic in the Skybox Reference Guide

IntegrationSecurityModel method

Description When adding or modifying a model, the IntegrationSecurityModel method must be called before any other method.

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.

Use only 1 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 57)



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 148)

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 1 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 to add.




$inm->SetCloudDestinationAlternativeIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 122) › SetCloudDestinationExcludedIPRanges method (on page 141) › SetCloudSourceAlternativeIPRanges method (on page 142) › SetCloudSourceExcludedIPRanges method (on page 142) › <network> element (on page 65)

SetCloudDestinationExcludedIPRanges method

Syntax The syntax of the Perl SetCloudDestinationExcludedIPRanges method is: SetCloudDestinationExcludedIPRanges(network, iprange)

Description The SetCloudDestinationAlternativeIPRanges 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 be excluded.

Example The following example uses this method: $inm->SetCloudDestinationExcludedIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 122) › SetCloudDestinationAlternativeIPRanges method (on page 140) › SetCloudSourceAlternativeIPRanges method (on page 142) › SetCloudSourceExcludedIPRanges method (on page 142) › <network> element (on page 65)



SetCloudSourceAlternativeIPRanges method

Syntax The syntax of the Perl SetCloudSourceAlternativeIPRanges method is: SetCloudDestinationAlternativeIPRanges(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 to add.

Example The following example uses this method: $inm->SetCloudSourceAlternativeIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 122) › SetCloudDestinationAlternativeIPRanges method (on page 140) › SetCloudDestinationExcludedIPRanges method (on page 141) › SetCloudSourceExcludedIPRanges method (on page 142) › <network> element (on page 65)

SetCloudSourceExcludedIPRanges method

Syntax The syntax of the Perl SetCloudSourceExcludedIPRanges method is: SetCloudDestinationAlternativeIPRanges(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 be excluded.

Example The following example uses this method: $inm->SetCloudSourceExcludedIPRanges($network1, "192.168.80.0-192.168.80.255");

See also

› AddNetwork method (on page 122) › SetCloudDestinationAlternativeIPRanges method (on page 140) › SetCloudDestinationExcludedIPRanges method (on page 141) › SetCloudSourceAlternativeIPRanges method (on page 142) › <network> element (on page 65)

SetCreationTime method

Syntax The syntax of the Perl SetCreationTime method is: SetCreationTime(time)

Description The SetCreationTime method sets the model’s creation time.

Use only 1 instance of this method per file.

If used, this method must appear immediately after the IntegrationSecurityModel method.

If this method is not used, 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.



Parameter Description The time format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

Example The following example uses this method: $inm->SetCreationTime("Aug 1, 2013 8:30");

iXML code generated The following iXML code is generated by the preceding example of the SetCreationTime method: <creation_time time="Aug 1, 2013 08:30" />

See also

› <creation_time> element (on page 45) › <intermediate_model> element (on page 57) › IntegrationSecurityModel method (on page 139)

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 1 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 150).

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 57)

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 the values of a single 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 added.

attribute The attribute to be changed or added 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: <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 where the name or IP address of the asset might not be unique in the network.



You can use this method when your organization has a unique ID for each asset (based on some 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 1 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 108) › <asset> element (on page 36)

SetLastScanTime method

Syntax The syntax of the Perl SetLastScanTime method is: SetLastScanTime(entity, last_scan_time)

Description The SetLastScanTime method sets the last 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 last scan time is applicable. The entity might be a network, asset, service, or vulnerability occurrence.

last_scan_time The last scan time for the specified entity. The time format is MMM dd, yyyy HH:mm. You can omit leading zeroes.




$inm->SetLastScanTime("myAsset", "Aug 1, 2013 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, 2013 08:30" />

See also

› <asset> element (on page 36) › <intermediate_model> element (on page 57) › <network> element (on page 65) › <service> element (on page 71) › <vulnerability_occurrence> element (on page 82)

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




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 gateway that specifies that data is permitted to pass over 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


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 140)

ENUMS FOR PARAMETERS OF API METHODS This section lists the possible values of enums that are used in the API methods.

Enum for the Access/NAT rule direction parameter The following is a list of possible values for the Access/NAT rule direction parameter:

• Inbound • Outbound • Both (default)

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 when the Default and Simple options of describing dependency are not sufficient.) You must state explicitly how a security loss on each of the member assets affects the Business Asset Group.

Enum for the damage level parameter The following is a list of possible values for the damage level parameter:

• UNDEFINED • VERY_LOW • LOW • MEDIUM



• HIGH • VERY_HIGH

Enum for the discovery method parameter The following is a list of possible values for the discovery method parameter:

• ALTIRIS • BANNER • BIGFIX • CLOUND_MANAGER • CMDB • CONFIG • CONFIG_APPLICATION • CONFIG_PARTIAL • 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_DIRECTOR • VIRTUAL • VIRTUALIZATION_MANAGER • VSHIELD • VSPHERE • VULNERABILITY_DETECTOR • VULNERABILITY_DETECTOR_RPM • VULNERABILITY_SCANNER • WSUS



Enum for the asset type parameter The following is a list of possible values for the asset type parameter:

• Host • Server • Firewall • Router • Workstation • Printer • LoadBalancer • Proxy • NetworkDevice • WirelessDevice • IPS • VirtualizationHost • Switch • Mobile

Enum for the network interface type parameter The following is a list of possible values for the network interface type parameter:

• NAT • Ethernet • WLAN • TokenRing • PPP • Slip • Virtual • Other • Unknown • Loopback • Serial • LoadBalancer • Tunnel • Vpn

Enum for the network type parameter The following is a list of possible values for the network type parameter:

• Cloud • ConnectingCloud • Link • Regular • Tunnel • VpnTunnel • SerialLink

Enum for the threat probability parameter The following is a list of possible values for the threat probability parameter:

• VERY_LOW • LOW • MEDIUM • HIGH • VERY_HIGH

Enum for the definition parameter The following is a list of possible values for the definition parameter:

• 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 ID and title of 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)

11839 Service Detected on Host


Chapter 5

This chapter explains the workflow of specific modeling scenarios.

In this chapter

Modeling load balancers ...................................................... 153

Modeling a Business Asset Group that is based on a network ... 153

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 modeling work is performed by the helper module

Note: If this load balancer has specific 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 or the AddIPRangeRef method 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 currently part of the specified IP address range are included as part of the Business Asset Group.

Specific modeling scenarios



Skybox does not automatically update the association between networks and Business Asset Groups. When you create a Business Asset Group that includes networks, a Model – Integrity task must be run every time 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 retrieve data from Skybox and use its core methods remotely.

Part II: APIs


Chapter 6

Skybox is an open platform that enables integration with external systems including SOC, ticketing systems, and organizational portals.

The Skybox APIs are based on web services, making integration relatively easy and applicable from most programming environments, including Java, .NET, and Perl.

This chapter describes the APIs that you can use for the integration.

In this chapter

APIs ................................................................................. 156

Methods ........................................................................... 156

Connecting to the Skybox APIs ............................................ 164

APIS The main integration APIs are:

› SkyboxAdministrationService (on page 167): Retrieves administrative information or performs administrative actions (for example, launching a Skybox task or reading the Skybox event log)

› SkyboxFirewallChangesService (on page 173): 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)

› SkyboxNetworkService (on page 180): Provides access analysis and Access Policy analysis; you can check access requests for connectivity (Access Analyzer) and see whether they comply with the Access Policy

› SkyboxTicketsService (on page 211): Retrieves and updates Skybox tickets › SkyboxVulnerabilitiesService (on page 242): Retrieves Vulnerability

Definitions, vulnerability occurrences, and threat alert tickets from Skybox

The URL for these web services is: https://<Skybox server>:8443/skybox/webservice/jaxws, where <Skybox server> is the name or IP address of the Server.

METHODS The methods in each web service are described in the following tables.

You can view the WSDL files for each of the web services listed here on the Server machine at the following location, (where <Skybox server> is the name or IP address of the Server):

Introduction to Skybox APIs

Chapter 6 Introduction to Skybox APIs


› https://<Skybox server>:8443/skybox/webservice/jaxws

Note: Each web service includes a testService method (no parameters) which can be used to make sure that the service is running.

Administration web service

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 the user’s information

getEvents (on page 169)

Retrieves a list of events from Skybox

getModelLockStatuses (on page 170)

Returns the lock statuses of all models in the Skybox database: Live, Forensics, What If, and Core

getRunningTaskNames (on page 171)

Returns an array of names of currently running tasks

getServerVersion (on page 171)

Returns the version of the Skybox Server.

launchTaskOrSequence (on page 172)

Launches a Skybox task

ping Pings the Skybox server

For additional information, see Administration API (on page 167).

Firewall Changes web service

Method Description

countFirewallChanges (on page 174)

Counts the number of change records that match the specified filter (date range, firewalls, change reconciliation status, or violation status).

findChangeReconciliationInfo (on page 174)

Returns change reconciliation information for the specified change record (including reconciliation fields, IDs of matched tickets, and matched access requests).

findFirewallChanges (on page 175)

Returns an array containing all the firewall change records that match the search criteria.

getAccessRulesHistory (on page 175)

Retrieves a list of changes to an access rule.

getFirewallChangeDetails (on page 176)

Returns all data related to the specified change record.

setChangeReconciliationInfo (on page 176)

Sets the change reconciliation information for the specified change record (so that you can, for example, update the list of associated tickets).



Method Description

updateFirewallChangeComment (on page 177)

Adds a new comment to the specified firewall change record.

For additional information, see Firewall Changes API (on page 173).

Network web service

Method Description

checkAccess (on page 184)

Activates Skybox’s access analysis from another application. For any combination of source, destination, and port, you can discover whether there is connection and which firewalls allow or deny the connection.

checkAccessV1 (on page 185)

Activates Skybox’s access analysis from another application. For any combination of source, destination, and port, you can discover whether there is connection and which firewalls allow or deny the connection. The method returns the first traceroute describing the path between the source and destination. You can define whether this route should be listed in HTML or XML format.

checkAccessCompliance (on page 187)

Checks whether an access request (source-destination-port) complies with your organization’s Access Policy.

checkRuleCompliance (on page 192)

Checks whether an access request (source-destination-port) complies with your organization’s Rule Policies.

countAssetsByIps (on page 188)

Counts the number of assets that match any of the specified IP address ranges. The output is used for page calculations.

countAssetsByNames (on page 189)

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 189)

Counts the number of access rules that use the specified firewall object. The output is used for page calculations.

createFirewallException (on page 190)

Creates a firewall exception in Skybox.

createRulePolicyException (on page 190)

Creates a Rule Policy exception in Skybox.

deleteFirewallException (on page 191)

Deletes a firewall exception from Skybox.

deleteRulePolicyException (on page 191)

Deletes a Rule Policy exception from Skybox.



Method Description

doCheckRuleCompliance (on page 192)


findAccessRules (on page 193)

Searches for access rules using the same search parameters that are used in the Manager GUI.

findAssetsByIps (on page 196)

Returns an array containing all the assets that match any of the specified IP address ranges.

findAssetsByNames (on page 196)

Returns an array containing all the assets that match any of the specified full or partial name strings.

findFirewallElementFAFolderPath (on page 194)

Returns the Skybox Firewall Assurance folder paths of the specified firewalls.

findFirewallObjectByName (on page 198)

Returns detailed information about the specified object as it occurs in the selected firewall

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 location (folder) in the All Firewalls tree.

findFirewallsByName (on page 197)

Returns a list of firewalls whose name includes the specified string.

findFirewallsByObjectName (on page 198)

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 199)

Returns all the source and destination network pairs in the model for a given source IP address range and destination IP address range.

findNetworks (on page 195)

Finds networks (Skybox network entities) with IP address ranges intersecting the specified IP address range.

findNetworksForIPRange (on page 199)

Finds network elements (Skybox network entities) whose IP address ranges intersect the specified range.

findObjectAffectedAccessRules (on page 200)

Returns an array containing access rules that use the specified firewall object.

getAccessRules (on page 201)

Retrieves a list of access rules from the requested firewall in the specified range of access rules.

getAccessRuleAttributes (on page 201)

Returns the business attributes of the specified access rule.



Method Description

getHostAttributes (on page 202)

Returns the business attributes of the specified asset (host).

getZoneFromNetwork (on page 205)

Finds the zone name of a network in the model. In Skybox, the zone signifies whether the network is trusted, semi-trusted, or untrusted.

getZoneFromFW (on page 204)

Finds the zone name of a network IP address according to the zone of the firewall’s interface that matches this IP address.

getHostNetworkInterfaces (on page 203)

Returns a list of all the network interfaces for the specified firewall.

getNetInterfacesByAssetId (on page 203)

Returns detailed information about the network interfaces of the specified firewall.

getNetInterfacesByNetworkId (on page 204)

Returns detailed information about the network interfaces of the specified network.

isBackwardRouteExist (on page 205)

Specifies whether a backward route exists between the given destination entity and the source entity (using reversed NAT rules).

modifyFirewallException (on page 206)

Modifies a firewall exception in Skybox.

modifyRulePolicyException (on page 206)

Modifies a Rule Policy exception in Skybox.

updateAccessRuleAttributes (on page 207)

Updates the business attributes of one or more access rules.

updateFwAccessRuleAttributes (on page 207)

Updates the business attributes of one or more access rules of the specified firewall.

updateHostAttributes (on page 208)

Updates the business attributes for an asset (host).

For additional information, see Network API (on page 180).

Tickets web service

Method Description

addAttachmentFile (on page 214)

Creates an attachment to a ticket in Skybox.

addDerivedChangeRequests (on page 215)

Adds a derived change request to a ticket if the original change request is of type Access Update.

addOriginalChangeRequests (on page 215)

Adds original change requests to a ticket. It then calculates the derived change requests, checks whether a change is required, and checks for policy compliance



Method Description violations and potential vulnerabilities.

analyzeAccessChangeTicket (on page 216)

Analyzes policy compliance and access for access requests of the specified ticket.

countAccessChangeTickets (on page 217)

Counts tickets by owner, phase, status, ID, or free text. This method is used for page calculations.

createAccessChangeTicket

Obsolete method. Information can be found in the documentation of version 7.5.xxx.

createChangeManagerTicket (on page 217)

Creates an Access Change ticket with a workflow and phases. If the workflow parameter is empty, the ticket is created using the default workflow.

createRecertifyTicket (on page 218)

Creates tickets for certification of a firewall’s access rules.

createTicketAccessRequestsForObjectChange (on page 219)

Adds access requests to an existing ticket. The method checks to see in which access rules the specified object appears, and creates an access request for each of these access rules.

deleteAccessChangeTicket (on page 220)

Deletes the specified Access Change ticket in Skybox.

deleteChangeRequests (on page 221)

Deletes change requests from a ticket.

expandFirewallsForAccessChangeTicket (on page 221)

Finds all the firewalls for the access requests (sets of source, destination, and port) in a specific 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 223)

Retrieves all Access Change tickets that match the search criteria.

findAccessRequests (on page 223)

Retrieves all access requests for the specified firewall created during the specified time interval.

findConfigurationItems (on page 224)

Retrieves the list of configuration items defined in the system

getAccessChangeTicket (on page 225)

Retrieves an Access Change ticket from Skybox. Note: There are separate methods for retrieving attachments, phases, events, and access requests.

getAccessRequests (on page 225)

Retrieves access requests according to their ID numbers.

getAnalysisTree (on page 226)

Returns a list of analyses, each of which includes its ID, path, name, and type.

getAttachmentFile (on page 227)

Retrieves the specified attachment from Skybox.

getAttachmentList (on page 227)

Retrieves the list of attachments to a specific ticket in Skybox.



Method Description

getDerivedChangeRequests


getDerivedChangeRequestsV1 (on page 228)

Retrieves the list of derived change requests for an original change request. Supports negated source, destination, and services in the change requests.


Retrieves the list of derived change requests for an original change request. This method is the same as getDerivedChangeRequestsV1, except that it can also handle change requests that include applications (for next generation firewalls) and users.

getGeneratedCommands (on page 229)

Retrieves the generated command output for the given change request. For Cisco firewalls, the command is in Cisco format. For other firewalls, a generic format is used.

getOriginalChangeRequest


getOriginalChangeRequestV1 (on page 230)

Retrieves all the (original) change requests in the specified ticket. Supports negated source, destination, and services in the change requests.


Retrieves all the (original) change requests in the specified ticket. This method is the same as getOriginalChangeRequestV1, except that it can also handle Add Rule and Modify Rule change requests with negated values in the source, destination, and service fields.

getPolicyViolations (on page 231)

Retrieves the list of access policy violations associated with a change request.

getPotentialVulnerabilities (on page 231)

Retrieves the list of the Vulnerability Definitions that, if the requested change is made, would be directly exposed to assets

getTicketAccessRequests (on page 232)

Retrieves from Skybox the list of access requests for the specified ticket.

getTicketEvents (on page 233)

Retrieves the history of a ticket.

getTicketFields (on page 233)

Retrieves ticket data from Skybox. You can use this method with all ticket types.

getTicketPhases (on page 234)

Retrieves from Skybox the list of ticket phases for a specific ticket type.

getTicketTypePhasesByTicketType (on page 234)

Retrieves the list of phases for the specific ticket type.

getTicketWorkflows (on page 235)

Retrieves the list of ticket workflows in Skybox, including an ID and a name for each ticket.

getVerificationDetails (on page 236)

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.



Method Description

removeAttachmentFile (on page 236)

Deletes an attachment from a ticket in Skybox.

setRecertificationStatus (on page 237)

Sets the recertification status for the specified change requests in the ticket. It can be used to change any other rule attributes for the rules in the specified change requests.

setTicketAccessRequests (on page 238)

Sets the list of access requests to the specified ticket.

setTicketFields (on page 239)

Sets ticket data in Skybox. You can use this method with all ticket types.

setTicketPhases (on page 239)

Sets the list of ticket phases for a specific ticket type in Skybox.

updateAccessChangeTicket (on page 240)

Enables you to make changes to an Access Change ticket. Note: There are separate methods for updating attachments, phases, events, and access requests.

For additional information, see Tickets API (on page 211).

Vulnerabilities web service

Method Description

countVulnerabilities (on page 244)

Counts the number of vulnerability occurrences that match the specified filter. This method is used for page calculations.

countVulnerabilityTypes (on page 244)

Counts the number of Vulnerability Definitions that match the specified filter. This method is used for page calculations.

countVulnerabilityTypeTickets (on page 245)

Counts the number of threat alert tickets that match the specified filter. This method is used for page calculations.

getVulnerabilities (on page 245)

Retrieves a list of vulnerability occurrences that match the specified filter.

getVulnerabilityTypeById


getVulnerabilityTypeByIdV1



Obsolete method. Information can be found in the documentation of version 8.0.500 or earlier.

getVulnerabilityTypeByIdV3 (on page 246)

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



Method Description




2015 Information about the threat alert includes the date on which it was reported.

getVulnerabilityTypes


getVulnerabilityTypesV1




getVulnerabilityTypesV3 (on page 247)

Returns a list of Vulnerability Definitions that match the search criteria. This method uses: • CVSS V3 for vulnerabilities published from Jan 1,


2015 getVulnerabilityTypesV4 (on page 248)

Returns a list of threat alerts that match the search criteria. Each threat alert can be a single Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses: • CVSS V3 for vulnerabilities published from Jan 1,


2015 This method is the same as getVulnerabilityTypesV3 (on page 247), but includes the reported date of each threat alert in the list.

getVulnerabilityTypeTickets (on page 249)

Retrieves a list of threat alert tickets that match the specified filter.

For additional information, see Vulnerabilities API (on page 242).

CONNECTING TO THE SKYBOX APIS The following topics explain how to connect to the Skybox APIs.

Authentication The Skybox web service APIs use HTTP basic access authentication which is 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 username and password are attached during the creation of the client’s web service port (interface). When a property is defined, it is transmitted automatically by the HTTP infrastructure on each web service call via a special Authorization HTTP header.



For Java clients, these properties are defined in:

› https://docs.oracle.com/javase/8/docs/api/javax/xml/ws/BindingProvider.html

In the context of a Java web service client, the following is a code example.

Note: This example assumes that appropriate stubs have been 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, "skyboxview"); bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "skyboxview");

Sessions The Skybox web service APIs use HTTP session, which is 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 code: bp.getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

If the session flag is false, server-side login takes place automatically on each call. If the session flag is true, server-side login takes place on the initial call, and subsequent calls are automatically attached to the initially created session.

Note: Clients other than Java (including PHP, Perl, and Python) have similar capabilities. Contact Skybox Professional Services for examples, if necessary.

Using API calls on behalf of other users Skybox Admin users can use the API on behalf of another user by adding a header to the API call. This enables automation scripts to authenticate via 1 user and password and do automatic work on tickets for other users without needing their passwords.

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 property in <Skybox_Home>\server\conf\sb_server.properties enables Skybox to log the SOAP messages that are output by your API calls:

› soap_debug_enabled=true

The full SOAP request and response are captured in the Server’s debug log (<Skybox_Home>/server/log/debug/debug.log).

We recommend that you set the value of this property to true when developing with the API.


Chapter 7

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 ............................................... 172

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 the user’s information

getEvents (on page 169)

Retrieves a list of events from Skybox

getModelLockStatuses (on page 170)

Returns the lock statuses of all models in the Skybox database: Live, Forensics, What If, and Core

getRunningTaskNames (on page 171)

Returns an array of names of currently running tasks

getServerVersion (on page 171)

Returns the version of the Skybox Server.

launchTaskOrSequence (on page 172)

Launches a Skybox task

ping Pings the Skybox server

Administration API



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 does the following:

1 Copies all the parameters from the task specified in the API (taskName)

2 Changes the scope of the task to that specified in the API (fwScope)

3 Runs the temporary task and waits for it to complete

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 task name from which the all the parameters (except the FW scope) are copied.

fwScope FWScope The firewall scope on which to run the CSV – Optimization & Cleanup Export task.

Result The method returns 1 of the following:

› The full path of the CSV file that was created by the task › An exception

findAllUsers method

Description The findAllUsers method returns a list of all users in the Skybox database.

Syntax users = findAllUsers ()

Parameters The findAllUsers method has no parameters.

Chapter 7 Administration API



› A list of data structures of type User (see page 316) › An exception

findUserByName method

Description The findUserByName method finds a user in the Skybox database by name and returns the user’s information.

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


› A data structure of type User (see page 316) › An exception

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 Skybox event records and process the records as required.

The getEvents method retrieves events created by the Skybox Server.

› Currently, there are no filtering mechanisms available; all stored events (starting from the requested sequence ID) are included in the results. However, if your organization uses only specific types of events, you can store only events of those types. See Configuring Skybox to store events (on page 170).

You can filter results on the caller side.

› On the 1st 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


sequenceNumber Integer


› A list of data structures of type Event (see page 278) › An exception

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. If you are not sure which event types your organization requires, enable all of them.

The following properties in sb_server.properties control which events 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, administrative database that contains operational and system information required by Skybox.

A model can be locked for reading, writing, and updating at any time.

Chapter 7 Administration API


Syntax getModelLockStatuses ()

Parameters The getModelLockStatuses method has no parameters.


› An array of entities of type ModelLockStatus (see page 296) › An exception

getRunningTaskNames method

Description The getRunningTaskNames method returns an array of names of currently running tasks. If no task is running, an empty array is returned.

Syntax getRunningTaskNames ()

Parameters The getRunningTaskNames method has no parameters.


› An array (list) of String objects

If no tasks are running, the array is empty.

› An exception

getServerVersion

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 Server version.



launchTaskOrSequence method

Description The launchTaskOrSequence method launches a Skybox task.

Syntax findUserByName (userName)

Parameters The parameters of the launchTaskOrSequence method are 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.

USING THE ADMINISTRATION API Use the following URL to view or access the web service, where <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 8

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 are not arbitrary.

In this chapter

Firewall Changes API methods ............................................. 173

Using the Firewall Changes API ............................................ 178

FIREWALL CHANGES API METHODS The methods in the Firewall Changes web service are described in the following table.

Method Description

countFirewallChanges (on page 174)

Counts the number of change records that match the specified filter (date range, firewalls, change reconciliation status, or violation status).

findChangeReconciliationInfo (on page 174)

Returns change reconciliation information for the specified change record (including reconciliation fields, IDs of matched tickets, and matched access requests).

findFirewallChanges (on page 175)

Returns an array containing all the firewall change records that match the search criteria.

getAccessRulesHistory (on page 175)

Retrieves a list of changes to an access rule.

getFirewallChangeDetails (on page 176)

Returns all data related to the specified change record.

setChangeReconciliationInfo (on page 176)

Sets the change reconciliation information for the specified change record (so that you can, for example, update the list of associated tickets).

updateFirewallChangeComment (on page 177)

Adds a new 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 175), which returns the actual changes.

Syntax numChanges = countFirewallChanges (filter)

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


Filter FirewallChangesSearchFilter (see page 290)

The type of changes to search for.


› An integer representing the number of firewall changes that match the search criteria

› An exception

findChangeReconciliationInfo method

Description The findChangeReconciliationInfo method returns change reconciliation information for the specified change record (including reconciliation fields, IDs of matched tickets, and matched access requests).

Syntax changeReconciliationDetails = findChangeReconciliationInfo (firewallChangeId)

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


firewallChangeId Integer The change ID is taken from the results of findFirewallChanges.


Chapter 8 Firewall Changes API


› A data structure of type FirewallChangeReconciliationDetails (see page 290) for the specified change record

› An exception

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 174) to count the number of firewall changes for display purposes and then run findFirewallChanges.

Syntax matchingChanges = findFirewallChanges (filter)

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


filter FirewallChangesSearchFilter (see page 290)

The type of changes to search for.


› An array of data structures of type FirewallChange (see page 288) › An exception

getAccessRulesHistory method

Description The getAccessRulesHistory method retrieves a list of changes to an access rule.

Run getAccessRules (see page 201) to get accessRuleId before running getAccessRulesHistory.

Syntax change_history = getAccessRulesHistory (accessRuleId, filter, subRange)

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


accessRuleId Integer The ID of the access rule in the



Parameter Type Comments firewall’s ACL.

filter ACLRuleHistoryFilter (see page 261)

The time frame for returning access rule history records.

subRange SubRange (see page 313)

The range of access rules to return from the list of access rules in the firewall that match the filter.


› An array of data structures of type FirewallChange (see page 288). › An exception

getFirewallChangeDetails method

Description The getFirewallChangeDetails method returns all data related to the specified change record. It is called after findFirewallChanges (see page 175), when you want to focus on the details of a single change.

Syntax changeDetails = getFirewallChangeDetails (firewallChangeId)

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




› A data structure of type FirewallChangeDetails (see page 289) › An exception

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 access requests). The operation overwrites the current list of connected ticket IDs and access request IDs with the lists supplied 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.

status Status of the change

The new status of the firewall change. Possible values: • PENDING • AUTHORIZED • UNAUTHORIZED • IGNORED

If null, the status is not changed.

comment String A string that is added to the existing comment of the firewall change record. If null, the comment is not changed. 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 access requests.

accessRequestIds Array of Integer A list of access requests IDs to connect to the change record. Note: For a specific access request, use this field only; do not add the ticket ID of the access 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 new comment to the specified firewall change record. Use it after viewing changes (findFirewallChanges), when 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.



comment String

Result The method adds a new 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 web service, where <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


Sample workflows for firewall change management

Workflow for viewing changes for a specific firewall To view changes for a specific firewall, do the following using the web services client application:

1 Use findFirewallsByName (on page 197) (from the Network API) to retrieve the ID of the desired firewall, as in the following example:

• fwId = findFirewallsByName("fw_europe_132")

2 Use countFirewallChanges (on page 174) to find the number of changes that match the specifications that you want (for example, the firewall and the tracking period), as in the following examples:

• countFirewallChanges(start:-24h,end: now, fwId)

• countFirewallChanges(start:-24h,end: now, folder="Europe")

This facilitates the display of the actual changes.



3 Use findFirewallChanges (on page 175) with the same parameters to display the change records, as in the following example:

• array_of_changes = findFirewallChanges(start:-24h,end: now, fwId)

4 Call getFirewallChangeDetails (on page 176) (with the desired change ID) for each change record that you select, as in the following example:

a. change_id = array_of_changes[23]

b. getFirewallChangeDetails(change_id)

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 177) to add a user comment to the Comments field of the change record. For example, “This change is wider than the requested change and should be fixed to prevent possible unnecessary access”. 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 particular 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 223) (from the Tickets API) to display all the access requests for the firewall created during the appropriate period of time (typically 1 to 2 weeks before the change was implemented).

2 Select the access request (or requests) that best match the change.

3 Attach the selected access requests to the change record using setChangeReconciliationInfo (on page 176).


Chapter 9

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 the corporate policy and then passed to firewall administrators for deployment.

In this chapter

Basic field types used in the API .......................................... 180

Network API methods ......................................................... 181

Using the Network API ........................................................ 208

BASIC FIELD TYPES USED IN THE API

IP addresses

› Address: Valid IP address › Address Range: <address1>-<address2> › Network Address: <address>/<n>

• N: Mask number 0-31

› Address Element: [<address> | <address range> | <network address>] › Addresses: <address element1>[, <address element2>[...]]

Ports

› The format for a port is: <port 1>[-<port 2>]/<protocol 1>,..., <protocol n>, where port is an integer and protocol is a string.

› 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)

Network API

Chapter 9 Network API


› Ports: A comma-separated list of ports, for example, 53/UDP, 53/TCP

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

checkAccess (on page 184)

Activates Skybox’s access analysis from another application. For any combination of source, destination, and port, you can discover whether there is connection and which firewalls allow or deny the connection.

checkAccessV1 (on page 185)

Activates Skybox’s access analysis from another application. For any combination of source, destination, and port, you can discover whether there is connection and which firewalls allow or deny the connection. The method returns the first traceroute describing the path between the source and destination. You can define whether this route should be listed in HTML or XML format.

checkAccessCompliance (on page 187)

Checks whether an access request (source-destination-port) complies with your organization’s Access Policy.



Method Description

checkRuleCompliance (on page 192)


countAssetsByIps (on page 188)

Counts the number of assets that match any of the specified IP address ranges. The output is used for page calculations.

countAssetsByNames (on page 189)

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 189)

Counts the number of access rules that use the specified firewall object. The output is used for page calculations.

createFirewallException (on page 190)

Creates a firewall exception in Skybox.

createRulePolicyException (on page 190)

Creates a Rule Policy exception in Skybox.

deleteFirewallException (on page 191)

Deletes a firewall exception from Skybox.

deleteRulePolicyException (on page 191)

Deletes a Rule Policy exception from Skybox.

doCheckRuleCompliance (on page 192)


findAccessRules (on page 193)

Searches for access rules using the same search parameters that are used in the Manager GUI.

findAssetsByIps (on page 196)

Returns an array containing all the assets that match any of the specified IP address ranges.

findAssetsByNames (on page 196)

Returns an array containing all the assets that match any of the specified full or partial name strings.

findFirewallElementFAFolderPath (on page 194)

Returns the Skybox Firewall Assurance folder paths of the specified firewalls.

findFirewallObjectByName (on page 198)

Returns detailed information about the specified object as it occurs in the selected firewall

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 location (folder) in the All Firewalls tree.

findFirewallsByName (on page 197)

Returns a list of firewalls whose name includes the specified string.



Method Description

findFirewallsByObjectName (on page 198)

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 199)

Returns all the source and destination network pairs in the model for a given source IP address range and destination IP address range.

findNetworks (on page 195)

Finds networks (Skybox network entities) with IP address ranges intersecting the specified IP address range.

findNetworksForIPRange (on page 199)

Finds network elements (Skybox network entities) whose IP address ranges intersect the specified range.

findObjectAffectedAccessRules (on page 200)

Returns an array containing access rules that use the specified firewall object.

getAccessRules (on page 201)

Retrieves a list of access rules from the requested firewall in the specified range of access rules.

getAccessRuleAttributes (on page 201)

Returns the business attributes of the specified access rule.

getHostAttributes (on page 202)

Returns the business attributes of the specified asset (host).

getZoneFromNetwork (on page 205)

Finds the zone name of a network in the model. In Skybox, the zone signifies whether the network is trusted, semi-trusted, or untrusted.

getZoneFromFW (on page 204)

Finds the zone name of a network IP address according to the zone of the firewall’s interface that matches this IP address.

getHostNetworkInterfaces (on page 203)

Returns a list of all the network interfaces for the specified firewall.

getNetInterfacesByAssetId (on page 203)

Returns detailed information about the network interfaces of the specified firewall.

getNetInterfacesByNetworkId (on page 204)

Returns detailed information about the network interfaces of the specified network.

isBackwardRouteExist (on page 205)

Specifies whether a backward route exists between the given destination entity and the source entity (using reversed NAT rules).

modifyFirewallException (on page 206)

Modifies a firewall exception in Skybox.



Method Description

modifyRulePolicyException (on page 206)

Modifies a Rule Policy exception in Skybox.

updateAccessRuleAttributes (on page 207)

Updates the business attributes of one or more access rules.

updateFwAccessRuleAttributes (on page 207)

Updates the business attributes of one or more access rules of the specified firewall.

updateHostAttributes (on page 208)

Updates the business attributes for an asset (host).

checkAccess method

Description The checkAccess 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 which firewalls allow or deny the connection.

› In a network context, the access analysis is done holistically, listing all gateways (firewalls and other devices).

› In a per-firewall context, the access analysis is done between 2 network interfaces of the specified firewall.

Example The result of this analysis is combinations of IP address ranges from source and destination that are accessible or inaccessible, for example:

› Request: net_A to net_B on port X › Response:

• Accessible: Part of net_A can connect to net_B on port X

• Inaccessible: The other part of net_A cannot connect to net_B on port X

For each accessible or inaccessible combination, you can request a traceroute:

› Request: Traceroute for the part of net_A that can connect to net_B on port X › Response: Permitted by rule#47 of firewall_A; pass through router Z;

permitted by rule #12 on firewall_D

How to use the method In a network context

1 Source-network-entity = findNetworks (source-address)

You might get errors (for example, the IP address is not valid or the network is not found). If multiple networks match the search criteria, you might get a response telling you to choose a single network.



2 Destination-network-entity = findNetworks (destination-address)

3 checkAccess (source-address, source-network-entity, destination-address, destination-address-entity, ports, mode)

In a firewall context

1 Firewall = findFirewalls (…)

• Select the firewall from a list, either by name or from a list of relevant firewalls

2 checkAccess (source-address, source-network-entity=null, destination-address, destination-address-entity=null, ports, firewall, mode)

Syntax result = checkAccess (query)

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


query AccessQueryElement (see page 256)


› A data structure of type CheckAccessResult (see page 272), which includes a list of accessible IP addresses (source, destination, ports, and authentication) and inaccessible IP addresses, and the 1st traceroute describing the path between the source and the destination

› A list of exceptions

checkAccessV1 method

Description The checkAccessV1 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 which firewalls allow or deny the connection.

› In a network context, the access analysis is done holistically, listing all gateways (firewalls and other devices).

› In a per-firewall context, the access analysis is done between 2 network interfaces of the specified firewall

The method returns the first traceroute describing the path between the source and destination. You can define whether this route should be listed in HTML or XML format.



Example The result of this analysis is combinations of IP address ranges from source and destination that are accessible or inaccessible, for example:

› Request: net_A to net_B on port X › Response:

• Accessible: Part of net_A can connect to net_B on port X

• Inaccessible: The other part of net_A cannot connect to net_B on port X

For each accessible or inaccessible combination, you can request a traceroute:

› Request: Traceroute for the part of net_A that can connect to net_B on port X › Response: Permitted by rule#47 of firewall_A; pass through router Z;

permitted by rule #12 on firewall_D

How to use the method In a network context

1 Source-network-entity = findNetworks (source-address)

You might get errors (for example, the IP address is not valid or the network is not found). If multiple networks match the search criteria, you might get a response telling you to choose a single network.

2 Destination-network-entity = findNetworks (destination-address)

3 checkAccessV1 (query (source-address, source-network-entity, destination-address, destination-address-entity, ports, mode), routeOutputType)

In a firewall context

1 Firewall = findFirewalls (…)

• Select the firewall from a list, either by name or from a list of relevant firewalls

2 checkAccessV1 (query (source-address, source-network-entity=null, destination-address, destination-address-entity=null, ports, firewall, mode), routeOutputType)

Syntax result = checkAccessV1 (query, routeOutputType)

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


query AccessQueryElement (see page 256)

routeOutputType Integer Possible values are: • 0: Indicates that the traceroute

should be returned in HTML format



• 1: Indicates that the traceroute should be returned in XML format


› A data structure of type CheckAccessResult (see page 272), which includes a list of accessible IP addresses (source, destination, ports, and authentication) and inaccessible IP addresses, and the 1st traceroute describing the path between the source and the destination


checkAccessCompliance method

Description The checkAccessCompliance method checks whether an access request (source-destination-port) complies with your organization’s 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 The compliance checking is done as follows:

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 205) › destinationZone = getZoneFromNetwork (destinationAddress) (see page 205) › checkAccessCompliance (sourceAddress, sourceZone, destinationAddress,

destinationZone, ports)

In a firewall context:

› fw = findFirewalls () (see page 193) › sourceZone = getZoneFromFW (fw, sourceAddress) (see page 204) › destinationZone = getZoneFromFW (fw, destinationAddress) (see page 204) › checkAccessCompliance (sourceAddress, sourceZone, destinationAddress,

destinationZone, ports)



Syntax result = checkAccessCompliance (request)

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


request CheckAccessComplianceRequest (see page 271)


› A data structure of type CheckAccessComplianceResponse (see page 271), which includes the compliance status of the request and a list of violations

› An exception

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 196), which returns the actual assets.

Syntax numAssets = countAssetsByIps (IPFilter)

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


IPFilter List of IPRanges (see page 296)

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.


› An integer representing the number of assets that match the IP address filter › An exception



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 196), which returns the actual assets.

Syntax numAssets = countAssetsByNames (NameFilter)



NameFilter List of strings The strings can be full or partial names. Wildcards (* and ?) are supported.


› An integer representing the number of assets that match the name filter › An exception

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 findObjectAffectedAccessRules (see page 200), which returns the actual 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.



Parameter Type Comments 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.


› An integer representing the number of access rules in the firewall that use the object

› An exception

createFirewallException method

Description The createFirewallException method takes the information for a firewall exception and returns a firewall 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 291)

The ID field in the firewall exception data is ignored.


› A firewall exception (see page 291) › An exception

createRulePolicyException method

Description The createRulePolicyException method takes the information for a Rule Policy exception and returns a Rule Policy exception with an ID.

Syntax exception = createRulePolicyException (policyException)



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


policyException RulePolicyException (see page 310)

The ID field in the exception data is ignored.


› A Rule Policy exception (see page 310) › An exception

deleteFirewallException method

Description The deleteFirewallException method removes a firewall exception from Skybox.

Syntax deleteFirewallException (firewallException)

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



Result The method does 1 of the following:

› Deletes the specified firewall exception in Skybox › Returns an exception

deleteRulePolicyException method

Description The deleteRulePolicyException method removes a Rule Policy exception from Skybox.

Syntax deleteRulePolicyException (policyException)

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






› Deletes the specified Rule Policy exception in Skybox › Returns an exception

doCheckRuleCompliance method

Description The doCheckRuleCompliance method checks whether an access request (source-destination-port) complies with your organization’s Rule Policies.

How to use this method The compliance checking is done as follows: 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).

The request has the following parameters:

› sourceAddress › destinationAddress › port › policyName (optional) › firewall (for future versions only)

Syntax result = doCheckRuleCompliance (req)

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


req CheckRuleComplianceRequest (see page 272)


› A data structure of type CheckRuleComplianceResponse (see page 273), which includes the compliance status of the request and a list of violations

› An exception



findAccessRules method

Description The findAccessRules method searches for access rules using the same search parameters that are used in the Manager GUI.

Syntax list = findAccessRules (filter)

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


filter AccessRuleSearchFilter (see page 259)


› An array of AccessRuleElement (see page 258) › An exception

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




› A list of firewalls (see page 291) › A list of exceptions

findFirewallsByLocation method

Description The findFirewallsByLocation method returns a list of the firewalls stored under the specified location (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.


› A list of firewalls › A list of exceptions

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 291)




› A data structure of type FindFirewallElementsFAFolderPathResult (see page 285), which includes a list of firewalls and a matching list of Firewall Access folder paths


findNetworks method

Description The findNetworks method finds network elements (Skybox network entities) (see page 302) whose IP address ranges intersect the specified range.

This method is used for unique identification of networks. Calling this method is a prerequisite for calling checkAccess (see page 184) and checkAccessCompliance (see page 187) when working with a network model (not individual firewalls).

Syntax list = findNetworks (ipRange)

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


ipRange Address Element


› A list of data structures of type NetworkElement (see page 302) in the model that match the specified IP address range


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 187).

Syntax list = findNetworkElementZone (networkElements)

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


networkElements NetworkElement (see page 302)




› A data structure of type FindNetworkElementsZoneResult (see page 286), which includes a list of networks and a matching list of network zones


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 188) to count the number of assets for display purposes and then run findAssetsByIps.

Syntax Assets = findAssetsByIps (IPFilter, subRange)

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


IPFilter List of IPRanges (see page 296)

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.


The range of assets to return from the list of assets that match the filter criteria.


› An array of assets (see page 266) sorted by ID › An exception

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 189) 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. Wildcards (* and ?) are supported.


The range of assets to return from the list of assets that match the filter criteria.


› An array of assets (see page 266) sorted by ID › An exception

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.


› A list of firewalls › A list of exceptions



findFirewallsByObjectName method

Description The findFirewallsByObjectName method checks all the access rules of the firewalls in the All Firewalls tree to see whether they use the specified object. It 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 countObjectAffectedAccessRules (see page 189) and findObjectAffectedAccessRules (see page 200).

Syntax list = findFirewallsByObjectName (objectName)

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


objectName String The name of the desired 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.


› A data structure of type FirewallFindByObjectResult (see page 292), which includes a list of firewalls and a list of objects for each firewall found


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 1 the following:

› Detailed information about the specified object › A list of exceptions

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 296)

The IP address range to check for the source.

destinationIpRangeElem

IPRangeElement (see page 296)

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 data structure of type FindNetworkEntitiesResult (see page 286)

findNetworksForIPRange method

Description The findNetworksForIPRange method finds network elements (Skybox network entities) (see page 302) whose IP address ranges intersect the specified range.

This method is used for unique identification of networks. Calling this method is a prerequisite for calling checkAccess (see page 184) and checkAccessCompliance (see page 187) 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


› A list of data structures of type IPAndNetworksPair (see page 296) in the model that match the specified IP address range


findObjectAffectedAccessRules method

Description The findObjectAffectedAccessRules 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 189) to count the number of access rules for display purposes and then run findObjectAffectedAccessRules.

Syntax matchingObjects = findObjectAffectedAccessRules (hostId, objectName, subRange, chainFilterMode, chainNames)

Parameters The parameters of the findObjectAffectedAccessRules 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.

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






› An list of data structures of type AccessRuleElement (see page 258) › An exception

getAccessRuleAttributes method

Description The getAccessRuleAttributes method returns a list of the business attributes of the access rule.

Syntax ruleAttributes = getAccessRuleAttributes(Id)

Parameters

The parameters of the getAccessRuleAttributes method are described in the following table.


Id Integer Access rule ID


› A data structure of type ruleAttributes (see page 309), which contains the list of business attributes for the specified access rule


getAccessRules method

Description The getAccessRules method retrieves a list of the access rules that lie within the given range of access rules for the requested firewall.

This method is used:

› To export a firewall’s access rules from Skybox › In conjunction with checkAccess (see page 184), to show the actual rules that

permitted or denied the access › In conjunction with getAccessRulesHistory (see page 175), to show the

history of an access rule



Syntax list = getAccessRules (fw, range, chainName)

Parameters The parameters of the getAccessRules 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 entity.

range Range element The range of rule numbers to be returned (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


› A list of data structures of type AccessRuleElement (see page 258) › A list of exceptions

getHostAttributes method

Description The getHostAttributes method returns a list of the business attributes of the specified firewall.

Syntax hostAttributes = getHostAttributes (Id)

Parameters

The parameters of the getHostAttributes method are described in the following table.


Id Integer Host ID




› A data structure of type hostAttributes (on page 295), which contains the list of business attributes for the specified host


getHostNetworkInterfaces method

Description The getHostNetworkInterfaces method returns a list of the network interfaces of the specified firewall.

Syntax hostInterfaces = getHostNetworkInterfaces (hostId)

Parameters

The parameters of the getHostNetworkInterfaces method are described in the following table.


hostId Integer


› A data structure of type FindNetInterfaceResult (see page 286), which 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 parameters of the getNetInterfacesByAssetId method are described in the following table.


assetId Integer


› An array of network interfaces (see page 300) › A list of exceptions



getNetInterfacesByNetworkId method

Description The getNetInterfacesByNetworkId method returns detailed information about the network interfaces of the specified network.

Syntax networkInterfaces = getNetInterfacesByNetworkId (networkId)

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


networkId Integer


› An array of network interfaces (see page 300) › A list of exceptions

getZoneFromFW method

Description The getZoneFromFW method finds the zone name of a network IP address according to the zones of the firewall’s 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 2 or more network interfaces, the result contains the zones of all the matched interfaces.

The method is a prerequisite for checkAccessCompliance (see page 187), which checks whether access via a specific 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 entity.

ipRange Address element




› 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 existing zone in the specified firewall.

› An exception

getZoneFromNetwork method

Description The getZoneFromNetwork method finds the zone name of a network in the model. In Skybox, the zone signifies whether the network is trusted, semi-trusted, or untrusted.

This method is a prerequisite for checkAccessCompliance (see page 187), which checks whether access via a specific 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 302)

Only the ID field of the NetworkElement is mandatory. Use findNetworks (on page 195) to get this entity.


› The name of the zone in the model that matches the network entity

The name is blank if there is no zone for this network

› An exception

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 IPAndNetworksPair (see page 296)

destinationEntity IPAndNetworksPair (see page 296)


› A Boolean specifying whether any backward routes exist. › A list of exceptions

modifyFirewallException method

Description The modifyFirewallException method takes a firewall exception (with the original ID) on which some changes have been made and returns the fixed exception.

Syntax modifiedexception = modifyFirewallException (firewallException)

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




› An updated firewall exception (see page 291) › An exception

modifyRulePolicyException method

Description The modifyFirewallException method takes a firewall exception (with the original ID) on which some changes have been made and returns the fixed exception.

Syntax modifiedException = modifyFirewallException (policyException)



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




› An updated Rule Policy exception (see page 310) › An exception

updateAccessRuleAttributes method

Description The updateAccessRuleAttributes method updates the business attributes of one or more access rules.

Syntax updatedAccessRuleAttributes = updateAccessRuleAttributes (updateInfo)

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


updateInfo RulesAttributesUpdateInfo (on page 310)


› An entity of type AccessRulesResponse (on page 260) › An exception

updateFwAccessRuleAttributes method

Description The updateFwAccessRuleAttributes method updates the business attributes of one or more access rules of the specified firewall.

Syntax updatedFwRuleAttributes = updateFwAccessRuleAttributes (updateInfo)



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


updateInfo FwRulesAttributesUpdateInfo (on page 294)


› An entity of type accessRulesByFwResponse (on page 260) › An exception

updateHostAttributes method

Description The updateHostAttributes method updates the business attributes for an asset (host).

Syntax updatedHostAttributes = updateHostAttributes (updateInfo)

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


updateInfo hostsAttributesUpdateInfo (on page 295)


› An entity of type hostsResponse (on page 295) › An exception

USING THE NETWORK API Use the following URL to view or access the web service, where <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 The following is a typical scenario using the Network API to check access.

1 You need access from your computer to some application. Create a ticket in an external ticketing system to request this access.

2 Fill in 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) and click Check Access.

3 The external ticketing system calls the Skybox checkAccess method (see page 184).

4 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 supplied, it returns an error.

5 Do 1 of the following:

• 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.

6 The expert sees the ticket and decides to use Skybox Manager to check the access.

7 The expert does 1 of the following:

• Opens Skybox’s 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.

8 The external ticketing system calls the Skybox createChangeManagerTicket method (see page 217), which creates a ticket in Skybox whose properties are based on those of the external ticket.

9 The expert finds the open ticket, which includes the source-destination-port combination that needs checking. The expert uses Skybox’s Access Analyzer to view and understand the access, and can use the information gained there to decide what to do with the original ticket in the external ticketing system.

10 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 To check whether access from a specific source IP address to a specific destination is permitted in the model, do the following using the web services client application:

1 Use findNetworks (on page 195) to find the network in the model that contains the source IP address.

2 Use findNetworks (on page 195) to find the network in the model that contains the destination IP address.



3 Create an AccessQueryElement object (see page 256) using the source and destination IP addresses, and network elements found on the previous step.

4 Call checkAccess (see page 184) and analyze its results.

Workflow for the checkAccess method across a single firewall To check whether access from a specific source IP address to a specific destination is permitted by a specific firewall, do the following using the web services client application:

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 256) using the source and destination IP addresses, and the firewall element found in the previous step

3 Call checkAccess (see page 184) and analyze its results.

Sample workflow for checking Access Compliance

To check whether access between 2 zones violates your organization’s Access Policy 1 Use getZoneFromNetwork (on page 205) (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 271) object using sourceZone, destinationZone, ports and (optionally) firewall elements.

4 Call checkAccessCompliance (see page 187) and analyze its results (list of violated Access Checks).


Chapter 10

This chapter describes the Tickets API, which retrieves and updates Skybox tickets.

You can use the Tickets API to support 2 types of scenarios:

› 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 180) to check connectivity and policy compliance of change requests.

• The applications can send tickets to Skybox, enabling you to use the Skybox GUI to analyzing the requests.

• You can create and manage firewall change tickets (known in Skybox as access change tickets) using the Tickets API.

For additional information, see Using the Tickets API (on page 240).

In this chapter

Tickets API methods ........................................................... 211

Using the Tickets API ......................................................... 240

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 214)

Creates an attachment to a ticket in Skybox.

addDerivedChangeRequests (on page 215)

Adds a derived change request to a ticket if the original change request is of type Access Update.

Tickets API



Method Description

addOriginalChangeRequests (on page 215)

Adds original change requests to a ticket. It then calculates the derived change requests, checks whether a change is required, and checks for policy compliance violations and potential vulnerabilities.

analyzeAccessChangeTicket (on page 216)

Analyzes policy compliance and access for access requests of the specified ticket.

countAccessChangeTickets (on page 217)

Counts tickets by owner, phase, status, ID, or free text. This method is used for page calculations.

createAccessChangeTicket


createChangeManagerTicket (on page 217)

Creates an Access Change ticket with a workflow and phases. If the workflow parameter is empty, the ticket is created using the default workflow.

createRecertifyTicket (on page 218)

Creates tickets for certification of a firewall’s access rules.

createTicketAccessRequestsForObjectChange (on page 219)

Adds access requests to an existing ticket. The method checks to see in which access rules the specified object appears, and creates an access request for each of these access rules.

deleteAccessChangeTicket (on page 220)

Deletes the specified Access Change ticket in Skybox.

deleteChangeRequests (on page 221)

Deletes change requests from a ticket.

expandFirewallsForAccessChangeTicket (on page 221)

Finds all the firewalls for the access requests (sets of source, destination, and port) in a specific 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 223)

Retrieves all Access Change tickets that match the search criteria.

findAccessRequests (on page 223)

Retrieves all access requests for the specified firewall created during the specified time interval.

findConfigurationItems (on page 224)

Retrieves the list of configuration items defined in the system

getAccessChangeTicket (on page 225)

Retrieves an Access Change ticket from Skybox. Note: There are separate methods for retrieving attachments, phases, events, and access requests.

getAccessRequests (on page 225)

Retrieves access requests according to their ID numbers.

getAnalysisTree (on page 226)

Returns a list of analyses, each of which includes its ID, path, name, and type.

getAttachmentFile (on page 227)

Retrieves the specified attachment from Skybox.

Chapter 10 Tickets API


Method Description

getAttachmentList (on page 227)

Retrieves the list of attachments to a specific ticket in Skybox.

getDerivedChangeRequests



Retrieves the list of derived change requests for an original change request. Supports negated source, destination, and services in the change requests.


Retrieves the list of derived change requests for an original change request. This method is the same as getDerivedChangeRequestsV1, except that it can also handle change requests that include applications (for next generation firewalls) and users.

getGeneratedCommands (on page 229)

Retrieves the generated command output for the given change request. For Cisco firewalls, the command is in Cisco format. For other firewalls, a generic format is used.

getOriginalChangeRequest



Retrieves all the (original) change requests in the specified ticket. Supports negated source, destination, and services in the change requests.


Retrieves all the (original) change requests in the specified ticket. This method is the same as getOriginalChangeRequestV1, except that it can also handle Add Rule and Modify Rule change requests with negated values in the source, destination, and service fields.

getPolicyViolations (on page 231)

Retrieves the list of access policy violations associated with a change request.

getPotentialVulnerabilities (on page 231)

Retrieves the list of the Vulnerability Definitions that, if the requested change is made, would be directly exposed to assets

getTicketAccessRequests (on page 232)

Retrieves from Skybox the list of access requests for the specified ticket.

getTicketEvents (on page 233)

Retrieves the history of a ticket.

getTicketFields (on page 233)

Retrieves ticket data from Skybox. You can use this method with all ticket types.

getTicketPhases (on page 234)

Retrieves from Skybox the list of ticket phases for a specific ticket type.

getTicketTypePhasesByTicketType (on page 234)

Retrieves the list of phases for the specific ticket type.

getTicketWorkflows (on page 235)

Retrieves the list of ticket workflows in Skybox, including an ID and a name for each ticket.



Method Description

getVerificationDetails (on page 236)

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.

removeAttachmentFile (on page 236)

Deletes an attachment from a ticket in Skybox.

setRecertificationStatus (on page 237)

Sets the recertification status for the specified change requests in the ticket. It can be used to change any other rule attributes for the rules in the specified change requests.

setTicketAccessRequests (on page 238)

Sets the list of access requests to the specified ticket.

setTicketFields (on page 239)

Sets ticket data in Skybox. You can use this method with all ticket types.

setTicketPhases (on page 239)

Sets the list of ticket phases for a specific ticket type in Skybox.

updateAccessChangeTicket (on page 240)

Enables you to make changes to an Access Change ticket. Note: There are separate methods for updating attachments, phases, events, and access requests.

addAttachmentFile method

Description The addAttachmentFile method creates an attachment to the specified ticket in Skybox, including 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




› The ID of the newly created attachment › An exception

addDerivedChangeRequests method

Description The addDerivedChangeRequests method adds a derived change request to a ticket if the original change request is of type Access Update.

Validations 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


ticketId Integer The unique ID of the ticket

changeRequestId Integer The ID of the original change request

firewalls Array of Asset (see page 266)

Array of firewalls for which to add derived change requests


› An array of derived change requests for the specified firewalls › An exception

addOriginalChangeRequests method

Description The addOriginalChangeRequests method adds original change requests to a ticket. It then calculates the derived change requests, checks whether a change is required, and checks for policy compliance violations and potential vulnerabilities.


› The change requests are only added if the user has permissions to edit the ticket.

› The change requests are only added if they are permitted in the workflow of the ticket.



Note: No optimization is done on the derived change requests.

Note: Firewall identification is based on the mode set in Tools > Options > Server > Change Manager Settings.

Syntax derivedChangeRequests = addOriginalChangeRequests (ticketId, changeRequests)

Parameters



changeRequests Array of ChangeRequest (see page 269)

Any type of the change request extensions; not abstract change requests.


› An array of change request objects (see page 269) › An exception

analyzeAccessChangeTicket method

Description The analyzeAccessChangeTicket method analyzes access and Access Policy compliance for access 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 unique ID of the ticket to analyze

accessRequests Array of Integer A list of specific access request IDs in the ticket to analyze. An empty list means that all access requests are analyzed. Note: To retrieve a list of the access requests in a ticket, use getTicketAccessRequests (on page 232).




Mode Integer The type of analysis: • 0: Access analysis only • 1: Access Policy compliance

analysis only • 2: Both


› A data structure of type AccessChangeTicket (see page 255), with updated access requests

› An exception

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 223), which returns the actual tickets.

Syntax numTickets = countAccessChangeTickets (Filter, subRange)

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


Filter TicketsSearchFilter (see page 314)

Mandatory


Mandatory


› An integer representing the number of Access Change tickets that match the search criteria

› An exception

createChangeManagerTicket method

Description The createChangeManagerTicket method creates an Access Change ticket with a workflow and phases.



Limitations:

› If the user creating the ticket does not have permission to create tickets in the selected workflow, no ticket is created.

› If no workflow is provided, 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 existing Access Change ticket using getAccessChangeTicket (on page 225) and update it using updateAccessChangeTicket (on page 240).

Syntax ticket = createChangeManagerTicket (accessChangeTicket, phases, workflowId)

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


accessChangeTicket

AccessChangeTicket (see page 255)

Mandatory

phases Array of Phase (see page 304)

Default phases are created (according to the workflow) if the list is empty.

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 235).


› A data structure of type AccessChangeTicket (see page 255) › An exception

createRecertifyTicket method

Description The createRecertifyTicket method creates tickets for certification of a firewall’s access rules. The workflow is checked to ascertain that it permits recertification. The ticket creation logic is the same as that used by Policy Rule Review tasks.

Syntax ticketList = createRecertifyTicket (accessChangeTicket, accessRuleElements, workflowId)

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




accessChangeTicket


Mandatory

accessRuleElements

Array of AccessRuleElement (see page 258)

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 235).


› An entity named RecertifyTicketCreationResult (see page 306), which contains a list of new ticket IDs and a list of the access rules that are not included in these tickets

› An exception

createTicketAccessRequestsForObjectChange method

Description The createTicketAccessRequestsForObjectChange method adds access requests to an existing ticket. The method finds the access rules in which the specified object occurs and creates an access request for each of these access rules.

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 access requests are attached.

hostId Integer The ID of the device to be changed.

objectName String The name of the object to be changed. The object can be an IP object or Service object.

changeType Integer The type of change: • 0: Add to the object • 1: Delete from the object.

Note: In the current version, only adding is supported.

addressChange Array of String The IP address to be added or removed from the object. Relevant only if the object is an IP object.




portChange String The service to be added or removed from the object. Relevant only if the object is a Service object.

maxAccessRequestsToCreate

Integer Limits the number of access requests that are created.

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



› Creates access requests on the specified ticket › Returns an exception

deleteAccessChangeTicket method

Description The deleteAccessChangeTicket method deletes the specified Access Change ticket in Skybox.

Syntax deleteAccessChangeTicket (ticketId)

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




› Deletes the specified ticket in Skybox

The deletion is written in the activity log. (For additional information, see the Activity log section in the Skybox Installation and Administration Guide.)

› Returns an exception



deleteChangeRequests method

Description The deleteChangeRequests method deletes change requests from a ticket.


› The change requests are only deleted if the user has permissions to edit the ticket.

Syntax deleteChangeRequests (ticketId, changeRequestIds)

Parameters



changeRequestIds Array of Integer The IDs of the change requests to be deleted


› Deletes the specified change requests from the ticket › Returns an exception

expandFirewallsForAccessChangeTicket method

Description The expandFirewallsForAccessChangeTicket method finds all the firewalls for the change requests (sets of source, destination, and port) in a specific 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 generates a list of change requests per firewall per source-destination-port combination.

If the source or destination of a change request is updated, set the Recalculate flag to true. If you are adding a new 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




Source Zone

Destination Zone

NetworkC NetworkD 21

After calling this method, the expanded ticket includes the change requests listed in the following table.


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 specific access request IDs. If the list is empty, all access requests are expanded.

Recalculate Boolean Specifies whether to expand the selected access requests.


› A data structure of type AccessChangeTicket (see page 255), with updated access requests that include firewalls, network interfaces, and zones for each change request

› An exception



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 217) to count the number of tickets for display purposes and then run findAccessChangeTickets.

Syntax matchingTickets = findAccessChangeTickets (Filter)

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


Filter TicketsSearchFilter (see page 314)


› An array of data structures of type AccessChangeTicket (see page 255) › An exception

findAccessRequests method

Description The findAccessRequests method retrieves all access requests for the specified firewall created during the specified time interval. The access requests might not all be from the same ticket.

Use this method with setChangeReconciliationInfo (see page 176) (in the Firewall Changes API) to connect specific access 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 unique ID of the firewall for which to find access requests.

dateRange DateRange (see page 276)

The time interval for which to find access requests.




› A list of data structures of type AccessRequest (see page 257) from the specified time interval for the specified asset

› An exception

findConfigurationItems method

Description The findConfigurationItems method retrieves the list of 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 273)


Limits the results to the specified subrange


› A list of configuration items (see page 267) › A list of exceptions

findTickets method

Description The findTickets method retrieves all the Access Change tickets in the specified analysis.

Note: Currently, 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


› A list of Access Change tickets (see page 255) › A list of exceptions

getAccessChangeTicket method

Description The getAccessChangeTicket method retrieves an Access Change ticket from Skybox.

Note: There are separate methods for retrieving attachments, phases, events, and access requests.

Use this method before calling updateAccessChangeTicket (see page 240) to make changes to a ticket.

Syntax ticket = getAccessChangeTicket (ticketId)

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




› A data structure of type AccessChangeTicket (see page 255) › An exception

getAccessRequests method

Description The getAccessRequests method retrieves access requests according to their ID numbers.



The result of calling findChangeReconciliationInfo (see page 174) (from the Firewall Changes API) for a change record includes a list of the IDs of access requests that are relevant to the specified change record. Use this method to get the details of the access requests (that is, the source, destination, and service) so that you can display it in the application.

Syntax accessRequests = getAccessRequests (accessRequestIds)

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


accessRequestIds Array of Integer The IDs of the desired access requests


› A list of the specified data structures of type AccessRequest (see page 257) › An exception

getAnalysisTree method

Description The getAnalysisTree method returns a list of analyses, each of which includes its ID, path, name, and type.

Note: Currently, this method supports only the public and private tickets analyses trees in the Tickets workspace.

Syntax tree = getAnalysisTree (type)

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


type String Legal values: • Network Assurance Tickets Public • Network Assurance Tickets Private


› A list of analyses › An exception



getAttachmentFile method

Description The getAttachmentFile method retrieves the specified ticket attachment from Skybox.

You can view a list of the ticket’s attachments using getAttachmentList (on page 227) and then pass the ID of the desired attachment with this method to retrieve the file. You can use an attachment’s ID to delete the attachment from the ticket (see removeAttachmentFile (on page 236)).

Syntax attachment = getAttachmentFile (attachmentId)

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


attachmentId Integer The unique ID of the attachment file (retrieved using getAttachmentList (on page 227))


› The attachment file (javax.activation.DataHandler) › An exception

getAttachmentList method

Description The getAttachmentFile method retrieves the list of attachments to a specific ticket in Skybox.

Note: The method returns metadata about each attachment (see page 267). To retrieve a specific attachment, call getAttachmentFile (on page 227) with the ID of the desired attachment.

Syntax list = getAttachmentList (ticketId)

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






› A list of data structures of type Attachment (see page 267) for the specified ticket

› An exception

getDerivedChangeRequestsV1 method

Description The getDerivedChangeRequestsv1 method retrieves the list of derived change requests for an original change request. This method is the same as getDerivedChangeRequests, except that it can also handle Add Rule and Modify Rule change requests with negated values in the source, destination, and service fields.


› The derived change requests are only returned if the user has permissions to view (or edit) this ticket.

Syntax derivedChangeRequests = getDerivedChangeRequestsV1 (ticketId, changeRequestId)

Parameters





› An array of ChangeRequest (see page 269) (the derived requests) › An exception

getDerivedChangeRequestsV2 method

Description The getDerivedChangeRequestsV2 method retrieves the list of derived change requests for an original change request. This method is the same as getDerivedChangeRequestsV1, except that it can also handle change requests which include applications (for next generation firewalls) and users.


› The derived change requests are only returned if the user has permissions to view (or edit) this ticket. If the user has no permissions for the ticket, they get an error message.



Syntax derivedChangeRequests = getDerivedChangeRequestsV2 (ticketId, changeRequestId)

Parameters





› An array of ChangeRequest (see page 269) (the derived requests) › An exception

getGeneratedCommands method

Description The getGeneratedCommands method retrieves the generated command output for the given change request. For Cisco firewalls, the command is in Cisco format. For other firewalls, a generic format is used.


› The generated commands are only returned if the user has permissions to view (or edit) this ticket.

Syntax generatedCommands = getGeneratedCommands (ticketId, changeRequestId)

Parameters



changeRequestId Integer The ID of the change request for which to retrieve the generated commands


› The generated command output (as a string) › An exception



getOriginalChangeRequestV1 method

Description The getOriginalChangeRequestV1 method retrieves all the (original) change requests in the specified ticket. This method is the same as getOriginalChangeRequest, except that it can also handle Add Rule and Modify Rule change requests with negated values in the source, destination, and service fields.


› The original change requests are only returned if the user has permissions to view (or edit) this ticket.

Syntax originalChangeRequests = getOriginalChangeRequestV1 (ticketId)

Parameters




› An array of original ChangeRequest (see page 269) › An exception

getOriginalChangeRequestV2 method

Description The getOriginalChangeRequestV2 method retrieves all the (original) change requests in the specified ticket. This method is the same as getOriginalChangeRequestV1, except that it can also handle Add Rule and Modify Rule change requests with negated values in the source, destination, and service fields.


› The original change requests are only returned if the user has permissions to view (or edit) this ticket. If the user has no permissions for the ticket, they get an error message.

Syntax originalChangeRequests = getOriginalChangeRequestV2 (ticketId)

Parameters






› An array of original ChangeRequest (see page 269) › An exception

getPolicyViolations method

Description The getPolicyViolations method retrieves the list of access policy violations associated with a change request.


› The policy violations are only returned if the user has permissions to view (or edit) this ticket.

Syntax policyViolations = getPolicyViolations (ticketId, changeRequestId)

Parameters



changeRequestId Integer The ID of the change request for which you want to see policy violations


› An array of ChangeRequestComplianceViolationElement (see page 270) › An exception

getPotentialVulnerabilities method

Description The getPotentialVulnerabilities method retrieves the list of the Vulnerability Definitions that, if the requested change is made, would be directly exposed to assets.


› The potential vulnerabilities are only returned if the user has permissions to view (or edit) this ticket.

Syntax potentialVulnerabilities = getPotentialVulnerabilities (ticketId, changeRequestId)



Parameters



changeRequestId Integer The ID of the change request for which you want to see policy violations


› An array of ChangeRequestPotentialVulnerability (see page 270) › An exception

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 parameters of the getSponsoringApplication method are described in the following table.




› A data structure of type BaseConfigurationItem (see page 267) › An exception

getTicketAccessRequests method

Description The getTicketAccessRequests method retrieves the list of access requests for the specified ticket (see page 257). The list is input to setTicketAccessRequests (see page 238), where you can add or update access requests for a ticket.

Syntax accessRequests = getTicketAccessRequests (ticketId)



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




› An array of data structures of type AccessRequest (see page 257) from the specified ticket

› An exception

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 parameters of the getTicketEvents method are described in the following table.




› An array of data structures of type TicketEvent (see page 313) for the specified ticket

› An exception

getTicketFields method

Description The getTicketFields method gets ticket data from Skybox. You can use it with all types of tickets.

Note: This method and setTicketFields translate between the external ticket ID and the Skybox ticket ID. All other methods use only the Skybox ticket ID.

Syntax ticket = getTicketFields (ticketIdType, ticketId)



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


ticketIdType String Signifies whether the ticket ID is the Skybox ticket ID or the ID from the external ticketing system Possible values: • SBV • EXTERNAL

ticketId String The unique ID of the ticket


› An exception › An array of data structures of type TicketField (see page 314)

getTicketPhases method

Description The getTicketPhases method retrieves the list of phases for the specified ticket (see page 304). The list is input to setTicketPhases (see page 239), where you can change the due dates and assignees for a ticket.

Syntax phases = getTicketPhases (ticketId)

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




› An array of data structures of type Phase (see page 304) in the specified ticket

› An exception

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 217)), and then calls getTicketPhases (on page 234) (using the ticket ID) and edits the phases for the ticket.

Syntax phases = getTicketTypePhasesByTicketType (ticketType)

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


ticketType String (enum) The following types are valid: • VulnerabilityTicket • ApplicationTicket • VulnerabilityDefinitionTicket • AccessChangeTicket • PolicyViolationTicket


› A list of data structures of type TicketTypePhase (see page 315) for the specified ticket type

› An exception

getTicketWorkflows method

Description The getTicketWorkflows method retrieves the list of ticket workflows in Skybox, including an ID and a name for each workflow.

Syntax ticketWorkflows = getTicketWorkflows ()

Parameters The getTicketWorkflows method has no parameters.


› An array of data structures of type TicketWorkflow (see page 315) › An exception



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 already verified. If the change request is not verified, the method returns null.


› The verification details are returned only if the user has permissions to view (or edit) this ticket.

Syntax verificationDetails= getVerificationDetails (ticketId, changeRequestId)

Parameters


ticketId Integer The unique 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.


› An array of FirewallChange (see page 288) › An exception

For change requests other than Add Rule or Modify Rule, an exception is returned if the request type is not supported.

removeAttachmentFile method

Description The removeAttachmentFile method deletes the specified attachment from a ticket in Skybox.

Syntax removeAttachmentFile (attachmentId)

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


attachmentId Integer The unique ID of the attachment. Find the ID using getAttachmentList (on page 227).




› Deletes the specified attachment from its ticket in Skybox › Returns an exception

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 retrieve the generated commands

ruleAttributes RuleAttributes (see page 309)


setSponsoringApplication method

Description Sponsoring applications for tickets enable setting the default owners for ticket phases. If an application is associated with a ticket, the phase approver settings from the selected application define the default owners for the ticket phases. If there are no approvers defined for the application or for a particular phase, the default phase owners are those defined for the ticket phases.

The setSponsoringApplication method sets the sponsoring application for a ticket.



Syntax setSponsoringApplication (ticketId, sponsoringApplicationId)

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


ticketId Integer

sponsoringApplicationId

Integer


setTicketAccessRequests method

Description The setTicketAccessRequests method sets the list of access requests for the specified ticket.

The method overwrites the existing list; to add to the list of access requests or update any existing requests, retrieve the original list (using getTicketAccessRequests (on page 232)), 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 256), and leave the rest of the fields. You can define the firewall for each request or use expandFirewallsForAccessChangeTicket (on page 221).

Note: After you create access requests for a ticket (including the firewall for each request), you can call analyzeAccessChangeTicket (on page 216) 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 257)




setTicketFields method

Description The setTicketFields method sets ticket data in Skybox. You can use it with all types of tickets.

Note: This method and getTicketFields translate between the external ticket ID and the Skybox ticket ID. All other methods use only the Skybox ticket ID.

Syntax setTicketFields (ticketIdType, ticketId, ticketField)

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


ticketIdType String Signifies 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 314)


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 234)), 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 304)

phaseOperation PhaseOperation (see page 304)


updateAccessChangeTicket method

Description The updateAccessChangeTicket method makes changes to an Access Change ticket.

The method overwrites the existing ticket. To add fields or update any existing field values, retrieve the original ticket (using getAccessChangeTicket (on page 225)), 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 access requests.

Syntax ticket = updateAccessChangeTicket (accessChangeTicket)

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


accessChangeTicket


Make any necessary changes.


› An updated Access Change ticket (see page 255) data structure › An exception

USING THE TICKETS API Use the following URLs to view or access the web service, where <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 169) to read Skybox events.

2 Filter the output for relevant events (for example, those with type = ticket_create).

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 239) to set the External ID field in the Skybox ticket.

Future ticket update events from Skybox include the external ticket ID.

c. (Optional) Use setTicketFields (on page 239) 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 233) 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 217) to pass the parameters for creation of a Skybox ticket describing the change request.

The information passed includes metadata such as workflow, title, owner, priority, and due date. Information about the actual change request is only passed after the ticket is created.

2 Use updateAccessChangeTicket (on page 240) to pass the change request. Before you do this, 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 221). 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 Call analyzeAccessChangeTicket (on page 216) to check connectivity and policy compliance; the result is in the relevant fields of each access request.

To work at the network level, find and complete the network elements for the source and destination, as explained in findNetworks (on page 195).


Chapter 11

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 the new and updated Vulnerability Definitions to see if they occur within your organization, or to check if the updated Vulnerability Definitions already have open tickets.

In this chapter

Vulnerabilities API methods ................................................. 242

Using the Vulnerabilities API ................................................ 250

VULNERABILITIES API METHODS The methods in the Vulnerabilities web service are described in the following table.

Method Description

countVulnerabilities (on page 244)

Counts the number of vulnerability occurrences that match the specified filter. This method is used for page calculations.

countVulnerabilityTypes (on page 244)

Counts the number of Vulnerability Definitions that match the specified filter. This method is used for page calculations.

countVulnerabilityTypeTickets (on page 245)

Counts the number of threat alert tickets that match the specified filter. This method is used for page calculations.

getVulnerabilities (on page 245)

Retrieves a list of vulnerability occurrences that match the specified filter.

getVulnerabilityTypeById






Vulnerabilities API

Chapter 11 Vulnerabilities API


Method Description




2015 getVulnerabilityTypeByIdV4 (on page 247)



2015 Information about the threat alert includes the date on which it was reported.

getVulnerabilityTypes






getVulnerabilityTypesV3 (on page 247)

Returns a list of Vulnerability Definitions that match the search criteria. This method uses: • CVSS V3 for vulnerabilities published from Jan 1,


2015 getVulnerabilityTypesV4 (on page 248)

Returns a list of threat alerts that match the search criteria. Each threat alert can be a single Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses: • CVSS V3 for vulnerabilities published from Jan 1,


2015 This method is the same as getVulnerabilityTypesV3 (on page 247), but includes the reported date of each threat alert in the list.

getVulnerabilityTypeTickets (on page 249)

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 getVulnerabilities (see page 245), which returns the actual vulnerability occurrences.

Syntax numVuls = countVulnerabilities (filter)



filter VulnerabilitySearchFilter (see page 318)

The set of vulnerability occurrences that are returned.


› An integer representing the number of vulnerability occurrences that match the search criteria

› An exception

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 actual Vulnerability Definitions.

Syntax numVulTypes = countVulnerabilityTypes (filter)



filter VulnerabilityTypeSearchFilterV2 (see page 323)

The set of Vulnerability Definitions that are returned.




› An integer representing the number of Vulnerability Definitions that match the search criteria

› An exception

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 249), which returns the actual tickets.

Syntax numTickets = countVulnerabilityTypeTickets (filter)



filter VulnerabilityTypeIdFilter (see page 323)


› An integer representing the number of tickets that match the search criteria › An exception

getVulnerabilities method The getVulnerabilities method returns an array containing all the vulnerability occurrences that match the search criteria.

We recommend that you use countVulnerabilities (on page 244) to count the number of vulnerability occurrences for display purposes and then run getVulnerabilities.

Syntax matchingVuls = getVulnerabilities (filter, subRange)

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


filter VulnerabilitySearchFilter (see page 318)

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.


› An array of data structures of type Vulnerability (see page 316), sorted by ID › An exception

getVulnerabilityTypeByIdV3 method

Description The getVulnerabilityTypeByIdV3 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

Syntax vulType = getVulnerabilityTypeByIdV3 (vulnerabilityTypeId, cvssNullIndication)



vulnerabilityTypeId

VulnerabilityTypeIdV1 (see page 323)

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)


› The VulnerabilityTypeV3 threat alert (see page 319) that has the specified ID › An exception



getVulnerabilityTypeByIdV4 method

Description The getVulnerabilityTypeByIdV4 method returns a threat alert that matches the specified ID. This method returns CVSS information in the appropriate version:


Information about the threat alert includes the date on which it was reported.

Syntax vulType = getVulnerabilityTypeByIdV4 (vulnerabilityTypeId, cvssNullIndication)



vulnerabilityTypeId

VulnerabilityTypeId (on page 322)

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)


› The VulnerabilityTypeV4 (on page 320) threat alert that has the specified ID › An exception

getVulnerabilityTypesV3 method

Description The getVulnerabilityTypesV3 method returns a list of threat alerts that match the search criteria. Each threat alert can be a single Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses:


We recommend that you use countVulnerabilityTypes (on page 244) to count the number of Vulnerability Definitions for display purposes and then run this method.



Syntax vulTypes = getVulnerabilityTypesV3 (filter, subRange, cvssNullIndication)

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





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)


› An array of data structures of type VulnerabilityTypeV3 (see page 319), sorted by ID

› An exception

getVulnerabilityTypesV4 method

Description The getVulnerabilityTypesV4 method returns a list of threat alerts that match the search criteria. Each threat alert can be a single Vulnerability Definition or a security bulletin that includes multiple Vulnerability Definitions. This method uses:


This method is the same as getVulnerabilityTypesV3 (on page 247), but includes the reported date of each threat alert in the list.

We recommend that you use countVulnerabilityTypes (on page 244) to count the number of Vulnerability Definitions for display purposes and then run this method.



Syntax vulTypes = getVulnerabilityTypesV4 (filter, subRange, cvssNullIndication)

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





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)


› An array of data structures of type VulnerabilityTypeV4 (on page 320), sorted by ID

› An exception

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 245) to count the number of threat alert tickets for display purposes and then run getVulnerabilityTypeTickets.

Syntax tickets = getVulnerabilityTypeTickets (vulnerabilityTypeId)





vulnerabilityTypeId

VulnerabilityTypeIdFilter (see page 323)

Specifies the IDs of the Vulnerability Definitions that are returned.


› An array of data structures of type VulnerabilityTypeTicket (see page 325) for Vulnerability Definitions with the specified IDs

› An exception

USING THE VULNERABILITIES API Use the following URL to view or access the web service, where <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 ticket and vulnerability occurrences 1 Use countVulnerabilityTypes (on page 244) to find the number of Vulnerability

Definitions that match the filter criteria you require (for example, all Vulnerability Definitions that are new since last week with high and critical severity).

2 Use getVulnerabilityTypesV3 (on page 247) to retrieve the Vulnerability Definitions that match the filter criteria you require. 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 249) 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 244) 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 getVulnerabilities (on page 245) 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 244) to find the number of vulnerability

occurrences that match the filter criteria you require (for example, all Vulnerability Definitions that were modified since last week and whose CVSS base score is greater than 9).

2 Use getVulnerabilities (on page 245) to retrieve the vulnerability occurrences that match the filter criteria you require. 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 getVulnerabilityTypeByIdV3 (on page 246) to retrieve all data related to the Vulnerability Definitions of the retrieved vulnerability occurrences.


Chapter 12

The following code shows an example of connecting to a Skybox web service, assuming that the client stubs were generated by wsimport from WSDL, and assuming the client is using Apache CXF JAX-WS (web services provider in Java).

Note: For information about wsimport, see https://docs.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html

HttpServiceParameters sp = new HttpServiceParameters(); sp.setUsername("skyboxview"); sp.setPassword("skyboxview"); 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;

API code example

Chapter 12 API code example


import org.apache.cxf.transport.http.HTTPConduit; 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, "skyboxview"); //bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "skyboxview"); } 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 13

This chapter defines the data structures used in the Skybox web services.

In this chapter

Data structures: A to C ....................................................... 255

Data structures: D to H ...................................................... 276

Data structures: I to R ....................................................... 295

Data structures: S to Z ....................................................... 311

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 Calculated automatically. 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

Data structures



Field Type Comments • Reopened • Demoted

title String

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 277)

customFields Array of CustomField (see page 274)

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 302)

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 195).

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.

Chapter 13 Data structures


Field Type Comments

mode Integer Specifies whether the answer is to include accessible or inaccessible paths. • 0: Accessible • 1: Inaccessible • 2: Both

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 302)

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 195).

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 256)

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



Field Type Comments

complianceViolations

Array of ComplianceViolationElement (see page 273)

potentialVulnerabilities

Array of PotentialVulnerability (see page 305)

isDisabled Boolean

accessQueryMode String Possible values: • FirewallMode • NetworkMode

AccessRuleElement data structure The fields of the AccessRuleElement data structure are listed in the following table.

Field Type Comments

accessRuleId 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.

direction Integer Possible values: • 0: Undefined • 1: Inbound • 2: Outbound • 3: Both

disabled Integer Possible values: • 0: False • 1: True

firewall FirewallElement (see page 291)

The name or ID of the firewall.

globalUniqueId String The global unique ID of the access rule.

implied Integer Possible values: • 0: False • 1: True

isAuthenticated Integer Possible values: • 0: False • 1: True

isApplicationDefault Boolean The default value is false.

netInterfaces Array of String



Field Type Comments

accessRuleId Integer The ID of the access rule.

orgDestinationText String The original text in the destination field.

orgPortsText String The original text in the services field.

orgRuleNumber String The original rule ID as taken from 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 in the rule. (Similar to ports.)

sourceAddresses Array of String Addresses are resolved to ranges.

sourceNetworkInterfaces

Array of String

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 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 are: • AND (all fields) • OR (any field)

firewallScope FWScope (see page 294)

The list of firewalls to include in the search scope. The default value is All.

ignoreRulesWithAny

Boolean The default value is true.



Field Type Comments

matchCriteria String Optional This field is only relevant for numeric searches, not character searches. Possible values are: • 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 should have the format: port/protocol. Note: If only the port number is provided, the default protocol is TCP.

source String Optional An 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 276)

The time frame for which to search for access rule history records.

AddRuleChangeRequest data structure The AddRuleChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Add Rule.

The additional fields of the AddRuleChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments

createAfter String Where in the ACL to create the new rule.


Array of String Destination addresses for the new rule.

destinationObjects

Array of FirewallObjectIdentification (see page 292)

Destination objects for the new rule.

expirationDate Date Sets the expiration date for the rule.

firewall Asset (see page 266)

The (name or ID of the) firewall to which the new access rule is to be added.

hideSourceBehindGW

Boolean Specifies whether to hide the source behind the gateway address. If ON, the NATSourceAddresses and NATSourceObjects are ignored.

NATDestinationAddresses

Array of String Translated destination addresses for the new rule.

NATDestinationObjects


Translated destination objects for the new rule.

NATPortObjects Array of FirewallObjectIdentification (see page 292)

Translated port objects for the new rule.

NATPorts Array of String Translated ports for the new rule.

NATSourceAddresses

Array of String Translated source addresses for the new rule.

NATSourceObject Array of FirewallObjectIde

Translated source objects for the new



Field Type Comments s ntification (see

page 292) rule.

portObjects Array of FirewallObjectIdentification (see page 292)

Port objects for the new rule.

ports String Ports for the new rule.


Business attributes for the new rule.

ruleGroup String

ruleType String

sourceAddresses Array of String Source addresses for the new rule.

sourceObjects Array of FirewallObjectIdentification (see page 292)

Source objects for the new rule.

vpn String Describes the VPN (if a VPN exists), for the new rule.

AddRuleChangeRequestV1 data structure The AddRuleChangeRequestV1 data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Add Rule.

The additional fields of the AddRuleChangeRequestV1 data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments




destinationObjects






hideSourceBehindGW


isDestinationNegated

Boolean Specifies whether to negate the destination IP addresses (“all IP



Field Type Comments addresses except...”)

isServicesNegated Boolean Specifies whether to negate the services (“all services except...”)

isSourceNegated Boolean Specifies whether to negate the source IP addresses (“all IP addresses except...”)









NATSourceAddresses


NATSourceObjects


Translated source objects for the new rule.






ruleGroup String

ruleType String





AddRuleChangeRequestV1 data structure The AddRuleChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Add Rule.



The additional fields of the AddRuleChangeRequestV2 data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments

applications Array of FirewallObjectIdentification (see page 292)

Applications for the new rule.




destinationObjects






hideSourceBehindGW



Boolean Specifies whether to negate the destination IP addresses (“all IP addresses except...”)

isServicesNegated Boolean Specifies whether to negate the services (“all services except...”)

isSourceNegated Boolean Specifies whether to negate the source IP addresses (“all IP addresses except...”)









NATSourceAddresses


NATSourceObjects

Array of FirewallObjectIdentification (see

Translated source objects for the new rule.



Field Type Comments page 292)






ruleGroup String

ruleType String




useApplicationDefaultPorts

Boolean Specifies whether to use the default ports of the applications as the ports for the change request.

userUsage String

users String


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 folder to this analysis. The names of the folders are separated by “/”.



ApplicationConfigurationItem data structure The ApplicationConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 267) 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 267) used for groups of ApplicationConfigurationItem (see page 266). It 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, those 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 are: • Firewall • Router • LoadBalancer • Proxy • NetworkDevice • WirelessDevice • IPS • Switch

primaryIP IP The primary IP address of the asset

netInterfaces List of NetInterfaces (see page 301)

All the network interfaces of the asset

status Status of the asset: • Up • Down • Not Found



Field Type Comments • Unknown

osVendor The asset’s operating system vendor

os the asset’s operating system

osVersion String The version of the asset’s OS

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

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 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 are possible extensions to the BaseConfigurationItem data structure:

› ApplicationConfigurationItem (on page 266) › ApplicationGroupConfigurationItem (on page 266) › ServiceConfigurationItem (on page 311) › ServiceGroupConfigurationItem (on page 311)

BlockAccessChangeRequest data structure The BlockAccessChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Access Update (block access).

The additional fields of the BlockAccessChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments


Array of String Destination addresses to be blocked in the new rule.

destinationObjects


Destination objects to be blocked in the new rule.


Port objects to be blocked in the new rule.

ports String Ports to be blocked in the new rule.



sourceAddresses Array of String Source addresses to be blocked in the new rule.


Source objects to be blocked in the new 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.



Field Type Comments

Text String The content of the change log entry.

ChangeRequest data structure The fields of the ChangeRequest data structure are listed in the following table.

Note: The ChangeRequest 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) • Computing • ERROR


Date


originalChangeRequestId

Integer

verificationStatus String Possible values: • Verified • Not Verified • Error • Computing • Unknown

The following are possible extensions to the ChangeRequest data structure:

› AddRuleChangeRequest (on page 261) › AddRuleChangeRequestV1 (on page 262) › BlockAccessChangeRequest (on page 268) › DeactivateRuleChangeRequest (on page 277) › ModifyObjectChangeRequest (on page 296) › ModifyRulesChangeRequest (on page 297) › ModifyRulesChangeRequestV1 (on page 298) › RequireAccessChangeRequest (on page 307)



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 301)

destinationNetworks

Array of NetworkElement (see page 302)

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 301)

sourceNetworks Array of NetworkElement (see page 302)

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



Field Type Comments

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 205) or getZoneFromFW (on page 204) with the specified source as the input to obtain 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 205) or getZoneFromFW (on page 204) with the specified destination as the input to obtain 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: Complies • 1: Does not comply • 2: Not resolved

violations Array of ComplianceViolationElement (see page 273)



CheckAccessResult data structure The fields of the CheckAccessResult data structure are listed in the following table.

Field Type Comments

accessible Array of AccessRuleElement (see page 258)

List of accessible IP addresses (source, destination, ports, and authentication).

inaccessible Array of AccessRuleElement (see page 258)

List of inaccessible IP addresses (source, destination, ports, and authentication).

route String The 1st traceroute describing the path between the source and the destination. Note: When the result contains multiple accessible or inaccessible source-destination-port sets, there might be multiple traceroutes. The result field contains only the 1st set. To obtain more traceroutes, call the method again with the relevant accessible/inaccessible row as the query.

status ReturnStatus (see page 309)

CheckRuleComplianceRequest data structure The fields of the CheckAccessComplianceRequest 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 the value of this field to Any.

destinationAddress

Address list or range, comma-separated.

To check rule compliance using any destination, set the value of 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: Complies • 1: Does not comply • 2: Not resolved

violations Array of RuleComplianceViolationElement (see page 310)

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 Array 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

freeTextFilter String

ids Array of Integer

ignoreEmptyGroups

Boolean

isEnabled Boolean

nameFilter String



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

CVSS data structure The fields of the CVSS data structure are listed in the following table.

Field Type Comments

AccessVector String Possible values: • NETWORK • LOCAL • ADJACENT_NETWORK • NULL

AccessComplexity String Possible values: • LOW • MEDIUM • HIGH • NULL

Authentication String Possible values: • NONE • SINGLE • MULTIPLE • NULL

ConfidentialityImpact

String Possible values: • NONE • PARTIAL • COMPLETE • NULL

IntegrityImpact String Possible values: • NONE • PARTIAL • COMPLETE • NULL



Field Type Comments

AvailabilityImpact String Possible values: • NONE • PARTIAL • COMPLETE • NULL

Exploitability 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 • UNCONFIRMED • UNCORROBORATED • NOT_DEFINED

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



Field Type Comments

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

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: When using DateRange, both fields must be given values.



DeactivateRuleChangeRequest data structure The DeactivateRuleChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Deactivate Rule.

The additional fields of the DeactivateRuleChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments

accessRules Array of SlimAccessRule (see page 311)

deactivationType String Possible values: • Disable Rule • Delete Rule


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 278).

Parameters String List of parameters, including an identifier (enum) and a text value for each parameter. For information about these parameters, see Event parameter enumerations (on page 278).

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 (events such as 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 • Reopened • Demoted

Due date SBVAPI_EVENT_PARAM_DUE_DATE

8 Date (in the format 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

12 • Critical • High



Description Event name Code Possible values • Medium • Low • Very Low

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 An IP address in dot format

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 (in the format 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 (Usually RLI or VLI, but customizable by selecting Tools > Options > Server Options > Security Metrics Configuration)

The security metric’s score 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, as specified in Tools > Options > Server Options > Security Metrics Configuration



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 type of the event (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 Access Check

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_APR_TYPE

43 • ACCESS_QUERY

• SECURITY_ACCESS_RULE

• CONNECTIVITY_ACCESS_RULE

• 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 SBVAPI_EVENT_PARAM_APR_N 45 Text



Description Event name Code Possible values from the Access Policy)

OTIFICATION_SOURCE

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 257).

The additional fields of the ExtendedAccessRequest data structure (that is, those 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 • Nessus • ISS • SecurityFocus • Retina • SBV • Qualys • Microsoft • FoundScan • nCircle • Cisco PSIRT • Rapid7 • OVAL • Oracle • Adobe

Id String ID; external vulnerability database ID

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

The firewall elements from the input.



Field Type Comments (see page 291)


FindNetInterfaceResult data structure The fields of the FindNetInterfaceResult data structure are listed in the following table.

Field Type Comments

Status ReturnStatus (see page 309)

netInterfaceElements

List of NetInterfaceElement (see page 301)

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 302)

The network elements from 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 303)


FirewallAclSnapshotData data structure The fields of the FirewallAclSnapshotData data structure are listed in the following table.

Field Type Comments

aclId Integer



Field Type Comments

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 296)

targetIpSpace IPSpace (see page 296)

firewallServiceSpace FirewallServiceSpace (see page 294)

isImplied Boolean

isDisabled Boolean

isFiltering Boolean

isUnsupported Boolean

originalRuleText String

translatedSourceIpSpace

IPSpace (see page 296)

translatedTargetIpSpace


translatedFirewallService

String

chainNumber Integer

originalRuleName String



Field Type Comments

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

creationTime Date



Date

hostName String

hostIpAddress String

hostId Integer

firewallType String Possible values: • LOAD_BALANCER • GENERIC • GENERIC2 • GENERIC3 • CHECKPOINT • CHECKPOINT_NG



Field Type Comments • 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: • UNKNOWN • VIOLATING • POTENTIALLY • NOT_VIOLATING

violations String

The following data structures are extensions to this data structure:

› FirewallChangeDetails (see page 289) › FirewallChangeReconciliationDetails (see page 290)

FirewallChangeDetails data structure The FirewallChangeDetails data structure is an extended version of the FirewallChange data structure (see page 288).



The additional fields of the FirewallChangeDetails data structure (that is, those that are not included in the FirewallChange data structure) are listed in the following table.

Field Type Comments

rootPreObjectTreeNode

FirewallObjectTreeNode (see page 293)

The state of the firewall object before the change. Note: Relevant only for changes of type OBJECT.

rootPostObjectTreeNode

FirewallObjectTreeNode (see page 293)

The state of the firewall object after the change. Note: Relevant only for changes of type OBJECT.

preAclData FirewallAclSnapshotData (see page 286)

The state of the access rule before the change. Note: Relevant only for changes of type ACL.

postAclData FirewallAclSnapshotData (see page 286)

The state of the access rule after the change. Note: Relevant only for changes of type ACL.

affectedAclsData Array of FirewallAclSnapshotData (see page 286)

A list of the access rules affected by this change. Note: Relevant only for changes of type OBJECT.

FirewallChangeReconciliationDetails data structure The FirewallChangeReconciliationDetails data structure is an extended version of the FirewallChange data structure (see page 288).

The additional fields of the FirewallChangeReconciliationDetails data structure (that is, those that are not included in the FirewallChange data structure) are listed in the following table.

Field Type Comments

ticketRelationDetailsList

Array of TicketRelationDetails (see page 314)

FirewallChangesSearchFilter data structure The fields of the FirewallChangesSearchFilter data structure are listed in the following table.

Field Type Comments

trackingPeriod DateRange (see page 276)

Include only changes created between the specified dates.

folderId Integer Include only changes from firewalls that are in the specified firewall folder.



Field Type Comments

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 firewall 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 the exception


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



Field Type Comments

firewall FirewallElement (see page 291)

(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 Date Optional An expiration date for the exception

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 291)

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



Field Type Comments

firewallManagementId

Integer

firewallManagementName

String

firewallManagementType

String


ports String

members String

affectedAccessRules

Integer

newObject Boolean

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 293) for a list of possible values

name String

isTemporary Boolean

Data String

subNodes Array of FirewallObject TreeNode

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 265)

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 291)



Field Type Comments

fwFolders Comma-separated list of strings representing FW folders in Firewall Assurance.

HostAttributes data structure The fields of the HostAttributes data structure are listed in the following table.

Field Type Comments

businessFunction String

customFields Array of type EntityField (see page 277)

Custom attributes created by this organization

email String

owner String

site String

userComment String

userNameTag String

HostsAttributesUpdateInfo data structure The fields of the HostsAttributesUpdateInfo data structure are listed in the following table.

Field Type Comments

hostAttributes HostAttributes (on page 295)

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



Field Type Comments

to Integer

IPAndNetworksPair data structure The fields of the IPAndNetworksPair data structure are listed in the following table.

Field Type Comments

IPRange IPRangeElement (see page 296)

network NetworkElement (see page 302)

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 Possible values include LIVE, FORENSICS, WHAT_IF, and CORE (an internal model used for operational and system purposes)

ModifyObjectChangeRequest data structure The ModifyObjectChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Modify Object.



The additional fields of the ModifyObjectChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments

addedAddresses Array of String The addresses to add to the object being modified.

addedObjects Array of FirewallObjectIdentification (see page 292)

The objects to add to the object being modified.

addedPorts String The ports to add to the object being modified.

object FirewallObjectIdentification (see page 292)

The object to modify.

removedAddresses

Array of String The addresses to remove from the object being modified.

removedObjects Array of FirewallObjectIdentification (see page 292)

The objects to remove from the object being modified.

removedPorts String The ports to remove from the object being modified.

ModifyRulesChangeRequest data structure The ModifyRulesChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Modify Rule.

The additional fields of the ModifyRulesChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments


addedAddresses Array of String


addedPorts String


The firewall for which the rules are to be modified.

modifiedField String The field to be modified. Possible values: • Source



Field Type Comments • Destination • Service • Source NAT • Destination NAT • Service NAT

removedAddresses

Array of String


removedPorts String


submitOnAllClusterMembers

Boolean

ModifyRulesChangeRequestV1 data structure The ModifyRulesChangeRequestV1 data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Modify Rule.

The additional fields of the ModifyRulesChangeRequestV1 data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments




addedPorts String



modifiedField String The field to be modified. 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:



Field Type Comments • NO_CHANGE • NEGATE • NOT_NEGATE

removedAddresses

Array of String


removedPorts String



Boolean

ModifyRulesChangeRequestV2 data structure The ModifyRulesChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Modify Rule.

The additional fields of the ModifyRulesChangeRequestV2 data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments




addedPorts String



modifiedField String The field to be modified. 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



Field Type Comments • NOT_NEGATE

removedAddresses

Array of String


removedPorts String



Boolean

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

userUsage String Possible values: • ANY • KNOWNUSER • UNKNOWN • SELECT

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 DateTime

description String

id Integer

ipAddress String

isDefaultGateway Boolean


DateTime

layer2 Boolean



Field Type Comments

locked Boolean

lockedToNetwork Boolean

macAddress String

missingNeighbors String

modifiedBy String

name String

netMask String

networkId Integer

networkName String

networkZoneType String

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



Field Type Comments • 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 See below for possible values for this field.

The possible values for the type field when representing 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 representing 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 IPAndNetworksPair (see page 296)

destinationEntity IPAndNetworksPair (see page 296)

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



Field Type Comments • Business Group

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

ticketTypePhase TicketTypePhase (see page 315)

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

isReject 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 current phase of the ticket to this phase

Change the owner of the phase to this owner

Ignored

CLOSE Ignored Ignored Mandatory True if the user rejects the tickets

DEMOTE Ignored Change the owner of the phase to this owner

Ignored

IGNORED Ignored Ignored Ignored

PROMOTE Ignored Change the owner of the phase to this owner

Ignored

REASSIGN Ignored Mandatory The new owner of the current phase

Ignored

REOPEN Change the current phase of the ticket to this phase

Change the owner of the phase to this owner

Ignored

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 tool)

• False: Otherwise RunningWith String Environment details, for example, the

version per operating system.

RecertifyTicketCreationResult data structure The fields of the RecertifyTicketCreationResult data structure are listed in the following table.

Field Type Comments

newTicketIds Array of integer

rejectedAccessRuleElements

Array of AccessRuleElement (see page 258)

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.



Field Type Comments

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.

RequireAccessChangeRequest data structure The RequireAccessChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Access Update.

The additional fields of the RequireAccessChangeRequest data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments


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 all derived requests.


Array of String Translated destination addresses.



Translated destination objects.


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/services for the rule.

ruleAttributes RuleAttributes Business attributes for the rule.



Field Type Comments (see page 309)

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.

RequireAccessChangeRequestV2 data structure The RequireAccessChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 269) used for change requests of type Access Update.

The additional fields of the RequireAccessChangeRequestV2 data structure (that is, those that are not included in the ChangeRequest data structure) are listed in the following table.

Field Type Comments

applications Array of FirewallObjectIdentification (see page 292)

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 rule/s.


Array of String Translated destination addresses.



Translated destination objects.


Translated port objects.

NATPorts String Translated ports.

NATSourceAddresses

Array of String Translated source addresses.

NATSourceObjects


Translated source objects.

portObjects Array of Array of port objects to use as the



Field Type Comments FirewallObjectIdentification (see page 292)

ports of the rule.

ports String Array of ports/services for the rule.


Business attributes for the rule.

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.

userUsage String Possible values: • ANY • KNOWNUSER • UNKNOWN • SELECT

users String Comma separated list 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.

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 of these fields has a value, it is copied to the matching field of the access rule.

Field Type Comments

businessFunction String

comment String

customFields Array of EntityField (see page 277)

email String

nextReviewDate Date

owner String



Field Type Comments

status String The recertification status of the rule. Possible values are: • 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 Policy exception.

ruleGuid String Mandatory The global unique ID of the access rule.

rulePolicyScope Comma-separated list of rule check policies

A comma-delimited list of Rule Policy names. The default value is All Rule Checks.



Field Type Comments

expirationDate Date For exceptions with expiration dates. The default value is no expiration date.

expiratioAccessRuleModification

Boolean When 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.

ServiceConfigurationItem data structure The ServiceConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 267) used for items containing a list of services/ports.

The additional fields of the ServiceConfigurationItem data structure (that is, those 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 267) used for groups of ServiceConfigurationItem (on page 311). It holds the names of the members and the sum of all their ports.

The additional fields of the ServiceGroupConfigurationItem data structure (that is, those 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 294)

globalUniqueId String

order Integer

originalRuleName String

originalRuleText String

primaryChain Boolean

sourceIPSpace IPSpace (see page 296)

targetIPSpace IPSpace (see page 296)

translatedFirewallServiceSpace

FirewallServiceSpace (see page 294)

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 • Note • MitigateByIPS (Mitigate By IPS)

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.



Field Type Comments

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

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.

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

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, where each string is a ticket status

Search tickets by status. Possible values: • New • InProgress • Resolved • Closed • Rejected • Ignored



Field Type Comments • 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

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, such as 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

isDisabled Boolean

comment String

Vulnerability data structure The fields of the Vulnerability data structure are listed in the following table.

Field Type Comments

VulnerabilityTypeId

VulnerabilityTypeId (on page 322)

The ID and vulnerability database (according to how it was searched) of the Vulnerability Definition of the vulnerability occurrence



Field Type Comments

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

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

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



Field Type Comments

LastScanTime Long The last scan time of the vulnerability occurrence, where -1 represents no value

DiscoveryMethod String The discovery method of the vulnerability occurrence See Enum for the discovery method parameter (on page 150) for the list of possible values

Comments String User comments

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: • Info • Low • Medium • High • Critical

SeverityScoreRange

IntRange (see page 295)

Search for vulnerability occurrences by severity score range.

ReportedDateRange

DateRange (see page 276)

Search for vulnerability occurrences by their reported date.

ScanTimeRange DateRange (see page 276)

Search for vulnerability occurrences by their last scan time.

ModificationDateRange


Search for vulnerability occurrences by their modification date.

CVSSBaseScoreRange

DoubleRange (see page 277)

Search for vulnerability occurrences by their CVSS base score range.

CVSSTemporalScoreRange


Search for vulnerability occurrences by their CVSS temporal score range.

VulnerabilityTypeIdFilter

VulnerabilityTypeIdFilter (see page 323)

Search for vulnerability occurrences by range of their ID filters.

Scope Scope (see page 311)

Search for vulnerability occurrences by scope (list of asset IDs). If the scope is a group object, search in all hierarchy levels.



VulnerabilityTypeV3 data structure The fields of the VulnerabilityTypeV3 data structure are listed in the following table.

Field Type Comments

id VulnerabilityTypeIdV1 (see page 323)

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 since 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.

lastModificationSource

String The last source that modified the Vulnerability Definition: 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, where -1 represents no value.

lastUserModificationDate

Long The most recent time that the Vulnerability Definition was modified by a user, where -1 represents no value.

status String Status of the Vulnerability Definition. Possible values: • Unassigned • In Process • Irrelevant • Resolved

isForReview Boolean True when the Vulnerability Definition has been updated (either major update or any update, according to the user setting).



Field Type Comments

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 275)

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).

relatedSources Array of Source (see page 313)

The related sources of the Vulnerability Definition.

products Array of Product (see page 306)

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 312)

externalURLs Array of URLInfo (see page 315)

All related URLInfo objects.

history Array of ChangeLog (see page 268)

List of all change log entries.

VulnerabilityTypeV4 data structure The fields of the VulnerabilityTypeV4 data structure are listed in the following table.

Field Type Comments

id VulnerabilityTypeIdV1 (see page 323)

The ID and vulnerability database of the Vulnerability Definition.

title String The title of the Vulnerability Definition.



Field Type Comments

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 since 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.

lastModificationSource

String The last source that modified the Vulnerability Definition: 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, where -1 represents no value.

lastUserModificationDate

Long The most recent time that the Vulnerability Definition was modified by a user, where -1 represents no value.

status String Status of the Vulnerability Definition. Possible values: • Unassigned • In Process • Irrelevant • Resolved

isForReview Boolean True when the Vulnerability Definition has been 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



Field Type Comments

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 275)

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).

relatedSources Array of Source (see page 313)

The related sources of the Vulnerability Definition.

products Array of Product (see page 306)

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 312)

externalURLs Array of URLInfo (see page 315)

All related URLInfo objects.

history Array of ChangeLog (see page 268)

List of all change log entries.

VulnerabilityTypeId data structure The fields of the VulnerabilityTypeId data structure are listed in the following table.

Field Type Comments

ID Integer The GUI ID of the Vulnerability Definition.

Dictionary String Mandatory Possible values: • SBV • DEEPSIGHT • IDEFENSE



VulnerabilityTypeIdV1 data structure The fields of the VulnerabilityTypeId1 data structure are listed in the following table.

Field Type Comments

ID Integer The GUI ID of the Vulnerability Definition.


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 295)


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



Field Type Comments • 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 277)

Search for Vulnerability Definitions by CVSS base score range.

CVSSTemporalScores


Search for Vulnerability Definitions by CVSS temporal score range.

ReportedDate DateRange (see page 276)

Search for Vulnerability Definitions by their reported date.

modificationSource String Search for Vulnerability Definitions by the source of their last change: system or user.

systemModificationDate


Search for Vulnerability Definitions by their most recent system modification date.

userModificationDate


Search for Vulnerability Definitions by their most recent user modification date.

ExternalCatalog ExternalCatalogId (see page 285)

Search for Vulnerability Definitions by catalog name or catalog and ID.

isCVSSOverridden Boolean Search for Vulnerability Definitions by their CVSS Overridden flag.

VulnerabilityCountThreshold

Integer Search for Vulnerability Definitions by vulnerability occurrence count threshold.

threatAlertType String Possible values: • VULNERABILITY_DEFINITION • SECURITY_BULLETIN

isCustomVtOnly Boolean Search only for custom Vulnerability Definitions.

CreatedByFilter OwnersFilter (see page 304)

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), where -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 in case there are no phases.

products List of RepositoryProduct (see page 306)

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.

customFields Array of CustomField (see page 274)

A list of all custom fields for this ticket type.

demotions Integer The number of times the ticket was demoted. If no phases exist, the field is empty.

externalTicketId Integer The external ticket ID if this exists, or empty otherwise.



Field Type Comments

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 312)

A list of all selected solutions for the ticket.

networkScope Array of NetworkEntityItem (see page 303)

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.

developer’s guide - skybox...

Documents