apt install -y libpcap-dev lxc-dev
cd /usr/local
wget https://storage.googleapis.com/golang/go1.8rc3.linux-amd64.tar.gz
tar vxf go1.8rc3.linux-amd64.tar.gz
mkdir /opt/honeytrap
cd /opt/honeytrap/
export GOPATH=/opt/honeytrap
export PATH=$PATH:/usr/local/go/bin/
go get github.com/honeytrap/honeytrap
cp config.toml.sample config.toml
$GOPATH/bin/honeytrap
# create container base image
$ lxc-create -t download -n honeytrap -- --dist ubuntu --release trusty --arch amd64
Honeytrap exposes a specific API which allows us to easily retrieve data about sessions and events which are occuring with the deployed instance. This API should allow anyone using the project to expose an interface to showcase the different occuring sessions running on the instance.
The HTTP API exposed by Honeytrap is a GET only API which focuses on providing access to
events and sessions, where the sessions hold's data about containers being used by who and with what credentials and events providing us a view of all processes which occured during the specific container usage and session periods.
GET /events
Expects to recieve a GET request to retrieve stored events, with the following body:
{
"response_per_page": 10,
"page":1,
"types": [1,5,20],
"sensors": ["ping", "^connect"]
}Note that all the request body fields are optional and if not present, will instead have all events returned, but if page is being used then response_per_page must be set as well.
The types and sensor field provides a means of filtering based on strings or regular expressions which will filter out the events according to the set criterias.
The API will responds with the following response body as regarding the above request:
{
"response_per_page": 10,
"page":1,
"total":100,
"events":[
{
"type": 1,
"sensor":"ping",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"connections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
{
"type": 1,
"sensor":"ping",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"connections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
}
]
}The total field represents the total events records stored within the db.
GET /sessions
Expects to recieve a GET request to retrieve stored session events, with the following body:
{
"response_per_page": 10,
"page":1,
"types": [1],
"sensors": ["^ssh_"]
}Note that all the request body fields are optional and if not present, will instead have all events returned, but if page is being used then response_per_page must be set as well.
The types and sensor field provides a means of filtering based on strings or regular expressions which will filter out the events according to the set criterias.
The API will responds with the following response body as regarding the above request:
{
"response_per_page": 10,
"page":1,
"total":100,
"events":[
{
"type": 1,
"sensor":"ssh_session",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"SSHConnections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
]
}The total field represents the total events records stored within the db.
The Honeytrap exposes also the ability to use websocket to connect with the API to retrieve events and sesssion data, whilst also receiving notifications as to the presence of new events or sessions.
-
GET /wsExposed by the API is a/wsroute which will attempt to upgrade any http request into a websocket connection which allows interfacing with the API to receive updates: -
Requests Requests to the API via the websocket endpoint expects requests in JSON format which follow the standard below, this requests are only retrieval and do not store/update any data to the API.
{
"type": INTEGER value of Request
}The API supports the following requests types with specific int values:
FETCH_SESSIONS = 1
FETCH_EVENTS = 3
- `FETCH_SESSIONS` returns all session related events which occur within the system.
- `FETCH_EVENTS` returns all non-session related events which occur within the system.
- Responses Resposne from the API via the websocket use the JSON format and follow the layout order:
{
"type": INTEGER value of Response,
"payload": JSON Array of Events
}The API supports the following response types with specific int values:
FETCH_SESSIONS_REPLY=2
FETCH_EVENTS_REPLY=4
ERROR_RESPONSE = 7
-
FETCH_SESSIONS_REPLYreturns all session events retrieved whenFETCH_SESSIONSrequest is sent. -
FETCH_EVENTS_REPLYreturns all session events retrieved whenFETCH_EVENTSrequest is sent. -
ERROR_RESPONSEis returned if any request sent fails to complete or is rejected due to internal system errors.
Below are response samples:
FETCH_SESSIONS:
With Request:
{
"type":1,
}Expected Response if Failed:
{
"type":7,
"payload": {
"request": 1,
"error": "Failed to retreive events due to db connection"
}
}Expected Response if Successfully:
{
"type": 2,
"payload":[
{
"type": 1,
"sensor":"ssh_session",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"SSHConnections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
]
}FETCH_EVENTS:
With Request:
{
"type":3,
}Expected Response if Failed:
{
"type":7,
"payload": {
"request": 1,
"error": "Failed to retreive events due to db connection"
}
}Expected Response if Successfully:
{
"type": 4,
"payload":[
{
"type": 1,
"sensor":"ping",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"connections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
]
}The websocket API also provides specific response which contain updates on sessions and non-session events:
NEW_SESSIONS=5
NEW_EVENTS=6
- `NEW_SESSIONS` indicates new session events from the backend.
- `NEW_EVENTS` indicates new non-session events from the backend.
NEW_SESSIONS:
Expected Response Body
{
"type": 6,
"payload":[
{
"type": 1,
"sensor":"ssh_session",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"SSHConnections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
]
}NEW_EVENTS:
Expected Response Body
{
"type": 5,
"payload":[
{
"type": 1,
"sensor":"ping",
"date":"06-04-2013",
"started":"06-04-2013 01:11:10:32",
"ended":"06-04-2013 12:11:10:32",
"token":"43354-57-76767-6767-676334-4343-44334",
"location":"unknown",
"category":"connections",
"hostAddr":"10.78.54.100:7080",
"localAddr":"43.65.78.2:5000",
"data":"=b534sfsds34343wwe3443;43434-4343",
"details": {"extra_data":[]},
"session_id": "6575-232-4545-232443-55454",
"container_id": "4343434-43-3434-43434343"
},
]
}Contributions are welcome.
Fork Honeytrap upstream source repository to your own personal repository. Copy the URL for marija from your personal github repo (you will need it for the git clone command below).
$ mkdir -p $GOPATH/src/github.com/honeytrap/honeytrap
$ cd $GOPATH/src/github.com/honeytrap/honeytrap
$ git clone <paste saved URL for personal forked honeytrap repo>
$ cd honeytrap/honeytrapHoneytrap community welcomes your contribution. To make the process as seamless as possible, we ask for the following:
-
Go ahead and fork the project and make your changes. We encourage pull requests to discuss code changes.
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
-
If you have additional dependencies for
Honeytrap,Honeytrapmanages its dependencies using govendor- Run
go get foo/bar - Edit your code to import foo/bar
- Run
make pkg-add PKG=foo/barfrom top-level directory
- Run
-
If you have dependencies for
Honeytrapwhich needs to be removed- Edit your code to not import foo/bar
- Run
make pkg-remove PKG=foo/barfrom top-level directory
-
When you're ready to create a pull request, be sure to:
- Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
- Run
make verifiers - Squash your commits into a single commit.
git rebase -i. It's okay to force update your pull request. - Make sure
go test -race ./...andgo buildcompletes.
-
Read Effective Go article from Golang project
Honeytrapproject is fully conformant with Golang style- if you happen to observe offending code, please feel free to send a pull request
Remco Verhoef
Code and documentation copyright 2017 Honeytrap.
Code released under Affero General Public License.