API Overview

Current API documentation is available within your Xylok installation, at /api/v1-docs/. This can be accessed via the user menu → API Documentation.

API UI example

The token for authorization can be found in the same menu, under API Token.

Examples

API examples can be found on the Xylok documentation index page, /docs/. The publicly accessible version is at https://app.xylok.io/docs/.

The current API endpoints are intended for automating scans, where you can fully automate the process of scanning, uploading, and analyzing a machine. In the example scripts, we pretend we want to scan a machine called Zeus. The expected request flow would look roughly like this:

Find the machine ID of the machine you’re scanning by host name /api/v1/machine?host_name=zeus. A list of machines is returned from this call, but if you only have one match it’ll be the first item in results. So, save results[0].pk as machine_pk
Get script for machine: /api/v1/machine/{machine_pk}/script/. Save resulting task ID as script_task_pk
Wait for task to complete to be done by repeatedly calling /api/v1/tasks/{script_task_pk}/ until the returned JSON shows complete is true.
The final result from checking the task will have a download property with a URL: fetch that URL, which will be the ZIP file containing the script.
Extract ZIP file
Run script inside
Upload results file using /api/v1/upload. An array of task IDs is returned, but for a single result file it should only be one task. Save it as upload_task_pk
Wait for task upload_task_pk to complete using the same process as before
Get most recent machine scans /api/v1/machine/{machine_pk}/scans/?limit=2. An array of scans is returned, save results[0].pk as new_scan_pk and results[1].pk as old_scan_pk
Copy interview answers from old scan to new scan via /api/v1/scans/{old_scan_pk}/copy-answers-to/{new_scan_pk}
Run automatic analysis: /api/v1/scans/{new_scan_pk}/aa/execute/

At that point, the scan is now as analyzed as it can be without human intervention.

Automatic Periodic Scan

On RHEL and other Systemd-based Linux distrobutions, we have an example systemd timer and service listed on the main docs page. To use it:

Put the xylok_auto_scan.sh script on the system you’ll be scanning
Edit xylok-collect.service. Change the ExecStart line to point to the path of the script. Add the CLI arguments to the script, just as if you were doing it yourself. Alternatively, edit the auto scan script to include the needed values directly.
Edit xylok-collect.timer. It has an OnCalendar entry in it that will run on the 10th of every month, but that can be freely changed.
Put the xylok-collect.timer and xylok-collect.service files in /etc/systemd/system/
Run sudo systemctl daemon-reload (to make systemd detect the new files)
Run sudo systemctl enable --now xylok-collect.timer to enable and start the timer.
Run sudo systemctl list-timers to verify the timer is now visible.
Test the script itself by running sudo systemctl start xylok-collect.service. That will start the data collection in the background. You can watch it run with sudo journalctl -u xylok-collect.service -f