Using the Balabit Shell Control Box REST API

May 05, 2017


Table of Contents

1. Introduction
1.1. Message format
2. How to configure SCB using REST
3. How to configure SCB using REST — a sample transaction
4. Authenticate to the SCB REST API
5. Checking the transaction status
6. Open a transaction
7. Commit a transaction
8. Delete a transaction
9. Reviewing the changelog of a transaction
10. Application level error codes
11. Navigating the configuration of SCB
12. Modifying the configuration of SCB
12.1. Delete an object
12.2. Create a new object
12.3. Change an object
13. SCB resources reference
13.1. Retrieve basic firmware and host information
13.2. Channel policy
13.3. RDP channels
13.4. SSH channels
13.5. SSH host keys and certificates
13.6. Auditing connections
13.7. Searching in the connection database
13.8. Reporting
13.9. Reports
13.10. Built-in subchapters
13.11. Pre-defined reports
13.12. Content subchapters
13.13. Custom subchapters
13.14. Connection statistics subchapters
13.15. SSH connections
13.16. Global SSH options
13.17. SSH settings policies
13.18. SSH authentication policies
13.19. SSH connection policies
13.20. RDP connections
13.21. Configuring domain membership
13.22. Global RDP options
13.23. RDP settings policies
13.24. Telnet connections
13.25. Global Telnet options
13.26. HTTP connections
13.27. Global HTTP options
13.28. HTTP settings policies
13.29. ICA connections
13.30. Global ICA options
13.31. ICA settings policies
13.32. VNC connections
13.33. Global VNC options
13.34. Policies
13.35. Audit policies
13.36. Real-time content monitoring with Content Policies
13.37. Credential stores
13.38. LDAP servers
13.39. Signing CA policies
13.40. Ticketing policies
13.41. Time policy
13.42. Trusted Certificate Authorities
13.43. Local user databases
13.44. Usermapping policy
13.45. User lists
13.46. User management and access control
13.47. Authentication and user database settings
13.48. Privileges of usergroups
13.49. Manage users and usergroups locally on SCB
13.50. Manage usergroups locally on SCB
13.51. Manage users locally on SCB
13.52. Management options
13.53. Internal certificates
13.54. Disk fill-up prevention
13.55. Mail settings
13.56. Health monitoring
13.57. SNMP settings
13.58. SNMP traps
13.59. RPC API
13.60. Syslog server settings
13.61. Web interface
13.62. Network configuration options
13.63. DNS servers
13.64. Routing between interfaces
13.65. Naming options
13.66. Network addresses
13.67. Routing table
13.68. Local services of SCB
13.69. Local services — Web login for administrators
13.70. Local services — Web login for users
13.71. Local services — access for SNMP agents
13.72. Local services — enabling SSH access to the SCB host
13.73. Local services — configuring the indexer
13.74. Alerting
13.75. System alerts
13.76. Traffic alerts
13.77. Date & time
13.78. NTP servers
13.79. Timezone
13.80. Plug-ins
13.81. Authentication and authorization plug-ins
13.82. Credential store plug-ins
13.83. Ticketing plug-ins
13.84. Troubleshooting options
13.85. Passwords stored on SCB
13.86. Private keys stored on SCB
13.87. Certificates stored on SCB
Index

1. Introduction

Starting with Balabit Shell Control Box version 4 F2, certain parts and features of SCB can be configured using a RESTful API (Representational State Transfer Application Programming Interface). The REST server conforms to the Hypermedia as the Engine of Application State (HATEOAS).

The SCB REST API uses JSON over HTTPS. The REST server has a single entry point and all resources are available at paths (URLs) returned in the response for a request sent to the entry point. The only path that is guaranteed not to change is /api/authentication. Every other path should be reached by navigating the links returned.

The SCB REST API allows you to create, read, update and delete (CRUD) the configuration resources of SCB.

In this tutorial, all examples are displayed with curl, but you can use any other HTTP client. In the examples it is assumed that the REST server is listening on the default HTTP port of SCB (443).

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

1.1. Message format

Response headers

The following headers are included in every response. Other headers are specific to responses to specific requests.

  • Allow: The SCB REST API allows you to create, read, update and delete (CRUD) the configuration resources of SCB. The value of the header lists the available actions for the resource or object.

  • Content-Language: The language of the response. Currently only English (en) is supported.

  • Content-Type: All messages are JavaScript Object Notation (JSON) objects. The SCB REST server sends all REST API responses in application/json format.

Response body

The response body contains JSON objects. These objects always contains a meta field with links to different parts of the REST service. The keys in the response, which are not resource identifiers, start with the underscore (_) charater, for example, meta, key, and error. In most cases, the following entries can be found in the meta object.

Element Type Description Notes
meta     Top level element, contains links to different parts of the REST service  
  changes string Path to the transaction changelog. This value is always /api/transaction/changes. For details, see Section 9, Reviewing the changelog of a transaction.
  href string (relative path) Path of the resource that returned the response. When creating a new object, this is the URL of the created object. For example, /api/authentication
  parent string (relative path)    
  next string (relative path) Path of the next sibling of the current resource For example, /api/configuration
  prev string (relative path) Path of the previous sibling of the current resource  
  first string (relative path) Path of the first sibling of the current resource  
  last string (relative path) Path of the last sibling of the current resource  
  transaction string (/api/transaction) The endpoint of the transaction log For details on how SCB handles transactions, see Procedure 2, How to configure SCB using REST.
items   list of JSON objects List of endpoints (objects) available from the current endpoint.

Each object in the list contains a key and a meta object for the endpoint. For example:

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-rsa-10.10.100.1:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22"
      }
    },
    {
      "key": "ssh-rsa-10.10.20.35:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22"
      }
    },
    {
      "key": "ssh-rsa-10.40.0.28:22",
      "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.40.0.28:22"
      }
    }
  ]
}

For example:

{
  "meta": {
    "href": "/api/authentication",
    "next": "/api/configuration"
  }
}

Error responses

All error responses are JSON objects with the following keys.

  • meta: JSON object containing navigation links. For details, see Section 1.1, Message format.

  • error: JSON object containing information about the error.

Element Type Description Notes
error     Top level element, contains links to different parts of the REST service  
  type string The type of the error that occurred. For example, AuthenticationFailure, or NodeNotFound. For a complete list, see Section 10, Application level error codes.
  message string A text message that describes the error. For example, Unable to locate the requested path.
  details JSON object List of additional information about the error (for example the path where the error occurred).

For example:

"details": {
  "path": "no/such/path"
}

The following is a complete error response.

{
  "error": {
    "type": "NodeNotFound",
    "message": "Unable to locate the requested path",
    "details": {
      "path": "no/such/path"
    }
  },
  "meta": {
    "href": "/api/configuration/no/such/path",
    "parent": "/api/configuration"
  }
}

2. Procedure – How to configure SCB using REST

The SCB REST server uses a transactional model for configuration management. Modifying the configuration has the following main steps. The steps are explained in detail in later sections of the tutorial. You find a simple transaction with detailed requests and responses in Procedure 3, How to configure SCB using REST — a sample transaction.

  1. Authenticate on the SCB REST server, and receive a session_id. For details, see Section 4, Authenticate to the SCB REST API.

  2. Open a transaction. This transaction will collect the changes and modifications you do, compared to the SCB configuration that is active at the time of opening the transaction. It is similar to a shopping cart, where your modifications are the items in the cart. For details, see Section 6, Open a transaction.

    Note that opening a transaction locks the configuration of SCB similarly to accessing SCB from the web interface. For details, see Section 4.2.2, Multiple web users and locking in The Balabit Shell Control Box 4 F3 Administrator Guide.

  3. Change and modify the configuration of SCB as you need. Note that to modify the configuration, you must have the required privileges. For details, see Section 5.7, Managing user rights and usergroups in The Balabit Shell Control Box 4 F3 Administrator Guide. For details on navigating and modifying the configuration of SCB, see Section 11, Navigating the configuration of SCB and Section 12, Modifying the configuration of SCB

  4. Commit your transaction to submit your changes to SCB (this is similar to clicking Checkout in a web shop). For details, see Section 7, Commit a transaction.

    If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

    If you do not want to commit your changes, and would like to restart with the original configuration of SCB, you can simply delete the transaction. This is similar to the rollback transaction in SQL. If your session times out, your transaction is deleted automatically. For details, see Section 8, Delete a transaction.

  5. SCB checks and validates the changes in your transaction. If other users have changed the configuration of SCB since you opened the transaction, SCB tries to merge your changes to the current configuration.

  6. If your changes are valid, SCB applies them and you have successfully changed the configuration of SCB. Otherwise, the REST server returns an error response.

3. Procedure – How to configure SCB using REST — a sample transaction

This procedure shows a sample transaction with detailed requests and responses. For details on the transaction model, see Procedure 2, How to configure SCB using REST.

  1. Authenticate on the SCB REST server, and receive a session_id.

    curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/authentication",
        "next": "/api",
        "transaction": "/api/transaction"
      }
    }
    --- END RESPONSE BODY ---
  2. Open a transaction.

    curl --data "" --cookie session_id=<session_cookie> --insecure -X POST https://<IP-address-of-SCB>/api/transaction
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/transaction",
        "parent": "/api"
      }
    }
    --- END RESPONSE BODY ---
  3. Retrieve a resource. The following example shows the resource corresponding to the AAA > Settings page of the SCB web interface.

    curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration/aaa/settings
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "key": "settings",
      "meta": {
        "first": "/api/configuration/aaa/settings",
        "href": "/api/configuration/aaa/settings",
        "last": "/api/configuration/aaa/settings",
        "next": null,
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
      },
      "settings": {
        "backend": {
          "cracklib_enabled": false,
          "expiration_days": 0,
          "minimum_password_strength": "good",
          "remember_previous_passwords": 10,
          "selection": "local"
        },
        "method": {
          "selection": "passwd"
        },
        "require_commitlog": false
      }
    }
    --- END RESPONSE BODY ---
  4. Change and modify the configuration of SCB as you need. The following example configures SCB to check the password strength of the passwords for users of the SCB web interface.

    # Body of the PUT request. You can read it from a file, for example, body.json
    {
      "backend": {
    	"cracklib_enabled": true,
    	"expiration_days": 0,
    	"minimum_password_strength": "good",
    	"remember_previous_passwords": 10,
    	"selection": "local"
      },
      "method": {
    	"selection": "passwd"
      },
      "require_commitlog": false
      }
    # Command to use
    curl -d @body.json --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration/aaa/settings
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "first": "/api/configuration/aaa/settings",
        "href": "/api/configuration/aaa/settings",
        "last": "/api/configuration/aaa/settings",
        "next": null,
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
      }
    }
    --- END RESPONSE BODY ---
  5. Commit your transaction to submit your changes to SCB.

    curl -d '{"status": "commit","message": "My commit message"}' --cookie session_id=<session_cookie> --insecure -X PUT https://<IP-address-of-SCB>/api/transaction
    
    Response status: 200
    --- BEGIN RESPONSE BODY ---
    {
      "meta": {
        "href": "/api/transaction",
        "parent": "/api"
      }
    }
    --- END RESPONSE BODY ---

    If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

  6. If your changes are valid, SCB applies them and you have successfully changed the configuration of SCB. Otherwise, the REST server returns an error response.

4. Authenticate to the SCB REST API

Prerequisites: 

  • You can access the REST server on the same IP address and port that you use to access the SCB web interface. Note that management (administrator) access must be enabled on the interface. For details on configuring management access, see Procedure 4.3.1, Configuring user and administrator login addresses in The Balabit Shell Control Box 4 F3 Administrator Guide.

  • The user accessing the SCB REST API must have the REST server privilege. For details, see Procedure 5.7.1, Modifying group privileges in The Balabit Shell Control Box 4 F3 Administrator Guide. Note that the built-in api usergroup does not have this privilege by default, it is used to access the SOAP RPC API of SCB.

The authentication procedure: 

  1. To authenticate on the SCB REST server, send an HTTP GET request using the basic HTTP authentication method, including your username and password to the /api/authentication resource.

  2. If the authentication is successful, the server returns the 200 status code, and a meta object in the response body. Also, the HTTP headers of the response includes an HTTP cookie named session_id. This cookie is used to identify the client in every subsequent HTTP request.

  3. For every subsequent request, include the session_id header with the value of the received session ID. For example:

    session_id 087658d7e30cdc2552b015dd761b6f7ccb25bbd5
  4. The authenticated session times out after 20 minutes of inactivity.

URL

GET https:<IP-address-of-SCB>/api/authentication

Headers

Header name Description Required Values
Authorization Contains the username and password of the user Required The string Basic followed by the username:password encoded using the RFC2045-MIME. For example, Basic YWRtaW46YQ==

Sample request

Example 1. Authenticate to the SCB REST server using curl

The following command authenticates on SCB using the curl HTTP client. The --insecure option used in the example is used to bypass verifying the certificate of SCB. (Alternatively, you can use the --cacert option or the CURL_CA_BUNDLE environment variable to specify the Certificate Authority to verify the certificate of SCB. For details, see the curl man page).

When using the REST API in production environments, make sure to download the CA certificate of SCB from Basic Settings > Management > SSL certificate > CA X.509 certificate, and validate the certificate of SCB using this CA certificate, or with the CA certificate you used to sign the Server X.509 certificate of SCB.

curl --basic --digest --user <username>:<password> --cookie-jar cookies --insecure https://<SCB-IP-address>/api/authentication

The cookie containing the session ID is also received (you can display it for example with the tail -l cookies command).

localhost  FALSE  /  FALSE  1395325830  session_id  600dc0ffeec0ffeec0ffeec0ffeec0ffeec0ffee

The following command retrieves the configuration of SCB, using the session ID received during the authentication.

curl --cookie session_id=<session_cookie> --insecure https://<IP-address-of-SCB>/api/configuration

Response

The following is a sample response received if the authentication is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
     "href": "/api/authentication",
     "next": "/api",
     "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Successful authentication
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the GET method for authentication.

5. Checking the transaction status

Before changing anything in the configuration of SCB, you must POST a request to open a transaction.

URL

GET https:<IP-address-of-SCB>/api/transaction/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command retrieves the transaction status of SCB, using the session ID received during the authentication.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "key": "transaction",
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "transaction": {
    "status": "closed"
  }
}
Element Type Description
transaction     Top level element, contains the details of the current transaction
  status string The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Transaction status has been retrieved successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.

6. Open a transaction

Before changing anything in the configuration of SCB, you must POST a request to open a transaction. For details about the transaction model of SCB see Procedure 2, How to configure SCB using REST.

Note that opening a transaction locks the configuration of SCB similarly to accessing SCB from the web interface. For details, see Section 4.2.2, Multiple web users and locking in The Balabit Shell Control Box 4 F3 Administrator Guide.

URL

POST https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

POST body

Note that you must send a body (which can be empty) in this POST request, or a Content-Length: 0 header. Otherwise the SCB REST server returns a 411 - Length Required error.

Sample request

The following command opens a new transaction on SCB, using the session ID received during the authentication.

curl -X POST --data "" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

After opening a transaction successfully, the transaction status changes to open.

{
    "body": {
        "status": "open"
    },
    "key": "transaction",
    "meta": {
        "changes": "/api/transaction/changes",
        "href": "/api/transaction",
        "parent": "/api"
    }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Transaction opened successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the POST method to open a transaction.
411 UnsupportedMethod You must send a body (which can be empty) in this POST request, otherwise the SCB REST server returns a 411 - Length Required error.

7. Commit a transaction

To submit your changes to SCB, you have to commit the transaction by using a PUT request with a JSON object. For details about the transaction model of SCB see Procedure 2, How to configure SCB using REST.

URL

PUT https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

PUT body

The PUT request must include the following JSON object in its body.

{
  "status": "commit"
}

If the AAA > Settings > Accounting settings > Require commit log option is selected in the SCB web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the SCB web interface. Note that on the AAA > Accounting page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

{
  "status": "commit",
  "message": "My commit message"
}

Sample request

The following command commits a transaction to SCB, using the session ID received during the authentication.

curl -d '{"status": "commit","message": "My commit message"}' --cookie session_id=<session_cookie> -X PUT https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if committing the transaction is successful. For details of the meta object, see Section 1.1, Message format.

After a successful commit, the transaction status changes to closed. To make other changes, you have to open a new transaction.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "key": "transaction",
  "transaction": {
    "status": "closed"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Transaction committed successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the PUT method to commit a transaction.

8. Delete a transaction

To delete your changes, you have to delete the transaction. This is similar to the rollback transaction in SQL. For details about the transaction model of SCB see Procedure 2, How to configure SCB using REST. Deleting the transaction also deletes the configuration lock of SCB.

URL

DELETE https:<IP-address-of-SCB>/api/transaction

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command deletes a transaction, reverting the configuration to the state it was when the transaction was opened, or to the current configuration available on SCB (if it another user has modified it since you opened the transaction).

curl --cookie session_id=<session_cookie> -X DELETE https://<IP-address-of-SCB>/api/transaction

Response

The following is a sample response received if deleting the transaction is successful. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Transaction deleted successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the DELETE method to reset a transaction.

9. Reviewing the changelog of a transaction

To review your changes, retrieve the changelog of the transaction. For details about the transaction model of SCB see Procedure 2, How to configure SCB using REST.

URL

GET https:<IP-address-of-SCB>/api/transaction/changes

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command retrieves the changelog of the transaction.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/transaction/changes

Response

The response contains the list of changes performed in the transaction, as list of JSON objects. Every change has a type and a path, other elements depend on the type of the transaction. For example, when you delete an object, the changelog includes the deleted object in the old_value field.

Element Type Description
new_order list The new order of a list after the change. This field is available for reorder transactions.
new_value string or JSON object The value of the object after the change. For example, the new value of a parameter.
old_order string or JSON object The order of a list before the change. This field is available for reorder transactions.
old_value string or JSON object The value of the object before the change. For example, the value of a deleted object.
path string Path of the changed endpoint or object.
type string The type of the change. One of: create, delete, reorder, replace

The following is a sample response received if the changelog is empty.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": []
}

The following is a sample changelog received after deleting a Channel policy.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": [
    {
      "old_value": {
        "name": "deny",
        "rules": []
      },
      "path": "/api/configuration/ssh/channel_policies/94615110156697e93121f3",
      "type": "delete"
    }
  ]
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Transaction changelog has been retrieved successfully
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the GET method to retrieve the changelog a transaction.

10. Application level error codes

In addition to the standard HTTP status codes, in certain cases, the SCB REST server provides additional information in the response about the error. The following table contains a brief description of such errors. For more details, see the error object in the response body.

Code Description Notes
400 InvalidRequestBody The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value.
400 ConfigTreeNotAvailable An error occurred while preparing the configuration tree for the REST API.
400 SyntacticError A value to be set is not accepted syntactically. Thedetails section contains the path that was found to be invalid.
400 InvalidPath The path provided by the client contains a syntax error. Path components are restricted to contain only lowercase alphanumeric characters, the dash (-) and the underscore (_) character. The details section contains the path that was attempted to be accessed, but could not be retrieved.
400 SemanticError The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
401 Unauthorized The requested resource cannot be retrieved because the client is not authorized to access it. The detailssection contains the path that was attempted to be accessed, but could not be retrieved.
404 NodeNotFound The requested endpoint does not exist in the configuration. The details section contains the path that you tried to access, but could not be retrieved.
404 NodeNotAvailable The requested endpoint exists in the configuration, however, it is not available directly. The details section contains the path that you tried to access, but could not be retrieved.
405 UnsupportedMethod The requested resource does not support the given method. The details section contains the attempted method.
405 PutNotAllowed Replacing the specified path is not supported.
405 MethodNotAllowed An attempt was made to change a configuration subtree in an unsupported way.
405 PostNotAllowed Posting to the specified path is not supported.
405 GetNotAllowed Querying the specified path is not supported.
405 DeleteNotAllowed Deleting the specified path is not supported.
409 MidAirCollisionSemanticError This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would interfere semantically with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 WebGuiOrRpcApiConfigInProgress Opening a new transaction is not allowed while another user is modifying configuration through other interfaces than the REST API. (E.g. web GUI, console, etc.)
409 MidAirCollision This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would overwrite or interfere with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 NoTransaction An attempt was made to change the configuration when no transaction was open.
409 DoubleTransaction This error is returned when the client attempts to open a transaction while another transaction of that client is already started.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

500 CommitMessageMissing This error is returned when a commit message is required for committing a transaction, but it was not provided in the commit request.
500 TransactionCommitError Unexpected internal errors during committing a transaction are interpreted as TransactionCommitError.
500 AuthorizationError The request could not be authorized due to an unexpected internal error.

11. Navigating the configuration of SCB

The main starting point of navigating the SCB configuration using REST is the https:<IP-address-of-SCB>/api/configuration endpoint. If you query this endpoint, the response contains a list of other endpoints that you can follow to list the various resources of SCB, or to list the objects of a specific resource. For example, https:<IP-address-of-SCB>/api/configuration/rdp lists resources related to controlling the Remote Desktop (RDP) protocol, while https:<IP-address-of-SCB>/api/configuration/rdp/channel_policies lists the available RDP Channel Policies.

Note that when you want to create an object that references another object (for example, a Channel Policy that uses a Content Policy), then the referenced object (in this case, the Content Policy) must already exist. For details, see Section 12.2, Create a new object.

To modify or delete an object, you need the ID of the object. For details, see Section 12.3, Change an object and Section 12.1, Delete an object.

The following is a sample command to query the https:<IP-address-of-SCB>/api/configuration endpoint, and a sample response.

curl --cookie session_id=<session_cookie> https:<IP-address-of-SCB>/api/configuration

Response status: 200
--- BEGIN RESPONSE BODY ---
{
  "meta": {
    "first": "/api/configuration",
    "href": "/api/configuration",
    "last": "/api/configuration",
    "next": null,
    "parent": null,
    "previous": null,
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "aaa",
      "meta": {
        "href": "/api/configuration/aaa"
      }
    },
    {
      "key": "alerting",
      "meta": {
        "href": "/api/configuration/alerting"
      }
    },
    {
      "key": "datetime",
      "meta": {
        "href": "/api/configuration/datetime"
      }
    },
    {
      "key": "http",
      "meta": {
        "href": "/api/configuration/http"
      }
    },
    {
      "key": "ica",
      "meta": {
        "href": "/api/configuration/ica"
      }
    },
    {
      "key": "local_services",
      "meta": {
        "href": "/api/configuration/local_services"
      }
    },
    {
      "key": "management",
      "meta": {
        "href": "/api/configuration/management"
      }
    },
    {
      "key": "network",
      "meta": {
        "href": "/api/configuration/network"
      }
    },
    {
      "key": "passwords",
      "meta": {
        "href": "/api/configuration/passwords"
      }
    },
    {
      "key": "plugins",
      "meta": {
        "href": "/api/configuration/plugins"
      }
    },
    {
      "key": "policies",
      "meta": {
        "href": "/api/configuration/policies"
      }
    },
    {
      "key": "private_keys",
      "meta": {
        "href": "/api/configuration/private_keys"
      }
    },
    {
      "key": "rdp",
      "meta": {
        "href": "/api/configuration/rdp"
      }
    },
    {
      "key": "reporting",
      "meta": {
        "href": "/api/configuration/reporting"
      }
    },
    {
      "key": "ssh",
      "meta": {
        "href": "/api/configuration/ssh"
      }
    },
    {
      "key": "telnet",
      "meta": {
        "href": "/api/configuration/telnet"
      }
    },
    {
      "key": "troubleshooting",
      "meta": {
        "href": "/api/configuration/troubleshooting"
      }
    },
    {
      "key": "vnc",
      "meta": {
        "href": "/api/configuration/vnc"
      }
    },
    {
      "key": "x509",
      "meta": {
        "href": "/api/configuration/x509"
      }
    }
  ]
}
--- END RESPONSE BODY ---

12. Modifying the configuration of SCB

12.1. Delete an object

To delete a configuration object (for example, a policy), use a DELETE request with the ID of the object as the key.

  • You cannot delete policies or objects that are used in other policies (for example, you cannot delete a Time policy that is used in a Channel policy).

  • You cannot delete built-in policies that are available on SCB by default.

  • You must commit your changes to take effect. For details, see Section 7, Commit a transaction.

URL

DELETE https:<IP-address-of-SCB>/api/configuration/<endpoint>/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command deletes an RDP Channel policy.

curl --cookie session_id=<session_cookie> -X DELETE -https:<IP-address-of-SCB>/api/configuration/rdp/channel_policies/<object-id>

Response

The following is a sample response received.

{
  "meta": {
    "first": "/api/configuration/rdp/channel_policies/-20100",
    "href": "/api/configuration/rdp/channel_policies/<id-of-the-deleted-object>",
    "last": "/api/configuration/rdp/channel_policies/<id-of-the-deleted-object>",
    "next": null,
    "parent": "/api/configuration/rdp/channel_policies",
    "previous": "/api/configuration/rdp/channel_policies/655555",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK The resource was successfully deleted
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 6, Open a transaction.

12.2. Create a new object

To create a new object (for example, a new policy), you have to complete the following steps.

  1. Authenticate and open a transaction.

  2. Post the new object as a JSON object to the appropriate resource URL.

  3. If successful, the REST server creates a ID for the new object, and returns it in the key field of the response.

  4. Commit the transaction.

Note that you cannot simply use the JSON from the response of a similar object. If the object contains references to other resources (for example, a Channel policy references a Time policy), then the JSON object contains an embedded _meta object. To get a valid JSON that you can use, you have to replace this embedded object with the ID (_key) of the referenced object. For example, the following is a reference to a Time policy:

"time_policy": {
		"_key": "-100",
		"_meta": {
			"href": "/api/configuration/policies/time_policies/-100"
		}
	}

In a POST or PUT request, you have to change it to the following:

"time_policy": "-100",

URL

POST https:<IP-address-of-SCB>/api/configuration/<path-to-the-parent-resource>

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command creates a new RDP Channel policy. The data content of the request is read from the file body.json

curl -H "Content-Type: application/json" -d @body.json --cookie session_id=1aca4793549c6f22aecd98bc1047d1bf32dd76ef -X POST https://<object-id>/api/configuration/rdp/channel_policies/

For a simple RDP Channel policy that uses the default settings and allows only the Drawing channel, the JSON object is the following.

{
  "name": "drawing-only",
  "rules": [
    {
      "actions": {
        "audit": true,
        "content_policy": null,
        "four_eyes": false,
        "ids": false
      },
      "allowed_for": {
        "clients": [],
        "gateway_groups": [],
        "remote_groups": [],
        "servers": [],
        "time_policy": "-100"
      },
      "channel": "#drawing"
    }
  ]
}

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "key": "f79bcc85-bb8b-4fa5-a141-eb4cf2b6ef33",
  "meta": {
    "href": "/api/configuration/rdp/channel_policies/f79bcc85-bb8b-4fa5-a141-eb4cf2b6ef33",
    "parent": "/api/configuration/rdp/channel_policies",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
201 Created The new resource was successfully created
400 Bad Request The request body format is invalid. The data is not a properly formated JSON object.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 6, Open a transaction.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

12.3. Change an object

To modify or update an object, use a PUT request on the object you want to change. In the body of the request, you have to upload the entire object, not only the parameter that you want to change.

Note that you cannot simply use the JSON from the response of a similar object. If the object contains references to other resources (for example, a Channel policy references a Time policy), then the JSON object contains an embedded _meta object. To get a valid JSON that you can use, you have to replace this embedded object with the ID (_key) of the referenced object. For example, the following is a reference to a Time policy:

"time_policy": {
		"_key": "-100",
		"_meta": {
			"href": "/api/configuration/policies/time_policies/-100"
		}
	}

In a POST or PUT request, you have to change it to the following:

"time_policy": "-100",

URL

PUT https:<IP-address-of-SCB>/api/configuration/<path-to-the-parent-resource>/<id-of-the-object-to-modify>

Headers

Header name Description Required Values
Content-Type Specifies the type of the data sent. SCB uses the JSON format. Required application/json
session_id Contains authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command updates an RDP Channel policy. The data content of the request is read from the file body.json

curl -H "Content-Type: application/json" -d @body.json --cookie session_id=07640a0bf14cdd361d8f5ae2b0b482a786c7a604 -X PUT https://10.40.255.17/api/configuration/rdp/channe_policies/<id-of-the-object-to-modify>

For a simple RDP Channel policy that uses the default settings and allows only the Drawing channel, the JSON object is the following.

{
  "name": "drawing-only",
  "rules": [
    {
      "actions": {
        "audit": true,
        "content_policy": null,
        "four_eyes": false,
        "ids": false
      },
      "allowed_for": {
        "clients": [],
        "gateway_groups": [],
        "remote_groups": [],
        "servers": [],
        "time_policy": "-100"
      },
      "channel": "#drawing"
    }
  ]
}

Response

The following is a sample response received. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/rdp/channel_policies/-20100",
    "href": "/api/configuration/rdp/channel_policies/<id-of-the-modified-object>",
    "last": "/api/configuration/rdp/channel_policies/<id-of-the-modified-object>",
    "next": null,
    "parent": "/api/configuration/rdp/channel_policies",
    "previous": "/api/configuration/rdp/channel_policies/655555",
    "transaction": "/api/transaction"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 Bad Request The request body format is invalid. The data is not a properly formated JSON object.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
409 Conflict No open Transaction is available. Open a transaction before using this request. For details, see Section 6, Open a transaction.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

13. SCB resources reference

13.1. Retrieve basic firmware and host information

The /api/info endpoint contains generic information about the SCB host. Note that part of this information is available without authentication.

URL

GET https://<IP-address-of-SCB>/api/info

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command displays the information about SCB that is available without authentication.

curl https://10.40.255.171/api/info

The following command displays the information about SCB that is available for authenticated users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/info

Response

The following is a sample response received by an anonymous user. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "domainname": "balabit",
        "hostname": "scbwriter",
        "nickname": null,
        "support_link": "mailto:scb-administrator@example.com"
    },
    "key": "about_info",
    "meta": {
        "href": "/api/info",
        "parent": "/api"
    }
}

The following is a sample response received by an authenticated user.

{
    "body": {
        "build_date": "2016-09-23",
        "domainname": "balabit",
        "firmware_version": "4.3.2a",
        "hostname": "scbwriter",
        "nickname": null,
        "support_link": "mailto:scb-administrator@example.com",
        "version": "4 F3"
    },
    "key": "about_info",
    "meta": {
        "href": "/api/info",
        "parent": "/api"
    }
}
Element Description      
build_date Build date of the SCB firmware. This element is included in the response only for authenticated users.      
domainname Name of the domain used on the network. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 13.65, Naming options.      
hostname Name of the machine running SCB. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 13.65, Naming options.      
nickname The nickname of the SCB host. Use it to distinguish the devices. It is displayed in the core and boot login shells. You can configure this parameter on the /api/configuration/network/naming endpoint. For details, see Section 13.65, Naming options.      
support_link The e-mail address of the SCB administrator, as set in the admin_address parameter of the /api/configuration/management/email endpoint. For details, see Section 13.55, Mail settings.      
firmware_version The version number of the firmware running on SCB, for example, 4.3.2a. This element is included in the response only for authenticated users.      
firmware_version The version number of the firmware running on SCB, for example, 4.3.2a. This element is included in the response only for authenticated users.      
version The name of the major release running on SCB, for example, 4 F3. This element is included in the response only for authenticated users.      

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.

13.2. Channel policy

The channel policy lists the channels (for example, terminal session and SCP in SSH; Drawing, Clipboard in RDP) that can be used in a connection. The channel policy can further restrict access to each channel based on the IP address of the client or the server, a user list, user group, or a time policy. For example, all clients may access the servers defined in a connection via SSH terminal, but the channel policy may restrict SCP access only to a single client. The policies set in the channel policy are checked when the user attempts to open a particular channel type in the connection.

Channel policies are protocol specific. To list the available Channel policies for a protocol, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/<http|ica|rdp|ssh|telnet|vnc>/channel_policies

The following sections detail the properties of Channel policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/<http|ica|rdp|ssh|telnet|vnc>/channel_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific RDP Channel policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/<rdp>/channel_policies/<object-id>

Response

The following is a sample response received, showing the properties of Channel policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "name": "terminal-only",
    "rules": [
      {
        "actions": {
          "audit": true,
          "content_policy": null,
          "four_eyes": false,
          "ids": false
        },
        "allowed_for": {
          "clients": [],
          "gateway_groups": [],
          "remote_groups": [],
          "servers": [],
          "time_policy": {
            "key": "-100",
            "meta": {
              "href": "/api/configuration/policies/time_policies/-100"
            }
          }
        },
        "channel": "#drawing"
      },
      {
        "actions": {
          "audit": true,
          "four_eyes": false,
          "ids": false
        },
        "allowed_for": {
          "clients": [],
          "gateway_groups": [],
          "remote_groups": [],
          "servers": [],
          "time_policy": {
            "key": "-100",
            "meta": {
              "href": "/api/configuration/policies/time_policies/-100"
            }
          }
        },
        "channel": "cliprdr"
      }
    ]
  }
}
Element Type Description
name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
rules   list of JSON objects Top level element, contains the configuration properties of the object.
  actions JSON object The actions that SCB performs for the channel, for example, recording the traffic into an audit trail.
  allowed_for JSON object Specifies the access control rules of the channel, for example, permitted target IP addresses or usergroups.
  channel string

The type of the channel. Note that channels are protocol specific, and different type of channels can have different parameters.

For example:

"channel": "#drawing",
Element Type Description
actions   JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  audit boolean

Set to true to record the activities of the channel into audit trails. Possible values: true or false

  content_policy JSON object

Specifies the Content policy to use in the channel, otherwise its value is null (which is the default). For details on Content policies, see Section 13.36, Real-time content monitoring with Content Policies For example:

"content_policy": {
"key": "<object-id>",
}
  four_eyes boolean

Set to true to require four-eyes authorization to access the channel. For details, see Section 18.3, Configuring 4-eyes authorization in The Balabit Shell Control Box 4 F3 Administrator Guide. Possible values: true or false

  ids boolean

Set to true to forward the connection to an Intrusion Detection System (IDS). Note that this feature is deprecated and is going to be removed in SCB version 4 F3 and later. Possible values: true or false

Element Type Description
allowed_for   JSON object Specifies the access control rules of the channel.
  clients list

To restrict the availability of the channel only to certain clients, list the IP address or network of the clients allowed to use this the channel. For IPv6 addresses, use the canonized format of the address. For example:

"clients": [
  "192.168.1.1/24",
  "2001:db8:85a3::8a2e:0:0/32"
]
  gateway_groups list

You can control channel access during gateway authentication with blacklists or whitelists of user groups. You can use local user lists on SCB, or LDAP groups.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

For example:

"gateway_groups": ["group1", "group2"],

To configure local user lists, see Section 13.45, User lists.

  remote_groups list

You can control channel access during authentication to the remote server with blacklists or whitelists of user groups. You can use local user lists on SCB, or LDAP groups.

For example:

"remote_groups": ["group1", "group2"],

To configure local user lists, see Section 13.45, User lists.

  servers list

To restrict the availability of the channel only to certain servers, list the IP address or network of the servers that your clients are allowed to access using this the channel. For IPv6 addresses, use the canonized format of the address. For example:

"servers": [
  "192.168.1.1/24",
  "2001:db8:85a3::8a2e:0:0/32"
]
  time_policy JSON object

Specifies the Time policy to use in the channel. If you do not want to restrict access, use the default 7x24 policy-100. For details on Time policies, see Section 13.41, Time policy. For example:

"time_policy": {
  "key": "-100",
}

13.3. RDP channels

The available RDP channel types and their functionalities are described below.

Channel Special options Description
#drawing Yes

Drawing: Enables access to the server's graphical desktop (screen). This channel must be enabled for RDP to work.

Channel-specific actions:

  • content_policy reference: The ID of the Content policy to apply to the connection.

For example:

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}
cliprdr None Clipboard: Enable access to the server's clipboard: the clipboard of the remote desktop can be pasted into local applications (and vice-versa). Note that SCB can audit the clipboard channel, but cannot search or display its contents.
rdpdr Yes

Redirects: Enables access to every device redirections available in RDP, like file-sharing, printer sharing, device (for example CD-ROM) sharing, and so on. To enable only a specific type of redirection, use the specific channels instead (for example, rdpdr-serial for serial device redirection).

Channel-specific actions:

  • log_transfer_to_db (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (true|false): Send the file operations into the system log

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpsnd None

Sound: Enable access to the sound device of the server.

customs Yes

Custom: Applications can open custom channels to the clients connecting remotely to the server. Enabling the Custom channel allows the clients to access all of these custom channels. To permit only specific channels, list the unique names of the channels into the customs field.

For example, to monitor RemoteApp connections, you need to configure custom channels. For more information, see Procedure 10.11, Configuring RemoteApps in The Balabit Shell Control Box 4 F3 Administrator Guide.

Channel-specific access control rules:

  • customs (list): To permit only specific custom channels, list the unique name of the channels in this field. Leave it empty to permit access to every custom channel available.

seamrdp None Seamless: Enable seamless channels that run a single application on the RDP server, instead of accessing the entire desktop.
drdynvc Yes

Dynamic virtual channel: Enable the server to open channels back to the client dynamically. Enabling this channel allows access to all of such dynamic channels. To restrict which dynamic channels are permitted, list the unique names of the channels into the drdynvcs field.

Channel-specific access control rules:

  • drdynvcs (list): To restrict which dynamic channels are permitted, list the unique names of the channels in this field. Leave it empty to permit access to every dynamic channel available.

rdpdr-serial Yes

Serial redirect: Enables access to serial-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-parallel Yes

Parallel redirect: Enables access to parallel-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-printer Yes

Printer redirect: Enables access to printer-port redirections. To restrict access to specific redirections, list the unique names of the channels in the devices field.

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-disk Yes

Disk redirect: Enables access to shared disk drives. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example:

"devices": [
  "C:"
]

Channel-specific actions:

  • log_transfer_to_db (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (true|false): Send the file operations into the system log

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

rdpdr-scard Yes

SCard redirect:Enables access to shared SCard devices. To restrict access to specific redirections, list the unique names of the channels in the devices field, for example:

Channel-specific access control rules:

  • devices (list): To permit only specific redirections, list the unique name of the redirection in this field. Leave it empty to permit access to every redirection available.

13.4. SSH channels

The available SSH channel types and their functionalities are described below.

Channel Special options Description
auth-agent None Agent: Forwards the SSH authentication agent from the client to the server.
x11 Yes

X11 Forward: Forwards the graphical X-server session from the server to the client. List the address of the client in the networks field to permit X11-forwarding only to the specified clients. Specify IP addresses or networks (in IP address/Prefix format). For example:

"networks": [
  {
    "selection": "address",
    "value": "192.168.1.1"
  },
  {
    "selection": "address",
    "value": "192.168.1.2"
  }
]
Note

Certain client applications send the Target address as a hostname, while others as an IP address. If you are using a mix of different client applications, you might have to duplicate the channel rules and create IP-address and hostname versions of the same rule.

Channel-specific access control rules:

  • networks (list): To X11-forwarding only to specific clients, list the IP addresses or networks of the clients in this field. Leave it empty to permit access to every client. For details, see Section Limiting addresses in port forwarding.

local-forwards Yes

Local Forward: Forwards traffic arriving to a local port of the client to a remote host. To enable forwarding only between selected hosts, use the local_forwards field. If the local_forwards field is empty, local forwarding is enabled without restriction, the client may forward any traffic to the remote host.

For example:

"local_forwards": [
  {
    "host_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "host_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
]

Channel-specific access control rules:

  • local_forwards (list): To permit local forwarding only to specific addresses, list the addresses in this field. Leave it empty to enable without restriction. In this case the client may forward any traffic to the remote host.

    Enter the source of the forwarded traffic into the originator_address field, the target of the traffic into the host_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the local host that sends data to the remote host), and not the SSH server or the client. For example, to enable forwarding from the 192.168.20.20 host to the remote host 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the host_address field. For details, see Section Limiting addresses in port forwarding.

remote-forwards Yes

Remote Forward: Forwards traffic arriving a remote port of the server to the client. To enable forwarding only between selected hosts, enter their IP addresses into the remote_forwards field. If the remote_forwards field is empty, remote forwarding is enabled without restriction, the SSH server may forward any traffic to the client.

For example:

"remote_forwards": [
  {
    "connected_address": {
      "selection": "address",
      "value": "192.168.100.1"
    },
    "connected_port": 5555,
    "originator_address": {
      "selection": "address",
      "value": "192.168.1.1"
    }
  }
]

Channel-specific access control rules:

  • remote_forwards (list): To permit only specific forwardins, list the permitted addresses in this field. Leave it empty to permit forwarding without restrictions.

    Enter the source of the forwarded traffic into the originator_address, the target of the traffic into the connected_address field. Specify IP addresses or networks (in IP address/Prefix format). These parameters are the end-points of the forwarded traffic (that is, the remote host that sends data to the client), and not the SSH server. For example, to enable forwarding from the 192.168.20.20 remote host to the client 192.168.50.50, enter 192.168.20.20 into the originator_address, and 192.168.50.50 into the connected_address field. For details, see Section Limiting addresses in port forwarding.

session-exec Yes

Session Exec: Execute a remote command (for example rsync) without opening a session shell. List the permitted command in the execs field. You can use regular expressions to specify the commands. This field can contain only letters (a-z, A-Z), numbers (0-9), and the following special characters ({}()*?\\|[]).

Warning

Restricting the commands available in Session Exec channels does not guarantee that no other commands can be executed. Commands can be renamed, or executed from shell scripts to circumvent such restrictions.

Channel-specific access control rules:

  • execs (list): List the permitted command in the execs field. Regular expressions may be used to specify the commands.

For example:

"execs": [
  "top",
  "ls"
]
session-exec-scp Yes

Session Exec SCP: Transfers files using the Secure Copy (SCP) protocol.

Channel-specific actions:

  • log_transfer_to_db (list): (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (list): (true|false): Send the file operations into the system log

For example:

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}
session-subsystem Yes

Session Subsystem: Use a subsystem. Enter the name of the permitted subsystem into the subsystems field.

Channel-specific access control rules:

  • subsystems (list): List the permitted subsystems in this field.

For example:

"execs": [
  "top",
  "ls"
]
session-exec-sftp Yes

Session SFTP: Transfers files using the Secure File Transfer Protocol (SFTP).

Channel-specific actions:

  • log_transfer_to_db (list): (true|false): Make the list of file operations available in the Search > Search > File operations column of the SCB web interface

  • log_transfer_to_syslog (list): (true|false): Send the file operations into the system log

For example:

"actions": {
  "audit": false,
  "four_eyes": false,
  "ids": false,
  "log_transfer_to_db": true,
  "log_transfer_to_syslog": true
}
session-shell Yes

Session Shell: The traditional remote terminal session.

Channel-specific actions:

  • content_policy reference: The ID of the Content policy to apply to the connection.

For example:

"actions": {
  "audit": true,
  "content_policy": {
    "key": "433849548566ab327522e6"
  },
  "four_eyes": false,
  "ids": false
}

Limiting addresses in port forwarding

The connected_address, host_address, network, and originator_address options that you can use in SSH channel policies that allow port-forwarding and X11 forwarding have the following parameters.

Element Type Description
connected_address, host_address, network, or originator_address   list of JSON objects Container objects for limiting access to port-forwarding in SSH channel policies. For details, see Section 13.4, SSH channels.
  selection address or network

Specifies the type of the address. Possible values: address or network

  value IPv4 address or network

The IP address, or the network in IP-address:prefix format. For example, 192.168.1.1 or 192.168.0.0/16

13.5. SSH host keys and certificates

SCB stores the host keys and X.509 certificates of the trusted servers. When a client tries to connect to a server, SCB verifies the host key or the certificate of the server, and allows connections only to the servers that have their keys available on SCB (unless the SSH Connection Policy is configured differently).

URL

GET https://<IP-address-of-SCB>/api/ssh-host-keys

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the SSH host keys and certificates of the servers that the users can connect to using SSH.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/ssh-host-keys/

The following command retrieves the properties of a specific key.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/ssh-host-keys/<object-id>

Response

The following is a sample response received when listing SSH host keys and certificates from the https:<IP-address-of-SCB>/api/ssh-host-keys/ endpoint. For details of the meta object, see Section 1.1, Message format.

The key of these objects is in the following format: <type-of-the-key>-<host-address>:<host-port>.

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    },
    {
      "key": "ssh-rsa-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-rsa-10.110.0.1:22"}
    },
    {
      "key": "x509v3-sign-rsa-d00::2222:dead:2222",
      "meta": {"href": "/api/ssh-host-keys/x509v3-sign-rsa-d00::2222:dead:2222"}
    }
  ]
}

When retrieving the endpoint of a specific host key, the response is the following.

{
  "key": "ssh-rsa-10.10.100.1:22",
  "meta": {
    "href": "/api/ssh-host-keys/ssh-rsa-10.10.100.1:22",
    "parent": "/api/ssh-host-keys"
  },
  "ssh-rsa-10.10.100.1:22": {
    "address": "10.10.100.1",
    "port": 22,
    "type": {
      "selection": "ssh-rsa",
      "value": "AAAAB3NzaC1yc2EAAAABIwAAAQEAxrtNxBZieXhBI2gJoAdsjKNq...=="
    }
  }
}
Element Type Description
key     string Top level element, contains the ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>
<id-of-the-host-key>     Top level element (string) The ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>.
  address   string The IPv4 or IPv6 address of the host that the key belongs to. Note that for IPv6 addresses, this is always the canonical format of the address.
  port   number The port number where the host uses the key or certificate.
  type   JSON object The ID of the host key or certificate in the following format: <type-of-the-key>-<host-address>:<host-port>.
    selection string Specifies the type of the host key. Possible values: ssh-rsa, ssh-dss, x509v3-sign-rsa, x509v3-sign-dss
    value string The host key or certificate as a string in PEM format.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Search and filter host keys

To list only specific host keys, you can use the following filters.

  • List every host key and certificate:

    GET https://<IP-address-of-SCB>/api/ssh-host-keys
  • List host keys of a specific type:

    GET https://<IP-address-of-SCB>/api/ssh-host-keys?type=<type-to-list>

    Possible values: ssh-rsa, ssh-dss, x509v3-sign-rsa, x509v3-sign-dss. For example:

    GET https://<IP-address-of-SCB>/api/ssh-host-keys?type=ssh-rsa
  • List host keys for a specific port number:

    GET https://<IP-address-of-SCB>/api/ssh-host-keys?port=<port-number-to-list>
  • List host keys for a specific host address (IPv4 or IPv6):

    GET https://<IP-address-of-SCB>/api/ssh-host-keys?address=<host-address>
  • For a complex filter, separate the parameters with an ampersand (&) character, for example:

    GET https://<IP-address-of-SCB>/api/ssh-host-keys?port=<port-number-to-list>&type=<type-to-list>

The response to such requests is a JSON object, where the items list includes the IDs of the selected host keys (or an empty list). For example, filtering for ssh-dss keys could return a similar list:

{
  "meta": {
    "href": "/api/ssh-host-keys",
    "parent": "/api"
  },
  "items": [
    {
      "key": "ssh-dss-10.110.0.1:22",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.1:22"}
    },
    {
      "key": "ssh-dss-10.110.0.2:2222",
      "meta": {"href": "/api/ssh-host-keys/ssh-dss-10.110.0.2:2222"}
    }
  ]
}

Add new host key

To upload a new host key or certificate, you have to POST the host key and other data as a JSON object to the https://<IP-address-of-SCB>/api/ssh-host-keys endpoint. For details, see Section 12.2, Create a new object. The body of the POST request must contain a JSON object with the parameters listed in SSH host key parameters. If the POST request is successful, the response includes an ID for the host key in the following format: <type-of-the-key>-<host-address>:<host-port>. For example:

{
  "address": "10.110.0.1",
  "port": 22,
  "type": {
    "selection": "ssh-rsa",
    "value": "AAAAB3NzaC1yc2EAAAAD...zvMwgc=="
  }
}

Note that for IPv6 addresses, SCB will automatically convert the address to its canonical format.

Delete host key

To delete a host key or certificate, you have to DELETE https://<IP-address-of-SCB>/api/ssh-host-keys/<ID-of-the-host-key> endpoint. For details, see Section 12.1, Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

{
    "meta": {
        "href": "/api/ssh-host-keys/ssh-rsa-10.10.20.35:22",
        "parent": "/api/ssh-host-keys"
    }
}

You must commit your changes to actually delete the object from SCB.

13.6. Auditing connections

The api/audit/connections endpoint lists the monitored connections (active and closed).

URL

GET https://<IP-address-of-SCB>/api/audit/connections

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/audit/connections

The following command retrieves the properties of a specific connection.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/audit/connections/<connection-key>

Response

The following is a sample response received when listing connections. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "2",
      "meta": {
        "href": "/api/audit/connections/2"
      }
    },
    {
      "key": "1",
      "meta": {
        "href": "/api/audit/connections/1"
      }
    }
  ],
  "meta": {
    "fields": [],
    "first": "/api/audit/connections?limit=500&offset=0&fields=",
    "href": "/api/audit/connections",
    "last": "/api/audit/connections?limit=500&offset=0&fields=",
    "limit": 500,
    "match_count": 39,
    "next": null,
    "offset": 0,
    "parent": "/api/audit",
    "previous": null
  }
}

When retrieving the endpoint of a specific connection, the response is the following.

{
  "body": {
    "active": false,
    "audit_trail": {
      "archive": null,
      "content": {
        "url": "/api/audit/connections/39/audit_trail"
      }
    },
    "channel_policy": "shell-only",
    "channels": [
      {
        "body": {
          "audit_stream_id": 2,
          "duration": 17,
          "end_time": 1461626632,
          "start_time": 1461626615,
          "type": "session shell",
          "verdict": "accept"
        },
        "key": "1",
        "meta": {
          "href": "/api/audit/connections/39/channels/1"
        }
      }
    ],
    "client_address": "<client-ip>",
    "client_port": 56189,
    "connection_policy": "<conn-policy>",
    "duration": 17,
    "end_time": 1461626632,
    "gateway_username": "<gw-username>",
    "protocol": "ssh",
    "server_address": "<server-ip>",
    "server_local_address": "<ip-of-SCB>",
    "server_local_port": <port-of-SCB>,
    "server_port": <server-port>,
    "server_username": "<username-on-server>",
    "session_id": "svc/unBaV9N2hhQxTfnouLiScs/catail:19/ssh",
    "start_time": 1461626615,
    "target_address": "<target-ip>",
    "target_port": <target-port>,
    "verdict": "accept"
  },
  "key": "39",
  "meta": {
    "href": "/api/audit/connections/39",
    "parent": "/api/audit/connections"
  }
}
Element Type Description
key   string Top level element, contains the key of the connection or audit trail.
body   Top level element (string) Contains the properties of the connection.
  active boolean If the returned value is true, the connection is ongoing.
  audit_trail Top level item Contains the audit trail of the session. If the session does not have an audit trail, this element is not used.
  channel_policy string References the name of the channel policy. You can find the list of channel policies for each protocol at the /api/configuration/<protocol>/channel_policies/ endpoint.
  channels Top level list

Contains the properties of each connection channel.

  client_address string The IP address of the client.
  client_port int The port of the client.
  connection_policy string References the key of the connection policy. You can find the list of connection policies for each protocol at the /api/configuration/<protocol>/connections/ endpoint.
  duration int The duration of the connection. Computed value.
  end_time int The UNIX timestamp of the end of the connection. For ongoing connection, the value is null.
  gateway_username string The username used for authenticating against the gateway.
  protocol string The protocol of the connection.
  server_address int The IP of the remote server.
  server_local_address string The IP of SCB.
  server_local_port int The port of SCB.
  server_port int The port of the remote server.
  server_username string The username used for authenticating on the remote server.
  session_id string The identifier of the session.
  start_time int The UNIX timestamp of the start of the connection.
  target_address string The IP the client targeted for connection.
  target_port int The port the client targeted for connection.
  verdict string

The connection verdict. Possible values are:

  • accept

    The connection attempt was successful.

  • accept-terminated

    The connection violated a content policy, and was terminated by SCB.

  • auth-fail

    Authentication failure.

  • deny

    The connection was denied.

  • fail

    The connection attempt failed.

  • four-eyes-reject

    The connection attempt was rejected by a four-eyes agent on SCB.

Audit trail elements Type Description
archive   Top level element

Indicates whether the audit trail has been archived or not. If the audit trail has not been archived yet, the value of the element is null. For example:

"audit_trail": {
            "archive": null,
            "content": {
                "href": "/api/audit/connections/10/audit_trail"
            }
        },
  date UNIXTIMESTAMP The date when the audit trail was archived in UNIX timestamp format (for example, 1451865600).
  server hostname or IP address The address of the remote server where the audit trail was archived.
  path string The path on the remote server where the audit trail was archived.
  policy string The ID of the archiving policy that was used to archive the audit trail.
content   Top level element Contains the list of available methods, and the endpoint of the audit trail.
  methods list, string Contains the methods available for working with the audit trail.
  url string The endpoint of the audit trail.
Channel elements Type Description
key   string Top level element, contains the ID of the channel.
body   Top level element (string) The properties of the channel.
  audit_stream_id int The identifier of the channel's audit stream. If the session does not have an audit trail, this element is not used.
  duration int The duration of the connection. Computed value.
  end_time int The UNIX timestamp of the end of the connection. For ongoing connections, the value is null.
  start_time int The UNIX timestamp of the start of the connection.
  type string

The type of the channel. Additional elements might be used with certain ICA, SSH and RDP channel types.

  verdict string

The channel's connection verdict.

  command string

Used with the session exec SSH channel type.

The executed command.

  scp_path string

Used with the session exec scp SSH channel type.

The folder used for Secure Copy.

  subsystem_name string

Used with the session subsystem sftp SSH channel type.

The name of the used subsystem.

  originator_address string

Used with the local forward and remote forward SSH channel types.

The source address of the forwarded traffic.

  originator_port int

Used with the local forward and remote forward SSH channel types.

The source port of the forwarded traffic.

  connected_address string

Used with the local forward and remote forward SSH channel types.

The target address of the forwarded traffic.

  connected_port int

Used with the local forward and remote forward SSH channel types.

The target port of the forwarded traffic.

  dynamic_channel string

Used with the dynamic virtual RDP channel type.

The name of the dynamic channel.

  device_name string

Used with the serial redirect, parallel redirect, printer redirect, disk redirect, and scard redirect RDP channel types.

The name of the device.

Examples: 

All possible SSH channel types:

"channels": [
  {
    "key": "1",
    "meta": {
      "href": "/api/audit/connections/1/channels/1"
    },
    "body": {
      "type": "session shell",
      "verdict": "accept",
      "start_time": 1451901988,
      "end_time": 1451902145,
      "duration": 157
    }
  },
  {
    "key": "2",
    "meta": {
      "href": "/api/audit/connections/1/channels/2"
    },
    "body": {
      "type": "session exec",
      "verdict": "accept",
      "start_time": 1451902141,
      "end_time": 1451902145,
      "duration": 4,
      "command": "ls"
    }
  },
  {
    "key": "3",
    "meta": {
      "href": "/api/audit/connections/1/channels/3"
    },
    "body": {
      "type": "session exec scp",
      "verdict": "accept",
      "start_time": 1451902141,
      "end_time": 1451902145,
      "duration": 4,
      "scp_path": "<path-to-folder>"
    }
  },
  {
    "key": "4",
    "meta": {
      "href": "/api/audit/connections/1/channels/4"
    },
    "body": {
      "type": "session subsystem sftp",
      "verdict": "accept",
      "start_time": 1451902142,
      "end_time": 1451902145,
      "duration": 3,
      "subsystem_name": "sftp"
    }
  },
  {
    "key": "5",
    "meta": {
      "href": "/api/audit/connections/1/channels/5"
    },
    "body": {
      "type": "local forward",
      "verdict": "accept",
      "start_time": 1451902145,
      "end_time": 1451902146,
      "duration": 1,
      "originator_address": "::1",
      "originator_port": 59578,
      "connected_address": "<server>",
      "connected_port": 22
    }
  },
  {
    "key": "6",
    "meta": {
      "href": "/api/audit/connections/1/channels/6"
    },
    "body": {
      "type": "remote forward",
      "verdict": "accept",
      "start_time": 1451902145,
      "end_time": 1451902146,
      "duration": 1,
      "originator_address": "::1",
      "originator_port": 42212,
      "connected_address": "localhost",
      "connected_port": 9898
    }
  },
  {
    "key": "7",
    "meta": {
      "href": "/api/audit/connections/1/channels/7"
    },
    "body": {
    "type": "x11 forward",
    "verdict": "deny",
    "start_time": 1451902149,
    "end_time": 1451902149,
    "duration": 0
    }
  }
 ]

All possible RDP channel types:

"channels": [
  {
    "key": "1",
    "meta": {
      "href": "/api/audit/connections/1/channels/1"
    },
    "body": {
      "type": "drawing",
      "verdict": "accept",
      "start_time": 1451901988,
      "end_time": 1451902145,
      "duration": 157
    }
  },
  {
    "key": "2",
    "meta": {
      "href": "/api/audit/connections/1/channels/2"
    },
    "body": {
      "type": "sound",
      "verdict": "accept",
      "start_time": 1451902141,
      "end_time": 1451902145,
      "duration": 4
    }
  },
  {
    "key": "3",
    "meta": {
      "href": "/api/audit/connections/1/channels/3"
    },
    "body": {
      "type": "clipboard",
      "verdict": "accept",
      "start_time": 1451902141,
      "end_time": 1451902145,
      "duration": 4
    }
  },
  {
    "key": "4",
    "meta": {
      "href": "/api/audit/connections/1/channels/4"
    },
    "body": {
      "type": "seamless",
      "verdict": "deny",
      "start_time": 1451902142,
      "end_time": 1451902142,
      "duration": 0
    }
  },
  {
    "key": "5",
    "meta": {
      "href": "/api/audit/connections/1/channels/5"
    },
    "body": {
      "type": "dynamic virtual",
      "verdict": "accept",
      "start_time": 1451902145,
      "end_time": 1451902146,
      "duration": 1,
      "dynamic_channel": "Microsoft::Windows::RDS::Geometry::v08.01"
    }
  },
  {
    "key": "6",
    "meta": {
      "href": "/api/audit/connections/1/channels/6"
    },
    "body": {
      "type": "custom",
      "verdict": "deny",
      "start_time": 1451902145,
      "end_time": 1451902145,
      "duration": 0
    }
  },
  {
    "key": "7",
    "meta": {
      "href": "/api/audit/connections/1/channels/7"
    },
    "body": {
      "type": "serial redirect",
      "verdict": "accept",
      "start_time": 1451902149,
      "end_time": 1451902150,
      "duration": 1,
      "device_name": "COM1"
    }
  },
  {
    "key": "8",
    "meta": {
      "href": "/api/audit/connections/1/channels/8"
    },
    "body": {
      "type": "parallel redirect",
      "verdict": "accept",
      "start_time": 1451902149,
      "end_time": 1451902150,
      "duration": 1,
      "device_name": "LPT1"
    }
  },
  {
    "key": "9",
    "meta": {
      "href": "/api/audit/connections/1/channels/9"
    },
    "body": {
      "type": "printer redirect",
      "verdict": "accept",
      "start_time": 1451902149,
      "end_time": 1451902150,
      "duration": 1,
      "device_name": "PRN22"
    }
  },
  {
    "key": "10",
    "meta": {
      "href": "/api/audit/connections/1/channels/10"
    },
    "body": {
      "type": "disk redirect",
      "verdict": "accept",
      "start_time": 1451902149,
      "end_time": 1451902150,
      "duration": 1,
      "device_name": "J:"
    }
  },
  {
    "key": "11",
    "meta": {
      "href": "/api/audit/connections/1/channels/11"
    },
    "body": {
      "type": "scard redirect",
      "verdict": "accept",
      "start_time": 1451902149,
      "end_time": 1451902150,
      "duration": 1,
      "device_name": "SCARD"
    }
  }
]

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.7. Searching in the connection database

You can list, search, and filter the SCB connection database at the /api/audit/connections endpoint. You can use the following actions:

  • ?q

    Filter the list using one or more property (element) of the connections.

  • ?fields

    Display the selected properties (elements and values) of the listed connections.

  • ?limit

    Define the number of connections that are displayed at once.

  • ?offset

    If the number of items exceeds the display limit, you can use the offset option to navigate the list.

  • ?sort

    Sort the results based on the values of the fields.

To combine multiple expressions, use the & (ampersand) character, for example:

Display the target server and port of each active connection:

curl --cookie session_id=<session_cookie> "https://<IP-address-of-SCB>/api/audit/connections?fields=target_address,target_port&q=active:true"

Display 10 connections at once, and navigate to 31-40:

curl --cookie session_id=<session_cookie> "https://<IP-address-of-SCB>/api/audit/connections?limit=10&offset=3"
Note

If you use curl, use quotation marks for the URL to avoid problems with the & (ampersand) character.

Response

The response to search or filtering action contains a list of the matching sessions, as well as some additional meta fields. For example:

{
    "items": [
        {
            "body": {
                "duration": 0,
                "gateway_username": "johndoe",
                "start_time": 1475756786
            },
            "key": "2",
            "meta": {
                "href": "/api/audit/connections/2"
            }
        },
        {
            "body": {
                "duration": 34,
                "gateway_username": "johndoe",
                "start_time": 1475757081
            },
            "key": "10",
            "meta": {
                "href": "/api/audit/connections/10"
            }
        }
    ],
    "meta": {
        "fields": [
            "start_time",
            "gateway_username",
            "duration"
        ],
        "first": "/api/audit/connections?limit=500&offset=0&fields=start_time,gateway_username,duration&q=gateway_username%3Ajohndoe&=duration",
        "href": "/api/audit/connections",
        "last": "/api/audit/connections?limit=500&offset=0&fields=start_time,gateway_username,duration&q=gateway_username%3Ajohndoe&sort=duration",
        "limit": 500,
        "match_count": 2,
        "next": null,
        "offset": 0,
        "parent": "/api/audit",
        "previous": null
    }
Element Type Description
items   list Top level element, a list containing the details of the matching sessions.
  body JSON object

Contains the information returned about a session, that is, the fields selected with the ?fields expression. For example, if you used the fields=start_time,gateway_username,duration expression in your query, then the body element contains these fields for each returned session:

"body": {
                "duration": 0,
                "gateway_username": null,
                "start_time": 1475756936
            },

For details about the returned fields, see Connection properties.

  key string The reference ID of the session.

In addition to the usual meta elements of other endpoints, search results can contain the following additional elements.

Element Type Description
meta   JSON object Top level element, a list containing meta information about the response.
  fields list

Contains the list of data fields returned about each session, that is, the fields selected with the ?fields expression. For example, if you used the fields=start_time,gateway_username,duration expression in your query, then the body element contains these fields for each returned session:

"fields": [
            "start_time",
            "gateway_username",
            "duration"
        ],

For details about the returned fields, see Connection properties.

  limit integer The maximum number of sessions returned in a the response (by default, 500).
  match_count integer The number of results matching the query.
  next string A query to retrieve the next set of search results, if match_count is higher than limit.
  offset integer Indicates the position of the results in this response, relative to the total number of results (match_count). Otherwise, its value is null.
  previous string A query to retrieve the previous set of search results, if match_count is higher than limit, and offset is higher than 0. Otherwise, its value is null.

Filtering

You can use the ?q option to filter the list using one or more property (element) of the connections.

?q=protocol:ssh

You can escape special characters using the backslash character.

?q=server_username:\"Windows User\"

To add multiple elements to the filter, you can use the AND, AND NOT, and OR operators.

?q=protocol:ssh AND verdict:accept AND NOT gateway_username:admin

You can create groups using () (parentheses).

?q=(client_address:10.20.30.40 OR target_address:10.20.30.40) AND verdict:accept

You can also use () (parentheses) to add multiple possible values for a property.

?q=protocol:(ssh rdp)

You can use the * (asterisk) and ? (question mark) wildcards for string-type values.

?q=gateway_username:?dmi*

You can define ranges using [] (brackets) or {} (braces) and the TO operator. This only works for numeric (int) values.

  • [ means equal or higher than the following value

  • ] means equal or lower than the preceding value

  • { means higher than the following value

  • }means lower than the preceding value

For example, the following range resolves to 22:

?q=port:{21 TO 23}

You can also use the * (asterisk) wildcard in the range.

?q=start_time:[* TO 1461654799]

Note that not all connection data can be used for filtering. The available elements are:

  • active

    Boolean, true means the connection is ongoing.

  • auth_method

    String, the authentication method used.

  • channel_policy

    String, the key of the channel policy.

  • client_address

    String, the IP address of the client.

  • client_port

    Integer, the port of the client.

  • connection_policy

    String, the key of the connection policy.

  • end_time

    Integer, the UNIX timestamp of the end of the connection.

  • gateway_username

    String, the username used for authenticating against the gateway.

  • protocol

    String, the protocol of the connection.

  • server_address

    String, the IP of the remote server.

  • server_local_address

    String, the IP of SCB.

  • server_local_port

    String, the port of SCB.

  • server_port

    String, the port of the remote server.

  • server_username

    String, the username used for authenticating on the remote server.

  • session_id

    String, the identifier of the session.

  • start_time

    Integer, the UNIX timestamp of the start of the connection.

  • target_address

    String, the IP the client targeted for connection.

  • target_port

    Integer, the port the client targeted for connection.

  • verdict

    String, the connection verdict. Possible values are:

    • accept

      The connection attempt was successful.

    • accept-terminated

      The connection violated a content policy, and was terminated by SCB.

    • conn-auth-fail

      Authentication failure.

    • conn-deny

      The connection was denied.

    • conn-fail

      The connection attempt failed.

    • four-eyes-reject

      The connection attempt was rejected by a four-eyes agent on SCB.

Displaying connection data

You can use the ?fields option to display the selected data (body elements) of each connection.

?fields=protocol

To list multiple elements, use the , (comma) character. Note that the response includes the selected fields in alphabetic order, not in the order they were specified.

?fields=protocol,gateway_username

To list all possible elements, use the fields=* expression.

?fields=*

Note that not all connection data can be displayed in the generated list. The available elements are:

  • active

    Boolean, true means the connection is ongoing.

  • archived

    Boolean, true means the connection is archived.

  • auth_method

    String, the authentication method used.

  • channel_policy

    String, the key of the channel policy.

  • client_address

    String, the IP address of the client.

  • client_port

    Integer, the port of the client.

  • connection_policy

    String, the key of the connection policy.

  • duration

    Integer, the duration of the connection. Computed value.

  • end_time

    Integer, the UNIX timestamp of the end of the connection.

  • gateway_username

    String, the username used for authenticating against the gateway.

  • protocol

    String, the protocol of the connection.

  • server_address

    String, the IP of the remote server.

  • server_local_address

    String, the IP of SCB.

  • server_local_port

    Integer, the port of SCB.

  • server_port

    Integer, the port of the remote server.

  • server_username

    String, the username used for authenticating on the remote server.

  • session_id

    String, the identifier of the session.

  • start_time

    Integer, the UNIX timestamp of the start of the connection.

  • target_address

    String, the IP the client targeted for connection.

  • target_port

    Integer, the port the client targeted for connection.

Changing the display limit

You can use the ?limit option to change the number of items displayed at once. The default limit is 500.

?limit=1000

To navigate beyond the displayed set, use the offset option.

Navigating large datasets

You can use the ?offset option to navigate data sets that extend beyond the display limit. The default value of the offset is 0, this is the initially displayed set. To move to the next set, increase the value to 1, 2, and so on.

Example: the display limit is the default 500, and the number of connections is 1012. The initial 500 connections are listed at:

?offset=0

To view connections from 501 to 1000, change the offset to 1:

?offset=1

To display the remaining 12 connections, change the offset to 2:

?offset=2

Sort the results

You can sort the search results using the sort expression, for example, based on the length of the sessions:

?sort=duration

You can use any field to sort the results. By default, sorting returns the results in ascending order, if you use ?sort=duration, then the shortest session is at the beginning of the list. To sort the results in descending order, add the minus sign (-) before the field name. For example, the response to the following expression starts with the longest session:

?sort=-duration

You can specify multiple fields to order the list. In this case, the list is first ordered using the first field, then the second, and so on. For example, to order the list first by duration, then by start time, use the following expression.

?sort=duration,start_time
curl --cookie session_id=<session_cookie> "https://<IP-address-of-SCB>/api/audit/connections?sort=duration&fields=start_time,gateway_username,duration"

13.8. Reporting

List of endpoints for configuring reporting, and accessing the generated reports.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/configuration/reporting

Response

The following is a sample response received when listing the available endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/reporting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/ssh",
    "parent": "/api/configuration",
    "previous": "/api/configuration/rdp",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "content_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/content_subchapters"
      }
    },
    {
      "key": "custom_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/custom_subchapters"
      }
    },
    {
      "key": "predefined_reports",
      "meta": {
        "href": "/api/configuration/reporting/predefined_reports"
      }
    },
    {
      "key": "reports",
      "meta": {
        "href": "/api/configuration/reporting/reports"
      }
    },
    {
      "key": "statistics_subchapters",
      "meta": {
        "href": "/api/configuration/reporting/statistics_subchapters"
      }
    }
  ]
}
Endpoint Description
content_subchapters List of the reporting subchapters created from audit trail content (statistics of search keywords, and screenshots).
custom_subchapters List of the reporting subchapters created from custom queries to the SCB connection database.
predefined_reports List of the pre-defined reports available on SCB.
reports List of the configured reports.
statistics_subchapters List of the reporting subchapters created from connection statistics.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.9. Reports

List of the configured reports.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting/reports

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configured reports.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/reports

The following command retrieves the properties of a specific report.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/reports/<key_value>

Response

The following is a sample response received when listing reports. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/reports",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/statistics_subchapters",
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/predefined_reports",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "7798770004e472c8576912",
      "meta": {
        "href": "/api/configuration/reporting/reports/7798770004e472c8576912"
      }
    },
    {
      "key": "8292675195707f19d932af",
      "meta": {
        "href": "/api/configuration/reporting/reports/8292675195707f19d932af"
      }
    }
  ]
}

When retrieving the endpoint of a specific report, the response is the following.

{
  "body": {
    "access": [
      "report"
    ],
    "chapters": [
      {
        "name": "System health",
        "subchapters": [
          {
            "name": "system_health_network_connections",
            "selection": "builtin"
          },
          {
            "name": "system_health_load_average",
            "selection": "builtin"
          }
        ]
      },
      {
        "name": "All connections",
        "subchapters": [
          {
            "name": "connection_each_scb_top10_channel_types_each",
            "selection": "builtin"
          },
          {
            "name": "connection_each_scb_top10_portforward_targets_each",
            "selection": "builtin"
          }
        ]
      },
      {
        "name": "Search statistics",
        "subchapters": [
          {
            "reference": "21111736175707f1df8bea1",
            "selection": "custom"
          }
        ]
      },
      {
        "name": "Misc",
        "subchapters": [
          {
            "reference": "13869311625707e0a3e0892",
            "selection": "custom"
          }
        ]
      },
      {
        "name": "Advanced statistics",
        "subchapters": [
          {
            "reference": "5983143445707eb740fee3",
            "selection": "custom"
          }
        ]
      }
    ],
    "email_recipients": {
      "recipients": [
        "admin@company.com"
      ],
      "selection": "other"
    },
    "frequency": {
      "day": false,
      "month": true,
      "week": false
    },
    "logo_id": "logoC890jH",
    "name": "all-options",
    "send_report_in_email": true
  },
  "key": "8292675195707f19d932af",
  "meta": {
    "first": "/api/configuration/reporting/reports/7798770004e472c8576912",
    "href": "/api/configuration/reporting/reports/8292675195707f19d932af",
    "last": "/api/configuration/reporting/reports/8292675195707f19d932af",
    "next": null,
    "parent": "/api/configuration/reporting/reports",
    "previous": "/api/configuration/reporting/reports/12046247915707e5d6a5c59",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the report
body     Top level element (string) The elements of the report.
  access   list

Required. List of access control groups whose members can access the subchapter.

To deny access to the report, use "admin" as the only value for the element.

  chapters   Top level item A chapter of the report.
  email_recipients   Top level item Contains the list of e-mails where the generated report is sent.
    recipients list

Custom list of e-mails where the generated report is sent.

To use a custom list, the selection element must be set to other.

    selection string

This element can have two values:

  • default uses the e-mail address configured in the reporting_address element of the https://<IP-address-of-SCB>/api/configuration/management/email endpoint (or the Basic Settings > Management > Mail settings > Send reports to field on the web UI).

  • other uses the e-mails listed in the recipients element.

  frequency   Top level item Contains the list of options for defining the frequency of generating the report.
    day boolean

Set it to true to generate the report each day.

    month boolean

Set it to true to generate the report each month.

    week boolean

Set it to true to generate the report each week.

  logo_id   string

The ID of the custom logo. The null value means the report is generated using the default logo.

You can upload a custom logo on the web UI of SCB, using the Reporting > Configuration > <report> > Choose new logo button.

  name   string The name of the report.
  send_report_in_email   boolean Set it to false if you do not want to include the generated report in the e-mail.
Chapters elements Type Description
name   string Name of the chapter.
subchapters   list List of subchapters included in the chapter.
  name string

Name of the built-in subchapter included in the chapter. For the list of the built-in subchapters, see Section 13.10, Built-in subchapters.

To include a built-in subchapter, use the value of its name element, not the key.

  reference string

The key of the custom, content, or statistics subchapter.

  • For the keys of the reporting subchapters created from custom queries to the SCB connection database, see the custom_subchapters endpoint.

  • For the keys of the reporting subchapters created from audit trail content (statistics of search keywords, and screenshots), see the reporting/content_subchapters endpoint.

  • For the keys of the reporting subchapters created from connection statistics, see the reporting/statistics_subchapters endpoint.

To include a custom, content, or statistics subchapter, use the value of its key element, not the name.

  selection string

This element can have two values:

  • Set builtin for the default reporting subchapters.

  • Set custom for all other subchapters (custom, content or statistics).

Examples: 

Set the e-mail recipients to the default (as configured in the reporting_address element of the /api/configuration/management/email endpoint):

"email_recipients": {
  "selection": "default"
}

Create a custom set of e-mail recipients:

"email_recipients": {
  "recipients": [
    "<email-1>",
    "<email-2>"
  ],
  "selection": "other"
}

Add a reporting chapter with built-in subchapters:

"chapters": [
  {
    "name": "<custom-name>",
    "subchapters": [
      {
        "name": "system_health_filesystem_usage",
        "selection": "builtin"
      },
      {
        "name": "system_health_network_connections",
        "selection": "builtin"
      },
      {
        "name": "system_health_load_average",
        "selection": "builtin"
      }
    ]
  }
]

Add a reporting chapter with custom, content, or statistics subchapters:

"chapters": [
  {
    "name": "<custom-name>",
    "subchapters": [
      {
        "reference": "<key-of-subchapter>",
        "selection": "custom"
      },
      {
        "reference": "<key-of-subchapter>",
        "selection": "custom"
      }
    ]
  }
]

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
400 IncompleteConfigurationSubtreeError Possible cause: PUT operation on the reports endpoint, instead of POST.
400

IncompleteConfigurationSubtreeError

"missing_paths": [ "email_recipients/recipients" ]

You have selected other for the selection element under email_recipients, but did not provide a list using recipients.
400

IncompleteConfigurationSubtreeError

Syntax error: \"No such property; property='recipients'

Do not provide recipients if you set the selection element under email_recipients to default.
400

IncompleteConfigurationSubtreeError

"missing_paths": [ "chapters/7/subchapters/0/name" ]

Verify that the selection element of the subchapter is correctly set to builtin or custom.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a report

To add a report, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new report.

    You can find a detailed description of the available parameters listed in Contents of a report.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/reports endpoint. If the POST request is successful, the response includes the key of the new report.

{
  "key": "26ddf648-9a21-4a7f-af56-9cea575785a9",
  "meta": {
    "href": "/api/configuration/reporting/reports/26ddf648-9a21-4a7f-af56-9cea575785a9",
    "parent": "/api/configuration/reporting/reports",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a report

To modify a report, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the report.

    You can find a detailed description of the available parameters listed in Contents of a report.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/reports/<key-of-the-report> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.10. Built-in subchapters

To create reports, you can use a number of predefined reporting subchapters. The following sections list the short description of each subchapter, as displayed on the web UI of SCB, and its name you can use to configure reports using the REST API.

Configuration changes

  • Configuration changes - Changes by pages:

    configuration_changes_changes_by_pages

  • Configuration changes - Changes by users:

    configuration_changes_changes_by_users

  • Configuration changes - Changes in time:

    configuration_changes_changes_in_time

  • Configuration changes - Special events:

    configuration_changes_special_events

  • Configuration changes - Password change:

    configuration_changes_password_change

Connection summary

  • Channels table

    connection_aggregate_scb_channels

  • Distribution of channels

    connection_aggregate_scb_channeldist

  • Channels history

    connection_aggregate_scb_channelshist

  • Verdicts history by channels

    connection_aggregate_scb_verdicthist

  • Usernames

    connection_aggregate_scb_usernames

  • Accepted usernames

    connection_aggregate_scb_accepted_usernames

  • Remote usernames

    connection_aggregate_scb_remote_usernames

  • Accepted remote usernames

    connection_aggregate_scb_accepted_remote_usernames

  • Four-eyes authorizers

    connection_aggregate_scb_4eyes_authorizers

  • Source addresses

    connection_aggregate_scb_source_addresses

  • Server addresses

    connection_aggregate_scb_server_addresses

  • Top 10 usernames in denied channels

    connection_aggregate_scb_top10_users_in_denied_channels

  • Top 10 denied usernames in channels

    connection_aggregate_scb_top10_denied_users

  • Top 10 denied servers in channels

    connection_aggregate_scb_top10_denied_servers

  • Top 10 denied channel types

    connection_aggregate_scb_top10_denied_channeltypes

  • Top 10 longest sessions

    connection_aggregate_scb_top10_longest_sessions

  • Top 10 shortest sessions

    connection_aggregate_scb_top10_shortest_sessions

System health

  • System health - Filesystem usage

    system_health_filesystem_usage

  • System health - Network connections

    system_health_network_connections

  • System health - Load average

    system_health_load_average

All connections

  • Top 10 usernames in each connection

    connection_each_scb_top10_users_each

  • Top 10 accepted usernames in each connection

    connection_each_scb_top10_accepted_users_each

  • Top 10 remote usernames in each connection

    connection_each_scb_top10_remote_users_each

  • Top 10 username/four-eyes authorizer in each connection

    connection_each_scb_top10_4eyes_authorizers_each

  • Top 10 servers in each connection

    connection_each_scb_top10_servers_each

  • Top 10 username/server in each connection

    connection_each_scb_top10_username_server_connection_each

  • Top 10 username/remote user in each connection

    connection_each_scb_top10_remoteusers_each

  • Top 10 commands over SSH session-exec channel in each connection

    connection_each_scb_top10_exec_commands_each

  • Top 10 channel types in each connection

    connection_each_scb_top10_channel_types_each

  • Top 10 Port forward targets in each connection

    connection_each_scb_top10_portforward_targets_each

Specific connections

You can also use subchapters for a specific connection. You have to use the protocol and the key of the connection.

The following examples assume that the connection's protocol is SSH, and its key is 8348340645707e2575e3c6.

  • Top 10 usernames in "<connection_name>"

    connection_<protocol>_scb_top10_users_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_users_ssh-8348340645707e2575e3c6

  • Top 10 accepted usernames in "<connection_name>"

    connection_<protocol>_scb_top10_accepted_users_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_accepted_users_ssh-8348340645707e2575e3c6

  • Top 10 remote usernames in "<connection_name>"

    connection_<protocol>_scb_top10_remote_users_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_remote_users_ssh-8348340645707e2575e3c6

  • Top 10 username/four-eyes authorizer in "<connection_name>"

    connection_<protocol>_scb_top10_4eyes_authorizers_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_4eyes_authorizers_ssh-8348340645707e2575e3c6

  • Top 10 servers in "<connection_name>"

    connection_<protocol>_scb_top10_servers_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_servers_ssh-8348340645707e2575e3c6

  • Top 10 username/server in "<connection_name>"

    connection_<protocol>_scb_top10_username_server_connection_<protocol>-<key>

    Example

    connection_ssh_scb_top10_username_server_connection_ssh-8348340645707e2575e3c6

  • Top 10 username/remote user in "<connection_name>"

    connection_<protocol>_scb_top10_remoteusers_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_remoteusers_ssh-8348340645707e2575e3c6

  • Top 10 commands over SSH session-exec channel in "<connection_name>"

    connection_<protocol>_scb_top10_exec_commands_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_exec_commands_ssh-8348340645707e2575e3c6

  • Top 10 channel types in "<connection_name>"

    connection_<protocol>_scb_top10_channel_types_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_channel_types_ssh-8348340645707e2575e3c6

  • Top 10 Port forward targets in "<connection_name>"

    connection_<protocol>_scb_top10_portforward_targets_<protocol>-<key>

    Example:

    connection_ssh_scb_top10_portforward_targets_ssh-8348340645707e2575e3c6

13.11. Pre-defined reports

You can configure the compliance reports of SCB using the predefined_reports endpoint.

To help you comply with the regulations of the Payment Card Industry Data Security Standard (PCI DSS), SCB can generate reports on the compliance status of SCB. Note that this is not a fully-featured compliance report: it is a tool to enhance and complement your compliance report by providing information available in SCB. The report corresponds with the document Payment Card Industry (PCI) Data Security Standard, Requirements and Security Assessment Procedures, Version 3.0, published by the PCI Security Standards Council.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting/predefined_reports

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the pre-defined reports available on SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/predefined_reports

The following command retrieves the properties of a specific report.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api//configuration/reporting/predefined_reports/<report-key>

Response

The following is a sample response received when listing pre-defined reports. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/predefined_reports",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/reports",
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/custom_subchapters",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "pcidss",
      "meta": {
        "href": "/api/configuration/reporting/predefined_reports/pcidss"
      }
    }
  ]
}

When retrieving the endpoint of a specific report, the response is the following.

{
  "key": "pcidss",
  "meta": {
    "first": "/api/configuration/reporting/predefined_reports/pcidss",
    "href": "/api/configuration/reporting/predefined_reports/pcidss",
    "last": "/api/configuration/reporting/predefined_reports/pcidss",
    "next": null,
    "parent": "/api/configuration/reporting/predefined_reports",
    "previous": null,
    "transaction": "/api/transaction"
  },
  "pcidss": {
    "access": [
      "report"
    ],
    "email_recipients": {
      "selection": "default"
    },
    "name": "PCI-DSS",
    "send_report_in_email": true
  }
}
Element Type Description
key     string Top level element, contains the ID of the report.
<id-of-the-report>     Top level item The elements of the pre-defined report.
  access   list List of access control groups whose members can access the report.
  email_recipients   Top level item Contains the list of e-mails where the generated report is sent.
    recipients list

Custom list of e-mails where the generated report is sent.

To use a custom list, the selection element must be set to other.

    selection string

This element can have two values:

  • default uses the e-mail address configured in the reporting_address element of the https://<IP-address-of-SCB>/api/configuration/management/email endpoint (or the Basic Settings > Management > Mail settings > Send reports to field on the web UI).

  • other uses the e-mails listed in the recipients element.

  name   string The name of the report.
  send_report_in_email   boolean Set it to false if you do not want to include the generated report in the e-mail.

Examples: 

Set the e-mail recipients to the default (as configured in the reporting_address element of the /api/configuration/management/email endpoint):

"email_recipients": {
  "selection": "default"
}

Create a custom set of e-mail recipients:

"email_recipients": {
  "recipients": [
    "<email-1>",
    "<email-2>"
  ],
  "selection": "other"
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
400

IncompleteConfigurationSubtreeError

Syntax error: \"No such property; property='recipients'

Do not provide recipients if you set the selection element under email_recipients to default.
400

Bad Request

"message": "New Ids are not allowed"

Error when committing your transaction. Creating new pre-defined reports is not allowed.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Modify a pre-defined report

To modify a report, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the report.

    You can find a detailed description of the available parameters listed in Pre-defined reports.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/predefined_reports/<report-key> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.12. Content subchapters

Reporting subchapters created from audit trail content (statistics of search keywords, and screenshots). You have to provide a list of keywords, and create the appropriate filters to narrow down the scope of the search. SCB searches the indexed content of all audit trails that fit the filter criteria, and provide the resulting statistics and screenshots in the report.

Configure and enable indexing for all connections that you want to include in the reports.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting/content_subchapters

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available content subchapters.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/content_subchapters

The following command retrieves the properties of a specific subchapter.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/content_subchapters/<subchapter-key>

Response

The following is a sample response received when listing content subchapters. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/content_subchapters",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/custom_subchapters",
    "parent": "/api/configuration/reporting",
    "previous": null,
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "13869311625707e0a3e0892",
      "meta": {
        "href": "/api/configuration/reporting/content_subchapters/13869311625707e0a3e0892"
      }
    }
  ]
}

When retrieving the endpoint of a specific content subchapter, the response is the following.

{
  "body": {
    "access": [
      "search"
    ],
    "filter": {
      "channel_policy": {
        "key": "-10200",
        "meta": {
          "href": "/api/configuration/ssh/channel_policies/-10200"
        }
      },
      "connection_policy": "8348340645707e2575e3c6",
      "protocol": "ssh",
      "server_address": "192.168.56.102",
      "server_port": 22,
      "source_address": "192.168.56.101",
      "source_port": 22,
      "username": "admin"
    },
    "name": "API_test_subchapter",
    "search_words": [
      "logout"
    ]
  },
  "key": "13869311625707e0a3e0892",
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters/13869311625707e0a3e0892",
    "href": "/api/configuration/reporting/content_subchapters/13869311625707e0a3e0892",
    "last": "/api/configuration/reporting/content_subchapters/13869311625707e0a3e0892",
    "next": null,
    "parent": "/api/configuration/reporting/content_subchapters",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the subchapter.
body     Top level element (string) The elements of the subchapter.
  access   list

Required. List of access control groups whose members can access the subchapter.

To deny access to the subchapter, use "admin" as the only value for the element.

  filter   Top level element. Filter options for narrowing the scope of the keyword search. See the corresponding table for more details.
    channel_policy string

References the key of the channel policy. You can configure channel policies at the "/api/configuration/<protocol>/channel_policies/<policy-ID>" endpoint.

Note that the path is different for each protocol.

To modify or add a channel policy, use the value of the returned key as the value of the channel_policy element, and remove any child elements (including the key).

    connection_policy string

The key of the connection policy specified for the search.

To use a connection policy, you must also set the protocol using the protocol element.

    protocol string

The protocol of the connection or channel policy specified for the search.

    server_address string

The target server's address.

Use an IPv4 address.

    server_port int The port of the target server's address.
    source_address string The address from where the connection is initiated.
    source_port int The port of the address from where the connection is initiated.
    username string The username used to connect to the target server.
  name   string The name of the subchapter.
  search_words   list The list of search keywords to generate statistics and screenshots for in the subchapter.

Examples: 

Create a content subchapter for the occurences of the "logout" keyword in SSH connections. Make the subchapter accessible to the search and report usergroups.

  • Search connections where the "shell-only" channel policy is used.

    {
      "access": [
        "search",
        "report"
      ],
      "filter": {
        "channel_policy": "-10000",
        "connection_policy": null,
        "protocol": "ssh",
        "server_address": null,
        "server_port": null,
        "source_address": null,
        "source_port": null,
        "username": null
      },
      "name": "Shell_access",
      "search_words": [
        "logout"
      ]
    }
  • Search connections of a specific connection policy. Provide the protocol of the connection. The key of the connection policy is available at the /api/configuration/<protocol>/connections/ endpoint.

    {
      "access": [
        "search",
        "report"
      ],
      "filter": {
        "channel_policy": null,
        "connection_policy": "<key-of-connection-policy>",
        "protocol": "ssh",
        "server_address": null,
        "server_port": null,
        "source_address": null,
        "source_port": null,
        "username": null
      },
      "name": "Controlled_access",
      "search_words": [
        "logout"
      ]
    }
  • Search connections where the "admin" username was used.

    {
      "access": [
        "search",
        "report"
      ],
      "filter": {
        "channel_policy": null,
        "connection_policy": null,
        "protocol": "ssh",
        "server_address": null,
        "server_port": null,
        "source_address": null,
        "source_port": null,
        "username": "admin"
      },
      "name": "Login_as_admin",
      "search_words": [
        "logout"
      ]
    }
  • Search connections made to a specific server address and port.

    {
      "access": [
        "search",
        "report"
      ],
      "filter": {
        "channel_policy": null,
        "connection_policy": null,
        "protocol": "ssh",
        "server_address": "<server-ip>",
        "server_port": <port>,
        "source_address": null,
        "source_port": null,
        "username": null
      },
      "name": "Server_access",
      "search_words": [
        "logout"
      ]
    }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
400

Path: <endpoint>/filter/channel_policy

Type: SyntacticError

You have included the key and meta elements of a channel_policy in a PUT or POST request.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a content subchapter

To add a content subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new content subchapter.

    You can find a detailed description of the available parameters listed in Content subchapters.

  • To use a channel policy for filtering, use the key of the policy. You must also set the protocol element to the corresponding protocol.

    For example, to use the shell-only channel policy, which is a default SSH policy provided by SCB, you have to configure both the channel_policy element…

    "channel_policy": "-10000"

    …and the protocol element:

    "protocol": "ssh"

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/content_subchapters/ endpoint. If the POST request is successful, the response includes the key of the new subchapter. For example:

{
  "key": "416bb324-b44e-4ed3-a49d-02e99e53e941",
  "meta": {
    "href": "/api/configuration/reporting/content_subchapters/416bb324-b44e-4ed3-a49d-02e99e53e941",
    "parent": "/api/configuration/reporting/content_subchapters",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a content subchapter

To modify a content subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the subchaper.

    You can find a detailed description of the available parameters listed in Content subchapters

  • To use a channel policy for filtering, do not include the returned key and meta elements of the channel policy in your PUT request. Instead, set the value of the channel_policy to the value of its key.

    For example, if a GET request for the subchapter returns the following channel_policy filter:

    "channel_policy": {
      "key": "-10200",
      "meta": {
        "href": "/api/configuration/ssh/channel_policies/-10200"
      }
    }

    You have to change it in your PUT request to:

    "channel_policy": "-10200"

    You must also configure the protocol element to the protocol of the channel policy.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/content_subchapters/<subchapter-key> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.13. Custom subchapters

List of the reporting subchapters created from custom queries to the SCB connection database. The list of tables and fields you can query are described in Section 19.5, Database tables available for custom queries in The Balabit Shell Control Box 4 F3 Administrator Guide.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting/custom_subchapters

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available custom subchapters.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/custom_subchapters

The following command retrieves the properties of a specific subchapter.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/custom_subchapters/<object-id>

Response

The following is a sample response received when listing custom subchapters. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/custom_subchapters",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/predefined_reports",
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/content_subchapters",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "5983143445707eb740fee3",
      "meta": {
        "href": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3"
      }
    }
  ]
}

When retrieving the endpoint of a specific subchapter, the response is the following.

{
  "body": {
    "access": [
      "search"
    ],
    "chart": {
      "column_titles": [
        "col1",
        "col2"
      ],
      "type": "list"
    },
    "name": "API_test_adv_stats",
    "query": "select\n  to_timestamp(audit_trail_downloads.download_time),\n  audit_trail_downloads.username,\n  channels.channel_type,\n  channels.connection,\n  audit_trail_downloads.ip\nfrom audit_trail_downloads,\n     channels\nwhere channels._connection_channel_id = audit_trail_downloads.id\nand audit_trail_downloads.download_time <= :range_start\nand audit_trail_downloads.download_time > :range_end\nand audit_trail_downloads.username != 'admin'\norder by audit_trail_downloads.download_time;"
  },
  "key": "5983143445707eb740fee3",
  "meta": {
    "first": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "href": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "last": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "next": null,
    "parent": "/api/configuration/reporting/custom_subchapters",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the custom subchapter.
body     Top level element (string) The elements of the custom subchapter.
  access   list

Required. List of access control groups whose members can access the subchapter.

To deny access to the subchapter, use "admin" as the only value for the element.

  chart   Top level element Defines the properties of the chart generated from the database query.
    type string

Defines the chart type.

  • Use bar to generate a bar chart.

    You have to provide the y_axis_title element for bar charts (its can be null).

  • Use pie to generate pie a chart.

  • Use list to generate a list.

    You have to provide the column_titles element for lists (it can be null).

    y_axis_title string

Required if the type element is set to bar.

The name of the y axis for the generated bar chart.

    column_titles list

Required if the type element is set to list.

The column titles for the generated list.

  name   string The name of the subchapter.
  query   string The SQL database query for creating the subchapter.

Examples: 

Create a bar chart with a custom title for the y-axis:

"chart": {
  "type": "bar",
  "y_axis_title": "Y_axis"
}

Create a pie chart:

"chart": {
  "type": "pie"
}

Create a list with custom column names:

"chart": {
  "column_titles": [
    "col1",
    "col2"
  ],
  "type": "list"
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a custom subchapter

To add a custom subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new subchapter.

    You can find a detailed description of the available parameters listed in Custom subchapters.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/custom_subchapters endpoint. If the POST request is successful, the response includes the key of the new subchapter. For example:

{
  "key": "9a8f7f19-edbf-4327-9d3a-9f527e7331ee",
  "meta": {
    "href": "/api/configuration/reporting/custom_subchapters/9a8f7f19-edbf-4327-9d3a-9f527e7331ee",
    "parent": "/api/configuration/reporting/custom_subchapters",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a custom subchapter

To modify a subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the subchapter.

    You can find a detailed description of the available parameters listed in Custom subchapters.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/custom_subchapters/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.14. Connection statistics subchapters

List of the reporting subchapters created from connection statistics.

URL

GET https://<IP-address-of-SCB>/api/configuration/reporting/statistics_subchapters

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available subchapters.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/statistics_subchapters

The following command retrieves the properties of a specific subchapter.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/reporting/statistics_subchapters/<subchapter-id>

Response

The following is a sample response received when listing connection statistics subchapters. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/statistics_subchapters",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": null,
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/reports",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "21111736175707f1df8bea1",
      "meta": {
        "href": "/api/configuration/reporting/statistics_subchapters/21111736175707f1df8bea1"
      }
    }
  ]
}

When retrieving the endpoint of a specific subchapter, the response is the following.

{
  "body": {
    "access": [
      "search",
      "reporting"
    ],
    "chart": {
      "type": "list"
    },
    "name": "stats_simple",
    "query": {
      "column": "username",
      "filter": [
        {
          "column": "protocol",
          "is_exact": false,
          "is_inverted": false,
          "value": "ssh"
        },
        {
          "column": "username",
          "is_exact": false,
          "is_inverted": false,
          "value": "admin"
        }
      ],
      "limit": 15,
      "order": "top"
    }
  },
  "key": "496444806570e9c7e32c30",
  "meta": {
    "first": "/api/configuration/reporting/statistics_subchapters/21111736175707f1df8bea1",
    "href": "/api/configuration/reporting/statistics_subchapters/496444806570e9c7e32c30",
    "last": "/api/configuration/reporting/statistics_subchapters/496444806570e9c7e32c30",
    "next": null,
    "parent": "/api/configuration/reporting/statistics_subchapters",
    "previous": "/api/configuration/reporting/statistics_subchapters/1539306268570e9442cab6c",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the subchapter.
body     Top level element (string) The elements of the subchapter.
  access   list

Required. List of access control groups whose members can access the subchapter.

To deny access to the subchapter, use "admin" as the only value for the element.

  chart   Top level element Defines the properties of the chart generated from the database query.
    type string

Defines the chart type.

  • Use bar to generate a bar chart.

  • Use pie to generate pie a chart.

  • Use list to generate a list.

  name   string The name of the subchapter.
  query   string The search query that defines the connections to use for creating statistics.

Examples: 

Create statistics about the 15 most common usernames used in SSH connections.

  • Create a bar chart.

    {
      "access": [
        "reporting",
        "search"
      ],
      "chart": {
        "type": "bar"
      },
      "name": "stats_bar",
      "query": {
        "column": "username",
        "filter": [
          {
            "column": "protocol",
            "is_exact": false,
            "is_inverted": false,
            "value": "ssh"
          }
        ],
        "limit": 15,
        "order": "top"
      }
    }
  • Create a pie chart.

    {
      "access": [
        "reporting",
        "search"
      ],
      "chart": {
        "type": "pie"
      },
      "name": "stats_pie",
      "query": {
        "column": "username",
        "filter": [
          {
            "column": "protocol",
            "is_exact": false,
            "is_inverted": false,
            "value": "ssh"
          }
        ],
        "limit": 15,
        "order": "top"
      }
    }
  • Create a list.

    {
        "access": [
          "reporting",
          "search"
        ],
        "chart": {
          "type": "list"
        },
        "name": "stats_list",
        "query": {
          "column": "username",
          "filter": [
            {
              "column": "protocol",
              "is_exact": false,
              "is_inverted": false,
              "value": "ssh"
            }
          ],
          "limit": 15,
          "order": "top"
        }
      }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a connection statistics subchapter

To add a connection statistics subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new subchapter.

    You can find a detailed description of the available parameters listed in Connection statistics subchapters.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/statistics_subchapters/ endpoint. If the POST request is successful, the response includes the key of the new subchapter. For example:

{
  "key": "769e627d-515d-4d26-a03e-cb2ed0bbee04",
  "meta": {
    "href": "/api/configuration/reporting/statistics_subchapters/769e627d-515d-4d26-a03e-cb2ed0bbee04",
    "parent": "/api/configuration/reporting/statistics_subchapters",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a connection statistics subchapter

To modify a subchapter, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the subchapter.

    You can find a detailed description of the available parameters listed in Connection statistics subchapters.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/reporting/statistics_subchapters//<key-of-the-subchapter> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.15. SSH connections

List of endpoints for configuring the policies, options and connection rules of SSH connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for SSH connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "authentication_policies",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies"
      }
    },
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/ssh/channel_policies"
      }
    },
    {
      "key": "connections",
      "meta": {
        "href": "/api/configuration/ssh/connections"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/ssh/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/ssh",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/telnet",
    "parent": "/api/configuration",
    "previous": "/api/configuration/reporting",
    "transaction": "/api/transaction"
  }
}
Item Description
authentication_policies List of the default and custom authentication policies.
channel_policies List of the default and custom channel policies.
connections List of connection policies.
options List of global SSH options that affect all connections.
settings_policies List of protocol-level settings (algorithms, greetings and banners, timeout). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.16. Global SSH options

List of options that affect all SSH connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global SSH options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/options

Response

The following is a sample response received when listing global SSH options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "channel_database_cleanup_days": 600,
        "enabled": true
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "gssapi": {
      "enabled": false
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/options",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/settings_policies",
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/connections",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global SSH options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable SSH connections, and specify the logging detail.
    enabled boolean Set to true to enable SSH connections.
    log_level int Defines the logging detail of SSH connections.
  gssapi   Top level item Deprecated setting.
Elements of audit Type Description
cleanup     Top level item Global retention settings for SSH connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of SSH connections, in days. Must exceed the retention time of the archiving policy (or policies) used for SSH connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of SSH connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for SSH connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "gssapi": {
    "enabled": false
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Modify global SSH settings

To modify global SSH settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global SSH settings endpoint.

    You can find a detailed description of the available parameters listed in Global SSH options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.17. SSH settings policies

SSH settings policies define protocol-level settings (algorithms, greetings and banners, timeout). You can create multiple policies, and choose the appropriate one for each SSH connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists SSH settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/settings_policies/<policy-id>

Response

The following is a sample response received when listing SSH settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-300",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies/-300"
      }
    },
    {
      "key": "236283841571912b948b88",
      "meta": {
        "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/settings_policies",
    "last": "/api/configuration/ssh/settings_policies",
    "next": null,
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "client_side_algorithms": {
      "cipher": [
        "aes128-ctr",
        "aes192-ctr",
        "aes256-ctr"
      ],
      "compression": [
        "none"
      ],
      "kex": [
        "diffie-hellman-group14-sha1"
      ],
      "mac": [
        "hmac-sha2-256",
        "hmac-sha2-512"
      ]
    },
    "greeting": "Welcome!",
    "name": "API_SSH_Setting",
    "preconnect_channel_check": true,
    "server_side_algorithms": {
      "cipher": [
        "aes128-ctr",
        "aes192-ctr",
        "aes256-ctr"
      ],
      "compression": [
        "none"
      ],
      "kex": [
        "diffie-hellman-group14-sha1"
      ],
      "mac": [
        "hmac-sha2-256",
        "hmac-sha2-512"
      ]
    },
    "software_version": "SSH",
    "strict_mode": true,
    "timeout": 600,
    "userauth_banner": "This is a monitored connection."
  },
  "key": "236283841571912b948b88",
  "meta": {
    "first": "/api/configuration/ssh/settings_policies/-300",
    "href": "/api/configuration/ssh/settings_policies/236283841571912b948b88",
    "last": "/api/configuration/ssh/settings_policies/236283841571912b948b88",
    "next": null,
    "parent": "/api/configuration/ssh/settings_policies",
    "previous": "/api/configuration/ssh/settings_policies/-300",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element (string) The elements of the SSH settings policy.
  client_side_algorithms   Top level element (list) Lists the permitted client-side encryption parameters.
    cipher list Lists the permitted client-side cipher algorithms.
    compression list Lists the permitted client-side compression algorithms.
    kex list Lists the permitted client-side KEX algorithms.
    mac list Lists the permitted client-side MAC algorithms.
  greeting   string Greeting message for the connection.
  name   string Name of the SSH settings policy.
  preconnect_channel_check   boolean

Before establishing the server-side connection, SCB can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server.

To enable this function, set the parameter to true.

  server_side_algorithms   Top level element (list) Lists the permitted server-side encryption parameters.
    cipher list Lists the permitted server-side cipher algorithms.
    compression list Lists the permitted server-side compression algorithms.
    kex list Lists the permitted server-side KEX algorithms.
    mac list Lists the permitted server-side MAC algorithms.
  software_version   string Specifies additional text to append to the SSH protocol banner sent by the server upon connection.
  strict_mode   boolean

When this option is enabled, SCB rejects connections that use unrealistic parameters (for example, terminals of thousand by thousand characters) and port-forwarding connections where the address in the port-forwarding request and the channel-opening request does not match. Note that this can interfere with certain client or server applications.

Strict mode is allowed by default. To turn it off, set the parameter to false.

  timeout   int Connection timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.
  userauth_banner   string You can display a banner message to the clients before authentication (as specified in RFC 4252 — The Secure Shell (SSH) Authentication Protocol). You can use this banner to inform the users that the connection is audited.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add SSH settings policies

To add a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new policy.

    You can find a detailed description of the available parameters listed in SSH Settings Policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/settings_policies/ endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "59790911-415c-4ed3-a0d2-1164637472ca",
  "meta": {
    "href": "/api/configuration/ssh/settings_policies/59790911-415c-4ed3-a0d2-1164637472ca",
    "parent": "/api/configuration/ssh/settings_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify SSH settings policies

To modify a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the policy.

    You can find a detailed description of the available parameters listed in SSH Settings Policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/settings_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.18. SSH authentication policies

Lists the configured authentication methods that can be used in a connection. Each connection policy uses an authentication policy to determine how the client can authenticate to the target server. Separate authentication methods can be used on the client and the server-side of the connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists SSH authentication policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies<object-id>

Response

The following is a sample response received when listing SSH authentication policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-200",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/-200"
      }
    },
    {
      "key": "1895203635707e3340262f",
      "meta": {
        "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/authentication_policies",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/channel_policies",
    "parent": "/api/configuration/ssh",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "mode": {
      "gateway_authentication": {
        "selection": "none"
      },
      "gssapi": false,
      "relayed_methods": {
        "certificate": {
          "selection": "disabled"
        },
        "keyboard_interactive": true,
        "password": true,
        "public_key": {
          "selection": "disabled"
        }
      }
    },
    "name": "base"
  },
  "key": "-200",
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies/-200",
    "href": "/api/configuration/ssh/authentication_policies/-200",
    "last": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "next": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f",
    "parent": "/api/configuration/ssh/authentication_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element Contains the elements of the policy.
  mode   Top level element Contains the configuration of the policy.
    gateway_authentication Top level item Client-side gateway authentication settings. The value of selection defines which authentication method is used.
    relayed_methods Top level element Server-side authentication settings.
    gssapi boolean Deprecated setting.
  name   string The name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
Elements of gateway_authentication Type Description
selection     string

Defines the authentication method for client-side gateway authentication. Possible values are:

  • none

    Disables client-side gateway authentication.

  • ldap

    Uses the LDAP server configured in the /api/configuration/policies/ldap_servers endpoint).

    To use this option, you must also configure the certificate, password, and public_key elements.

  • local

    Uses the local user database configured in the /api/configuration/policies/user_databases/ endpoint.

    To use this option, you must also configure the certificate, password, public_key, and user_database elements.

  • radius

    Uses one or more Radius servers for authentication.

    To use this option, you must also configure the servers element.

certificate     Top level item

Configures authentication with an X.509 certificate.

The enabled child element is required for this option. To enable it, you must also configure the trusted_ca child element.

  enabled   boolean

Possible values:

  • true

    Enables client-side, X.509 certification-based authentication. You must also use the trusted_ca element to define a certificate authority.

  • false

    Disables client-side, X.509 certificate-based authentication.

  trusted_ca   string

References the key of the trusted CA. You can configure trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

password     boolean

Authentication based on username and password.

Set it to true to enable password-based client-side authentication.

public_key     boolean

Authentication based on public-private encryption keypairs.

Set it to true to enable public key-based client-side authentication.

user_database     string

References the key of the local user database. You can configure local user databases at the /api/configuration/policies/user_databases/ endpoint.

To modify or add a local user database, use the value of the returned key as the value of the user_database element, and remove any child elements (including the key).

servers     Top level list

Defines the properties of the RADIUS servers used for client-side authentication.

A valid list item consists of the address, port and shared_secret elements.

  address   Top level element Defines the address of a RADIUS server.
    selection string

Required child of the address element. Possible values are:

  • ip

    The value element contains the IP of the RADIUS server.

  • fqdn

    The value element contains the FQDN of the RADIUS server.

    value string The IP or the FQDN address of the RADIUS server.
  port   int The port number of the RADIUS server.
  shared_secret   string

References the key of the shared secret for the RADIUS server. You can configure shared secrets at the /api/configuration/passwords/ endpoint.

To modify or add a shared secret, use the value of the returned key as the value of the shared_secret element, and remove any child elements (including the key).

Elements of relayed_authentication Type Description
certificate   Top level item

Authentication based on X.509 certificates.

Use the selection child element to disable or configure authentication using X.509 certificates on the remote server.

  selection string

  • agent

    Allows the SSH client to use agent-forwarding, and use its own certificate on the server-side.

  • disabled

    Disables the authentication method.

  • fix

    Use the specified private key and certificate in the server-side connection.

    You have to use the X509_identity element to reference the private key and certificate.

  • generate

    SCB generates an X.509 certificate and the corresponding private key for every connection policy, and uses this certificate in the server-side connections.

    You have to use the signing_CA element to reference a signing certificate authority.

  • publish_to_ldap

    SCB generates an X.509 certificate and the corresponding private key for every connection policy, and uses this certificate in the server-side connections. The certificate is also uploaded to the LDAP database set in the LDAP Server of the connection policy. That way the server can authenticate the client to the generated certificate stored under the user's username in the LDAP database. You can configure LDAP servers using the /api/configuration/policies/ldap_servers endpoint, and connection policies using the /api/configuration/ssh/connections endpoint.

    You have to use the signing_CA element to reference a signing certificate authority.

  X509_identity string

References the private key and certificate used for authenticating on the remote server. You can configure X.509 certificates and keys at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate and private key, use the value of the returned key as the value of the X509_identity element, and remove any child elements (including the key).

  signing_CA string

References the Certificate Authority (CA) used for signing certificates. You can configure signing CAs at the /api/configuration/policies/signing_cas/ endpoint.

To modify or add a signing CA, use the value of the returned key as the value of the X509_identity element, and remove any child elements (including the key).

keyboard_interactive   boolean

Authentication based on exchanging messages between the user and the server. This method includes authentication schemes like S/Key or TIS authentication. Depending on the configuration of the SSH server, might have to be used together with password-based authentication.

Set to true to enable interactive authentication on the remote server.

password   boolean

Authentication based on username and password.

Set to true to enable password-based authentication on the remote server.

public_key   Top level item

Authentication based on public-private encryption keypairs.

Use the selection child element to disable or configure authentication using public-private keypairs on the remote server.

  selection string

Configures authenticaton on the remote server using public-private keypairs. The following values are possible:

  • disabled

    Disables the authentication method.

  • publish_to_ldap

    SCB generates a keypair, and uses this keypair in the server-side connection. The public key of this keypair is also uploaded to the LDAP database set in the LDAP Server of the connection policy. That way the server can authenticate the client to the generated public key stored under the user's username in the LDAP database. You can configure LDAP servers using the /api/configuration/policies/ldap_servers endpoint, and connection policies using the /api/configuration/ssh/connections endpoint.

  • fix

    Uses a private key in the server-side connection.

    You have to use the private_key element to reference the private key.

  • agent

    Allow the client to use agent-forwarding, and use its own keypair on the server-side. If this option is used, SCB requests the client to use its SSH agent to authenticate on the target server.

  private_key string

References the key of the private key used for authenticating with a public-private keypair on the remote server. You can configure private keys at the /api/configuration/private_keys/ endpoint.

To modify or add a private key, use the value of the returned key as the value of the private_key element, and remove any child elements (including the key).

Examples: 

Password authentication against LDAP on the client side, and using a username and password on the remote server:

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": false
      },
      "password": true,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "Passwords"
}

Password authentication against a local user database on SCB, and using a username and password on the remote server. You can find the key of the local user database is available at the /api/configuration/policies/user_databases/ endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": false
      },
      "password": true,
      "public_key": {
        "enabled": false
      },
      "selection": "local",
      "user_database": <key-of-the-local-usr-db>
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "Local_usr_db"
}

Authenticating against an RADIUS server on the client side, and using a username and password on the remote server. The key of the shared secret is available at the /api/configuration/passwords/ endpoint. The IP of the RADIUS server is used.

{
  "mode": {
    "gateway_authentication": {
      "selection": "radius",
      "servers": [
        {
          "address": {
            "selection": "ip",
            "value": "<radius-server-ip>"
          },
          "port": 1812,
          "shared_secret": <key-of-shared-secret>
        }
      ]
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "disabled"
      },
      "keyboard_interactive": false,
      "password": true,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "RADIUS"
}

Using X.509 certificates against an LDAP server on the client-side, and forwarding it for authentication on the server-side. The key of the trusted Certificate Authority (CA) is available at the /api/configuration/policies/trusted_ca_lists endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": true,
        "trusted_ca": <key-of-trusted-ca>
      },
      "password": false,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "agent"
      },
      "keyboard_interactive": false,
      "password": false,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "X509_forwarding"
}

Using X.509 certificates against an LDAP server on the client-side, and generating X.509 certificate and key on the fly for authentication on the server-side. The generated keys are uploaded to the LDAP server, so that SCB can authenticate the user on the remote server. The key of the trusted Certificate Authority (CA) is available at the /api/configuration/policies/trusted_ca_lists/ endpoint. The key of the signing Certificate Authority (CA) is available at the /api/configuration/policies/signing_cas/ endpoint.

{
  "mode": {
    "gateway_authentication": {
      "certificate": {
        "enabled": true,
        "trusted_ca": <key-of-trusted-ca>
      },
      "password": false,
      "public_key": {
        "enabled": false
      },
      "selection": "ldap"
    },
    "gssapi": false,
    "relayed_methods": {
      "certificate": {
        "selection": "publish_to_ldap",
        "signing_ca": <key-of-signing-ca>
      },
      "keyboard_interactive": false,
      "password": false,
      "public_key": {
        "selection": "disabled"
      }
    }
  },
  "name": "X509"
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add an SSH authentication policy

To add an SSH authentication policy, you have to:

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies/ endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "6f924f39-e4c9-4b0f-8018-8842e2115ebd",
  "meta": {
    "href": "/api/configuration/ssh/authentication_policies/6f924f39-e4c9-4b0f-8018-8842e2115ebd",
    "parent": "/api/configuration/ssh/authentication_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify an SSH authentication policy

To modify an SSH authentication policy, you have to:

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/authentication_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.19. SSH connection policies

Connection policies determine if a server can be accessed from a particular client. Connection policies reference other resources (policies, usergroups, keys) that must be configured and available before creating a connection policy.

URL

GET https://<IP-address-of-SCB>/api/configuration/ssh/connections/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists SSH connection policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/connections/

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ssh/connections/<connection-key>

Response

The following is a sample response received when listing SSH connection policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "8348340645707e2575e3c6",
      "meta": {
        "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ssh/authentication_policies",
    "href": "/api/configuration/ssh/connections",
    "last": "/api/configuration/ssh/settings_policies",
    "next": "/api/configuration/ssh/options",
    "parent": "/api/configuration/ssh",
    "previous": "/api/configuration/ssh/channel_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific SSH connection policy, the response is the following.

{
  "body": {
    "access_control": [
      {
        "authorizer": "reporting",
        "permission": "audit_and_authorize",
        "require_different_ip": true,
        "require_different_username": true,
        "subject": {
          "selection": "everybody"
        }
      }
    ],
    "active": true,
    "channel_database_cleanup": {
      "days": 550,
      "enabled": true
    },
    "client_side_hostkey": {
      "plain_hostkey": {
        "dsa_key": null,
        "enabled": true,
        "rsa_key": {
          "key": "e5a58682-6189-4477-9415-67c1c9b20b0d",
          "meta": {
            "href": "/api/configuration/private_keys/e5a58682-6189-4477-9415-67c1c9b20b0d"
          }
        }
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "indexing": {
      "enabled": true,
      "policy": {
        "key": "-50000",
        "meta": {
          "href": "/api/configuration/policies/indexing/-50000"
        }
      },
      "priority": 2
    },
    "log_audit_trail_downloads": true,
    "name": "API_test_SSH",
    "network": {
      "clients": [
        "0.0.0.0/24"
      ],
      "ports": [
        22
      ],
      "targets": [
        "192.168.56.102/24"
      ]
    },
    "policies": {
      "aa_plugin": null,
      "archive_cleanup_policy": {
        "key": "1854671967571b9063c4c82",
        "meta": {
          "href": "/api/configuration/policies/archive_cleanup_policies/1854671967571b9063c4c82"
        }
      },
      "audit_policy": {
        "key": "78101850949e47437dd91d",
        "meta": {
          "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
        }
      },
      "authentication_policy": {
        "key": "1895203635707e3340262f",
        "meta": {
          "href": "/api/configuration/ssh/authentication_policies/1895203635707e3340262f"
        }
      },
      "backup_policy": {
        "key": "512524636571b903540804",
        "meta": {
          "href": "/api/configuration/policies/backup_policies/512524636571b903540804"
        }
      },
      "channel_policy": {
        "key": "-10000",
        "meta": {
          "href": "/api/configuration/ssh/channel_policies/-10000"
        }
      },
      "credential_store": {
        "key": "505008562571b936560254",
        "meta": {
          "href": "/api/configuration/policies/credentialstores/505008562571b936560254"
        }
      },
      "ldap_server": {
        "key": "250588254571b931066482",
        "meta": {
          "href": "/api/configuration/policies/ldap_servers/250588254571b931066482"
        }
      },
      "settings": {
        "key": "-300",
        "meta": {
          "href": "/api/configuration/ssh/settings_policies/-300"
        }
      },
      "ticketing_policy": null,
      "usermapping_policy": {
        "key": "9328731525704545f5e3de",
        "meta": {
          "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
        }
      }
    },
    "rate_limit": {
      "enabled": true,
      "value": 200
    },
    "server_address": {
      "selection": "original"
    },
    "server_side_hostkey": {
      "plain_hostkey": {
        "enabled": true,
        "hostkey_check": "accept-first-time"
      },
      "x509_hostkey": {
        "enabled": false
      }
    },
    "source_address": {
      "selection": "box_address"
    },
    "web_gateway_authentication": {
      "enabled": true,
      "groups": [
        "reporting"
      ],
      "require_same_ip": true
    }
  },
  "key": "8348340645707e2575e3c6",
  "meta": {
    "first": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "href": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "last": "/api/configuration/ssh/connections/8348340645707e2575e3c6",
    "next": null,
    "parent": "/api/configuration/ssh/connections",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the SSH connection policy.
body     Top level element (string) The elements of the SSH connection policy.
  access_control   Top level list Collection of access policies. Access policies define who can authorize and audit a connection.
  active   boolean Set to false to suspend the connection policy. Connection settings are preserved.
  channel_database_cleanup   Top level item Configures cleanup of the connection metadata on the connection policy's level.
    days int

Retention time, in days. Must not exceed the retention time of the archive_cleanup_policy, and the retention time configured in the global settings of the SSH protocol.

The global settings of the SSH protocol are available at the api/configuration/ssh/options endpoint.

    enabled boolean Set to true to enable periodical cleanup of the connection metadata.
  client_side_hostkey   Top level item The host keys and X.509 certificates SCB shows to clients.
  indexing   Top level item Configures indexing for the connection policy.
    enabled boolean Set to true to enable indexing the connections.
    policy string

References the identifier of the indexing policy. You can configure indexing policies at the /api/configuration/policies/indexing/ endpoint.

To modify or add an indexing policy, use the value of the returned key as the value of the policy element, and remove any child elements (including the key).

    priority int

Specifies the indexing priority for the connection. Possible values are:

  • 4

    Very low priority.

  • 3

    Low priority.

  • 2

    Normal (default) priority.

  • 1

    High priority.

  • 0

    Very high priority.

  log_audit_trail_downloads   boolean

Set to true to log audit trail downloads.

  name   string The name of the connection policy.
  network      
    clients list, string List of client ("from") IP addresses.
    ports list, int List of target ports.
    targets list, string List of target IP addresses.
  policies   Top level item List of policies referenced by the connection policy.
    aa_plugin string

References the identifier of the AA plug-in. You can configure AA plug-ins at the /api/configuration/plugins/aa/ endpoint.

To modify or add an AA plug-in, use the value of the returned key as the value of the aa_plugin element, and remove any child elements (including the key).

    archive_cleanup_policy string

References the identifier of the archive/cleanup policy. You can configure archive/cleanup policies at the /api/configuration/policies/archive_cleanup_policies/ endpoint.

To modify or add an archive/cleanup policy, use the value of the returned key as the value of the archive_cleanup_policy element, and remove any child elements (including the key).

    audit_policy string

Cannot be null.

References the identifier of the audit policy. You can configure audit policies at the /api/configuration/policies/audit_policies/ endpoint.

To modify or add an audit policy, use the value of the returned key as the value of the audit_policy element, and remove any child elements (including the key).

    authentication_policy string

Cannot be null.

References the identifier of the authentication policy. You can configure authentication policies at the /api/configuration/ssh/authentication_policies/ endpoint.

To modify or add an authentication policy, use the value of the returned key as the value of the authentication_policy element, and remove any child elements (including the key).

    backup_policy string

References the identifier of the backup policy. You can configure backup policies at the /api/configuration/policies/backup_policies/ endpoint.

To modify or add a backup policy, use the value of the returned key as the value of the backup_policy element, and remove any child elements (including the key).

    channel_policy string

Cannot be null.

References the identifier of the channel policy. You can configure channel policies at the /api/configuration/ssh/channel_policies/ endpoint.

To modify or add a channel policy, use the value of the returned key as the value of the channel_policy element, and remove any child elements (including the key).

    credential_store string

References the identifier of the credential store. You can configure credential stores at the /api/configuration/policies/credentialstores/ endpoint.

To modify or add a credential store, use the value of the returned key as the value of the credential_store element, and remove any child elements (including the key).

    ldap_server string

References the identifier of the LDAP server. You can configure LDAP servers at the /api/configuration/policies/ldap_servers/ endpoint.

To modify or add an LDAP server, use the value of the returned key as the value of the ldap_server element, and remove any child elements (including the key).

    settings string

Cannot be null.

References the identifier of the SSH settings policy. You can configure SSH settings policies at the /api/configuration/ssh/settings_policies/ endpoint.

To modify or add an SSH settings policy, use the value of the returned key as the value of the settings element, and remove any child elements (including the key).

    ticketing_policy string

References the identifier of the ticketing policy. You can configure ticketing policies at the /api/configuration/policies/usermapping_policies/ endpoint.

To modify or add a ticketing policy, use the value of the returned key as the value of the ticketing_policy element, and remove any child elements (including the key).

  rate_limit   Top level element Connection rate limit.
    enabled boolean Set to true to provide a connection rate limit.
    value int The number of connections (per minute) that are allowed in the connection policy.
  server_address   Top level item Defines the address where the clients connect to.
  server_side_hostkey   Top level element

Settings for verifying the server's identity using plain hostkeys and X.509 host certificates.

At least one of the options (plain_hostkey or X509_hostkey) must be enabled.

  source_address   Top level element Allows you to configure Source Network Address Translation (SNAT) on the server side of SCB. SNAT determines the IP address SCB uses in the server-side connection. The target server will see the connection coming from this address.
    selection string

Configures Source Network Address Translation. Possible values are:

  • box_address

    Default. Uses the network address of the logical interface of SCB.

  • original

    Uses the IP address of the client, as seen by SCB.

  • fix

    Uses a fixed address when connecting to the remote server.

    Must be used with the address element.

    address string

Must be used if the value of the selection element is set to fix.

The IP address to use as the source address in server-side connections.

  web_gateway_authentication   Top level item When gateway authentication is required for a connection, the user must authenticate on SCB as well. This additional authentication can be performed out-of-band on the SCB web interface for every protocol.
    enabled boolean Set to true to enable additional gateway authentication on the SCB web interface.
    groups list, string

By default, any user can perform gateway authentication for the connections. You can restrict authentication to members of specific usergroups. Define the usergroups at the /api/configuration/aaa/local_database/groups/ endpoint, and list the name of each groups here.

    require_same_ip boolean Set to true to only accept web gateway authentication from the same host that initiated the connection.
Elements of access_control Type Description
authorizer   string

The usergroup (local or LDAP) who can authorize or audit the connection.

Local usergroups can be added or modified at the /api/configuration/aaa/local_database/groups/ endpoint.

permission   string

Defines the permissions of the authorizer usergroup. Possible values are:

  • audit

    The usergroup with the audit permission can monitor ongoing connections, and download the audit trails of a closed and indexed connection.

  • authorize

    The usergroup with the authorize permission can authorize connection requests.

  • audit_and_authorize

    The usergroup with the audit_and_authorize permission can authorize connection requests, monitor connections, and download the audit trail of closed and indexed connections.

require_different_ip   boolean Set to true to require the authorizing user and its subject to have different IP addresses.
require_different_username   boolean Set to true to require the authorizing user and its subject to have different usernames.
subject   Top level item Defines the subjects of the access control policy.
  group string

The usergroup (local or LDAP) that is subject to the access control policy.

Locla usergroups can be added or modified at the /api/configuration/aaa/local_database/groups/ endpoint.

  selection string

Possible values:

  • everybody

    Every user is subject to the access control policy.

  • only

    Requires the group element.

    Members of the usergroup specified in the group element are subject to the access control policy.

Elements of client_side_hostkey Type Description
plain_hostkey     Top level item Configures the RSA and DSA keys SCB shows to the clients.
  dsa_key   string

References the identifier of the DSA key. You can add DSA keys at the /api/configuration/private_keys/ endpoint.

To modify or add a DSA key, use the value of the returned key as the value of the dsa_key element, and remove any child elements (including the key).

  enabled   boolean

Set to true to allow presenting DSA and RSA keys to clients.

You must enable either plain_hostkey or x509_hostkey (or both).

  rsa_key   string

References the identifier of the RSA key. You can add RSA keys at the /api/configuration/private_keys/ endpoint.

To modify or add an RSA key, use the value of the returned key as the value of the rsa_key element, and remove any child elements (including the key).

x509_hostkey     Top level item Configures the X.509 keys SCB shows to the clients.
  enabled   boolean

Set to true to allow presenting X.509 hostkeys to clients.

You must enable either plain_hostkey or x509_hostkey (or both).

  x509   Top level item Parameters for X.509 hostkeys.
    selection string

Possible values:

  • fix

    Presents the same certificate for every connection.

    Must be used with the x509_identity element.

  • generate

    Generates a X.509 certificate for the connection policy.

    Must be used with the signing_CA element.

    signing_ca string

Must be used when generating the X.509 certificate.

References the signing Certificate Authority (CA). You can configure signing CAs at the /api/configuration/policies/signing_cas/ endpoint.

To modify or add a signing CA, use the value of the returned key as the value of the rsa_key element, and remove any child elements (including the key).

    x509_identity string

Must be used when using the same X.509 host certificate across connection policies.

References the identifier of the X.509 certificate stored on SCB. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

Elements of server_address Type Description
selection     string

Configures the address where the clients connect to. Possible values are:

  • original

    Connect to the same address specified by the client.

  • nat

    Perform a network address translation on the target address.

    Must be used with the network element.

  • fix

    Must be used with the address and port elements.

  • inband

    Extract the address of the server from the username.

    Must be used with the domains element.

    Optional elements: exception_domains, dns_server, and dns_suffixes.

network     string

Must be used if selection is set to nat.

The target address in IP/prefix format. Example: "10.20.30.40/24".

address     string

Must be used if selection is set to fix.

The IP address of the target server.

port     int

Must be used if selection is set to fix.

The port of the target server.

domains     Top level list

Must be used if selection is set to inband.

  domain   Top level item Lists the address ranges that are included in the connection policy.
    selection string

Specifies if the target address range is provided as a domain or as an IP range. Possible values are:

  • address

    The value of the target address is an IP range.

  • domain

    The value of the target address is a domain.

    value string

The address range of the target server(s).

Use the selection element to specify if the address is an IP range, or a domain.

  port   int The port of the targer server(s).
exception_domains     Top level list

Can only be used if selection is set to inband.

Lists the address ranges that are excluded from the connection policy.

  domain   Top level item Contains the excluded address range.
    selection string

Specifies if the excluded address(es) are provided as a domain or as an IP range. Possible values are:

  • address

    The value of the excluded address is an IP range.

  • domain

    The value of the excluded address is a domain.

    value string

The excluded address(es).

Use the selection element to specify if the address is an IP range, or a domain.

  port   int The excluded port.
dns_server     string

Can only be used if selection is set to inband.

IP address or the hostname of the domain name server used to resolve the address of the target server.

dns_suffixes     list, string

Can only be used if selection is set to inband.

If the clients do not include the domain name when addressing the server (for example they use username@server instead of username@server.example.com), SCB can automatically add domain information (for example example.com).

You can add multiple domain names. SCB attempts to resolve the target address by appending the domain names in the provided order, and uses the first successfully resolved address to establish the connection.

Elements of server_side_hostkey Type Description
plain_hostkey     Top level element Verifies the identity of the servers based on their hostkeys.
  enabled   boolean

Set to true to enable plain hostkey checking.

If enabled, the hostkey_check element is mandatory.

  hostkey_check   string

Defines the method for checking the host keys of the target server. Possible values are:

  • disabled

    Disables host key verification.

  • accept-first-time

    Records the key shown for the first connection, and accepts only the same key for any subsequent connections.

  • accept-known-keys

    Only accepts hostkeys that are already stored on SCB.

    You can add host keys at the /api/ssh-host-keys endpoint.

x509_hostkey     Top level element Verifies the identity of the servers based on their X.509 certificates.
  enabled   string

Set to true to enable X.509 hostkey verification.

If enabled, the x509_check element is mandatory.

  x509_check   Top level item Contains the configuration settings for verifying X.509 certificates.
    selection string

Configures the validation of X.509 certificates. Possible values are:

  • disabled

    Disables X.509 certificate verification.

  • accept-first-time

    Records the X.509 certificate shown for the first connection, and accepts only the same certificate for any subsequent connections.

  • accept-known-certificates

    Only accepts X.509 certificates that are already stored on SCB.

    You can add X.509 certificates at the /api/ssh-host-keys endpoint.

  • accept-signed-by

    Accepts all X.509 certificates that are signed by a trusted Certificate Authority.

    Must be used with the trusted_ca element.

    trusted_ca string

Must be used if the selection element is set to accept-signed-by.

References the identifier of the trusted CA. You can add or modify the list of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the ticketing_policy element, and remove any child elements (including the key).

Examples: 

Note

For practical purposes, the following examples show only the relevant parts of a connection policy JSON object. To modify or add a connection policy, always submit the full JSON object.

Access control list: configuring the "security" usergroup to only audit connections made by the "root_only" usergroup.

"access_control": [
      {
    "authorizer": "security",
    "permission": "audit",
    "require_different_ip": true,
    "require_different_username": true,
    "subject": {
      "group": "root_only",
      "selection": "only"
    }
  }
]

Client-side hostkey: use plain hostkeys uploaded to SCB, and generate X.509 certificates for the connection.

"client_side_hostkey": {
  "plain_hostkey": {
    "dsa_key": "<id-of-dsa-key>",
    "enabled": true,
    "rsa_key": "<id-of-rsa-key>"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509": {
      "selection": "generate",
      "signing_ca": "<key-of-signing-ca>"
    }
  }
}

Policies: configure only the required policies.

"policies": {
  "aa_plugin": null,
  "archive_cleanup_policy": null,
  "audit_policy": "<key-of-audit-policy>",
  "authentication_policy": "<key-of-auth-policy>",
  "backup_policy": null,
  "channel_policy": "<key-of-channel-policy>",
  "credential_store": null,
  "ldap_server": null,
  "settings": "<key-of-settings-policy>",
  "ticketing_policy": null,
  "usermapping_policy": null
}

Target server: use the address specified by the client.

"server_address": {
  "selection": "original"
}

Target server: use a fix address.

"server_address": {
  "address": "<fix-IP>",
  "port": 22,
  "selection": "fix"
}

Target server: configure inband selection, where the client can specify the target address in the username. The target can be either an IP range, or a domain.

"server_address": {
  "dns_server": "<ip-of-dns-server>",
  "dns_suffixes": null,
  "domains": [
    {
      "domain": {
        "selection": "address",
        "value": "<IP-range>"
      },
      "port": 22
    },
    {
      "domain": {
        "selection": "domain",
        "value": "*.example"
      },
      "port": 22
    }
  ],
  "selection": "inband"
}

Server-side hostkey: accept the hostkey or X.509 certificate presented at the first connection, and require the same hostkey or certificate for any subsequent connections.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": true,
    "hostkey_check": "accept-first-time"
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-first-time"
    }
  }
}

Server-side hostkey: only accept X.509 certificates that are verified by a trusted CA.

"server_side_hostkey": {
  "plain_hostkey": {
    "enabled": false
  },
  "x509_hostkey": {
    "enabled": true,
    "x509_check": {
      "selection": "accept-signed-by",
      "trusted_ca": "<id-of-trusted-ca>"
    }
  }
}

Source address: use the same fix IP when connecting to the remote server.

"source_address": {
  "address": "<ip-address>",
  "selection": "fix"
}

Web gateway authentication: require the admin usergroup to perform an additional gateway authentication on the SCB web interface. They must authenticate from the same host which initiated the connection.

"web_gateway_authentication": {
  "enabled": true,
  "groups": [
    "admin"
  ],
  "require_same_ip": true
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add an SSH connection policy

To add an SSH connection policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new SSH connection policy.

    You can find a detailed description of the available parameters listed in SSH connections.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/connections/ endpoint. If the POST request is successful, the response includes the key of the new SSH connection policy. For example:

{
  "key": "a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
  "meta": {
    "href": "/api/configuration/ssh/connections/a99be49b-b0a2-4cf9-b70d-fea1f9ea188f",
    "parent": "/api/configuration/ssh/connections",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify an SSH connection policy

To modify an SSH connection policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the SSH connection policy.

    You can find a detailed description of the available parameters listed in SSH connections.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ssh/connections/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.20. RDP connections

List of endpoints for configuring the policies, options and connection rules of RDP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for RDP connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/rdp/channel_policies"
      }
    },
    {
      "key": "domain_membership",
      "meta": {
        "href": "/api/configuration/rdp/domain_membership"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/rdp/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/rdp",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/reporting",
    "parent": "/api/configuration",
    "previous": "/api/configuration/private_keys",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
domain_membership Domain membership configuration. Prerequisite for configuring Credential Security Service Provider / Network Layer Authentication.
options List of global RDP options that affect all connections.
settings_policies List of protocol-level settings (timeout, display, protocol version, and authentication). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.21. Configuring domain membership

Joining a domain is required when using Credential Security Service Provider (CredSSP, also called Network Layer Authentication). The target servers and SCB must be in the same domain, or you must establish trust between the domains that contain the target servers and SCB.

The SCB configuration API allows you to view, disable, or modify the domain membership configuration. To join the configured domain, you have to use the web interface of SCB.

URL

GET https://<IP-address-of-SCB>/api/rdp/domain_membership

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options for domain membership.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/rdp/domain_membership

Response

The following is a sample response received when querying the domain membership configuration. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "domain": "testdomain",
    "enabled": true,
    "realm": "testdomain.api.test"
  },
  "key": "domain_membership",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/domain_membership",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/options",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the domain membership configuration.
  domain string

The name of the domain.

Must be used if enabled is set to true.

  enabled boolean Set to true to configure domain membership.
  realm string

Name of the realm.

Must be used if enabled is set to true.

Examples: 

Configure domain membership for the "test" domain on the "config.api" realm:

{
  "domain": "test",
  "enabled": true,
  "realm": "test.config.api"
}

Disable domain membership.

{
  "enabled": false
}

Modify domain membership settings

To modify domain membership settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the domain membership configuration.

    You can find a detailed description of the available parameters listed in Domain membership configuration.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/rdp/domain_embership/ endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.22. Global RDP options

List of options that affect all RDP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global RDP options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/options

Response

The following is a sample response received when listing global RDP options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/options",
    "last": "/api/configuration/rdp/settings_policies",
    "next": "/api/configuration/rdp/settings_policies",
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/domain_membership",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global RDP options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable RDP connections, and specify the logging detail.
    enabled boolean Set to true to enable RDP connections.
    log_level int Defines the logging detail of RDP connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for RDP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of RDP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for RDP connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of RDP connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for RDP connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global RDP settings

To modify global RDP settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global RDP settings endpoint.

    You can find a detailed description of the available parameters listed in Global RDP options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.23. RDP settings policies

RDP settings policies define protocol-level settings (timeout, display, protocol version, and authentication). You can create multiple policies, and choose the appropriate one for each RDP connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists RDP settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/<policy-id>

Response

The following is a sample response received when listing RDP settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-301",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/-301"
      }
    },
    {
      "key": "-303",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/-303"
      }
    },
    {
      "key": "13298899495727c51f725cf",
      "meta": {
        "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/rdp/channel_policies",
    "href": "/api/configuration/rdp/settings_policies",
    "last": "/api/configuration/rdp/settings_policies",
    "next": null,
    "parent": "/api/configuration/rdp",
    "previous": "/api/configuration/rdp/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "autologon_domain_suffix": "-AUTO",
    "name": "API_test",
    "permit_unreliable_usernames": true,
    "preconnect_channel_check": true,
    "protocol_features": {
      "nla": {
        "enabled": true,
        "require_domain_membership": false
      },
      "rdp4_auth_enabled": true,
      "rdp4_enabled": true,
      "rdp5_enabled": true
    },
    "screen": {
      "maximum_bpp": 32,
      "maximum_height": 2000,
      "maximum_width": 2000
    },
    "timeout": 600
  },
  "key": "13298899495727c51f725cf",
  "meta": {
    "first": "/api/configuration/rdp/settings_policies/-301",
    "href": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf",
    "last": "/api/configuration/rdp/settings_policies/13298899495727c51f725cf",
    "next": null,
    "parent": "/api/configuration/rdp/settings_policies",
    "previous": "/api/configuration/rdp/settings_policies/-303",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the RDP settings policy.
  autologon_domain_suffix string Enter the suffix that the client will append to the domain when using autologon in conjunction with Network Level Authentication (CredSSP).
  name string Name of the RDP settings policy. Cannot contain whitespace.
  permit_unreliable_usernames boolean Set to true to automatically terminate RDP connections if SCB cannot reliably extract the username.
  preconnect_channel_check boolean

Before establishing the server-side connection, SCB can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server.

To enable this function, set the parameter to true.

  protocol_features Top level item Settings for RDP protocol versions, and Network Layer Authentication.
  screen Top level item Display size and depth settings.
  timeout int Connection timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.
Elements of protocol Type Description
nla   Top level item Settings for Network Level Authentication.
  enabled boolean

Set to true to enable Network Level Authentication.

If set to true, the require_domain_membership element is required in the JSON.

  require_domain_membership boolean

Set to true to require domain membership.

Must be in the JSON if NLA is enabled.

rdp4_auth_enabled   boolean Set to true to enable RDP4 authentication within the RDP5 protocol. This might be needed for compatibility reasons with certain client applications.
rdp4_enabled   boolean Set to true to enable the version 4 of the Remote Desktop Protocol.
rdp5_enabled   boolean

Set to true to enable the version 5 of the Remote Desktop Protocol.

To also configure SSL-encryption for RDP5, enable the nla element, or configure a Signing CA in your connection policies.

Elements of screen Type Description
maximum_bpp int The maximum allowed color depth of the remote desktop, in bits. The following values are valid: 8, 15, 16, 24.
maximum_height int The maximum allowed height of the remote desktop, in pixels.
maximum_width int The maximum allowed width of the remote desktop, in pixels.

Examples: 

Turn off NLA.

{
  "autologon_domain_suffix": "-AUTO",
  "name": "API_test",
  "permit_unreliable_usernames": true,
  "preconnect_channel_check": true,
  "protocol_features": {
    "nla": {
      "enabled": false
    },
    "rdp4_auth_enabled": true,
    "rdp4_enabled": true,
    "rdp5_enabled": true
  },
  "screen": {
    "maximum_bpp": 24,
    "maximum_height": 2000,
    "maximum_width": 2000
  },
  "timeout": 600
}

Configure NLA.

{
  "autologon_domain_suffix": "-AUTO",
  "name": "API_test",
  "permit_unreliable_usernames": true,
  "preconnect_channel_check": true,
  "protocol_features": {
    "nla": {
      "enabled": true,
      "require_domain_membership": false
    },
    "rdp4_auth_enabled": true,
    "rdp4_enabled": true,
    "rdp5_enabled": true
  },
  "screen": {
    "maximum_bpp": 24,
    "maximum_height": 2000,
    "maximum_width": 2000
  },
  "timeout": 600
 }

Add RDP settings policies

To add a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new policy.

    You can find a detailed description of the available parameters listed in RDP Settings Policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/ endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7",
  "meta": {
    "href": "/api/configuration/rdp/settings_policies/9c3a0419-53e6-43a4-902c-2b3b0ce7a7a7",
    "parent": "/api/configuration/rdp/settings_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify RDP settings policies

To modify a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the policy.

    You can find a detailed description of the available parameters listed in RDP Settings Policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/rdp/settings_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400

Bad Request

"message": "RDP Settings Policy 'API_test': SCB must be a domain member to allow enabling Network Level Authentication."

You have set require_domain_membership to true, but SCB is not the member of a domain.

401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.24. Telnet connections

List of endpoints for configuring the policies, options and connection rules of Telnet connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/telnet

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for Telnet connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/telnet

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/telnet/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/telnet/options"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/telnet",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/troubleshooting",
    "parent": "/api/configuration",
    "previous": "/api/configuration/ssh",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global Telnet options that affect all connections.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.25. Global Telnet options

List of options that affect all Telnet connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/telnet/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global Telnet options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/telnet/options

Response

The following is a sample response received when listing global Telnet options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/telnet/channel_policies",
    "href": "/api/configuration/telnet/options",
    "last": "/api/configuration/telnet/options",
    "next": null,
    "parent": "/api/configuration/telnet",
    "previous": "/api/configuration/telnet/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global Telnet options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable Telnet connections, and specify the logging detail.
    enabled boolean Set to true to enable Telnet connections.
    log_level int Defines the logging detail of Telnet connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for Telnet connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of Telnet connections, in days. Must exceed the retention time of the archiving policy (or policies) used for Telnet connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of Telnet connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for Telnet connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global Telnet settings

To modify global Telnet settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global Telnet settings endpoint.

    You can find a detailed description of the available parameters listed in Global Telnet options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/telnet/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.26. HTTP connections

List of endpoints for configuring the policies, options and connection rules of HTTP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/http

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for HTTP connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/http/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/http/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/http/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/http",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/ica",
    "parent": "/api/configuration",
    "previous": "/api/configuration/datetime",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global HTTP options that affect all connections.
settings_policies List of protocol-level settings (idle and session timeout). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.27. Global HTTP options

List of options that affect all HTTP connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/http/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global HTTP options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/options

Response

The following is a sample response received when listing global HTTP options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/options",
    "last": "/api/configuration/http/settings_policies",
    "next": "/api/configuration/http/settings_policies",
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global HTTP options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable HTTP connections, and specify the logging detail.
    enabled boolean Set to true to enable HTTP connections.
    log_level int Defines the logging detail of HTTP connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for HTTP connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of HTTP connections, in days. Must exceed the retention time of the archiving policy (or policies) used for HTTP connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of HTTP connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for HTTP connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global HTTP settings

To modify global HTTP settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global HTTP settings endpoint.

    You can find a detailed description of the available parameters listed in Global HTTP options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/http/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.28. HTTP settings policies

HTTP settings policies define protocol-level settings for idle and session timeout. You can create multiple policies, and choose the appropriate one for each HTTP connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/http/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists HTTP settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/http/settings_policies/<policy-id>

Response

The following is a sample response received when listing HTTP settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-3040010",
      "meta": {
        "href": "/api/configuration/http/settings_policies/-3040010"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/http/channel_policies",
    "href": "/api/configuration/http/settings_policies",
    "last": "/api/configuration/http/settings_policies",
    "next": null,
    "parent": "/api/configuration/http",
    "previous": "/api/configuration/http/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "name": "default",
    "session_timeout": 900,
    "timeout": 300
  },
  "key": "-3040010",
  "meta": {
    "first": "/api/configuration/http/settings_policies/-3040010",
    "href": "/api/configuration/http/settings_policies/-3040010",
    "last": "/api/configuration/http/settings_policies/-3040010",
    "next": null,
    "parent": "/api/configuration/http/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the HTTP settings policy.
  name string Name of the HTTP settings policy. Cannot contain whitespace.
  session_timeout int Session timeout, in seconds.
  timeout int Idle timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.

Add HTTP settings policies

To add a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new policy.

    You can find a detailed description of the available parameters listed in HTTP Settings Policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/http/settings_policies/ endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "3848c708-2e1d-4463-b232-0c8c5875ff55",
  "meta": {
    "href": "/api/configuration/http/settings_policies/3848c708-2e1d-4463-b232-0c8c5875ff55",
    "parent": "/api/configuration/http/settings_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify HTTP settings policies

To modify a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the policy.

    You can find a detailed description of the available parameters listed in HTTP Settings Policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/http/settings_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.29. ICA connections

List of endpoints for configuring the policies, options and connection rules of ICA connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for ICA connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/ica/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/ica/options"
      }
    },
    {
      "key": "settings_policies",
      "meta": {
        "href": "/api/configuration/ica/settings_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/ica",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/local_services",
    "parent": "/api/configuration",
    "previous": "/api/configuration/http",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global ICA options that affect all connections.
settings_policies List of protocol-level settings (timeout, reliability). You can create multiple variations, and choose the appropriate one for each connection policy.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.30. Global ICA options

List of options that affect all ICA connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global ICA options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/options

Response

The following is a sample response received when listing global ICA options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/options",
    "last": "/api/configuration/ica/settings_policies",
    "next": "/api/configuration/ica/settings_policies",
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global ICA options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable ICA connections, and specify the logging detail.
    enabled boolean Set to true to enable ICA connections.
    log_level int Defines the logging detail of ICA connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for ICA connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of ICA connections, in days. Must exceed the retention time of the archiving policy (or policies) used for ICA connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of ICA connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for ICA connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global ICA settings

To modify global ICA settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global ICA settings endpoint.

    You can find a detailed description of the available parameters listed in Global ICA options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.31. ICA settings policies

ICA settings policies define protocol-level settings (timeout, reliability). You can create multiple policies, and choose the appropriate one for each ICA connection.

URL

GET https://<IP-address-of-SCB>/api/configuration/ica/settings_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists ICA settings policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/settings_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/<policy-id>

Response

The following is a sample response received when listing ICA settings policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "-301101020",
      "meta": {
        "href": "/api/configuration/ica/settings_policies/-301101020"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/ica/channel_policies",
    "href": "/api/configuration/ica/settings_policies",
    "last": "/api/configuration/ica/settings_policies",
    "next": null,
    "parent": "/api/configuration/ica",
    "previous": "/api/configuration/ica/options",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific policy, the response is the following.

{
  "body": {
    "name": "default",
    "preconnect_channel_check": false,
    "reliability": {
      "reconnect_attempts": 30,
      "reconnect_sleep": 2,
      "reconnect_timeout": 600
    },
    "timeout": 600
  },
  "key": "-301101020",
  "meta": {
    "first": "/api/configuration/ica/settings_policies/-301101020",
    "href": "/api/configuration/ica/settings_policies/-301101020",
    "last": "/api/configuration/ica/settings_policies/-301101020",
    "next": null,
    "parent": "/api/configuration/ica/settings_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the policy.
body   Top level element (string) The elements of the ICA settings policy.
  name string Name of the ICA settings policy. Cannot contain whitespace.
  preconnect_channel_check boolean

Before establishing the server-side connection, SCB can evaluate the connection and channel policies to determine if the connection might be permitted at all. The server-side connection is established only if the evaluated policies permit the client to access the server.

To enable this function, set the parameter to true.

  reliability Top level item Settings for ICA connection attempts.
  timeout int Connection timeout, in seconds. Note that the SCB web UI displays the same value in milliseconds.
Elements of reliability Type Description
reconnect_attempts int The number of times SCB attempts to connect to the target server.
reconnect_sleep int The number of seconds SCB waits between connection attempts.
reconnect_timeout int The number of seconds SCB waits after exhausting the number of reconnect_attempts.

Add ICA settings policies

To add a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new policy.

    You can find a detailed description of the available parameters listed in ICA Settings Policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/ endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "dcd58077-98b3-4c73-8f0b-b34147863028",
  "meta": {
    "href": "/api/configuration/ica/settings_policies/dcd58077-98b3-4c73-8f0b-b34147863028",
    "parent": "/api/configuration/ica/settings_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify ICA settings policies

To modify a settings policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the policy.

    You can find a detailed description of the available parameters listed in ICA Settings Policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/ica/settings_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.32. VNC connections

List of endpoints for configuring the policies, options and connection rules of VNC connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/vnc

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available settings for configuring for VNC connections.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/vnc

Response

The following is a sample response received when listing the configuration settings. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "channel_policies",
      "meta": {
        "href": "/api/configuration/vnc/channel_policies"
      }
    },
    {
      "key": "options",
      "meta": {
        "href": "/api/configuration/vnc/options"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/vnc",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/x509",
    "parent": "/api/configuration",
    "previous": "/api/configuration/troubleshooting",
    "transaction": "/api/transaction"
  }
}
Item Description
channel_policies List of the default and custom channel policies.
options List of global VNC options that affect all connections.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.33. Global VNC options

List of options that affect all VNC connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/vnc/options

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists global VNC options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/vnc/options

Response

The following is a sample response received when listing global VNC options. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "audit": {
      "cleanup": {
        "enabled": false
      },
      "timestamping": {
        "selection": "local",
        "signing_interval": 30
      }
    },
    "service": {
      "enabled": true,
      "log_level": 4
    }
  },
  "key": "options",
  "meta": {
    "first": "/api/configuration/vnc/channel_policies",
    "href": "/api/configuration/vnc/options",
    "last": "/api/configuration/vnc/options",
    "next": null,
    "parent": "/api/configuration/vnc",
    "previous": "/api/configuration/vnc/channel_policies",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     Top level item Contains the ID of the endpoint.
body     Top level item Contains the elements of the global VNC options.
  audit   Top level item Contains settings for timestamping and cleanup.
  service   Top level item Global setting to enable VNC connections, and specify the logging detail.
    enabled boolean Set to true to enable VNC connections.
    log_level int Defines the logging detail of VNC connections.
Elements of audit Type Description
cleanup     Top level item Global retention settings for VNC connection metadata. To configure retention time for a specific connection policy, use the archive_cleanup_policy element at the endpoint of the policy instead.
  channel_database_cleanup_days   int Global retention time for the metadata of VNC connections, in days. Must exceed the retention time of the archiving policy (or policies) used for VNC connections, and the connection-specific database cleanup times (if configured).
  enabled   boolean To enable the global cleanup of VNC connection metadata, set this element to true.
timestamping     Top level item Global timestamping settings for VNC connections.
  selection   string

Configures local or remote timestamping.

  • Set local to use SCB for timestamping.

  • Set remote to configure a remote timestamping server.

  server_url   string

Required for remote timestamping.

The URL of the timestamping server. Note that HTTPS and password-protected connections are not supported.

  oid   Top level item The Object Identifier of the policy used for timestamping.
    enabled boolean

Required for remote timestamping.

Set to true to configure the Object Identifier of the timestamping policy on the timestamping remote server.

    policy_oid string

Required if the oid is enabled.

The Object Identifier of the timestamping policy on the remote timestamping server.

  signing_interval   int Time interval for timestamping open connections, in seconds.

Examples: 

Set SCB as the timestamping server:

{
  "audit": {
    "cleanup": {
      "enabled": false
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Enable cleanup, and set it to occur every 10 days:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
      "selection": "local",
      "signing_interval": 30
    }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, without specifying a timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": false
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Change timestamping to a remote server, and specify the 1.2.3 timestamping policy:

{
  "audit": {
    "cleanup": {
      "channel_database_cleanup_days": 10,
      "enabled": true
    },
    "timestamping": {
        "oid": {
          "enabled": true,
          "policy_oid": "1.2.3"
        },
        "selection": "remote",
        "server_url": "<url-of-timestamping-server>",
        "signing_interval": 30
      }
  },
  "service": {
    "enabled": true,
    "log_level": 4
  }
}

Modify global VNC settings

To modify global VNC settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the global VNC settings endpoint.

    You can find a detailed description of the available parameters listed in Global VNC options. The elements of the audit item are described in Audit elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/vnc/options endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.34. Policies

List of endpoints for configuring policies and settings that can be referenced when configuring connections.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies

Response

The following is a sample response received when listing the available configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "audit_policies",
      "meta": {
        "href": "/api/configuration/policies/audit_policies"
      }
    },
    {
      "key": "content_policies",
      "meta": {
        "href": "/api/configuration/policies/content_policies"
      }
    },
    {
      "key": "credentialstores",
      "meta": {
        "href": "/api/configuration/policies/credentialstores"
      }
    },
    {
      "key": "indexing",
      "meta": {
        "href": "/api/configuration/policies/indexing"
      }
    },
    {
      "key": "ldap_servers",
      "meta": {
        "href": "/api/configuration/policies/ldap_servers"
      }
    },
    {
      "key": "signing_cas",
      "meta": {
        "href": "/api/configuration/policies/signing_cas"
      }
    },
    {
      "key": "ticketing_policies",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies"
      }
    },
    {
      "key": "time_policies",
      "meta": {
        "href": "/api/configuration/policies/time_policies"
      }
    },
    {
      "key": "trusted_ca_lists",
      "meta": {
        "href": "/api/configuration/policies/trusted_ca_lists"
      }
    },
    {
      "key": "user_databases",
      "meta": {
        "href": "/api/configuration/policies/user_databases"
      }
    },
    {
      "key": "userlists",
      "meta": {
        "href": "/api/configuration/policies/userlists"
      }
    },
    {
      "key": "usermapping_policies",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/policies",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/private_keys",
    "parent": "/api/configuration",
    "previous": "/api/configuration/plugins",
    "transaction": "/api/transaction"
  }
}
Endpoint Description
audit_policies Audit trail encryption, timestamping, and signing.
content_policies Actions for detected commands, screen content, credit card information, and window titles.
credentialstores Local and external credential stores.
indexing Languages for Optical Character Recognition (OCR).
ldap_servers LDAP servers.
signing_cas

Signing CAs for generating the server-side certificates on the fly. You can use such CAs in SSL-encrypted RDP sessions, RDP sessions that use Network Level Authentication (CredSSP), or SSH connections that use X.509-based authentication.

To configure signing for audit trails, use the audit_policies endpoint.

ticketing_policies Integration settings for external ticketing systems.
time_policies Time policies.
trusted_ca_lists Trusted Certificate Authorities (CAs), and options for restricting the accepted certificates.
user_databases Local User Databases are available for RDP, SSH and Telnet protocols, and can be used to authenticate the clients to credentials (passwords, public keys, and certificates) that are locally available on SCB.
userlists Local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.
usermapping_policies Usermapping policies describe who can use a specific username to access the remote server.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.35. Audit policies

The list of audit policies. An audit policy contains settings for encrypting, timestamping, and signing audit trails. To enable auditing for a connection, select an audit policy when configuring connections, and enable auditing for the appropriate protocol channels in the connection's channel policy.

Note

The default audit policy is pre-selected when creating connection policies. Modify that audit policy with care.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/audit_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the audit policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/audit_policies

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/policies/audit_policies/<policy-id>

Response

The following is a sample response received when listing audit policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "78101850949e47437dd91d",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
      }
    },
    {
      "key": "9161063345713f11489305",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/9161063345713f11489305"
      }
    },
    {
      "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/audit_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/content_policies",
    "parent": "/api/configuration/policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific audit policy, the response is the following.

{
  "body": {
    "encryption": {
      "certificates": [
        {
          "certificate": "<cert1>",
          "four_eyes_certificate": "<cert2>"
        }
      ],
      "different_certificates_for_upstream": {
        "certificates": [
          {
            "certificate": "<cert3>",
            "four_eyes_certificate": "<cert4>"
          }
        ],
        "enabled": true
      },
      "enabled": true
    },
    "name": "<policy-name>",
    "signing": {
      "enabled": true,
      "x509_identity": {
        "key": "ec0b6604-37f6-4df6-bd2f-d7879a75b324",
        "meta": {
          "href": "/api/configuration/x509/ec0b6604-37f6-4df6-bd2f-d7879a75b324"
        }
      }
    },
    "timestamping_enabled": true
  },
  "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
  "meta": {
    "first": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
    "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "last": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "next": null,
    "parent": "/api/configuration/policies/audit_policies",
    "previous": "/api/configuration/policies/audit_policies/9161063345713f11489305",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element (string) The configuration elements of the policy.
  encryption   Top level element Audit trail encryption settings.
  name   string The name of the policy. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  signing   Top level element Audit trail signing settings.
    enabled boolean

Set to true to enable audit trail signing.

If signing is enabled, the x509_identity element is also required.

    x509_identity string

Required for signing audit trails.

References the identifier of the X.509 certificate stored on SCB. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  timestamping   boolean Set to true to timestamp the audit trail.
Elements of encryption Type Description
certificates     Top level list Contains the encrypting certificates.
  certificate   string The encrypting certificate. You can replay an encrypted audit trail with the private key of the encrypting certificate.
  four_eyes_certificate   string Additional certificate for joint (4-eyes) encryption. You can only replay a jointly encrypted audit trail with the private keys of both certificates.
different_certificates_for_upstream     Top level item Configures encrypting upstream traffic separately.
  certificates   Top level list The certificates for encrypting upstream traffic.
    certificate string The encrypting certificate. You can replay an encrypted upstream with the private key of the encrypting certificate.
    four_eyes_certificate string Additional certificate for joint (4-eyes) encryption. You can only replay a jointly encrypted upstream with the private keys of both certificates.
  enabled   boolean

Set to true to encrypt the upstream traffic with separate certificate(s).

If upstream encryption is enabled, the certificates element is required.

enabled     boolean

Set to true to enable encrypting audit trails.

If encryption is enabled, the certificates and different_certificates_for_upstream elements are required.

Examples: 

Disable encryption, signing, and timestamping.

{
  "encryption": {
    "enabled": false
  },
  "name": "default",
  "signing": {
    "enabled": false
  },
  "timestamping_enabled": false
}

Encrypt upstream traffic only (single certificate).

{
  "encryption": {
    "certificates": [],
    "different_certificates_for_upstream": {
      "certificates": [
        {
          "certificate": "<cert>",
          "four_eyes_certificate": null
        }
      ],
      "enabled": true
    },
    "enabled": true
  },
  "name": "Upstream_only",
  "signing": {
    "enabled": false
  },
  "timestamping_enabled": false
}

Enable signing and timestamping, no traffic encryption.

{
  "encryption": {
    "enabled": false
  },
  "name": "Sign_and_timestamp",
  "signing": {
    "enabled": true,
    "x509_identity": {
      "key": "9508db81-4a3f-45a7-a2b1-a86f71c56416",
      "meta": {
        "href": "/api/configuration/x509/9508db81-4a3f-45a7-a2b1-a86f71c56416"
      }
    }
  },
  "timestamping_enabled": true
}

Enable signing and timestamping, and encrypt traffic with a single certificate (no separate upstream encryption).

{
  "encryption": {
    "certificates": [
      {
        "certificate": "<cert>",
        "four_eyes_certificate": null
      }
    ],
    "different_certificates_for_upstream": {
      "enabled": false
    },
    "enabled": true
  },
  "name": "API_audit_pol",
  "signing": {
    "enabled": true,
    "x509_identity": {
      "key": "d0286f64-41aa-45e1-ab19-830ac2f99f57",
      "meta": {
        "href": "/api/configuration/x509/d0286f64-41aa-45e1-ab19-830ac2f99f57"
      }
    }
  },
  "timestamping_enabled": true
}

Encrypting certificates

Encrypting certificates must not contain any metadata. SCB uses only the key part of the certificate, no other data (expiry, etc.) are relevant for encryption.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add an audit policy

To add an audit policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new audit policy.

    You can find a detailed description of the available parameters listed in Audit policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/audit_policies endpoint. If the POST request is successful, the response includes the key of the new audit policy. For example:

{
  "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
  "meta": {
    "href": "/api/configuration/policies/audit_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "parent": "/api/configuration/policies/audit_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify an audit policy

To modify an audit policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the audit policy.

    You can find a detailed description of the available parameters listed in Audit policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/audit_policies/<policy-key> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.36. Real-time content monitoring with Content Policies

You can monitor the traffic of certain connections in real time, and execute various actions if a certain pattern (for example, a particular command or text) appears in the command line or on the screen, or if a window with a particular title appears in a graphical protocol. Since content-monitoring is performed real-time, SCB can prevent harmful commands from being executed on your servers. SCB can also detect numbers that might be credit card numbers. The patterns to find can be defined as regular expressions. In case of ICA, RDP, and VNC connections, SCB can detect window title content.

The following actions can be performed:

  • Log the event in the system logs.

  • Immediately terminate the connection.

  • Send an e-mail or SNMP alerts about the event.

  • Store the event in the connection database of SCB.

SCB currently supports content monitoring in SSH session-shell connections, Telnet connections, RDP and Citrix ICA Drawing channels, and in VNC connections.

Note

Command, credit card and window detection algorithms use heuristics. In certain (rare) situations, they might not match the configured content. In such cases, contact the Balabit Support Team to help analyze the problem.

Real-time content monitoring in graphical protocols is not supported for Arabic and CJK languages.

To list the available Content policies, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/content_policies

The following sections detail the properties of Content policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/policies/content_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific Content policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/policies/content_policies/<object-id>

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "name": "example-content-policy-window-title",
    "rules": [
      {
        "actions": {
          "log": true,
          "notify": true,
          "store_in_connection_database": true,
          "terminate": false
        },
        "event": {
          "ignore": [],
          "match": [
            "mmc.exe"
          ],
          "selection": "window_title"
        },
        "gateway_groups": [],
        "remote_groups": []
      }
    ]
  }
}
Element Type Description
name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
rules   JSON object Top level element, contains the configuration properties of the object.
  actions JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  event JSON object Specifies the event that triggers an action.
  gateway_groups list

To apply the Content policy only for users belonging to specific groups, list those groups in the gateway_groups or remote_groups fields. If the gateway_groups or remote_groups field is set, the content policy is applied only to connections of these usergroups.

For example:

"gateway_groups": ["group1", "group2"],
  remote_groups list

To apply the Content policy only for users belonging to specific groups, list those groups in the gateway_groups or remote_groups fields. If the gateway_groups or remote_groups field is set, the content policy is applied only to connections of these usergroups.

For example:

"remote_groups": ["group1", "group3"],
Element Type Description
actions   JSON object The list of actions to perform when the Content policy matches the analyzed traffic. All actions are boolean values (true or false)
  log boolean

Log the event in the system logs. Possible values: true or false

  terminate boolean

Immediately terminate the connection. Possible values: true or false

  notify boolean

Send an e-mail or SNMP alerts about the event. Possible values: true or false

  store_in_connection_database boolean

Store the event in the connection database of SCB. Possible values: true or false

Element Type Description
event   JSON object Specifies the event that triggers an action.
  ignore list

A list of strings or regular expressions. SCB will perform an action if the match expression is found in the connection, unless it is listed in the ignore list. For example:

"ignore": [
"mmc.exe",
"cmd.exe"
],
  • Use Perl Compatible Regular Expressions (PCRE).

  • The following characters must be escaped using a backslash character: '(single-quote). For example, instead of .*' use .*\'

  • SCB uses substring search to find the expression in the content. That is, SCB finds the expression even if there is more content before or after the matching part. For example, the conf pattern will match the following texts: conf, configure, reconfigure, arcconf, and so on.

  • Using complicated regular expressions or using many regular expressions will affect the performance of SCB.

  • If the multiple expressions are set, SCB processes them one after the other, and stops processing the content if the first match is found, even if other expressions would also match the content. Therefore, when using multiple expressions, start with the most specific one, and add general expressions afterward.

  match list

A list of strings or regular expressions. SCB will perform an action if the match expression is found in the connection, unless it is listed in the ignore list. For example:

"match": [
"mmc.exe",
"cmd.exe"
],
  • Use Perl Compatible Regular Expressions (PCRE).

  • The following characters must be escaped using a backslash character: '(single-quote). For example, instead of .*' use .*\'

  • SCB uses substring search to find the expression in the content. That is, SCB finds the expression even if there is more content before or after the matching part. For example, the conf pattern will match the following texts: conf, configure, reconfigure, arcconf, and so on.

  • Using complicated regular expressions or using many regular expressions will affect the performance of SCB.

  • If the multiple expressions are set, SCB processes them one after the other, and stops processing the content if the first match is found, even if other expressions would also match the content. Therefore, when using multiple expressions, start with the most specific one, and add general expressions afterward.

  selection string

The type of event that you want to monitor.

  • command: The commands executed in the session-shell channel of SSH connections, or in Telnet connections.

    Warning

    During indexing, if a separate certificate is used to encrypt the upstream traffic, command detection works only if the upstream key is accessible on the machine running the indexer.

  • screen_content: Every text that appears on the screen. For example, every text that is displayed in the terminal of SSH or Telnet connections. This includes the executed commands as well, unless echoing is turned off for the terminal.

  • creditcard: Process every text that appears on the screen and attempt to detect credit card numbers in SSH or Telnet connections. SCB performs an action if the number of detected credit card numbers exceeds the value set as Permitted number of credit card numbers.

    Credit card number detection is based on the Luhn algorithm and lists of known credit card number prefixes.

  • window_title: Text appearing as window titles in case of RDP, Citrix ICA, and VNC connections. Only Windows Classic Themes are supported. Themes with rounded corners, or Windows Aero themes are not supported.

For example:

"selection": "window_title"

Add a content policy

To add a content policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new content policy.

    You can find a detailed description of the available parameters listed in Parameters of Content policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/content_policies endpoint. If the POST request is successful, the response includes the key of the new policy. For example:

{
  "key": "1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
  "meta": {
    "href": "/api/configuration/policies/content_policies/1e089e2a-76b4-4079-94e3-c83ebc74dc2e",
    "parent": "/api/configuration/policies/content_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a content policy

To modify a content policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the content policy.

    You can find a detailed description of the available parameters listed in Parameters of Content policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/content_policies/<policy-key> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.37. Credential stores

Credential Stores offer a way to store user credentials (for example, passwords, private keys, certificates) and use them to login to the target server, without the user having access to the credentials. That way, the users only have to perform gateway authentication on SCB with their usual password (or to an LDAP database), and if the user is allowed to access the target server, SCB automatically logs in using the Credential Store.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/credentialstores

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the credential stores.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/credentialstores

The following command retrieves the properties of a specific credential store.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/policies/credentialstores/<policy-id>

Response

The following is a sample response received when listing credential stores. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "1580973975727acedd51b2",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/1580973975727acedd51b2"
      }
    },
    {
      "key": "935272738572bc2ec1dbdd",
      "meta": {
        "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/credentialstores",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/indexing",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/content_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific credential store, the response is the following.

{
  "body": {
    "name": "API_LIEBERMANN",
    "type": {
      "authenticator_name": "auth_server_name",
      "default_namespace": "{HOST}",
      "dns_servers": {
        "primary": "192.168.56.1",
        "secondary": "192.168.56.2"
      },
      "domain_mappings": [
        {
          "domain": "domain",
          "host": {
            "selection": "fqdn",
            "value": "host"
          }
        }
      ],
      "login_mode": {
        "password": {
          "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
          "meta": {
            "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
          }
        },
        "selection": "fixed",
        "username": "fixed_username"
      },
      "proxy_server": "http://192.168.56.201:9999",
      "selection": "lieberman",
      "server_certificate_check": {
        "enabled": true,
        "trusted_ca": {
          "key": "12269547065727ad6e79d9e",
          "meta": {
            "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
          }
        }
      },
      "web_interface_url": "http://erpm_address"
    }
  },
  "key": "935272738572bc2ec1dbdd",
  "meta": {
    "first": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "href": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "last": "/api/configuration/policies/credentialstores/935272738572bc2ec1dbdd",
    "next": null,
    "parent": "/api/configuration/policies/credentialstores",
    "previous": "/api/configuration/policies/credentialstores/1580973975727acedd51b2",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the credential store.
body     Top level element (string) The configuration elements of the credential store.
  name   string The name of the credential store. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  type   Top level item All elements for the configured type of credential store.
    authenticator_name string If your ERPM setup is configured to use an external authentication method, enter the name of the Authentication Server (Authenticator Source) set on your ERPM server. If empty, SCB uses the [Explicit] authenticator.
    default_namespace string The default namespace of the accounts (for example, [Linux], [LDAP], [IPMI], W2003DOMAIN).
    dns_servers Top level item The IP addresses of the DNS servers to use for resolving the hostnames provided in domain_mappings.
    domain_mappings Top level list

Use for RDP connections only. In a domainless environment, use default_namespace.

To retrieve the password of a domain user from Lieberman ERPM, SCB queries the domain controller directly. This element contains the necessary Domain/Host mappings.

    encryption Top level item Configures the encryption key for the local credential store.
    login_mode Top level item Configures the account SCB uses to login to the ERPM server.
    plugin string

Must be used if the selection element is set to external_plugin.

References the Credential Store plugin. You can find the list of available plugins at the /api/configuration/plugins/credentialstore/ endpoint.

To modify or add a plugin, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

Plugins can only be uploaded using the web interface of SCB.

    proxy_server string The IP address and port of the proxy server. Use the http:// or https:// prefix.
    selection string

Configures the type of the credential store. Possible values are:

  • lieberman

    Lieberman ERPM. Can only be configured using the web interface of SCB.

  • local

    Local credential store. Can only be configured using the web interface of SCB.

  • external_plugin

    Credential Store Plug-in. Can only be configured using the web interface of SCB.

    server_certificate_check Top level item To verify the certificate of the ERPM server, configure server_certificate_check.
    web_interface_url string Name of the DN of the ERPM server. Use the http:// or https:// prefix.
Elements of dns_servers Type Description
primary string The IP address of the primary DNS server.
secondary string The IP address of the secondary DNS server.
Elements of domain_mappings Type Description
domain   string The domain name used for Domain/Host mapping.
host   Top level item The host name or address of the domain controller used for Domain/Host mapping.
  selection string

Declares if the value element contains an IP or an FQDN. Possible values are:

  • fqdn

    The value element contains a hostname.

  • ip

    The value element contains an IP.

  value string The IP address or hostname of the domain controller.
Elements of encryption Type Description
selection string

Defines the encryption of the local credential store. Possible values are:

  • basic

    The local credential store uses the built-in protection of SCB.

  • password

    The local credential store is protected by one or more passwords.

Elements of login_mode Type Description
password string

Must be used if the selection element is set to fixed_username.

References the password SCB uses to authenticate on the ERPM server. You can find the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

selection string

Possible values are:

  • fixed_username

    SCB uses a fix username and password.

    Requires the username and password elements.

  • gateway_auth_credentials

    SCB uses the username and password that the user provided during the gateway authentication process.

    Can only be used for SSH connections.

username string

Must be used if the selection element is set to fixed_username.

The username SCB uses to authenticate on the ERPM server.

Elements of server_certificate_check Type Description
enabled boolean Set to true to verify the ERPM server's certificate.
trusted_ca string

Must be used if server certificate checking is enabled.

References the list of trusted Certificate Authorities. You can find the lists of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To reference a trusted CA list, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

Examples: 

Note

The following examples are responses only. Credential stores can only be configured using the web interface of SCB.

Use a Lieberman ERPM server, configure domain mapping and provide the host address as an IP, reuse the gateway login credentials of the user to access the ERPM server, and do not verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "ip",
          "value": "192.168.56.1"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": false
    },
    "web_interface_url": "https://erpm_address"
  }
}

Change the host address to a hostname for domain mapping, and verify the server's certificate.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "selection": "gateway_auth_credentials"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "https://erpm_address"
  }
}

Use a fixed username to access the Lieberman ERPM server.

{
  "name": "API_LIEBERMANN",
  "type": {
    "authenticator_name": "auth_server_name",
    "default_namespace": "{HOST}",
    "dns_servers": {
      "primary": "192.168.56.1",
      "secondary": "192.168.56.2"
    },
    "domain_mappings": [
      {
        "domain": "domain",
        "host": {
          "selection": "fqdn",
          "value": "host"
        }
      }
    ],
    "login_mode": {
      "password": {
        "key": "e0ecbe98-bd17-4805-ba5d-17fb789f3971",
        "meta": {
          "href": "/api/configuration/passwords/e0ecbe98-bd17-4805-ba5d-17fb789f3971"
        }
      },
      "selection": "fixed",
      "username": "fixed_username"
    },
    "proxy_server": "http://192.168.56.201:9999",
    "selection": "lieberman",
    "server_certificate_check": {
      "enabled": true,
      "trusted_ca": {
        "key": "12269547065727ad6e79d9e",
        "meta": {
          "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
        }
      }
    },
    "web_interface_url": "http://erpm_address"
  }
}

Use a credential store plugin.

{
  "name": "API_PLUGIN",
  "type": {
    "plugin": {
      "key": "2534221015734bb18aaf32",
      "meta": {
        "href": "/api/configuration/plugins/credentialstore/2534221015734bb18aaf32"
      }
    },
    "selection": "external_plugin"
  }
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.38. LDAP servers

SCB can authenticate the users of the controlled SSH or RDP connections to LDAP databases.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the available LDAP server configurations.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers

The following command retrieves the properties of a specific LDAP server.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers/<object-id>

Response

The following is a sample response received when listing LDAP servers. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "3548834825727acc530407",
      "meta": {
        "href": "/api/configuration/policies/ldap_servers/3548834825727acc530407"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/ldap_servers",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/signing_cas",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/indexing",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific LDAP server, the response is the following.

{
  "body": {
    "base_dn": "basedn",
    "bind_dn": "binddn",
    "bind_password": {
      "key": "f09f94f5-a2c9-4cc5-96ab-2ef1855d12d1",
      "meta": {
        "href": "/api/configuration/passwords/f09f94f5-a2c9-4cc5-96ab-2ef1855d12d1"
      }
    },
    "encryption": {
      "selection": "disabled"
    },
    "generated_publickey_attribute": null,
    "generated_x509_attribute": null,
    "name": "API_LDAP",
    "nested_groups": true,
    "publickey_attribute": "sshPublicKey",
    "schema": {
      "selection": "ad"
    },
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "10.20.30.40"
        },
        "port": 389
      }
    ],
    "x509_attribute": "userCertificate"
  },
  "key": "3548834825727acc530407",
  "meta": {
    "first": "/api/configuration/policies/ldap_servers/3548834825727acc530407",
    "href": "/api/configuration/policies/ldap_servers/3548834825727acc530407",
    "last": "/api/configuration/policies/ldap_servers/17610964665734c0598c669",
    "next": "/api/configuration/policies/ldap_servers/17610964665734c0598c669",
    "parent": "/api/configuration/policies/ldap_servers",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the LDAP server configuration.
body     Top level element (string) Contains the properties of the LDAP server.
  base_dn   string Name of the DN to be used as the base of the queries.
  bind_dn   string Name of the DN where SCB should bind to before accessing the database.
  bind_password   string

References the password SCB uses to authenticate on the server. You can find the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

  encryption   Top level item Configuration settings for encrypting the communication between SCB and the LDAP server.
  generated_publickey_attribute   string

Set this element to null if you use passwords to authenticate.

Configure this element if you want SCB to generate server-side encryption keys on-the-fly, and store them in a separate attribute on the LDAP server.

  generated_x509_attribute   string

Set this element to null if you use passwords to authenticate.

Configure this element if you want SCB to generate server-side certificates on-the-fly, and store them in a separate attribute on the LDAP server.

  name   string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  nested_groups   boolean

Set to true to use nested groups when querying the LDAP server.

Nested groups are mostly useful when authenticating the users to Microsoft Active Directory, but can slow down the query and cause the connection to timeout if the LDAP tree is very large.

  publickey_attribute   string

Set this element to null if you use passwords to authenticate.

The name of the LDAP attribute that stores the public keys of the users.

  schema   Top level item Contains the configuration settings for the AD schema.
    member_uid_attribute string

Must be used if the selection element is set to posix.

Attribute name of the POSIX group membership.

    selection string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

  • ad

    Microsoft Active Directory server.

  • posix

    Server uses the POSIX LDAP scheme.

    Must be used with the member_uid_attribute, unique_member_attribute and username_attribute elements.

    unique_member_attribute string

Must be used if the selection element is set to posix.

Attribute name of the GroupOfUniqueMemberships membership.

    username_attribute string

Must be used if the selection element is set to posix.

Attribute name of the username (user ID).

  servers   Top level list Contains the addresses and ports of the LDAP servers.
  x509_attribute   string

Set this element to null if you use passwords to authenticate.

The name of the LDAP attribute that stores the certificates of the users.

Elements of encryption Type Description
client_authentication   Top level item

Must be used with the selection child element.

Configures the X.509 certificate SCB uses to authenticate on the LDAP server.

  enabled boolean

Must be used with the client-authentication parent element.

Set to true if the LDAP server requires mutual authentication.

  x509_identity string

Must be used if the enabled element is set to true.

References the identifier of the X.509 certificate stored on SCB. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

selection   string

Defines the type of encryption SCB uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

server_certificate_check   Top level item

Must be used with the selection child element.

Configuration settings for verifying the LDAP server's certificate.

  enabled boolean

Must be used with the server_certificate_check parent element.

Set to true to verify the LDAP server's certificate using the certificate of a Certificate Authority (CA).

  server_certificate_ca string

Must be used if the enabled element is set to true.

The certificate of the CA.

Elements of servers Type Description
host   Top level item Contains the address of the LDAP server.
  selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

  value string The address of the LDAP server.
port   int The port of the LDAP server.

Examples: 

Configure a POSIX server without communication encryption.

{
  "base_dn": "<basedn>",
  "bind_dn": "<binddn>",
  "bind_password": "<bind-password>",
  "encryption": {
    "client_authentication": {
      "enabled": false
    },
    "selection": "ssl",
    "server_certificate_check": {
      "enabled": false
    }
  },
  "generated_publickey_attribute": null,
  "generated_x509_attribute": null,
  "name": "<name-of-ldap-policy>",
  "nested_groups": true,
  "publickey_attribute": "<sshPublicKey>",
  "schema": {
    "member_uid_attribute": "<memberUid>",
    "selection": "posix",
    "unique_member_attribute": "<uniqueMember>",
    "username_attribute": "<uid>"
  },
  "servers": [
    {
      "host": {
        "selection": "fqdn",
        "value": "<server-name>"
      },
      "port": <server-port>
    }
  ],
  "x509_attribute": "<userCertificate>"
}

Configure a Microsoft Active Directory server with mutual authentication, and the verification of the server's X.509 certificate.

{
  "base_dn": "<basedn>",
  "bind_dn": "<binddn>",
  "bind_password": "<key-of-password>",
  "encryption": {
    "client_authentication": {
      "enabled": true,
      "x509_identity": "<key-of-cert>"
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": true,
      "server_certificate_ca": "<ca-cert>"
    }
  },
  "generated_publickey_attribute": null,
  "generated_x509_attribute": null,
  "name": "<name-of-ldap-policy>",
  "nested_groups": true,
  "publickey_attribute": "<sshPublicKey>",
  "schema": {
    "selection": "ad"
  },
  "servers": [
    {
      "host": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "port": <server-port>
    }
  ],
  "x509_attribute": "<userCertificate>"
}

CA certificates

CA certificates must not contain any metadata. SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add an LDAP server

To add an LDAP server, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new LDAP server.

    You can find a detailed description of the available parameters listed in LDAP servers.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers endpoint. If the POST request is successful, the response includes the key of the new LDAP server. For example:

{
  "key": "f9f9783c-1e28-4ce8-a650-fc4c7311ac52",
  "meta": {
    "href": "/api/configuration/policies/ldap_servers/f9f9783c-1e28-4ce8-a650-fc4c7311ac52",
    "parent": "/api/configuration/policies/ldap_servers",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify an LDAP server

To modify the configuration of an LDAP server, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the LDAP server.

    You can find a detailed description of the available parameters listed in LDAP servers.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ldap_servers/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.39. Signing CA policies

SCB can generate the server-side certificates on the fly. This technique is used for example in SSL-encrypted RDP sessions, RDP sessions that use Network Level Authentication (CredSSP), or SSH connections that use X.509-based authentication.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/signing_cas

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configured signing Certificate Authorities (CAs).

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/signing_cas

The following command retrieves the properties of a specific policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/signing_cas/<object-id>

Response

The following is a sample response received when listing signing CAs. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "991699365727ac4eb4606",
      "meta": {
        "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/signing_cas",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/ticketing_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/ldap_servers",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific signing CA, the response is the following.

{
  "body": {
    "ca": {
      "key": "55b2419c-f94f-4836-9c0b-bc3796b6f556",
      "meta": {
        "href": "/api/configuration/x509/55b2419c-f94f-4836-9c0b-bc3796b6f556"
      }
    },
    "name": "API_CA"
  },
  "key": "991699365727ac4eb4606",
  "meta": {
    "first": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "href": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "last": "/api/configuration/policies/signing_cas/991699365727ac4eb4606",
    "next": null,
    "parent": "/api/configuration/policies/signing_cas",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the signing CA.
body   Top level element (string) Contains the properties of the signing CA.
  ca string

References the identifier of the signing CA's X.509 certificate. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  name string The name of the signing CA. This name is also displayed on the SCB web interface. It cannot contain whitespace.

Add a signing CA

To add a signing CA, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Have the value of the key element of a valid X.509 CA certificate stored on SCB.

  • Create the JSON object for the new signing CA. Use the X.509 certificate's key as the value of the ca element for the signing CA.

    You can find a detailed description of the available parameters listed in Signing CAs.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/signing_cas endpoint. If the POST request is successful, the response includes the key of the new signing CA. For example:

{
  "key": "325768b5-5b85-467d-8e30-e2b57d0869c8",
  "meta": {
    "href": "/api/configuration/policies/signing_cas/325768b5-5b85-467d-8e30-e2b57d0869c8",
    "parent": "/api/configuration/policies/signing_cas",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a signing CA

To modify a signing CA, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Have the value of the key element of a valid X.509 CA certificate stored on SCB.

  • Modify the JSON object of the signing CA. Use the X.509 certificate's key as the value of the ca element for the signing CA.

    You can find a detailed description of the available parameters listed in Signing CAs.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/signing_cas/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
400

Bad Request

"message": "Signing certificate is not CA;

The referenced certificate is not a valid CA certificate.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.40. Ticketing policies

SCB provides a plugin framework to integrate SCB to external ticketing (or issue tracking) systems, allowing you to request a ticket ID from the user before authenticating on the target server. That way, SCB can verify that the user has a valid reason to access the server — and optionally terminate the connection if he does not. Requesting a ticket ID currently supports the following protocols:

  • Remote Desktop (RDP)

  • Secure Shell (SSH)

  • TELNET

  • TN3270

To request a plugin that interoperates with your ticketing system, contact the BalaBit Support Team.

You can upload ticketing plugins using the web interface of SCB. The API allows you to reference existing (uploaded) ticketing plugins, change the message prompts, and configure the validation of the provided ticket number.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/ticketing_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists ticketing policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ticketing_policies

The following command retrieves the properties of a specific ticketing policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/ticketing_policies/<policy-id>

Response

The following is a sample response received when listing ticketing policies. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "9816939765734be5978af1",
      "meta": {
        "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/ticketing_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/time_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/signing_cas",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific ticketing policy, the response is the following.

{
  "body": {
    "name": "API_ticketing_plugin",
    "plugin": {
      "key": "21425174515734bb223d197",
      "meta": {
        "href": "/api/configuration/plugins/ticketing/21425174515734bb223d197"
      }
    },
    "prompt": "Please enter ticket ID: ",
    "require_valid_ticket": true
  },
  "key": "9816939765734be5978af1",
  "meta": {
    "first": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "href": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "last": "/api/configuration/policies/ticketing_policies/9816939765734be5978af1",
    "next": null,
    "parent": "/api/configuration/policies/ticketing_policies",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the ticketing policy.
body   Top level element (string) Contains the properties of the ticketing policy.
  name string The name of the policy. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  plugin string

References the Ticketing plugin. You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

To modify or add a plugin, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

Plugins can only be uploaded using the web interface of SCB.

  prompt string The user prompt that is displayed in terminal connections (for example, "Enter the ticket ID:").
  require_valid_ticket boolean Set to true to terminate the connection if the provided ticket number is invalid.

Add a ticketing policy

To add a ticketing policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Have the value of the key element of a ticketing plugin uploaded on SCB. You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

  • Create the JSON object for the new ticketing policy. Use the ticketing plugin's key as the value of the plugin element.

    You can find a detailed description of the available parameters listed in Ticketing policies.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ticketing_policies endpoint. If the POST request is successful, the response includes the key of the new ticketing policy. For example:

{
  "key": "aa423b72-0d0f-4275-be30-494e9a99ffad",
  "meta": {
    "href": "/api/configuration/policies/ticketing_policies/aa423b72-0d0f-4275-be30-494e9a99ffad",
    "parent": "/api/configuration/policies/ticketing_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a ticketing policy

To modify a ticketing policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Have the value of the key element of a ticketing plugin uploaded on SCB. You can find the list of available plugins at the /api/configuration/plugins/ticketing/ endpoint.

  • Modify the JSON object of the ticketing policy. Use the ticketing plugin's key as the value of the plugin element.

    You can find a detailed description of the available parameters listed in Ticketing policies.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/ticketing_policies/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.41. Time policy

The time policy determines the timeframe when the users are permitted to access a particular channel. To list the available Time policies, use the following command.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/time_policies

The following sections detail the properties of Time policy objects.

URL

GET https:<IP-address-of-SCB>/api/configuration/policies/time_policies/<object-id>

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the properties of a specific Time policy object.

curl --cookie session_id=<session_cookie> -https:<IP-address-of-SCB>/api/configuration/policies/time_policies/<object-id>

Response

The following is a sample response received, showing the properties of Content policy objects. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "Fri": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Mon": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sat": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Sun": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Thu": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Tue": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "Wed": [
      [
        "0:00",
        "23:59"
      ]
    ],
    "name": "7x24"
}
Element Type Description
name string Top level element, the name of the object. This name is also displayed on the SCB web interface. It cannot contain whitespace.
Fri list

A list of intervals for the day when the users are allowed to access the connection. Use the hh:mm format.

If the users are not allowed to access the connection for this day, use an empty list. For example:

"Sat": [],

To allow access for the whole day, use 0:00 for the starting time, and 23:59for the end. For example:

"Wed": [
  [
    "0:00",
    "23:59"
  ]
]

You can list multiple intervals for a day, for example:

"Wed": [
  [
	"8:00",
	"18:00"
  ],
  [
	"19:00",
	"22:00"
  ]
]
Sat list
Sun list
Thu list
Tue list
Wed list

13.42. Trusted Certificate Authorities

SCB can check the validity of certificates using the certificates and certificate-revocation lists of trusted certificate authorities (CAs) that issued the certificates.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the trusted CAs.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists

The following command retrieves the properties of a specific CA.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists/<policy-id>

Response

The following is a sample response received when listing trusted CAs. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "12269547065727ad6e79d9e",
      "meta": {
        "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/trusted_ca_lists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/user_databases",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/time_policies",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific CA, the response is the following.

{
  "body": {
    "authorities": [
      {
        "certificate": "<cert>",
        "crl": "<url-of-revocation-list>"
      }
    ],
    "dn_check": {
      "altEmailAddress": "<altEmail>",
      "c": "<country>",
      "cn": "<commonName>",
      "emailAddress": "<email>",
      "l": "<localityName>",
      "o": "<orgName>",
      "ou": "<orgUnitName>",
      "st": "<stateOrProvince>"
    },
    "dns_lookup": false,
    "name": "<ca-name>",
    "strict_hostcheck": true
  },
  "key": "12269547065727ad6e79d9e",
  "meta": {
    "first": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "href": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "last": "/api/configuration/policies/trusted_ca_lists/12269547065727ad6e79d9e",
    "next": null,
    "parent": "/api/configuration/policies/trusted_ca_lists",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the CA.
body     Top level element (string) Contains the properties of the CA.
  authorities   Top level list

Contains the certificates and the Certificate Revocation Lists (CLR) of the trusted CAs.

You can add multiple certificate and CRL pairs.

    certificate string The certificate of the trusted CA.
    crl string The URL of the Certificate Revocation List of the CA.
  dn_check   Top level item Certificates are only accepted if their content matches the configured values.
    altEmailAddress string The certificate is only accepted if its alternative e-mail address matches the value of the altEmailAddress element.
    c string The certificate is only accepted if its country matches the value of the c element.
    cn string The certificate is only accepted if its common name matches the value of the cn element.
    emailAddress string The certificate is only accepted if its e-mail address matches the value of the emailAddress element.
    l string The certificate is only accepted if its locality matches the value of the l element.
    o string The certificate is only accepted if its organization name matches value of the o element.
    ou string The certificate is only accepted if its organization unit name matches value of the ou element.
    st string The certificate is only accepted if its state or province matches value of the st element.
  dns_lookup   boolean Set to true to use the domain name server set on the /api/configuration/network/naming endpoint to resolve the hostnames and IP addresses for certificate validation. If you have enabled strict_hostcheck, you probably want to enable this option as well.
  name   string The name of the trusted CA. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  strict_hostcheck   boolean Set to true to configure only accepting certificates where the Common Name of the certificate contains the hostname or the IP address of the host showing the certificate.

Uploading CA certificates

SCB uses only the key part of the CA certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add a trusted CA

To add a trusted CA, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new trusted CA.

    You can find a detailed description of the available parameters listed in Trusted CAs.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists endpoint. If the POST request is successful, the response includes the key of the new trusted CA. For example:

{
  "key": "becc17b1-e876-4443-b22e-a3baf7825e55",
  "meta": {
    "href": "/api/configuration/policies/trusted_ca_lists/becc17b1-e876-4443-b22e-a3baf7825e55",
    "parent": "/api/configuration/policies/trusted_ca_lists",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a trusted CA

To modify a trusted CA, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the trusted CA.

    You can find a detailed description of the available parameters listed in Trusted CAs.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/trusted_ca_lists/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.43. Local user databases

Local User Databases are available for RDP, SSH and Telnet protocols, and can be used to authenticate the clients to credentials that are locally available on SCB. Such credentials include passwords, public keys, and certificates. Local User Databases are most commonly used in inband gateway authentication scenarios.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/user_databases

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists local user databases.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/user_databases

The following command retrieves the properties of a specific local user database.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/user_databases/<object-id>

Response

The following is a sample response received when listing local user databases. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "8235074425707e306abf39",
      "meta": {
        "href": "/api/configuration/policies/user_databases/8235074425707e306abf39"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/user_databases",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/userlists",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/trusted_ca_lists",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific local user database, the response is the following.

{
  "body": {
    "name": "<name-of-the-user-database>",
    "users": [
      {
        "certificates": [
          "<cert>"
        ],
        "passwords": [
          {
            "key": "ad55822d-fa28-45aa-bca4-220074f770e1",
            "meta": {
              "href": "/api/configuration/passwords/ad55822d-fa28-45aa-bca4-220074f770e1"
            }
          }
        ],
        "public_keys": [
          {
            "selection": "rsa",
            "value": "<public-key>"
          }
        ],
        "username": "<username>"
      }
    ]
  },
  "key": "8235074425707e306abf39",
  "meta": {
    "first": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "href": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "last": "/api/configuration/policies/user_databases/8235074425707e306abf39",
    "next": null,
    "parent": "/api/configuration/policies/user_databases",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the local user database.
body     Top level element (string) Contains the properties of the local user database.
  name   string The name of the local user database. This name is also displayed on the SCB web interface. It cannot contain whitespace.
  users   Top level list Contains the password, key, and certificates of each configured user.
    certificates Top level list, string Contains the certificates of the user.
    passwords Top level item

References the password of the user. You can find the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

    public_keys Top level list Contains the pubic keys of the user.
    username Top level list, string Name of the user.
Elements of public_keys Type Description
selection string

Possible values are:

  • rsa

    The value element contains an RSA key.

  • dsa

    The value element contains a DSA key.

value string The public key.

Examples: 

Configure password authentication only for test_user. (New passwords can only be provided using the web interface of SCB.)

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [],
      "passwords": [
        "ad55822d-fa28-45aa-bca4-220074f770e1"
      ],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Configure two possible X.509 certificates for test_user, and no other authentication options.

{
  "name": "<name-of-the-user-database>",
  "users": [
    {
      "certificates": [
        "<cert1>",
        "<cert2>"
      ],
      "passwords": [],
      "public_keys": [],
      "username": "test_user"
    }
  ]
}

Uploading certificates

SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Add a local user database

To add a local user database, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new local user database.

    You can find a detailed description of the available parameters listed in Local user databases.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/user_databases endpoint. If the POST request is successful, the response includes the key of the new local user database. For example:

{
  "key": "c4e60325-971a-44bc-ac01-e353dc6320d6",
  "meta": {
    "href": "/api/configuration/policies/user_databases/c4e60325-971a-44bc-ac01-e353dc6320d6",
    "parent": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a local user database

To modify a local usre database, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the local user database.

    You can find a detailed description of the available parameters listed in Local user databases.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/user_databases/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.44. Usermapping policy

For SSH, RDP, Telnet, and Citrix ICA connections, usermapping policies can be defined. A usermapping policy describes who can use a specific username to access the remote server: only members of the specified local or LDAP usergroups (for example, administrators) can use the specified username (for example, root) on the server.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/usermapping_policies

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the existing usermapping policies.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/usermapping_policies

The following command retrieves the properties of a specific usermapping policy.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/usermapping_policies<object-id>

Response

The following is a sample response received when listing usermapping policies. For details of the meta object, see Section 1.1, Message format.

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/usermapping_policies",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": null,
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/userlists",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "11581153055704544883f77",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies/11581153055704544883f77"
      }
    },
    {
      "key": "9328731525704545f5e3de",
      "meta": {
        "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
      }
    }
  ]
}

When retrieving the endpoint of a specific host key, the response is the following.

{
  "body": {
    "allow_other_remote_users_without_mapping": false,
    "mappings": [
      {
        "allowed_groups": [],
        "remote_user": "test"
      },
      {
        "allowed_groups": [
          "admins"
        ],
        "remote_user": "root"
      }
    ],
    "name": "Test"
  },
  "key": "9328731525704545f5e3de",
  "meta": {
    "first": "/api/configuration/policies/usermapping_policies/277736452570454272e157",
    "href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
    "last": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
    "next": null,
    "parent": "/api/configuration/policies/usermapping_policies",
    "previous": "/api/configuration/policies/usermapping_policies/11581153055704544883f77",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the policy.
body     Top level element (string) The elements of the usermapping policy.
  allow_other_remote_users_without_mapping   boolean

Default value: true.

To allow access the remote servers for users who are not explicitly listed in the Usermapping Policy, configure true. Note that these users must use the same username on the SCB gateway and the remote server.

  mappings   Top level list Contains the list of user groups and the corresponding remote usernames the group members can use to log in.
    allowed_groups list

The usergroups allowed to log in as the remote_user on the remote server.

Required element. Empty means all users.

    remote_user string

The username on the remote server that the users configured in allowed_groups can use to log in.

Required element. Must have a value.

Example mappings: 

Anyone can log in to the remote server as the test user:

"mappings": [
  {
    "allowed_groups": [],
    "remote_user": "test"
  }
]

Only the members of the admin group can log in to the remote server as the root user:

"mappings": [
  {
    "allowed_groups": [
      "admins"
    ],
    "remote_user": "root"
  }
]

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a usermapping policy

To add a usermapping policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new usermapping policy.

    You can find a detailed description of the available parameters listed in Usermapping policy.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/usermapping endpoint. If the POST request is successful, the response includes the key of the new usermapping policy. For example:

{
  "key": "2e8692fa-7fda-4753-8363-37e8244f6b80",
  "meta": {
    "href": "/api/configuration/policies/usermapping_policies/2e8692fa-7fda-4753-8363-37e8244f6b80",
    "parent": "/api/configuration/policies/usermapping_policies",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a usermapping policy

To modify a usermapping policy, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the usermapping policy.

    You can find a detailed description of the available parameters listed in Usermapping policy.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/usermapping/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.45. User lists

User lists are local white- or blacklists of usernames that allow fine-control over who can access a connection or a channel.

Note

User lists on SCB cannot prevent a user from accessing the server from a local terminal.

You can use user lists when configuring gateway_groups or remote_groups in the allowed_for element of channel policies. For more information on configuring channel policies, see Section 13.2, Channel policy.

To use this option, you must also configure web gateway authentication in the connection policy, or client-side gateway authentication back-end in the authentication policy.

URL

GET https://<IP-address-of-SCB>/api/configuration/policies/userlists

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the user lists created on SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/userlists

The following command retrieves the properties of a specific list.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/policies/userlists/<key-id>

Response

The following is a sample response received when retrieveing the user lists. For details of the meta object, see Section 1.1, Message format.

The keys with negative ID values are the default user lists of SCB.

{
  "meta": {
    "first": "/api/configuration/policies/audit_policies",
    "href": "/api/configuration/policies/userlists",
    "last": "/api/configuration/policies/usermapping_policies",
    "next": "/api/configuration/policies/usermapping_policies",
    "parent": "/api/configuration/policies",
    "previous": "/api/configuration/policies/user_databases",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "-1",
      "meta": {
        "href": "/api/configuration/policies/userlists/-1"
      }
    },
    {
      "key": "-2",
      "meta": {
        "href": "/api/configuration/policies/userlists/-2"
      }
    },
    {
      "key": "-3",
      "meta": {
        "href": "/api/configuration/policies/userlists/-3"
      }
    },
    {
      "key": "-4",
      "meta": {
        "href": "/api/configuration/policies/userlists/-4"
      }
    },
    {
      "key": "20088200245706af301b1ba",
      "meta": {
        "href": "/api/configuration/policies/userlists/20088200245706af301b1ba"
      }
    }
  ]
}

When retrieving the endpoint of a specific user list, the response is the following.

{
  "body": {
    "default": "exclude",
    "name": "root_only",
    "users": [
      "root"
    ]
  },
  "key": "-4",
  "meta": {
    "first": "/api/configuration/policies/userlists/-1",
    "href": "/api/configuration/policies/userlists/-4",
    "last": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "next": "/api/configuration/policies/userlists/20088200245706af301b1ba",
    "parent": "/api/configuration/policies/userlists",
    "previous": "/api/configuration/policies/userlists/-3",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the user list
body   Top level element (string) The elements of the user policy.
  default string

The default policy of the user list. Possible values are:

  • include creates a blacklist, where listed users are denied access.

  • exclude creates a whitelist, where only listed user are allowed access.

  name string

The name of the user list.

  users list

The usernames added to the list.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
400 InvalidQuery The requested filter or its value is invalid.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

Add a user list

To add a user list, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new user list.

    You can find a detailed description of the available parameters listed in User list elements.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/userlists endpoint. If the POST request is successful, the response includes the key of the new user list. For example:

{
  "key": "321314dc-eca0-4e97-b445-0612fedc0165",
  "meta": {
    "href": "/api/configuration/policies/userlists/321314dc-eca0-4e97-b445-0612fedc0165",
    "parent": "/api/configuration/policies/userlists",
    "transaction": "/api/transaction"
  }
}

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a user list

To modify a user list, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the user list.

    You can find a detailed description of the available parameters listed in User list elements.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/policies/userlists/<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

13.46. User management and access control

The AAA endpoint contains the configuration endpoints for the authentication, authorization, and account (AAA) settings of the users who access SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the AAA configuration endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/

Response

The following is a sample response received when listing AAA configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "acls",
      "meta": {
        "href": "/api/configuration/aaa/acls"
      }
    },
    {
      "key": "local_database",
      "meta": {
        "href": "/api/configuration/aaa/local_database"
      }
    },
    {
      "key": "settings",
      "meta": {
        "href": "/api/configuration/aaa/settings"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/aaa",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/alerting",
    "parent": "/api/configuration",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Description
acls Access control settings for usergroups.
local_database Local users and usergroups.
settings Authentication and user database settings.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.47. Authentication and user database settings

Contains settings for authenticating to SCB. You can create a user database locally on SCB, or connect to an LDAP server to authenticate users. You can configure authentication with passwords, X.509 certificates, or against a RADIUS server.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/settings

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the authentication and user database settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/settings

Response

The following is a sample response received when listing authentication and user database settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "backend": {
      "cracklib_enabled": false,
      "expiration_days": 0,
      "minimum_password_strength": "good",
      "remember_previous_passwords": 10,
      "selection": "local"
    },
    "method": {
      "selection": "passwd"
    },
    "require_commitlog": false
  },
  "key": "settings",
  "meta": {
    "first": "/api/configuration/aaa/acls",
    "href": "/api/configuration/aaa/settings",
    "last": "/api/configuration/aaa/settings",
    "next": null,
    "parent": "/api/configuration/aaa",
    "previous": "/api/configuration/aaa/local_database",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the properties of the !-OBJECT .
  backend Top level item Settings for the user database (local or LDAP), and password policy.
  method Top level item Settings for the authentication method (password, RADIUS server, or X.509 certificate).
  require_commitlog boolean Set to true to request the user to write an explanation to every configuration change.
Elements of backend Type Description
selection     string

Defines the user database back-end. Possible values are:

  • ldap

    Use an LDAP server (AD or POSIX) for authentication.

  • local

    Use a local user database for authentication.

cracklib_enabled     boolean

Password setting. Set to false if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Set to true to test the strength of user passwords with simple dictionary attacks before they are committed.

expiration_days     int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of days the user passwords are considered valid. Expired passwords must be changed upon login.

The 0 value means the passwords do not expire. The highest value you can configure is 365.

minimum_password_strength     string

Password setting. Set to disabled if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the required password strength for new passwords. Possible values are:

  • disabled

    Any password is accepted.

  • good

    Weak passwords are not accepted.

  • strong

    Only strong passwords are accepted.

remember_previous_passwords     int

Password setting. Set to 0 if a RADIUS server or X.509 certificate is used for authentication. Must be used if the value of the selection element is set to local.

Configures the number of previous passwords to retain to prevent password reuse.

The 0 value means passwords can be reused.

base_dn     string

Must be used if the value of the selection element is set to ldap.

Name of the DN to be used as the base of the queries.

bind_dn     string

Must be used if the value of the selection element is set to ldap.

Name of the DN where SCB should bind to before accessing the database.

bind_password     string

Must be used if the value of the selection element is set to ldap.

References the password SCB uses to authenticate on the server. You can find the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

encryption     Top level item

Must be used if the value of the selection element is set to ldap.

Configuration settings for encrypting the communication between SCB and the LDAP server.

  client_authentication   Top level item

Must be used with the selection child element.

Configures the X.509 certificate SCB uses to authenticate on the LDAP server.

    enabled boolean

Must be used with the client-authentication parent element.

Set to true if the LDAP server requires mutual authentication.

    x509_identity string

Must be used if the enabled element is set to true.

References the identifier of the X.509 certificate stored on SCB. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 host certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  selection   string

Defines the type of encryption SCB uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

  server_certificate_check   Top level item

Must be used with the selection child element.

Configuration settings for verifying the LDAP server's certificate.

    enabled boolean

Must be used with the server_certificate_check parent element.

Set to true to verify the LDAP server's certificate using the certificate of a Certificate Authority (CA).

    server_certificate_ca string

Must be used if the enabled element is set to true.

The certificate of the CA.

memberof_attribute     string

Must be used if the value of the selection element is set to ldap.

Optional. Configure this element if you have an LDAP schema where the user groups can only be determined from a user attribute that contains the group DNs. Using this option significantly slows down logon to the SCB web interface if you have too many groups.

The name of the user attribute (for example, in case of Active Directory: memberOf).

nested_groups     boolean

Must be used if the value of the selection element is set to ldap.

Set to true to use nested groups when querying the LDAP server

schema     Top level item

Must be used if the value of the selection element is set to ldap.

Schema settings for AD and POSIX servers.

  selection   string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

  • ad

    Microsoft Active Directory server.

  • posix

    Server uses the POSIX LDAP scheme.

    Must be used with the member_uid_attribute, unique_member_attribute and username_attribute elements.

  member_uid_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the POSIX group membership.

  unique_member_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the GroupOfUniqueMemberships membership.

  username_attribute   string

Must be used if the value of the selection element is set to posix.

Attribute name of the username (user ID).

servers     Top level list

Must be used if the value of the selection element is set to ldap.

Contains the addresses and ports of the LDAP servers.

  host   Top level item Contains the address of the LDAP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

    value string The address of the LDAP server.
  port   int The port of the LDAP server.
Elements of method Type Description
selection     string

Configures the authentication method. Possible values are:

  • passwd

    Use passwords for authentication.

  • radius

    Configure authentication against a RADIUS server.

  • x509

    Use X.509 certificates for authentication.

servers     Top level list

RADIUS setting. Must be used if the value of the selection element is set to radius.

Contains the RADIUS server addresses and port numbers, and references the shared secrets.

  address   Top level item

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address and port number of the RADIUS server.

    selection string

RADIUS setting. Must be used if the value of the selection element is set to radius.

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The RADIUS server address is provided as a fully qualified domain name.

  • ip

    The RADIUS server address is provided as an IP address.

    value string

RADIUS setting. Must be used if the value of the selection element is set to radius.

The address of the RADIUS server.

  port   int

RADIUS setting. Must be used if the value of the selection element is set to radius.

The port number of the RADIUS server.

  shared_secret   string

RADIUS setting. Must be used if the value of the selection element is set to radius.

References the identifier of the shared secret. You can view or modify the list of shared secrets at the /api/configuration/passwords/ endpoint.

To modify or add a shared secret, use the value of the returned key as the value of the shared_secret element, and remove any child elements (including the key).

admin_fallback     boolean

X.509 setting. Must be used if the value of the selection element is set to x509.

Set to true to allow the admin user to use password for login.

dn     string

X.509 setting. Must be used if the value of the selection element is set to x509.

X.509 DN field name of the username (case sensitive). In most cases, this value is either CN or UID.

trusted_ca     string

X.509 setting. Must be used if the value of the selection element is set to x509.

References the identifier of the trusted CA. You can view or modify the list of trusted CAs at the /api/configuration/policies/trusted_ca_lists/ endpoint.

To modify or add a trusted CA, use the value of the returned key as the value of the trusted_ca element, and remove any child elements (including the key).

Examples: 

Using a local user database with a password policy to authenticate the users of SCB:

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "good",
    "remember_previous_passwords": 10,
    "selection": "local"
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Using a local user database with a RADIUS server to authenticace the users of SCB. Note that the password-related elements have to be disabled, as the RADIUS server determines the password policy.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "selection": "radius",
    "servers": [
      {
        "address": {
          "selection": "ip",
          "value": "<server-ip>"
        },
        "port": <port>,
        "shared_secret": "<id-of-the-password>"
      }
    ]
  },
  "require_commitlog": false
}

Using a local user database with X.509 certificates to authenticace the users of SCB. Note that the password-related elements have to be disabled.

{
  "backend": {
    "cracklib_enabled": false,
    "expiration_days": 0,
    "minimum_password_strength": "disabled",
    "remember_previous_passwords": 0,
    "selection": "local"
  },
  "method": {
    "admin_fallback": true,
    "dn": "<CN>",
    "selection": "x509",
    "trusted_ca": "<id-of-the-trusted-ca>"
  },
  "require_commitlog": false
}

Using a POSIX server without communication encryption. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the POSIX server determines the password policy.

{
  "backend": {
    "base_dn": "<basedn>",
    "bind_dn": "<binddn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "selection": "disabled"
    },
    "memberof_attribute": "<user-attr-of-group-dns>",
    "nested_groups": true,
    "schema": {
      "member_uid_attribute": "<memberUid-attr>",
      "selection": "posix",
      "unique_member_attribute": "<uniqueMember-attr>",
      "username_attribute": "<uid-attr>"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Using Microsoft Active Directory server with mutual authentication, and the verification of the server's X.509 certificate. Note that for password authentication, the password-related elements have to be omitted from the JSON, as the AD server determines the password policy.

{
  "backend": {
    "base_dn": "<base-dn>",
    "bind_dn": "<bind-dn>",
    "bind_password": "<id-of-the-password>",
    "encryption": {
      "client_authentication": {
        "enabled": true,
        "x509_identity": "<id-of-the-cert>",
      "selection": "starttls",
      "server_certificate_check": {
        "enabled": true,
        "server_certificate_ca": "<cert>"
      }
    },
    "memberof_attribute": "<memberOf-attribute-name>",
    "nested_groups": true,
    "schema": {
      "selection": "ad"
    },
    "selection": "ldap",
    "servers": [
      {
        "host": {
          "selection": "ip",
          "value": "<ip-of-server>"
        },
        "port": <port>
      }
    ]
  },
  "method": {
    "selection": "passwd"
  },
  "require_commitlog": false
}

Modify the authentication and user database settings

To modify the authentication and user database settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Authentication and user database settings.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/settings endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.48. Privileges of usergroups

This endpoint lists the usergroups configured on SCB, and the privileges (ACLs) of each group.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/acls

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the local users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/acls

Response

The following is a sample response received when querying the endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "body": [
        {
            "group": "basic-view",
            "objects": [
                "/special/basic"
            ],
            "permission": "read"
        },
        {
            "group": "basic-write",
            "objects": [
                "/special/basic"
            ],
            "permission": "write"
        },
        {
            "group": "auth-view",
            "objects": [
                "/special/auth"
            ],
            "permission": "read"
        },
        {
            "group": "auth-write",
            "objects": [
                "/special/auth"
            ],
            "permission": "write"
        },
        {
            "group": "search",
            "objects": [
                "/special/searchmenu"
            ],
            "permission": "read"
        },
        {
            "group": "changelog",
            "objects": [
                "/special/changelog"
            ],
            "permission": "read"
        },
        {
            "group": "policies-view",
            "objects": [
                "/special/pol"
            ],
            "permission": "read"
        },
        {
            "group": "policies-write",
            "objects": [
                "/special/pol"
            ],
            "permission": "write"
        },
        {
            "group": "ssh-view",
            "objects": [
                "/special/ssh"
            ],
            "permission": "read"
        },
        {
            "group": "ssh-write",
            "objects": [
                "/special/ssh"
            ],
            "permission": "write"
        },
        {
            "group": "rdp-view",
            "objects": [
                "/special/rdp"
            ],
            "permission": "read"
        },
        {
            "group": "rdp-write",
            "objects": [
                "/special/rdp"
            ],
            "permission": "write"
        },
        {
            "group": "telnet-view",
            "objects": [
                "/special/telnet"
            ],
            "permission": "read"
        },
        {
            "group": "telnet-write",
            "objects": [
                "/special/telnet"
            ],
            "permission": "write"
        },
        {
            "group": "vnc-view",
            "objects": [
                "/special/vnc"
            ],
            "permission": "read"
        },
        {
            "group": "vnc-write",
            "objects": [
                "/special/vnc"
            ],
            "permission": "write"
        },
        {
            "group": "indexing",
            "objects": [
                "/special/search/search",
                "/special/bap"
            ],
            "permission": "write"
        },
        {
            "group": "ica-view",
            "objects": [
                "/special/ica"
            ],
            "permission": "read"
        },
        {
            "group": "ica-write",
            "objects": [
                "/special/ica"
            ],
            "permission": "write"
        },
        {
            "group": "api",
            "objects": [
                "/special/rpcapi"
            ],
            "permission": "write"
        },
        {
            "group": "http-view",
            "objects": [
                "/special/http"
            ],
            "permission": "read"
        },
        {
            "group": "http-write",
            "objects": [
                "/special/http"
            ],
            "permission": "write"
        },
        {
            "group": "indexer-view",
            "objects": [
                "/special/indexer"
            ],
            "permission": "read"
        },
        {
            "group": "indexer-write",
            "objects": [
                "/special/indexer"
            ],
            "permission": "write"
        }
    ],
    "key": "acls",
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/acls",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/local_database",
        "parent": "/api/configuration/aaa",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Element Type Description
body   Top level element (JSON object) Contains the properties of the user.
  group string The name of the usergroup.
  objects list The list of privileges that the group has access to.
  permission read | write The type of the permission. The group needs write access to configure an object, or to perform certain actions.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.49. Manage users and usergroups locally on SCB

Contains the endpoints for managing users and usergroups locally on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints of the local database.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database

Response

The following is a sample response received when listing the endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "groups",
            "meta": {
                "href": "/api/configuration/aaa/local_database/groups"
            }
        },
        {
            "key": "users",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/acls",
        "href": "/api/configuration/aaa/local_database",
        "last": "/api/configuration/aaa/settings",
        "next": "/api/configuration/aaa/settings",
        "parent": "/api/configuration/aaa",
        "previous": "/api/configuration/aaa/acls",
        "transaction": "/api/transaction"
    }
}
Element Description
groups Endpoint that contains local usergroups.
users Endpoint that contains local usernames.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.50. Manage usergroups locally on SCB

Contains the local usergroups of SCB. You can use local groups to control the privileges of SCB local and LDAP users — who can view and configure what. You can edit the group memberships here as well.

Note that currently you cannot edit the privileges (ACLs) of the groups using the REST API.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the local usergroups.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups

Response

The following is a sample response received when querying a particular usergroup endpoint. For details of the meta object, see Section 1.1, Message format.

{
    "body": {
        "members": [],
        "name": "http-write"
    },
    "key": "ca2dc85730ca082ee6b5c8",
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups/224696054489c27f6c5710",
        "href": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5c8",
        "last": "/api/configuration/aaa/local_database/groups/ca2dc85730ca082ee6b5f8",
        "next": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1f9",
        "parent": "/api/configuration/aaa/local_database/groups",
        "previous": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
        "transaction": "/api/transaction"
    }
}
Element Type Description
body   Top level element (JSON object) Contains the properties of the usergroup.
  members list Lists the names of the users belonging to the group.
  name string The name of the group.
key   string Top level element, contains the ID of the endpoint.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Section 6, Open a transaction).

Add new local usergroup

To create a new local usergroup, you have to POST the name and members of the group as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups endpoint. For details, see Section 12.2, Create a new object.

  1. Open a transaction. For details, see Section 6, Open a transaction.

  2. Create a new usergroup. POST the name of the group and the list of member accounts as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups endpoint. The body of the POST request should be the following. Note that you must refer to existing user accounts, and use their reference IDs, not their usernames.

    {
        "name": "new-userggroup",
        "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]
    }

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups --data "{"name": "new-usergroup", "members": ["46785097158061f46c63d0", "1362061674580df4e00620d"]}"

    If the POST request is successful, the response includes a reference ID for the usergroup object.

  3. Commit your changes. For details, see Section 7, Commit a transaction.

Delete usergroup

To delete a usergroup, you have to:

  1. Open a transaction (for details, see Section 6, Open a transaction).

  2. DELETE the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/groups/<ID-of-the-group> endpoint. For details, see Section 12.1, Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

    {
        "meta": {
            "href": "/api/configuration/aaa/local_database/groups/b080b1ba546232548bb1a9",
            "parent": "/api/configuration/aaa/local_database/groups"
        }
    }
  3. Commit your changes to actually delete the object from SCB (for details, see Section 7, Commit a transaction).

13.51. Manage users locally on SCB

Contains the local users of SCB. You can use local users and groups to control the privileges of SCB local and LDAP users — who can view and configure what.

Note

The admin user is available by default and has all possible privileges. It is not possible to delete this user.

Local users cannot be managed when LDAP authentication is used. When LDAP authentication is enabled, the accounts of local users is disabled, but they are not deleted,

When using RADIUS authentication together with local users, the users are authenticated to the RADIUS server, only their group memberships must be managed locally on SCB.

For details, see Section 13.47, Authentication and user database settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the local users.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users

The following command displays the parameters of a specific user.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<ID-of-the-user>

Response

The following is a sample response received when querying the list of users. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "103640099357f3b14f0529a",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a"
            }
        },
        {
            "key": "46785097158061f46c63d0",
            "meta": {
                "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa/local_database/groups",
        "href": "/api/configuration/aaa/local_database/users",
        "last": "/api/configuration/aaa/local_database/users",
        "next": null,
        "parent": "/api/configuration/aaa/local_database",
        "previous": "/api/configuration/aaa/local_database/groups",
        "transaction": "/api/transaction"
    }
}

The following is a sample response received when querying a specific user.

{
    "body": {
        "name": "testuser",
        "password": {
            "key": "8f84d7d1-9de1-429a-a7a7-c33a61cc7419",
            "meta": {
                "href": "/api/configuration/passwords/8f84d7d1-9de1-429a-a7a7-c33a61cc7419"
            }
        },
        "password_created": 1476796261
    },
    "key": "46785097158061f46c63d0",
    "meta": {
        "first": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "href": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "last": "/api/configuration/aaa/local_database/users/46785097158061f46c63d0",
        "next": null,
        "parent": "/api/configuration/aaa/local_database/users",
        "previous": "/api/configuration/aaa/local_database/users/103640099357f3b14f0529a",
        "transaction": "/api/transaction"
    }
Element Type Description
body   Top level element (JSON object) Contains the properties of the user.
  name string The username of the user account.
  password reference A reference to a password object. To create or update passwords, see Section 13.85, Passwords stored on SCB.
  password_created integer The date when the password of the account was changed in UNIX timestamp format (for example, 1476796261).
key   string Top level element, contains the ID of the user.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
400 SemanticError You tried to reuse a password object. You can use a password object for only one purpose, that is, you cannot reference a password object twice.
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.
409 NoTransaction No open Transaction is available. You must open a transaction first (for details, see Section 6, Open a transaction).

Add new local user

To create a new local user account, you have to POST the username and the reference ID of the password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users endpoint. For details, see Section 12.2, Create a new object.

  1. Open a transaction. For details, see Section 6, Open a transaction.

  2. Create a new password object. SCB returns the reference ID of the password. For details, see Section 13.85, Passwords stored on SCB.

  3. Create a new user account. POST the username and the reference ID of the password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users endpoint. The body of the POST request should be the following.

    {
        "name": "new-user",
        "password": "<value-of-the-key-attribute-from-the-previous-step>"
    }

    For example:

    curl -X POST -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users --data "{"name": "new-user", "password": "<value-of-the-key-attribute-from-the-previous-step>"}"

    If the POST request is successful, the response includes a reference ID for the user object.

  4. Commit your changes. For details, see Section 7, Commit a transaction.

Change password for a local user

To change the password of a user, you have to create a new password, then PUT the username and the reference ID of the new password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> endpoint.

  1. Open a transaction. For details, see Section 6, Open a transaction.

  2. Create a new password object. SCB returns the reference ID of the password. For details, see Section 13.85, Passwords stored on SCB.

  3. Update the user account. PUT the username and the reference ID of the new password as a JSON object to the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> endpoint. The body of the PUT request should be the following.

    {
        "name": "username",
        "password": "<value-of-the-key-attribute-from-the-previous-step>"
    }

    For example:

    curl -X PUT -H "Content-Type: application/json" --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<reference-id-of-the-user-account> --data "{"name": "new-user", "password": "<value-of-the-key-attribute-from-the-previous-step>"}"

    If the request is successful, the response includes the reference ID for the user object.

  4. Commit your changes. For details, see Section 7, Commit a transaction.

Delete user

To delete a user, you have to:

  • Open a transaction (for details, see Section 6, Open a transaction).

  • DELETE the https://<IP-address-of-SCB>/api/configuration/aaa/local_database/users/<ID-of-the-user> endpoint. For details, see Section 12.1, Delete an object. If the DELETE request is successful, the response includes only the meta object, for example:

    {
        "meta": {
            "href": "/api/configuration/aaa/local_database/users/b080b1ba546232548bb1a9",
            "parent": "/api/configuration/aaa/local_database/users"
        }
    }
  • Commit your changes to actually delete the object from SCB (for details, see Section 7, Commit a transaction).

13.52. Management options

Contains the configuration endpoints for managing SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists management configuration endpoints.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management

Response

The following is a sample response received when listing management endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "certificates",
      "meta": {
        "href": "/api/configuration/management/certificates"
      }
    },
    {
      "key": "disk_fillup_prevention",
      "meta": {
        "href": "/api/configuration/management/disk_fillup_prevention"
      }
    },
    {
      "key": "email",
      "meta": {
        "href": "/api/configuration/management/email"
      }
    },
    {
      "key": "health_monitoring",
      "meta": {
        "href": "/api/configuration/management/health_monitoring"
      }
    },
    {
      "key": "snmp",
      "meta": {
        "href": "/api/configuration/management/snmp"
      }
    },
    {
      "key": "soap",
      "meta": {
        "href": "/api/configuration/management/soap"
      }
    },
    {
      "key": "syslog",
      "meta": {
        "href": "/api/configuration/management/syslog"
      }
    },
    {
      "key": "webinterface",
      "meta": {
        "href": "/api/configuration/management/webinterface"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/management",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/network",
    "parent": "/api/configuration",
    "previous": "/api/configuration/local_services",
    "transaction": "/api/transaction"
  }
}
Endpoints Description
certificates References the certificates of SCB's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web interface.
disk_fillup_prevention Disk fill-up prevention.
email SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.
health_monitoring Configuration settings for monitoring the utilization of SCB.
snmp SNMP settings.
soap Configuration settings for the RPC API.
syslog Syslog server address and authentication.
webinterface Configuration settings for the SCB web interface.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.53. Internal certificates

This endpoint references the certificates of SCB's internal Certificate Authority, Timestamping Authority, and the SSL certificate of the web interface.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/certificates

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the internal certificates of SCB.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/certificates

Response

The following is a sample response received when listing the internal certificates of SCB. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "ca": {
      "selection": "identity",
      "x509_identity": {
        "key": "fbd684e1-e1ac-4f34-ad25-86c560c51e24",
        "meta": {
          "href": "/api/configuration/x509/fbd684e1-e1ac-4f34-ad25-86c560c51e24"
        }
      }
    },
    "server": {
      "key": "fd1c73e8-bcb8-4d13-991f-722f492dc074",
      "meta": {
        "href": "/api/configuration/x509/fd1c73e8-bcb8-4d13-991f-722f492dc074"
      }
    },
    "tsa": {
      "key": "20e72ede-78ef-460a-b843-68a35d994142",
      "meta": {
        "href": "/api/configuration/x509/20e72ede-78ef-460a-b843-68a35d994142"
      }
    }
  },
  "key": "certificates",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/certificates",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/disk_fillup_prevention",
    "parent": "/api/configuration/management",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string The ID of the endpoint.
body     Top level element (string) Contains the internal certificates of SCB.
  ca   Top level item Contains the certificate of SCB's internal Certificate Authority.
    selection string Must be set to identity.
    x509_identity string

References the certificate of SCB's internal Certificate Authority. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  server   string

References the SSL certificate of SCB's web interface. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  tsa   string

References the certificate of SCB's internal Timestamping Authority. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

Modify a certificate

To modify a certificate, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Have the value of the key element of a valid X.509 CA certificate stored on SCB.

  • Modify the JSON object of the endpoint. Use the X.509 certificate's key as the value of the ca element

    You can find a detailed description of the available parameters listed in Internal certificates.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/certificates endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.54. Disk fill-up prevention

Contains the configuration options for preventing disk fill-up.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists disk fill-up prevention options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention

Response

The following is a sample response received when listing disk fill-up prevention settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "archiving_enabled": false,
    "enabled": true,
    "used_space_ratio_limit": 80
  },
  "key": "disk_fillup_prevention",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/disk_fillup_prevention",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/email",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/certificates",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the configuration settings for disk fill-up prevention.
  archiving_enabled boolean

Set to true to automatically start all configured archiving/cleanup jobs when disk usage goes over the value of the used_space_ratio_limit element.

  enabled boolean Set to true to enable disk fill-up prevention.
  used_space_ratio_limit int

Disk utilization limit, in percent. When used disk space reaches this limit, SCB disconnects all clients.

Set to 0 to turn the feature off.

Modify disk fill-up prevention settings

To modify the disk fill-up prevention settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the disk fill-up configuration endpoint.

    You can find a detailed description of the available parameters listed in Disk fill-up prevention.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/disk_fillup_prevention endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.55. Mail settings

Configuration settings for SMTP server address and authentication, administrator e-mail, and e-mail addresses for alerts and reports.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/email

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists mail settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/email

Response

The following is a sample response received when listing mail settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "admin_address": "<admin-email>",
    "alerting_address": "<alerts-target-email>",
    "reporting_address": "<reports-target-email>",
    "sender_address": null,
    "smtp_auth": {
      "enabled": false
    },
    "smtp_encryption": {
      "selection": "disabled"
    },
    "smtp_server": {
      "selection": "ip",
      "value": "<smtp-server-ip>"
    }
  },
  "key": "email",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/email",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/health_monitoring",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/disk_fillup_prevention",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the configuration options for e-mail.
  admin_address   string The e-mail address of the administrator of SCB.
  alerting_address   string The e-mail address where monitoring alerts are sent.
  reporting_address   string The e-mail address where traffic reports are sent.
  sender_address   string The address of the sender (SCB).
  smtp_auth   Top level item Configures authentication to the SMTP server.
    enabled boolean Set to true to enable authenticating to the SMTP server.
    password string

References the password of the authenticating user. You can list password at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

    username string The username for authenticating to the SMTP server.
  smtp_encryption   Top level item Configuration settings for encrypting the communication between SCB and the SMTP server.
  smtp_server   Top level item Contains the address of the SMTP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The SMTP server address is provided as a fully qualified domain name.

  • ip

    The SMTP server address is provided as an IP address.

    value string The address of the SMTP server.
Elements of smtp_encryption Type Description
client_authentication   Top level item

Configures authenticating as a client with an X.509 certificate.

Can only be enabled if the value of the selection element is set to starttls.

  enabled boolean

Set to true to enable authenticating as a client with an X.509 certificate.

Can only be enabled if the value of the selection element of snmp_encryption is set to starttls.

  x509_identity  

References the identifier of the authenticating client's X.509 certificate. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

selection   string

Configures encrypted communication with the SMTP server. The following values are possible:

  • disabled

    Disables e-mail encryption.

  • starttls

    Enables STARTTLS encryption.

server_certificate_check   Top level item

Configuration settings for validating the SMTP server's certificate.

Can only be enabled if the value of the selection element is set to starttls.

  enabled boolean

Set to true to enable validating the SMTP server's certificate.

Can only be enabled if the value of the selection element of snmp_encryption is set to starttls.

  server_certificate_ca string The CA certificate of the Certificate Authority.

Examples: 

Enable authentication to the SMTP server.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "aec663b5-f5bd-4c93-bb51-36fea3328e58",
      "meta": {
        "href": "/api/configuration/passwords/aec663b5-f5bd-4c93-bb51-36fea3328e58"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "selection": "disabled"
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

Configure STARTTLS encryption without certificate checks.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "0210848a-b301-47d5-9023-779c5fe951f7",
      "meta": {
        "href": "/api/configuration/passwords/0210848a-b301-47d5-9023-779c5fe951f7"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "client_authentication": {
      "enabled": false
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": false
    }
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

Configure STARTTLS encryption with server certificate check, and authenticate as client with an X.509 certificate.

{
  "admin_address": "<admin-email>",
  "alerting_address": "<alerts-target-email>",
  "reporting_address": "<reports-target-email>",
  "sender_address": null,
  "smtp_auth": {
    "enabled": true,
    "password": {
      "key": "37716c4f-759d-4900-9740-ea22211498cf",
      "meta": {
        "href": "/api/configuration/passwords/37716c4f-759d-4900-9740-ea22211498cf"
      }
    },
    "username": "<smtp-username>"
  },
  "smtp_encryption": {
    "client_authentication": {
      "enabled": true,
      "x509_identity": {
        "key": "c3a23e32-d75b-461e-afc0-14d1f6692879",
        "meta": {
          "href": "/api/configuration/x509/c3a23e32-d75b-461e-afc0-14d1f6692879"
        }
      }
    },
    "selection": "starttls",
    "server_certificate_check": {
      "enabled": true,
      "server_certificate_ca": "<ca-cert>"
    }
  },
  "smtp_server": {
    "selection": "ip",
    "value": "<smtp-server-ip>"
  }
}

CA certificates

CA certificates must not contain any metadata. SCB uses only the key part of the certificate.

To use a certificate with the SCB API, remove all metadata, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Modify mail settings

To modify mail settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Mail settings.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/email endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.56. Health monitoring

Configuration settings for monitoring the utilization of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/health_monitoring

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists health monitoring settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/health_monitoring

Response

The following is a sample response received when listing health monitoring settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "maximum_disk_utilization_ratio": 80,
    "maximum_load1": null,
    "maximum_load15": null,
    "maximum_load5": null,
    "maximum_swap_utilization_ratio": 70
  },
  "key": "health_monitoring",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/health_monitoring",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/snmp",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/email",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains health monitoring settings.
  maximum_disk_utilization_ratio   int The highest allowed value for disk utilization (in %).
  maximum_load1   int Average maximum for load for 1 minute.
  maximum_load15   int Average maximum load for 15 minutes.
  maximum_load5   int Average maximum load for 5 minutes.
  maximum_swap_utilization_ratio   int The highest allowed value for swap utilization (in %).

Modify health monitoring settings

To modify health monitoring settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Health monitoring.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/health_monitoring endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.57. SNMP settings

Contains the configuration endpoints for SNMP settings.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/snmp

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints for SNMP configuration settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/snmp

Response

The following is a sample response received when listing SNMP configuration endpoints. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "trap",
      "meta": {
        "href": "/api/configuration/management/snmp/trap"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/snmp",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/soap",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/health_monitoring",
    "transaction": "/api/transaction"
  }
}
Element Description
trap Configuration settings for SNMP traps.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.58. SNMP traps

Configuration settings for the address and protocol of the SNMP server.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/snmp/trap

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists !-INTRO .

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/snmp/trap

Response

The following is a sample response received when listing the address and protocol settings of the SNMP server. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "enabled": true,
    "version": {
      "selection": "2c",
      "value": {
        "community": "public",
        "server": {
          "selection": "ip",
          "value": "10.20.30.40"
        }
      }
    }
  },
  "key": "trap",
  "meta": {
    "first": "/api/configuration/management/snmp/trap",
    "href": "/api/configuration/management/snmp/trap",
    "last": "/api/configuration/management/snmp/trap",
    "next": null,
    "parent": "/api/configuration/management/snmp",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the address and protocol settings of the SNMP server.
  enabled boolean Set to true to send alerts to an SNMP server.
  version Top level item Contains the configuration settings for the server address, and the SNMP protocol.
Elements of version Type Description  
selection     string

Defines the SNMP protocol to use. Possible values are:

  • 2c

    Configures version 2c of the SNMP protocol.

  • 3

    Configures version 3 of the SNMP protocol.

value     Top level item Contains the SNMP server address, and the protocol-specific settings.
  auth_method   string

Required parameter when using SNMP version 3. Configures encrypted communication with the SNMP server. Possible values are:

  • md5: Use MD5 encryption. The auth_password element must reference a valid password.

  • sha1: Use SHA1 encryption. The auth_password element must reference a valid password.

  auth_password   string

Required parameter when using SNMP version 3. References the password used for authenticating to the SNMP server. You can view the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  community   string

Must be used if version 2c of the SNMP protocol is configured.

The name of the SNMP community.

  encryption_method   string

Must be used if version 3 of the SNMP protocol is configured.

Configures encrypted communication with the SNMP server. Possible values are:

  • none: No encryption. The value of the encryption_password element must also be set to null.

  • aes: AES encryption. The encryption_password element must reference a valid password.

  • des: DES encryption. The encryption_password element must reference a valid password.

  encryption_password   string

Must be used if version 3 of the SNMP protocol is configured.

Set to null if the value of the encryption_method is set to none.

References the password used for encrypting the communication with the SNMP server. You can view the list of passwords at the /api/configuration/passwords/ endpoint.

To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character.

  engine_id   string

Must be used if version 3 of the SNMP protocol is configured.

The Engine ID. Must be a a hexadecimal number at least 10 digits long (for example, 0x0123456789ABCDEF).

  server   top level item Contains the IP address of FQDN of the SNMP server.
    selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The SNMP server address is provided as a fully qualified domain name.

  • ip

    The SNMP server address is provided as an IP address.

    value string The address of the SNMP server.
  username   string

Must be used if version 3 of the SNMP protocol is configured.

The username for sending SNMP traps.

Examples: 

Configure a server with the SNMP v2c protcol.

{
  "enabled": true,
  "version": {
    "selection": "2c",
    "value": {
      "community": "public",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      }
    }
  }
}

Configure a server with the SNMP v3 protocol, and MD5 authentication.

{
  "enabled": true,
  "version": {
    "selection": "3",
    "value": {
      "auth_method": "md5",
      "auth_password": {
        "key": "d21f3675-8dff-43c5-a982-17839390a6b3",
        "meta": {
          "href": "/api/configuration/passwords/d21f3675-8dff-43c5-a982-17839390a6b3"
        }
      },
      "encryption_method": "none",
      "encryption_password": null,
      "engine_id": "<0x0123456789ABCDEF>",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "username": "<username>"
    }
  }
}

Configure a server with the SNMP v3 protocol, SHA1 authentication, and AES-encrypted communication.

{
  "enabled": true,
  "version": {
    "selection": "3",
    "value": {
      "auth_method": "sha",
      "auth_password": {
        "key": "0f5f646d-d6e7-4a4a-bc66-ead670faff3f",
        "meta": {
          "href": "/api/configuration/passwords/0f5f646d-d6e7-4a4a-bc66-ead670faff3f"
        }
      },
      "encryption_method": "aes",
      "encryption_password": {
        "key": "6237d67a-b6b4-49e0-b0f6-6d68d0f08cc3",
        "meta": {
          "href": "/api/configuration/passwords/6237d67a-b6b4-49e0-b0f6-6d68d0f08cc3"
        }
      },
      "engine_id": "<0x0123456789ABCDEF>",
      "server": {
        "selection": "ip",
        "value": "<server-ip>"
      },
      "username": "<username>"
    }
  }
}

Modify SNMP trap settings

To modify the address and protocol settings for the SNMP server, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the SNMP trap endpoint.

    You can find a detailed description of the available parameters listed in SNMP trap.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/ !-ENDPOINT /<key-of-the-object> endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.59. RPC API

The SCB RPC API allows you to access, query, and manage SCB from remote applications. You can access the API using the Simple Object Access Protocol (SOAP) protocol over HTTPS, meaning that you can use any programming language that has access to a SOAP client to integrate SCB to your environment.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/soap

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the RPC API settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/soap

Response

The following is a sample response received when listing the RPC API settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "enabled": true
  },
  "key": "soap",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/soap",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/syslog",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/snmp",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the RPC API configuration options.
  enabled boolean Set to true to enable the RPC API.

Modify RPC API settings

To modify the RPC API settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in RPC API.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/soap endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.60. Syslog server settings

SCB can send its system log messages to remote syslog servers, for example, syslog-ng Premium Edition, syslog-ng Store Box, Splunk, or HPE ArcSight Data Platform.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/syslog

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the syslog server settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/syslog

Response

The following is a sample response received when listing syslog server settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "certificates": {
      "ca": "<ca-cert>",
      "client": {
        "key": "191725ec-b71b-47ab-9e87-561a5d9e2bb7",
        "meta": {
          "href": "/api/configuration/x509/191725ec-b71b-47ab-9e87-561a5d9e2bb7"
        }
      }
    },
    "include_node_id": true,
    "receivers": [
      {
        "address": {
          "selection": "ip",
          "value": "10.20.30.40"
        },
        "port": 514,
        "protocol": {
          "ip_protocol": "tcp",
          "protocol_type": "legacy-bsd",
          "tls_enabled": false
        }
      }
    ],
    "server_key_check": "optional-trusted"
  },
  "key": "syslog",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/syslog",
    "last": "/api/configuration/management/webinterface",
    "next": "/api/configuration/management/webinterface",
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/soap",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key     string Top level element, contains the ID of the endpoint.
body     Top level element (string) Contains the syslog server configuration settings.
  certificates   Top level item Contains the certificates of the client (SCB), and the certificate of the CA.
    ca string

The CA certificate of the Certificate Authority. Configure this option if the value of the tls_enabled element is set to true.

    client string

Configure this option if the value of the tls_enabled element is set to true, and the syslog server requires mutual authentication. Otherwise, set its value to null.

References the identifier of the client's (SCB's) X.509 certificate. You can configure X.509 certificates at the /api/configuration/x509/ endpoint.

To modify or add an X.509 certificate, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key).

  include_node_id   boolean

Set to true to display separate hostnames for syslog messages sent by the nodes of a SCB HA cluster.

The node ID included in the hostname filed of the syslog message is the MAC address of the node's HA interface. Messages of the core firmware are always sent by the master node.

  receivers   Top level list Contains the addresses of the syslog servers.
  server_key_check   string

Configures validating the syslog server's certificate with the CA. The following values are possible:

  • optional-trusted

    If the server sends a certificate, SCB checks if it is valid (not expired) and that the Common Name of the certificate contains the domain name or the IP address of the server. If these checks fail, SCB rejects the connection. However, SCB accepts the connection if the server does not send a certificate.

  • optional-untrusted

    SCB accepts any certificate shown by the server.

  • required-trusted

    SCB verifies the certificate shown by the server.

  • required-untrusted

    SCB requests a certificate from the server, and rejects the connection if no certificate is received, if the certificate is not valid (expired), or if the Common Name of the certificate does not contain the domain name or the IP address of the server.

Elements of receivers Type Description
address   Top level item Contains the address of the syslog server.
  selection string

Defines the address type (IP or domain name). Possible values are:

  • fqdn

    The syslog server address is provided as a fully qualified domain name.

  • ip

    The syslog server address is provided as an IP address.

  value string The address of the syslog server.
port   int The port of the syslog server.
protocol   Top level item Contains the syslog protocol settings.
  ip_protocol string

Configures the IP protocol. The following options are available:

  • tcp

    TCP protocol.

  • udp

    UDP protocol.

  protocol_type string

Configures the syslog protocol. The following options are available:

  • legacy-bsd

    BSD-syslog protocol.

  • syslog

    IETF-syslog protocol.

  tls_enabled string

Set to true to enable TLS encryption.

If TLS is enabled, the value of the ca and client elements cannot be null.

Examples: 

Default settings: no external syslog servers.

{
  "certificates": {
    "ca": null,
    "client": null
  },
  "include_node_id": true,
  "receivers": [],
  "server_key_check": "optional-untrusted"
}

Uploading CA certificates

SCB uses only the key part of the CA certificate.

To use a certificate with the SCB API, remove all data, and substitute line breaks with \n.

The following is an example certificate, as used on the SCB web interface:

-----BEGIN CERTIFICATE-----
MIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC
Q0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT
B0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi
aXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2
MDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP
bnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD
VQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN
AQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS
59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw
0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc
3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs
X5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX
hJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA
R5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP
AB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy
0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB
uNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc
N5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt
qYyyD1ld89OUEYZ+aJQd/A==
-----END CERTIFICATE-----

The same certificate, as accepted by the SCB API:

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDnDCCAoQCCQDc536Ob5tPQTANBgkqhkiG9w0BAQUFADCBjzELMAkGA1UEBhMC\nQ0ExEDAOBgNVBAgTB09udGFyaW8xEDAOBgNVBAcTB1Rvcm9udG8xEDAOBgNVBAoT\nB0JhbGFiaXQxFjAUBgNVBAsTDURvY3VtZW50YXRpb24xEDAOBgNVBAMTB2JhbGFi\naXQxIDAeBgkqhkiG9w0BCQEWEWNhdGFpbEBiYWxhYml0Lmh1MB4XDTE2MDQyMjE2\nMDAyNloXDTE3MDQyMjE2MDAyNlowgY8xCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdP\nbnRhcmlvMRAwDgYDVQQHEwdUb3JvbnRvMRAwDgYDVQQKEwdCYWxhYml0MRYwFAYD\nVQQLEw1Eb2N1bWVudGF0aW9uMRAwDgYDVQQDEwdiYWxhYml0MSAwHgYJKoZIhvcN\nAQkBFhFjYXRhaWxAYmFsYWJpdC5odTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBAOGa9I2jmVlVdVWEI/Wy7ahTeyaIjK52FQUXqxG8okOSD+nV74ZFUuiS\n59X+2Ow1aDqVGrDMgPNhSVpYXUvDUAUOILJW4rAIoxDY6vDU9/4v9dDiQfEPlauw\n0qNRjPS1MLzjSOQDSKqPkdivkS6HKZeX3+TFq3OxO+vIrF9zFfp9T+eDG2oSobPc\n3mV2zkvtD61CXzbezAVdArDl6WnysRyzxyH8WEhFwZepWxFD9Y5N1dzKody7Hncs\nX5kVIv0+Z6bBHfg/7wHWysJdwNuLr0ByTOvPM6WdA83k3Fy2gYNk7Rc0BbRFbQTX\nhJVfUzSUWHVhFQtAb4diKU5voqepfNMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEA\nR5DIwOHsEKoGkiI3cHC2VMnxP2rRhpTneh6El+DFnQPdjrXa+tnqV4TdnNaD+FvP\nAB1kqbmC4hJAsjMLU2b1ne6m+SLmzhRuMxcA6x+fnYvcQT57IbRdq2E/4oJGeyuy\n0jQE+nmoVD3lDytIOxCfQvZhl1tcbBE5hp5USme4PmNhY6QfUlgjsFjPfoVG7XDB\nuNaUoWS6RvZPmL5IuvF9tqe96ES6DTjC8rBfQYvSoVNjjPnUMx0C8xstRSEG7oJc\nN5+4ImYnFNxSG20hZpFy0OFDf2g7Fx+W50/NtXamUF1Sf8WlPZc03oVl1/Fzo7mt\nqYyyD1ld89OUEYZ+aJQd/A==\n-----END CERTIFICATE-----\n"

Modify syslog server settings

To modify the syslog server settings, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Syslog server.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/syslog endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.61. Web interface

Configuration options for the web interface of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/management/webinterface

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configuration options for the SCB web interface.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/management/webinterface

Response

The following is a sample response received when listing the configuration options of the SCB web interface. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "timeout": 10
  },
  "key": "webinterface",
  "meta": {
    "first": "/api/configuration/management/certificates",
    "href": "/api/configuration/management/webinterface",
    "last": "/api/configuration/management/webinterface",
    "next": null,
    "parent": "/api/configuration/management",
    "previous": "/api/configuration/management/syslog",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the configuration options of the SCB web interface.
  timeout int Session timeout, in minutes.

Modify the configuration of the web interface

To modify the configuration of the web interface, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Web interface.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/management/webinterface endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.62. Network configuration options

Contains the endpoints for configuring networking on SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/network

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists network configuration options.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network

Response

The following is a sample response received when listing network configuration options. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "dns",
      "meta": {
        "href": "/api/configuration/network/dns"
      }
    },
    {
      "key": "ip_forwarding_rule_pairs",
      "meta": {
        "href": "/api/configuration/network/ip_forwarding_rule_pairs"
      }
    },
    {
      "key": "naming",
      "meta": {
        "href": "/api/configuration/network/naming"
      }
    },
    {
      "key": "nics",
      "meta": {
        "href": "/api/configuration/network/nics"
      }
    },
    {
      "key": "routing",
      "meta": {
        "href": "/api/configuration/network/routing"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/network",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/passwords",
    "parent": "/api/configuration",
    "previous": "/api/configuration/management",
    "transaction": "/api/transaction"
  }
}
Element Description
dns The address of the primary and secondary DNS server.
ip_forwarding_rule_pairs Rules for routing between the network interfaces.
naming DNS search domain, hostname, and appliance nickname settings.
nics References the endpoints of the three physical network interfaces.
routing Routing table. Defines the address of the gateway server for each configured subnet.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.63. DNS servers

Contains the address of the primary and secondary DNS server.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/dns

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configured DNS servers.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/dns

Response

The following is a sample response received when listing the configured DNS servers. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "primary": "192.168.56.1",
    "secondary": null
  },
  "key": "dns",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/dns",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/ip_forwarding_rule_pairs",
    "parent": "/api/configuration/network",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoints.
body   Top level element (string) Contains the addresses of the DNS servers.
  primary string The IP address of the primary DNS server.
  secondary string The address of the secondary DNS server.

Modify the address of the DNS servers

To modify the addres of a DNS server, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in DNS servers.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/dns endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.64. Routing between interfaces

Configures routing between network interfaces. To use an interface in single-interface router mode, configure both interface_a and interface_b elements to reference that same interface.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists interface routing rules.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs

Response

The following is a sample response received when listing interface routing rules. For details of the meta object, see Section 1.1, Message format.

{
  "body": [
    {
      "interface_a": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      },
      "interface_b": {
        "key": "nic1.interfaces.ff7574025754b3df1647001",
        "meta": {
          "href": "/api/configuration/network/nics/nic1/interfaces/ff7574025754b3df1647001"
        }
      }
    }
  ],
  "key": "ip_forwarding_rule_pairs",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/ip_forwarding_rule_pairs",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/naming",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/dns",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (list) Contains the rules for routing between the network interfaces.
  interface_a string

References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint.

To modify or add a network interface, use the value of the returned key as the value of the interface_a element, and remove any child elements (including the key).

  interface_b string

References the identifier of the network interface. You can configure network interfaces at the /api/configuration/network/nics/ endpoint.

To modify or add a network interface, use the value of the returned key as the value of the interface_b element, and remove any child elements (including the key).

Add a rule for routing between the network interfaces

To add a rule, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new list of rules.

    You can find a detailed description of the available parameters listed in Routing between interfaces.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs endpoint. If the POST request is successful, the response includes the key of the new !-OBJECT . For example:


To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify a rule for routing between the network interfaces

To modify a rule, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the list of rules.

    You can find a detailed description of the available parameters listed in Routing between interfaces.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/ip_forwarding_rule_pairs endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.65. Naming options

Contains the settings for the DNS search domain, hostname, and appliance nickname.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/naming

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the naming settings.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/naming

Response

The following is a sample response received when listing naming settings. For details of the meta object, see Section 1.1, Message format.

{
  "body": {
    "domainname": "balabit",
    "hostname": "scb-api-docs",
    "nickname": null
  },
  "key": "naming",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/naming",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/nics",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/ip_forwarding_rule_pairs",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (string) Contains the naming settings.
  domainname string The domain name of the network.
  hostname string The hostname of SCB.
  nickname string The nickname for the appliance. Use this name to distinguish between multiple SCB appliances on the network. This name is visible in the boot and core login shells.

Modify a name

To modify a name, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the endpoint.

    You can find a detailed description of the available parameters listed in Naming settings.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/network/naming endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.66. Network addresses

Contains the network addresses configured for each physical NIC.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/nics

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the endpoints for the physical network interfaces.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/

The following commands retrieve the properties of a specific physical network interface.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic1
curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic2
curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/nics/nic3

Response

The following is a sample response received when listing physical network interfaces. For details of the meta object, see Section 1.1, Message format.

{
  "items": [
    {
      "key": "nic1",
      "meta": {
        "href": "/api/configuration/network/nics/nic1"
      }
    },
    {
      "key": "nic2",
      "meta": {
        "href": "/api/configuration/network/nics/nic2"
      }
    },
    {
      "key": "nic3",
      "meta": {
        "href": "/api/configuration/network/nics/nic3"
      }
    }
  ],
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/nics",
    "last": "/api/configuration/network/routing",
    "next": "/api/configuration/network/routing",
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/naming",
    "transaction": "/api/transaction"
  }
}

When retrieving the endpoint of a specific physical network interface, the response is the following.

{
  "body": {
    "interfaces": {
      "@order": [
        "ff7574025754b3df1647001"
      ],
      "ff7574025754b3df1647001": {
        "addresses": {
          "1": "192.168.56.101/24",
          "4323998795727ae1ab8750": "192.168.56.151/24",
          "@order": [
            "1",
            "4323998795727ae1ab8750"
          ]
        },
        "name": "default",
        "vlantag": 0
      }
    },
    "name": "eth0",
    "speed": "auto"
  },
  "key": "nic1",
  "meta": {
    "first": "/api/configuration/network/nics/nic1",
    "href": "/api/configuration/network/nics/nic1",
    "last": "/api/configuration/network/nics/nic3",
    "next": "/api/configuration/network/nics/nic2",
    "parent": "/api/configuration/network/nics",
    "previous": null,
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the physical network interface (nic1, nic2 or nic3).
body   Top level element (string) Contains the properties of the physical network interface.
  interfaces Top level item Contains the configuration of all virtual interfaces on the physical NIC.
  name string The system name of the physical network interface (eth0, eth1 or eth2). Do not change this value.
  speed string

The speed of the physical network interface. The default value is auto. Change this setting only for troubleshooting purposes. Possible values are:

  • auto

    Negotiate the network speed automatically. This is the default value.

  • 10-half

    10BaseT/Half.

  • 100-half

    100BaseT/Half.

  • 10-full

    10BaseT/Full.

  • 100-full

    100BaseT/Full.

  • 1000-full

    1000BaseT/Full.

Elements of interfaces Type Description
@order     list

Lists the keys of the interfaces in the order they are be displayed on the SCB web UI.

<key-of-an-interface>     string

Contains the addresses, name, and vlantag of the network interface.

Each physical NIC has an automatically created interface key, where the value of the vlanid element is set to 0.

To add a valid virtual network interface to the physical NIC, create an additional interface, and assign a value between 1 and 4094 to its vlanid element.

  addresses   string Contains the addresses of the interface, and their display order.
    <key-of-address> string Contains the IP address range.
    @order list Lists the keys of the addresses in the order they are be displayed on the SCB web UI.
  name   string The name of the interface, as displayed on the SCB web UI.
  vlantag   string

The ID of the interface.

For the physical interface, the value is 0. For virtual interfaces, the value is between 1 and 4094.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.67. Routing table

Contains the address of the gateway server for each configured subnet.

URL

GET https://<IP-address-of-SCB>/api/configuration/network/routing

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the configured subnets and the corresponding gateway servers.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/network/routing

Response

The following is a sample response received when viewing the routing table. For details of the meta object, see Section 1.1, Message format.

{
  "body": [
    {
      "gateway": "192.168.56.1",
      "target_network": "0.0.0.0/0"
    }
  ],
  "key": "routing",
  "meta": {
    "first": "/api/configuration/network/dns",
    "href": "/api/configuration/network/routing",
    "last": "/api/configuration/network/routing",
    "next": null,
    "parent": "/api/configuration/network",
    "previous": "/api/configuration/network/nics",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key   string Top level element, contains the ID of the endpoint.
body   Top level element (list) Contains the routing table.
  gateway string The IP address of the gateway server.
  target_network string The network id (IP address and subnet mask) of the subnet.

Add a subnet

To add a subnet, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Create the JSON object for the new routing table.

    You can find a detailed description of the available parameters listed in Routing table.

POST the JSON object to the https://<IP-address-of-SCB>/api/configuration/network/routing endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Modify the routing table

To modify the routing table, you have to:

  • Have an open transaction. You can open a new transaction by performing a POST request on https://<IP-address-of-SCB>/api/transaction.

  • Modify the JSON object of the routing table.

    You can find a detailed description of the available parameters listed in Routing table.

PUT the modified JSON object to the https://<IP-address-of-SCB>/api/configuration/netowrk/routing endpoint.

To close the transaction, perform a PUT action on https://<IP-address-of-SCB>/api/transaction.

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Section 10, Application level error codes.

Code Description Notes
200 OK Updating the resource was successful
401 AuthenticationFailure Unknown username, invalid password, or some other error occurred.
404 NotFound The requested object does not exist.

13.68. Local services of SCB

Contains the endpoints for configuring the local services of SCB.

URL

GET https://<IP-address-of-SCB>/api/configuration/local_services

Headers

Header name Description Required Values
session_id Contains the authentication token of the user Required The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Section 4, Authenticate to the SCB REST API.

Sample request

The following command lists the local services.

curl --cookie session_id=<session_cookie> https://<IP-address-of-SCB>/api/configuration/local_services

Response

The following is a sample response received when listing local services. For details of the meta object, see Section 1.1, Message format.

{
    "items": [
        {
            "key": "admin_web",
            "meta": {
                "href": "/api/configuration/local_services/admin_web"
            }
        },
        {
            "key": "indexer",
            "meta": {
                "href": "/api/configuration/local_services/indexer"
            }
        },
        {
            "key": "postgresql",
            "meta": {
                "href": "/api/configuration/local_services/postgresql"
            }
        },
        {
            "key": "snmp_agent",
            "meta": {
                "href": "/api/configuration/local_services/snmp_agent"
            }
        },
        {
            "key": "ssh",
            "meta": {
                "href": "/api/configuration/local_services/ssh"
            }
        },
        {
            "key": "user_web",
            "meta": {
                "href": "/api/configuration/local_services/user_web"
            }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa",
        "href": "/api/configuration/local_services",
        "last": "/api/configuration/x509",
        "next": "/api/configuration/management",
        "parent": "/api/configuration",
        "previous": "/api/configuration/ica",
        "transaction": "/api/transaction"
    }
}
Element Description