Using the Balabit Shell Control Box REST API

Copyright © 2017 Balabit SA. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balabit.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (https://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

This product uses Botan cryptographic library. The library was released under the BSD-2 license. For details about the Botan license, see Botan cryptographic library license.

The Balabit™ name and the Balabit™ logo are registered trademarks of Balabit SA.

The Balabit Shell Control Box™ name and the Balabit Shell Control Box™ logo are registered trademarks of Balabit.

Citrix®, ICA® and XenApp™ are trademarks or registered trademarks of Citrix Systems, Inc.

Linux™ is a registered trademark of Linus Torvalds.

Sun™, Sun Microsystems™, the Sun logo, Sun Fire 4140™, Sun Fire 2100™, Sun Fire 2200™, Sun Fire 4540™, and Sun StorageTek™ are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries in the U.S. and other countries.

The syslog-ng™ name and the syslog-ng™ logo are registered trademarks of Balabit.

VMware™, VMware ESX™ and VMware View™ are trademarks or registered trademarks of VMware, Inc. and/or its affiliates.

Windows™ 95, 98, ME, 2000, XP, Server 2003, Vista, Server 2008, 7, 8, and Server 2012 are registered trademarks of Microsoft Corporation.

The Zorp™ name and the Zorp™ logo are registered trademarks of BalaSys IT Ltd.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER. Balabit is not responsible for any third-party websites mentioned in this document. Balabit does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balabit will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

Botan cryptographic library license. 

Botan http://botan.randombit.net/ is distributed under these terms:

Copyright ©

  • 1999-2013,2014 Jack Lloyd

  • 2001 Peter J Jones

  • 2004-2007 Justin Karneges

  • 2004 Vaclav Ovsik

  • 2005 Matthew Gregan

  • 2005-2006 Matt Johnston

  • 2006 Luca Piccarreta

  • 2007 Yves Jerschow

  • 2007-2008 FlexSecure GmbH

  • 2007-2008 Technische Universitat Darmstadt

  • 2007-2008 Falko Strenzke

  • 2007-2008 Martin Doering

  • 2007 Manuel Hartl

  • 2007 Christoph Ludwig

  • 2007 Patrick Sona

  • 2010 Olivier de Gaalon

  • 2012 Vojtech Kral

  • 2012-2014 Markus Wanner

  • 2013 Joel Low

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

August 31, 2017


Table of Contents

1. Introduction
1.1. Message format
1.2. How to configure SCB using REST
1.3. How to configure SCB using REST — a sample transaction
2. Using the SCB REST API
2.1. Authenticate to the SCB REST API
2.2. Authenticate to the SCB REST API using X.509 certificate
2.3. Retrieve user information
2.4. Checking the transaction status
2.5. Open a transaction
2.6. Commit a transaction
2.7. Delete a transaction
2.8. Reviewing the changelog of a transaction
2.9. Application level error codes
2.10. Navigating the configuration of SCB
2.11. Modifying the configuration of SCB
2.11.1. Delete an object
2.11.2. Create a new object
2.11.3. Change an object
3. Basic settings
3.1. Retrieve basic firmware and host information
3.2. Network settings
3.2.1. Web interface
3.2.2. Network configuration options
3.2.3. DNS servers
3.2.4. Routing between interfaces
3.2.5. Naming options
3.2.6. Network addresses
3.2.7. Routing table
3.2.8. Local services of SCB
3.2.9. Local services — Web login for administrators
3.2.10. Local services — Web login for users
3.3. Date and time
3.3.1. Date & time
3.3.2. NTP servers
3.3.3. Timezone
3.4. Logs, monitoring and alerts
3.4.1. Management options
3.4.2. Syslog server settings
3.4.3. Disk fill-up prevention
3.4.4. Mail settings
3.4.5. Health monitoring
3.4.6. SNMP settings
3.4.7. SNMP traps
3.4.8. Local services — access for SNMP agents
3.4.9. Alerting
3.4.10. System alerts
3.4.11. Traffic alerts
4. User management and access control
4.1. User management and access control
4.2. Authentication and user database settings
4.3. Privileges of usergroups
4.4. Manage users and usergroups locally on SCB
4.5. Manage usergroups locally on SCB
4.6. Manage users locally on SCB
5. Managing SCB
5.1. Troubleshooting options
5.2. Internal certificates
5.3. Passwords stored on SCB
5.4. Private keys stored on SCB
5.5. Certificates stored on SCB
5.6. Local services — enabling SSH access to the SCB host
5.7. RPC API
6. General connection settings
6.1. Channel policy
6.2. Policies
6.3. Audit policies
6.4. Real-time content monitoring with Content Policies
6.5. LDAP servers
6.6. Signing CA policies
6.7. Time policy
6.8. Trusted Certificate Authorities
6.9. Local user databases
6.10. User lists
7. HTTP connections
7.1. HTTP connections
7.2. Global HTTP options
7.3. HTTP settings policies
8. Citrix ICA connections
8.1. ICA connections
8.2. Global ICA options
8.3. ICA settings policies
9. RDP connections
9.1. RDP connections
9.2. RDP channels
9.3. Configuring domain membership
9.4. Global RDP options
9.5. RDP settings policies
10. SSH connections
10.1. SSH connections
10.2. SSH connection policies
10.3. SSH channels
10.4. SSH authentication policies
10.5. Global SSH options
10.6. SSH settings policies
10.7. SSH host keys and certificates
11. Telnet connections
11.1. Telnet connections
11.2. Global Telnet options
12. VNC connections
12.1. VNC connections
12.2. Global VNC options
13. Searching and indexing sessions
13.1. Audited sessions
13.2. Searching in the session database
13.3. Session alerts
13.4. Session events
13.5. Local services — configuring the indexer
13.6. Indexer policies
14. Reporting
14.1. Reporting
14.2. Reports
14.3. Built-in subchapters
14.4. Pre-defined reports
14.5. Content subchapters
14.6. Custom subchapters
14.7. Connection statistics subchapters
15. Advanced authentication and authorization
15.1. Usermapping policy
15.2. Plugins
15.3. Authentication and authorization plugins
15.4. Credential store plugins
15.5. Credential stores
15.6. Ticketing policies
15.7. Ticketing plugins
List of SCB REST API parameters and elements