| Installer |
Included components |
Description |
| Kam1n0-Server.msi |
Core engine |
Main engine providing service for indexing and searching. |
| Workbench |
A user interface to manage the repositories and running service. |
| Web user interface |
Web user interface for searching/indexing binary files and assembly functions. |
| Visual C++ redistributable for VS 15 |
Dependecy for z3. |
| Kam1n0-IDA-Plugin.msi |
Plug-in |
Connectors and user interface. |
| PyPI wheels for Cefpython |
Rendering engine for the user interface. |
| PyPI and dependent wheels |
Package management for Python. Included for IDA 6.8 &6.9. |
## Installing the Kam1n0 Server
The Kam1n0 core engine is purely written in Java. You need the following dependencies:
* [Required] The latest x64 8.x JRE/JDK distribution from [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/index.html).
* Java9 and Java10 are not supported at this moment.
* [Optional] The latest version of IDA Pro with the [idapython](https://github.com/idapython/src/) plug-in installed. The Python plug-in and runtime should have already been installed with IDA Pro. Reinstall IDA Pro if necessary.
Download the ```Kam1n0-Server.msi``` file from our [release page](https://github.com/McGill-DMaS/Kam1n0-Plugin-IDA-Pro/releases). Follow the instructions to install the server. You will be prompted to select an installation path. IDA Pro is optional if the server does not have to deal with any disassembling. In other words, the client side uses the Kam1n0 plugin for IDA Pro. It is strongly suggested to have the IDA Pro installed with the Kam1n0 server. Kam1n0 server will automatically detect your IDA Pro by looking for the default application that you used to open `.i64` file.
## Installing the IDA Pro Plug-in
The Kam1n0 IDA Pro plug-in is written in Python for the logic and in HTML/JavaScript for the rendering. The following dependencies are required for its installation:
* [Required] IDA Pro (>6.7) with the [idapython](https://github.com/idapython/src/) plug-in installed. The Python plug-in and runtime should have already been installed with IDA Pro. Reinstall IDA Pro if necessary.
Next, download the ```Kam1n0-IDA-Plugin.msi``` installer from our [release page](https://github.com/McGill-DMaS/Kam1n0-Plugin-IDA-Pro/releases). Follow the instructions to install the plug-in and runtime. Please note that the plug-in has to be installed in the IDA Pro plugins folder which is located at ```$IDA_PRO_PATH$/plugins```. For example, on Windows, the path could be ```C:/Program Files (x86)/IDA 6.95/plugins```. The installer will detect and validate the path.
## Setting Up Kam1n0 on Ubuntu/Debian-based systems
* Ensure you have the **Oracle** version of Java 8. (Not default-jdk in apt, and not Java 8 or 9.)
* Add Oracle's PPA and then update your package repository: `sudo add-apt-repository ppa:webupd8team/java`
* If you encounter any errors (such as `~webupd8team not found`), if you are on a proxy, make sure you set and export your `http_proxy` and `https_proxy` environment variables, and then try again with the `-E` option on sudo. Additionally, if you are getting a 'add-apt repository command not found error, try: `sudo apt install -y software-properties-common`.
* Afterwards: `sudo apt-get update`, and `sudo apt-get install oracle-java8-installer`
* Verify your Java version with `java -version`; you may need to manually set the JAVA_HOME environment variable (in `/etc/environment`), `JAVA_HOME=/usr/lib/jvm/java-8-oracle`
* Download the latest release for Linux (Kam1n0-IDA-Plugin.tar.gz and Kam1n0-Server.tar.gz) from [Kam1n0-Community](https://github.com/McGill-DMaS/Kam1n0-Community/releases).
* Extract the two tarballs (i.e. tar –xvzf Kam1n0-IDA-Plugin.tar.gz and tar –xvzf Kam1n0-Server.tar.gz)
* The Kam1n0-Server.tar.gz file will create the server directory.
* Inside the `server` directory, you should see a file called `kam1n0.properties`, which is where you will set various configurations for kam1n0; this is very important.
* Set `kam1n0.data.path` to where you would like your kam1n0-related data to be written to. We choose to put it in the same place that we keep our `server`. `kam1n0.ida.home` refers to where your IDA installation is located. Comment this line (and `kam1n0.ida.batch`, the line following) if you do not have IDA and don't plan to use kam1n0 for disassembly. For more (accurate) information about the `kam1n0.properties` file, see the `kam1n0.properties.explained` file.
* Run kam1n0-server-workbench: `java -jar kam1n0-server-workbench.jar`. This *should* cause a window to pop up, which prompts you to actually start kam1n0. Alternatively, run kam1n0-server: `java -jar kam1n0-server.jar --start`. This starts the server from the console without a window.
* To connect and use it, go to `127.0.0.1:8571` (the default port kam1n0 listens on should be 8571, but can be changed in kam1n0.properties) in your browser. You should see the pretty kam1n0 web UI. From there, follow the [tutorial](https://github.com/McGill-DMaS/Kam1n0-Community/blob/master2.x/documentation/server/server.md) on the Kam1n0-Community repo if you do not know how to use kam1n0.
## Backward Compatibility
The assembly code repositories and configuration files used in previous versions (<2.0.0) are no longer supported by the latest version. Please contact us if you need to migrate your old repositories.
# Documentation
* [Kam1n0 Server Tutorial](documentation/server/server.md#tutorial)
* [Configuration and Engine Startup](documentation/server/server.md#edit-and-start-engine)
* [Register an account and login](documentation/server/server.md#register-an-account-and-login)
* [Create an application](documentation/server/server.md#create-an-app)
* [Application Sharing and Access Control](documentation/server/server.md#share-an-app)
* [Preparing the data](documentation/server/server.md#preparing-the-data)
* [The application URL for IDA Pro Plugin](documentation/server/server.md#get-the-url-for-ida-pro-plugin)
* [Index binary files](documentation/server/server.md#index-binary-files)
* [Search with an assembly function](documentation/server/server.md#search-with-an-assembly-function)
* [Flow graph view](documentation/server/server.md#flow-graph-view)
* [Text diff view](documentation/server/server.md#text-diff-view)
* [Clone group view](documentation/server/server.md#clone-group-view)
* [Search with a binary file](documentation/server/server.md#search-with-a-binary-file)
* [Browse a clone search result](documentation/server/server.md#browse-a-clone-search-result)
* [The summary boxes](documentation/server/server.md#the-summary-boxes)
* [Details](documentation/server/server.md#details)
* [IDA Pro Plug-in Tutorial](documentation/ida-pro-plugin/ida-pro-plugin.md#tutorial)
* [Functionalities](documentation/ida-pro-plugin/ida-pro-plugin.md#functionalities)
* [Walk through example](documentation/ida-pro-plugin/ida-pro-plugin.md#walk-through-example)
* [Preparing the data](documentation/ida-pro-plugin/ida-pro-plugin.md#preparing-the-data)
* [Engine startup and application URL](documentation/ida-pro-plugin/ida-pro-plugin.md#start-the-engine-and-get-the-url-for-ida-pro-plugin)
* [Connection configuration](documentation/ida-pro-plugin/ida-pro-plugin.md#set-up-connection)
* [Indexing from plug-in](documentation/ida-pro-plugin/ida-pro-plugin.md#indexing)
* [Functions search](documentation/ida-pro-plugin/ida-pro-plugin.md#functions-search)
* [Composition analysis](documentation/ida-pro-plugin/ida-pro-plugin.md#composition-analysis)
* [Assembly fragment search](documentation/ida-pro-plugin/ida-pro-plugin.md#assembly-fragment-search)
* [Search box](documentation/ida-pro-plugin/ida-pro-plugin.md#search-box)
* [How does the Plugin Work](documentation/ida-pro-plugin/ida-pro-plugin.md#how-does-the-plug-in-work)
* [User Interface](documentation/ida-pro-plugin/ida-pro-plugin.md#user-interface)
* [Synchronization](documentation/ida-pro-plugin/ida-pro-plugin.md#synchronization)
* [Two-way Communication](documentation/ida-pro-plugin/ida-pro-plugin.md#communication)
# Development
Clone the latest stable branch (don't forget `--recursive`!):
```bash
git clone --recursive -b master2.x --single-branch https://github.com/McGill-DMaS/Kam1n0-Community
```
## Importing the project.
IntelliJ: Import the root /kam1n0/kam1n0/ as a maven project. All the submodules will be loaded accordingly.
EclipseEE: Add the cloned git repository to the git view. Import all maven projects from the git repository.
You may need to modify the classpath to address any error.
All the resources path are dynamically modified when running inside an IDE
(through the kam1n0-resources submodule).
To build the project:
```
cd /kam1n0/kam1n0
mvn -DskipTests clean package
mvn -DskipTests package
```
The resulting binaries can be found in /kam1n0/build-bins/
To run the test code, you will need to first download `chromedriver.exe` from http://chromedriver.chromium.org/ and add its *absolute* path into an environment variable named `webdriver.chrome.driver`. It is also required that there is a chrome browser installed in the system. The test code will launch a browser instance to test the UI interfaces. The complete testing procedure will take approximately 3 hours.
```
cd /kam1n0/kam1n0
mvn -DskipTests clean package # you can skip this one if you already built the package
mvn -DskipTests package # you can skip this one if you already built the package
mvn -DforkMode=never test
```
These commands only compiles java with pre-compiled wheels of libvex and z3. It works out-of-the-box.
The build of libvex and z3 is platform-dependent. We use a fork of libvex from Angr.
More serious build scripts as well as installers for windows/linux can be found under /kam1n0-builds/
* kam1n0: The server's source code.
* kam1n0-builds: Installer source code and scripts to build the distribution.
* kam1n0-clients: The clients' source code.
## Binary Releases
We have a Jenkin server for contineous development and delivery. Latest stable release will be posted here. Periodically we will synchronize our internal experimental branch with this repository.
## Licensing
The software was developed by [Steven H. H. Ding](http://stevending.net/), [Miles Q. Li](http://milesqli.github.io/), and [Benjamin C. M. Fung](http://dmas.lab.mcgill.ca/fung/) in the [McGill Data Mining and Security Lab](http://dmas.lab.mcgill.ca/) and [Queen's L1NNA Research Laboratory](https://l1nna.com/) in Canada. It is distributed under the Apache License Version 2.0. Please refer to [LICENSE.txt](LICENSE.txt) for details.
Copyright 2014-2021 McGill University and the Researchers. All rights reserved.
## Acknowledgement
-orange.svg?style=for-the-badge)
What Is Kam1n0 v2? 
