Lynis Enterprise API
This is the supporting documentation for Lynis Enterprise. The focus of this document is the application programming interface (API), to use and automate data coming from the API. For the installation of Lynis, consult the Installation Guide.
API Basics
Introduction
The application programming interface (API) is a common way to retrieve or store data in software solutions. Lynis Enterprise uses an API accorrding to representational state transfers, also known as REST or RESTful. This means your scripts or software solutions can query data, update it, or delete objects.
Tips
If you use particular fields from the API, have your scripts check for them in the output. This way changes are detected early.
For users of the API it suggested to be on our mailinglist to receive updates about upcoming changes. Ask your support person to be added to the notifications list.
Using the API
The API can be used with popular tools like curl.
curl -sS -X GET https://hostname/api/systems/ \
-H 'Accept: application/json; indent=4' \
-H 'Authorization: Token 0979b38de04ee537341f18bdb5eb6fcc2f7a6da8'
Authentication
To proof your identity, the API expects a form of authentication. Typically this is done with a generated token that is linked to your user account. In the examples you will see this token back in the Authorization header.
Output formats
The API returns data in the popular JSON format. By default no identation is added, as typically data is processed by machines. To add indentation, provide the related header.
curl -sS -X GET https://hostname/api/systems/ \
-H 'Accept: application/json; indent=4'
Parsing output
The jq utility is a great addition to perform both identation and show colored output. Besides that, it can filter the data that you might be looking for.
Throttling
Humans have a typical delay between the requests they make. With machines and automated scripts, the main system can be overwhelmed by requests. Each user is therefore restricted by the requests they can make, which is named throttling. If you hit the throttle limit, you will receive an error and have to wait before doing new requests.
Request was throttled. Expected available in X seconds.
API errors
Authentication credentials were not provided.
Solution: provide the Authorization header with a valid token.
Invalid token.
Solution: ensure that the token is valid by logging in to the interface. Click on Configuration and go the API section.
Request was throttled.
Solution: add a delay of 10 seconds after each request, to reduce the load on the API. For shell scripts use 'sleep 10'.
Systems
Query data
curl -sS -X GET https://portal.example.org/api/systems/ \
-H 'Accept: application/json; indent=4' \
-H 'Authorization: Token 0979b38de04ee537341f18bdb5eb6fcc2f7a6da8'
Filter data
Find all systems with a minimum risk score
/api/systems/?min_risk_score=10000
Just need a counter of the number of systems that have a score higher than 10.000? Filter it through jq and extract the counter.
cat results.json | jq '.count'
Filter by hostname or alias
/api/systems/?search=centos
Additional filtering
Want to reduce the data in the stored output? Apply additional filtering with the jq utility.
Example: Select particular fields, with colored output
cat results.json | jq --color-output '.results[] | [.id,.system_hostname,.system_risk_score]'
Example: Only return number of results
cat results.json | jq '.count'
Change one field
To make changes to a system, we need to specify it by its ID. To find the ID, use browsable API interface or use the value of id in the API output.
curl -sS -X PUT https://portal.example.org/api/systems/1234/ \
-F 'system_hostname_alias=mynewalias' \
-H 'Authorization: Token 0979b38de04ee537341f18bdb5eb6fcc2f7a6da8'
Need Help?