Usage and Examples¶
The aim of this module is to provide simple object based access to the BloxOne APIs and make it as simple as possible to code given the swagger available documentation.
There are several classes/subclasses that provide this access. The base
class is b1
. This acts as a parent class for the BloxOne Application
APIs.
Associated with this are the subclasses b1platform
that provide access
to API calls associated with the BloxOne platform itself and b1ddi
that
provides access the BloxOne DDI API core methods for get, create, delete
and update in addition to specific task orientated helper methods.
Note
Currently it is only the Platform and BloxOne DDI APIs subclasses that have been developed.
BloxOne Threat Defense and Cloud will be added in a later version. Place holder files currently contain functions for TIDE and Dossier based on the ActiveTrust platform rather than BloxOne APIs. At this time this has not been tested so functionality may be limited.
There is an associated set of utility functions provided in bloxone.utils.
Basic Usage¶
For BloxOne DDI therefore the basic usage structure for a get is:
import bloxone
b1ddi = bloxone.b1ddi(<cini file>)
response = b1ddi.get(<object path>)
if response.status_code in b1ddi.return_codes_ok:
print(response.text)
else:
print(response.status_code
Similarly for the other core functions. For details around parameters, please see the class documentation
For debugging purposes, the bloxone
module supports logging via the logging
module using debug.
Warning
Although I have attempted to keep debugging clean. There is still potential for the debug output to produce full data dumps of API responses.
Examples¶
Todo
These examples are placeholders, useful, but actual example set here is on the todo.
# Note this is a set of rough examples to show mthod calls
import bloxone
import logging
log=logging.getLogger(__name__)
# logging.basicConfig(level=logging.DEBUG)
# Create a BloxOne DDI Object
b1ddi = bloxone.b1ddi()
# Specify ini filename
# b1ddi = bloxone.b1ddi('/Users/<username/<path>/<inifile>')
# Show API Key
b1ddi.api_key
# Generic Get wrapper using "Swagger Path for object"
response = b1ddi.get('/ipam/ip_space')
# Response object handling
response.status_code
response.text
response.json()
# Using custom parameters
response = b1ddi.get('/dns/view', _fields="name,id")
response.text
# Example with multiple API parameters
response = b1ddi.get('/ipam/subnet', _tfilter="Owner==marrison",_fields="address")
response = b1ddi.get('/ipam/subnet', _tfilter="Owner~mar")
# Get ID from key/value pair
id = b1ddi.get_id('/dns/auth_zone', key="fqdn", value="home.")
# 'dns/auth_zone/80b0e234-8d5b-465b-8c98-e9430c5d83a9'
id = b1ddi.get_id('/ipam/ip_space', key="name", value="marrison-lab")
# 'ipam/ip_space/fd388619-b013-11ea-b956-ca543bd8c483'
r = b1ddi.get_zone_child(parent="zone", name="home.", fields="name,record_type,record_data")
# Get all on_prem_hosts
b1platform = bloxone.b1platform()
response = b1platform.on_prem_hosts()
response.text
# Using tag filters
response = b1platform.on_prem_hosts(_tfilter="Owner==marrison")
response.text
# Get all records for a 'named' zone
response = b1ddi.get_zone_child(name="home.")
response.text
# Get all zones in a view by view name
response = b1ddi.get_zone_child(name="marrison-dns-view1")
response.text
# Create Examples
body = '{ "name": "my-ip-space", "tags": { "Owner": "marrison" }}'
r = b1ddi.create('/ipam/ip_space', body=body)
r.text
# '{"result":{"asm_config":{"asm_threshold":90,"enable":true,"enable_notification":true,"forecast_period":14,"growth_factor":20,"growth_type":"percent","history":30,"min_total":10,"min_unused":10,"reenable_date":"1970-01-01T00:00:00Z"},"asm_scope_flag":0,"comment":"","dhcp_config":{"allow_unknown":true,"filters":[],"ignore_list":[],"lease_time":3600},"dhcp_options":[],"id":"ipam/ip_space/edfb2cde-c2fc-11ea-b5c8-3670d2b79356","inheritance_sources":null,"name":"marrison-test","tags":null,"threshold":{"enabled":false,"high":0,"low":0},"utilization":{"abandon_utilization":0,"abandoned":"0","dynamic":"0","free":"0","static":"0","total":"0","used":"0","utilization":0}}}'
>>> r = b1ddi.get_object_by_key('/ipam/ip_space', key="name", value="marrison-lab")
>>> r.text
'{"result":{"asm_config":{"asm_threshold":90,"enable":true,"enable_notification":true,"forecast_period":14,"growth_factor":20,"growth_type":"percent","history":30,"min_total":10,"min_unused":10,"reenable_date":"1970-01-01T00:00:00Z"},"asm_scope_flag":0,"comment":"","dhcp_config":{"allow_unknown":true,"filters":[],"ignore_list":[],"lease_time":43200},"dhcp_options":[],"id":"ipam/ip_space/fd388619-b013-11ea-b956-ca543bd8c483","inheritance_sources":null,"name":"marrison-lab","tags":{"Location":"Hampshire, UK","Owner":"marrison"},"threshold":{"enabled":false,"high":0,"low":0},"utilization":{"abandon_utilization":0,"abandoned":"0","dynamic":"40","free":"65491","static":"5","total":"65536","used":"45","utilization":0}}}'
>>>
# Update tags on an on_prem_hosts object example
# Create a b1platform object
b1p = bloxone.b1platform('/Users/marrison/bin/tide.ini')
# Note: this will change the "tags" i.e. replace the "tags" with the "tags" in the update body
body = '{"display_name":"marrison-hw-ddi1", "tags":{"Location":"Hampshire, UK","Owner":"marrison","host/deployment_type":"APPLIANCE","host/k8s":"false","host/ophid":"63f2b1c3f80455d87186aa054e87f1a9"}}'
# Call the update method
response = b1p.update('/on_prem_hosts', id="97290", body=body)