Developer’s Guide - Skyboxdownloads.skyboxsecurity.com/files/Installers/Archive/8.5/8.5.500/D… · Skybox®, Skybox® Security, Skybox Firewall Assurance, Skybox Network Assurance,

Skybox

Developer’s Guide

8.5.500

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/7000/8000, 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.500 3

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

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

Part I: Integration .................................................................................. 12

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

iXML elements ....................................................................................... 16 List of iXML elements, subelements, and attributes ................................ 16 Hierarchical order of iXML elements ..................................................... 24 Examples of iXML code ....................................................................... 26 Description of iXML elements .............................................................. 32

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

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

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

Contents

Skybox Developer’s Guide


Part II: APIs ........................................................................................ 164

Introduction to Skybox APIs .................................................................. 165 APIs ............................................................................................... 165 Methods ......................................................................................... 166 Connecting to the Skybox APIs .......................................................... 174

Administration API ............................................................................... 176 Administration API methods .............................................................. 176 Using the Administration API ............................................................. 183

Firewall Changes API ............................................................................ 184 Firewall Changes API methods ........................................................... 184 Using the Firewall Changes API ......................................................... 189

Network API ........................................................................................ 191 Basic field types used in the API ........................................................ 191 Network API methods....................................................................... 192 Using the Network API ..................................................................... 217

Tickets API .......................................................................................... 220 Tickets API methods ........................................................................ 220 Using the Tickets API ....................................................................... 247

Vulnerabilities API ................................................................................ 249 Vulnerabilities API methods .............................................................. 249 Using the Vulnerabilities API ............................................................. 256

API code example ................................................................................ 258

Data structures .................................................................................... 261 Data structures: A to C .................................................................... 261 Data structures: D to H .................................................................... 282 Data structures: I to R ..................................................................... 301 Data structures: S to Z..................................................................... 315


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 12): Explains how to integrate data from non-standard devices and sources with the Skybox platform

› APIs (on page 164): 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.500/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.

Introduction



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

Chapter 1 Introduction


The Skybox Security Suite includes:

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

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

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

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

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

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

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

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

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

› Detects vulnerabilities on network devices and "un-scannable" systems › Targets imminent threats for immediate response and systematically reduces

potential threats with context-aware remediation guidance

Skybox Threat Manager Threat Manager consolidates threat intelligence sources and analyzes and prioritizes advisories in the context of your attack surface. It automatically analyzes the potential impact of a threat and provides remediation guidance, so that you can respond to imminent threats in minutes. Stay on top of threat intelligence with on-demand impact assessment.



› Take command of threat intelligence with on-demand impact assessments › Prioritize threats and remediation efforts quickly and accurately by combining

intelligence on your attack surface and threats in the wild › Consolidate threat intelligence into a single common view › Optimize threat remediation tasks with built-in workflows and automated

status tracking

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

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

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

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

single consistent and efficient process

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

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

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

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

› Troubleshoots access paths to ensure business continuity

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

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

Chapter 1 Introduction


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

› Ensures changes are made as intended and don’t introduce new risk › Customizes and simplifies workflows to reduce change management time by

80 percent › Establishes end-to-end rule life cycle management for secure infrastructure

and optimized firewalls

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

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

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

› Drills down to specific sites or zooms out for panoramic attack surface visibility

› Customizes views to focus on IOE types and severity levels or see IOE trends and history to track risk-reduction progress

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

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

Skybox model .................................................................... 14

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 following figure shows the typical process (using Perl).

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

Introduction to integration



(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 custom 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)

Chapter 2 Introduction to integration


• 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, subelements, and attributes ................. 16

Hierarchical order of iXML elements ...................................... 24

Examples of iXML code ........................................................ 26

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

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

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

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

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

Element Subelements Attributes

<intermediate_model> (on page 62)

<creation_time> <network_model> <business_model>

version method creation_time last_scan_time

<intermediate_model> subelements

<creation_time> (on page 49)

time

<network_model> (on page 72)

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

iXML elements

Chapter 3 iXML elements



<business_model> (on page 46)

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

<network_model> subelements


<network> (on page 70)

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

<asset> (on page 39)

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

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



Element Subelements Attributes latitude longitude high_availability_active

<host_group> (on page 59)

<host_ref> <network_ref>

name group_type owner ip_network comment

<asset_category> (on page 43)

<asset_ref> <network_ref>

name owner ip_network comment

<asset_group> (on page 44)

<asset_ref> <network_ref>

name owner ip_network comment

<vpn_tunnel> (on page 87)

name number mask type endpoint1 endpoint2 last_scan_time display_as_cloud do_not_outdate comment

<config_check_result> (on page 48)

<host_ref> key type status detection_time file_name line_number actual_result

<tenant> (on page 85)

<host_ref> <security_group_ref> <security_tag_ref>

id name description type data_mode comment

<security_tag> (on page 76)

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

id name description tag_position comment




<security_group> (on page 75)

<host_ref> id name description comment

<network> subelements

<segment> (on page 77)

<host_ref> <ip_range_ref>

name type is_virtual private_vlan_type parent_vlan_id vlan_id is_distributed is_promiscuous other_names

<asset> subelements

<interface> (on page 60)

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

<service> (on page 79)

<vulnerability_occurrence>

banner vendor_banner product_banner version_banner port interfaces last_scan_time status comment

<routing_rule> (on page 74)

destination gateway dynamic interface vrouter via_vrouter via_global null_route preference comment

<access_rule> (on id



Element Subelements Attributes page 32) source

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

<ips_access_rule> (on page 63)

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



Element Subelements Attributes destination_obj service_obj source_zone destination_zone application user acl_expiration_date

<ips_rule_group> (on page 65)

<ips_rule> name

<nat_rule> (on page 68)

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

<vulnerability_occurrence> (on page 91)

definition id sbv_id title policy last_scan_time scanner_severity scanner_description comment




<patch> (on page 73)

product code comment

<vpn_unit> (on page 88)

name orig_text my_domain peer_domain service interface

<vrouter> (on page 89)

name

<config_file> (on page 48)

path

<address_object> (on page 35)

name domains ip_ranges comment

<address_group_object> (on page 34)

<address_object_ref> name comment

<service_object> (on page 81)

name fw_services comment

<service_group_object> (on page 81)

<service_object_ref> name comment

<firewall_application> (on page 52)

name standard_ports

<firewall_application_group> (on page 53)

<firewall_app_ref> name standard_ports

<firewall_user> (on page 54)

name

<firewall_user_group> (on page 54)

<firewall_user_ref> name

<custom_property> (on page 50)

property_name property_value

<ips_rule_group> subelements

<ips_rule> (on page 66)

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



Element Subelements Attributes comment

<..._ref> subelements

<address_object_ref> (on page 35)

name

<asset_ref> (on page 44)

ip unique_tag

<firewall_app_ref> (on page 53)

name

<firewall_user_ref> (on page 54)

name

<host_ref> (on page 60)

ip unique_tag

<ip_range_ref> (on page 63)

ip

<network_ref> (on page 73)

ip

<security_group_ref> (on page 76)

id

<security_tag_ref> (on page 77)

id

<service_object_ref> (on page 82)

name

<business_model> subelements


<application> (on page 36)

<host_ref> <ip_range_ref>

name dependency owner comment uid

<business_unit> (on page 47)

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

name owner comment uid

<damage> (on page 50)

<application_ref> <host_ref>

name effect per_member value rate

<dependency> (on page 51)

<source> <destination>

name effect any

<regulation> (on page 74)

<application_ref> name effect value



Element Subelements Attributes rate

<business_impact_type> (on page 45)

<application_ref> name effect value rate

<location> (on page 67)

<network_ref> <location_ref>

name

<threat> (on page 86)

<application_ref> <host_ref> <network_ref>

name probability skill value

<threat_group> (on page 87)

<threat_ref> name

<dependency> subelements

<source> (on page 82)


effect

<destination> (on page 52)


effect

<..._ref> subelements

<application_ref> (on page 37)

name uid

<business_unit_ref> (on page 47)

name uid

<group_ref> (on page 55)

name

<host_ref> (on page 60)

ip unique_tag

<ip_range_ref> (on page 63)

ip

<location_ref> (on page 67)

name

<network_ref> (on page 73)

ip

<threat_ref> (on page 87)

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_application_group> <firewall_app_ref> <firewall_user> <firewall_user_group> <firewall_user_ref> <custom_property> <host_group> <host_ref> Note: At least 1 instance per <host_group> <network_ref> <asset_category> <asset_ref> Note: At least 1 instance per <asset_category> <network_ref> <asset_group> <asset_ref> Note: At least 1 instance per <asset_group> <network_ref> <vpn_tunnel> <config_check_result> <host_ref> Note: At least 1 instance per <config_check_result> <tenant> <host_ref> <security_group_ref> <security_tag_ref> <security_tag> <host_ref> <access_rule> <nat_rule> <firewall_application> <firewall_application_group> <firewall_app_ref> <firewall_user> <firewall_user_group> <firewall_user_ref> <address_object> <address_group_object> <address_object_ref> <service_object>



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

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

› Example of iXML code for network and business models (on page 26) › Example of iXML code for an L2 firewall (on page 29) › Example of iXML code for VPN (on page 29) › Example of iXML code for an IPS device (on page 30) › Example of iXML code for an Application and Service Repository (on page 31)

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 95). <?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. <?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 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 that are permitted for this access rule. • Separate the values of a range with a hyphen.

The default value is 0.0.0.0-255.255.255.255.

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


service A comma-separated list of access rule services that are permitted for this access rule; 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. • Inbound • Outbound • Both (default)




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

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

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

source_orig_text The source 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 access rule as it appeared in the configuration file.

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

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

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

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

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

authenticated Specifies whether the access rule is authenticated.

comment A free-form user comment.

description A description of the access rule.

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

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

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

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

service_obj A semicolon-separated list of service object names.

source_zone A semicolon-separated list of source zone names.

destination_zone A semicolon-separated list of destination zone names.

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




is_negated_source

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

is_negated_destination

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

is_negated_service

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

is_negated_application

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

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

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

source_security_group_obj

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

destination_security_group_obj

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

acl_expiration_date

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

See also

› <asset> element (on page 39) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › AddAccessRule method (on page 97) › AddComment method (on page 107) › The Assets topic in the Skybox Reference Guide › SetRuleVpnValue method (on page 156)

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

<address_object> element


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

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



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

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

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


See also

› <access_rule> element (on page 32) › <asset> element (on page 39)

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

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

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

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


uid The unique ID of the Business Asset Group.



See also

› <application_ref> element (on page 37) › <host_ref> element (on page 60) › <ip_range_ref> element (on page 63) › AddApplication method (on page 101)

<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 referenced Business Asset Group.

uid The unique ID of the referenced Business Asset Group.

See also

› <application> element (on page 36) › AddApplicationBusinessImpactTypeRef method (on page 102) › AddApplicationRef method (on page 103) › AddApplicationRegulationRef method (on page 103)

<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



Attribute Description 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 38) › Example of iXML code for an Application and Service Repository (on page 31)

<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 37) › <app_group_conf_item> element (on page 38)

<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 31) › <app_conf_item> element (on page 37) › <app_group_conf_item_ref> element (on page 39)

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

<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> <address_object> <address_group_object> <service_object> <service_group_object> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <custom_property> </asset>

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

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


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

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

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

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

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




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

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

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

inbound_chains A comma-separated list of the names of inbound rule chains to use for access rules. Note: This attribute is applicable only if 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.

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

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

status • Up (default) • Down • Unknown

unique_tag Add this attribute to an asset 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. The default value is false.

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

primary_chain The name and direction of the primary chain. Note: This attribute is applicable only if 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 known domain.

user The user that is associated with the asset.

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

latitude The latitude coordinate of the asset.

longitude The longitude coordinate of the asset.

high_availability_active

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

See also

› <access_rule> element (on page 32) › <interface> element (on page 60) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › <service> element (on page 79) › <vulnerability_occurrence> element (on page 91) › <patch> element (on page 73) › <vpn_unit> element (on page 88) › <ips_access_rule> element (on page 63) › <ips_rule_group> element (on page 65) › <vrouter> element (on page 89) › <config_file> element (on page 48) › <custom_property> element (on page 50) › <address_group_object> element (on page 34) › <address_object> element (on page 35) › <service_group_object> element (on page 81)



› <service_object> element (on page 81) › <firewall_application> element (on page 52) › <firewall_user> element (on page 54) › <firewall_user_group> element (on page 54) › <host_ref> element (on page 60) › <asset_ref> element (on page 44) › Banners (on page 80) › AddComment method (on page 107) › AddConfigFile method (on page 108) › AddHost method (on page 117) › SetLastScanTime method (on page 155) › SetEntityValue method (on page 153) › 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> <network_ref> </asset_category>

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

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

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


name The name of the asset group to add.

owner The name of the owner of the asset group.

ip_network The IP network of the asset group.


See also

› <group_ref> element (on page 55) › <asset_ref> element (on page 44) › AddHostGroup method (on page 119)



› 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> <network_ref> </asset_group>

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

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

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






See also

› <group_ref> element (on page 55) › <asset_ref> element (on page 44) › AddHostGroup method (on page 119) › 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 43) and the <asset_group> element (see page 44) only. To reference an asset elsewhere, use the <host_ref> element (see page 59).

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




ip The name or IP address of the referenced asset.

unique_tag Add this attribute to an <asset_ref> element 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 39) › AddHostRef method (on page 120)

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

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



› AddBusinessImpactType method (on page 104)

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

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 36) › <business_unit> element (on page 47) › <damage> element (on page 50) › <dependency> element (on page 51) › <regulation> element (on page 74) › <business_impact_type> element (on page 45) › <location> element (on page 67) › <threat> element (on page 86) › <threat_group> element (on page 87) › AddApplication method (on page 101) › AddDamage method (on page 110) › AddThreat method (on page 141) › AddDependency method (on page 111) › AddLocation method (on page 127) › AddBusinessUnit method (on page 105)



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


uid The unique ID of the Business Unit.

See also

› <application_ref> element (on page 37) › <business_unit_ref> element (on page 47) › <group_ref> element (on page 55) › <location_ref> element (on page 68) › AddBusinessUnit method (on page 105)

<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 referenced Business Unit.

uid The unique ID of the referenced Business Unit.



See also

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

<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 The time of the analysis. The format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

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 72) › <host_ref> element (on page 60)

<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 39) › AddConfigFile method (on page 108)

<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 format is MMM dd, yyyy HH:mm. You can omit leading zeroes. The default value is the current date and time.

See also

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



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

rate The quantitative value of the damage, in default currency



Attribute Description 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 37) › AddDamage method (on page 110)

<dependency> element

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

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

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

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


name The name of the dependency rule 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 52) › <source> element (on page 82) › AddDependency method (on page 111)



› 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 adds a destination to a dependency rule. A destination is the effect of possible damage (for example, an availability loss on a payment system).

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


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

See also

› <dependency> element (on page 51) › <source> element (on page 82) › <application_ref> element (on page 37) › <host_ref> element (on page 60) › AddDependency method (on page 111) › AddDependencyDestination method (on page 113) › AddDependencySource method (on page 113)

<firewall_application> element


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

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


name The name of the firewall application.




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

See also


<firewall_application_group> element

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

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

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


name The name of the firewall application group.

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

See also

› <firewall_application> element (on page 52) › <asset> element (on page 39)

<firewall_app_ref> element


Description The <firewall_app_ref> element references a specific firewall application.

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


name The name of the referenced firewall application.



See also

› <firewall_application> element (on page 52)

<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 54) › <asset> element (on page 39)

<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 referenced firewall user.

See also

› <firewall_user> element (on page 54)

<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 referenced asset group.

See also

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

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

Syntax with 1st-level subelements <host> <access_rule> <interface> <nat_rule> <routing_rule> <service> <vulnerability> <patch> <vpn_unit> <ips_access_rule> <ips_rule_group>



<vrouter> <config_file> <address_object> <address_group_object> <service_object> <service_group_object> <firewall_application> <firewall_application_group> <firewall_user> <firewall_user_group> <custom_property> </asset>

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

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


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



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

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

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



Attribute Description 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 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 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. The default value is false.

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

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



Attribute Description 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 known 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 format is MMM dd, yyyy HH:mm. You can omit leading zeroes.

latitude The latitude coordinate of the asset.

longitude The longitude coordinate of the asset.

high_availability_active

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

See also

› <asset> element (on page 39) › <access_rule> element (on page 32) › <interface> element (on page 60) › <nat_rule> element (on page 68) › <routing_rule> element (on page 74) › <service> element (on page 79) › <vulnerability_occurrence> element (on page 91) › <patch> element (on page 73) › <vpn_unit> element (on page 88) › <ips_access_rule> element (on page 63) › <ips_rule_group> element (on page 65) › <host_ref> element (on page 60) › <vrouter> element (on page 89) › <config_file> element (on page 48) › <custom_property> element (on page 50) › <address_group_object> element (on page 34) › <address_object> element (on page 35) › <firewall_application> element (on page 52) › <firewall_user> element (on page 54) › <firewall_user_group> element (on page 54) › <service_group_object> element (on page 81) › <service_object> element (on page 81)



› Banners (on page 80) › AddComment method (on page 107) › AddConfigFile method (on page 108) › AddHost method (on page 117) › SetLastScanTime method (on page 155) › SetEntityValue method (on page 153) › 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 43). The <host_group> element with group_type = BusinessUnit is superseded by the <asset_group> element (see page 44). Functionality is retained for backward compatibility.

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

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

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



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




See also

› <asset_category> element (on page 43)



› <asset_group> element (on page 44) › <group_ref> element (on page 55) › <host_ref> element (on page 60) › AddHostGroup method (on page 119) › 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 39) › AddHostRef method (on page 120)

<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. The default value is false.




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 160). The default value is Ethernet.

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

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


proxy_arp_type The behavior of this network interface regarding ARP requests: • Static: The interface acts as a proxy for ARP requests

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

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

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

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

zone The zone of the interface.

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


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

description A description of the interface.

Note: In 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 39) › AddComment method (on page 107) › AddInterface method (on page 121) › The Network interfaces section in the Skybox Reference Guide › SetEntityValue method (on page 153)

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

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 159). The default value is INTERMEDIATE.

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

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



See also

› <business_model> element (on page 46) › <creation_time> element (on page 49) › <network_model> element (on page 72) › IntegrationSecurityModel method (on page 148) › SetCreationTime method (on page 152) › SetLastScanTime method (on page 155) › SetDiscoveryMethod method (on page 153)

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

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

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

The default value is ANY.

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

The default value is ANY.

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



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

• Inbound • Outbound • Both (default)

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

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

The default is all interfaces.

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

The default is all interfaces.

ips_rule_group_ref

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





orig_text The IPS access rule as it appeared in the configuration file.

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




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







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


acl_expiration_date

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

See also

› <asset> element (on page 39) › <ips_rule_group> element (on page 65) › AddIpsAccessRule method (on page 123) › AddIpsRuleGroup method (on page 127) › 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 Description attribute of the <ips_access_rule> element (see page 65).

See also

› <asset> element (on page 39) › <ips_access_rule> element (on page 63) › AddIpsAccessRule method (on page 123) › AddIpsRuleGroup method (on page 127) › 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

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

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 160). 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 65) › AddIpsRule method (on page 125) › 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 68) › AddLocation method (on page 127)



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

See also

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

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

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

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


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


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


semicolon.



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

destination port, and protocol are permitted. translated_source The translated source IP address.

translated_destination

The translated destination IP address.

translated_service The translated service.

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

chain The name of the rule chain to which to add this NAT rule. Rule chain names are set by the <asset> element (on page 39). 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 NAT rule. • IP address ranges are not permitted.

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





orig_text The NAT rule as it appeared in the configuration file.

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

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


description A description of the NAT rule.

translated_source_obj

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

translated_destination_obj

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

translated_service_obj

A semicolon-separated list of translated service object names.









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

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


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

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


acl_expiration_date

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

See also

› <asset> element (on page 39) › <access_rule> element (on page 32) › <routing_rule> element (on page 74) › AddComment method (on page 107) › AddNatRule method (on page 129) › 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 160). The default value is Regular.

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

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

source_alternative_ip_ranges

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

source_excluded_ip_ranges

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

destination_alternative_ip_ranges

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

destination_excluded_ip_ranges

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

owner The name of the owner of the network.

zone_id The global unique identifier (GUID) of the zone to which this network belongs.

include_hosts

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


See also

› <network_ref> element (on page 73) › <segment> element (on page 77)



› AddComment method (on page 107) › AddNetwork method (on page 130) › SetCloudDestinationAlternativeIPRanges method (on page 149) › SetCloudDestinationExcludedIPRanges method (on page 150) › SetCloudSourceAlternativeIPRanges method (on page 150) › SetCloudSourceExcludedIPRanges method (on page 151) › SetEntityValue method (on page 153) › SetLastScanTime method (on page 155) › 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 14)).

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 59) › <asset_category> element (on page 43) › <asset_group> element (on page 44) › <asset> element (on page 39) › <network> element (on page 70) › <vpn_tunnel> element (on page 87) › <config_check_result> element (on page 48) › AddNetwork method (on page 130) › AddHost method (on page 117) › AddInterface method (on page 121)



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

See also

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

<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 107) › AddPatch method (on page 133)



<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 37) › AddRegulation method (on page 134)

<routing_rule> element


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

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




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

gateway The gateway IP address for the rule.

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

interface The network interface for the rule.

vrouter The virtual router through which to route traffic.

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

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

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

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


See also

› <asset> element (on page 39) › <access_rule> element (on page 32) › <nat_rule> element (on page 68) › <vrouter> element (on page 89) › AddComment method (on page 107) › AddRoutingRule method (on page 135) › The Assets topic in the Skybox Reference Guide › The Working with routing rules chapter in the Skybox Reference Guide

<security_group> element

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

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

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




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

name The name of the security group.

description A description of the security group.


See also

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

<security_group_ref> element


Description The <security_group_ref> element references a specific security group.

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


id The ID of the referenced security group.

See also

› <tenant> element (on page 85)

<security_tag> element

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



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

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


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

name The name of the security tag.

description A description of the security tag.

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


See also


<security_tag_ref> element


Description The <security_tag_ref> element references a specific security tag.

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


id The ID of the referenced security tag.

See also

› <tenant> element (on page 85)

<segment> element

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



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

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


name The name of the segment to 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. The default value is false.

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

Note: The default value (and the value to use 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. The default value is false.

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




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


See also

› <host_ref> element (on page 60) › <ip_range_ref> element (on page 63) › AddComment method (on page 107) › AddSegment method (on page 137)

<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. vendor_banner The vendor name as contained in the service banner.

product_banner The product name as contained in the service banner.

version_banner The version as contained in the service banner.

port The service port number and protocol.

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

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



Attribute Description 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 39) › <vulnerability_occurrence> element (on page 91) › Banners (on page 80) › AddComment method (on page 107) › AddService method (on page 138) › SetEntityValue method (on page 153) › SetLastScanTime method (on page 155) › 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



Attribute Description 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 39) › <access_rule> element (on page 32) › AddServiceObject method (on page 139)

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

<source> element

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

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

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




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

See also

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

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



› Example of iXML code for an Application and Service Repository (on page 31)

<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 83) › <srv_group_conf_item> element (on page 84)

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

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;



Attribute Description Implementation: joes".

See also

› Example of iXML code for an Application and Service Repository (on page 31) › <srv_conf_item> element (on page 83) › <srv_group_conf_item_ref> element (on page 85)

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

<tenant> element

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

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

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


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

name The name of the tenant.




description A description of the tenant.

type The type of the tenant.

data_mode


See also


<threat> element

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

Description The <threat> element adds a threat to the model. (In 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 160).

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

See also

› <threat_group> element (on page 87) › <threat_ref> element (on page 87) › AddThreat method (on page 141)



<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 86) › <threat_ref> element (on page 87)

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

See also

› <threat> element (on page 86) › <threat_group> element (on page 87) › AddThreatRef method (on page 142)

<vpn_tunnel> element




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

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





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

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


See also

› <vpn_unit> element (on page 88) › AddVpnTunnel method (on page 142) › SetLastScanTime method (on page 155)

<vpn_unit> element


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



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


name VPN unit name.

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

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

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

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

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

See also

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

<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 74) and the <interface> element (see page 60).

See also

› <asset> element (on page 39) › <routing_rule> element (on page 74) › <interface> element (on page 60) › AddVrouter method (on page 145)



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

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

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

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

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




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

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

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

scanner_description

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


See also

› <vulnerability_occurrence> element (on page 91) › <asset> element (on page 39) › <service> element (on page 79) › AddComment method (on page 107) › AddCustomVulnerability method (on page 109) › AddVulnerability method (on page 145) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 161)

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

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

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

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

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

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

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

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

scanner_description

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




description of custom Vulnerability Definitions only.


See also

› <asset> element (on page 39) › <service> element (on page 79) › AddComment method (on page 107) › AddCustomVulnerability method (on page 109) › AddVulnerability method (on page 145) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 161)

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

In this chapter

Parameters of API methods .................................................. 94

API methods and generated iXML code .................................. 94

Examples of Perl scripts ....................................................... 95

Mandatory include statements for Perl scripts ......................... 96

Description of Perl API methods ............................................ 97

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

Perl API methods

Chapter 4 Perl API methods


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

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 117) sets most of the attributes of an <asset> element (see page 39) and the AddService method (see page 138) sets most of the attributes of a <service> element (see page 79). However, some attributes cannot be added using these methods. Occasionally, there are special methods for these attributes (for example, the SetCloudDestinationAlternativeIPRanges (see page 149) method), but attributes can always be added (or modified) using the SetEntityValue method (see page 153).

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 29). ################################################################## # # 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"); # 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. • Inbound • Outbound • Both (default)

chain (Optional) The rule change to which the access rule is appended. Rule chain names are set by the AddHost method (on page 117).

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). The default value is false. For example, a device whose default behavior is to block all packets when no access rules are defined has an implied rule of "src=any, dest=any, action=Deny".

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

uid (Optional) 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 default value is false.


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

is_negated_service

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


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

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 117) › AddNatRule method (on page 129) › AddRoutingRule method (on page 135) › <access_rule> element (on page 32) › <asset> element (on page 39) › The Assets topic in the Skybox Reference Guide

AddAddressObject method

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

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


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




Note: You must include a value for at least 1 of ip_ranges and domains.

name The name of the address object to add.

domains A semicolon-separated list of domain names. Note: You must include a value for at least 1 of domains and ip_ranges.



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

iXML code generated The following iXML code is generated by the preceding examples of the AddAddressObject method. <address_object name="net1" ip_ranges="1.1.1.1" /> <address_object name="news" domains="www.a.co.il;www.b.co.il" />

See also

› <asset> element (on page 39) › <address_object> element (on page 35)

AddAddressGroupObject method

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

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


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



name The name of the address group.

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

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

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



<address_group_object name="address_group1" > <address_object_ref name="net1" /> <address_object_ref name="news" /> </address_group_object>

See also

› <asset> element (on page 39) › <address_group_object> element (on page 34)

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

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

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 103) › AddHostRef method (on page 120) › <application> element (on page 36) › <application_ref> element (on page 37) › <host_ref> element (on page 60)

AddApplicationBusinessImpactTypeRef method

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

Description The AddApplicationBusinessImpactTypeRef method attaches 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 104) › <application_ref> element (on page 37)



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 101) › AddDamage method (on page 110) › AddThreat method (on page 141) › <application_ref> element (on page 37)

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 134) › <application_ref> element (on page 37)

AddBusinessImpactType method

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

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


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





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

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

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

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 103) › AddBusinessUnitRef method (on page 106) › AddGroupRef method (on page 117) › AddLocationRef method (on page 128) › <application_ref> element (on page 37) › <business_unit> element (on page 47) › <business_unit_ref> element (on page 47) › <group_ref> element (on page 55) › <location_ref> element (on page 68)

AddBusinessUnitRef method

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

Description The AddBusinessUnitRef method attaches 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 105) › <business_unit_ref> element (on page 47)

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 32) › <application> element (on page 36) › <business_unit> element (on page 47) › <host_group> element (on page 59) › <asset_category> element (on page 43) › <asset_group> element (on page 44) › <asset> element (on page 39) › <interface> element (on page 60) › <ips_access_rule> element (on page 63) › <ips_rule> element (on page 66) › <nat_rule> element (on page 68) › <network> element (on page 70) › <patch> element (on page 73) › <routing_rule> element (on page 74) › <segment> element (on page 77) › <service> element (on page 79) › <vpn_tunnel> element (on page 87) › <vulnerability_occurrence> element (on page 91)

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 117) › <config_file> element (on page 48)

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

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 161). Any other value is mapped to ID 3326 (Uncataloged



Parameter Description Generic Vulnerability) and the Vulnerability Definition is not used by Skybox during attack simulation.

title (Optional) A title for the vulnerability occurrence. 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 161)).

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 91) › AddHost method (on page 117) › AddService method (on page 138) › AddVulnerability method (on page 145) › Generic Vulnerability Definitions in the Vulnerability Dictionary (on page 161) › 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 50)

AddDependency method

Syntax The syntax of the Perl AddDependency method is:



AddDependency(name, effect, any)

Description The AddDependency method adds a dependency rule to the model. A dependency rule defines how the security of a Business Asset Group depends on the security of its members, infrastructure servers, and other assets. For example, an availability loss of a DNS server might imply an availability loss for a Business Asset Group.


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

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


name The name of the dependency rule 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 113) › AddDependencySource method (on page 113) › <dependency> element (on page 51) › <destination> element (on page 52) › <source> element (on page 82)



AddDependencyDestination method

Syntax The syntax of the Perl AddDependencyDestination method is: AddDependencyDestination(dependency, effect)

Description The AddDependencyDestination method adds a dependency rule destination to the model that describes the effect of possible damage (for example, an availability loss on a payment system).


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


dependency A reference to the dependency rule instance created by the AddDependency method.


Example The following example uses this method. $inm->AddDependencyDestination($myDependency, "CIA");

iXML code generated The following iXML code is generated by the preceding example of the AddDependencyDestination method. <destination effect="CIA" />

See also

› AddDependency method (on page 111) › AddDependencySource method (on page 113) › <destination> element (on page 52)

AddDependencySource method

Syntax The syntax of the Perl AddDependencySource method is: AddDependencySource(dependency, effect)



Description The AddDependencySource method adds a dependency rule source to the model that describes the cause of possible damage (for example, an integrity or availability loss on the web servers in your system).


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


dependency A reference to the dependency rule instance created by the AddDependency method.


Example The following example uses this method. $inm->AddDependencySource($myDependency, "CIA");

iXML code generated The following iXML code is generated by the preceding example of the AddDependencySource method. <source effect="CIA" />

See also

› AddDependency method (on page 111) › AddDependencyDestination method (on page 113) › <source> element (on page 82)

AddFirewallApplication method

Syntax The syntax of the Perl AddFirewallApplication method is: AddFirewallApplication(firewall, name, standard_ports)

Description The AddFirewallApplication method adds a firewall application to a firewall.

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 117) › <asset> element (on page 39) › <firewall_application> element (on page 52)

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 117) › <asset> element (on page 39) › <firewall_user> element (on page 54)

AddFirewallUserGroup method

Syntax The syntax of the Perl AddFirewallUserGroup method is: AddFirewallUserGroup(firewall, name, object_name)

Description The AddFirewallUserGroup method adds a firewall user group to a firewall.


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



name The name of the firewall user group 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 117)



› <asset> element (on page 39) › <firewall_user_group> element (on page 54)

AddGroupRef method

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

Description The AddGroupRef method attaches 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 119) › <group_ref> element (on page 55)

AddHost method

Syntax The syntax of the Perl AddHost method is: AddHost(assetname, ip_forwarding, os, platform, inbound_chains, outbound_chains, type, dynamic_routing, do_not_outdate, layer2)

Description The AddHost method adds an asset to the model.




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


assetname The name of the asset 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.


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

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

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



Parameter Description 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 153). For a complete list of asset attributes, see <asset> element (on page 39).

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 39) › Banners (on page 80) › The Assets topic in the Skybox Reference Guide

AddHostGroup method

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

Description The AddHostGroup method adds an asset group to the model.


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



Example The following example uses this method.



$inm->AddHostGroup("grp1");

iXML code generated The following iXML code is generated by the preceding example of the AddHostGroup method. <host_group name="grp1" />

See also

› AddHostRef method (on page 120) › <host_group> element (on page 59) › <asset_category> element (on page 43) › <asset_group> element (on page 44) › <host_ref> element (on page 60) › The Asset groups topic in the Skybox Reference Guide

AddHostRef method

Syntax The syntax of the Perl AddHostRef method is: AddHostRef(entity, ip)

Description The AddHostRef method references 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 101) › AddDamage method (on page 110)



› AddThreat method (on page 141) › <host_ref> element (on page 60)

AddInterface method

Syntax The syntax of the Perl AddInterface method is: AddInterface(asset, ip_address, ip_mask, mac_address, name, type, add_directly_connected_route, network, is_primary, layer_2, vrouter, zone, locked)

Description The AddInterface method adds an asset’s network interface to the model.

At least 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 160). The default value is Ethernet.

add_directly_connected_route

Specifies whether a routing rule to the network to which the interface is connected can be added implicitly. The default value is false. 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. The default value is false.

layer_2 Specifies whether this is an L2 interface. The default value is false.




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

zone The zone to which the interface belongs.

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

Note: In 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 153). For a complete list of interface attributes, see <interface> element (on page 60).

Example The following example uses this method. $inm->AddInterface($asset1, "192.168.90.200", "255.255.255.0", "FF:34:23:33:44:11", "myNewInterface", "Ethernet", "", "myNetwork");

iXML code generated The following iXML code is generated by the preceding example of the AddInterface method. <interface ip_address="192.168.90.200" ip_mask="255.255.255.0" mac_address="FF:34:23:33:44:11" name="myNewInterface" type="Ethernet" network="myNetwork" />

See also

› AddHost method (on page 117) › <interface> element (on page 60) › The Network interfaces topic in the Skybox Reference Guide

AddIPRangeRef method

Syntax The syntax of the Perl AddIPRangeRef method is: AddIPRangeRef(entity, ip_range)

Description The AddIPRangeRef method references 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 101) › <ip_range_ref> element (on page 63)

AddIpsAccessRule method

Syntax The syntax of the Perl AddIpsAccessRule method is: AddIpsAccessRule(asset, ips_rule_group_name, source, destination, service, direction, chain, applied_interfaces, source_interfaces, disabled, implied, source_orig_text, destination_orig_text, service_orig_text, orig_text, comment)

Description The AddIpsAccessRule method adds an IPS access rule to an asset. Every packet that matches the scope of the rule is inspected using the rules in the referenced IPS rule group (protection domain). For 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_na The name of the associated IPS rule group. Each IPS rule



Parameter Description me 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.

• Inbound • Outbound • Both (default)

chain (Optional) The name of the rule chain. Rule chain names are set by the AddHost method (on page 117).

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

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


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





orig_text The rule as it appeared in the configuration file.


Example The following example uses this method. $inm-> AddIpsAccessRule($asset1, "DNS", "any", "any", "any", "", "IPS");

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



<ips_access_rule ips_rule_group_ref="DNS" source="any" destination="any" service="any" chain="IPS" />

See also

› <asset> element (on page 39) › <ips_rule_group> element (on page 65) › <ips_access_rule> element (on page 63) › AddIpsRuleGroup method (on page 127) › 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



Parameter Description • 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 160). 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 66) › <ips_rule_group> element (on page 65) › The Assets topic in the Skybox Reference Guide



AddIpsRuleGroup method

Syntax The syntax of the Perl AddIpsRuleGroup method is: AddIpsRuleGroup(asset, ips_rule_group_name)

Description The AddIpsRuleGroup method adds an IPS rule group to an asset.


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



ips_rule_group_name

The name of the IPS rule group 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 123)).

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

iXML code generated The following iXML code is generated by the preceding example of the AddIpsRuleGroup method. <ips_rule_group name="DNS" />

See also

› <asset> element (on page 39) › <ips_rule_group> element (on page 65) › <ips_access_rule> element (on page 63) › AddIpsAccessRule method (on page 123) › 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 67)

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

name The name of the referenced location.

Example The following example uses this method. $inm->AddLocationRef($location1, "myLocation");



iXML code generated The following iXML code is generated by the preceding example of the AddLocationRef method. <location_ref name="myLocation" />

See also

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

AddNatRule method

Syntax The syntax of the Perl AddNatRule method is: AddNatRule(asset, source, destination, service, translated_source, translated_destination, translated_service, direction, chain, applied_interfaces, source_interfaces, disabled, implied)

Description The AddNatRule method adds a NAT rule to an asset.


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





service The NAT rule service. The format 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. translated_source (Optional) The translated source IP address.

translated_destination

(Optional) The translated destination IP address.

translated_service (Optional) The translated service.

direction The NAT rule direction. • Inbound • Outbound



Parameter Description • Both (default)

chain The name of the chain to which the rule belongs. Rule chain names are set by the AddHost method (see page 117).

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

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


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

Example The following example uses this method. $inm->AddNatRule($asset1, "172.20.0.0/16", "10.0.0.0/8", "21/TCP", "10.1.1.1-10.1.1.10");

iXML code generated The following iXML code is generated by the preceding example of the AddNatRule method. <nat_rule source="172.20.0.0/16" destination="10.0.0.0/8" service="21/TCP" translated_source="10.1.1.1-10.1.1.10" />

See also

› AddHost method (on page 117) › AddAccessRule method (on page 97) › AddRoutingRule method (on page 135) › <nat_rule> element (on page 68) › <asset> element (on page 39) › 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 160). 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 delete 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 70) › The Networks topic in the Skybox Reference Guide

AddNetworkGroup method

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

Description The AddNetworkGroup method adds an asset group for a specific network to the model.




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


name The name of the network group to add.

grouptype Set to "NetworkGroup".

ip_network The IP network of the group.

See also

› AddHostRef method (on page 120) › <host_group> element (on page 59) › <host_ref> element (on page 60) › The Network groups topic in the Skybox Reference Guide

AddNetworkRef method

Syntax The syntax of the Perl AddNetworkRef method is: AddNetworkRef(entity, ip)

Description The AddNetworkRef method references a 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 referenced network.

Example The following example uses this method. $inm->AddNetworkRef($location1, "192.168.80.0/24");

iXML code generated The following iXML code is generated by the preceding example of the AddNetworkRef method. <network_ref ip="192.168.80.0/24" />



See also

› AddApplication method (on page 101) › AddDamage method (on page 110) › AddThreat method (on page 141) › <network_ref> element (on page 73)

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 36) › <business_unit> element (on page 47) › <host_group> element (on page 59) › <asset_category> element (on page 43) › <asset_group> element (on page 44) › <asset> element (on page 39) › <network> element (on page 70)

AddPatch method

Syntax The syntax of the Perl AddPatch method is: AddPatch(asset, code, product)



Description The AddPatch method adds patch information to an asset.


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



code Patch code (patch ID).

product Product banner (of the product to which the patch is applied). • 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, "KB3163912", "Microsoft Windows 10");

iXML code generated The following iXML code is generated by the preceding example of the AddPatch method. <patch code="KB3163912" product="Microsoft Windows 10" />

See also

› <patch> element (on page 73) › AddHost method (on page 117) › 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 159).

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

AddRoutingRule method

Syntax The syntax of the Perl AddRoutingRule method is: AddRoutingRule(asset, destination, gateway, dynamic, vrouter, via_vrouter, via_global, null_route)

Description The AddRoutingRule method adds a routing rule to an asset.


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





destination The name or IP address of the destination network.

gateway The gateway IP address.

dynamic Specifies whether the routing rule is dynamic. The default value is false.

vrouter The virtual router through which to route traffic.

via_vrouter Specifies whether traffic is directed through a specific virtual router.

via_global Specifies whether the traffic is directed through the global virtual router.

null_route Specifies whether the route is considered as a route to null (that is, packets 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 117) › <asset> element (on page 39) › <vrouter> element (on page 89) › The Assets topic in the Skybox Reference Guide › The Working with routing rules chapter in the Skybox Reference Guide

AddRuleOriginalText method

Syntax The syntax of the Perl AddRuleOriginalText method is: AddRuleOriginalText(rule, orig_text, source_orig_text, destination_orig_text, service_orig_text)

Description The AddRuleOriginalText method adds the original text to an access rule or NAT rule (the text of the rule’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.

orig_text The rule as it appeared in the configuration file.

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 97) › AddNatRule method (on page 129) › <access_rule> element (on page 32) › <nat_rule> element (on page 68)

AddSegment method

Syntax The syntax of the Perl AddSegment method is: AddSegment(network, name)

Description The AddSegment method adds a segment to the specified network.

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



Parameter Description 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 130) › <segment> element (on page 77)

AddService method

Syntax The syntax of the Perl AddService method is: AddService(asset, banner, port, interfaces)

Description The AddService method adds a service to an asset.


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


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

banner The service banner, which helps 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 153). For a complete list of service attributes, see <service> element (on page 79).

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

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 117) › <service> element (on page 79) › Banners (on page 80) › The Services topic in the Skybox Reference Guide

AddServiceObject method

Syntax The syntax of the Perl AddServiceObject method is: AddServiceObject(fw_services, name)

Description The AddServiceObject method adds a service object to an asset.


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


fw_services A semicolon-separated list of firewall services; the format of each service can be 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 32) › <asset> element (on page 39) › <service_object> element (on page 81)

AddServiceGroupObject method

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

Description The AddServiceGroupObject method adds a service group object to an asset.


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


asset The asset to which to add the service group object.

name The name of the service group.

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

Example The following example uses this method. $inm->AddServiceGroupObject(asset, "service_group1", "srv1;srv2");

iXML code generated The following iXML code is generated by the preceding example of the AddServiceGroupObject method. <service_group_object name="service_group1" > <service_object_ref name="srv1" /> <service_object_ref name="srv2" /> </service_group_object>



See also

› <asset> element (on page 39) › <service_group_object> element (on page 81)

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

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

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 142) › <threat> element (on page 86)



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

Example The following example uses this method. $inm->AddThreatRef($threat1, "BadNews");

iXML code generated The following iXML code is generated by the preceding example of the AddThreatRef method. <threat_ref name="BadNews" />

See also

› AddThreat method (on page 141) › <threat_ref> element (on page 87)

AddVpnTunnel method

Syntax The syntax of the Perl AddVpnTunnel method is: AddVpnTunnel(name, number, netmask, type, endpoint1, endpoint2, do_not_outdate, display_as_cloud)

Description The AddVpnTunnel method adds a secure VPN to the model.


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






netmask The 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 160).

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 deleted 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 143) › <vpn_tunnel> element (on page 87) › The Networks topic in the Skybox Reference Guide

AddVpnUnit method

Syntax The syntax of the Perl AddVpnUnit method is:



AddVpnUnit(asset, name, my_domain, peer_domain, service, interface)

Description The AddVpnUnit method adds a VPN Unit to the model.


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



name VPN Unit name.

my_domain The networks protected by this gateway. The default value is ANY.

peer_domain The networks protected by the endpoint gateway. Only packets with networks that match these domains can pass thought the VPN tunnel. Note: This field is 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 117) › AddVpnTunnel method (on page 142) › <vpn_unit> element (on page 88) › The Networks topic in the Skybox Reference Guide



AddVrouter method

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

Description The AddVrouter method adds a virtual router to an asset.


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


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

name The name of the 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 117) › <vrouter> element (on page 89)

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

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 109) › AddHost method (on page 117) › AddService method (on page 138) › <vulnerability_occurrence> element (on page 91) › 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 121) › AddNetwork method (on page 130) › AssignInterfaceToSegment method (on page 147) › 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 121) › AddSegment method (on page 137)



› AssignInterfaceToNetwork method (on page 146) › The Network interfaces topic in the Skybox Reference Guide

IntegrationSecurityModel method

Description When adding or modifying a model, you must call the IntegrationSecurityModel method 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 62)

Print method

Syntax The syntax of the Perl Print method is: Print



Description The Print method prints the current model to the screen (console window).

Parameters The Print method does not have any parameters.

Example The following example uses this method. $inm->Print;

iXML code generated The Print method does not generate any iXML code.

See also

› Write method (on page 157)

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.

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

See also

› AddNetwork method (on page 130) › SetCloudDestinationExcludedIPRanges method (on page 150)



› SetCloudSourceAlternativeIPRanges method (on page 150) › SetCloudSourceExcludedIPRanges method (on page 151) › <network> element (on page 70)

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 130) › SetCloudDestinationAlternativeIPRanges method (on page 149) › SetCloudSourceAlternativeIPRanges method (on page 150) › SetCloudSourceExcludedIPRanges method (on page 151) › <network> element (on page 70)

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 130) › SetCloudDestinationAlternativeIPRanges method (on page 149) › SetCloudDestinationExcludedIPRanges method (on page 150) › SetCloudSourceExcludedIPRanges method (on page 151) › <network> element (on page 70)

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



Parameter Description 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 130) › SetCloudDestinationAlternativeIPRanges method (on page 149) › SetCloudDestinationExcludedIPRanges method (on page 150) › SetCloudSourceAlternativeIPRanges method (on page 150) › <network> element (on page 70)

SetCreationTime method

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

Description The SetCreationTime method sets the model’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. The 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 49) › <intermediate_model> element (on page 62) › IntegrationSecurityModel method (on page 148)

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

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

iXML code generated The following iXML code is generated by the preceding example of the SetDiscoveryMethod method. <intermediate_model method="NMAP" />

See also

› <intermediate_model> element (on page 62)

SetEntityValue method

Syntax The syntax of the Perl SetEntityValue method is:



SetEntityValue(entity, attribute, value)

Description The SetEntityValue method is a generic method that sets or changes 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 of the SetEntityValue method. <asset assetname="Asset1" status="down" />

SetHostUniqueTag method

Syntax The syntax of the Perl SetHostUniqueTag method is: SetHostUniqueTag(asset, tag)

Description The SetHostUniqueTag method assigns a tag to an asset. This is useful where the name or IP address of the asset might not be unique in the network.

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 117) › <asset> element (on page 39)

SetLastScanTime method

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

Description The SetLastScanTime method sets the scan time for the specified entity.

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


entity The name of the entity for which the specified scan time is applicable. The entity might be a network, asset, service, or vulnerability occurrence.

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

Example The following example uses this method. $inm->SetLastScanTime("myAsset", "Aug 1, 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 39) › <intermediate_model> element (on page 62) › <network> element (on page 70)



› <service> element (on page 79) › <vulnerability_occurrence> element (on page 91)

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


Chapter 5

This section lists the possible values of enums that are used in attributes of iXML elements and parameters of Perl API methods.

In this chapter

Enum for the Business Asset Group dependency parameter .... 158

Enum for the damage level parameter .................................. 159

Enum for the discovery method parameter ............................ 159

Enum for the asset type parameter ...................................... 159

Enum for the network interface type parameter ..................... 160

Enum for the network type parameter .................................. 160

Enum for the threat probability parameter ............................ 160

Enum for the definition parameter ....................................... 160

Generic Vulnerability Definitions in the Vulnerability Dictionary 161

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.

Enums for iXML elements and Perl API methods

Chapter 5 Enums for iXML elements and Perl API methods


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:

• UNKNOWN • NMAP • SNMPWALK • SNMPWALK_NIFS • SNMPWALK_RR • CONFIG • NESSUS • ISS • RETINA • QUALYS • NMB • TRACEROUTE • HPOV • BANNER • HFNETCHK • FOUNDSCAN • NCIRCLE • INTERMEDIATE • USER • CONFIG_PARTIAL • CONFIG_APPLICATION • HARRIS • ISS_SITEPROTECTOR • TIPPINGPOINT • SCCM • VSPHERE • VSHIELD • VCLOUD_DIRECTORY • VULNERABILITY_SCANNER • NETWORK_SCANNER • DIRECTORY • PATCH_MANAGER • CMDB • END_POINT_PROTECTOR • END_POINT_COLLECTOR • VIRTUALIZATION_MANAGER • CLOUND_MANAGER • NAC • WSUS • VULNERABILITY_DETECTOR • LANDESK • EPO • RAPID7 • OUTPOST24 • MAXPATROL • ALTIRIS • VULNERABILITY_DETECTOR_RPM • SATELLITE • FW1_CPINFO • GENERIC_CMDB • BIGFIX • CYBERX • APPSCAN

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 • Peering

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 • Peering

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

Chapter 5 Enums for iXML elements and Perl API methods


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 6

This chapter explains the workflow of specific modeling scenarios.

In this chapter

Modeling load balancers ...................................................... 162

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

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

Chapter 6 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, you must run a Model – Integrity task every time that the network is updated. For information about these tasks, see the Model integrity tasks topic in the Skybox Reference Guide.

This part describes how to retrieve data from Skybox and use its core methods remotely.

Part II: APIs


Chapter 7

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

Methods ........................................................................... 166

Connecting to the Skybox APIs ............................................ 174

APIS The main integration APIs are:

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

› SkyboxFirewallChangesService (on page 184): 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 191): Provides access analysis and Access Policy analysis; you can check change requests for connectivity (Access Analyzer) and see whether they comply with the Access Policy

› SkyboxTicketsService (on page 220): Retrieves and updates Skybox tickets › SkyboxVulnerabilitiesService (on page 249): 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.

Note: Additional web services—intended for internal use only—can be found at: https://<Skybox server>:8443/skybox/webservice/jaxwsinternal.

Introduction to Skybox APIs



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

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

Runs a CSV – Optimization & Cleanup Export task and returns the full path name of the file output by the task

findAllUsers (on page 177)

Returns a list of all users in the Skybox database

findUserByName (on page 178)

Finds a user in the Skybox database by name and returns the user’s information

getCollectorsFileStoreSpace (on page 178)

Returns information about the available space on each file store of each Skybox Collector, where a file store is a disk in Windows, and a partition in Unix.

getCollectorsUptime (on page 179)

Returns information about the uptime of each Skybox Collector.

getCSVReport (on page 179)

Returns the specified CSV or ZIP file.

getEvents (on page 179)

Retrieves a list of events from Skybox

getModelLockStatuses (on page 181)

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

getRunningTaskNames (on page 181)

Returns an array of names of currently running tasks

getRunningTasksInfo (on page 181)

getServerVersion (on page 182)

Returns the version of the Skybox Server.

launchTaskOrSequence (on page 182)

Launches a Skybox task

listCSVReports (on page 182)

ping Pings the Skybox server

testService (on page 183)

Tests communication with the web service.

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

Chapter 7 Introduction to Skybox APIs


Firewall Changes web service

Method Description

countFirewallChanges (on page 185)

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

findChangeReconciliationInfo (on page 185)

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

findFirewallChanges (on page 186)

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

getAccessRulesHistory (on page 186)

Retrieves a list of changes to an access rule.

getFirewallChangeDetails (on page 187)

Returns all data related to the specified change record.

setChangeReconciliationInfo (on page 187)

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


Tests communication with the service.

updateFirewallChangeComment (on page 188)

Adds a new comment to the specified firewall change record.

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

Network web service

Method Description

checkAccess (on page 195)

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 permit or deny the connection.

checkAccessV1 (on page 196)

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 permit or deny the connection. The method returns the 1st 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 198)

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

checkRuleCompliance (on page 202)

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

countAssetsByIps (on page 199)

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



Method Description

countAssetsByNames (on page 199)

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

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

createFirewallException (on page 201)

Creates a firewall exception in Skybox.

createRulePolicyException (on page 201)

Creates a Rule Policy exception in Skybox.

deleteFirewallException (on page 201)

Deletes a firewall exception from Skybox.

deleteRulePolicyException (on page 202)

Deletes a Rule Policy exception from Skybox.

doCheckRuleCompliance (on page 202)


findAccessRules (on page 203)

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

findAssetsByIps (on page 206)

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

findAssetsByNames (on page 206)

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

findFirewallElementFAFolderPath (on page 204)

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

findFirewallObjectByName (on page 208)

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

findFirewalls (on page 203)

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

Returns a list of the firewalls stored under the specified folder in the All Firewalls tree.

findFirewallsByName (on page 207)

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

findFirewallsByObjectName (on page 207)

Returns a list of the firewalls (in the All Firewalls tree) that have access rules that use the specified object.

findNetworkElementZone (on page 205)

Returns the zones of the specified networks.



Method Description

findNetworkEntitiesBySourceAndDestination (on page 208)

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

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

findNetworksForIPRange (on page 209)

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

findObjectAffectedAccessRules (on page 209)

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

getAccessRules (on page 211)

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

getAccessRuleAttributes (on page 210)

Returns the business attributes of the specified access rule.

getHostAttributes (on page 211)

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

getZoneFromNetwork (on page 214)

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

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

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

getNetInterfacesByAssetId (on page 212)

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

getNetInterfacesByNetworkId (on page 213)

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

isBackwardRouteExist (on page 214)

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

modifyFirewallException (on page 215)

Modifies a firewall exception in Skybox.

modifyRulePolicyException (on page 215)

Modifies a Rule Policy exception in Skybox.



updateAccessRuleAttributes (on page 216)

Updates the business attributes of 1 or more access rules.



Method Description

updateFwAccessRuleAttributes (on page 216)

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

updateHostAttributes (on page 216)

Updates the business attributes for an asset (host).

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

Tickets web service

Method Description

addAttachmentFile (on page 223)

Creates an attachment to a ticket in Skybox.

addDerivedChangeRequests (on page 224)

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

addOriginalChangeRequests (on page 224)

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

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

countAccessChangeTickets (on page 226)

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

Creates an Access Change ticket with a workflow and phases.

createRecertifyTicket (on page 227)

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

createTicketAccessRequestsForObjectChange (on page 227)

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

deleteAccessChangeTicket (on page 228)

Deletes the specified Access Change ticket in Skybox.

deleteChangeRequests (on page 229)

Deletes change requests from a ticket.

expandFirewallsForAccessChangeTicket (on page 229)

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.

findAccessChangeTickets (on page 231)

Retrieves all Access Change tickets that match the search criteria.



Method Description

findAccessRequests (on page 231)

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

findConfigurationItems (on page 232)

Retrieves the configuration items that are defined in the system

getAccessChangeTicket (on page 233)

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

getAccessRequests (on page 233)

Retrieves change requests according to their ID numbers.

getAnalysisTree (on page 234)

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

getAttachmentFile (on page 234)

Retrieves the specified attachment from Skybox.

getAttachmentList (on page 235)

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

getDerivedChangeRequests


getDerivedChangeRequestsV1 (on page 235)

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

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

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

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

getPotentialVulnerabilities (on page 238)

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



Method Description

getTicketAccessRequests (on page 239)

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

getTicketEvents (on page 240)

Retrieves the history of a ticket.

getTicketFields (on page 240)

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

getTicketPhases (on page 241)

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

getTicketTypePhasesByTicketType (on page 241)

Retrieves the list of phases for the specific ticket type.

getTicketWorkflows (on page 242)

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

getVerificationDetails (on page 242)

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

Deletes an attachment from a ticket in Skybox.

setRecertificationStatus (on page 243)

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

Sets the list of change requests to the specified ticket.

setTicketFields (on page 245)

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

setTicketPhases (on page 246)

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



updateAccessChangeTicket (on page 246)

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

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

Vulnerabilities web service

Method Description

countVulnerabilities (on page 251)

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

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



Method Description ypes (on page 251) calculations.

countVulnerabilityTypeTickets (on page 252)

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

getVulnerabilities (on page 252)

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

Returns a threat alert that matches the specified ID. This method returns CVSS information: • CVSS V3 for vulnerabilities published from Jan 1,

2016 • CVSS V2 for vulnerabilities published until Dec 31,

2015 getVulnerabilityTypeByIdV4 (on page 253)



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

getVulnerabilityTypes


getVulnerabilityTypesV1




getVulnerabilityTypesV3 (on page 254)

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

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 254), but includes the reported date of each threat alert in the list.



Method Description

getVulnerabilityTypeTickets (on page 256)

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



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

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 were generated from WSDL.

SkyboxVulnerabilities vulnerabilitiesWebServicePort = new SkyboxVulnerabilitiesService().getSkyboxVulnerabilitiesPort(); BindingProvider bp = (BindingProvider) vulnerabilitiesWebServicePort; bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "https://127.0.0.1:8443/skybox/webservice/jaxws/vulnerabilities"); bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "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, the server side logs in automatically on each call. If the session flag is true, the server side logs in on the initial call and subsequent calls are automatically attached to the existing session.

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

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

› (SOAP messages) jaxws_debug_message_enabled

› (REST messages) jaxrs_debug_message_enabled

The full requests and responses are captured in the Server debug log (<Skybox_Home>\server\log\debug\debug.log).

We recommend that you set the value of these properties to true when developing with the API.



Chapter 8

This chapter describes the SkyboxAdministrationService API, which provides administrative services related to Skybox, including:

› Retrieving administrative information › Performing administrative actions (for example, launching a Skybox task or

reading the Skybox event log)

In this chapter

Administration API methods ................................................ 176

Using the Administration API ............................................... 183

ADMINISTRATION API METHODS The methods in the Administration web service are described in the following table.

Method Description

exportOptimizationAndCleanupCSVByTask (on page 177)

Runs a CSV – Optimization & Cleanup Export task and returns the full path name of the file output by the task

findAllUsers (on page 177)

Returns a list of all users in the Skybox database

findUserByName (on page 178)

Finds a user in the Skybox database by name and returns the user’s information

getCollectorsFileStoreSpace (on page 178)

Returns information about the available space on each file store of each Skybox Collector, where a file store is a disk in Windows, and a partition in Unix.

getCollectorsUptime (on page 179)

Returns information about the uptime of each Skybox Collector.

getCSVReport (on page 179)

Returns the specified CSV or ZIP file.

getEvents (on page 179)

Retrieves a list of events from Skybox

getModelLockStatuses (on page 181)

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

getRunningTaskNames (on page 181)

Returns an array of names of currently running tasks

getRunningTasksInfo (on page 181)

Administration API

Chapter 8 Administration API


Method Description

getServerVersion (on page 182)

Returns the version of the Skybox Server.

launchTaskOrSequence (on page 182)

Launches a Skybox task

listCSVReports (on page 182)

ping Pings the Skybox server


Tests communication with the web service.

exportOptimizationAndCleanupCSVByTask method

Description The exportOptimizationAndCleanupCSVByTask method runs a CSV – Optimization & Cleanup Export task and returns the full path name of the file output by the task.

The method 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 the full path of the CSV file that was created by the task.

findAllUsers method

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



Syntax users = findAllUsers ()

Parameters The findAllUsers method has no parameters.

Result The method returns a list of data structures of type User (see page 320).

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

Result The method returns a data structure of type User (see page 320).

getCollectorsFileStoreSpace method

Description The getCollectorsFileStoreSpace method returns information about the available space on each file store of each Skybox Collector, where a file store is a disk in Windows, and a partition in Unix.

Syntax collectorFileStores = getCollectorsFileStoreSpace ()

Parameters The getCollectorsFileStoreSpace method has no parameters.

Result The method returns a list of data structures of type CollectorFileStoreInfo (on page 277).



getCollectorsUptime method

Description The getCollectorsUptime method returns information about the uptime of each Skybox Collector.

Syntax uptimeInfo = getCollectorsUptime ()

Parameters The getCollectorsUptime method has no parameters.

Result The method returns a list of data structures of type CollectorUptimeInfo (on page 278).

getCSVReport method

Description The getCSVReport method returns the specified CSV or ZIP file. The file must be located in the <Skybox_Home>\data\csv directory on the Server.

For security purposes, only Admin users can retrieve reports. If a non-Admin user tries to use this method, the method fails.

Syntax file = getCSVReport (fileName)

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


fileName String The name of the CSV report to return.

Result The method returns the requested file as a csvContent data structure (on page 279).

Note: The output of this method is the content of the file after encoding in Base64. Decode the string to obtain the original file content.

getEvents method

Description The getEvents method enables integration of Skybox with external ticketing systems and Security Operation Center (SOC) systems, providing data to any external program that can parse and process Skybox event records.

The getEvents method retrieves events created by the Skybox Server.



› Currently, there are no filtering mechanisms available; all stored events (starting at 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 180).

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

Result The method returns a list of data structures of type Event (see page 283).

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 uses, 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 that is required by Skybox.

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

Syntax getModelLockStatuses ()

Parameters The getModelLockStatuses method has no parameters.

Result The method returns an array of entities of type ModelLockStatus (see page 302).

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.

Result The method returns an array (list) of String objects. If no tasks are running, the array is empty.

getRunningTasksInfo method

Description The getRunningTasksInfo method returns information about the Skybox tasks that are currently running.

Syntax tasksInfo = getRunningTasksInfo ()

Parameters The getRunningTasksInfo method has no parameters.



Result The method returns a list of data structures of type TaskWsdl (see page 317).

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.

listCSVReports method

Description The listCSVReports method lists the CSV reports that meet the criteria of the filter.

Syntax reports = listCSVReports (reportFilter)

Parameters




reportFilter csvReportFilter (on page 279)

Result The method returns a list of data structures of type csvReportInfo (on page 279).

testService method

Description The testService method tests communication with the service.

Syntax result = testService (anyValue)

Parameters


anyValue Integer

Result The method returns the same value that it was sent.

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 9

This chapter describes the Firewall Changes API, which retrieves changes to firewall access rules and objects, including functions for change reconciliation.

The Firewall Changes API enables you to get a list of changes for firewalls over time. You can get a list of change records by firewall or firewall group and date ranges. For each change, you can get the details of the change (before and after). You can correlate the changes with change requests to verify that the changes were not made arbitrarily.

In this chapter

Firewall Changes API methods ............................................. 184

Using the Firewall Changes API ............................................ 189

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

Method Description

countFirewallChanges (on page 185)

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

findChangeReconciliationInfo (on page 185)

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

findFirewallChanges (on page 186)

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

getAccessRulesHistory (on page 186)

Retrieves a list of changes to an access rule.

getFirewallChangeDetails (on page 187)

Returns all data related to the specified change record.

setChangeReconciliationInfo (on page 187)

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

Adds a new comment to the specified firewall change record.

Firewall Changes API

Chapter 9 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 186), 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 296)

The type of changes to search for.

Result The method returns an integer representing the number of firewall changes that match the search criteria.

findChangeReconciliationInfo method

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

Syntax changeReconciliationDetails = findChangeReconciliationInfo (firewallChangeId)

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


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

Result The method returns a data structure of type FirewallChangeReconciliationDetails (see page 296) for the specified change record.



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 185) 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 296)

The type of changes to search for.

Result The method returns an array of data structures of type FirewallChange (see page 294).

getAccessRulesHistory method

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

Run getAccessRules (see page 211) 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 firewall’s ACL.

filter ACLRuleHistoryFilter (see page 267)

The time frame for returning access rule history records.

subRange SubRange (see page 317)

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



Result The method returns an array of data structures of type FirewallChange (see page 294).

getFirewallChangeDetails method

Description The getFirewallChangeDetails method returns all data related to the specified change record. It is called after findFirewallChanges (see page 186), 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.



Result The method returns a data structure of type FirewallChangeDetails (see page 295).

setChangeReconciliationInfo method

Description The setChangeReconciliationInfo method sets the change reconciliation information for the specified change record (including IDs of matched tickets and IDs of matched change requests). The operation overwrites the current list of connected ticket IDs and change request IDs with the lists in the ticketIds and accessRequestIds fields.

Syntax setChangeReconciliationInfo (firewallChangeId, status, comment, ticketIds, accessRequestIds)

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


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




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

accessRequestIds Array of Integer A list of change requests IDs to connect to the change record. Note: For a specific change request, use this field only; do not add the ticket ID of the change request to the list of tickets IDs.

Result The method updates the change reconciliation information for the specified firewall change record.

updateFirewallChangeComment method

Description The updateFirewallChangeComment method adds a 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 207) (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 185) 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 186) 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 187) (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 188) 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 specific change record. You want to check that this change was made according to a specific request and fulfills the requirements of that request.

1 Use findAccessRequests (on page 231) (from the Tickets API) to display all the change requests for the firewall created during the relevant period (typically 1 to 2 weeks before the change was implemented).

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

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


Chapter 10

This chapter describes the Network API, which provides access analysis and Access Policy analysis. Use the API in conjunction with the change assurance process.

The Network API enables you to utilize, from external applications, Skybox’s ability to analyze policy compliance and access.

The API supports the process of change assurance, starting with network change requests, usually submitted by users. These requests must be validated to make sure that they comply with your organization’s policy and then passed to firewall administrators for deployment.

In this chapter

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

Network API methods ......................................................... 192

Using the Network API ........................................................ 217

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



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

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 permit or deny the connection.

checkAccessV1 (on page 196)

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 permit or deny the connection. The method returns the 1st 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 198)

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

checkRuleComplia Checks whether a change request (source-destination-

Chapter 10 Network API


Method Description nce (on page 202) port) complies with your organization’s Rule Policies.

countAssetsByIps (on page 199)

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

countAssetsByNames (on page 199)

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

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

createFirewallException (on page 201)

Creates a firewall exception in Skybox.

createRulePolicyException (on page 201)

Creates a Rule Policy exception in Skybox.

deleteFirewallException (on page 201)

Deletes a firewall exception from Skybox.

deleteRulePolicyException (on page 202)

Deletes a Rule Policy exception from Skybox.

doCheckRuleCompliance (on page 202)


findAccessRules (on page 203)

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

findAssetsByIps (on page 206)

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

findAssetsByNames (on page 206)

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

findFirewallElementFAFolderPath (on page 204)

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

findFirewallObjectByName (on page 208)

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

findFirewalls (on page 203)

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

Returns a list of the firewalls stored under the specified folder in the All Firewalls tree.

findFirewallsByName (on page 207)

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



Method Description

findFirewallsByObjectName (on page 207)

Returns a list of the firewalls (in the All Firewalls tree) that have access rules that use the specified object.

findNetworkElementZone (on page 205)

Returns the zones of the specified networks.

findNetworkEntitiesBySourceAndDestination (on page 208)

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

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

findNetworksForIPRange (on page 209)

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

findObjectAffectedAccessRules (on page 209)

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

getAccessRules (on page 211)

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

getAccessRuleAttributes (on page 210)

Returns the business attributes of the specified access rule.

getHostAttributes (on page 211)

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

getZoneFromNetwork (on page 214)

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

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

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

getNetInterfacesByAssetId (on page 212)

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

getNetInterfacesByNetworkId (on page 213)

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

isBackwardRouteExist (on page 214)

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

modifyFirewallException (on page 215)

Modifies a firewall exception in Skybox.



Method Description

modifyRulePolicyException (on page 215)

Modifies a Rule Policy exception in Skybox.



updateAccessRuleAttributes (on page 216)

Updates the business attributes of 1 or more access rules.

updateFwAccessRuleAttributes (on page 216)

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

updateHostAttributes (on page 216)

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 permit 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 select 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 262)

Result The method returns a data structure of type CheckAccessResult (see page 276), which includes a list of accessible IP addresses (source, destination, ports, and authentication), a list of inaccessible IP addresses, and the 1st traceroute describing the path between the source and the destination.

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 permit 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 1st 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


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

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

Result The method returns a data structure of type CheckAccessResult (see page 276), which includes a list of accessible IP addresses (source, destination, ports, and authentication), a list of inaccessible IP addresses, and the 1st traceroute describing the path between the source and the destination.

checkAccessCompliance method

Description The checkAccessCompliance method checks whether a change request (source-destination-port) complies with your 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 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 214)

• destinationZone = getZoneFromNetwork (destinationAddress) (see page 214)

• checkAccessCompliance (sourceAddress, sourceZone, destinationAddress, destinationZone, ports)

› In a firewall context:

• fw = findFirewalls () (see page 203)

• sourceZone = getZoneFromFW (fw, sourceAddress) (see page 213)

• destinationZone = getZoneFromFW (fw, destinationAddress) (see page 213)

• 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 275)

Result The method returns a data structure of type CheckAccessComplianceResponse (see page 276), which includes the compliance status of the request and a list of violations.

countAssetsByIps method

Description The countAssetsByIps method counts the number of assets that match any of the specified IP address ranges. The output is used for page calculations. The method works in conjunction with findAssetsByIps (see page 206), 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 301)

Search the assets in the model to see if they match any of the IP address ranges in the filter. All interfaces of each asset are searched for a match, not just the primary address.

Result The method returns an integer representing the number of assets that match the IP address filter.

countAssetsByNames method

Description The countAssetsByNames method counts the number of assets that match any of the specified full or partial name strings. The output is used for page calculations. The method works in conjunction with findAssetsByNames (see page 206), 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.

Result The method returns an integer representing the number of assets that match the name filter.

countObjectAffectedAccessRules method

Description The countObjectAffectedAccessRules method counts the number of access rules in the specified rule chains of the firewall that use the specified firewall object. The output is used for page calculations.

The method works in conjunction with findObjectAffectedAccessRules (see page 209), 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. Possible values: • 0: Search all chains • 1: Search only primary chain • 2: Search by chain name

chainNames String A list of chain names in which to search for the object. Relevant only if chainFilterMode=2.

Result The method returns an integer representing the number of access rules in the firewall that use the object.



createFirewallException method

Description The createFirewallException method takes the information for 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 297)

The ID field in the firewall exception data is ignored.

Result The method returns a firewall exception (see page 297).

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

The ID field in the exception data is ignored.

Result The method returns A Rule Policy exception (see page 315).

deleteFirewallException method

Description The deleteFirewallException method deletes a firewall exception from Skybox.

Syntax deleteFirewallException (firewallException)



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



Result The method deletes the specified firewall exception in Skybox.

deleteRulePolicyException method

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

Syntax deleteRulePolicyException (policyException)

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



Result The method deletes the specified Rule Policy exception in Skybox.

doCheckRuleCompliance method

Description The doCheckRuleCompliance method checks whether a change request (source-destination-port) complies with your organization’s Rule Policies.


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

Result The method returns a data structure of type CheckRuleComplianceResponse (see page 277), which includes the compliance status of the request and a list of violations.

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

Result The method returns an array of AccessRuleElement (see page 264).

findFirewalls method

Description The findFirewalls method finds firewalls that are probably relevant for a request (and filters between a source and a destination).

The method looks for firewalls in the All Firewalls tree that contain an interface with the source IP address range and a different interface with the destination IP address range.

Syntax list = findFirewalls (sourceIpRange, destinationIpRange)



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


sourceIpRange Address element

destinationIpRange

Address Element

Result The method returns a list of firewalls (see page 296).

findFirewallsByLocation method

Description The findFirewallsByLocation method returns a list of the firewalls stored under the specified folder in the Firewall Assurance tree.

Syntax list = findFirewallsByLocation (locationName)

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


locationName String The name of a firewall folder in the Firewall Assurance tree. Null signifies the root folder.

Result The method returns a list of firewalls.

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



Result The method returns a data structure of type FindFirewallElementsFAFolderPathResult (see page 291), 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 306) 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 195) and checkAccessCompliance (see page 198) 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

Result The method returns a list of data structures of type NetworkElement (see page 306) 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 198).

Syntax list = findNetworkElementZone (networkElements)

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


networkElements NetworkElement (see page 306)



Result The method returns a data structure of type FindNetworkElementsZoneResult (see page 292), 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 199) 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 301)

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.

Result The method returns an array of assets (see page 271) sorted by ID.

findAssetsByNames method

Description The findAssetsByNames method returns an array containing all the assets that match any of the specified full or partial name strings.

We recommend that you use countAssetsByNames (see page 199) 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.

Result The method returns an array of assets (see page 271) sorted by ID.

findFirewallsByName method

Description The findFirewallsByName method returns a list of firewalls in the All Firewalls tree whose name includes the specified string.

Syntax list = findFirewallsByName (firewallName)

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


firewallName String If the search string is empty, all firewalls are returned.

Result The method returns a list of firewalls.

findFirewallsByObjectName method

Description The findFirewallsByObjectName method checks 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 200) and findObjectAffectedAccessRules (see page 209).

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.

Result The method returns a data structure of type FirewallFindByObjectResult (see page 298), 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 detailed information about the specified object.

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

The IP address range to check for the source.

destinationIpRangeElem

IPRangeElement (see page 301)

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

findNetworksForIPRange method

Description The findNetworksForIPRange method finds network elements (Skybox network entities) (see page 306) 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 195) and checkAccessCompliance (see page 198) when working with a network model (not individual firewalls).

Syntax list = findNetworksForIPRange (ipRange)

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


ipRange Address Element

Result The method returns a list of data structures of type IPAndNetworksPair (see page 301) 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 200) 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.



Result The method returns a list of data structures of type AccessRuleElement (see page 264).

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

Result The method returns a data structure of type ruleAttributes (see page 314), 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 195), to show the actual rules that

permitted or denied the access › In conjunction with getAccessRulesHistory (see page 186), 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 203) 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

Result The method returns a list of data structures of type AccessRuleElement (see page 264).

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

Result The method returns a data structure of type hostAttributes (on page 300), 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

Result The method returns a data structure of type FindNetInterfaceResult (see page 291), 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

Result The method returns an array of network interfaces (see page 305).



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

Result The method returns an array of network interfaces (see page 305).

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 198), 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 203) to get this entity.

ipRange Address element



Result The method returns the zones in the model that matches the address element of the firewall. The list is empty if the address element is not part of any existing zone in the specified firewall.

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 198), 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 306)

Only the ID field of the NetworkElement is mandatory. Use findNetworks (on page 205) to get this entity.

Result The method returns 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.

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




destinationEntity IPAndNetworksPair (see page 301)

Result The method returns a Boolean specifying whether any backward routes exist.

modifyFirewallException method

Description The modifyFirewallException method takes a firewall exception (with the original ID) on which 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.



Result The method returns an updated firewall exception (see page 297).

modifyRulePolicyException method

Description The modifyFirewallException method takes a firewall exception (with the original ID) on which 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.



Result The method returns an updated Rule Policy exception (see page 315).



updateAccessRuleAttributes method

Description The updateAccessRuleAttributes method updates the business attributes of 1 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 314)

Result The method returns an entity of type AccessRulesResponse (on page 266).

updateFwAccessRuleAttributes method

Description The updateFwAccessRuleAttributes method updates the business attributes of 1 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 300)

Result The method returns an entity of type AccessRulesByFwResponse (on page 266).

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

Result The method returns an entity of type HostsResponse (on page 301).

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 Provide a source-destination-port combination in the ticket form (source: your computer; destination: the application to which you want access; port: the service over which you need the access) and click Check Access.

3 The external ticketing system calls the Skybox checkAccess method (see page 195).

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 provided, it returns an error.

5 Do either 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 either 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 226), 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 205) to find the network in the model that contains the source IP address.

2 Use findNetworks (on page 205) to find the network in the model that contains the destination IP address.

3 Create an AccessQueryElement object (see page 262) using the source and destination IP addresses, and network elements found on the previous step.

4 Call checkAccess (see page 195) 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 203) to find the firewall that controls traffic between the specified source and destination IP addresses.

2 Create an AccessQueryElement object (see page 262) using the source and destination IP addresses, and the firewall element found in the previous step

3 Call checkAccess (see page 195) 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 214) (twice) to find the zone names

corresponding to the source and destination IP addresses.

2 (Optional) Use findFirewalls (on page 203) to find firewalls that control traffic between the specified source and destination IP addresses.

3 Create a CheckAccessComplianceRequest (see page 275) object using sourceZone, destinationZone, ports and (optionally) firewall elements.

4 Call checkAccessCompliance (see page 198) and analyze its results (list of violated Access Checks).


Chapter 11

This chapter describes the Tickets API, which retrieves and updates Skybox tickets.

The Tickets API supports 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 191) to check connectivity and policy compliance of change requests.

• The applications can send tickets to Skybox, enabling you to use the Skybox GUI to analyze the requests.

• You can create and manage firewall change tickets (known in Skybox as access change tickets) using the Tickets API.

In this chapter

Tickets API methods .......................................................... 220

Using the Tickets API ......................................................... 247

TICKETS API METHODS The Tickets web service enables you to update tickets.

Note: The API enables you to change all the fields of Access Change Tickets. For other ticket types, it enables you to change the general fields only (for example, owner, status, priority, and due date).

The methods in the Tickets web service are described in the following table.

Method Description

addAttachmentFile (on page 223)

Creates an attachment to a ticket in Skybox.

addDerivedChangeRequests (on page 224)

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

addOriginalChangeRequests (on page

Adds original change requests to a ticket. It then calculates the derived change requests, checks whether

Tickets API

Chapter 11 Tickets API


Method Description 224) a change is required, and checks for policy compliance

violations and potential vulnerabilities.

analyzeAccessChangeTicket (on page 225)

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

countAccessChangeTickets (on page 226)

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

createAccessChangeTicket


createChangeManagerTicket (on page 226)

Creates an Access Change ticket with a workflow and phases.

createRecertifyTicket (on page 227)

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

createTicketAccessRequestsForObjectChange (on page 227)

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

deleteAccessChangeTicket (on page 228)

Deletes the specified Access Change ticket in Skybox.

deleteChangeRequests (on page 229)

Deletes change requests from a ticket.

expandFirewallsForAccessChangeTicket (on page 229)

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.

findAccessChangeTickets (on page 231)

Retrieves all Access Change tickets that match the search criteria.

findAccessRequests (on page 231)

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

findConfigurationItems (on page 232)

Retrieves the configuration items that are defined in the system

getAccessChangeTicket (on page 233)

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

getAccessRequests (on page 233)

Retrieves change requests according to their ID numbers.

getAnalysisTree (on page 234)

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

getAttachmentFile (on page 234)

Retrieves the specified attachment from Skybox.

getAttachmentList (on page 235)

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



Method Description

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

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

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

getPotentialVulnerabilities (on page 238)

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

getTicketAccessRequests (on page 239)

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

getTicketEvents (on page 240)

Retrieves the history of a ticket.

getTicketFields (on page 240)

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

getTicketPhases (on page 241)

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

getTicketTypePhasesByTicketType (on page 241)

Retrieves the list of phases for the specific ticket type.

getTicketWorkflows (on page 242)

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

getVerificationDetails (on page 242)

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

Deletes an attachment from a ticket in Skybox.

setRecertificationStatus (on page 243)

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

Sets the list of change requests to the specified ticket.

setTicketFields (on page 245)

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

setTicketPhases (on page 246)

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



updateAccessChangeTicket (on page 246)

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

addAttachmentFile method

Description The addAttachmentFile method creates an attachment to the specified ticket in Skybox, 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



Result The method returns the ID of the newly created attachment.

addDerivedChangeRequests method

Description The addDerivedChangeRequests method adds a derived change request to a ticket if the original change request is of type Access Update.

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

Array of firewalls for which to add derived change requests

Result The method returns an array of derived change requests (see page 273) for the specified firewalls.

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

Any type of the change request extensions; not abstract change requests.

Result The method returns an array of change requests (see page 273).

analyzeAccessChangeTicket method

Description The analyzeAccessChangeTicket method analyzes access and Access Policy compliance for change requests of the specified ticket.

Syntax ticket = analyzeAccessChangeTicket (ticketId, accessRequests, Mode)

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


ticketId Integer The unique ID of the ticket to analyze

accessRequests Array of Integer A list of specific change request IDs in the ticket to analyze. An empty list means that all change requests are analyzed. Note: To retrieve a list of the change requests in a ticket, use getTicketAccessRequests (on page 239).

Mode Integer The type of analysis: • 0: Access analysis only • 1: Access Policy compliance

analysis only • 2: Both

Result The method returns a data structure of type AccessChangeTicket (see page 261), with updated change requests.



countAccessChangeTickets method

Description The countAccessChangeTickets method counts the number of tickets that match the specified filter (owner, phase, status, ID, created by, or modified by parameters; or free text search). The output is used for page calculations.

The method works in conjunction with findAccessChangeTickets (see page 231), 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 319)

Mandatory


Mandatory

Result The method returns an integer representing the number of Access Change tickets that match the search criteria.

createChangeManagerTicket method

Description The createChangeManagerTicket method creates an Access Change ticket with a workflow and phases.

Limitations:

› If the user creating the ticket does not have permission to create tickets in the selected workflow, no ticket is created.

› If you do not provide a workflow, the ticket is created in the user’s default workflow. If no default workflow was defined for the user, no ticket is created.

You can retrieve an existing Access Change ticket using getAccessChangeTicket (on page 233) and update it using updateAccessChangeTicket (on page 246).

Syntax ticket = createChangeManagerTicket (accessChangeTicket, phases, workflowId)

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




accessChangeTicket

AccessChangeTicket (see page 261)

Mandatory

phases Array of Phase (see page 308)

Default phases are created (according to the workflow) if the list is empty.

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 242).

Result The method returns a data structure of type AccessChangeTicket (see page 261).

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

workflowId Integer Workflow IDs can be retrieved using getTicketWorkflows (on page 242).

Result The method returns an entity named RecertifyTicketCreationResult (see page 311), which contains a list of new ticket IDs and a list of the access rules that are not included in these tickets.

createTicketAccessRequestsForObjectChange method

Description The createTicketAccessRequestsForObjectChange method adds change requests to an existing ticket. The method finds the access rules in which the specified object occurs and creates a change 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 change 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

addressChange Array of String The IP address to be added to or deleted from the object. Relevant only if the object is an IP object.

portChange String The service to be added to or deleted from the object. Relevant only if the object is a Service object.

maxAccessRequestsToCreate

Integer Limits the number of change requests that are created.



Result The method creates change requests on the specified ticket.

deleteAccessChangeTicket method

Description The deleteAccessChangeTicket method deletes the specified Access Change ticket in Skybox.

Syntax deleteAccessChangeTicket (ticketId)



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



Result The method deletes the specified ticket in Skybox and writes the deletion in the activity log. (For additional information, see the Activity log section in the Skybox Installation and Administration Guide.)

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

Result The method deletes the specified change requests from the ticket.

expandFirewallsForAccessChangeTicket method

Description The expandFirewallsForAccessChangeTicket method finds all the firewalls for the change requests (sets of source, destination, and port) in a 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 203) for each source-destination-port combination and then creates 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

NetworkC NetworkD 21

After calling this method, the expanded ticket includes the change requests listed in the following table.

Source Destination Ports Firewall

Source Zone

Destination Zone

NetworkA (int_2)

NetworkB (int_3)

80 main_FW

External DMZ

NetworkA (int_54)

NetworkB (int_55)

80 prod FW

External Internal

NetworkC (int_4)

NetworkD (int_7)

21 vlab-cisco

External DMZ

NetworkC (int_1)

NetworkD (int_2)

21 dev FW External Partner

NetworkC (int_49)

NetworkD (int_53)

21 prod FW

External Internal

Syntax ticket = expandFirewallsForAccessChangeTicket (ticketId, accessRequestIds, Recalculate)

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



accessRequestIds Array of Integer A list of specific change request IDs. If the list is empty, all change requests are expanded.

Recalculate Boolean Specifies whether to expand the selected change requests.

Result The method returns a data structure of type AccessChangeTicket (see page 261), with updated change requests that include firewalls, network interfaces, and zones for each change request.



findAccessChangeTickets method

Description The findAccessChangeTickets method returns an array containing all the Access Change tickets that match the search criteria.

We recommend that you use countAccessChangeTickets (on page 226) 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 319)

Result The method returns an array of data structures of type AccessChangeTicket (see page 261).

findAccessRequests method

Description The findAccessRequests method retrieves all change requests for the specified firewall created during the specified time interval. The change requests might not all be from the same ticket.

Use this method with setChangeReconciliationInfo (see page 187) (in the Firewall Changes API) to connect specific change requests to a change record.

Syntax accessRequests = findAccessRequests (hostId, dateRange)

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


hostId Integer The unique ID of the firewall for which to find change requests.

dateRange DateRange (see page 282)

The time interval for which to find change requests.



Result The method returns a list of data structures of type AccessRequest (see page 263) for the specified time interval and the specified asset.

findConfigurationItems method

Description The findConfigurationItems method retrieves the configuration items defined in the system. A filter can be used to limit the search.

Syntax list = findConfigurationItems (filter, subRange)

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


filter ConfigurationItemFilter (see page 278)


Limits the results to the specified subrange

Result The method returns a list of configuration items (see page 272).

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

Result The method returns a list of Access Change tickets (see page 261).



getAccessChangeTicket method

Description The getAccessChangeTicket method retrieves an Access Change ticket from Skybox.

Note: There are separate methods for retrieving attachments, phases, events, and change requests.

Use this method before calling updateAccessChangeTicket (see page 246) to make changes to a ticket.

Syntax ticket = getAccessChangeTicket (ticketId)

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



Result The method returns a data structure of type AccessChangeTicket (see page 261).

getAccessRequests method

Description The getAccessRequests method retrieves change requests (previously named access requests) according to their ID numbers.

The result of calling findChangeReconciliationInfo (see page 185) (in the Firewall Changes API) for a change record includes a list of the IDs of change requests that are relevant to the specified change record. Use this method to get the details of the change requests (that is, the source, destination, and service) so that you can display it in the application.

Syntax accessRequests = getAccessRequests (accessRequestIds)

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


accessRequestIds Array of Integer The IDs of the desired access requests

Result The method returns a list of the specified data structures of type AccessRequest (see page 263).



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

Result The method returns a list of analyses.

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 235) 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 243)).

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

Result The method returns the attachment file (javax.activation.DataHandler).



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 272). To retrieve a specific attachment, call getAttachmentFile (on page 234) with the ID of the desired attachment.

Syntax list = getAttachmentList (ticketId)

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



Result The method returns a list of data structures of type Attachment (see page 272) for the specified ticket.

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






Result The method returns an array of ChangeRequest (see page 273) (the derived requests).

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




Result The method returns an array of ChangeRequest (see page 273) (the derived requests).

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

Result The method returns the generated command output (as a string).

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



Result The method returns an array of original ChangeRequest (see page 273).

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



Result The method returns an array of original ChangeRequest (see page 273).

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

Result The method returns an array of ChangeRequestComplianceViolationElement (see page 274).

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

Result The method returns an array of ChangeRequestPotentialVulnerability (see page 275).

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.



Result The method returns a data structure of type BaseConfigurationItem (see page 272).

getTicketAccessRequests method

Description The getTicketAccessRequests method retrieves the list of change requests for the specified ticket (see page 263). The list is input to setTicketAccessRequests (see page 244), where you can add or update change requests for a ticket.

Syntax accessRequests = getTicketAccessRequests (ticketId)

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





Result The method returns an array of data structures of type AccessRequest (see page 263) for the specified ticket.

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.



Result The method returns an array of data structures of type TicketEvent (see page 318) for the specified ticket.

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



Result The method returns an array of data structures of type TicketField (see page 318).

getTicketPhases method

Description The getTicketPhases method retrieves the list of phases for the specified ticket (see page 308). The list is input to setTicketPhases (see page 246), 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.



Result The method returns an array of data structures of type Phase (see page 308) in the specified ticket.

getTicketTypePhasesByTicketType method

Description The getTicketTypePhasesByTicketType method retrieves the list of phases for the specified ticket type.

Note: It is not necessary to use this method if Skybox defines the phases for each ticket when creating the ticket (using createChangeManagerTicket (on page 226)), and then calls getTicketPhases (on page 241) (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



Result The method returns a list of data structures of type TicketTypePhase (see page 319) for the specified ticket type.

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.

Result The method returns an array of data structures of type TicketWorkflow (see page 320).

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.

Result The method returns an array of FirewallChange (see page 294); if the change request is not verified, the method returns null.

Note: For change requests other than Add Rule or Modify Rule, an exception is returned if the request type is not supported.



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

Result The method deletes the specified attachment from its ticket in Skybox.

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


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 of the selected application define the default owners for the ticket phases. If there are no approvers defined for the application or for a specific 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 change requests (previously named access requests) for the specified ticket.

The method overwrites the existing list; to add to the list of change requests or update any existing requests, retrieve the original list (using getTicketAccessRequests (on page 239)), 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 262), and leave the rest of the fields. You can define the firewall for each request or use expandFirewallsForAccessChangeTicket (on page 229).



Note: After you create change requests for a ticket (including the firewall for each request), you can call analyzeAccessChangeTicket (on page 225) 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 263)


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




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 241)), 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 308)

phaseOperation PhaseOperation (see page 309)


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 233)), make the changes, and then use this method to send the updated ticket back to Skybox.

Note: There are separate methods for updating attachments, phases, events, and change requests.

Syntax ticket = updateAccessChangeTicket (accessChangeTicket)

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




accessChangeTicket


Make any necessary changes.

Result The method returns an updated Access Change ticket (see page 261) data structure.

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 179) 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 245) 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 245) to set the External Ticket Status field in the Skybox ticket.

d. If you get a ticket update event from Skybox and the external ID is missing, it might mean that an update event in Skybox occurred before the external ID was set. If this happens, use getTicketFields (on page 240) 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 226) to pass the parameters for creation of a Skybox ticket describing the change request.

The information passed includes metadata including 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 246) 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 229). 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 225) to check connectivity and policy compliance; the result is in the relevant fields of each change request.

To work at the network level, find and complete the network elements for the source and destination, as explained in findNetworks (on page 205).


Chapter 12

This chapter describes the Vulnerabilities API, which retrieves Vulnerability Definitions, vulnerability occurrences, and threat alert tickets from Skybox.

The Vulnerabilities API enables you to retrieve Vulnerability Definitions, vulnerability occurrences, and threat alert tickets from Skybox. For each Vulnerability Definition, you can retrieve its details, instances, and tickets.

You can use the API to check 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 ................................................. 249

Using the Vulnerabilities API ................................................ 256

VULNERABILITIES API METHODS The methods in the Vulnerabilities web service are described in the following table.

Method Description

countVulnerabilities (on page 251)

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

countVulnerabilityTypes (on page 251)

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

countVulnerabilityTypeTickets (on page 252)

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

getVulnerabilities (on page 252)

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

getVulnerabilityTypeById






Vulnerabilities API



Method Description

getVulnerabilityTypeByIdV3 (on page 253)



2015 getVulnerabilityTypeByIdV4 (on page 253)



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

getVulnerabilityTypes






getVulnerabilityTypesV3 (on page 254)

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

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 254), but includes the reported date of each threat alert in the list.

getVulnerabilityTypeTickets (on page 256)

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



Chapter 12 Vulnerabilities API


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 252), which returns the actual vulnerability occurrences.

Syntax numVuls = countVulnerabilities (filter)



filter VulnerabilitySearchFilter (see page 322)

The set of vulnerability occurrences that are returned.

Result The method returns an integer representing the number of vulnerability occurrences that match the search criteria.

countVulnerabilityTypes method

Description The countVulnerabilityTypes method counts the number of Vulnerability Definitions that match the specified filter. The output is used for page calculations. The method works in conjunction with getVulnerabilityTypes, which returns the actual Vulnerability Definitions.

Syntax numVulTypes = countVulnerabilityTypes (filter)



filter VulnerabilityTypeSearchFilterV2 (see page 327)

The set of Vulnerability Definitions that are returned.

Result The method returns an integer representing the number of Vulnerability Definitions that match the search criteria.



countVulnerabilityTypeTickets method

Description The countVulnerabilityTypeTickets method counts the number of threat alert tickets for Vulnerability Definitions that have the IDs specified in the filter. The output is used for page calculations. The method works in conjunction with getVulnerabilityTypeTickets (see page 256), which returns the actual tickets.

Syntax numTickets = countVulnerabilityTypeTickets (filter)



filter VulnerabilityTypeIdFilter (see page 327)

Result The method returns an integer representing the number of tickets that match the search criteria.

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 251) 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 322)

The set of vulnerability occurrences that are returned.


The range of vulnerability occurrences to return from the list of Vulnerability Definitions that match the filter criteria.

Result The method returns an array of data structures of type Vulnerability (see page 321), sorted by ID.



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

Specifies the ID of the Vulnerability Definition to return.

cvssNullIndication Boolean If there is no valid value for any of the following CVSS Base Score properties, returns null instead of N\A: • Access Vector (AV) • Access Complexity (AC) • Authentication (Au) • Confidentiality Impact (C) • Integrity Impact (I) • Availability Impact (A)

Result The method returns the VulnerabilityTypeV3 threat alert (see page 323) that has the specified ID.

getVulnerabilityTypeByIdV4 method

Description The getVulnerabilityTypeByIdV4 method returns a threat alert that matches the specified ID. This method returns CVSS information in the appropriate version:


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

Syntax vulType = getVulnerabilityTypeByIdV4 (vulnerabilityTypeId, cvssNullIndication)





vulnerabilityTypeId

VulnerabilityTypeId (on page 326)

Specifies the ID of the Vulnerability Definition to return.

cvssNullIndication Boolean If there is no valid value for any of the following CVSS Base Score properties, returns null instead of N\A: • Access Vector (AV) • Access Complexity (AC) • Authentication (Au) • Confidentiality Impact (C) • Integrity Impact (I) • Availability Impact (A)

Result The method returns the VulnerabilityTypeV4 (on page 325) threat alert that has the specified ID.

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

Result The method returns an array of data structures of type VulnerabilityTypeV3 (see page 323), sorted by ID.

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 254), but includes the reported date of each threat alert in the list.

We recommend that you use countVulnerabilityTypes (on page 251) 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)

Result The method returns an array of data structures of type VulnerabilityTypeV4 (on page 325), sorted by ID.

getVulnerabilityTypeTickets method

Description The getVulnerabilityTypeTickets method returns an array containing all the threat alert tickets for Vulnerability Definitions that match the search filter (of catalog and IDs).

We recommend that you use countVulnerabilityTypeTickets (on page 252) to count the number of threat alert tickets for display purposes and then run getVulnerabilityTypeTickets.

Syntax tickets = getVulnerabilityTypeTickets (vulnerabilityTypeId)



vulnerabilityTypeId

VulnerabilityTypeIdFilter (see page 327)

Specifies the IDs of the Vulnerability Definitions that are returned.

Result The method returns an array of data structures of type VulnerabilityTypeTicket (see page 329) for Vulnerability Definitions with the specified IDs.

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 251) to find the number of Vulnerability

Definitions that match your filter criteria (for example, all Vulnerability Definitions that are new since last week with high and critical severity).

2 Use getVulnerabilityTypesV3 (on page 254) to retrieve the Vulnerability Definitions that match your filter criteria. Depending on the number of Vulnerability Definitions found at the previous step, you might need to retrieve the Vulnerability Definitions by chunks (using the subRange object).

3 Go over the list of Vulnerability Definitions and use their IDs as input to getVulnerabilityTypeTickets (on page 256) 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 251) 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 252) 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 251) to find the number of vulnerability

occurrences that match your filter criteria (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 252) to retrieve the vulnerability occurrences that match your filter criteria. Depending on the number of vulnerability occurrences found at the previous step, you might need to retrieve them by chunks (using the subRange object).

3 Use getVulnerabilityTypeByIdV3 (on page 253) to retrieve all data related to the Vulnerability Definitions of the retrieved vulnerability occurrences.


Chapter 13

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 that the client is using Apache CXF JAX-WS.

Note: For information about wsimport, see https://docs.oracle.com/javase/6/docs/technotes/tools/share/wsimport.html

HttpServiceParameters sp = new HttpServiceParameters(); sp.setUsername("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 13 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 14

This chapter defines the data structures used in the Skybox web services.

In this chapter

Data structures: A to C ....................................................... 261

Data structures: D to H ...................................................... 282

Data structures: I to R ....................................................... 301

Data structures: S to Z ....................................................... 315

DATA STRUCTURES: A TO C AccessChangeTicket data structure

The fields of the AccessChangeTicket data structure are listed in the following table.

Field Type Comments

id Integer Read-only

comment String

description String

creationTime Date Read-only; calculated automatically

lastModificationTime

Date Read-only

createdBy String Read-only

lastModifiedBy String Read-only

externalTicketId String

externalTicketStatus

String Possible values: • Pending • Open • Closed • Error • Rejected

status String Possible values: • New • InProgress • Resolved • Closed • Rejected • Ignored • Verified • Reopened

Data structures



Field Type Comments • 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 283)

customFields Array of CustomField (see page 279)

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

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

firewall Empty or Firewall Name or Firewall ID

Mandatory for firewall-context analysis; null for network-context analysis. Use findFirewalls (on page 203) to get this entity.

Chapter 14 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 306)

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

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

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

potentialVulnerabilities

Array of PotentialVulnerability (see page 310)

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

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

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 you provide only the port number, 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 282)

The time frame for which to search for access rule history records.

AddRuleChangeRequestV1 data structure The AddRuleChangeRequestV1 data structure is an extended version of the ChangeRequest data structure (see page 273) 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

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

Destination objects for the new rule.

expirationDate Date (Check Point firewalls only) Sets the expiration date for the rule.

firewall Asset (see page 271)

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.

isDestinationNegated

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

NATDestinationAddresses

Array of String Translated destination addresses for the new rule.

NATDestinationObjects


Translated destination objects for the new rule.

NATPortObjects Array of Translated port objects for the new



Field Type Comments FirewallObjectIdentification (see page 298)

rule.

NATPorts Array of String Translated ports for the new rule.

NATSourceAddresses

Array of String Translated source addresses for the new rule.

NATSourceObjects


Translated source objects for the new rule.

portObjects Array of FirewallObjectIdentification (see page 298)

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

Source objects for the new rule.

vpn String Describes the VPN (if a VPN exists), for the new rule.

AddRuleChangeRequestV1 data structure The AddRuleChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 273) 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 298)

Applications for the new rule.

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

Destination objects for the new rule.



Field Type Comments page 298)

expirationDate Date (Check Point firewalls only) Sets the expiration date for the rule.


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.


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


Array of String Translated destination addresses for the new rule.



Translated destination objects for the new rule.

NATPortObjects Array of FirewallObjectIdentification (see page 298)

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.

NATSourceObjects


Translated source objects for the new rule.


Port objects for the new rule.

ports String Ports for the new rule.



ruleGroup String

ruleType String

sourceAddresses Array of String Source addresses for the new rule.



Field Type Comments


Source objects for the new rule.

useApplicationDefaultPorts

Boolean Specifies whether to use the default ports of the applications as the ports for the change request.

userUsage String

users String

vpn String Describes the VPN (if a VPN exists), for the new rule.

Analysis data structure The fields of the Analysis data structure are listed in the following table.

Field Type Comments

id Integer

name String

type Possible values: • Business Assets • Hosts • Vulnerabilities • Threat Origins • Locations • Regulation Compliance • Tickets • Networks • Access • Worms • Network Interfaces

path String The full path from the root directory to this analysis.

ApplicationConfigurationItem data structure The ApplicationConfigurationItem data structure is an extended version of the BaseConfigurationItem data structure (see page 272) 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 272) used for groups of ApplicationConfigurationItem (see page 270). 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 306)

All the network interfaces of the asset

status Status of the asset: • Up • Down • Not Found • 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



Field Type Comments

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 270) › ApplicationGroupConfigurationItem (on page 271) › ServiceConfigurationItem (on page 315) › ServiceGroupConfigurationItem (on page 315)



BlockAccessChangeRequest data structure The BlockAccessChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 273) 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.

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



Field Type Comments

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:

› AddRuleChangeRequestV1 (on page 267) › AddRuleChangeRequestV2 (on page 268) › BlockAccessChangeRequest (on page 273) › DeactivateRuleChangeRequest (on page 282) › ModifyObjectChangeRequest (on page 302) › ModifyRulesChangeRequestV1 (on page 302) › ModifyRulesChangeRequestV2 (on page 303) › RequireAccessChangeRequest (on page 311)

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



Field Type Comments

destinationNetworks

Array of NetworkElement (see page 306)

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

sourceNetworks Array of NetworkElement (see page 306)

ChangeRequestPotentialVulnerability data structure The fields of the ChangeRequestPotentialVulnerability data structure are listed in the following table.

Field Type Comments

catalogId String

cveId String

fixCount Integer

hostNames String

new Boolean

reportedDate Date

serviceName String

servicePorts String

severityLevel String

severityScore Float

title String

vulDefId Integer

CheckAccessComplianceRequest data structure The fields of the CheckAccessComplianceRequest data structure are listed in the following table.

Field Type Comments

Source Address (Optional) Used to find Access Checks that are limited by the source field.

Source Zone Zone name Use getZoneFromNetwork (on page



Field Type Comments 214) or getZoneFromFW (on page 213) 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 214) or getZoneFromFW (on page 213) 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 203) 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 278)

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

List of accessible IP addresses (source, destination, ports, and authentication).

inaccessible Array of AccessRuleElement (see page 264)

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



Field Type Comments might be multiple traceroutes. The result field contains only the 1st set. To obtain more traceroutes, call the method again with the relevant accessible or inaccessible row as the query.

status ReturnStatus (see page 313)

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

CollectorFileStoreInfo data structure The fields of the CollectorFileStoreInfo data structure are listed in the following table.



Field Type Comments

fileStores Array of FileStoreSpaceInfo (on page 291)

ipAddress String

name String

status Integer Possible values are: • 0: success • -1: failure

CollectorUptimeInfo data structure The fields of the CollectorUptimeInfo data structure are listed in the following table.

Field Type Comments

ipAddress String

name String

status Integer Possible values are: • 0: success • -1: failure (for example, if

uptime=0) uptime Integer Machine uptime in seconds

ComplianceViolationElement data structure The fields of the ComplianceViolationElement data structure are listed in the following table.

Field Type Comments

aprName String The name of the Access Check in Skybox

aprPath String The path of the Access Check in Skybox

importance Integer Possible values: • 0=Very Low • 1=Low • 2=Medium • 3=High • 4=Critical

portsViolating List of String

ConfigurationItemFilter data structure The fields of the ConfigurationItemFilter data structure are listed in the following table.

Field Type Comments

ancestorOf Array of Integer

childrenOf Array of Integer



Field Type Comments

configurationItemTypes

Array of String

freeTextFilter String

ids Array of Integer

ignoreEmptyGroups

Boolean

isEnabled Boolean

nameFilter String

csvContent data structure The fields of the csvContent data structure are listed in the following table.

Field Type Comments

data base64Binary

csvReportFilter data structure The fields of the csvReportFilter data structure are listed in the following table.

Field Type Comments

recency Integer

reportName String

csvReportInfo data structure The fields of the csvReportInfo data structure are listed in the following table.

Field Type Comments

creationDate Date

fileName String

fileSize Long

CustomField data structure The fields of the CustomField data structure are listed in the following table.

Field Type Comments

id Integer

comment String

description String

creationTime Date


Date

createdBy String


name String



Field Type Comments

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

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



Field Type Comments

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

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



Field Type Comments

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: You must give values for both fields.

DeactivateRuleChangeRequest data structure The DeactivateRuleChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 273) 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 316)

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

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

Event types The supported event types for the Events API are listed in the following table.



Event type Event name Code

Ticket creation SBVAPI_EVENT_TYPE_TICKET_CREATION 1

Ticket update SBVAPI_EVENT_TYPE_TICKET_UPDATE 2

Ticket deletion SBVAPI_EVENT_TYPE_TICKET_DELETE 3

Security Metric notification

SBVAPI_EVENT_TYPE_KPI_NOTIFICATION 4

Operational (for example, Server start and Server stop)

SBVAPI_EVENT_TYPE_OPERATIONAL 5

Task end SBVAPI_EVENT_TYPE_TASK 6

Firewall compliance violation notification

SBVAPI_EVENT_TYPE_APR_NOTIFICATION 7

Event parameter enumerations In the Events API, each event record is composed of different parameters according to the event type. Each parameter has its own name and code number. Some parameters are relevant to multiple event types. For example, the ticket ID is used for ticket creation events, ticket update events, and ticket deletion events.

Ticket creation parameters The values that are used for ticket creation events (Event type code = 1) are listed in the following tables.

Enums for ticket creation parameters

Description Event name Code Possible values

Ticket ID SBVAPI_EVENT_PARAM_TICKET_ID

1 Integer

External ID SBVAPI_EVENT_PARAM_TICKET_EXTERNAL_ID

2 Text

Title SBVAPI_EVENT_PARAM_TITLE 3 Text

Owner name SBVAPI_EVENT_PARAM_OWNER 4 Text

The most recent comment

SBVAPI_EVENT_PARAM_COMMENT

5 Text

Ticket priority SBVAPI_EVENT_PARAM_PRIORITY

6 • Critical • High • Medium • Low • Very Low

Ticket status SBVAPI_EVENT_PARAM_STATUS

7 • Closed • Ignored • In Progress • New • Rejected • Resolved • Verified • Reopened • Demoted

Due date SBVAPI_EVENT_PARAM_DUE_D 8 Date (in the



Description Event name Code Possible values ATE 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


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



Description Event name Code Possible values 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



Description Event name Code Possible values • 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 from the Access Policy)

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_SOURCE

45 Text

The destination (taken from the Access Policy)

SBVAPI_EVENT_PARAM_APR_NOTIFICATION_DESTINATION

46 Text

ExtendedAccessRequest data structure The ExtendedAccessRequest data structure is an extended version of the AccessRequest data structure (see page 263).

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



Field Type Comments • SBV • Qualys • Microsoft • FoundScan • nCircle • Cisco PSIRT • Rapid7 • OVAL • Oracle • Adobe

Id String ID; external vulnerability database ID

FileStoreSpaceInfo data structure The fields of the FileStoreSpaceInfo data structure are listed in the following table.

Field Type Comments

name String

totalSize Long

unallocatedSize Long

FindFirewallElementsFAFolderPathResult data structure The fields of the FindFirewallElementsFAFolderPathResult data structure are listed in the following table.

Field Type Comments

faPaths List of String Element[i] of this list is the Firewall Assurance folder path found for fwElements[i].

fwElements List of FirewallElement (see page 296)

The firewall elements of the input.


FindNetInterfaceResult data structure The fields of the FindNetInterfaceResult data structure are listed in the following table.

Field Type Comments

Status ReturnStatus (see page 313)

netInterfaceElements

List of NetInterfaceElement (see page 306)



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

The network elements of the input.


zones List of String Element[i] of this list is the zone for networkElements[i].

FindNetworkEntitiesResult data structure The fields of the FindNetworkEntitiesResult data structure are listed in the following table.

Field Type Comments

networkEntitiesResultElementArray

NetworkEntitiesResultElement (see page 307)


FirewallAclSnapshotData data structure The fields of the FirewallAclSnapshotData data structure are listed in the following table.

Field Type Comments

aclId Integer

aclUserComment String

aclDescription String

aclCreationTime Date

aclLastModificationTime

Date

aclCreatedBy String

aclModifiedBy String

ruleOrder Long

actionType String Possible values: • Undefined • Allow • Deny • Translate • Ips

directionType String Possible values: • UNDEFINED • Inbound • Outbound



Field Type Comments • Both

vpnUnitUsageType String Possible values: • None • Specific • Any • RemoteAccess

sourceIpSpace IPSpace (see page 301)

targetIpSpace IPSpace (see page 301)

firewallServiceSpace FirewallServiceSpace (see page 299)

isImplied Boolean

isDisabled Boolean

isFiltering Boolean

isUnsupported Boolean

originalRuleText String

translatedSourceIpSpace

IPSpace (see page 301)

translatedTargetIpSpace


translatedFirewallService

String

chainNumber Integer

originalRuleName String

ruleType String Possible values: • Regular • AntiSpoofing • HideNat • DenyAny • Mip • PixNat

globalUniqueId String

isExcluded Boolean

isAuthenticalted Boolean

isLogEnabled Boolean

netInterfaces String

sourceNetInterfaces String

vpnUnits String

idpRuleGroups String

chainName String

preChangeId Integer



Field Type Comments

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



Field Type Comments

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 295) › FirewallChangeReconciliationDetails (see page 296)

FirewallChangeDetails data structure The FirewallChangeDetails data structure is an extended version of the FirewallChange data structure (see page 294).

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

The state of the firewall object before the change. Note: Relevant only for changes of type OBJECT.

rootPostObjectTreeNode

FirewallObjectTreeNode (see page 298)

The state of the firewall object after the change. Note: Relevant only for changes of type OBJECT.

preAclData FirewallAclSnapshotData (see page 292)

The state of the access rule before the change. Note: Relevant only for changes of type ACL.

postAclData FirewallAclSnapshotData (see page 292)

The state of the access rule after the change. Note: Relevant only for changes of type ACL.



Field Type Comments

affectedAclsData Array of FirewallAclSnapshotData (see page 292)

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

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

FirewallChangesSearchFilter data structure The fields of the FirewallChangesSearchFilter data structure are listed in the following table.

Field Type Comments

trackingPeriod DateRange (see page 282)

Include only changes created between the specified dates.

folderId Integer Include only changes from firewalls that are in the specified firewall folder.

firewallId Integer Include only changes from the specified firewall.

changeReconciliationStatusFilter

Comma-separated list of reconciliation statuses

Include only changes with the specified reconciliation statuses. Possible values: • PENDING • AUTHORIZED • UNAUTHORIZED • IGNORED

violationStatusFilter

Comma-separated list of violation statuses

Include only changes with the specified violation statuses. Possible values: • UNKNOWN • VIOLATING • POTENTIALLY • NOT_VIOLATING

FirewallElement data structure The fields of the FirewallElement data structure are listed in the following table.



Field Type Comments

id Integer

name String

path String

FirewallException data structure The fields of the FirewallException data structure are listed in the following table.

Field Type Comments

id Integer The ID of the 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

firewall FirewallElement (see page 296)

(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



Field Type Comments

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

The firewalls that match the specified object name.

objectNames List of String Element[i] of this list is the list of object names found for fwElements[i].

FirewallObjectIdentification data structure The fields of the FirewallObjectIdentification data structure are listed in the following table.

Field Type Comments

firewallId Integer The ID of the firewall.

firewallName String

firewallIP String

firewallFolder String

firewallManagementId

Integer

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 299) for a list of possible values



Field Type Comments

name String

isTemporary Boolean

Data String

subNodes Array of FirewallObjectTreeNode

FWObjectTypeEnum values Possible firewall object types:

• FW1Host • FW1Cluster • FW1Network • FW1Group • FW1Service • FW1ServiceGroup

• FW1VPNCommunity • FW1AddressRange

• FW1Module • FW1Domain

• PIXNetworkGroup • PIXServiceGroup • PIXProtocolGroup • PIXICMPTypeGroup • PIXHost • PIXNetwork • PIXProtocol • PIXPortObject • PIXServiceObject • NSAddress • NSService • NSZone • NSAddressGroup • NSServiceGroup • NSMultiIpRangeAddress • FortiGateIPAddress • FortiGateFQDNAddress • FortiGateRangeAddress • FortiGateAddressGroup • FortiGateService • FortiGateServiceGroup • FortiGateZone • FortiGateVipNatAddress • TempIP • TempService • FW1Extension • PIXExtension • NSExtension • FG_EXTENSION • JunosACLExtension • NSDomainAddress • JunosAddress • JunosAddressSet • JunosApplication • JunosApplicationSet • JunosZone

FirewallServiceSpace data structure The fields of the FirewallServiceSpace data structure are listed in the following table.

Field Type Comments

FirewallServices String

isNegated Boolean

originalText String

Folder data structure The fields of the Folder data structure are listed in the following table.

Field Type Comments

id Integer



Field Type Comments

name String

subfolders Array of Folder

analyses Array of Analysis (see page 270)

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

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

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

hostIds Array of Integer

HostsResponse data structure The fields of the HostsResponse data structure are listed in the following table.

Field Type Comments

hostIds Array of Integer


DATA STRUCTURES: I TO R IntRange data structure

The fields of the IntRange data structure are listed in the following table.

Field Type Comments

from Integer

to Integer

IPAndNetworksPair data structure The fields of the IPAndNetworksPair data structure are listed in the following table.

Field Type Comments

IPRange IPRangeElement (see page 301)

network NetworkElement (see page 306)

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 273) 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 298)

The objects to add to the object being modified.

addedPorts String The ports to add to the object being modified.

object FirewallObjectIdentification (see page 298)

The object to modify.

removedAddresses

Array of String The addresses to delete from the object being modified.

removedObjects Array of FirewallObjectIdentification (see page 298)

The objects to delete from the object being modified.

removedPorts String The ports to delete from the object being modified.

ModifyRulesChangeRequestV1 data structure The ModifyRulesChangeRequestV1 data structure is an extended version of the ChangeRequest data structure (see page 273) 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

accessRules Array of SlimAccessRule (see page 316)

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 • Destination • Service • Source NAT • Destination NAT • Service NAT

negationChangeType

String Specifies whether to negate the value of the field to be modified. Possible values: • NO_CHANGE • NEGATE • NOT_NEGATE

removedAddresses

Array of String


removedPorts String


submitOnAllClusterMembers

Boolean

ModifyRulesChangeRequestV2 data structure The ModifyRulesChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 273) 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

accessRules Array of SlimAccessRule



Field Type Comments (see page 316)

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 • Destination • Service • Source NAT • Destination NAT • Service NAT

negationChangeType

String Specifies whether to negate the value of the field to be modified. Possible values: • NO_CHANGE • NEGATE • NOT_NEGATE

removedAddresses

Array of String


removedPorts String


submitOnAllClusterMembers

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 Date

description String

id Integer

ipAddress String

isDefaultGateway Boolean


Date

layer2 Boolean

locked Boolean

lockedToNetwork Boolean

macAddress String

missingNeighbors String

modifiedBy String

name String

netMask String

networkId Integer

networkName String

networkZoneType String

primary Boolean

status String

type String Possible values: • NAT • ETHERNET • WLAN • TOKEN_RING • PPP • SLIP • VIRTUAL • OTHER • UNKNOWN • LOOPBACK • SERIAL



Field Type Comments • LOAD_BALANCER • TUNNEL • VPN • CONNECTING_CLOUD_INTERFACE

virtualRouter String

zoneName String

zoneType String

NetInterfaceElement data structure The fields of the NetInterfaceElement data structure are listed in the following table.

Field Type Comments

id Integer

name String

type String Possible values: • NAT • ETHERNET • WLAN • TOKEN_RING • PPP • SLIP • VIRTUAL • OTHER • UNKNOWN • LOOPBACK • SERIAL • LOAD_BALANCER • TUNNEL • VPN • CONNECTING_CLOUD_INTERFACE

ipAddress String

zoneType String

zoneName String

Description String

NetworkElement data structure The fields of the NetworkElement data structure are listed in the following table.

Field Type Comments

IPAddress String

id Integer

name String

netMask Integer

path String

type Integer 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 301)

destinationEntity IPAndNetworksPair (see page 301)

preNATSource Boolean Specifies whether the source entity represents a pre-NAT address.

postNATDestination

Boolean Specifies whether the destination entity represents a post-NAT address.



Field Type Comments

forwardingRoute Boolean Specifies whether a forward route is possible from the source entity to the destination entity.

backwardRoute Boolean Specifies whether a backward route is possible from the destination entity to the source entity. Null means that there was no examination.

NetworkEntityItem data structure The fields of the NetworkEntityItem data structure are listed in the following table.

Field Type Comments

id Integer The ID of the network entity

Name String The name of the network entity

Type String The type of the network entity Possible values: • Network • Location • Host • Network Group • Host Group • Business Asset • Business Group

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

lastModificationTi Date Read-only



Field Type Comments me

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

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 Ignored



Phase operation (type)

phaseId phaseOwner isReject

of the phase to this owner

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

RepositoryProduct data structure The fields of the RepositoryProduct data structure are listed in the following table.

Field Type Comments

disabled Boolean True if the repository product is disabled; otherwise false.

installedVersions String Comma-separated string of all installed versions of the product.

product String Name of the product.

vendor String Name of the vendor.

id Integer ID of the product.

productGroups String Names of the product groups to which the repository product belongs.

userComments String User comments.

RequireAccessChangeRequest data structure The RequireAccessChangeRequest data structure is an extended version of the ChangeRequest data structure (see page 273) 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.


Array of FirewallObjectIdentification (see

Translated destination objects.



Field Type Comments page 298)


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.


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.

RequireAccessChangeRequestV2 data structure The RequireAccessChangeRequestV2 data structure is an extended version of the ChangeRequest data structure (see page 273) 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 298)

Array of firewall applications to use. (For use with next-generation firewalls).


Array of String Array of addresses to use as the destination of the rule.

destinationObjects


Array of firewall objects to use as the destination of the rule.

expirationDate Date Sets the expiration date for the access rules.



Field Type Comments


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.


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

email String

nextReviewDate Date

owner String

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.

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 272) 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 272) used for groups of ServiceConfigurationItem (on page 315). 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 299)

globalUniqueId String

order Integer

originalRuleName String

originalRuleText String

primaryChain Boolean

sourceIPSpace IPSpace (see page 301)

targetIPSpace IPSpace (see page 301)

translatedFirewallServiceSpace

FirewallServiceSpace (see page 299)

translatedSourceIPSpace


translatedTargetIPSpace


Solution data structure The fields of the Solution data structure are listed in the following table.

Field Type Comments

ID Numeric The ID of the solution.

Name String The name of the solution.

Type String The type of the solution: • Other (General) • Config • Block • Patch • Remove • Upgrade • Workaround



Field Type Comments • Note • MitigateByIPS

Description String The description of the solution.

Product String The product name to which the solution applies or empty if it applies to all products.

Vendor String The vendor name of the product to which the solution applies or empty if it applies to all products.

Environment String The environment (that is, operating system) to which the solution applies or empty if it applies to all products.

EnvironmentVersion

String The environment version (that is, version of operating system) to which the solution applies or empty if it applies to all products

EnvironmentVendor

String The environment version (that is, version of operating system) to which the solution applies or empty if it applies to all products.

CustomSolution Boolean • True: A custom solution (user’s solution)

• False: Otherwise

Source data structure The fields of the Source data structure are listed in the following table.

Field Type Comments

id String The ID of the external source.

Severity String The severity of the external source.

Source String The name of the external source.

SubRange data structure The fields of the SubRange data structure are listed in the following table.

Field Type Comments

start Integer

size Integer

TaskWSDL data structure The fields of the TaskWSDL data structure are listed in the following table.

Field Type Comments

duration Long

launchedBy String

sequenceName String

startDate Date



Field Type Comments

taskType String

TicketEvent data structure The fields of the TicketEvent data structure are listed in the following table.

Field Type Comments

id Integer

user String

date String

modifiedField String

oldValue String

newValue String

TicketField data structure The fields of the TicketField data structure are listed in the following table.

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 • Verified • Reopened • Demoted

owner String Search tickets by owner

phaseName String Search tickets by current phase

freeTextFilter String Free text search in the following ticket fields: • Title • Comment • Owner • ID • Status • Priority • Vendor reference • Solutions • CVE catalog ID • Custom fields of type String

createdBy String User name

modifiedBy String User name

TicketTypePhase data structure The fields of the TicketTypePhase data structure are listed in the following table.

Field Type Comments


ticketType String Possible values: • VulnerabilityTicket • ApplicationTicket • VulnerabilityDefinitionTicket • AccessChangeTicket • PolicyViolationTicket • EOLTicket

order Integer

waitingForClosure Boolean



Field Type Comments

name String

defaultOwner String

TicketWorkflow data structure The fields of the TicketWorkflow data structure are listed in the following table.

Field Type Comments

id Integer The ID of the ticket workflow.

name String The name of the ticket workflow.

URLInfo data structure The fields of the URLInfo data structure are listed in the following table.

Field Type Comments

Source String Source of the URL (for example, CVE or SecurityFocus)

Title String Title of the URL

Info String

User data structure The fields of the User data structure are listed in the following table.

Field Type Comments

username String

email String

phone String

department String

baseRole String Possible values: • ADMIN • ADMIN_OPS • ADMIN_USERS • SECURE_ADMIN • ASSURE_ADMIN • User • SECURE_USER • ASSURE_USER • READONLY • SECURE_READONLY • ASSURE_READONLY • TICKET_HANDLER • TICKET_REQUESTOR • RECIPIENT

lastLogin Date

firstName String

lastName String

groups Array of String List of groups to which the user



Field Type Comments 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 326)

The ID and vulnerability database (according to how it was searched) of the Vulnerability Definition of the vulnerability occurrence

Title String The title of the Vulnerability Definition of the vulnerability occurrence

Severity String The severity of the Vulnerability Definition Possible values: • Info • Low • Medium • High • Critical • Unknown

CVE String The CVE of the Vulnerability Definition

hostId Integer The ID of the asset in Skybox

hostIp String The IP address of the asset

hostName String The name of the asset

ServiceName String The name of the service on which the vulnerability occurrence exists

ServicePorts String The ports of the service, comma-separated

NetworkNames String The names of the networks to which the asset belongs (comma-separated), or empty for unassigned assets

NetworkGroupNames

String The names of the network groups to which the network of the asset is attached, comma-separated

Exposure String Exposure of the vulnerability occurrence Possible values: • Direct • Indirect • Protected • Potential • Inaccessible • Excluded • Unknown



Field Type Comments

Risk String Possible values: • Very Low • Low • Medium • High • Critical

Status String Possible values: • Found • Ignored • Fixed

ScannerID String The ID of the scanner that was the source of the vulnerability occurrence

LastScanTime Long The 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 159) 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 301)

Search for vulnerability occurrences by severity score range.

ReportedDateRange

DateRange (see page 282)

Search for vulnerability occurrences by their reported date.

ScanTimeRange DateRange (see page 282)

Search for vulnerability occurrences by their scan time.

ModificationDateRange


Search for vulnerability occurrences by their modification date.

CVSSBaseScoreRange

DoubleRange (see page 283)

Search for vulnerability occurrences by their CVSS base score range.



Field Type Comments

CVSSTemporalScoreRange


Search for vulnerability occurrences by their CVSS temporal score range.

VulnerabilityTypeIdFilter

VulnerabilityTypeIdFilter (see page 327)

Search for vulnerability occurrences by range of their ID filters.

Scope Scope (see page 315)

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

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.



Field Type Comments

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

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

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

The related sources of the Vulnerability Definition.

products Array of Product (see page 310)

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

externalURLs Array of URLInfo (see page 320)

All related URLInfo objects.

history Array of ChangeLog (see page 273)

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

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

reportedDate Date The date on which the Vulnerability Definition was reported.

severityLevel String Possible values: • Info • Low • Medium • High • Critical

severityScore Float The severity score of the Vulnerability Definition.

cvssBase Float The CVSS base score, in 0.1 resolutions. Note: The user value is provided if it was updated by the user.

cvssTemporal Float The CVSS temporal score, in 0.1 resolutions. Note: The user value is provided if it was updated by the user.

vulnerabilityCount Integer Vulnerability occurrences instance count.

cvss cvssv1 (see page 281)

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

The related sources of the Vulnerability Definition.

products Array of Product (see page 310)

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

externalURLs Array of URLInfo (see page 320)

All related URLInfo objects.

history Array of ChangeLog (see page 273)

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.



Field Type Comments

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


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




Field Type Comments

SeverityLevels Array of String Search the Vulnerability Definitions by list of severity levels. Possible values: • Info • Low • Medium • High • Critical

SeverityScoreRange


Search for Vulnerability Definitions by severity score range.

Statuses Array of String Search for Vulnerability Definitions by statuses. Possible values: • Irrelevant • Resolved • In Process • Unassigned

Title String Search for Vulnerability Definitions by title.

CVSSBaseScores DoubleRange (see page 283)

Search for Vulnerability Definitions by CVSS base score range.

CVSSTemporalScores


Search for Vulnerability Definitions by CVSS temporal score range.

ReportedDate DateRange (see page 282)

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

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

Search for Vulnerability Definitions by users or user groups who created



Field Type Comments 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 311)

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

A list of all custom fields for this ticket type.



Field Type Comments

demotions Integer The number of times the ticket was demoted. If no phases exist, this field is empty.

externalTicketId Integer The external ticket ID if this exists, or empty otherwise.

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

A list of all selected solutions for the ticket.

networkScope Array of NetworkEntityItem (see page 308)

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.

Documents

Developer’s Guide - Skyboxdownloads.skyboxsecurity.com/files/Installers/Archive/8.5/8.5.500/D… · Skybox®, Skybox® Security, Skybox Firewall Assurance, Skybox Network Assurance,