appgate-extensions

Disclaimer

© 2019, Cyxtera Cybersecurity, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: (a) redistributions of source code must retain the above copyright notice, this list of conditions and the disclaimer below, and (b) redistributions in binary form must reproduce the above copyright notice, this list of conditions and the disclaimer below in the documentation and/or other materials provided with the distribution. THE CODE AND SCRIPTS POSTED ON THIS WEBSITE ARE PROVIDED ON AN “AS IS” BASIS AND YOUR USE OF SUCH CODE AND/OR SCRIPTS IS AT YOUR OWN RISK. CYXTERA DISCLAIMS ALL EXPRESS AND IMPLIED WARRANTIES, EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING, BUT NOT LIMITED TO, ALL WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, ACCURACY, COMPLETENESS, COMPATABILITY OF SOFTWARE OR EQUIPMENT OR ANY RESULTS TO BE ACHIEVED THEREFROM. CYXTERA DOES NOT WARRANT THAT SUCH CODE AND/OR SCRIPTS ARE OR WILL BE ERROR-FREE. IN NO EVENT SHALL CYXTERA BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, RELIANCE, EXEMPLARY, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR ANY LOSS OF GOODWILL,LOSS OF ANTICIPATED SAVINGS, COST OF PURCHASING REPLACEMENT SERVICES, LOSS OF PROFITS, REVENUE, DATA OR DATA USE, ARISING IN ANY WAY OUT OF THE USE AND/OR REDISTRIBUTION OF SUCH CODE AND/OR SCRIPTS, REGARDLESS OF THE LEGAL THEORY UNDER WHICH SUCH LIABILITY IS ASSERTED AND REGARDLESS OF WHETHER CYXTERA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LIABILITY.

AppGate extensions

Current repositories with example code

Concepts

Conceptually we divide the different integration points in AppGate in three categories:

  1. System Architects and business process system owners can model the user access provisioning process into an automated secure business process.
  2. Security officers and admins can rollout and enforce policy compliancy by modelling the policy rules.
  3. SOC and configuration-management can integrate with their company strategies and system to support compliant operations and react automatically on alerts and changes.

To meet these three conceptual challenges in IT secure access provisioning we added the integration points in AppGate SDP. You will find the integrations point in first an architectural overview and then with real world examples.

Architecture

extension architecture

AppGate SDP

The AppGate system builds on the core system (AppGate SDP)which is the standard off the shelf product. The core system does convey all the features for a full SDP solution. The layer right above the core system,the middle layer, are higher level components but essentially belongs to the core system as well. The middle layer demonstrates the extension components exposed in the system, which are used for integrations or process workflows with other systems or sources.

JavaScript Sandbox

The Sandbox component is the in-system evaluation environment and sealed from the outside of the AppGate system. The sandbox evaluates JavaScript code. Entitlement scripts and criteria scripts can be either of the latter’s. Note that the Java Script code however can be written to make use of external information through https requests etc.

Name resolvers

Name resolvers evaluate an expression as defined to the syntax accordingly to the type of VM fabric, or simple as to the DNS hostname. Name resolvers can be seen as higher level name resolvers to IP address, such as tags in a cloud environment.

AppGate API

The AppGate API ties in the core of the system. All the real configuration and operations is executed through the API. For example, the AppGate web-based admin user interface is using the API to read and write all the information and changes the administrators sees and makes.

AppGate Client

The AppGate Client allows the execution of a program or script on the host device. The execution is done in a shell of the operating system and is normally used to collect information from the host device aka un-trusted claims. These device claims will be used for contextual decision making throughout the life-cycle of a user session.

Responsibilities

The colouring of the layered architecture model designates the level of responsibility:

Green (standard): Overall Core System

All the components involved in the configuration are standard and do not expose an operational risk if it is configured without more than standard settings.

Yellow (Advanced): Extension might produce system impact or use issues

The components are advanced features and need to be properly designed, engineered and maintained through the system reliability team. The risk might be system performance degradation or end-user issues.

Red (Advanced): Extension is critical for the overall uptime of the system

The components are system administration components and rely under the ownership of the system owner (accountability). The DevOps team and system reliability team are responsible for the proper usage and maintenance of the implemented extensions.

Technical Background

The extensions can be separated into three areas where they are implemented or active:

extension model

The diagram depicts where what feature (extension) is located. The internal anatomy of the extensions are depicted in the diagram below.

extension anatomy

The client side extension

The client side extension allows the AppGate System to collect information from the client device itself, called device claims. It is normally achieved through an executable script or program run by the client on the operating system of the client-device. The feature to achieve this is called on demand device claims.

The information collected will be added to the set of claims for the user-session in the AppGate System, which can be utilized in decision making throughout the system.

An example of a use-case is for example a script which retrieves the system’s ID from the registry. The collected claims are typically consumed in decision making processes such as criteria for policy matching on the Controller or in criteria for conditions on the Gateways.

Considerations when designing client side extension

The on demand device claim is collected on the client. The client executes the specified resource which can be a script or binary (executable) on the operating system the client runs on.

1. Execution time-out

by default the client spawns a shell wherein the resource is executed. If the execution does not end after 5 seconds, the client will kill the process and continues. The reason for this is to keep a good user experience, and timing is important for this. The value of the time-out can be changed on the user’s machine, but should be taken into consideration for the user experience (countermeasures need to be evaluated).

2. Execution rights (OS)

Some operating system have restrictions controlled by the local or remote (domain) policy. In case of Windows please check with your domain administrator/security team what changes to do (policy change, signing etc.).

3. Endpoint protection and white listing

If an endpoint protection or white listing software is installed you might need to adjust the policies of those to guarantee execution of them. You can provide the script to the operations and security team to review the scripts and the checksum of it (as displayed in the AppGate console).

4. Privileges

The scripts or binaries are run with user-space privilege, meaning calls to resources which require higher privileges (such lie system or root users) are not supported.

5. Error handling

Error handling needs to be taken care of in the resource. A well defined return value of all cases (including edge cases) simplifies the troubleshooting throughout the AppGate installation.

Dynamic model

The following sequence diagram depicts a user session with the extensions. extension dynamic model

  1. Client authenticates user on Controller.
  2. Controller ships claims token to Client, device scripts are downloaded if needed.
  3. Any device scripts are now executed if existing.
  4. Any device claims tokens are send to Controller if generated by device script.
  5. Client asks Controller for authorization.
  6. Controller evaluates policies (policy assignment), runs scripts if defined.
  7. Controller ships entitlement tokens to client.
  8. Client finds from entitlement tokens Gateway adresses, and connects to these (one or many sites). Client sends all corresponding claims and entitlement tokens to its respective site.
  9. Gateway(s) intantiaite entitlements, runs entitlement scripts if any and resolves hostnames to IPs.

Whenever permitted traffic hits one of the firewall rules which has a condition attached, it will be evaluated everytime until the condition returns true. A defined remedy action might trigger user end-user feedback as long the condition returns false. This can included MFA input, input field, password request etc. Good to know is that a remedy is only triggered when the condition fails. Also, a condition might have a re-evaluation timer which executes every Zminutes. Condition are also evaluated whenever entitlement tokens are renewed (by it’s lifetime or forced via API call).

Default timers

Force token re-newal or session re-evaluation

Revoking token with API call /token-records/revoked/by-dn/{distinguished-name}

Token renewal will revoke all tokens for a session and force the client to create new tokens. The delayMinutes property will allow the client to gracefully re-new the token without the user loosing connection to the end-points. When this is set to “0”, the gateway will immediately revoke all access because the tokens are revoked and client needs to go through the token creation motion first before intantiating the new entitlements tokens (remember all tokens are bound to validity time period). With a delay of “n” minutes, new tokens have already been crated and the current tokens will be invalidated by now +n minutes. The user will be prompted basically immediately for authentication (if SAML), and once granted tokens are replaced. Default is 5 minutes.

Re-evaluate session with API call /token-records/reeval/by-dn/{distinguished-name}

Reevaluate does force the entitlement scripts and conditions to be re-evaluated. This is less expensive and more robust than toekn-revocation method if you need only to force a conditions or entitlement scripts to be re-runthan token renewal.

Use cases

Automatic and secure access provisioning process

If you are considering to control user access to assets where the asset is known not in advance or the asset can be retrieved from an other system or environment, you will most probably go for one of the following features:

Policy compliance

If you are considering to assure user access is compliant to your policies, you most probably go for one of the following features:

Operations and configuration management or process support

If you are considering how to integrate operational control with your SOC or configuration management, or integrate with a workflow which requires operational interactions with AppGate, then you most likely looking for the usage of: