Adaptive Honeypot System

Master's degree final project - Adaptive Honeypot System

Architecture

The honeypot system consists of 4 main components:

• an agent which will be deployed on the target machine
• an API which will handle all the data processing and database interaction
• a dashboard which will display the data in a human friendly manner
• an Apache Cassandra cluster which will store all the data provided by the agents.
• an ElasticSearch cluster which will store the logs from the agents for easier indexing.

Dependencies

The honeypot system is built using Golang and NextJS

Installing NextJS:

#Install nodejs
curl -fsSL https://deb.nodesource.com/setup_21.x | sudo -E bash - && sudo apt-get install -y nodejs

#Check the node 21 was installed
node -v

#Check that npm was installed
npm -v

Installing modules for dashboard

cd ./dashboard/
npm install

Checking if the dashboard has all dependencies installed

#Start the dashboard in development mode
npm run dev

Configure database

In order for the API to run, a Apache Cassandra cluster is needed. The easiest way is to start a single node cluster is to run docker-compose in the root of the repository.

docker-compose up -d

The docker-compose command will create the Cassandra container and the necessary keyspace for the API. It will also create 2 volumes, one for initializing the Cassandra keyspace and one which will assure persistence of the Cassandra database.

If the init-cassandra service fails to start, you should check the permissions of the scripts/cassandra/init.sh script (it should be executable - chmod +x scripts/cassandra/init.sh)

Configuring Agent and API

Both the agent and the API have a configuration file inside their directory (agent.conf and api.conf). The format of the data in the configuration file is JSON.

1. API configuration

The API needs the following fields in the configuration file in order to start:

• address - This is the IP address the API will listen on
• port - The port to listen on
• cassandraNodes - The nodes of the Apache Cassandra cluster (list of strings)
• cassandraKeyspace - The keyspace of the Cassandra cluster
• exploitTemplatePath - The path to the exploit generation template.

Example configuration:

{
    "address": "0.0.0.0",
    "port":"8081",
    "cassandraNodes": ["127.0.0.1"],
    "cassandraKeyspace": "api",
    "exploitTemplatePath": "templates/exploit.tmpl"
}

2. Agent configuration

The Agent needs the following fields in the configuration file in order to run:

• protocol - The protocol to listen on (http or https)
• address - The IP address the agent will listen on
• port - The port the agent will listen on
• forbiddenPagePath - Path to the forbidden page
• blacklistUserAgentPath - Path to the list of blacklisted user agents
• forwardServerProtocol - The protocol of the forward server (protected server)
• forwardServerAddress - The address of the forward server
• forwardServerPort - The port of the forward server
• apiProtocol - The protocol of the API
• apiIpAddress - The IP address of the API
• apiPort - The port of the API
• uuid - This will be completed at first run (pulled from API) - leave empty
• rulesDirectory - The rules directory
• operationMode - The mode of operation of the agent

Example Agent configuration:

{
    "protocol": "http",
    "address": "0.0.0.0",
    "port": "8080",
    "forbiddenPagePath": "./static/forbidden.html",
    "blacklistUserAgentPath": "./lists/user_agent.list",
    "forwardServerProtocol": "http",
    "forwardServerAddress": "127.0.0.1",
    "forwardServerPort": "8000",
    "apiProtocol": "http",
    "apiIpAddress": "127.0.0.1",
    "apiPort": "8081",
    "uuid": "237870e8-f2f5-49dd-b63c-8d67c4003513",
    "rulesDirectory": "./rules",
    "operationMode": "testing"
}

Starting IDE

You can start the Visual Studio Code IDE using one of the scripts start_ide.ps1 or start_ide.sh depending on the operating system you have installed on your machine (.ps1 for Windows, .sh for Linux)

How to setup elasticsearch with volume

In order to setup the volume for the elasticsearch cluster you need to change the permission of the folder to be owned by the user with uid 1000.

sudo chown 1000:1000 ./data/elastic

How to deploy the agent as a systemd service

To add the agent as a systemd service you have to create a file in /etc/systemd/system folder (ex: /etc/systemd/system/agent.service).

Add the following options in the file

[Unit]
Description=Disertatie Agent
ConditionPathExists=<PATH_TO_AGENT_CODE>
After=network.target
[Service]
Type=simple
User=<USER>
Group=<GROUP>
WorkingDirectory=<PATH_TO_AGENT_CODE>
ExecStart=/usr/local/go/bin/go run main.go -config ./agent.conf
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=agent
[Install]
WantedBy=multi-user.target