6. Using the WAPT Server APIs¶
Note
This documentation does not describe all the available APIs, it will however concentrate on the most useful ones.
All available API URLs may be found in /opt/wapt/waptserver/server.py
.
URLs are formed by calling the proper command from the WAPT Server, ex: https://srvwapt/command_path
.
Hint
This documentation contains examples using Python code or curl.
Warning
Since version 2.5, most API URLs are protected with SSL client certificates. You will have to modify your scripts (cf. examples below).
6.1. API V1¶
6.1.1. /api/v1/hosts¶
Get registration data of one or several hosts.
# Args: # has_errors (0/1): filter out hosts with packages errors # need_upgrade (0/1): filter out hosts with outdated packages # groups (csvlist of packages): hosts with packages # columns (csvlist of columns): # uuid (csvlist of uuid): <uuid1[,uuid2,...]>): filter based on uuid # filter (csvlist of field):regular expression: filter based on attributes # not_filter (0,1): # limit (int): 1000 # trusted_certs_sha256 (csvlist): filter out hosts based on their trusted package certs # Returns: # result (dict): {'records':[],'files':[]} # query: # uuid=<uuid> # or # filter=<csvlist of fields>:regular expression # """
List all hosts using the following parameters:
reachable;
computer_fqdn ==> computer_name;
connected_ips;
mac_addresses.
This example shows a request with parameters:
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem') advanced_hosts_wapt = wgets('https://%s:%s@%s/api/v1/hosts?columns=reachable,computer_fqdn,connected_ips,mac_addresses&limit=10000' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path) parsed = json.loads(advanced_hosts_wapt) print(json.dumps(parsed, indent=1, sort_keys=True))
This example is a global request:
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem') hosts_wapt = wgets('https://%s:%s@%s/api/v1/hosts' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path) parsed = json.loads(hosts_wapt) print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/hosts
This one just show request with reachable status, the computer name, its connected ips and its mac addresses. The display limit is 10000.
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/hosts?columns=reachable,computer_fqdn,connected_ips,mac_addresses&limit=10000
6.1.2. /api/v1/groups¶
Get all group packages. Group is found with section group in the package:
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem') group_wapt = wgets('https://%s:%s@%s/api/v1/groups' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path) parsed = json.loads(group_wapt) print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/groups
6.1.3. /api/v1/host_data¶
6.1.3.1. dmi¶
Get DMI info for a host:
Note
# # Get additional data for a host # query: # uuid=<uuid> # field=packages, dmi or softwares
Note
dmi is not the only available option. You can also lookup information using installed_packages, wsusupdates ou installed_softwares.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
dmi_host_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=dmi' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
#print(dmi_host_data_wapt)
parsed = json.loads(dmi_host_data_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=dmi
6.1.3.2. installed_packages¶
Option installed_packages will list all packages installed on a specific host.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
install_packages_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=installed_packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(install_packages_data_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=installed_packages
6.1.3.3. installed_softwares¶
Option installed_softwares will list all softwares installed on a specific host.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
install_softwares_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=installed_softwares' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
#print(install_softwares_data_wapt)
parsed = json.loads(install_softwares_data_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=installed_softwares
6.1.3.4. wsusupdates¶
Option wsusupdates will list all Windows Updates installed on a specific host.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
wsusupdates_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=wsusupdates' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
#print(wsusupdates_data_wapt)
parsed = json.loads(wsusupdates_data_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=wsusupdates
6.1.4. /api/v1/usage_statistics¶
Get usage statistics from the WAPT Server.
Hint
This API is useful if you have several WAPT Servers and you want to know how many hosts are there.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
usage_statistics_wapt =wgets('https://%s:%s@%s/api/v1/usage_statistics' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
#print(usage_statistics_wapt)
parsed = json.loads(usage_statistics_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/usage_statistics
6.2. API V2¶
6.2.1. /api/v2/waptagent_version¶
Display waptagent.exe version.
waptagent_version = wgets('https://%s:%s@%s/api/v2/waptagent_version' % (wapt_user,wapt_password,wapt_url))
parsed = json.loads(waptagent_version)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v2/waptagent_version
6.3. API V3¶
6.3.1. /api/v3/reporting_exec¶
Here is a python script that executes a query with a specific id from WAPT Console Reporting tab. In this script, user “reporting” should have “Run reports” ACL. It works on every platform (windows, linux and mac agents).
import os
import json
import logging
import waptlicences
import requests
import sys
sys.path.append('/opt/wapt')
from common import get_requests_client_cert_session
from common import Wapt
WAPT = Wapt()
ini_wapt_path = WAPT.config_filename
w = Wapt(config_filename=ini_wapt_path)
# WAPT Conf
wapt_url = w.waptserver.server_url
user = "reporting"
password = "password"
def run_report():
t = waptlicences.waptserver_login(ini_wapt_path,user,password)
session = get_requests_client_cert_session(wapt_url,
cert=(t['client_certificate'],t['client_private_key'],t['client_private_key_password']),
verify=w.waptserver.verify_cert
)
session.cookies.set(t['session_cookies'][0]['Name'], t['session_cookies'][0]['Value'], domain=t['session_cookies'][0]['Domain'])
t= None
url = f'{wapt_url}/api/v3/reporting_exec?id=19'
response = session.get(url)
data = response.json()
return data['result']
print(run_report())
6.3.2. /api/v3/packages¶
List packages on the repository, retrieve the control
files of WAPT packages.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
packages_wapt = wgets('https://%s:%s@%s/api/v3/packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(packages_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/packages
6.3.3. /api/v3/known_packages¶
List all packages with last signed_on information.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
known_packages_wapt = wgets('https://%s:%s@%s/api/v3/known_packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(known_packages_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/known_packages
6.3.4. /api/v3/trigger_cancel_task¶
Cancel a running task.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
trigger_cancel_task = wgets('https://%s:%s@%s/api/v3/trigger_cancel_task' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(trigger_cancel_task)
print(json.dumps(parsed, indent=1, sort_keys=True))
6.3.5. /api/v3/get_ad_ou¶
List OU seen by hosts and displayed in the WAPT Console.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
get_ad_ou = wgets('https://%s:%s@%s/api/v3/get_ad_ou' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(get_ad_ou)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_ou
6.3.6. /api/v3/get_ad_sites¶
List Active Directory sites.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
get_ad_sites = wgets('https://%s:%s@%s/api/v3/get_ad_sites' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(get_ad_sites)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_sites
6.3.7. /api/v3/hosts_for_package¶
List hosts with a specific package installed.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
hosts_for_package = wgets('https://%s:%s@%s/api/v3/hosts_for_package?package=PACKAGE' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(hosts_for_package)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_for_package?package=demo-namepackage
6.3.8. /api/v3/host_tasks_status¶
List tasks on a particular host.
cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
host_tasks_status = wgets('https://%s:%s@%s/api/v3/host_tasks_status?uuid=UUID' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
parsed = json.loads(host_tasks_status)
print(json.dumps(parsed, indent=1, sort_keys=True))
Hint
This is the same exemple with a simple html request:
https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/host_tasks_status?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD
Attention
Next API are with POST method.
6.3.9. /api/v3/upload_packages¶
Todo
Tests
6.3.10. /api/v3/upload_hosts¶
Todo
Tests
6.3.11. /api/v3/change_password¶
Change the Admininistrator password [only this account]. The request is a python dictionnary {} with keys:
user;
old_password;
new_password.
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"user":"USER","password":"old_password","new_password":"new_password"}' -H "Content-Type: application/json" "https://user:old_password@srvwapt/api/v3/change_password"
6.3.12. /api/v3/login¶
Initialize a connection to the WAPT Server.
curl --insecure -X POST --data-raw '{"user":"admin","password":"MYPASSWORD"}' -H "Content-Type: application/json" "https://srvwapt.mydomain.lan/api/v3/login"
{"msg": "Authentication OK", "result": {"edition": "enterprise", "hosts_count": 6, "version": "1.7.4", "server_domain": "mydomain.lan", "server_uuid": "32464dd6-c261-11e8-87be-cee799b43a00"}, "success": true, "request_time": 0.03377699851989746}
Hint
We can make a connection by html form then POST: https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_sites
6.3.13. /api/v3/packages_delete¶
Delete package with a precise version. The request is a python list []. A list of packages may be given, separated by commas ,.
Example:
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '["demo-libreoffice-stable_5.4.6.2-3_all.wapt"]' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/packages_delete"
6.3.14. /api/v3/reset_hosts_sid¶
Reinitialize all host connections.
For the POST method, the syntax is: --data-raw
a dictionnary list with uuids
as keys and the UUIDs of the hosts as values.
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/reset_hosts_sid"
{"msg": "Hosts connection reset launched for 1 host(s)", "result": {}, "success": true, "request_time": null}
Hint
If you want several hosts:
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID#1","UUID#2"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/reset_hosts_sid"
{"msg": "Hosts connection reset launched for 2 host(s)", "result": {}, "success": true, "request_time": null}
6.3.15. /api/v3/trigger_wakeonlan¶
If hosts are WakeOnLan enabled, this API is useful.
Syntax is --data-raw
: a dictionnary with key uuids and a list of host uuids.
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/trigger_wakeonlan"
{"msg": "Wakeonlan packets sent to 1 machines.", "result": [{"computer_fqdn": "computer_fqdn", "mac_addresses": ["mac_addresses"], "uuid": "UUID"}], "success": true, "request_time": null}
Hint
If you want several hosts:
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID#1","UUID#2"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/trigger_wakeonlan"
{"msg": "Wakeonlan packets sent to 2 machines.", "result": [{"computer_fqdn": "computer_fqdn#1", "mac_addresses": ["mac_addresses#1"], "uuid": "UUID#1"}, {"computer_fqdn": "computer_fqdn#2", "mac_addresses": ["mac_addresses#2"], "uuid": "UUID#2"}], "success": true, "request_time": null}
6.3.16. /api/v3/hosts_delete¶
"""Remove one or several hosts from the WAPT Server database and optionnally the host packages
Args:
uuids (list): list of uuids to delete
filter (csvlist of field:regular expression): filter based on attributes
delete_packages (bool): delete host's packages
delete_inventory (bool): delete host's inventory
Returns:
result (dict):
"""
If you want to delete a host from the inventory:
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"],"delete_inventory":"True","delete_packages":"True"}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_delete"
{"msg": "1 files removed from host repository\n1 hosts removed from DB", "result": {"files": ["/var/www/wapt-host/UUID.wapt"], "records": [{"computer_fqdn": "computer_fqdn", "uuid": "UUID"}]}, "success": true, "request_time": null}
If you do not want to delete from the inventory:
curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"],"delete_inventory":"False","delete_packages":"False"}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_delete"
{"msg": "0 files removed from host repository\n1 hosts removed from DB", "result": {"files": [], "records": [{"computer_fqdn": "computer_fqdn", "uuid": "UUID"}]}, "success": true, "request_time": null}
6.3.17. /api/v3/trigger_host_action¶
Todo
Tests
6.3.18. /api/v3/upload_waptsetup¶
# Upload waptsetup
#Handle the upload of customized waptagent.exe into wapt repository
### DOES NOT WORK
#curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST -H "Content-Type: multipart/form-data" -F 'data=@waptagent.exe' "https://admin:MYPASSWORD@srvwapt.mydomain.lan/upload_waptsetup"
6.3.19. /api/v3/ping¶
Ping shows a general set of informations on a WAPT Server.
# https://srvwapt.mydomain.lan/ping
# Lists WAPT Server informations
ping_wapt = wgets('https://%s:%s@%s/ping' % (wapt_user,wapt_password,wapt_url))
parsed = json.loads(ping_wapt)
print(json.dumps(parsed, indent=1, sort_keys=True))