Page tree
Skip to end of metadata
Go to start of metadata

Installation and Network configuration

 

Icon

Kiuwan provides a Local Analyzer that locally analyzes the source code, avoiding the need to upload it to the Kiuwan cloud service, so code does not travel out of the "organization perimeter".

Only analysis results are transferred and processed in Kiuwan cloud service.

 

In order to do that, Kiuwan provides a downloadable agent (Kiuwan Local AnalyzerKLA) that performs code analyses locally.

Kiuwan Local Analyzer:

  1. Downloads the model associated with target software,
  2. Launches a sequence of analysis steps —compliance with security and quality rules, code metrics, duplicated code detection, etc—, and
  3. Sends analysis results to Kiuwan cloud service.

 

Automatic Upgrade:

Before running any new analysis, KLA verify its installed version and, in the case there were a newer version, KLA update itself, downloading and installing it, notifying to the user (visit Local Analyzer Upgrade ).

 

Installation Requirements

System permissions

Icon

Kiuwan Local Analyzer is distributed as a downloadable compressed ZIP file.


Therefore, before to download it, please check you have permissions on your computer to download the zip file, uncompress and execute it.

Kiuwan Account

Icon

Kiuwan Local Analyzer distribution is downloaded from your Kiuwan account website.

So please be sure you have a valid account when login at https://www.kiuwan.com/saas/web/login.html

 

Download Kiuwan Local Analyzer 

Once logged-in, you can download KLA by opening top-right menu and selecting Download Kiuwan Local Analyzer


 

Internet Connectivity

Icon

Internet connectivity is required during execution of KLA (for authentication, automatic upgrades, quality model download, and results upload).

If you need to execute KLA without Internet connectivity, you should execute KLA in deferred mode. Please visit Offline analyses: the deferred mode for further information


To properly work, Kiuwan Local Analyzer needs to access following URLs:

Additionally, next URLs should also be accessible to contact Kiuwan support if you are using Kiuwan website:

Operating Systems and Java

Icon

Operating systems supported by the local analyzer are Windows, Linux, MacOS and any UNIX system and any OS that supports Java.

Java 8 (64 bits) or above —either JDK or JRE— is required.


Setting JAVA_HOME

Depending on your platform, you have to make sure the JAVA_HOME environment variable points to the directory where the version was installed (in some platforms the installer takes care of this for you), and that you have $JAVA_HOME/bin in your PATH. 

Windows Configuration of JAVA_HOME

Once you have Java installed, you should set JAVA_HOME variable by accessing to 'System properties' in Control Panel, then clicking on 'Advanced' tab and on 'Environment variables', as shown in the image below:

 

Then, in 'System variables', you have to click on 'New' and name it 'JAVA_HOME', as well as indicate the path where the software is located:

 

Memory and Time Requirements

Icon

When KLA executes a local analysis, it starts a JVM for every analysis step.

By default:

  • JVM is configured to take a maximum of 1GB per concurrent analysis
  • Max time (timeout) for every analysis step is configured to 60 minutes.

 

These default values are usually valid for most of the analyses. 

For analyses that contain more than 5,000 sources files and/or more than 1.5 Million lines of code , it's recommended to increase those values.

You can configure Kiuwan to increases those limits for the whole installation or per application.

If you increase the max memory, please be sure your local machine has enough available resources, otherwise JVM would not start and analysis will not proceed.

 

Installation and Authentication

Icon

Kiuwan Local Analyzer is distributed as a downloadable compressed ZIP file accessible at Kiuwan WebSite.

After downloaded, to install just unzip it within a local directory of your machine and, by default, it will create a KiuwanLocalAnalyzer directory (hereinafter, AGENT_HOME) with all the needed KLA resources.

KLA does not install anything at any other location than AGENT_HOME, so to uninstall just delete AGENT_HOME directory, and then there will not be anymore any KLA-related software at your machine.

 

Info for UNIX-like installations

Under Unix-like systems, please check:

  • You need to change permissions for shell scripts.
    • Use a command like "chmod +x *.sh" for executable permissions.
  • Please check permissions of the Unix user running Kiuwan Local Analyzer:  
    • read/write permissions on AGENT_HOME/*
    • read permissions on directory of source code to be analyzed by Kiuwan

 

Icon

IMPORTANT: Please check /dev/random configuration of JVM. This may produce severe performance problems.

Visit Analyses are very slow in Unix Linux, or halt when uploading results to Kiuwan and Java urandom Entropy for help on how to solve it.

 

Setting your credentials

Kiuwan Local Analyzer authenticates against a valid Kiuwan account using the credentials you provide.

 

Icon

If you use the local analyzer GUI ($AGENT_HOME/agent.cmd), it will ask for credentials (user and password).

If the credentials are valid, KLA will encrypt and save these credentials within agent properties file ($AGENT_HOME/conf/agent.properties) and will be used in subsequent executions.


Please remember that if you change the password for your username in Kiuwan application, you need to change it in the agent as well.

Icon

In case you need to change (and encrypt) the credentials, you can execute:

  • Unix:  $AGENT_HOME/bin/agent.sh –e (or --encrypt-password)
  • Windows:  $AGENT_HOME/bin/agent.cmd –e (or --encrypt-password)

 

Network configuration

You can configure how Kiuwan Local Analyzer connects to kiuwan services.

Icon

If your local network uses a Proxy, or if your organization has a Local Authentication system, you can configure them in the "Network configuration" dialog.

 

Open the "Network configuration" dialog clicking on the "Advanced" button in the bottom left corner of the login window:


 

Proxy configuration

Icon

If your network has a pass-through Proxy required for Internet access, you should configure the proxy settings in the first tab of the Network configuration dialog


Here you can set:

  • The protocol used by the proxy (http or socks).
  • The host of the proxy server (e.g. proxy.myorganization.com).
    • Leave this option empty if your connection to the Internet needs no proxy pass-through.
  • The port where the proxy server is listening to.
  • The authentication type for the proxy.
    • Only Basic authentication is supported.
    • Leave this option to "None" if no authorization is required.
  • The username for the proxy authentication.
  • The password for the proxy authentication.

 

Icon

From Java 8 Update 111 (8u111) onwards, the Basic authentication scheme has been deactivated, by default, in the Oracle Java Runtime.

If you are using Java 8 Update 111 (or later), proxies requiring Basic authentication when setting up a tunnel for HTTPS will no longer succeed by default.

Please visit Basic Authentication Error : Proxy returns HTTP1.1 407 Proxy Authentication Required for help on how to set up.

Icon

Alternatively, instead of using Kiuwan Local Analyzer GUI, you can manually configure the proxy settings in $(AGENT_HOME)/conf/agent.properties file

agent.properties

 

Local Authentication configuration

Icon

You can integrate Kiuwan Local Analyzer with a Local Authentication system.


This is a common scenario in organizations that validate their employees' credentials against their own authentication system, and do not want them to use other credentials when accessing to external services.

If your company uses a corporate authentication service, your users and passwords will most probably be stored in an Active Directory, an OpenLDAP or an IBM Tivoli.

If that is your case, it’s not needed to have different users/password for your Kiuwan account.

Icon

By integrating Kiuwan with your Auth service, you will make Kiuwan authentication to delegate on your own system.

 

 

If this is your case, you will need to configure the URL of your organization's local authentication system

You can also set the local authentication to use the currently configured proxy (as long as it uses http protocol).

Ask your systems administrator what value to enter in the "Local authentication URL" field.

Note that when a local authentication URL is configured, the username and password you set in the login window will be sent to the local authentication system instead to Kiuwan.

 

Icon

Alternatively, instead of using Kiuwan Local Analyzer GUI, you can manually configure Local Authentication settings in AGENT_HOME/conf/agent.properties file

agent.properties

 

How to configure Kiuwan to use your Local Authentication system

Your company users should not connect to https://www.kiuwan.com to sign in, but to an internal URL of your corporate network that you choose, like: http://kiuwan.yourdomain.com or http://yourdomain.com/kiuwan (for example).

In that address you will have an authentication service application that will rely on your local auth service.

If you have permissions to access Kiuwan, it will generate a JWT authentication token including the username, which is encrypted using a secret key, that you can generate in your Kiuwan account settings page.

This token is sent to Kiuwan, so it makes the validation and creates the session for the user, who is automatically redirected to https://www.kiuwan.com, to access the application.

 

 

A sample application

You can find a sample authentication application (kiuwan/kiuwan-local-authentication) as a way to get started.

This sample application uses Tomcat (tomcat-users.xml) as authentication mechanism.

The steps are simple:

  1. Install [Tomcat 8.5.11]  (or another application server or use one you already have in your company) on a server.
  2. Compile and deploy the sample authentication service application we provide for authenticating users in your application server.
  3. Configure the authentication service application in index.jsp page. (Remember, this is a sample application. Do not use it as production code)

 

 

The required clientId and secretKey fields are generated from Kiuwan. You need login in Kiuwan and go to Account Management >> Secret keys

You need also configure the security settings in the application server where you deployed our authentication service application, to connect to your LDAP or any other authentication server.

In this example, we use Tomcat (tomcat-users.xml):

tomcat-users.xml


Configure the web.xml file to use this authentication mechanism:

web.xml

 

You are done!

Now you just have to tell your Kiuwan users to use the URL you have defined to access our authentication service application.

Remember that this same configuration is also valid if you have Single-Sign-On mechanisms such as LDAP, SPNEGO or IBM WebSeal.

 

Local Analyzer Upgrade

For a correct interpretation of results, Local Analyzer version installed on the client workstations should be the latest available on the server.

Icon

Before running a new analysis, KLA checks the version is using and, in case there were a newer version, it updates itself, downloading and installing it, notifying to the user and writing these changes in log file.


Under some circumstances, automatic upgrade might be not executed, and you will see a warning message stating that upgrade of Kiuwan Local Analyzer has not been executed.

 

This message only means that the analysis was not executed with the last available KLA.

This does not mean necessarily an error. It could be only a temporary situation.

 

Before executing an analysis, Kiuwan Local Analyzer always checks if there's available a new version. If so, automatic upgrading process starts.

In some parallel high-load scenarios, there might be already running analysis. And those analysis executed before the new version is installed will show this warning message.

Icon

KLA will be automatically upgraded as soon as a new analysis is executed and there are no running analyses. Therefore, it's not a problem to see this warning message (it's only a temporary situation).

 

But, if you see those messages appearing during some hours, perhaps there's a problem in your installation that is currently blocking automatic upgrade.

In that case, when you are sure there are no running analyses, please delete any *.lock file that might be at temp directory of you KLA installation.

After that, run the analysis again. If the problem still persists, please contact Kiuwan Technical Support.