def get_list(page=1, limit=10, key=None, exclude=None, **kwargs):
"""Return response tuple as response to API call.
Note:
Up to 200 records can be returned by API.
Args:
page (int): Page # to request.
limit (int): Limit number of records to request.
key (str): API key, if not specify obtain via ``key`` module.
Returns:
Return ``requests.Response`` object.
http://docs.python-requests.org/en/master/api/#requests.Response
"""
assert isinstance(page, int)
assert isinstance(limit, int)
key = get_key(key=key)
response = None
api_uri = ("https://s-platform.api.opendns.com/1.0/" +
"domains?customerKey=" + key)
api_uri += "&page={0}&limit={1}".format(page, limit)
response = send_get(url=api_uri)
format_response(response.status_code, json.loads(response.text), exclude,
**kwargs)
return response
def top_identities(destination, cred=None, orgid=None, **kwargs):
"""Request top10 identities which send DNS requests to destination.
Parameters:
destination (str): a domain name specified without
any protocol or delimiters
orgid (str): Cisco Umbrella organization ID
Returns:
requests.Response: Return ``requests.Response`` class object
"""
cfg_file = kwargs.get("filename", "umbrella.json")
exclude = kwargs.get("exclude", None)
api_uri = (
"https://reports.api.umbrella.com/v1/organizations"
+ "/{}/destinations/{}/identities".format(
get_orgid(orgid, filename=cfg_file), destination
)
)
ident_response = send_get(
url=api_uri, headers=get_headers(cred, filename=cfg_file)
)
if ident_response.status_code == 200:
table = json_to_table(
json.loads(ident_response.text)["identities"], exclude_col=exclude
)
print(
tabulate(
table[1:], headers=table[0], tablefmt=kwargs.get("format")
)
)
return ident_response
def management_api(command, orgid=None, cred=None, limit=10, page=1, **kwargs):
"""Send a command to Umbrella Management API."""
assert command in MNGT_API_COMMANDS
console = kwargs.get("console", True)
cfg_file = kwargs.get("filename", "umbrella.json")
exclude = kwargs.get("exclude", None)
table_format = kwargs.get("format")
api_uri = (
"https://management.api.umbrella.com/v1/organizations"
+ "/{}/{}?limit={}&page={}".format(
get_orgid(orgid, filename=cfg_file), command, limit, page
)
)
response = send_get(
url=api_uri,
headers={
"Authorization": "Basic {}".format(
get_base64(cred=cred, filename=cfg_file, api="management")
)
},
)
if response.status_code == 200:
if console:
table = json_to_table(
json.loads(response.text), exclude_col=exclude
)
print(tabulate(table[1:], headers=table[0], tablefmt=table_format))
else:
logger.error(
"HTTP Status code: %s\n%s", response.status_code, response.text
)
return response
def activity(cred=None, orgid=None, **kwargs):
"""Request the last security activities.
Parameters:
orgid (str): Cisco Umbrella organization ID
limit (int): the number of results to return, from 1 to 500
start (int): the start of the time window for which
results are shown, specified as Unix (epoch)
timestamp in seconds.
stop (int): the stop of the time window for which
results are shown, specified as Unix (epoch)
timestamp in seconds
_stop_timest (int): used for pagination and gathered
from the output of the previous query, specified as
Unix (epoch) timestamp in milliseconds. (not implemented)
Returns:
requests.Response: Return ``requests.Response`` class object
"""
cfg_file = kwargs.get("filename", "umbrella.json")
limit = kwargs.get("limit", 10)
start = kwargs.get("start", None)
stop = kwargs.get("stop", None)
exclude = kwargs.get("exclude", None)
if start and stop:
time_filter = "&start={}&stop={}".format(start, stop)
else:
time_filter = ""
api_uri = (
"https://reports.api.umbrella.com/v1/organizations"
+ "/{}/security-activity?limit={}{}".format(
get_orgid(orgid, filename=cfg_file), limit, time_filter
)
)
activity_response = send_get(
url=api_uri, headers=get_headers(cred, filename=cfg_file)
)
if activity_response.status_code == 200:
table = json_to_table(
json.loads(activity_response.text)["requests"], exclude_col=exclude
)
print(
tabulate(
table[1:], headers=table[0], tablefmt=kwargs.get("format")
)
)
return activity_response
def recent(destination, cred=None, orgid=None, offset=0, **kwargs):
"""Request the most recent DNS requests for a particular destination.
Parameters:
destination (str): a domain name specified without any
orgid (str): Cisco Umbrella organization ID protocol or
delimiters
limit (int): number of requests for the specified
destination returned
offset (int): changes which index the list of returned
orgs starts at. Default is 0, and orgs are listed in
reverse alphabetical order. Offset essentially allows
for pagination. If the first set of results shows 50,
then offset=50 shows the next fifty and offset=100 shows
the next fifty after that.
Returns:
requests.Response: Return ``requests.Response`` class object
"""
cfg_file = kwargs.get("filename", "umbrella.json")
exclude = kwargs.get("exclude", None)
limit = kwargs.get("limit", 10)
api_uri = (
"https://reports.api.umbrella.com/v1/organizations"
+ "/{}/destinations/{}/activity?limit={}&offset={}".format(
get_orgid(orgid, filename=cfg_file), destination, limit, offset
)
)
recent_response = send_get(
url=api_uri, headers=get_headers(cred, filename=cfg_file)
)
if recent_response.status_code == 200:
table = json_to_table(
json.loads(recent_response.text)["requests"], exclude_col=exclude
)
print(
tabulate(
table[1:], headers=table[0], tablefmt=kwargs.get("format")
)
)
return recent_response
def test_send_get(self):
"""Call incorrect send_get, get None.""" # import requests
from umbr_api._http_requests import send_get
response = send_get(" ")
self.assertEqual(response, None)