-{
- "name": "isNew",
- "value": {
- "type": "bool"
- }
-}
This article discusses the changes in the API between 19.07 and 19.03. It’s intended to help you port your code forward to the latest version of Twistlock. Note that we maintain a very large internal app that must be ported forward with every major release of Twistlock. We take the notes from our porting exercise, along with output from some custom diff tools, to identify and document critical breaking changes in the API.
In 19.07, the API for creating and updating users has changed.
In 19.03, there was a single POST endpoint for both creating and updating users.
To create a user, you would set isNew
in the request body to true
.
To updated an existing user, you would set isNew
to false
.
In 19.07, there is a dedicated POST endpoint for creating users, and a dedicated PUT endpoint for updating existing users.
The trusted images feature was updated in 19.07. Twistlock now automatically learns which images should be trusted and adds them to a model. The model can be augmented with user-defined rules that explicitly whitelist or blacklist specific registries, repositories, or images.
Here are the key changes.
In 19.03, there was no automatic learning. In 19.07, there is a 24 automatic learning period when Twistlock is first installed. Re-learning can be initiated at any time. Learning can be stopped at any time. Learning can be controlled with the following new endpoints:
GET /api/v1/trust/learn
POST /api/v1/trust/learn
The endpoints for declaring trust groups remains the same.
GET /api/v1/trust
POST /api/v1/trust
PUT /api/v1/trust/{id}
DELETE /api/v1/trust/{id}
The mechanism for enforcing trusted images has changed. In 19.03, you created a compliance policy with PUT /api/v1/compliance/container, setting compliance check 423 (Image is not trusted) to alert or block. By default, the effect was set to alert.
In 19.07, there is a dedicated policy for trusted images, which you manage with the /api/v1/policies/trust endpoint. A default rule alerts on all non-trusted images.
When retrieving the list of trusted images, a new response property called learning
indicates whether Twistlock added the image to the model, or whether an operator added it by rule.
New request parameter: learning
+{
+ "name": "learning",
+ "value": {
+ "type": "bool"
+ }
+}
As part of the new trusted images feature, there is a new metric that counts the number of trust audits.
New response: trustAudits
+{
+ "name": "trustAudits",
+ "value": {
+ "type": "int"
+ }
+}
Image scan reports get a new field to indicate whether they are considered trusted according to your policy (model + rules).
New query parameter: trustStatuses
+{
+ "name": "trustStatuses",
+ "array": true,
+ "value": {
+ "type": "string"
+ }
+}
Runtime rules for host apps have changed.
The mechanism for whitelisting and blacklisting capabilities has been enhanced to enable per-capability per-app resolution.
This mechanism is supported with a new serviceRules
object.
New request parameter: serviceRules
+{
+ "name": "serviceRules",
+ "array": true,
+ "value": {
+ "type": "shared.ServiceRule",
+ "fields": [
+ {
+ "name": "serviceName",
+ "value": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "capabilities",
+ "array": true,
+ "value": {
+ "type": "shared.CapabilityRule",
+ "fields": [
+ {
+ "name": "type",
+ "value": {
+ "type": "shared.CapabilityType",
+ "values": [
+ "",
+ "SYSTEM_LOGS",
+ "DOCKER",
+ "DOCKER_SOCKET",
+ "USERS_ADMIN",
+ "INSTALLER",
+ "KUBERNETES",
+ "OPENSHIFT",
+ "SSH",
+ "SHELL",
+ "NET",
+ "HOSTS_CONFIG",
+ "SERVICE_OPERATOR",
+ "GCLOUD",
+ "PRIVILEGED_PROCESSES",
+ "SECRETS_MANAGER"
+ ]
+ }
+ },
+ {
+ "name": "effect",
+ "value": {
+ "type": "shared.RuntimeRuleEffect",
+ "values": [
+ "block",
+ "prevent",
+ "alert",
+ "disable"
+ ]
+ }
+ }
+ ]
+ }
+ }
+ ]
+ }
+}
New request parameter: capabilitiesEffect
+{
+ "name": "capabilitiesEffect",
+ "value": {
+ "type": "shared.RuntimeRuleEffect",
+ "values": [
+ "block",
+ "prevent",
+ "alert",
+ "disable"
+ ]
+ }
+}
If you’re using the Twistlock API to configure which registries Twistlock should scan, update your scripts to use PUT /api/v1/settings/registry rather than POST /api/v1/settings/registry. The PUT endpoint in 19.07 works exactly the same way as the POST endpoint in 19.03. The new 19.07 POST endpoint lets you add a single registry at a time to the list of registries to scan, whereas the PUT endpoint completely overwrites the previous list with a new list.
As you’re updating your integration with /api/v1/settings/registry, consider taking advantage of 19.07’s enhanced capabilities for distributing registry scan jobs across multiple Defenders.
In 19.03, you needed to explicitly select a Defender to handle a registry scan by specifying hostname
(the host where Defender runs).
In 19.07, you can leave hostname
empty to specify Twistlock’s new auto-select algorithm, and then specify the number of Defenders to use to handle the job in scanners
.
By removing the dependency of Defender running on a specific host, you can make your scripts more robust.
New request parameter: scanners
+{
+ "name": "scanners",
+ "value": {
+ "type": "int"
+ }
+}
In 19.03, you needed to designate a Defender to scan serverless functions. In 19.07, Console handles serverless function scanning, so you no longer need to make the explicit designation. This change was made to improve scan performance.
Deprecated request parameter: serverlessScanner
-{
- "name": "serverlessScanner",
- "value": {
- "type": "bool"
- }
-}
The strings for some of the host forensic activities have changed.
Updated response: type
{
"name": "type",
"value":
{
"type": "shared.ActivityType",
"values":
[
- "App Restart",
+ "app restart",
- "App Install",
+ "app install",
- "App Modified",
+ "app modified",
- "Cron Modified",
+ "cron modified",
- "System Update",
+ "system update",
- "System Reboot",
+ "system reboot",
- "Source Modified",
+ "source modified",
- "Source Added",
+ "source added",
- "Iptables Changed",
+ "iptables changed",
- "Secret Modified",
+ "secret modified",
"login",
"sudo",
- "Accounts Modified",
+ "accounts modified",
- "Sensitive Files Modified",
+ "sensitive files modified",
"docker"
]
}
}