Metadata-Version: 1.1
Name: smc-python
Version: 0.6.1
Summary: Python based API to Stonesoft Security Management Center
Home-page: http://github.com/gabstopper/smc-python
Author: David LePage
Author-email: dwlepage70@gmail.com
License: Apache 2.0
Description-Content-Type: UNKNOWN
Description: |Documentation Status| |Python version| |PyPI version| 
        
        smc-python
        ==========
        
        Python based library to provide the ability to interact with the
        Stonesoft Management Center API. Provides automation capabilities for
        any environment that interact with the SMC remotely.
        
        Some of the functionality you get with the SMC Python API:
        
        -  Create any engine types; single firewall, cluster firewalls, ips
           engines, layer 2 firewalls, master engine and virtual engines.
        -  Engine operations such as enabling/disabling AV, GTI, default NAT,
           Contact Addresses, etc
        -  Interface configurations
        -  Routing configurations (OSPF, BGP, Static, Antispoofing)
        -  Engine level commands such as rebooting, going offline, policy push,
           enable/disable SSH, etc.
        -  Create and modify all network element objects such as Host, Network,
           Address Ranges, Domain Names, etc.
        -  Policy control (create rules, delete rules) for layer 3 firewall
           policies
        -  VPN Policy control and creation
        -  Management / Log Server settings configuration
        -  Admin User creation and modification
        -  System level controls; update system packages, update engines, global
           blacklisting, etc
        -  Tasks
        -  Search operations for any object type by name, href and by filter
        -  Collections interface to view all objects by type
        
        Requirements
        ------------
        
        Python 2.7
        
        Python 3.4, 3.5
        
        Requests >= 2.12.0
        
        Security Management Center version 6.0, 6.1, 6.1.1, 6.1.2, 6.2, 6.2.1, 6.3.x
        
        Getting Started
        ---------------
        
        Installing package
        
        Use pip to get latest released version:
        
        ``pip install smc-python``
        
        Specific version:
        
        ``pip install smc-python>=0.5.8``
        
        From git:
        
        ``pip install git+https://github.com/gabstopper/smc-python.git``
        
        Or download the latest tarball:
        `smc-python <https://github.com/gabstopper/smc-python/archive/master.zip>`__,
        unzip and run:
        
        ``python setup.py install``
        
        *The master branch is used as a dev branch, installing from this branch will pull the latest code commit. All commits are still tested before being uploaded.*
        
        Testing
        -------
        
        Included are a variety of test example scripts that leverage the API to
        do various tasks in /examples
        
        Basics
        ------
        
        Before any commands are run, you must obtain a login session. Once
        commands are complete, call `session.logout()` to remove the active session.
        To obtain the api\_key, log in to the Stonesoft Management Center and
        create an API client with the proper privileges.
        
        .. code:: python
        
            from smc import session
        
            session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxx')
            ....do stuff....
            session.logout()
        
        Or log in to a specific Admin Domain and use a specific version of the
        API:
        
        .. code:: python
        
            session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxx',
                          domain=mydomain, api_version=6.2)
            ....do stuff....
            session.logout()
        
        Once a valid session is obtained, it will be re-used for each operation
        for the duration of the sessions validity, or until the program is
        exited.
        
        Extensions
        **********
        
        Extensions are available to smc-python that provide additional functionality besides what
        is provided in the base library. Extensions are kept separate as they may require additional
        package requirements and simplify packaging.
        
        Extensions will require smc-python to function, but it is possible to install an extension
        directly and it will grab the required smc-python version automatically.
        
        Available extensions:
        
        * `smc-python-monitoring <https://badge.fury.io/py/smc-python-monitoring>`__: Monitoring for SMC connections, blacklists, users, VPNs, alerts, etc. In addition this package provides the ability to 'subscribe' to administrative event modifications.
        
        
        Example install of an smc-python extension:
        
        ``pip install smc-python-monitoring``
        
        Extensions are found in the base smc-python repository as namespace packages and each is housed in it's own sub-directory of this base package.
        
        Please see the read-the-docs documentation above for a full explanation
        and technical reference on available API classes.
        
        `View Documentation on Read The
        Docs <http://smc-python.readthedocs.io/en/latest/?badge=latest>`__
        
        .. |Documentation Status| image:: https://readthedocs.org/projects/smc-python/badge/?version=latest
           :target: http://smc-python.readthedocs.io/en/latest/?badge=latest
        .. |PyPI version| image:: https://badge.fury.io/py/smc-python.svg
           :target: https://badge.fury.io/py/smc-python
        .. |Python version| image:: https://img.shields.io/pypi/pyversions/smc-python.svg?maxAge=2592000
            :target: https://pypi.python.org/pypi/smc-python/
        
        Release History
        ===============
        
        0.5.6
        -----
        
        .. note:: For older release release history information, see CHANGELOG. All future documentation will be logged
        	in this document.
        
        **Improvements**
        
        - Support SMC 6.3:
            - Support for L2 interface policies (Inline L2, IPS and Capture interfaces on L3 engine)
            - Route based VPN support, IPSEC wrapped RBVPN and GRE Tunnel/Transport/No Encryption VPN.
        - SMC 6.3 API only supports TLSv1.2 or greater, ensure your openssl version supports TLSv1.2. This can be done
          by: openssl s_client -connect <smc_ip>:8082 -tls1_2
        - Simplified generic Search (`smc.base.collections.Search`) to be uniform with ElementCollection.
        - Simplify API reference documentation
        - SMC login using environment variables. See session documentation for more info.
        - Rule counters on all Policy types
        - Proxy or static type required when adding arp entry to interface
        - Add simple .get() method on Element. This simplifies determining if the element by name exists. For example,
          Host.get('kali') would raise ElementNotFound if it doesn't exist. Prior to this, you would have to search
          for the element and attempt to access and element resource before receiving the ElementNotFound message,
          i.e. host = Host('kali'); host.address. The 'get()' method still returns an 'un-inflated' instance (only meta
          data).
        - Deprecation warnings are now generated for functions in `smc.core.engine.interfaces`:
          `add_single_node_interface`, `add_node_interface`, `add_vlan_to_node_interface`, `add_ipaddress_to_vlan_interface`.
          These functions will eventually be deprecated. As of version 6.3, SMC engines can now support both layer 2 and
          layer 3 interfaces on the same engine. New interface functions added: `add_layer3_vlan_interface`, `add_layer3_interface`,
          `add_inline_ips_interface`, `add_inline_l2fw_interface`.
        - New element types: URLCategory, URLCategoryGroup, ICMPServiceGroup
        
        
        .. important:: Renamed `smc.vpn.policy.VPNPolicy` to `smc.vpn.policy.PolicyVPN`
        
        **Bugfixes**
        
        - HTTP GET was treating a 204 response as an error, fix to treat No Content response as success.
        - Fix help() on dynamic `create_collection` class so constructor methods are proxied properly
        - Raise SMCConnectionError when non-HTTP 200 error code presented from SMC when retrieving entry points
        - Sending empty payload on POST request with parameters might cause validation error. Do not submit empty
          dict with POST requests.
          
        0.5.8
        -----
        
        **Improvements**
        
        - Support for SMC version 6.3.0, 6.3.1 and 6.3.2
        - Add ``case_sensitive`` key word to filtered queries. This requires SMC 6.3+. Set this as a kwarg when making
          the query: Host.objects.filter('myhost', case_sensitive=False). Default: case_sensitive=True.
        - Optimize retrieval of nodes by serializing engine node data versus making a call to the engine links. This eliminates
          the query to get the node links and a query for each node that needs to be operated on, or node payload required.
        - Add `smc.core.node.ApplianceInfo` and link on node to retrieve appliance related info:
        	appliance = node.appliance_info()
        	...
        - GatewayTunnel implemented on PolicyVPN for setting preshared key, enabling/disabling specific tunnel endpoints
        - BGP node added to engine. Add full create/modify/delete capability by reference: engine.bgp.is_enabled, etc. Added to
          provide modular configuration to BGP.
        - OSPF node added to engine. Add full create/modify/delete capability by reference: engine.ospf.is_enabled, etc.
        - merging lists on element update will now filter out duplicate entries before potentially updating. The SMC API protects
          against this but validation moved into element update function saving potential exception on PUT
        - get_or_create and update_or_create return classmethod get for elements that are considered read-only; i.e. do not have
          a `create` classmethod.
        - update_or_create will now check the provided key/value pairs before updating the specified element. This is to make
          the modification more idempotent. If the retrieved element exists and has the same value (based on current ETag), then
          do not modify.
        - Optimization of resolved alias retrieval from the engine. Instead of retrieving all aliases and resolving the alias
          reference, first retrieve the entire list of aliases (1 query) and then correlate to resolved alias references. This
          amounts to reducing the number of queries to retrieve a single engines aliases from ~60 to 3.
        - set_stream_logger and set_file_logger attached to smc.api.session.Session() as convenience functions.
        - Optimize logging at request level, more clear output
        - Simplify interface creating where zone or logical interface is needed. Now zone/logical interfaces can be provided
          as either name (if they don't exist, they will be created), as href, or as Zone/LogicalInterface instances.
        - New engine level resources: antivirus, file_reputation, sidewinder_proxy, sandbox and url_filtering, policy_routing,
          dns and default nat added as engine resources. Previous functions nested in smc.core.properties.AddOns set to deprecated
          and will be removed in the near future.
        - Added support for adding DNS Server entries to engines based on elements (previously only IP addresses were supported).
        - TLS Server Credentials supported for inbound SSL decryption, add to engine from engine.tls_inspection resource.
        - Add create_hook to ElementCreator to intercept json before submitting to SMC server. See smc.base.decorators.create_hook
          for more info.
        - Added engine.interface_options node for settings related to setting primary mgt, backup mgt, primary hearbeat, and backup heartbeat
          rather than having them nested on the PhysicalInterface. These can be called directly from the engine which removes ambiguity in how
          these settings are modified. Previous versions they could be called directly (i.e. engine.physical_interface.set_primary_mgt() however
          required unnecessary plumbing. This more closely models the SMC UI configuration.
        - All engine interface nodes now return InterfaceCollection as an iterable. Also included is a get(interface_id) method to 
          directly retrieve an interface of that type. Any 'add' methods are proxied from the collection manager to an instance.
        - remove_vlan on interface no longer requires the interface reference, however now requires the interface context to run. Before:
          engine.physical_interface.remove_vlan(interface_id=100, vlan_id=1), now you need to load the interface, then delete the
          vlan: interface = engine.interface.get(100); interface.remove_vlan(1)
        - history property on Element added
          
         **Bugfixes**
         
         - If a search is provided in format: Host.objects.filter(address='1.1.1.1').first(), and the search returns meta but the
           filtered results do not return a match, the method tries to pop from an empty list. Return None instead.
        
        0.6.0
        -----
        
        **Tested SMC Version**
        
        - Support for SMC 6.3.3, 6.3.4
        
        **Improvements**
        
        - SubElementCollection helper methods for using matching criteria on returned results: get, get_contains, get_all_contains.
          Useful for searching meta data returned for this collection type.
        - IndexedIterable used for collections returned in various areas of the configuration and provides a common interface
          for data that is returned in lists. IndexedIterable classes provide a simplified interface to retrieving data from the
          collection.
        - Change add_arp_entry to static_arp_entry in physical_interface
        - Added Reports to smc.administration module
        - Added collections for all interfaces making it possible to fetch a VLAN or sub interface without iterating
        - File objects can be accepted for TLSServerCredential import methods
        - InterfaceNotFound exception replaces EngineCommandFailed when fetching interfaces
        - engine.routing.get raises InterfaceNotFound instead of returning None when specified interface does not exist
        - renamed remove_route_element to remove_route_gateway in smc.core.route.Routing
        - engine.routing shortcuts: as_tree, bgp_peerings, ospf_areas, netlinks
        - delete instance cache after successful delete() call
        - Policy rules support for decrypting (requires SMC >= 6.3.3)
        - TLS Server Credential elements support valid_from, valid_to
        - current_user property added to session to derive the logged on user from the API client key
          
        0.6.1
        -----
        
        **Tested SMC Version**
        
        - Support for SMC 6.3.4, 6.4.0
        - ReportDesign.generate takes new arguments for start_time, end_time and senders to specify the timeframe
          to run the report and any filters
        - Improved readability of debug logging
        - Fetch by VLAN id in format '1.10' for interface 1, vlan 10. Using engine.interface.get('1.10')
        - Removed dependency on third party ipaddress module
        - Layer3Firewall and FirewallCluster can now take an additional `interfaces` argument to define additional
          interfaces to create when creating a single or cluster FW. VLANs definitions are also supported.
        - Create rule sections in all supported rule types, comments for rules
        - Firewall Clusters can be fully created with additional interfaces and primary_heartbeat, backup_mgt fields
          can be customized during creation
        - Renamed module smc.core.properties to smc.core.addon
        - Added keyword argument to get_or_create and update_or_create `with_status` which takes a boolean value.
          If set, will return a 2 tuple (Element, was_created), were was_created indicates whether the element
          had to be created or whether it was fetched.
        - Add BGP Peerings to Tunnel Interface fixed to set on top level interface versus network level.
        - update_or_create methods for ExternalGateway, ExternalEndpoint and VPNSite. Allows for full provisioning
          of an external gateway and update after creation.
        - Interfaces rewritten to provide more flexibility. Interfaces can be built from a low level API or previous
          helper methods can be used
        
         
        
         
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
