Getting Started

Introduction

For your convenience, Kleio comes with both a Dockerfile and a Docker compose, which you can find here. Moreover, you can directly download the Docker image either from the GitHub image registry (ghcr.io/aegis-forge/kleio:1.0.0), or from Docker Hub (aegisforge/kleio:1.0.0).

Requirements

To run, Kleio needs both MongoDB and Neo4j instances to be up and running. If you are using the Docker compose file (we recommend it), then everything will already be defined and connected. For the databases, the following is needed:

Neo4j - v5.26.9 (neo4j:5.26.9)
MongoDB - v7.0 (mongodb/mongodb-community-server:7.0-ubi8)

Installation

Create a GitHub Personal Access Token (Optional)

By going here, you can create your Personal Access Token (PAT). If you only want Kleio to access public repos, then a default token is sufficient. However, if you also want Kleio to access private repos, then you will need to select either All repositories, or Only selected repositories.

Set Environment Variables

Make sure to duplicate the .env.template file present in the root of the repository. Then, rename it to .env. Finally, set the variables.

Both the GITHUB_PATH and GITHUB_PATH_VULN environment variables are not needed if dealing with a few public repositories. However, it is recommended to set them if you have many repositories to analyze.

If not set, GITHUB_PATH_VULN will use the same GitHub Personal Access Token as GITHUB_PATH.

Specify Custom Repositories (Optional)

By default, Kleio will clone and analyze the env.SIZE * env.PAGES most starred repositories on GitHub. If you want Kleio to analyze a custom list of repositories, create a repositories.txt file. The file should be a list of GitHub URL, one line per URL, for example:

repositories.txt

https://github.com/aegis-forge/soteria
https://github.com/aegis-forge/cage
https://github.com/aegis-forge/kleio

The newline after the last URL is required, otherwise the last URL will be skipped.

Run Docker Compose

If you want to pass custom repositories to Kleio, then you will need to uncomment these lines in the compose.yaml file:

compose.yaml

services:
crawler:
    image: aegisforge/kleio:latest
        env_file: ".env"
        # Uncomment to use a custom list of repositories
        volumes:
        - ./repositories.txt:/kleio/repositories.txt
        networks:
        - crawler

Now that everything is set up, you can use the compose.yaml file to spin the Kleio, Neo4j, and MongoDB instances. To do so, run the following command:

docker compose up -d