Permalink
Browse files

formatted readme

  • Loading branch information...
1 parent 79c6010 commit e1fb8868c04dd2a9b675f9f9b9d08177e23ff522 @pjlantz committed Aug 12, 2010
Showing with 11 additions and 9 deletions.
  1. +11 −9 README.md
View
@@ -1,6 +1,5 @@
-
About
-------
+================================
Hale is a botnet command & control monitor/spy with a modular design to easily develop new modules that monitor new protocols used by C&C servers. Hale comes with IRC and HTTP monitors developed with Twisted to handle scalability of a large amount of connections. Theses modules have configurable protocol grammar and bot settings but can also be modified to fit your needs. All captured logs and files are saved to a database and in case of IRC, tracked IP numbers too.
@@ -9,7 +8,7 @@ To hide the location of the operator, connections can be made through SOCKSv5 pr
The main idea with Hale is to help botnet hunting and research to collaborate by creating a network of sensors (Hale monitors). To improve this idea a XMPP bot is available to connect to a centralized XMPP server where currently two different grouprooms are used for coordinating between sensors and a room for sharing logs and files. The coordination room makes use of botnet hashes that are made out of the unique keys in the botnet settings, in this way botnets dont have to be monitored simultaneously that have the same hash (identity) and improves utilization. To help 3rd parties to make use of this network, a bot can join the coordination room and ask a sensor to start tracking a botnet if its unknown by sending the configurations for it, also in the share room 3rd party bots can get their hands on logs and files captured by the sensors in realtime. To assist with log history the web API can be used that support GET requests.
Install
---------------
+================================
Hale has the following dependencies:
@@ -31,7 +30,7 @@ Hale has the following dependencies:
Additionally the monitor requires a database backend driver corresponding to the database used by django. When these libraries are installed download the source from here and extract it anywhere.
Setup
-------------
+================================
1) First create a database that will be used by Hale, the database engine can be any of your choice. If you are using an existing database then skip this step.
@@ -52,7 +51,7 @@ Setup
9) Before running the monitor edit **`hale.conf`** in **`hale/src/conf/`** if you wish to use a XMPP server. If not then skip this step. To activate XMPP bot set use setting to True and either edit login info to an existing account and server or start your own XMPP server. An important step when starting up a XMPP server is to increase the max stanza size from the default value to something like 10Mb. Otherwise malware sharing will not be possible. The channel settings in hale.conf are used for the share grouproom used by the bot and the coord setting is used for the grouproom where all coordination between sensors is done.
Usage
-------------
+================================
To start the monitor head to **`hale/src/`** and execute **`python main.py`**. If it fires up with errors then the django **`settings.py`** file is not correctly set or some libraries are missing. When the monitor is running type **`help`** or **`?`** to get the available commands. Type help command to get more info about the specific command. Starting up a monitor bot is done by first editing the **`hale/src/conf/modules.conf`** file, for example using a irc configuration as follow:
@@ -83,9 +82,10 @@ Edit or create a new config by specifying a new uniquely named section (**`[ircC
The web interface provides access to all captured data in the database which is accessible from the index page. There is also a search function which enables the user to search for botnet and file hashes, related IP numbers, botnet IDs, botnet modules used and botnet hosts. If the user got access to edit proxies or modules then this can be done in the admin section, url to this is http://.../admin. The administrator can set user modes and also add consumers for the web API.
Development
-------------------
+================================
-How to add modules, the current module API work as follow:
+HOWTO add modules
+------------------
1) Implement module, for example:
@@ -217,7 +217,8 @@ where the regular expression is as follow:
4) Upload the module to the web ui by setting the module name to for example irc, filename ircModule.py and then add a config example for this module.
-Feeder bot HOWTO:
+Feeder bot HOWTO
+-----------------
When sending a request for a botnet to track the request is made as follow
to the groupchat coordination room
@@ -254,7 +255,8 @@ Malware share is done by sensors sending a message like:
where the content is Base64 encoded and comes directly after the file hash value.
-RESTful Web API:
+RESTful Web API
+----------------
To get access to the api you need a consumer key and secret key, this can be created by the admin and are used with OAuth to authenticate. The following URLs are available to fetch data in JSON format:

0 comments on commit e1fb886

Please sign in to comment.