Python based API to Stonesoft Security Management Center
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
- Search operations for any object type by name, href and by filter
- Collections interface to view all objects by type
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.0
Use pip to get latest released version:
pip install smc-python
pip install smc-python>=0.5.5
If you are installing directly from git or tarball, you will be installing the latest dev branch. The dev branch does undergo unittest prior to push, however it is likely coverage will not be as complete as a released version.
pip install git+https://github.com/gabstopper/smc-python.git
Or download the latest tarball: smc-python, unzip and run:
python setup.py install
Included are a variety of test example scripts that leverage the API to do various tasks in /examples
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.
from smc import session session.login(url='http://18.104.22.168:8082', api_key='xxxxxxxxxxxxx') ....do stuff.... session.logout()
Or log in to a specific Admin Domain and use a specific version of the API:
session.login(url='http://22.214.171.124: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 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.
- 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.
For older release release history information, see CHANGELOG. All future documentation will be logged in this document.
- 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
Renamed smc.vpn.policy.VPNPolicy to smc.vpn.policy.PolicyVPN
- 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.
- 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).
- If a search is provided in format: Host.objects.filter(address=‘126.96.36.199’).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.